Spracovanie chýb
Na tejto strane
Chyby sú nevyhnutné
V produkčnom prostredí funkcie zlyhávajú. Externé API vypadnú, ID neexistujú, parametre sú neplatné a časové limity vypršia. Otázka neznie „zlyhá to?“, ale „ako zvládneme zlyhanie elegantne?“. Sledovač platieb, ktorý spadne, pretože používateľ napísal T9999 namiesto T1001, nie je produkčný systém; je to len demo.
Dobrou správou je, že máš k dispozícii zdroj, ktorý klasické architektúry nemajú: model Mistral dokáže pochopiť chybové hlášky, ktoré mu pošleš späť, a podľa toho prispôsobiť svoju odpoveď. Kým tradičný backend musí pre každý chybový kód vytvoriť správu do UI, ty môžeš nechať model preložiť zlyhanie do užitočnej vety pre používateľa. Stačí mu poskytnúť informácie.
Nikdy neskrývaj chybu pred modelom
Toto je zlaté pravidlo tejto lekcie. Vráť chybu v správe tool presne tak, ako by si vrátil bežný výsledok: ako štruktúrované JSON. Opakom – zachytenie výnimky a vrátenie prázdneho reťazca alebo null – by model presvedčil, že funkcia uspela, ale nemala čo povedať. To vedie k tým najmatúcim odpovediam, aké si vieš predstaviť.
def retrieve_payment_status(df, transaction_id: str) -> str:
"""Načíta stav s kompletným ošetrením chýb."""
try:
if transaction_id not in df["transaction_id"].values:
return json.dumps({
"error": "transaction_not_found",
"message": f"Transakcia {transaction_id} v databáze neexistuje."
})
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"Chyba pri načítavaní dát: {str(e)}"
})
Stačia dve polia: strojový kód v error a čitateľné vysvetlenie v message. Kód umožní tvojmu monitorovaciemu systému počítať výskyty; vysvetlenie umožní modelu formulovať užitočnú odpoveď. Pozri sa, čo sa stane pri neexistujúcej transakcii.
# Používateľ žiada neexistujúcu transakciu
messages = [{"role": "user", "content": "Stav platby T9999?"}]
# Model zavolá retrieve_payment_status(transaction_id="T9999")
# Tvoja funkcia vráti: {"error": "transaction_not_found", ...}
# Model sformuluje:
# → "Nenašiel som transakciu s ID T9999.
# Mohol by si skontrolovať číslo a skúsiť to znova?"
Túto vetu nikto nenapísal. Vychádza z chybového kódu a dokonca používateľovi navrhuje nápravné opatrenie.
Vykonávač, ktorý neprepustí nič
Ochrana funkcie nestačí: vrstva, ktorá distribuuje tool_calls, má svoje vlastné režimy zlyhania, nezávislé od tvojej obchodnej logiky. Model môže halucinovať názov funkcie, ktorá nie je v tvojom slovníku. Môže vyprodukovať chybné JSON argumenty – zriedkavý, no reálny prípad pri komplexných schémach. Môže tiež poskytnúť platné JSON, ktorého kľúče nezodpovedajú podpisu funkcie v Pythone, čo spôsobí TypeError počas **function_params. Každý z týchto troch prípadov si zasluhuje vlastný chybový kód, pretože každý si vyžaduje inú opravu na tvojej strane.
def execute_tool_call(tool_call, available_functions):
"""Vykoná tool_call s kompletným ošetrením chýb."""
function_name = tool_call.function.name
# Skontroluj, či funkcia existuje
if function_name not in available_functions:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "function_not_found",
"message": f"Funkcia {function_name} nie je dostupná."
}),
"tool_call_id": tool_call.id
}
# Spracuj argumenty
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"Neplatné JSON argumenty: {str(e)}"
}),
"tool_call_id": tool_call.id
}
# Vykonaj funkciu
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"Nekompatibilné parametre: {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"Chyba vykonania: {str(e)}"
}),
"tool_call_id": tool_call.id
}
Všimni si, že každá vetva, vrátane tých chybových, vracia kompletnú správu tool s jej tool_call_id. To je nevyhnutné: API odmietne históriu, kde zostane tool_call bez odpovede, a tiché zlyhanie by spôsobilo chybu validácie v ďalšom kole, ďaleko od skutočnej príčiny.
Rozlišuj prechodné a trvalé zlyhania
Nie všetky chyby sú rovnaké. Chýbajúca transakcia bude chýbať aj pri druhom pokuse; opakovanie len plytvá časom. Časový limit siete alebo dočasne preťažená služba sa však často vyriešia samy. Pre túto druhú kategóriu opakovanie s exponenciálnym oneskorením (jedna sekunda, potom dve, potom štyri) dá službe čas na zotavenie bez toho, aby si ju zahltil požiadavkami. Po vyčerpaní pokusov sa vrátiš k bežnému správaniu: chybové JSON určené pre model.
import time
def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
"""Vykoná funkciu s exponenciálnym opakovaním."""
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"Služba nedostupná po {max_retries} pokusoch.",
"details": str(e)
})
API Mistral môže tiež zlyhať
Všetko vyššie uvedené sa týka tvojich funkcií. Volanie samotného API Mistral je odlišným bodom zlyhania, ktorý sa rieši samostatne: tu niet modelu, ktorý by vysvetlil problém, keďže model je práve ten nedostupný. HTTPValidationError zvyčajne signalizuje chybu v štruktúre tvojej správy alebo nástrojov, ktorú musíš opraviť v kóde; iné výnimky súvisia so sieťou alebo službou a riešia sa rovnakou logikou opakovania ako vyššie.
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
def safe_chat_complete(client, model, messages, tools):
"""Volanie API Mistral s ošetrením chýb."""
try:
return client.chat.complete(
model=model,
messages=messages,
tools=tools
)
except HTTPValidationError as e:
print(f"Chyba validácie: {e}")
return None
except Exception as e:
print(f"Chyba API: {e}")
return None
Zisti, čo sa skutočne deje
Systém volania funkcií sa ťažno debuguje spätne, ak nevieš, ktorá funkcia bola zavolaná, s akými argumentmi a čo vrátila. Logovanie nie je luxus; je to spôsob, ako zistíš, že nejednoznačný popis núti model pliesť si dve funkcie, alebo že každý piaty používateľ systematicky spúšťa transaction_not_found. Loguj volanie pred vykonaním a potom výsledok, pričom rozlišuj úroveň info od úrovne error, aby sa tvoje alerty dali efektívne filtrovať.
import logging
logger = logging.getLogger("function_calling")
def execute_and_log(tool_call, available_functions):
"""Vykoná a zaloguje výsledok."""
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
logger.info(f"Volanie: {function_name}({function_params})")
result = execute_tool_call(tool_call, available_functions)
content = json.loads(result["content"])
if "error" in content:
logger.error(f"Zlyhanie {function_name}: {content['error']} - {content['message']}")
else:
logger.info(f"Úspech {function_name}: {content}")
return result
Kľúčové poznatky
- Vždy vráť chyby modelu v správe
tool– vie ich interpretovať - Používaj štruktúrované chybové kódy (
transaction_not_found,invalid_argumentsatď.) - Implementuj opakovanie s oneskorením pre prechodné chyby
- Ošetruj chyby v tvojich funkciách a chyby v API Mistral oddelene
- Loguj každé volanie a každú chybu pre produkčný monitoring