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

Gestionarea erorilor și mecanismele de fallback

Lecția 4 din 20 Dezvoltator
Pe această pagină
  1. Gestionarea erorilor și mecanismele de fallback
  2. Returnarea erorilor către model
  3. Reîncercare cu backoff exponențial
  4. Timeout-uri per funcție
  5. Fallback între funcții
  6. Circuit breaker
  7. Buclă robustă completă
  8. Puncte cheie

Gestionarea erorilor și mecanismele de fallback

Apelarea funcțiilor introduce o provocare pe care codul clasic nu o întâmpină: atunci când funcția dumneavoastră eșuează, există doi destinatari pentru acea eroare. Aplicația dumneavoastră, ca de obicei – și modelul, care așteaptă un rezultat pentru a continua. Uitarea acestui aspect creează cel mai derutant simptom în producție: o conversație care se oprește brusc fără nicio explicație, deoarece o excepție a fost înghițită pe partea de server, iar modelul așteaptă în continuare.

Regula care structurează întreaga lecție este următoarea: returnați întotdeauna un function_call_output, chiar și în caz de eșec. Un model informat că un API este indisponibil poate propune o alternativă, poate cere clarificări sau poate explica situația utilizatorului. Un model care nu primește nimic nu poate face nimic.

Returnarea erorilor către model

Formatul erorii contează la fel de mult ca trimiterea acesteia. Un simplu „Eroare“ nu învață modelul nimic; un obiect JSON care distinge tipul erorii, dacă este tranzitorie sau permanentă, și pașii următori, permite modelului să decidă. Acest lucru este contraintuitiv: scrieți mesaje de eroare menite să fie citite de o mașină de raționament, nu înregistrate (logged) pentru oameni.

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

Reîncercare cu backoff exponențial

Reîncercarea are sens doar pentru probleme care s-ar putea rezolva la a doua încercare: întreruperi de rețea, coduri de status 429 sau indisponibilități temporare. Reîncercarea unei cereri respinse din cauza autentificării invalide sau a parametrilor incorecți doar întârzie eșecul, multiplicând în același timp numărul de apeluri. De aceea, codul de mai jos filtrează explicit erorile – filtrarea face munca, în timp ce backoff-ul este doar o curtoazie pe care o datorați serviciului remote.

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

Timeout-uri per funcție

Un singur timeout pentru toate funcțiile este întotdeauna configurat greșit: prea scurt și ucide procesările intensive; prea lung și face utilizatorul să aștepte după o simplă căutare în cache. Bazați fiecare valoare pe duratele observate în condiții normale, cu o marjă de siguranță – nu pe cel mai rău caz imaginabil, ceea ce ar însemna efectiv absența oricărui timeout.

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

Fallback între funcții

Fallback-ul este un compromis, nu un reflex: servirea unor date din cache vechi de șase ore este mai bună decât nimic pentru un tablou de bord, dar mult mai rea decât nimic pentru un sold bancar. Când degradați serviciul, spuneți-o explicit – în rezultatul returnat modelului, astfel încât acesta să poată avertiza utilizatorul în loc să prezinte date învechite ca fiind proaspete.

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

Circuit breaker

Circuit breaker gestionează ceea ce reîncercarea nu poate: un serviciu care este picat pe termen lung. După N eșecuri, acesta se declanșează și returnează o eroare imediat, fără a mai încerca, permițând apoi ocazional trecerea unei cereri de test pentru a verifica recuperarea. Câștigul este dublu – utilizatorii dumneavoastră nu mai așteaptă un timeout la fiecare cerere, iar serviciul care are probleme nu este ținut jos de reîncercările dumneavoastră.

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

Buclă robustă completă

Modelul complet reunește cele cinci mecanisme de mai sus. O singură precauție îl face cu adevărat sigur și este ușor de omis: limitați numărul de iterații. Un model care intră în buclă apelând o funcție al cărei rezultat nu îi convine este rar, dar fără o limită superioară va epuiza bugetul dumneavoastră până la epuizare – iar acesta este genul de incident pe care îl descoperiți pe factură.

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"

Puncte cheie

  • Returnați întotdeauna un function_call_output, chiar și în caz de eroare
  • Structurați erorile ca JSON pentru ca modelul să le poată utiliza
  • Reîncercați doar erorile tranzitorii cu backoff exponențial
  • Implementați mecanisme de fallback între sursele de date
  • Utilizați un circuit breaker pentru a proteja serviciile care eșuează