Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Foutafhandeling

Les 10 van 14 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Fouten zijn onvermijdelijk
  2. Verberg nooit een fout voor het model
  3. Een executor die niets door de mazen laat glippen
  4. Onderscheid tijdelijke van permanente storingen
  5. De Mistral API kan ook falen
  6. Zie wat er werkelijk gebeurt
  7. Belangrijkste punten

Fouten zijn onvermijdelijk

In productieomgevingen falen functies. Externe API’s vallen uit, ID’s bestaan niet, parameters zijn ongeldig en time-outs lopen af. De vraag is niet “zal het mislukken?”, maar “hoe gaan we elegant om met storingen?”. Een betalingsvolgsysteem dat crasht omdat een gebruiker T9999 heeft ingetypt in plaats van T1001, is geen productiesysteem; het is een demo.

Het goede nieuws is dat u hier over een hulpbron beschikt die klassieke architecturen missen: het Mistral-model kan foutberichten begrijpen die u terugstuurt en daar zijn reactie op aanpassen. Waar een traditionele backend voor elke foutcode een UI-bericht moet construeren, kunt u het model de storing laten vertalen naar een behulpzame zin voor de gebruiker. U hoeft het alleen de juiste informatie te geven.

Verberg nooit een fout voor het model

Dit is de gouden regel van deze les. Stuur een fout in het tool-bericht exact terug zoals u een normaal resultaat zou doen: als gestructureerde JSON. De tegenovergestelde reflex—de exceptie vangen en een lege string of null teruggeven—laat het model denken dat de functie succesvol was maar simpelweg niets te melden had. Dit levert de meest verwarrende reacties op die denkbaar zijn.

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)}"
        })

Twee velden volstaan: een machinecode in error en een voor mensen leesbare uitleg in message. De code stelt uw monitoringssysteem in staat om incidenten te tellen; de uitleg stelt het model in staat een behulpzaam antwoord te formuleren. Kijk wat er gebeurt bij een niet-bestaande transactie.

# 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?"

Niemand heeft die zin geschreven. Hij vloeit voort uit de foutcode en suggereert de gebruiker zelfs een corrigerende actie.

Een executor die niets door de mazen laat glippen

Het beschermen van een functie is niet genoeg: de laag die tool_calls verstuurt, heeft zijn eigen faalmodi, onafhankelijk van uw bedrijfslogica. Het model kan een functienaam hallucineren die niet in uw woordenboek staat. Het kan malformed JSON-argumenten produceren—een zeldzaam maar reëel geval bij complexe schema’s. Het kan ook geldige JSON leveren waarvan de sleutels niet overeenkomen met de Python-signatuur, wat een TypeError veroorzaakt tijdens **function_params. Elk van deze drie gevallen verdient zijn eigen foutcode, omdat elk een andere oplossing aan uw kant vereist.

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
        }

Merk op dat elke tak, inclusief de faaltakken, een compleet tool-bericht retourneert met de bijbehorende tool_call_id. Dit is essentieel: de API keurt een geschiedenis af waarin een tool_call onbeantwoord blijft, en een stille storing zou bij de volgende beurt een validatiefout veroorzaken, ver verwijderd van de werkelijke oorzaak.

Onderscheid tijdelijke van permanente storingen

Niet alle fouten zijn gelijk. Een ontbrekende transactie zal bij een tweede poging nog steeds ontbreken; opnieuw proberen is dan tijdverspilling. Een netwerktime-out of een tijdelijk overbelaste service lost zich daarentegen vaak vanzelf op. Voor deze tweede categorie biedt een nieuwe poging met exponentiële backoff—één seconde, dan twee, dan vier—de service de tijd om te herstellen zonder deze te bestoken met verzoeken. Na uitputting van de pogingen valt u terug op het gebruikelijke gedrag: een fout-JSON bestemd voor het 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)
                })

De Mistral API kan ook falen

Al het bovenstaande betreft uw functies. De aanroep naar de Mistral API zelf is een apart faalpunt, dat apart wordt afgehandeld: hier is er geen model om het probleem aan uit te leggen, aangezien het model precies datgene is dat onbereikbaar is. Een HTTPValidationError wijst meestal op een fout in uw bericht- of tools-structuur, die u in de code moet oplossen; andere uitzonderingen hebben te maken met het netwerk of de service en worden afgehandeld met dezelfde retry-logica als hierboven.

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

Zie wat er werkelijk gebeurt

Een function calling-systeem is achteraf moeilijk te debuggen als u niet weet welke functie is aangeroepen, met welke argumenten en wat het resultaat was. Loggen is geen luxe; het is de manier waarop u ontdekt dat een ambiguë beschrijving het model ertoe aanzet twee functies te verwarren, of dat één op de vijf gebruikers systematisch een transaction_not_found activeert. Log de aanroep vóór uitvoering, en vervolgens de uitkomst, waarbij u niveau info onderscheidt van niveau error, zodat uw alerts effectief kunnen filteren.

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

Belangrijkste punten

  • Stuur fouten altijd terug naar het model in het tool-bericht—het weet hoe ze te interpreteren
  • Gebruik gestructureerde foutcodes (transaction_not_found, invalid_arguments, enz.)
  • Implementeer retry met backoff voor tijdelijke storingen
  • Handel fouten in uw functies en fouten in de Mistral API apart af
  • Log elke aanroep en elke fout voor monitoring in productie