Tutoriel JSONL : créer, lire et convertir des fichiers JSONL
Un tutoriel pas à pas pour apprendre à manipuler les fichiers JSONL (JSON Lines), avec des exemples de code en Python et JavaScript et des outils en ligne de commande.
Qu'est-ce que JSONL ?
JSONL (JSON Lines) est un format texte léger dans lequel chaque ligne contient une valeur JSON distincte et valide. Contrairement au JSON standard, qui regroupe toutes les données dans un seul tableau ou objet, JSONL stocke un enregistrement par ligne, les enregistrements étant séparés par des caractères de retour à la ligne (\n).
Cette organisation ligne par ligne fait de JSONL un format idéal pour lire de grands jeux de données en streaming, ajouter des enregistrements sans réécrire le fichier et traiter les données en parallèle. Il est largement utilisé par OpenAI pour les jeux de données de fine-tuning, par les systèmes de journalisation comme la stack ELK et par les outils de big data tels que BigQuery et Apache Spark.
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}Comment créer des fichiers JSONL
Pour créer un fichier JSONL, il suffit de sérialiser chaque enregistrement en JSON sur une seule ligne, puis de l’écrire dans le fichier en le faisant suivre d’un retour à la ligne. Voici des exemples dans les langages les plus courants.
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`);À la main, dans un éditeur de texte
Vous pouvez aussi créer un fichier JSONL dans n’importe quel éditeur de texte. Saisissez un objet JSON valide par ligne, sans virgule entre les lignes, puis enregistrez le fichier avec l’extension .jsonl. Vérifiez que chaque ligne contient une valeur JSON complète et valide.
Comment lire des fichiers JSONL
Chaque ligne contenant une valeur JSON indépendante, il suffit de parcourir le fichier ligne par ligne pour le lire. Voici les méthodes les plus courantes.
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}`);
}# Afficher les 10 premières lignes
head -n 10 data.jsonl
# Compter le nombre total d'enregistrements
wc -l data.jsonl
# Afficher joliment chaque ligne avec jq
cat data.jsonl | jq .
# Filtrer les enregistrements où le rôle est "engineer"
cat data.jsonl | jq 'select(.role == "engineer")'
# Extraire uniquement le champ name
cat data.jsonl | jq -r '.name'
# Rechercher des lignes contenant un mot-clé
grep '"Alice"' data.jsonlComment convertir du JSON en JSONL
Pour convertir un tableau JSON standard en JSONL, il suffit d’écrire chaque élément sur une ligne distincte. C’est l’une des opérations les plus courantes avec JSONL.
import json
# Lire le tableau JSON
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f) # expects a JSON array
# Écrire en 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';
// Lire le tableau JSON
const data = JSON.parse(readFileSync('data.json', 'utf-8'));
// Écrire en 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`);Comment convertir du CSV en JSONL
La conversion de CSV en JSONL consiste à transformer chaque ligne en objet JSON, en reprenant les en-têtes du CSV comme noms de champs. Elle est utile pour migrer des données tabulaires vers un format adapté au streaming ou au 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');Bonnes pratiques pour JSONL
Utilisez l’encodage UTF-8 pour tous vos fichiers JSONL. Il garantit la compatibilité entre les plateformes et permet de représenter les caractères de toutes les langues.
Écrivez exactement un objet JSON par ligne. Ne répartissez jamais un objet sur plusieurs lignes et ne placez jamais plusieurs objets sur une même ligne.
N’ajoutez pas de virgules entre les lignes. Contrairement aux tableaux JSON, JSONL utilise uniquement le caractère de retour à la ligne comme séparateur.
Validez chaque ligne séparément. Chacune doit contenir une valeur JSON complète et valide. Utilisez un validateur JSONL pour repérer les erreurs de syntaxe au plus tôt.
Lisez les fichiers volumineux en streaming. Au lieu de charger tout le fichier en mémoire, traitez-le ligne par ligne avec readline (Node.js) ou en parcourant directement le fichier (Python).
Conservez une structure cohérente pour les enregistrements. JSONL autorise un schéma différent à chaque ligne, mais une structure uniforme simplifie considérablement le traitement des données.
Évitez les espaces en fin de ligne. Vérifiez qu’aucune ligne ne se termine par des espaces ou des tabulations superflus susceptibles de poser des problèmes lors de l’analyse.
Terminez le fichier par un retour à la ligne. Un retour à la ligne après le dernier enregistrement permet aux outils comme wc et cat de traiter correctement le fichier.
Erreurs courantes avec JSONL
[
{"name":"Alice"},
{"name":"Bob"}
]{"name":"Alice"}
{"name":"Bob"}Un fichier JSONL n’est pas un tableau JSON. N’entourez pas les lignes de crochets et n’ajoutez pas de virgules entre elles. Chaque ligne est indépendante.
{"name":"Alice"},
{"name":"Bob"},{"name":"Alice"}
{"name":"Bob"}Les virgules en fin de ligne ou entre les lignes ne sont pas autorisées en JSONL. Le caractère de retour à la ligne est le seul séparateur.
{
"name": "Alice",
"age": 30
}{"name":"Alice","age":30}Chaque objet JSON doit tenir sur une seule ligne. Du JSON mis en forme avec une indentation et des retours à la ligne n’est pas du JSONL valide.
{"text":"She said "hello""}{"text":"She said \"hello\""}Dans les chaînes JSON, les guillemets et les caractères spéciaux doivent être correctement échappés à l’aide de barres obliques inverses. Des guillemets non échappés provoquent une erreur d’analyse JSON.
Valider votre fichier JSONL
Une fois votre fichier JSONL créé, validez-le pour repérer les erreurs de syntaxe au plus tôt. Notre validateur gratuit vérifie chaque ligne instantanément.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Mettez en forme vos fichiers JSONL avec une indentation adaptée pour les rendre plus lisibles et faciliter le débogage et la revue des données.
Convertissez des tableaux JSON au format JSONL. Idéal pour préparer des données destinées au streaming et à l’entraînement de modèles de machine learning.
Exportez vos données JSONL dans des fichiers CSV pour les analyser dans Excel ou Google Sheets.
Un guide complet pour manipuler des fichiers JSONL en Python. Apprenez à lire, écrire et parser du JSONL avec json, pandas et orjson, et à utiliser le streaming pour les fichiers volumineux.