Guida al formato JSONL di OpenAI
Tutto quello che devi sapere sul formato JSONL utilizzato da OpenAI per il fine-tuning dei modelli e la Batch API. Include specifiche del formato, esempi di codice e insidie comuni.
Ultimo aggiornamento: febbraio 2026
Cos'è il formato JSONL di OpenAI?
OpenAI utilizza JSONL (JSON Lines) come formato file standard per i dataset di fine-tuning e le richieste della Batch API. Ogni riga del file è un oggetto JSON completo e indipendente — nessun array di contenimento, nessuna virgola tra le righe.
Questo formato è stato scelto perché consente uno streaming efficiente e l'elaborazione riga per riga. Ogni esempio di addestramento o richiesta API può essere validato indipendentemente, e i file possono essere elaborati senza caricare l'intero dataset in memoria.
Comprendere i requisiti esatti del formato è fondamentale. Anche piccoli errori di formattazione — come una virgola finale o un campo mancante — causeranno il rifiuto dell'intero file.
Formato JSONL per il fine-tuning
Per il fine-tuning dei modelli chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), ogni riga deve contenere un array "messages" con i turni 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 messaggio (obbligatorio)
- role — Uno tra: "system", "user" o "assistant" (obbligatorio)
- content — Il contenuto testuale del messaggio (obbligatorio)
Il messaggio di sistema è opzionale ma consigliato. Ogni conversazione deve avere almeno un messaggio utente e un messaggio assistente. Il messaggio dell'assistente è ciò che il modello impara a generare.
Formato JSONL per la Batch API
La Batch API utilizza un formato JSONL diverso in cui ogni riga è 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 — Un identificatore univoco per ogni richiesta (obbligatorio)
- method — Metodo HTTP, tipicamente "POST" (obbligatorio)
- url — Percorso dell'endpoint API (obbligatorio)
- body — Il corpo della richiesta, uguale a una chiamata API regolare (obbligatorio)
Requisiti del formato
Segui queste regole per assicurarti che il tuo file JSONL venga accettato da OpenAI:
- Ogni riga deve essere JSON valido — nessun errore di sintassi consentito
- Ogni riga deve essere un oggetto JSON (inizia con '{' e termina con '}')
- I file di fine-tuning devono includere un array "messages" in ogni riga
- Ogni messaggio deve avere sia il campo "role" che il campo "content"
- I ruoli validi sono: "system", "user" e "assistant"
- Il file deve essere codificato in UTF-8 senza BOM (Byte Order Mark)
- Nessuna virgola finale, commenti o spazi extra tra le righe
- Le righe vuote sono consentite e verranno ignorate
Errori comuni
Questi sono gli errori più frequenti nella creazione di file JSONL per OpenAI:
Usare un array JSON invece di JSONL
Sbagliato: racchiudere tutti gli oggetti in [ ]. I file JSONL devono avere un oggetto per riga senza array di contenimento.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Campi obbligatori mancanti
Ogni messaggio deve avere sia "role" che "content". Omettere uno dei due causerà il fallimento della validazione.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Virgole finali nel JSON
JSON non consente virgole finali dopo l'ultimo elemento in un array o oggetto.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'Caratteri BOM o codifica errata
Salva il tuo file come UTF-8 senza BOM. Alcuni editor di testo aggiungono caratteri BOM invisibili che interrompono l'analisi JSON.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Esempi di codice
Ecco come creare file JSONL per OpenAI in modo programmatico:
import jsontraining_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`);