Gestionarea erorilor
Pe această pagină
Erorile sunt inevitabile
În producție, funcțiile eșuează. API-urile externe cad, ID-urile nu există, parametrii sunt invalizi, iar timeout-urile expiră. Întrebarea nu este „se va produce o eroare?“, ci „cum gestionăm eșecul cu eleganță?“. Un tracker de plăți care se blochează pentru că un utilizator a tastat T9999 în loc de T1001 nu este un sistem de producție; este doar o demonstrație.
Vestea bună este că dispuneți de o resursă pe care arhitecturile clasice nu o au: modelul Mistral poate înțelege mesajele de eroare pe care i le trimiteți și își poate adapta răspunsul în consecință. În timp ce un backend tradițional trebuie să genereze un mesaj de interfață pentru fiecare cod de eroare, dumneavoastră puteți lăsa modelul să transforme eșecul într-o propoziție utilă pentru utilizator. Trebuie doar să îi furnizați informațiile necesare.
Nu ascundeți niciodată o eroare de model
Aceasta este regula de aur a acestei lecții. Returnați o eroare în mesajul tool exact așa cum ați returna un rezultat normal: sub formă de JSON structurat. Reflexul opus—capturarea excepției și returnarea unui șir gol sau a valorii null—face ca modelul să creadă că funcția a reușit, dar pur și simplu nu a avut nimic de spus. Acest lucru generează cele mai confuze răspunsuri posibile.
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)}"
})
Două câmpuri sunt suficiente: un cod mașină în error și o explicație lizibilă pentru om în message. Codul permite sistemului de monitorizare să numere aparițiile; explicația permite modelului să formuleze un răspuns util. Iată ce se întâmplă în cazul unei tranzacții inexistente.
# 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?"
Nimeni nu a scris acea propoziție. Ea derivă din codul de eroare și sugerează chiar o acțiune corectivă utilizatorului.
Un executor care nu lasă nimic să scape
Protejarea unei funcții nu este suficientă: stratul care distribuie tool_calls are propriile sale moduri de eșec, independente de logica de afaceri. Modelul poate halucina un nume de funcție care nu există în dicționarul dumneavoastră. Poate produce argumente JSON malformate—un caz rar, dar real, în cazul schemelor complexe. De asemenea, poate furniza un JSON valid ale cărui chei nu corespund semnăturii Python, provocând un TypeError în timpul execuției **function_params. Fiecare dintre aceste trei cazuri merită propriul cod de eroare, deoarece fiecare necesită o remediere diferită din partea dumneavoastră.
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
}
Observați că fiecare ramură, inclusiv cele de eșec, returnează un mesaj tool complet cu tool_call_id său. Acest lucru este esențial: API-ul respinge un istoric în care un tool_call rămâne fără răspuns, iar un eșec silențios ar provoca o eroare de validare la următoarea iterație, departe de cauza reală.
Distingeți erorile tranzitorii de cele permanente
Nu toate erorile sunt egale. O tranzacție lipsă va fi tot lipsă și la a doua încercare; reîncercarea doar pierde timp. Un timeout de rețea sau un serviciu momentan saturat, însă, se rezolvă adesea de la sine. Pentru această a doua categorie, o reîncercare cu backoff exponențial—o secundă, apoi două, apoi patru—oferă serviciului timp să își revină fără a fi bombardat cu cereri. După epuizarea încercărilor, reveniți la comportamentul obișnuit: un JSON de eroare destinat modelului.
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)
})
Și API-ul Mistral poate eșua
Tot ce am discutat până acum privește funcțiile dumneavoastră. Apelul către API-ul Mistral în sine este un punct de eșec distinct, gestionat separat: aici, nu există un model căruia să îi explicați problema, deoarece modelul este chiar cel inaccesibil. Un HTTPValidationError semnalează de obicei o eroare în structura mesajelor sau a instrumentelor, pe care trebuie să o remediați în cod; alte excepții țin de rețea sau de serviciu și sunt gestionate cu aceeași logică de reîncercare ca mai sus.
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
Vedeți ce se întâmplă cu adevărat
Un sistem de apelare a funcțiilor este greu de depanat post-factum dacă nu știți ce funcție a fost apelată, cu ce argumente și ce a returnat. Logarea nu este un lux; este modul în care veți descoperi că o descriere ambiguă împinge modelul să confunde două funcții sau că unul din cinci utilizatori declanșează sistematic un transaction_not_found. Logați apelul înainte de execuție, apoi verdictul, distingând nivelul info de nivelul error, astfel încât alertele dumneavoastră să poată filtra eficient.
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
Puncte cheie
- Returnați întotdeauna erorile către model în mesajul
tool—acesta știe cum să le interpreteze - Utilizați coduri de eroare structurate (
transaction_not_found,invalid_argumentsetc.) - Implementați reîncercarea cu backoff pentru erorile tranzitorii
- Gestionați separat erorile din funcțiile dumneavoastră și erorile din API-ul Mistral
- Logați fiecare apel și fiecare eroare pentru monitorizarea în producție