Di Jerry Fan

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.

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.

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.
Struttura di base di una richiesta
{"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.

Richiesta singola
{"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.

File JSONL con più richieste
{"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.

Formato delle richieste di embedding
{"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.

Risposta a una richiesta riuscita
{"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.

Risposta di errore
{"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.

  1. 1Crea un file JSONL con una richiesta per riga
  2. 2Carica il file tramite la Files API, impostando purpose su batch
  3. 3Crea un job batch specificando l'ID del file caricato
  4. 4Controlla periodicamente lo stato del batch finché non passa a completed, failed o cancelled
  5. 5Scarica il file JSONL di output ed eseguine il parsing per estrarre i risultati
Procedura completa per usare la Batch API
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.

Caratteristica
Batch API
API in tempo reale
Costo
Sconto del 50%
Tariffe standard
Latenza
Fino a 24 ore
Secondi
Limiti di frequenza
Limiti più elevati
Limiti standard
Formato di input
Caricamento di un file JSONL
Singole chiamate API
Ideale per
Elaborazione in blocco, valutazione, generazione di dati
App interattive, chat in tempo reale, streaming

Per approfondire il formato JSONL per il fine-tuning di OpenAI, consulta la nostra Guida al formato JSONL di OpenAI.

Lavora con i file JSONL online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Non devi caricare alcun file: i tuoi dati restano privati al 100%.

Domande frequenti

Riferimenti