Zpracování chyb
Na této stránce
Chyby jsou nevyhnutelné
V produkčním prostředí funkce selhávají. Externí API přestávají fungovat, ID neexistují, parametry jsou neplatné a časové limity vyprší. Otázkou není „selže to?“, ale „jak elegantně zvládneme selhání?“. Sledovač plateb, který spadne, protože uživatel napsal T9999 místo T1001, není produkční systém; je to jen demo.
Dobrou zprávou je, že máte k dispozici zdroj, kterému klasické architektury postrádají: model Mistral dokáže pochopit chybové zprávy, které mu pošlete zpět, a podle toho přizpůsobit svou odpověď. Zatímco tradiční backend musí pro každý chybový kód ručně vytvářet zprávu pro uživatelské rozhraní, vy můžete nechat model převést selhání na užitečnou větu pro uživatele. Stačí mu poskytnout potřebné informace.
Nikdy před modelem chybu neskrývej
To je zlaté pravidlo této lekce. Vrať chybu ve zprávě tool přesně tak, jako by šlo o běžný výsledek: jako strukturované JSON. Opakem – zachycení výjimky a vrácení prázdného řetězce nebo null – donutíš model věřit, že funkce uspěla, ale neměla co říct. To vede k těm nejmatoucím odpovědím, jaké si dokážeš představit.
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)}"
})
Stačí dvě pole: strojový kód v error a srozumitelné vysvětlení pro člověka v message. Kód umožní tvému monitorovacímu systému počítat výskyty; vysvětlení pomůže modelu formulovat užitečnou odpověď. Podívej se, co se stane u neexistující transakce.
# 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?"
Tuto větu nikdo nenapsal. Vznikla na základě chybového kódu a dokonce uživateli navrhuje nápravné opatření.
Executor, kterým nic neproklouzne
Ochrana samotné funkce nestačí: vrstva, která dispatchuje tool_calls, má své vlastní režimy selhání, nezávislé na tvé obchodní logice. Model může halucinovat název funkce, který ve tvém slovníku neexistuje. Může vygenerovat malformed JSON argumenty – vzácný, ale reálný případ u komplexních schémat. Může také poskytnout platný JSON, jehož klíče neodpovídají podpisu funkce v Pythonu, což způsobí TypeError během **function_params. Každý z těchto tří případů si zaslouží vlastní chybový kód, protože každý vyžaduje jiný zásah z tvé strany.
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
}
Všimni si, že každá větev, včetně těch chybových, vrací kompletní zprávu tool s jejím tool_call_id. To je zásadní: API odmítne historii, kde na tool_call nepřijde odpověď, a tiché selhání by způsobilo chybu validace až v dalším kole, daleko od skutečné příčiny.
Rozlišuj přechodná a trvalá selhání
Ne všechny chyby jsou stejné. Chybějící transakce bude chybět i při druhém pokusu; opakování jen plýtvá časem. Naopak výpadek sítě nebo dočasné přetížení služby se často vyřeší samo. Pro tuto druhou kategorii nabízí opakování s exponenciálním backoffem (jedna sekunda, pak dvě, pak čtyři) službě čas na zotavení, aniž bys ji zahlcoval požadavky. Po vyčerpání pokusů se vrátíš k běžnému chování: JSON s chybou určený pro model.
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)
})
API Mistralu také může selhat
Vše výše uvedené se týká tvých funkcí. Volání samotného API Mistralu je odlišným bodem selhání, který se řeší samostatně: zde není žádný model, kterému bys problém vysvětlil, protože model je právě ten, který je nedostupný. HTTPValidationError obvykle signalizuje chybu ve struktuře tvých zpráv nebo nástrojů, kterou musíš opravit v kódu; ostatní výjimky souvisejí se sítí nebo službou a řeší se stejnou logikou opakování jako výše.
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
Zjisti, co se skutečně děje
Systém volání funkcí je těžké dodatečně ladit, pokud nevíš, která funkce byla zavolána, s jakými argumenty a co vrátila. Logování není luxus; je to způsob, jak zjistíš, že nejednoznačný popis nutí model plést si dvě funkce, nebo že každý pátý uživatel systematicky spouští transaction_not_found. Loguj volání před provedením a poté výsledek, přičemž rozlišuj úroveň info od úrovně error, aby tvé alerty mohly efektivně filtrovat.
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
Klíčové poznatky
- Vždy vracej chyby modelu ve zprávě
tool– umí je interpretovat - Používej strukturované chybové kódy (
transaction_not_found,invalid_argumentsatd.) - Implementuj opakování s backoffem pro přechodné chyby
- Odděleně řeš chyby ve tvých funkcích a chyby v API Mistralu
- Loguj každé volání a každou chybu pro produkční monitoring