Guida al Formato JSONL per la Batch API di OpenAI
Impara a strutturare file JSONL per la Batch API di OpenAI per risparmiare il 50% sui costi
Ultimo aggiornamento: Febbraio 2026
Cos'è la Batch API di OpenAI?
La Batch API di OpenAI ti permette di inviare grandi volumi di richieste API come un singolo job batch. Invece di effettuare migliaia di chiamate API individuali, carichi un file JSONL contenente tutte le tue richieste e OpenAI le elabora in modo asincrono entro 24 ore.
Il vantaggio principale è il costo: le richieste batch costano il 50% in meno rispetto alle chiamate API in tempo reale. Questo rende la Batch API ideale per attività che non necessitano di risposte immediate, come la generazione di contenuti, la classificazione dei dati, il calcolo di embedding e le pipeline di valutazione.
Formato JSONL delle Richieste
Ogni riga nel file JSONL di input del batch rappresenta una richiesta API. Ogni riga deve contenere tre campi obbligatori e segue una struttura specifica.
custom_id — Un identificatore univoco per ogni richiesta. Usato per abbinare le richieste alle risposte. Può essere qualsiasi stringa fino a 512 caratteri.method — Il metodo HTTP. Attualmente è supportato solo POST.url — Il percorso dell'endpoint API. Per chat completions: /v1/chat/completions. Per embedding: /v1/embeddings.body — Il corpo della richiesta. Stesso formato del corpo della richiesta dell'endpoint API corrispondente.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}
Batch di Chat Completions
Il caso d'uso più comune per la Batch API è l'invio di molteplici richieste di chat completion. Ogni riga contiene una richiesta completa con model, messages e parametri opzionali come max_tokens o temperature.
Singola Richiesta
Ogni riga contiene una richiesta di chat completion completa con model, messages e parametri opzionali.
{"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 Richieste Multiple
Un file batch contiene tipicamente centinaia o migliaia di richieste. Ecco un file con tre attività diverse: 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}}
Batch di Embedding
La Batch API supporta anche richieste di embedding, utili per elaborare grandi collezioni di documenti. I batch di embedding usano la stessa struttura JSONL ma puntano all'endpoint /v1/embeddings.
Le richieste di embedding usano una struttura del corpo più semplice con model e 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
Quando un job batch è completato, OpenAI fornisce un file JSONL di output dove ogni riga contiene la risposta per una richiesta. La risposta include il custom_id originale per poter abbinare le risposte alle richieste.
Risposta con Successo
Una risposta con successo 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 con Errore
Le richieste fallite includono un oggetto errore con un codice e un messaggio che spiega cosa è andato storto.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}
Flusso di Lavoro Completo della Batch API
Ecco il flusso di lavoro completo in 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 usando la Files API con purpose impostato su batch
- 3Crea un job batch facendo riferimento all'ID del file caricato
- 4Interroga lo stato del batch fino a quando raggiunge completed, failed o cancelled
- 5Scarica e analizza il file JSONL di output per estrarre i risultati
from openai import OpenAIimport jsonimport timeclient = OpenAI()# Step 1: Create the JSONL batch fileprompts = ["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 filebatch_file = client.files.create(file=open("batch_input.jsonl", "rb"),purpose="batch",)# Step 3: Create the batchbatch = 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 completionwhile True:status = client.batches.retrieve(batch.id)print(f"Status: {status.status}")if status.status in ("completed", "failed", "cancelled"):breaktime.sleep(60)# Step 5: Download resultsif 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 vs API in Tempo Reale
Capire quando usare la Batch API rispetto all'API standard in tempo reale ti aiuta a ottimizzare sia i costi che le prestazioni.
Per dettagli sul 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 e ispezionare i tuoi file JSONL batch prima di inviarli a OpenAI.