Przejdź do głównej treści
Polski— Wybierz język
Menu

Obsługa błędów

Lekcja 10 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Błędy są nieuniknione
  2. Nigdy nie ukrywaj błędu przed modelem
  3. Executor, który niczego nie przepuści
  4. Rozróżniaj błędy przejściowe od trwałych
  5. API Mistral również może zawieść
  6. Zobacz, co naprawdę się dzieje
  7. Kluczowe wnioski

Błędy są nieuniknione

W środowisku produkcyjnym funkcje ulegają awariom. Zewnętrzne API przestają działać, identyfikatory nie istnieją, parametry są nieprawidłowe, a limity czasu wygasają. Pytanie nie brzmi „czy wystąpi błąd?“, ale „jak obsłużyć awarię w sposób elegancki?“. System śledzenia płatności, który crashinguje, ponieważ użytkownik wpisał T9999 zamiast T1001, nie jest systemem produkcyjnym – to jedynie demonstracja.

Dobra wiadomość jest taka, że masz tutaj zasób, którego brakuje klasycznym architekturom: model Mistral potrafi zrozumieć komunikaty o błędach, które mu odeślesz, i odpowiednio dostosować swoją odpowiedź. Podczas gdy tradycyjny backend musi generować komunikat interfejsu użytkownika dla każdego kodu błędu, Ty możesz pozwolić modelowi przełożyć awarię na pomocne zdanie dla użytkownika. Musisz mu tylko dostarczyć odpowiednie informacje.

Nigdy nie ukrywaj błędu przed modelem

To złota zasada tej lekcji. Zwracaj błąd w wiadomości tool dokładnie tak samo, jak normalny wynik: jako ustrukturyzowany JSON. Przeciwny odruch – przechwycenie wyjątku i zwrócenie pustego ciągu znaków lub null – sprawia, że model wierzy, iż funkcja zakończyła się sukcesem, ale po prostu nie miała nic do powiedzenia. Generuje to najbardziej mylące możliwe odpowiedzi.

def retrieve_payment_status(df, transaction_id: str) -> str:
    """Pobiera status z pełną obsługą błędów."""
    try:
        if transaction_id not in df["transaction_id"].values:
            return json.dumps({
                "error": "transaction_not_found",
                "message": f"Transakcja {transaction_id} nie istnieje w bazie danych."
            })

        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"Błąd podczas pobierania danych: {str(e)}"
        })

Wystarczą dwa pola: kod maszynowy w error i czytelny dla człowieka opis w message. Kod pozwala systemowi monitorowania zliczać wystąpienia; opis umożliwia modelowi sformułowanie pomocnej odpowiedzi. Zobacz, co dzieje się w przypadku nieistniejącej transakcji.

# Użytkownik żąda nieistniejącej transakcji
messages = [{"role": "user", "content": "Status płatności T9999?"}]

# Model wywołuje retrieve_payment_status(transaction_id="T9999")
# Twoja funkcja zwraca: {"error": "transaction_not_found", ...}

# Model formułuje:
# → "Nie udało mi się znaleźć transakcji o ID T9999.
#     Czy możesz sprawdzić numer i spróbować ponownie?"

Nikt nie napisał tego zdania. Wynika ono z kodu błędu, a nawet sugeruje użytkownikowi działanie naprawcze.

Executor, który niczego nie przepuści

Zabezpieczenie samej funkcji to za mało: warstwa obsługująca wywołania tool_calls ma własne tryby awarii, niezależne od Twojej logiki biznesowej. Model może halucynować nazwę funkcji, której nie ma w Twoim słowniku. Może wygenerować źle sformatowane argumenty JSON – rzadki, ale realny przypadek przy złożonych schematach. Może też dostarczyć poprawny JSON, którego klucze nie pasują do sygnatury Pythona, powodując TypeError podczas **function_params. Każdy z tych trzech przypadków zasługuje na własny kod błędu, ponieważ każdy wymaga innego rodzaju naprawy po Twojej stronie.

