Διαχείριση Σφαλμάτων
Σε αυτήν τη σελίδα
Τα Σφάλματα είναι Αναπόφευκτα
Σε περιβάλλον παραγωγής, οι συναρτήσεις αποτυγχάνουν. Εξωτερικά API πέφτουν, τα IDs δεν υπάρχουν, οι παράμετροι είναι άκυρες και τα χρονικά όρια (timeouts) λήγουν. Το ερώτημα δεν είναι «θα αποτύχει;», αλλά «πώς θα διαχειριστούμε την αποτυχία με κομψό τρόπο;». Ένας ιχνηλάτης πληρωμών που καταρρέει επειδή ένας χρήστης πληκτρολόγησε T9999 αντί για T1001 δεν είναι σύστημα παραγωγής· είναι μια επίδειξη.
Τα καλά νέα είναι ότι διαθέτετε εδώ έναν πόρο που στερούνται οι κλασικές αρχιτεκτονικές: το μοντέλο Mistral μπορεί να κατανοήσει τα μηνύματα σφάλματος που του στέλνετε πίσω και να προσαρμόσει ανάλογα την απάντησή του. Εκεί που ένα παραδοσιακό backend πρέπει να δημιουργήσει ένα μήνυμα UI για κάθε κωδικό σφάλματος, εσείς μπορείτε να αφήσετε το μοντέλο να μεταφράσει την αποτυχία σε μια χρήσιμη πρόταση για τον χρήστη. Αρκεί να του παρέχετε τις πληροφορίες.
Μην Κρύβετε Ποτέ ένα Σφάλμα από το Μοντέλο
Αυτός είναι ο χρυσός κανόνας αυτού του μαθήματος. Επιστρέψτε ένα σφάλμα στο μήνυμα tool ακριβώς όπως θα κάνατε με ένα κανονικό αποτέλεσμα: ως δομημένο JSON. Η αντίθετη αντίδραση—να πιάνετε την εξαίρεση και να επιστρέφετε μια κενή συμβολοσειρά ή null—κάνει το μοντέλο να πιστεύει ότι η συνάρτηση εκτελέστηκε επιτυχώς αλλά απλώς δεν είχε τίποτα να πει. Αυτό παράγει τις πιο συγχυτικές απαντήσεις που μπορείτε να φανταστείτε.
def retrieve_payment_status(df, transaction_id: str) -> str:
"""Retrieves status with full error handling."""
try:
if transaction_id not in df["transaction_id"].values:
return json.dumps({
"error": "transaction_not_found",
"message": f"Transaction {transaction_id} does not exist in the database."
})
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status, "transaction_id": transaction_id})
except Exception as e:
return json.dumps({
"error": "internal_error",
"message": f"Error retrieving data: {str(e)}"
})
Δύο πεδία αρκούν: ένας κωδικός μηχανής στο error και μια επεξήγηση αναγνώσιμη από άνθρωπο στο message. Ο κωδικός επιτρέπει στο σύστημα παρακολούθησής σας να μετράει τις εμφανίσεις· η επεξήγηση επιτρέπει στο μοντέλο να διατυπώσει μια χρήσιμη απάντηση. Δείτε τι συμβαίνει με μια ανύπαρκτη συναλλαγή.
# User requests a non-existent transaction
messages = [{"role": "user", "content": "Status of payment T9999?"}]
# Model calls retrieve_payment_status(transaction_id="T9999")
# Your function returns: {"error": "transaction_not_found", ...}
# Model formulates:
# → "I couldn't find a transaction with ID T9999.
# Could you check the number and try again?"
Κανείς δεν έγραψε αυτή την πρόταση. Πηγάζει από τον κωδικό σφάλματος και μάλιστα προτείνει μια διορθωτική ενέργεια στον χρήστη.
Ένας Εκτελεστής που Δεν Αφήνει Τίποτα να Διαφύγει
Η προστασία μιας συνάρτησης δεν αρκεί: το στρώμα που διανέμει τις tool_calls έχει τους δικούς του τρόπους αποτυχίας, ανεξάρτητα από την επιχειρηματική σας λογική. Το μοντέλο μπορεί να παραισθησιογονεί ένα όνομα συνάρτησης που δεν υπάρχει στο λεξικό σας. Μπορεί να παράγει κακοδιατυπωμένα ορίσματα JSON—μια σπάνια αλλά υπαρκτή περίπτωση με πολύπλοκα σχήματα. Μπορεί επίσης να παρέχει έγκυρο JSON του οποίου τα κλειδιά δεν ταιριάζουν με την υπογραφή της Python, προκαλώντας ένα TypeError κατά τη διάρκεια του **function_params. Καθεμία από αυτές τις τρεις περιπτώσεις αξίζει τον δικό της κωδικό σφάλματος, καθώς η κάθε μία απαιτεί διαφορετική διόρθωση από την πλευρά σας.
def execute_tool_call(tool_call, available_functions):
"""Executes a tool_call with full error handling."""
function_name = tool_call.function.name
# Check if function exists
if function_name not in available_functions:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "function_not_found",
"message": f"Function {function_name} is not available."
}),
"tool_call_id": tool_call.id
}
# Parse arguments
try:
function_params = json.loads(tool_call.function.arguments)
except json.JSONDecodeError as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "invalid_arguments",
"message": f"Invalid JSON arguments: {str(e)}"
}),
"tool_call_id": tool_call.id
}
# Execute function
try:
result = available_functions[function_name](**function_params)
return {
"role": "tool",
"name": function_name,
"content": result,
"tool_call_id": tool_call.id
}
except TypeError as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "invalid_params",
"message": f"Incompatible parameters: {str(e)}"
}),
"tool_call_id": tool_call.id
}
except Exception as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "execution_error",
"message": f"Execution error: {str(e)}"
}),
"tool_call_id": tool_call.id
}
Παρατηρήστε ότι κάθε κλάδος, συμπεριλαμβανομένων των κλάδων αποτυχίας, επιστρέφει ένα πλήρες μήνυμα tool με το αντίστοιχο tool_call_id. Αυτό είναι απαραίτητο: το API απορρίπτει ένα ιστορικό όπου μια tool_call μένει αναπάντητη, και μια σιωπηρή αποτυχία θα προκαλούσε σφάλμα επικύρωσης στον επόμενο γύρο, μακριά από την πραγματική αιτία.
Ξεχωρίστε τα Παροδικά από τα Μόνιμα Σφάλματα
Δεν είναι όλα τα σφάλματα ίδια. Μια missing συναλλαγή θα λείπει και στη δεύτερη προσπάθεια· η επανάληψη απλώς σπαταλά χρόνο. Ένα χρονικό όριο δικτύου ή μια υπηρεσία που είναι στιγμιαία κορεσμένη, ωστόσο, συχνά επιλύεται μόνη της. Για αυτή τη δεύτερη κατηγορία, μια επανάληψη με εκθετική καθυστέρηση (exponential backoff)—ένα δευτερόλεπτο, μετά δύο, μετά τέσσερα—δίνει χρόνο στην υπηρεσία να ανακάμψει χωρίς να την βομβαρδίζετε με αιτήματα. Αφού εξαντληθούν οι προσπάθειες, επιστρέφετε στη συνήθη συμπεριφορά: ένα JSON σφάλματος destined για το μοντέλο.
import time
def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
"""Executes a function with exponential retry."""
for attempt in range(max_retries):
try:
result = func(**params)
return result
except ConnectionError as e:
if attempt < max_retries - 1:
delay = base_delay * (2 ** attempt)
time.sleep(delay)
else:
return json.dumps({
"error": "service_unavailable",
"message": f"Service unavailable after {max_retries} attempts.",
"details": str(e)
})
Το Mistral API Μπορεί Επίσης να Αποτύχει
Όλα τα παραπάνω αφορούν τις δικές σας συναρτήσεις. Η κλήση στο ίδιο το Mistral API αποτελεί ένα ξεχωριστό σημείο αποτυχίας, το οποίο διαχειρίζεται χωριστά: εδώ, δεν υπάρχει μοντέλο για να εξηγήσει το πρόβλημα, καθώς το μοντέλο είναι ακριβώς αυτό που είναι απρόσιτο. Ένα HTTPValidationError συνήθως σηματοδοτεί ένα σφάλμα στη δομή των μηνυμάτων ή των εργαλείων σας, το οποίο πρέπει να διορθώσετε στον κώδικα· άλλες εξαιρέσεις σχετίζονται με το δίκτυο ή την υπηρεσία και διαχειρίζονται με την ίδια λογική επανάληψης όπως παραπάνω.
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
def safe_chat_complete(client, model, messages, tools):
"""Mistral API call with error handling."""
try:
return client.chat.complete(
model=model,
messages=messages,
tools=tools
)
except HTTPValidationError as e:
print(f"Validation error: {e}")
return None
except Exception as e:
print(f"API error: {e}")
return None
Δείτε Τι Συμβαίνει Πραγματικά
Ένα σύστημα κλήσης συναρτήσεων είναι δύσκολο να αποσφαλματωθεί εκ των υστέρων αν δεν γνωρίζετε ποια συνάρτηση κλήθηκε, με ποια ορίσματα και τι επέστρεψε. Η καταγραφή (logging) δεν είναι πολυτέλεια· είναι ο τρόπος με τον οποίο θα ανακαλύψετε ότι μια ασφαλής περιγραφή ωθεί το μοντέλο να μπερδέψει δύο συναρτήσεις, ή ότι ένας στους πέντε χρήστες προκαλεί συστηματικά ένα transaction_not_found. Καταγράψτε την κλήση πριν την εκτέλεση και μετά το αποτέλεσμα, διαχωρίζοντας το επίπεδο info από το επίπεδο error, ώστε οι ειδοποιήσεις σας να μπορούν να φιλτράρουν αποτελεσματικά.
import logging
logger = logging.getLogger("function_calling")
def execute_and_log(tool_call, available_functions):
"""Executes and logs the result."""
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
logger.info(f"Call: {function_name}({function_params})")
result = execute_tool_call(tool_call, available_functions)
content = json.loads(result["content"])
if "error" in content:
logger.error(f"Failure {function_name}: {content['error']} - {content['message']}")
else:
logger.info(f"Success {function_name}: {content}")
return result
Βασικά σημεία
- Επιστρέφετε πάντα τα σφάλματα στο μοντέλο μέσω του μηνύματος
tool· γνωρίζει πώς να τα ερμηνεύσει - Χρησιμοποιείτε δομημένους κωδικούς σφάλματος (
transaction_not_found,invalid_arguments, κ.λπ.) - Υλοποιείτε επανάληψη με καθυστέρηση (backoff) για παροδικά σφάλματα
- Διαχειρίζεστε χωριστά τα σφάλματα στις δικές σας συναρτήσεις και τα σφάλματα στο Mistral API
- Καταγράφετε κάθε κλήση και κάθε σφάλμα για παρακολούθηση σε περιβάλλον παραγωγής