Di Jerry Fan

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.

Valida il tuo file JSONL

Prima di caricare il file su OpenAI, controllalo con il nostro validatore gratuito. Seleziona «Formato di fine-tuning di OpenAI» per verificare i messaggi, i ruoli e le risposte di assistant in ogni riga, oltre alla sintassi JSON.

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.

Formato richiesto
{"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.

Formato richiesto
{"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.

Sbagliato
[{"messages":[...]}, {"messages":[...]}]
Corretto
{"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.

Sbagliato
{"messages":[{"role":"user"}]}
Corretto
{"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.

Sbagliato
{"messages":[{"role":"user","content":"Hi",}]}
Corretto
{"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.

Sbagliato
\uFEFF{"messages":[...]}
Corretto
{"messages":[...]}

Esempi di codice

Ecco come generare file JSONL per OpenAI da codice:

Python — Creare un file JSONL per il fine-tuning
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")
JavaScript — Creare un file JSONL per il fine-tuning
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`);

Visualizza e modifica file JSONL di OpenAI

Usa il nostro visualizzatore JSONL online gratuito per esaminare i dataset di fine-tuning e i file della Batch API, con vista affiancata, evidenziazione della sintassi e validazione in tempo reale.

Domande frequenti

Riferimenti