def execute_tool_call(tool_call, available_functions):
    """Wykonuje tool_call z pełną obsługą błędów."""
    function_name = tool_call.function.name

    # Sprawdź, czy funkcja istnieje
    if function_name not in available_functions:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "function_not_found",
                "message": f"Funkcja {function_name} jest niedostępna."
            }),
            "tool_call_id": tool_call.id
        }

    # Parsuj argumenty
    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"Nieprawidłowe argumenty JSON: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

    # Wykonaj funkcję
    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"Niekompatybilne parametry: {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"Błąd wykonania: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

Zauważ, że każda gałąź, włącznie z tymi obsługującymi błędy, zwraca kompletną wiadomość tool z jej tool_call_id. Jest to kluczowe: API odrzuci historię, w której na tool_call nie ma odpowiedzi, a cicha awaria spowodowałaby błąd walidacji przy następnej turze, daleko od rzeczywistej przyczyny.

Rozróżniaj błędy przejściowe od trwałych

Nie wszystkie błędy są takie same. Brakująca transakcja nadal będzie brakować przy drugiej próbie; ponawianie tylko marnuje czas. Timeout sieciowy lub chwilowo przeciążona usługa często jednak rozwiązują się same. W przypadku tej drugiej kategorii ponowienie próby z wykładniczym opóźnieniem (jedna sekunda, potem dwie, potem cztery) daje usłudze czas na odzyskanie sprawności bez zasypywania jej żądaniami. Po wyczerpaniu prób wracasz do standardowego zachowania: zwracasz JSON z błędem przeznaczony dla modelu.

import time

def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
    """Wykonuje funkcję z wykładniczą próbą ponowienia."""
    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"Usługa niedostępna po {max_retries} próbach.",
                    "details": str(e)
                })

API Mistral również może zawieść

Wszystko powyższe dotyczy Twoich funkcji. Wywołanie samego API Mistral to odrębny punkt awarii, obsługiwany osobno: tutaj nie ma modelu, któremu można by wyjaśnić problem, ponieważ to właśnie model jest nieosiągalny. HTTPValidationError zazwyczaj sygnalizuje błąd w strukturze Twoich wiadomości lub narzędzi, który musisz naprawić w kodzie; inne wyjątki dotyczą sieci lub usługi i są obsługiwane z użyciem tej samej logiki ponawiania co powyżej.

from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError

def safe_chat_complete(client, model, messages, tools):
    """Wywołanie API Mistral z obsługą błędów."""
    try:
        return client.chat.complete(
            model=model,
            messages=messages,
            tools=tools
        )
    except HTTPValidationError as e:
        print(f"Błąd walidacji: {e}")
        return None
    except Exception as e:
        print(f"Błąd API: {e}")
        return None

Zobacz, co naprawdę się dzieje

System wywoływania funkcji jest trudny do debugowania post factum, jeśli nie wiesz, która funkcja została wywołana, z jakimi argumentami i co zwróciła. Logowanie nie jest luksusem; to sposób, w jaki odkryjesz, że niejednoznaczny opis skłania model do pomylenia dwóch funkcji, albo że co piąty użytkownik systematycznie wyzwala transaction_not_found. Loguj wywołanie przed wykonaniem, a następnie werdykt, rozróżniając poziom info od error, aby Twoje alerty mogły skutecznie filtrować zdarzenia.

import logging

logger = logging.getLogger("function_calling")

def execute_and_log(tool_call, available_functions):
    """Wykonuje i loguje wynik."""
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    logger.info(f"Wywołanie: {function_name}({function_params})")

    result = execute_tool_call(tool_call, available_functions)
    content = json.loads(result["content"])

    if "error" in content:
        logger.error(f"Awaría {function_name}: {content['error']} - {content['message']}")
    else:
        logger.info(f"Sukces {function_name}: {content}")

    return result

Kluczowe wnioski

  • Zawsze zwracaj błędy do modelu w wiadomości tool – potrafi je zinterpretować
  • Używaj ustrukturyzowanych kodów błędów (transaction_not_found, invalid_arguments itp.)
  • Wdróż ponawianie z wykładniczym opóźnieniem dla błędów przejściowych
  • Obsługuj błędy w Twoich funkcjach i błędy w API Mistral oddzielnie
  • Loguj każde wywołanie i każdy błąd dla potrzeb monitorowania produkcji