Håndtering af fejl
På denne side
Fejl er uundgåelige
I produktion fejler funktioner. Eksterne API’er går ned, ID’er findes ikke, parametre er ugyldige, og timeouts udløber. Spørgsmålet er ikke “vil det fejle?”, men “hvordan håndterer vi fejlen elegant?”. En betalingstracker, der crascher, fordi en bruger har tastet T9999 i stedet for T1001, er ikke et produktionssystem; det er en demo.
De gode nyheder er, at du har en ressource her, som klassiske arkitekturer mangler: Mistral-modellen kan forstå fejlmeddelelser, du sender tilbage, og tilpasse sit svar derefter. Hvor en traditionel backend skal udforme en UI-meddelelse for hver fejlkode, kan du lade modellen oversætte fejlen til en hjælpsom sætning til brugeren. Du skal bare give den informationen.
Skjul aldrig en fejl for modellen
Dette er guldreglen i denne lektion. Returner en fejl i tool-meddelelsen præcis som du ville gøre med et normalt resultat: som struktureret JSON. Den modsatte refleks – at fange undtagelsen og returnere en tom streng eller null – får modellen til at tro, at funktionen lykkedes, men blot ikke havde noget at sige. Det producerer de mest forvirrende svar overhovedet.
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)}"
})
To felter er nok: en maskinkode i error og en menneskelæsbar forklaring i message. Koden lader dit overvågningssystem tælle forekomster; forklaringen lader modellen formulere et hjælpsomt svar. Se hvad der sker med en ikke-eksisterende transaktion.
# 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?"
Ingen har skrevet den sætning. Den stammer fra fejlkoden, og den foreslår endda en korrigerende handling til brugeren.
En eksekvering, der ikke lader noget slippe igennem
Det er ikke nok at beskytte en funktion: laget, der dispatcher tool_calls, har sine egne fejltilstande, uafhængigt af din forretningslogik. Modellen kan hallucinere et funktionsnavn, der ikke findes i dit dictionary. Den kan producere forkert formaterede JSON-argumenter – et sjældent, men reelt tilfælde med komplekse skemaer. Den kan også levere gyldig JSON, hvis nøgler ikke matcher Python-signaturen, hvilket forårsager en TypeError under **function_params. Hver af disse tre tilfælde fortjener sin egen fejlkode, fordi hver kræver en anden løsning fra din side.
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
}
Bemærk, at hver gren, inklusive fejlgrene, returnerer en komplet tool-meddelelse med sin tool_call_id. Dette er afgørende: API’et afviser en historik, hvor et tool_call forbliver ubesvaret, og en stille fejl ville forårsage en valideringsfejl ved næste tur, langt væk fra den egentlige årsag.
Skel mellem midlertidige og permanente fejl
Ikke alle fejl er ens. En manglende transaktion vil stadig mangle ved andet forsøg; at prøve igen spilder blot tid. En netværks-timeout eller en tjeneste, der øjeblikkeligt er overbelastet, løser sig dog ofte af sig selv. Til denne anden kategori giver et genforsøg med eksponentiel backoff – ét sekund, så to, så fire – tjenesten tid til at komme sig uden at hamre den med forespørgsler. Når forsøgene er udtømte, falder du tilbage til den sædvanlige adfærd: en fejl-JSON bestemt til modellen.
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’et kan også fejle
Alt ovenstående vedrører dine funktioner. Selve kaldet til Mistral API’et er et særskilt fejlpunkt, der håndteres separat: her er der ingen model at forklare problemet til, da modellen netop er den, der er utilgængelig. En HTTPValidationError signalerer normalt en fejl i din meddelelses- eller værktøjsstruktur, som du skal rette i koden; andre undtagelser relaterer sig til netværket eller tjenesten og håndteres med samme genforsøgslogik som ovenfor.
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
Se hvad der faktisk sker
Et funktionkaldssystem er svært at fejlfinde i eftertid, hvis du ikke ved, hvilken funktion der blev kaldt, med hvilke argumenter, og hvad den returnerede. Logning er ikke en luksus; det er sådan, du opdager, at en tvetydig beskrivelse får modellen til at forveksle to funktioner, eller at en ud af fem brugere systematisk udløser en transaction_not_found. Log kaldet før eksekvering, og derefter resultatet, og skel mellem info-niveau og error-niveau, så dine alarmer kan filtrere effektivt.
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
Vigtige pointer
- Returner altid fejl til modellen i
tool-meddelelsen – den ved, hvordan den skal fortolke dem - Brug strukturerede fejlkoder (
transaction_not_found,invalid_argumentsosv.) - Implementer genforsøg med backoff for midlertidige fejl
- Håndter fejl i dine funktioner og fejl i Mistral API’et separat
- Log hvert kald og hver fejl til produktionsovervågning