Gestion des erreurs
Šajā lapā
Les erreurs sont inévitables
En production, les fonctions échouent. Les API externes tombent en panne, les identifiants n’existent pas, les paramètres sont invalides et les délais d’attente expirent. La question n’est pas « est-ce que cela va échouer ? », mais « comment gérer l’échec avec élégance ? ». Un suivi de paiement qui plante parce qu’un utilisateur a saisi T9999 au lieu de T1001 n’est pas un système de production ; c’est une démo.
La bonne nouvelle, c’est que tu disposes ici d’une ressource dont les architectures classiques sont dépourvues : le modèle Mistral peut comprendre les messages d’erreur que tu lui renvoies et adapter sa réponse en conséquence. Là où un backend traditionnel doit concevoir un message d’interface pour chaque code d’erreur, tu peux laisser le modèle traduire l’échec en une phrase utile pour l’utilisateur. Il suffit de lui fournir l’information.
Ne cache jamais une erreur au modèle
C’est la règle d’or de cette leçon. Renvoie une erreur dans le message tool exactement comme tu le ferais pour un résultat normal : sous forme de JSON structuré. Le réflexe inverse — attraper l’exception et renvoyer une chaîne vide ou null — fait croire au modèle que la fonction a réussi mais n’avait rien à dire. Cela produit les réponses les plus confuses qui soient.
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)}"
})
Deux champs suffisent : un code machine dans error et une explication lisible par un humain dans message. Le code permet à ton système de surveillance de compter les occurrences ; l’explication permet au modèle de formuler une réponse utile. Vois ce qui se passe avec une transaction inexistante.
# 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?"
Personne n’a écrit cette phrase. Elle découle du code d’erreur et suggère même une action corrective à l’utilisateur.
Un exécuteur qui ne laisse rien passer
Protéger une fonction ne suffit pas : la couche qui distribue les tool_calls possède ses propres modes de défaillance, indépendants de ta logique métier. Le modèle pourrait halluciner un nom de fonction qui n’existe pas dans ton dictionnaire. Il pourrait produire des arguments JSON malformés — un cas rare mais réel avec des schémas complexes. Il pourrait aussi fournir un JSON valide dont les clés ne correspondent pas à la signature Python, provoquant une TypeError lors de **function_params. Chacun de ces trois cas mérite son propre code d’erreur, car chacun nécessite une correction différente de ta part.
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
}
Remarque que chaque branche, y compris les branches d’échec, renvoie un message tool complet avec son tool_call_id. C’est essentiel : l’API rejette un historique où un tool_call reste sans réponse, et un échec silencieux provoquerait une erreur de validation au tour suivant, loin de la cause réelle.
Distingue les échecs transitoires des échecs permanents
Toutes les erreurs ne se valent pas. Une transaction manquante le sera toujours lors d’une seconde tentative ; réessayer ne fait que perdre du temps. Un délai d’attente réseau ou un service momentanément saturé, en revanche, se résout souvent de lui-même. Pour cette seconde catégorie, une nouvelle tentative avec un backoff exponentiel — une seconde, puis deux, puis quatre — laisse au service le temps de récupérer sans le submerger de requêtes. Après épuisement des tentatives, tu reviens au comportement habituel : un JSON d’erreur destiné au modèle.
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)
})
L’API Mistral peut aussi échouer
Tout ce qui précède concerne tes fonctions. L’appel à l’API Mistral elle-même constitue un point de défaillance distinct, géré séparément : ici, il n’y a pas de modèle pour expliquer le problème, puisque le modèle est précisément ce qui est inaccessible. Une HTTPValidationError signale généralement une erreur dans la structure de tes messages ou de tes outils, que tu dois corriger dans le code ; d’autres exceptions concernent le réseau ou le service et sont gérées avec la même logique de nouvelle tentative que ci-dessus.
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
Vois ce qui se passe réellement
Un système d’appel de fonctions est difficile à déboguer après coup si tu ne sais pas quelle fonction a été appelée, avec quels arguments et ce qu’elle a renvoyé. La journalisation n’est pas un luxe ; c’est ainsi que tu découvriras qu’une description ambiguë pousse le modèle à confondre deux fonctions, ou qu’un utilisateur sur cinq déclenche systématiquement un transaction_not_found. Journalise l’appel avant l’exécution, puis le verdict, en distinguant le niveau info du niveau error pour que tes alertes puissent filtrer efficacement.
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
Galvenās atziņas
- Renvoie toujours les erreurs au modèle dans le message
tool— il sait les interpréter - Utilise des codes d’erreur structurés (
transaction_not_found,invalid_arguments, etc.) - Implémente une nouvelle tentative avec backoff pour les erreurs transitoires
- Gère séparément les erreurs dans tes fonctions et les erreurs dans l’API Mistral
- Journalise chaque appel et chaque erreur pour la surveillance en production