Guida al formato JSONL di OpenAI
Tutto quello che devi sapere sul formato JSONL usato da OpenAI per il fine-tuning dei modelli e per la Batch API: specifiche del formato, esempi di codice ed errori da evitare.
Cos'è il formato JSONL di OpenAI?
OpenAI usa JSONL (JSON Lines) come formato standard per i file dei dataset di fine-tuning e delle richieste alla Batch API. Ogni riga del file contiene un oggetto JSON completo e indipendente: gli oggetti non sono racchiusi in un array e non ci sono virgole tra una riga e l’altra.
Questo formato consente di leggere i dati in streaming in modo efficiente e di elaborarli riga per riga. Ogni esempio di addestramento o richiesta API può essere validato singolarmente, e i file possono essere elaborati senza caricare in memoria l’intero dataset.
È fondamentale rispettare tutti i requisiti del formato. Basta un piccolo errore, come una virgola di troppo dopo l’ultimo elemento o un campo mancante, perché l’intero file venga rifiutato.
Formato JSONL per il fine-tuning
Per il fine-tuning dei modelli di chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), ogni riga deve contenere un array "messages" con i messaggi della conversazione.
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}Campi obbligatori
- messages — Array di oggetti che rappresentano i messaggi (obbligatorio)
- role — Uno dei seguenti valori: "system", "user" o "assistant" (obbligatorio)
- content — Contenuto testuale del messaggio (obbligatorio)
Il messaggio di sistema è facoltativo, ma consigliato. Ogni conversazione deve contenere almeno un messaggio dell’utente e uno dell’assistente. Il messaggio dell’assistente è il testo che il modello impara a generare.
Formato JSONL per la Batch API
La Batch API usa un formato JSONL diverso: ogni riga contiene una richiesta API con un ID personalizzato.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, how are you?"}]}}
{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"What is the weather today?"}]}}Campi obbligatori
- custom_id — Identificatore univoco di ogni richiesta (obbligatorio)
- method — Metodo HTTP, di solito "POST" (obbligatorio)
- url — Percorso dell'endpoint API (obbligatorio)
- body — Corpo della richiesta, come in una normale chiamata API (obbligatorio)
Requisiti del formato
Perché OpenAI accetti il tuo file JSONL, segui queste regole:
- Ogni riga deve contenere JSON valido, senza errori di sintassi
- Ogni riga deve contenere un oggetto JSON (che inizia con { e termina con })
- Nei file per il fine-tuning, ogni riga deve contenere un array "messages"
- Ogni messaggio deve contenere entrambi i campi "role" e "content"
- I ruoli ammessi sono: "system", "user" e "assistant"
- Il file deve essere codificato in UTF-8 senza BOM (Byte Order Mark)
- Non sono ammesse virgole dopo l’ultimo elemento, commenti o spazi aggiuntivi tra le righe
- Le righe vuote sono ammesse e vengono ignorate
Errori comuni
Ecco gli errori più frequenti quando si creano file JSONL per OpenAI:
Usare un array JSON invece di JSONL
Non racchiudere tutti gli oggetti in [ ]. Un file JSONL deve contenere un oggetto per riga, senza un array che li racchiuda tutti.
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}Omettere campi obbligatori
Ogni messaggio deve contenere sia "role" sia "content". Se manca uno dei due campi, la validazione non va a buon fine.
{"messages":[{"role":"user"}]}{"messages":[{"role":"user","content":"Hello"}]}Inserire virgole dopo l’ultimo elemento
JSON non ammette virgole dopo l’ultimo elemento di un array o di un oggetto.
{"messages":[{"role":"user","content":"Hi",}]}{"messages":[{"role":"user","content":"Hi"}]}Usare una codifica errata o includere un BOM
Salva il file in UTF-8 senza BOM. Alcuni editor di testo aggiungono caratteri BOM invisibili che impediscono il parsing del JSON.
\uFEFF{"messages":[...]}{"messages":[...]}Esempi di codice
Ecco come generare file JSONL per OpenAI da codice:
import json
training_data = [
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is JSONL?"},
{"role": "assistant", "content": "JSONL (JSON Lines) is a text format where each line is a valid JSON object."}
]},
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "How do I fine-tune a model?"},
{"role": "assistant", "content": "Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API."}
]},
]
with open("training.jsonl", "w", encoding="utf-8") as f:
for entry in training_data:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
print(f"Created training.jsonl with {len(training_data)} examples")const fs = require('fs');
const trainingData = [
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is JSONL?' },
{ role: 'assistant', content: 'JSONL (JSON Lines) is a text format where each line is a valid JSON object.' },
]},
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'How do I fine-tune a model?' },
{ role: 'assistant', content: 'Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API.' },
]},
];
const jsonl = trainingData.map(d => JSON.stringify(d)).join('\n');
fs.writeFileSync('training.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created training.jsonl with ${trainingData.length} examples`);Strumenti e guide correlati
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Formatta i file JSONL con un’indentazione corretta per renderli più leggibili e facilitare il debug e la revisione dei dati.
Dividi file JSONL grandi in parti più piccole e gestibili per numero di righe.
Impara a strutturare i file JSONL per la Batch API di OpenAI. Formato delle richieste, parsing delle risposte e workflow completo con esempi di codice.
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.