Gestione degli errori e fallback
In questa pagina
Gestione degli errori e fallback
La chiamata di funzioni introduce una sfida che il codice classico non affronta: quando la tua funzione fallisce, ci sono due destinatari per quell’errore. La tua applicazione, come al solito, e il modello, che aspetta un risultato per continuare. Dimenticare questo aspetto crea il sintomo più sconcertante in produzione: una conversazione che si blocca improvvisamente senza spiegazioni, perché un’eccezione è stata inghiottita lato server e il modello sta ancora aspettando.
La regola che segue struttura l’intera lezione: restituisci sempre un function_call_output, anche in caso di fallimento. Un modello informato che un’API non è disponibile può proporre un’alternativa, chiedere chiarimenti o spiegare la situazione all’utente. Un modello che non riceve nulla non può fare nulla.
Restituire gli errori al modello
Il formato dell’errore conta tanto quanto l’invio stesso. Un semplice “Errore” non insegna nulla al modello; un oggetto JSON che distingue il tipo di errore, se è transitorio o permanente, e i prossimi passi permette al modello di decidere. Questo è controintuitivo: stai scrivendo messaggi di errore destinati a essere letti da una macchina ragionante, non registrati per gli umani.
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)
})
}
Riprova con backoff esponenziale
La riprova ha senso solo per problemi che potrebbero risolversi al secondo tentativo: interruzioni di rete, codici di stato 429 o interruzioni temporanee. Riprovare una richiesta rifiutata a causa di un’autenticazione non valida o parametri errati ritarda solo il fallimento moltiplicando le chiamate. Ecco perché il codice sottostante filtra esplicitamente gli errori: il filtro fa il lavoro, mentre il backoff è solo la cortesia che devi al servizio remoto.
import time
import random
def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
"""Riprova con backoff esponenziale e 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:
# Errore nei dati: non riprovare
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 per funzione
Un singolo timeout per tutte le funzioni è sempre configurato male: troppo breve e uccide l’elaborazione pesante; troppo lungo e fa aspettare l’utente per una semplice ricerca in cache. Basa ogni valore sulle durate osservate in condizioni normali, con un margine, non sul caso peggiore immaginabile, che equivarrebbe effettivamente a non avere alcun timeout.
import signal
from functools import wraps
TIMEOUTS = {
"search_client": 5,
"generate_report": 30,
"send_email": 10,
}
def with_timeout(func, timeout_seconds):
"""Esegue una funzione con un 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 di 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 tra funzioni
Il fallback è un compromesso, non un riflesso: servire dati in cache vecchi di sei ore è meglio di niente per una dashboard, e molto peggio di niente per un saldo bancario. Quando degradi il servizio, dillo esplicitamente nel risultato restituito al modello, così può avvisare l’utente invece di presentare dati obsoleti come freschi.
async def search_product(term: str) -> dict:
"""Ricerca con fallback: API primaria -> cache -> database locale."""
# Tentativo 1: API del catalogo
try:
return await api_catalog.search(term)
except Exception:
pass
# Tentativo 2: Cache Redis
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
# Tentativo 3: Database locale SQLite
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
Il circuit breaker gestisce ciò che la riprova non può: un servizio giù per lungo tempo. Dopo N fallimenti, scatta e restituisce un errore immediatamente, senza nemmeno provare, permettendo poi occasionalmente a una richiesta di test di passare per verificare il recupero. Il guadagno è duplice: i tuoi utenti smettono di aspettare un timeout per ogni richiesta e il servizio in difficoltà non viene tenuto giù dai tuoi tentativi di riprova.
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: consenti un tentativo di test
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"
# Un circuit breaker per servizio esterno
breakers = {
"weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
"catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}
Ciclo robusto completo
Il pattern completo riunisce i cinque meccanismi sopra descritti. Una precauzione lo rende veramente sicuro ed è facile da trascurare: limita il numero di iterazioni. Un modello che entra in loop chiamando una funzione il cui risultato non gli piace è raro, ma senza un limite superiore brucerà il tuo budget fino all’esaurimento, e questo è il tipo di incidente che scopri sulla fattura.
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"
Punti chiave
- Restituisci sempre un
function_call_output, anche in caso di errore - Struttura gli errori come JSON in modo che il modello possa utilizzarli
- Riprova solo gli errori transitori con backoff esponenziale
- Implementa fallback tra diverse fonti dati
- Usa un circuit breaker per proteggere i servizi che falliscono