Salt la conținutul principal
Română— Alege o limbă
Meniu

Gestionarea erorilor

Lecția 10 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Erorile sunt inevitabile
  2. Nu ascundeți niciodată o eroare de model
  3. Un executor care nu lasă nimic să scape
  4. Distingeți erorile tranzitorii de cele permanente
  5. Și API-ul Mistral poate eșua
  6. Vedeți ce se întâmplă cu adevărat
  7. Puncte cheie

Erorile sunt inevitabile

În producție, funcțiile eșuează. API-urile externe cad, ID-urile nu există, parametrii sunt invalizi, iar timeout-urile expiră. Întrebarea nu este „se va produce o eroare?“, ci „cum gestionăm eșecul cu eleganță?“. Un tracker de plăți care se blochează pentru că un utilizator a tastat T9999 în loc de T1001 nu este un sistem de producție; este doar o demonstrație.

Vestea bună este că dispuneți de o resursă pe care arhitecturile clasice nu o au: modelul Mistral poate înțelege mesajele de eroare pe care i le trimiteți și își poate adapta răspunsul în consecință. În timp ce un backend tradițional trebuie să genereze un mesaj de interfață pentru fiecare cod de eroare, dumneavoastră puteți lăsa modelul să transforme eșecul într-o propoziție utilă pentru utilizator. Trebuie doar să îi furnizați informațiile necesare.

Nu ascundeți niciodată o eroare de model

Aceasta este regula de aur a acestei lecții. Returnați o eroare în mesajul tool exact așa cum ați returna un rezultat normal: sub formă de JSON structurat. Reflexul opus—capturarea excepției și returnarea unui șir gol sau a valorii null—face ca modelul să creadă că funcția a reușit, dar pur și simplu nu a avut nimic de spus. Acest lucru generează cele mai confuze răspunsuri posibile.

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

Două câmpuri sunt suficiente: un cod mașină în error și o explicație lizibilă pentru om în message. Codul permite sistemului de monitorizare să numere aparițiile; explicația permite modelului să formuleze un răspuns util. Iată ce se întâmplă în cazul unei tranzacții inexistente.

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

Nimeni nu a scris acea propoziție. Ea derivă din codul de eroare și sugerează chiar o acțiune corectivă utilizatorului.

Un executor care nu lasă nimic să scape

Protejarea unei funcții nu este suficientă: stratul care distribuie tool_calls are propriile sale moduri de eșec, independente de logica de afaceri. Modelul poate halucina un nume de funcție care nu există în dicționarul dumneavoastră. Poate produce argumente JSON malformate—un caz rar, dar real, în cazul schemelor complexe. De asemenea, poate furniza un JSON valid ale cărui chei nu corespund semnăturii Python, provocând un TypeError în timpul execuției **function_params. Fiecare dintre aceste trei cazuri merită propriul cod de eroare, deoarece fiecare necesită o remediere diferită din partea dumneavoastră.

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
        }

Observați că fiecare ramură, inclusiv cele de eșec, returnează un mesaj tool complet cu tool_call_id său. Acest lucru este esențial: API-ul respinge un istoric în care un tool_call rămâne fără răspuns, iar un eșec silențios ar provoca o eroare de validare la următoarea iterație, departe de cauza reală.

Distingeți erorile tranzitorii de cele permanente

Nu toate erorile sunt egale. O tranzacție lipsă va fi tot lipsă și la a doua încercare; reîncercarea doar pierde timp. Un timeout de rețea sau un serviciu momentan saturat, însă, se rezolvă adesea de la sine. Pentru această a doua categorie, o reîncercare cu backoff exponențial—o secundă, apoi două, apoi patru—oferă serviciului timp să își revină fără a fi bombardat cu cereri. După epuizarea încercărilor, reveniți la comportamentul obișnuit: un JSON de eroare destinat modelului.

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

Și API-ul Mistral poate eșua

Tot ce am discutat până acum privește funcțiile dumneavoastră. Apelul către API-ul Mistral în sine este un punct de eșec distinct, gestionat separat: aici, nu există un model căruia să îi explicați problema, deoarece modelul este chiar cel inaccesibil. Un HTTPValidationError semnalează de obicei o eroare în structura mesajelor sau a instrumentelor, pe care trebuie să o remediați în cod; alte excepții țin de rețea sau de serviciu și sunt gestionate cu aceeași logică de reîncercare ca mai sus.

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

Vedeți ce se întâmplă cu adevărat

Un sistem de apelare a funcțiilor este greu de depanat post-factum dacă nu știți ce funcție a fost apelată, cu ce argumente și ce a returnat. Logarea nu este un lux; este modul în care veți descoperi că o descriere ambiguă împinge modelul să confunde două funcții sau că unul din cinci utilizatori declanșează sistematic un transaction_not_found. Logați apelul înainte de execuție, apoi verdictul, distingând nivelul info de nivelul error, astfel încât alertele dumneavoastră să poată filtra eficient.

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

Puncte cheie

  • Returnați întotdeauna erorile către model în mesajul tool—acesta știe cum să le interpreteze
  • Utilizați coduri de eroare structurate (transaction_not_found, invalid_arguments etc.)
  • Implementați reîncercarea cu backoff pentru erorile tranzitorii
  • Gestionați separat erorile din funcțiile dumneavoastră și erorile din API-ul Mistral
  • Logați fiecare apel și fiecare eroare pentru monitorizarea în producție