Gestionarea erorilor și mecanismele de fallback
Pe această pagină
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ă