Obvladovanje napak
Na tej strani
Napake so neizogibne
V produkcijskem okolju funkcije odpovedo. Zunanji API-ji se sesujejo, ID-ji ne obstajajo, parametri so neveljavni in časovne omejitve potečejo. Vprašanje ni „ali bo prišlo do napake?”, temveč „kako bomo napako elegantno obvladali?” Sistem za sledenje plačilom, ki se sesuje, ker je uporabnik vnesel T9999 namesto T1001, ni produkcijski sistem; to je le demonstracija.
Dobra novica je, da imaš na voljo vir, ki ga klasične arhitekture nimajo: model Mistral lahko razume sporočila o napakah, ki jih pošlješ nazaj, in temu primerno prilagodi svoj odgovor. Medtem ko mora tradicionalni strežniški del za vsako kodo napake ročno ustvariti sporočilo za uporabniški vmesnik, lahko ti modelu prepustiš, da neuspeh prevede v koristno poved za uporabnika. Podati mu moraš le prave informacije.
Modelu nikoli ne skrij napake
To je zlato pravilo te lekcije. Napako vrni v sporočilu tool natanko tako, kot bi vrnil normalen rezultat: kot strukturiran JSON. Nasprotni refleks – ujemanje izjeme in vračanje praznega niza ali null – modela prepriča, da je funkcija uspela, le da ni imela kaj povedati. To proizvede najbolj zmedene odgovore, kar si jih lahko zamisliš.
def retrieve_payment_status(df, transaction_id: str) -> str:
"""Pridobi status s popolnim obvladovanjem napak."""
try:
if transaction_id not in df["transaction_id"].values:
return json.dumps({
"error": "transaction_not_found",
"message": f"Transakcija {transaction_id} ne obstaja v bazi podatkov."
})
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"Napaka pri pridobivanju podatkov: {str(e)}"
})
Dve polji sta dovolj: strojna koda v error in človeku berljivo pojasnilo v message. Koda omogoča tvojemu sistemu za nadzor štetje pojavitev; pojasnilo pa modelu omogoča oblikovanje koristnega odgovora. Poglej, kaj se zgodi z neobstoječo transakcijo.
# Uporabnik zahteva neobstoječo transakcijo
messages = [{"role": "user", "content": "Status plačila T9999?"}]
# Model pokliče retrieve_payment_status(transaction_id="T9999")
# Tvoja funkcija vrne: {"error": "transaction_not_found", ...}
# Model oblikuje:
# → "Transakcije z ID-jem T9999 nisem našel.
# Lahko preveriš številko in poskusiš znova?"
Tega stavka ni napisal nihče. Izvira iz kode napake in uporabniku celo predlaga korektivno dejanje.
Izvajalec, ki ne spusti ničesar skozi
Zaščita funkcije sama po sebi ni dovolj: plast, ki razpošilja tool_calls, ima svoje načine odpovedi, neodvisne od tvoje poslovne logike. Model lahko halucinira ime funkcije, ki ne obstaja v tvojem slovarju. Lahko proizvede neveljavne argumente JSON – redek, a realen primer pri kompleksnih shemah. Lahko tudi zagotovi veljaven JSON, katerega ključi se ne ujemajo s podpisom Pythona, kar povzroči TypeError med **function_params. Vsak od teh treh primerov zasluži svojo kodo napake, saj vsak zahteva drugačen popravek na tvoji strani.
def execute_tool_call(tool_call, available_functions):
"""Izvede tool_call s popolnim obvladovanjem napak."""
function_name = tool_call.function.name
# Preveri, ali funkcija obstaja
if function_name not in available_functions:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "function_not_found",
"message": f"Funkcija {function_name} ni na voljo."
}),
"tool_call_id": tool_call.id
}
# Razčleni argumente
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"Neveljavni argumenti JSON: {str(e)}"
}),
"tool_call_id": tool_call.id
}
# Izvedi funkcijo
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"Nezdružljivi parametri: {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"Napaka pri izvajanju: {str(e)}"
}),
"tool_call_id": tool_call.id
}
Opazi, da vsaka veja, vključno z vejami za napake, vrne popolno sporočilo tool z njegovim tool_call_id. To je bistveno: API zavrne zgodovino, kjer tool_call ostane brez odgovora, tiha napaka pa bi povzročila napako validacije v naslednjem koraku, daleč od resničnega vzroka.
Razlikuj med prehodnimi in trajnimi napakami
Vse napake niso enake. Manjkajoča transakcija bo manjkala tudi ob drugem poskusu; ponovni poskus le zapravlja čas. Časovni iztek omrežja ali trenutno preobremenjena storitev pa se pogosto sama od sebe popravi. Za to drugo kategorijo ponovni poskus z eksponentnim zamikom (ena sekunda, nato dve, nato štiri) storitvi da čas za obnovitev, ne da bi jo zasul z zahtevami. Ko poskusi izčrpaš, se vrneš na običajno vedenje: JSON z napako, namenjen modelu.
import time
def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
"""Izvede funkcijo z eksponentnim ponovnim poskusom."""
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"Storitev ni na voljo po {max_retries} poskusih.",
"details": str(e)
})
Tudi API Mistral lahko odpove
Vse zgoraj navedeno se nanaša na tvoje funkcije. Klic samega API-ja Mistral je ločena točka odpovedi, ki jo obravnavamo posebej: tukaj ni modela, ki bi razložil težavo, saj je model prav tisti, ki je nedosegljiv. HTTPValidationError običajno signalizira napako v strukturi tvojih sporočil or orodij, ki jo moraš popraviti v kodi; druge izjeme se nanašajo na omrežje ali storitev in jih obravnavamo z enako logiko ponovnega poskusa kot zgoraj.
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
def safe_chat_complete(client, model, messages, tools):
"""Klic API-ja Mistral z obvladovanjem napak."""
try:
return client.chat.complete(
model=model,
messages=messages,
tools=tools
)
except HTTPValidationError as e:
print(f"Napaka validacije: {e}")
return None
except Exception as e:
print(f"Napaka API-ja: {e}")
return None
Poglej, kaj se dejansko dogaja
Sistem za klicanje funkcij je težko razhroščevati naknadno, če ne veš, katera funkcija je bila poklicana, s katerimi argumenti in kaj je vrnila. Beleženje (logging) ni razkošje; tako boš odkril, da dvoumen opis modela spodbudi k zamenjavi dveh funkcij ali da eden od petih uporabnikov sistematično sproži transaction_not_found. Pred izvedbo zabeleži klic, nato pa sodbo, pri čemer razlikuj med ravnjo info in error, da se lahko tvoja opozorila učinkovito filtrirajo.
import logging
logger = logging.getLogger("function_calling")
def execute_and_log(tool_call, available_functions):
"""Izvede in zabeleži rezultat."""
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
logger.info(f"Klic: {function_name}({function_params})")
result = execute_tool_call(tool_call, available_functions)
content = json.loads(result["content"])
if "error" in content:
logger.error(f"Neuspeh {function_name}: {content['error']} - {content['message']}")
else:
logger.info(f"Uspeh {function_name}: {content}")
return result
Ključne ugotovitve
- Napake modelu vedno vrni v sporočilu
tool– zna jih razlagati - Uporabi strukturirane kode napak (
transaction_not_found,invalid_argumentsitd.) - Implementiraj ponovni poskus z zamikom za prehodne napake
- Napake v tvojih funkcijah in napake v API-ju Mistral obravnavaj ločeno
- Za nadzor v produkcijskem okolju zabeleži vsak klic in vsako napako