Batch API: Elaborazione Asincrona Massiva
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della guida Batch API e della struttura di risposta delle Responses API: la lettura dei risultati non presume più che il primo elemento di
outputsia il messaggio (un elemento di ragionamento potrebbe precederlo), e la chiave del codice di errore, scritta senza virgolette, generava unNameError. Fonte: Batch API.
Scambia la Latenza con il Costo
La Batch API si basa su un semplice principio di mercato: accetti che le tue richieste vengano elaborate in modo asincrono entro una finestra di massimo ventiquattro ore e, in cambio, paghi il cinquanta per cento in meno. Tutto ciò che non deve servire un umano in attesa davanti allo schermo rientra in questa categoria. Su larga scala, non si tratta di una micro-ottimizzazione: dimezzi la tua linea di budget.
L’abitudine da costruire all’interno di un team è chiedersi, per ogni nuovo compito di elaborazione, se qualcuno sta aspettando il risultato. Analizzare uno stock di contratti, generare schede prodotto per un catalogo, eseguire un benchmark su migliaia di casi di test, classificare un arretrato di ticket di sei mesi, estrarre campi da un lotto di fatture: in tutti questi casi, la risposta finisce in una dashboard o in un database, non in un’interfaccia conversazionale. Il ritardo è invisibile, ma il risparmio no.
Costruisci e Avvia un Batch
Il formato di input è un file JSONL: una riga per richiesta, dove ogni riga è un oggetto completo e indipendente. Il campo custom_id è ciò che ti permette di collegare ogni risposta alla sua richiesta originale, poiché nulla garantisce l’ordine del file di output. Scegli un ID stabile e significativo: un ID documento dal tuo database piuttosto che un numero di iterazione, altrimenti la fase di riconciliazione diventerà un incubo.
import json
requests = [
{
"custom_id": f"doc-{i}",
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "gpt-5.6-luna",
"input": f"Summarize this document in 3 key points: {doc}",
"max_output_tokens": 500,
},
}
for i, doc in enumerate(documents_list)
]
# Scrivi il file JSONL
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
Il file viene quindi caricato e referenziato durante la creazione del batch. I metadati non servono a scopi tecnici, ma ti salveranno la giornata quando tre batch saranno in esecuzione parallela e dovrai scoprire quale corrisponde a quale versione del prompt.
import openai
client = openai.OpenAI()
# Carica il file
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Crea il batch
batch = client.batches.create(
input_file_id=file_obj.id,
endpoint="/v1/responses",
completion_window="24h",
metadata={"project": "contract-analysis", "version": "2.1"},
)
print(f"Batch creato: {batch.id}")
print(f"Stato: {batch.status}")
Il monitoraggio prevede il polling del batch finché non esce dallo stato di avanzamento, per poi scaricare il file di output, che è anch’esso in formato JSONL. Il ciclo sottostante distingue tre esiti terminali: failed, expired, cancelled, e solleva un’eccezione per ciascuno: un batch scaduto è uno in cui la finestra di ventiquattro ore è trascorsa prima che tutto fosse elaborato, e trattarlo come un successo parziale silenzioso sarebbe l’opzione peggiore.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Attende il completamento di un batch e restituisce i risultati."""
while True:
batch = client.batches.retrieve(batch_id)
print(
f"Stato: {batch.status} | "
f"Completati: {batch.request_counts.completed}/"
f"{batch.request_counts.total} | "
f"Falliti: {batch.request_counts.failed}"
)
if batch.status == "completed":
break
elif batch.status in ("failed", "expired", "cancelled"):
raise RuntimeError(f"Batch fallito: {batch.status}")
time.sleep(interval)
# Scarica i risultati
content = client.files.content(batch.output_file_id)
results = []
for line in content.text.strip().split("\n"):
results.append(json.loads(line))
return results
results = wait_for_batch(batch.id)
# Elabora i risultati
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output può contenere altri elementi prima del messaggio
# (ragionamento, ad esempio): cerca il testo del messaggio
text = next(
part["text"]
for item in response["body"]["output"] if item["type"] == "message"
for part in item["content"] if part["type"] == "output_text"
)
print(f"{custom_id}: {text[:100]}...")
else:
print(f"{custom_id}: ERRORE {response['status_code']}")
Pianifica i Fallimenti Parziali
Su un batch di grandi dimensioni, alcune richieste falliranno: un documento troncato, un overflow del contesto o un errore transitorio lato server. Un batch quindi non è mai semplicemente “riuscito” o “fallito”: è parzialmente riuscito e devi sapere come isolare la parte mancante. Il pattern da adottare è separare immediatamente i successi dai fallimenti e rigenerare un file JSONL pronto per essere rilanciato, piuttosto che scavare nei log tre giorni dopo per ricostruire ciò che manca.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Separa i successi dai fallimenti per la rielaborazione."""
successes = []
failures = []
for r in results:
if r["response"]["status_code"] == 200:
successes.append(r)
else:
failures.append(r)
if failures:
print(f"Attenzione: {len(failures)} richieste fallite su {len(results)}")
# Riscrivi un file JSONL con i fallimenti per il retry
with open("batch_retry.jsonl", "w") as f:
for failure in failures:
original_request = {
"custom_id": failure["custom_id"],
"method": "POST",
"url": "/v1/responses",
"body": failure["request"]["body"],
}
f.write(json.dumps(original_request) + "\n")
return successes, failures
Moltiplica i Tuoi Risparmi
Su un’esecuzione di elaborazione di diecimila documenti con GPT-5.6 Luna, l’API sincrona rappresenta il costo base, la Batch API rappresenta la metà di tale costo e la cache dei prompt si aggiunge sopra, poiché anche i token memorizzati nella cache beneficiano della propria riduzione. I due meccanismi non sono in competizione: se le tue diecimila richieste condividono lo stesso prompt di sistema lungo, strutturalo come un prefisso stabile e combinerai entrambi gli effetti.
Infine, c’è la questione della suddivisione. Un batch non dovrebbe essere infinito ed è più comodo monitorare diversi batch gestibili piuttosto che un singolo monolite il cui fallimento costa un’intera giornata. La funzione seguente taglia una lista di richieste in batch di dimensioni limitate.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Divide in batch di dimensioni ottimali."""
batches = []
current_batch = []
for request in requests:
current_batch.append(request)
if len(current_batch) >= max_size:
batches.append(current_batch)
current_batch = []
if current_batch:
batches.append(current_batch)
return batches
Punti chiave
- La Batch API offre una riduzione del 50% per l’elaborazione non in tempo reale
- Prepara le tue richieste in un file JSONL con un
custom_idunico per richiesta - Pianifica un meccanismo di retry per le richieste fallite
- Combina con la cache dei prompt per massimizzare i risparmi