File di addestramento JSONL

Cos'è

Il JSON è il metodo più comune per scrivere dati strutturati in formato testuale: oggetti tra parentesi graffe, elenchi tra parentesi quadre, chiavi e valori tra virgolette. Il JSONL, noto anche come JSON Lines o newline-delimited JSON, aggiunge un'ulteriore regola: ogni riga del file rappresenta un valore JSON completo e valido, e le righe sono separate da un'interruzione di riga. Per i dati di addestramento, ogni valore è un oggetto che contiene un singolo esempio.

train.jsonl

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"How do I reset my password?"},{"role":"assistant","content":"Open Settings → Security…"}]}

{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello! How can I help?","weight":0},{"role":"user","content":"Export my report as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF…","weight":1}]}

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"Can I change my plan mid-month?"},{"role":"assistant","content":"Yes. The difference is prorated…"}]}

…una riga per record, nessuna virgola tra le righe, nessuna [ ] circostante

{ … }un oggetto JSON completo = un record di addestramento"messages"la conversazione, in ordine"role"chi lo ha detto: sistema, utente o assistente"weight"impara questa risposta (1) o leggila soltanto (0)\nun'interruzione di riga termina il record

Un file JSONL è una pila di oggetti JSON indipendenti, uno per riga. Ogni riga può essere letta, controllata, contata o mescolata singolarmente, motivo per cui ogni principale servizio di fine-tuning lo utilizza.

Perché l'addestramento lo utilizza

Streaming: un provider può leggere un file di svariati gigabyte una riga alla volta, anziché caricarlo e analizzarlo per intero.
Indipendenza: i record possono essere contati, mescolati, suddivisi in set di addestramento e validazione, o campionati senza dover analizzare il resto del file.
Errori chiari: un record malformato interrompe una sola riga e il messaggio di errore può indicarla con precisione (“line 482: unexpected end of input”).
Accodabile: aggiungere esempi significa aggiungere righe; nient'altro nel file subisce modifiche.

Le regole e come si corrompono i file

Le specifiche JSON Lines prevedono tre regole: il file è in formato UTF-8, ogni riga è un valore JSON valido e ogni riga termina con un carattere di avanzamento riga (line-feed). Si consiglia vivamente di terminare il file con un'interruzione di riga. Quasi tutti i file di addestramento danneggiati violano una di queste regole:

errori comuni in un file

✗ {"messages": [ ...          ← a pretty-printed object split over lines
     {"role": "user", ... } ]}
✗ [ {"messages": ...}, {"messages": ...} ]   ← a JSON array, not one object per line
✗ {"messages": [...]},        ← trailing comma
✗                             ← a blank line in the middle
✓ {"messages":[...]}          ← one complete object, then a line break

Le interruzioni di riga all'interno del testo di un messaggio sono ammesse, poiché il JSON le memorizza con sequenze di escape (una barra rovesciata seguita da n) all'interno della stringa. Ciò che non è consentito è un'interruzione di riga effettiva nel mezzo di un oggetto, che è esattamente ciò che accade quando si applica il “pretty-printing” a un file per migliorarne la leggibilità.

Stesso formato, strutture diverse

Tutti i principali servizi di fine-tuning supportano il formato JSONL, ma ciascuno definisce il proprio schema per il contenuto delle righe. Alcuni utilizzano un elenco messages con i ruoli system, user e assistant; altri inseriscono il prompt di sistema in un campo separato; altri ancora chiamano l'elenco contents e il ruolo dell'assistente model; alcuni supportano un parametro weight per ogni messaggio dell'assistente, in modo che le risposte precedenti fungano solo da contesto.

un esempio, tre formati di provider

// chat "messages" (with an optional weight per assistant reply)
{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello!","weight":0},{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF.","weight":1}]}

// "contents" with user / model roles
{"contents":[{"role":"user","parts":[{"text":"Export as PDF"}]},{"role":"model","parts":[{"text":"Open the report, click Export → PDF."}]}]}

// separate system field
{"system":"You are a support assistant.","messages":[{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF."}]}

Laddove un formato non preveda un peso per singolo messaggio, una conversazione a più turni con diversi target viene scritta come un record per target, ciascuno interrotto subito dopo la rispettiva risposta target. In questi record vengono apprese anche le risposte precedenti dell'assistente, poiché il formato non offre alcun modo per contrassegnarle esclusivamente come contesto.

Esempio pratico: una conversazione, due file

Una conversazione contiene quattro messaggi: “Hi”, un saluto, “Export my report as PDF” e le istruzioni. Solo le istruzioni sono contrassegnate come target.
Per un provider che supporta i pesi: una riga, con il saluto a weight: 0 e le istruzioni a weight: 1.
Per un provider senza pesi: anch'esso su una riga, che termina alle istruzioni. Se anche il saluto fosse stato un target, ci sarebbero state due righe — una terminante al saluto, una alle istruzioni — e il saluto sarebbe stato appreso due volte.
Entrambi i file contengono lo stesso testo ripulito e revisionato. Differisce solo la formattazione esterna.

Errori comuni

Formattare un file di addestramento con il pretty-printing, in modo che ogni oggetto occupi più righe.
Salvare un array JSON di record nominandolo .jsonl.
Modificare manualmente un file in uno strumento che altera la codifica o aggiunge virgolette intelligenti, compromettendo il JSON.
Riutilizzare il file di un provider con un altro provider: il formato è lo stesso, ma lo schema interno no.

Riferimenti e letture di approfondimento

Le fonti esterne si aprono in una nuova scheda.