Fehlerbehandlung
Auf dieser Seite
Fehler sind unvermeidbar
In der Produktion versagen Funktionen. Externe APIs gehen aus, IDs existieren nicht, Parameter sind ungültig und Timeouts laufen ab. Die Frage lautet nicht „wird es versagen?“, sondern „wie behandeln wir das Versagen angemessen?“. Ein Zahlungstracker, der abstürzt, weil ein Nutzer T9999 statt T1001 eingegeben hat, ist kein Produktionssystem; es ist eine Demo.
Die gute Nachricht ist, dass Sie hier über eine Ressource verfügen, die klassische Architekturen nicht besitzen: Das Mistral-Modell kann Fehlermeldungen, die Sie zurücksenden, verstehen und seine Antwort entsprechend anpassen. Wo ein traditioneller Backend-Server für jeden Fehlercode eine Benutzeroberflächen-Nachricht formulieren muss, können Sie das Modell beauftragen, den Fehler in einen hilfreichen Satz für den Nutzer zu übersetzen. Sie müssen ihm lediglich die Informationen geben.
Verstecken Sie einen Fehler niemals vor dem Modell
Dies ist die goldene Regel dieser Lektion. Geben Sie einen Fehler in der tool-Nachricht genau so zurück wie ein normales Ergebnis: als strukturiertes JSON. Der gegenteilige Reflex, die Ausnahme abzufangen und eine leere Zeichenfolge oder null zurückzugeben, lässt das Modell glauben, die Funktion sei erfolgreich gewesen, habe aber nichts zu sagen. Dies erzeugt die verwirrendsten möglichen Antworten.
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)}"
})
Zwei Felder reichen aus: ein maschinenlesbarer Code in error und eine für Menschen lesbare Erklärung in message. Der Code ermöglicht es Ihrem Überwachungssystem, Vorkommnisse zu zählen; die Erklärung ermöglicht es dem Modell, eine hilfreiche Antwort zu formulieren. Sehen Sie, was bei einer nicht existierenden Transaktion passiert.
# 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?"
Niemand hat diesen Satz geschrieben. Er leitet sich aus dem Fehlercode ab und schlägt dem Nutzer sogar eine Korrekturmaßnahme vor.
Ein Executor, der nichts durchrutschen lässt
Der Schutz einer Funktion reicht nicht aus: Die Schicht, die tool_calls dispatcht, verfügt über eigene Fehlermodi, die unabhängig von Ihrer Geschäftslogik sind. Das Modell könnte einen Funktionsnamen halluzinieren, der nicht in Ihrem Wörterbuch existiert. Es könnte fehlerhaftes JSON-Argumente produzieren – ein seltener, aber realer Fall bei komplexen Schemata. Es könnte auch gültiges JSON bereitstellen, dessen Schlüssel nicht der Python-Signatur entsprechen, was einen TypeError während **function_params verursacht. Jeder dieser drei Fälle verdient einen eigenen Fehlercode, da jeder eine andere Korrektur auf Ihrer Seite erfordert.
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
}
Beachten Sie, dass jeder Zweig, einschließlich der Fehlerzweige, eine vollständige tool-Nachricht mit ihrem tool_call_id zurückgibt. Dies ist essenziell: Die API lehnt eine Historie ab, in der ein tool_call unbeantwortet bleibt, und ein stilles Versagen würde einen Validierungsfehler im nächsten Turn verursachen, weit entfernt von der eigentlichen Ursache.
Unterscheiden Sie zwischen vorübergehenden und dauerhaften Fehlern
Nicht alle Fehler sind gleich. Eine fehlende Transaktion wird beim zweiten Versuch immer noch fehlen; ein erneuter Versuch verschwendet lediglich Zeit. Ein Netzwerk-Timeout oder ein vorübergehend überlasteter Dienst lösen sich jedoch oft von selbst auf. Für diese zweite Kategorie bietet ein Retry mit exponentiellem Backoff – eine Sekunde, dann zwei, dann vier – dem Dienst Zeit zur Erholung, ohne ihn mit Anfragen zu überlasten. Nach Erschöpfung der Versuche greifen Sie auf das übliche Verhalten zurück: ein Fehler-JSON, das dem Modell bestimmt ist.
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)
})
Die Mistral-API kann ebenfalls versagen
Alles oben bezieht sich auf Ihre Funktionen. Der Aufruf der Mistral-API selbst ist ein separates Fehlerpunkt, der separat behandelt wird: Hier gibt es kein Modell, das das Problem erklären kann, da das Modell genau das ist, das unerreichbar ist. Eine HTTPValidationError signalisiert in der Regel einen Fehler in Ihrer Nachrichten- oder Werkzeugstruktur, den Sie im Code beheben müssen; andere Ausnahmen betreffen das Netzwerk oder den Dienst und werden mit der gleichen Retry-Logik wie oben behandelt.
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
Sehen Sie, was tatsächlich passiert
Ein Funktion-Aufruf-System ist nachträglich schwer zu debuggen, wenn Sie nicht wissen, welche Funktion mit welchen Argumenten aufgerufen wurde und was sie zurückgegeben hat. Protokollierung ist kein Luxus; sie ist der Weg, auf dem Sie entdecken, dass eine mehrdeutige Beschreibung das Modell dazu veranlasst, zwei Funktionen zu verwechseln, oder dass systematisch bei fünf von zehn Nutzern ein transaction_not_found ausgelöst wird. Protokollieren Sie den Aufruf vor der Ausführung, dann das Urteil, und unterscheiden Sie zwischen info- und error-Ebene, damit Ihre Warnungen effektiv filtern können.
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
Kernaussagen
- Geben Sie Fehler immer im
tool-Nachricht an das Modell zurück – es weiß, wie es sie interpretiert - Verwenden Sie strukturierte Fehlercodes (
transaction_not_found,invalid_argumentsusw.) - Implementieren Sie Retry mit Backoff für vorübergehende Fehler
- Behandeln Sie Fehler in Ihren Funktionen und Fehler in der Mistral-API separat
- Protokollieren Sie jeden Aufruf und jeden Fehler für die Produktionsüberwachung