Foutafhandeling
Op deze pagina
Fouten zijn onvermijdelijk
In productieomgevingen falen functies. Externe API’s vallen uit, ID’s bestaan niet, parameters zijn ongeldig en time-outs lopen af. De vraag is niet “zal het mislukken?”, maar “hoe gaan we elegant om met storingen?”. Een betalingsvolgsysteem dat crasht omdat een gebruiker T9999 heeft ingetypt in plaats van T1001, is geen productiesysteem; het is een demo.
Het goede nieuws is dat u hier over een hulpbron beschikt die klassieke architecturen missen: het Mistral-model kan foutberichten begrijpen die u terugstuurt en daar zijn reactie op aanpassen. Waar een traditionele backend voor elke foutcode een UI-bericht moet construeren, kunt u het model de storing laten vertalen naar een behulpzame zin voor de gebruiker. U hoeft het alleen de juiste informatie te geven.
Verberg nooit een fout voor het model
Dit is de gouden regel van deze les. Stuur een fout in het tool-bericht exact terug zoals u een normaal resultaat zou doen: als gestructureerde JSON. De tegenovergestelde reflex—de exceptie vangen en een lege string of null teruggeven—laat het model denken dat de functie succesvol was maar simpelweg niets te melden had. Dit levert de meest verwarrende reacties op die denkbaar zijn.
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)}"
})
Twee velden volstaan: een machinecode in error en een voor mensen leesbare uitleg in message. De code stelt uw monitoringssysteem in staat om incidenten te tellen; de uitleg stelt het model in staat een behulpzaam antwoord te formuleren. Kijk wat er gebeurt bij een niet-bestaande transactie.
# 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 heeft die zin geschreven. Hij vloeit voort uit de foutcode en suggereert de gebruiker zelfs een corrigerende actie.
Een executor die niets door de mazen laat glippen
Het beschermen van een functie is niet genoeg: de laag die tool_calls verstuurt, heeft zijn eigen faalmodi, onafhankelijk van uw bedrijfslogica. Het model kan een functienaam hallucineren die niet in uw woordenboek staat. Het kan malformed JSON-argumenten produceren—een zeldzaam maar reëel geval bij complexe schema’s. Het kan ook geldige JSON leveren waarvan de sleutels niet overeenkomen met de Python-signatuur, wat een TypeError veroorzaakt tijdens **function_params. Elk van deze drie gevallen verdient zijn eigen foutcode, omdat elk een andere oplossing aan uw kant vereist.
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
}
Merk op dat elke tak, inclusief de faaltakken, een compleet tool-bericht retourneert met de bijbehorende tool_call_id. Dit is essentieel: de API keurt een geschiedenis af waarin een tool_call onbeantwoord blijft, en een stille storing zou bij de volgende beurt een validatiefout veroorzaken, ver verwijderd van de werkelijke oorzaak.
Onderscheid tijdelijke van permanente storingen
Niet alle fouten zijn gelijk. Een ontbrekende transactie zal bij een tweede poging nog steeds ontbreken; opnieuw proberen is dan tijdverspilling. Een netwerktime-out of een tijdelijk overbelaste service lost zich daarentegen vaak vanzelf op. Voor deze tweede categorie biedt een nieuwe poging met exponentiële backoff—één seconde, dan twee, dan vier—de service de tijd om te herstellen zonder deze te bestoken met verzoeken. Na uitputting van de pogingen valt u terug op het gebruikelijke gedrag: een fout-JSON bestemd voor het model.
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)
})
De Mistral API kan ook falen
Al het bovenstaande betreft uw functies. De aanroep naar de Mistral API zelf is een apart faalpunt, dat apart wordt afgehandeld: hier is er geen model om het probleem aan uit te leggen, aangezien het model precies datgene is dat onbereikbaar is. Een HTTPValidationError wijst meestal op een fout in uw bericht- of tools-structuur, die u in de code moet oplossen; andere uitzonderingen hebben te maken met het netwerk of de service en worden afgehandeld met dezelfde retry-logica als hierboven.
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
Zie wat er werkelijk gebeurt
Een function calling-systeem is achteraf moeilijk te debuggen als u niet weet welke functie is aangeroepen, met welke argumenten en wat het resultaat was. Loggen is geen luxe; het is de manier waarop u ontdekt dat een ambiguë beschrijving het model ertoe aanzet twee functies te verwarren, of dat één op de vijf gebruikers systematisch een transaction_not_found activeert. Log de aanroep vóór uitvoering, en vervolgens de uitkomst, waarbij u niveau info onderscheidt van niveau error, zodat uw alerts effectief kunnen filteren.
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
Belangrijkste punten
- Stuur fouten altijd terug naar het model in het
tool-bericht—het weet hoe ze te interpreteren - Gebruik gestructureerde foutcodes (
transaction_not_found,invalid_arguments, enz.) - Implementeer retry met backoff voor tijdelijke storingen
- Handel fouten in uw functies en fouten in de Mistral API apart af
- Log elke aanroep en elke fout voor monitoring in productie