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

Obsługa błędów i mechanizmy awaryjne

Lekcja 4 z 20 Programista
Na tej stronie
  1. Obsługa błędów i mechanizmy awaryjne
  2. Zwracanie błędów do modelu
  3. Ponawianie z wykładniczym opóźnieniem (Exponential Backoff)
  4. Limit czasu dla poszczególnych funkcji
  5. Przełączanie awaryjne między funkcjami (Fallback)
  6. Wyłącznik czasowy (Circuit Breaker)
  7. Kompletna pętla odporna na błędy
  8. Kluczowe wnioski

Obsługa błędów i mechanizmy awaryjne

Wywoływanie funkcji wprowadza wyzwanie, z którym klasyczny kod się nie mierzy: gdy Twoja funkcja zawiedzie, odbiorcami tego błędu są dwie strony. Twoja aplikacja, jak zwykle, oraz model, który czeka na wynik, aby kontynuować działanie. Zapomnienie o tym powoduje najbardziej zagadkowy objaw w środowisku produkcyjnym: konwersacja nagle ustaje bez żadnego wyjaśnienia, ponieważ wyjątek został połknięty po stronie serwera, a model nadal czeka.

Zasada, która stanowi fundament tej lekcji, brzmi: zawsze zwracaj function_call_output, nawet w przypadku błędu. Model poinformowany o niedostępności API może zaproponować alternatywę, poprosić o doprecyzowanie lub wyjaśnić sytuację użytkownikowi. Model, który nie otrzyma żadnej odpowiedzi, nie może zrobić nic.

Zwracanie błędów do modelu

Format błędu jest równie ważny co samo jego przesłanie. Gołe słowo „Błąd“ niczego modelowi nie nauczy; obiekt JSON, który rozróżnia typ błędu, określa, czy jest on przejściowy, czy trwały, i sugeruje kolejne kroki, pozwala modelowi podjąć decyzję. Jest to kontrintuicyjne: piszesz komunikaty o błędach przeznaczone do przetworzenia przez maszynę rozumującą, a nie do logowania dla ludzi.

import json
from openai import OpenAI

client = OpenAI()

def execute_function(name: str, arguments: str, call_id: str) -> dict:
    try:
        args = json.loads(arguments)
        result = dispatcher[name](**args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except KeyError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "unknown_function",
                "message": f"The function '{name}' does not exist"
            })
        }
    except json.JSONDecodeError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "invalid_arguments",
                "message": "The JSON arguments are malformed"
            })
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "internal_error",
                "message": str(e)
            })
        }

Ponawianie z wykładniczym opóźnieniem (Exponential Backoff)

Ponawianie ma sens tylko w przypadku problemów, które mogą ustąpić przy drugiej próbie: przerwy w sieci, kody statusu 429 lub tymczasowe awarie. Ponawianie żądania odrzuconego z powodu nieprawidłowej autentyfikacji lub błędnych parametrów jedynie opóźnia niepowodzenie, mnożąc jednocześnie liczbę wywołań. Dlatego poniższy kod jawnie filtruje błędy – to filtrowanie wykonuje właściwą pracę, podczas gdy mechanizm backoff jest jedynie uprzejmością, którą jesteś winien zdalnej usłudze.

import time
import random

def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
    """Retry with exponential backoff and jitter."""
    for attempt in range(max_retries + 1):
        try:
            return func(**args)
        except (ConnectionError, TimeoutError) as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)
        except ValueError:
            # Data error: do not retry
            raise

def execute_function_robust(name, arguments, call_id):
    args = json.loads(arguments)
    try:
        result = execute_with_retry(dispatcher[name], args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": type(e).__name__,
                "message": str(e),
                "retries_performed": 3
            })
        }

Limit czasu dla poszczególnych funkcji

Jeden limit czasu dla wszystkich funkcji jest zawsze źle skonfigurowany: zbyt krótki zabija ciężkie przetwarzanie, zbyt długi заставляет użytkownika czekać na proste odpytanie pamięci podręcznej. Oprzyj każdą wartość na obserwowanych czasach trwania w normalnych warunkach, z pewnym marginesem – nie na najgorszym możliwym scenariuszu, co w praktyce oznaczałoby brak limitu czasu.

import signal
from functools import wraps

TIMEOUTS = {
    "search_client": 5,
    "generate_report": 30,
    "send_email": 10,
}

def with_timeout(func, timeout_seconds):
    """Executes a function with a timeout."""
    import concurrent.futures
    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
        future = executor.submit(func)
        try:
            return future.result(timeout=timeout_seconds)
        except concurrent.futures.TimeoutError:
            raise TimeoutError(
                f"Function interrupted after {timeout_seconds}s"
            )

