Virheenkäsittely
Tällä sivulla
Virheet ovat väistämättömiä
Tuotantoympäristössä funktiot epäonnistuvat. Ulkoiset rajapinnat kaatuvat, tunnisteita ei löydy, parametrit ovat virheellisiä ja aikakatkaisut laukeavat. Kysymys ei kuulu “epäonnistuuko se?”, vaan “kuinka käsittelemme epäonnistumisen hallitusti?” Maksuseurantajärjestelmä, joka kaatuu, koska käyttäjä syötti T9999 T1001:n sijaan, ei ole tuotantojärjestelmä; se on vain demo.
Hyvä uutinen on, että sinulla on käytössäsi resurssi, jota perinteiset arkkitehtuurit eivät tarjoa: Mistral-malli pystyy ymmärtämään virheilmoituksia, jotka lähetät sille takaisin, ja mukauttamaan vastauksensa sen mukaisesti. Kun perinteisen backendin on luotava käyttöliittymäviesti jokaiselle virhekoodille, voit antaa mallin kääntää epäonnistumisen hyödylliseksi lauseeksi käyttäjälle. Sinun tarvitsee vain antaa sille tarvittavat tiedot.
Älä koskaan piilota virhettä mallilta
Tämä on tämän oppitunnin kultainen sääntö. Palauta virhe tool-viestissä täsmälleen samalla tavalla kuin normaali tulos: jäsennettynä JSONina. Päinvastainen refleksi – poikkeuksen sieppaaminen ja tyhjän merkkijonon tai null:n palauttaminen – saa mallin luulemaan, että funktio onnistui, mutta sillä ei yksinkertaisesti ollut mitään sanottavaa. Tämä tuottaa mahdollisimman hämmentäviä vastauksia.
def retrieve_payment_status(df, transaction_id: str) -> str:
"""Hakee tilan täydellisellä virheenkäsittelyllä."""
try:
if transaction_id not in df["transaction_id"].values:
return json.dumps({
"error": "transaction_not_found",
"message": f"Transaktiota {transaction_id} ei ole tietokannassa."
})
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"Virhe haettaessa dataa: {str(e)}"
})
Kaksi kenttää riittää: koneellinen koodi kentässä error ja ihmislukemuotoinen selitys kentässä message. Koodi antaa valvontajärjestelmällesi mahdollisuuden laskea esiintymiskertoja; selitys antaa mallille mahdollisuuden muotoilla avulias vastaus. Katso, mitä tapahtuu olemattoman transaktion kohdalla.
# Käyttäjä pyytää olematonta transaktiota
messages = [{"role": "user", "content": "Maksun T9999 tila?"}]
# Malli kutsuu retrieve_payment_status(transaction_id="T9999")
# Funktiosi palauttaa: {"error": "transaction_not_found", ...}
# Malli muotoilee:
# → "En löytänyt transaktiota tunnuksella T9999.
# Voisitko tarkistaa numeron ja yrittää uudelleen?"
Kukaan ei kirjoittanut tuota lausetta. Se syntyy virhekoodista, ja se jopa ehdottaa käyttäjälle korjaavaa toimenpidettä.
Suoritin, joka ei päästä mitään läpi sormien
Funktion suojaaminen ei riitä: tool_calls-kutsuja jakavalla kerroksella on omat vikatilansa, jotka ovat riippumattomia liiketoimintalogiikastasi. Malli saattaa hallusinoida funktion nimen, jota ei ole sanakirjassasi. Se saattaa tuottaa väärin muotoiltuja JSON-argumentteja – harvinainen mutta todellinen tapaus monimutkaisten skeemojen kanssa. Se saattaa myös antaa kelvollista JSONia, jonka avaimet eivät täsmää Python-funktion allekirjoitukseen, aiheuttaen TypeError-virheen kohdassa **function_params. Jokainen näistä kolmesta tapauksesta ansaitsee oman virhekoodinsa, koska kukin vaatii sinulta erilaisen korjauksen.
def execute_tool_call(tool_call, available_functions):
"""Suorittaa tool_callin täydellisellä virheenkäsittelyllä."""
function_name = tool_call.function.name
# Tarkista, onko funktio olemassa
if function_name not in available_functions:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "function_not_found",
"message": f"Funktiota {function_name} ei ole saatavilla."
}),
"tool_call_id": tool_call.id
}
# Jäsennä argumentit
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"Virheelliset JSON-argumentit: {str(e)}"
}),
"tool_call_id": tool_call.id
}
# Suorita funktio
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"Yhteensopimattomat parametrit: {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"Suoritusvirhe: {str(e)}"
}),
"tool_call_id": tool_call.id
}
Huomaa, että jokainen haara, myös epäonnistumishaarat, palauttaa täydellisen tool-viestin sen tool_call_id:n kanssa. Tämä on välttämätöntä: API hylkää historian, jossa tool_call jää vastaamattomaksi, ja hiljainen epäonnistuminen aiheuttaisi validointivirheen seuraavalla kierroksella, kaukana todellisesta syystä.
Erota ohimenevät ja pysyvät virheet
Kaikki virheet eivät ole samanarvoisia. Puuttuva transaktio on edelleen puuttuva toisellakin yrittämällä; uudelleenyritys vain tuhlaa aikaa. Verkon aikakatkaisu tai hetkellisesti ylikuormitettu palvelu sen sijaan korjaantuu usein itsestään. Tälle toiselle kategorialle uudelleenyritys eksponentiaalisella viiveellä (yksi sekunti, sitten kaksi, sitten neljä) antaa palvelulle aikaa toipua ilman, että sitä pommitetaan pyynnöillä. Kun yritykset on uuvutettu, palaat normaaliin toimintaan: mallille tarkoitettuun virhe-JSONiin.
import time
def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
"""Suorittaa funktion eksponentiaalisella uudelleenyrityksellä."""
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"Palvelu ei ole saatavilla {max_retries} yrityksen jälkeen.",
"details": str(e)
})
Myös Mistral API voi epäonnistua
Kaikki edellä mainittu koskee omia funktioitasi. Itse Mistral API -kutsu on erillinen vikapiste, jota käsitellään erikseen: tässä tapauksessa ei ole mallia, joka selittäisi ongelman, koska nimenomaan malli on tavoittamaton. HTTPValidationError viittaa yleensä virheeseen viesti- tai työkalurakenteessasi, joka on korjattava koodissa; muut poikkeukset liittyvät verkkoon tai palveluun ja niitä käsitellään samalla uudelleenyrityslogiikalla kuin edellä.
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
def safe_chat_complete(client, model, messages, tools):
"""Mistral API -kutsu virheenkäsittelyllä."""
try:
return client.chat.complete(
model=model,
messages=messages,
tools=tools
)
except HTTPValidationError as e:
print(f"Validointivirhe: {e}")
return None
except Exception as e:
print(f"API-virhe: {e}")
return None
Näe, mitä todella tapahtuu
Funktiokutsujärjestelmää on vaikea vianetsiä jälkikäteen, jos et tiedä, mitä funktiota kutsuttiin, millä argumenteilla ja mitä se palautti. Lokitus ei ole ylellisyyttä; sen avulla huomaat, että epäselvä kuvaus saa mallin sekoittamaan kaksi funktiota, tai että joka viides käyttäjä laukaisee systemaattisesti transaction_not_found-virheen. Lokita kutsu ennen suoritusta ja sen jälkeen tehty päätös, erottaen info-taso error-tasosta, jotta hälytyksesi voivat suodattaa tehokkaasti.
import logging
logger = logging.getLogger("function_calling")
def execute_and_log(tool_call, available_functions):
"""Suorittaa ja lokittaa tuloksen."""
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
logger.info(f"Kutsu: {function_name}({function_params})")
result = execute_tool_call(tool_call, available_functions)
content = json.loads(result["content"])
if "error" in content:
logger.error(f"Epäonnistuminen {function_name}: {content['error']} - {content['message']}")
else:
logger.info(f"Onnistuminen {function_name}: {content}")
return result
Keskeiset asiat
- Palauta aina virheet mallille
tool-viestissä – se osaa tulkita ne - Käytä jäsennettyjä virhekoodeja (
transaction_not_found,invalid_argumentsjne.) - Toteuta uudelleenyritys viiveellä ohimeneville virheille
- Käsittele virheet omissa funktioissasi ja Mistral API:ssa erikseen
- Lokita jokainen kutsu ja jokainen virhe tuotannon valvontaa varten