Tutorial JSONL: creare, leggere e convertire file JSONL
Un tutorial passo dopo passo con tutto ciò che ti serve per lavorare con i file JSONL (JSON Lines), con esempi di codice in Python e JavaScript e comandi da eseguire con gli strumenti CLI.
Cos'è JSONL?
JSONL (JSON Lines) è un formato di testo leggero in cui ogni riga contiene un valore JSON valido e indipendente. A differenza del JSON standard, che racchiude tutti i dati in un unico array o oggetto, JSONL memorizza un record per riga, usando il carattere di fine riga (\n) come separatore.
Questa struttura rende JSONL ideale per elaborare grandi dataset in streaming, aggiungere record senza riscrivere il file ed elaborare i dati in parallelo. È molto usato da OpenAI per i dataset di fine-tuning, dai sistemi di logging come lo stack ELK e dagli strumenti per i big data come BigQuery e Apache Spark.
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}Come creare file JSONL
Creare un file JSONL è semplice: serializza ogni record in una stringa JSON su una sola riga e scrivila nel file, seguita da un carattere di fine riga. Ecco alcuni esempi nei linguaggi più usati.
import json
records = [
{"id": 1, "name": "Alice", "role": "engineer"},
{"id": 2, "name": "Bob", "role": "designer"},
{"id": 3, "name": "Charlie", "role": "manager"},
]
with open("output.jsonl", "w", encoding="utf-8") as f:
for record in records:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print("Created output.jsonl with", len(records), "records")import { writeFileSync } from 'fs';
const records = [
{ id: 1, name: 'Alice', role: 'engineer' },
{ id: 2, name: 'Bob', role: 'designer' },
{ id: 3, name: 'Charlie', role: 'manager' },
];
const jsonl = records
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created output.jsonl with ${records.length} records`);Creazione manuale con un editor di testo
Puoi creare file JSONL anche con un qualsiasi editor di testo. Basta scrivere un oggetto JSON valido per riga, senza virgole tra una riga e l’altra, e salvare il file con estensione .jsonl. Assicurati che ogni riga contenga un valore JSON completo e valido.
Come leggere file JSONL
Ogni riga contiene un valore JSON indipendente: per leggere un file JSONL basta quindi scorrere le righe. Ecco gli approcci più comuni.
import json
with open("data.jsonl", "r", encoding="utf-8") as f:
for line_number, line in enumerate(f, 1):
line = line.strip()
if not line:
continue # skip empty lines
record = json.loads(line)
print(f"Line {line_number}: {record['name']} - {record['role']}")import { createReadStream } from 'fs';
import { createInterface } from 'readline';
const rl = createInterface({
input: createReadStream('data.jsonl', 'utf-8'),
});
let lineNumber = 0;
for await (const line of rl) {
if (!line.trim()) continue; // skip empty lines
lineNumber++;
const record = JSON.parse(line);
console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);
}# View first 10 lines
head -n 10 data.jsonl
# Count total records
wc -l data.jsonl
# Pretty-print each line with jq
cat data.jsonl | jq .
# Filter records where role is "engineer"
cat data.jsonl | jq 'select(.role == "engineer")'
# Extract only the name field
cat data.jsonl | jq -r '.name'
# Search for lines containing a keyword
grep '"Alice"' data.jsonlCome convertire JSON in JSONL
Per convertire un normale array JSON in JSONL, basta scrivere ogni elemento su una riga separata. È una delle operazioni più comuni quando lavori con JSONL.
import json
# Read JSON array
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f) # expects a JSON array
# Write as JSONL
with open("data.jsonl", "w", encoding="utf-8") as f:
for record in data:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print(f"Converted {len(data)} records from JSON to JSONL")import { readFileSync, writeFileSync } from 'fs';
// Read JSON array
const data = JSON.parse(readFileSync('data.json', 'utf-8'));
// Write as JSONL
const jsonl = data
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Converted ${data.length} records from JSON to JSONL`);Come convertire CSV in JSONL
La conversione da CSV a JSONL trasforma ogni riga in un oggetto JSON, usando le intestazioni del CSV come nomi dei campi. È utile per migrare dati tabulari verso un formato adatto allo streaming o al machine learning.
import csv
import json
with open("data.csv", "r", encoding="utf-8") as csv_file:
reader = csv.DictReader(csv_file)
with open("data.jsonl", "w", encoding="utf-8") as jsonl_file:
for row in reader:
jsonl_file.write(json.dumps(row, ensure_ascii=False) + "\n")
print("Converted CSV to JSONL successfully")import { readFileSync, writeFileSync } from 'fs';
const csv = readFileSync('data.csv', 'utf-8');
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');
const jsonl = lines.slice(1).map(line => {
const values = line.split(',');
const obj = {};
headers.forEach((h, i) => obj[h.trim()] = values[i]?.trim());
return JSON.stringify(obj);
}).join('\n');
writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log('Converted CSV to JSONL successfully');Buone pratiche per lavorare con JSONL
Usa la codifica UTF-8 per tutti i file JSONL: garantisce la compatibilità tra piattaforme e il supporto per i caratteri internazionali.
Scrivi esattamente un oggetto JSON per riga. Non distribuire mai un oggetto JSON su più righe e non inserire più oggetti nella stessa riga.
Non aggiungere virgole tra le righe. A differenza degli array JSON, JSONL usa il carattere di fine riga come unico delimitatore.
Valida ogni riga separatamente: deve contenere un valore JSON completo e valido. Usa un validatore JSONL per individuare subito gli errori di sintassi.
Leggi i file di grandi dimensioni in streaming. Anziché caricare tutto il file in memoria, elaboralo riga per riga con readline (Node.js) o iterando sulle righe del file (Python).
Mantieni una struttura coerente tra i record. JSONL consente di usare schemi diversi per ogni riga, ma una struttura uniforme semplifica molto l’elaborazione dei dati.
Evita spazi e tabulazioni a fine riga. Verifica che le righe non contengano spazi o tabulazioni superflui che potrebbero causare problemi di parsing.
Termina il file con un carattere di fine riga. Aggiungerlo dopo l’ultimo record aiuta strumenti come wc e cat a gestire correttamente il file.
Errori comuni con JSONL
[
{"name":"Alice"},
{"name":"Bob"}
]{"name":"Alice"}
{"name":"Bob"}JSONL non è un array JSON. Non racchiudere le righe tra parentesi quadre e non separarle con virgole: ogni riga è indipendente.
{"name":"Alice"},
{"name":"Bob"},{"name":"Alice"}
{"name":"Bob"}In JSONL non sono ammesse virgole alla fine delle righe o tra una riga e l’altra. L’unico separatore è il carattere di fine riga.
{
"name": "Alice",
"age": 30
}{"name":"Alice","age":30}Ogni oggetto JSON deve occupare una sola riga. Il JSON formattato con indentazione e interruzioni di riga non è JSONL valido.
{"text":"She said "hello""}{"text":"She said \"hello\""}Le virgolette e i caratteri speciali all’interno delle stringhe JSON richiedono l’escape con il backslash. Le virgolette senza escape causano un errore nel parser JSON.
Valida il tuo file JSONL
Dopo aver creato il file JSONL, validalo per individuare subito eventuali errori di sintassi. Il nostro validatore gratuito controlla ogni riga all’istante.
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.
Converti gli array JSON in formato JSONL. Ideale per preparare dati per lo streaming e l’addestramento di modelli di machine learning.
Esporta i dati JSONL in fogli di calcolo CSV. Ideale per le analisi in Excel o Google Sheets.
Una guida completa per lavorare con i file JSONL in Python. Impara a leggere, scrivere ed effettuare il parsing dei dati JSONL con json, pandas e orjson, e a usare lo streaming per i file di grandi dimensioni.