Modalità in background
In questa pagina
Una terza via tra sincrono e batch
La modalità in background delle Responses API colma una nicchia specifica nel tuo toolkit. Una chiamata sincrona ti fornisce la risposta immediatamente, ma ti costringe a mantenere la connessione aperta per l’intera generazione. Le Batch API elaborano migliaia di richieste a metà prezzo, ma i risultati richiedono ore. La modalità in background si colloca tra le due: gestisce singole richieste alla tariffa standard senza bisogno di una connessione aperta. Invii la richiesta, ricevi un ID e recuperi il risultato quando è pronto.
Questo compromesso mira a un caso d’uso preciso: una singola richiesta che richiede troppo tempo per una chiamata bloccante, ma che non può attendere fino al giorno dopo. È esattamente lo scenario che si presenta quando esegui un modello ad alto ragionamento su un documento complesso.
Avvio e recupero
L’attivazione richiede un solo parametro. La risposta immediata non contiene testo; restituisce un ID e uno stato, tipicamente queued o in_progress.
import openai
client = openai.OpenAI()
# Avvia la richiesta in background
response = client.responses.create(
model="gpt-5.6-sol", # Ideale per task lenti (alto ragionamento)
input="Analizza le implicazioni economiche della regolamentazione europea sull'IA "
"per le PMI francesi. Proponi un piano d'azione in 10 punti.",
background=True, # Modalità in background
)
print(f"ID risposta: {response.id}")
print(f"Stato: {response.status}") # "queued" o "in_progress"
Questo ID è il tuo unico collegamento con il lavoro in corso: salvalo prima di fare qualsiasi altra cosa. Perderlo significa pagare per una generazione che non recupererai mai. Il recupero prevede quindi il polling dell’API finché lo stato non diventa terminale, gestendo fallimenti e cancellazioni separatamente poiché hanno conseguenze aziendali diverse.
import time
def wait_for_response(response_id: str, interval: int = 5) -> str:
"""Attende il completamento di una risposta in background."""
while True:
response = client.responses.retrieve(response_id)
match response.status:
case "completed":
return response.output_text
case "failed":
raise RuntimeError(
f"Richiesta fallita: {response.error}"
)
case "cancelled":
raise RuntimeError("La richiesta è stata cancellata.")
case _:
print(f"Stato: {response.status}...")
time.sleep(interval)
Task di ragionamento prolungato
Un modello come GPT-5.6 Sol con il ragionamento avanzato abilitato può impiegare da 30 secondi a due minuti prima di produrre il primo token visibile. In una chiamata sincrona, queste durate superano i timeout predefiniti di client HTTP, proxy e gateway. La modalità in background elimina questo problema alla radice e, incidentalmente, ti permette di lanciare diverse analisi pesanti senza bloccare altrettante connessioni.
async def deep_analysis(document: str) -> str:
"""Avvia un'analisi con GPT-5.6 Sol senza bloccare."""
response = client.responses.create(
model="gpt-5.6-sol",
input=f"Esegui un'analisi legale approfondita di questo contratto. "
f"Identifica tutti i potenziali rischi, le clausole problematiche "
f"e proponi modifiche.\n\n{document}",
background=True,
)
return response.id
# Avvia più analisi in parallelo
task_ids = []
for doc in documents:
task_id = await deep_analysis(doc)
task_ids.append(task_id)
# Recupera i risultati in seguito
results = {}
for task_id in task_ids:
results[task_id] = wait_for_response(task_id)
Questo pattern si estende naturalmente ai webhook quando il chiamante è un altro servizio. Il tuo endpoint avvia la richiesta, restituisce l’ID e delega un task in background per monitorare il completamento e inviare notifiche. Il chiamante non effettua polling; viene semplicemente notificato.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
@app.post("/api/long-analysis")
async def launch_analysis(request: dict, background_tasks: BackgroundTasks):
"""Avvia un'analisi e notifica tramite webhook al termine."""
response = client.responses.create(
model="gpt-5.6-sol",
input=request["prompt"],
background=True,
)
# Monitora in background
background_tasks.add_task(
monitor_and_notify,
response_id=response.id,
webhook_url=request["webhook_url"],
)
return {"response_id": response.id, "status": "launched"}
async def monitor_and_notify(response_id: str, webhook_url: str):
"""Monitora una richiesta in background e notifica tramite webhook."""
result = wait_for_response(response_id)
async with httpx.AsyncClient() as http:
await http.post(webhook_url, json={
"response_id": response_id,
"result": result,
})
Scegliere la modalità giusta
La regola decisionale si riduce a due domande. Quante richieste? E l’utente sta aspettando? Oltre cento richieste senza requisiti di immediatezza, le Batch API vincono sul prezzo: risultati in ore a metà costo. Se qualcuno sta aspettando davanti allo schermo, le chiamate sincrone rimangono l’unica scelta accettabile alla tariffa standard. La modalità in background copre il resto dello spettro: poche richieste, risultati in minuti, prezzo standard. Vale la pena codificare questa logica una volta per tutte invece di rielaborarla per ogni nuovo servizio.
def choose_mode(
num_requests: int,
urgency: str,
budget: str,
) -> str:
"""Raccomanda la modalità di esecuzione ottimale."""
if num_requests > 100 and urgency != "immediate":
return "batch"
elif urgency == "immediate":
return "synchronous"
else:
return "background"
Infine, prevedi una via di fuga. Una richiesta in background che supera di gran lunga la durata prevista blocca il budget e ritarda il resto della tua pipeline; l’API ti permette di cancellarla esplicitamente. Imposta questo limite al doppio della durata che osservi nella pratica, non alla media, altrimenti rischi di cancellare richieste che stavano per avere successo.
def cancel_if_too_long(response_id: str, timeout: int = 120):
"""Cancella una richiesta se supera il timeout."""
start = time.time()
while time.time() - start < timeout:
response = client.responses.retrieve(response_id)
if response.status == "completed":
return response.output_text
time.sleep(5)
# Timeout superato — cancella
client.responses.cancel(response_id)
raise TimeoutError(
f"Richiesta {response_id} cancellata dopo {timeout}s."
)
Punti chiave
- La modalità in background avvia le richieste senza mantenere aperta una connessione
- Ideale per impostazioni di alto ragionamento (GPT-5.6 Sol) e task lunghi
- Combinala con un webhook per un’architettura event-driven
- Persisti l’ID della risposta: è il tuo unico collegamento con il lavoro in corso
- Per l’elaborazione bulk a basso costo, preferisci le Batch API