Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Hibakezelés

10. lecke 14 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. A hibák elkerülhetetlenek
  2. Soha ne rejtsd el a hibát a modell elől
  3. Egy végrehajtó, ami nem enged át semmit
  4. Különböztesd meg az átmeneti és a végleges hibákat
  5. A Mistral API is meghibásodhat
  6. Lásd, mi történik valójában
  7. Főbb megállapítások

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_arguments stb.)
  • 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