def execute_with_timeout(name, arguments, call_id):
    args = json.loads(arguments)
    timeout = TIMEOUTS.get(name, 10)  # 10s by default

    try:
        result = with_timeout(
            lambda: dispatcher[name](**args),
            timeout
        )
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except TimeoutError as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "timeout",
                "message": str(e),
                "suggestion": "Retry with more specific criteria"
            })
        }

Przełączanie awaryjne między funkcjami (Fallback)

Mechanizm fallback to kompromis, a nie odruch: serwowanie sześciogodzinnych danych z cache jest lepsze niż nic dla panelu dashboard, ale znacznie gorsze niż nic w przypadku salda konta bankowego. Gdy obniżasz jakość usługi, poinformuj o tym – w wyniku zwracanym do modelu, aby mógł ostrzec użytkownika, zamiast przedstawiać nieaktualne dane jako świeże.

async def search_product(term: str) -> dict:
    """Search with fallback: primary API -> cache -> local database."""
    # Attempt 1: Catalog API
    try:
        return await api_catalog.search(term)
    except Exception:
        pass

    # Attempt 2: Redis cache
    try:
        cached = await redis_client.get(f"product:{term}")
        if cached:
            result = json.loads(cached)
            result["_source"] = "cache"
            result["_warning"] = "Data may be outdated"
            return result
    except Exception:
        pass

    # Attempt 3: Local SQLite database
    try:
        row = db.execute(
            "SELECT * FROM products WHERE name LIKE ?",
            (f"%{term}%",)
        ).fetchone()
        if row:
            return {
                "name": row["name"],
                "price": row["price"],
                "_source": "local_db",
                "_warning": "Data from last synchronization"
            }
    except Exception:
        pass

    return {
        "error": "unavailable",
        "message": "No data source accessible for this search"
    }

Wyłącznik czasowy (Circuit Breaker)

Circuit breaker radzi sobie z tym, z czym nie poradzi sobie ponawianie: z usługą, która jest niedostępna przez dłuższy czas. Po N niepowodzeniach się otwiera i natychmiast zwraca błąd, nawet nie próbując wykonać żądania, a następnie okazjonalnie przepuszcza żądanie testowe, aby sprawdzić, czy usługa wróciła do życia. Korzyść jest podwójna – Twoi użytkownicy przestają czekać na przekroczenie limitu czasu przy każdym żądaniu, a obciążona usługa nie jest dodatkowo dobijana przez Twoje próby ponowienia.

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, failure_threshold=5, open_duration=60):
        self.threshold = failure_threshold
        self.duration = open_duration
        self.failures = 0
        self.last_failure = None
        self.state = "closed"  # closed, open, half-open

    def can_execute(self) -> bool:
        if self.state == "closed":
            return True
        if self.state == "open":
            if datetime.now() - self.last_failure > timedelta(seconds=self.duration):
                self.state = "half-open"
                return True
            return False
        return True  # half-open: allow one test attempt

    def record_success(self):
        self.failures = 0
        self.state = "closed"

    def record_failure(self):
        self.failures += 1
        self.last_failure = datetime.now()
        if self.failures >= self.threshold:
            self.state = "open"

# One circuit breaker per external service
breakers = {
    "weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
    "catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}

Kompletna pętla odporna na błędy

Pełny wzorzec łączy powyższych pięć mechanizmów. Jeden środek ostrożności czyni go naprawdę bezpiecznym i łatwo go przeoczyć: ogranicz liczbę iteracji. Model, który wpada w pętlę wywołując funkcję, której wynik mu nie odpowiada, jest rzadki, ale bez górnego limitu wypali Twój budżet aż do wyczerpania – a to rodzaj incydentu, o którym dowiadujesz się z faktury.

def robust_loop(prompt, tools, max_turns=10):
    messages = prompt
    for turn in range(max_turns):
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=messages,
            tools=tools
        )

        calls = [i for i in response.output if i.type == "function_call"]
        if not calls:
            return response.output_text

        results = []
        for call in calls:
            result = execute_function_robust(
                call.name, call.arguments, call.call_id
            )
            results.append(result)

        messages = response.output + results

    return "Workflow interrupted: turn limit reached"

Kluczowe wnioski

  • Zawsze zwracaj function_call_output, nawet w przypadku błędu
  • Strukturyzuj błędy jako JSON, aby model mógł z nich skorzystać
  • Ponawiaj tylko błędy przejściowe, stosując wykładnicze opóźnienie
  • Wdrażaj mechanizmy fallback między źródłami danych
  • Używaj circuit breakera do ochrony awaryjnych usług