Hibakezelés
Ezen az oldalon
A hibák elkerülhetetlenek
Éles környezetben a függvények meghibásodnak. Külső API-k leállnak, az azonosítók nem léteznek, a paraméterek érvénytelenek, és az időtúllépések bekövetkeznek. A kérdés nem az, hogy „meghibásodik-e?“, hanem az, hogy „hogyan kezeljük a hibákat elegánsan?“. Egy fizetéskövető rendszer, amely összeomlik, mert a felhasználó T9999-et írt T1001 helyett, nem éles rendszer, csupán egy demó.
A jó hír az, hogy van egy erőforrásod, amely a klasszikus architektúrákból hiányzik: a Mistral modell képes megérteni a neki visszaküldött hibaüzeneteket, és ennek megfelelően igazítani a válaszát. Míg egy hagyományos backendnek minden hibakódhoz külön felhasználói felületi üzenetet kell generálnia, addig te rábízhatod a modellre, hogy a hibát hasznos mondattá alakítsa a felhasználó számára. Csak annyi a dolgod, hogy megadd neki a szükséges információt.
Soha ne rejtsd el a hibát a modell elől
Ez ennek a leckének az aranyszabálya. A hibát pontosan úgy add vissza a tool üzenetben, ahogy egy normál eredményt tennéd: strukturált JSON formátumban. Az ellenkező reflex – a kivétel elkapása és egy üres string vagy null visszaadása – azt a hamis hitet kelti a modellben, hogy a függvény sikeresen lefutott, csak nincs mit mondania. Ez a lehető legzavaróbb válaszokat eredményezi.
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)}"
})
Két mező elegendő: egy gépi kód az error mezőben, és egy ember által olvasható magyarázat a message mezőben. A kód lehetővé teszi a monitorozó rendszered számára az előfordulások számlálását; a magyarázat pedig segít a modellnek hasznos választ megfogalmazni. Nézd meg, mi történik egy nem létező tranzakció esetén.
# 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?"
Senki sem írta meg ezt a mondatot. A hibakódból származik, és még egy korrekciós lépést is javasol a felhasználónak.
Egy végrehajtó, ami nem enged át semmit
Önmagában nem elég megvédeni egy függvényt: a tool_callsokat kiosztó rétegnek is vannak saját hibalehetőségei, függetlenül az üzleti logikádtól. A modell hallucinálhat egy olyan függvénynevet, amely nem létezik a szótáradban. Előfordulhat, hogy rosszul formázott JSON argumentumokat generál – ez ritka, de komplex sémák esetén valós eset. Az is megtörténhet, hogy érvényes JSON-t ad meg, de a kulcsai nem egyeznek a Python aláírással, ami TypeError-t okoz a **function_params során. E három eset mindegyike saját hibakódot érdemel, mivel mindegyik más-más javítást igényel a te részedről.
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
}
Figyeld meg, hogy minden ág, beleértve a hibaágakat is, egy teljes tool üzenetet ad vissza a saját tool_call_id-jével. Ez létfontosságú: az API elutasít egy olyan előzményt, ahol egy tool_call válasz nélkül marad, és egy csendes hiba validációs hibát okozna a következő körben, messze a valódi októl.
Különböztesd meg az átmeneti és a végleges hibákat
Nem minden hiba egyforma. Egy hiányzó tranzakció második próbálkozásra is hiányozni fog; az újrapróbálkozás csak az időt pocsékolja. Egy hálózati időtúllépés vagy egy pillanatnyilag túlterhelt szolgáltatás azonban gyakran magától megoldódik. Erre a második kategóriára egy exponenciális visszalépéssel (backoff) történő újrapróbálkozás – egy másodperc, majd kettő, majd négy – időt ad a szolgáltatásnak a helyreállásra anélkül, hogy kérésekkel ostromolnád. A kísérletek kimerítése után visszatérsz a szokásos viselkedéshez: egy JSON hibaüzenethez, amely a modell számára készült.
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)
})
A Mistral API is meghibásodhat
A fentiek mind a te függvényeidre vonatkoznak. Maga a Mistral API-hívás egy különálló hibapont, amelyet elkülönítve kell kezelni: itt nincs modell, aki elmagyarázná a problémát, hiszen éppen a modell elérhetetlen. Egy HTTPValidationError általában hibát jelez az üzeneted vagy az eszközeid szerkezetében, amit kódban kell javítanod; más kivételek a hálózattal vagy a szolgáltatással kapcsolatosak, és ugyanazzal az újrapróbálkozási logikával kezelendők, mint fentebb.
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
Lásd, mi történik valójában
Egy függvényhívó rendszert utólag nehéz hibakeresni, ha nem tudod, melyik függvényt hívták meg, milyen argumentumokkal, és mit adott vissza. A naplózás nem luxus; így fedezheted fel, hogy egy kétértelmű leírás miatt a modell összezavar két függvényt, vagy hogy a felhasználók minden ötöde szisztematikusan kivált egy transaction_not_found hibát. Naplózd a hívást a végrehajtás előtt, majd az eredményt, megkülönböztetve az info szintet a error szinttől, hogy az értesítéseid hatékonyan szűrni tudjanak.
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
Főbb megállapítások
- Mindig add vissza a hibákat a modellnek a
toolüzenetben – tudja, hogyan értelmezze őket - Használj strukturált hibakódokat (
transaction_not_found,invalid_argumentsstb.) - Implementálj újrapróbálkozást visszalépéssel (backoff) az átmeneti hibák esetén
- Kezeld külön a saját függvényeidben fellépő hibákat és a Mistral API-ban történő hibákat
- Naplózz minden hívást és minden hibát az éles környezeti monitorozás érdekében