Rukovanje greškama
Na ovoj stranici
Greške su neizbježne
U produkcijskom okruženju funkcije padaju. Vanjski API-ji se ruše, ID-jevi ne postoje, parametri su neispravni, a vremenska ograničenja istječu. Pitanje nije „hoće li doći do kvara?“, već „kako ćemo se elegantno nositi s neuspjehom?“. Sustav za praćenje plaćanja koji se ruši jer je korisnik upisao T9999 umjesto T1001 nije produkcijski sustav; to je samo demo.
Dobra vijest je da ovdje imaš resurs kojemu klasične arhitekture nemaju: Mistral model može razumjeti poruke o greškama koje mu pošalješ i sukladno tome prilagoditi svoj odgovor. Dok tradicionalni backend mora ručno kreirati poruku korisničkog sučelja za svaki kod greške, ti možeš prepustiti modelu da neuspjeh prevede u korisnu rečenicu za korisnika. Samo mu moraš dostaviti informacije.
Nikada ne skrivaj grešku od modela
Ovo je zlatno pravilo ove lekcije. Vrati grešku u poruci tool točno onako kako bi vratio normalan rezultat: kao strukturirani JSON. Suprotan refleks—hvatanje iznimke i vraćanje praznog niza ili null—navodi model na uvjerenje da je funkcija uspjela, ali jednostavno nije imala što reći. To proizvodi najzbunjujuće moguće odgovore.
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)}"
})
Dva polja su dovoljna: strojni kod u error i objašnjenje čitljivo ljudima u message. Kod omogućuje tvom sustavu za nadzor brojanje pojavljivanja; objašnjenje omogućuje modelu formuliranje korisnog odgovora. Pogledaj što se događa s nepostojećom transakcijom.
# 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?"
Nitko nije napisao tu rečenicu. Proizašla je iz koda greške, pa čak sugerira korisniku korektivnu radnju.
Izvršitelj koji ne propušta ništa
Zaštita funkcije nije dovoljna: sloj koji raspoređuje tool_calls ima vlastite načine kvarova, neovisne o tvojoj poslovnoj logici. Model može halucinirati ime funkcije koje ne postoji u tvom rječniku. Može proizvesti neispravne JSON argumente—rijetko, ali stvarno kod složenih shema. Također može dati valjani JSON čiji ključevi ne odgovaraju Python potpisu, uzrokujući TypeError tijekom **function_params. Svaki od ova tri slučaja zaslužuje vlastiti kod greške jer svaki zahtijeva drugačiji popravak s tvoje strane.
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
}
Primijeti da svaka grana, uključujući one za neuspjeh, vraća potpunu poruku tool s njezinim tool_call_id. To je bitno: API odbija povijest u kojoj tool_call ostane bez odgovora, a tihi neuspjeh uzrokovao bi grešku validacije u sljedećem koraku, daleko od stvarnog uzroka.
Razlikuj prolazne od trajnih neuspjeha
Nisu sve greške jednake. Nedostajuća transakcija ostat će nedostajuća i pri drugom pokušaju; ponovni pokušaj samo troši vrijeme. Mrežno vremensko ograničenje ili trenutno zasićena usluga, međutim, često se sami riješe. Za ovu drugu kategoriju, ponovni pokušaj s eksponencijalnim kašnjenjem—jedna sekunda, zatim dvije, pa četiri—daje usluzi vremena za oporavak bez preopterećivanja zahtjevima. Nakon iscrpljivanja pokušaja, vraćaš se uobičajenom ponašanju: JSON greške namijenjen modelu.
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 također može otkazati
Sve gore navedeno odnosi se na tvoje funkcije. Poziv samom Mistral API-ju zasebna je točka kvara koja se rješava odvojeno: ovdje nema modela kojem bi se objasnio problem, budući da je model upravo ono što je nedostupno. HTTPValidationError obično signalizira grešku u strukturi tvoje poruke ili alata, koju moraš popraviti u kodu; druge iznimke odnose se na mrežu ili uslugu i rješavaju se istom logikom ponovnog pokušaja kao i gore.
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
Vidi što se zapravo događa
Sustav pozivanja funkcija teško je otkloniti naknadno ako ne znaš koja je funkcija pozvana, s kojim argumentima i što je vratila. Vođenje zapisnika (logging) nije luksuz; to je način na koji ćeš otkriti da dvosmislen opis navodi model na brkanje dviju funkcija ili da jedan od pet korisnika sustavno okida transaction_not_found. Zabilježi poziv prije izvršenja, zatim presudu, razlikujući razinu info od razine error kako bi tvoja upozorenja mogla učinkovito filtrirati.
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
Ključne točke
- Uvijek vrati greške modelu u poruci
tool—on zna kako ih protumačiti - Koristi strukturirane kodove grešaka (
transaction_not_found,invalid_argumentsitd.) - Implementiraj ponovni pokušaj s kašnjenjem za prolazne greške
- Rukuj greškama u svojim funkcijama i greškama u Mistral API-ju odvojeno
- Bilježi svaki poziv i svaku grešku radi nadzora u produkciji