Guida al formato JSONL per la Batch API di OpenAI
Scopri come strutturare i file JSONL per la Batch API di OpenAI e risparmiare il 50% sui costi
Cos'è la Batch API di OpenAI?
La Batch API di OpenAI ti permette di inviare grandi volumi di richieste API in un unico job batch. Anziché effettuare migliaia di chiamate API singole, carichi un file JSONL con tutte le richieste e OpenAI le elabora in modo asincrono entro 24 ore.
Il vantaggio principale è il risparmio: le richieste batch costano il 50% in meno rispetto alle chiamate API in tempo reale. La Batch API è quindi ideale per attività che non richiedono risposte immediate, come la generazione di contenuti, la classificazione dei dati, il calcolo degli embedding e le pipeline di valutazione.
Formato JSONL delle richieste
Ogni riga del file JSONL di input del batch rappresenta una richiesta API, deve contenere tre campi obbligatori e deve seguire una struttura precisa.
custom_id — Un identificatore univoco per ciascuna richiesta, che permette di associare ogni risposta alla richiesta corrispondente. Può essere una stringa qualsiasi, fino a 512 caratteri.method — Il metodo HTTP. Al momento è supportato solo POST.url — Il percorso dell'endpoint API: /v1/chat/completions per le chat completion, /v1/embeddings per gli embedding.body — Il corpo della richiesta, nello stesso formato previsto dall'endpoint API corrispondente.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Chat completion in batch
L'uso più comune della Batch API è l'invio di più richieste di chat completion. Ogni riga contiene una richiesta completa con model, messages e parametri facoltativi come max_tokens o temperature.
Richiesta singola
Ogni riga contiene una richiesta di chat completion completa, con model, messages e parametri facoltativi.
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}File JSONL con più richieste
Un file batch contiene in genere centinaia o migliaia di richieste. Questo esempio contiene tre attività diverse: generazione di un riassunto, classificazione e traduzione.
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}Embedding in batch
La Batch API supporta anche le richieste di embedding, utili per elaborare grandi raccolte di documenti. I batch di embedding usano la stessa struttura JSONL, ma le richieste sono dirette all'endpoint /v1/embeddings.
Le richieste di embedding hanno un corpo più semplice, con model e il testo di input.
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}Formato delle risposte
Al termine di un job batch, OpenAI fornisce un file JSONL di output in cui ogni riga contiene la risposta a una richiesta. Ogni risposta include il custom_id originale, così puoi associarla alla richiesta corrispondente.
Risposta a una richiesta riuscita
La risposta a una richiesta riuscita include il custom_id, il codice di stato della risposta e il corpo completo della risposta API.
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}Risposta di errore
Le richieste non riuscite includono un oggetto di errore con un codice e un messaggio che descrive il problema.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Procedura completa per usare la Batch API
Ecco i cinque passaggi per usare la Batch API con l'SDK Python, dalla creazione del file JSONL al download e al parsing dei risultati.
- 1Crea un file JSONL con una richiesta per riga
- 2Carica il file tramite la Files API, impostando purpose su batch
- 3Crea un job batch specificando l'ID del file caricato
- 4Controlla periodicamente lo stato del batch finché non passa a completed, failed o cancelled
- 5Scarica il file JSONL di output ed eseguine il parsing per estrarre i risultati
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())Batch API e API in tempo reale a confronto
Sapere quando usare la Batch API e quando l'API standard in tempo reale ti aiuta a ottimizzare costi e prestazioni.
Per approfondire il formato JSONL per il fine-tuning di OpenAI, consulta la nostra Guida al formato JSONL di OpenAI.
Prepara i tuoi file batch
Usa i nostri strumenti gratuiti per creare, validare ed esaminare i file JSONL del batch prima di inviarli a OpenAI.
Una guida completa alla preparazione dei file JSONL per OpenAI: formato dei dati per il fine-tuning, richieste alla Batch API, errori comuni e consigli per la validazione.
Dividi file JSONL grandi in parti più piccole e gestibili per numero di righe.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Impara a preparare dati di addestramento JSONL per il fine-tuning AI/ML. La guida presenta i formati dei dataset di OpenAI, Anthropic Claude e HuggingFace, con validazione e pipeline di preparazione dei dati.