Samouczek JSONL: Tworzenie, odczyt i konwersja plików JSONL
Samouczek krok po kroku obejmujący wszystko, co musisz wiedzieć o pracy z plikami JSONL (JSON Lines). Zawiera przykłady kodu w Python, JavaScript i narzędziach CLI.
Ostatnia aktualizacja: luty 2026
Czym jest JSONL?
JSONL (JSON Lines) to lekki format tekstowy, w którym każda linia jest osobną, prawidłową wartością JSON. W przeciwieństwie do standardowego JSON, który zawija wszystkie dane w jedną tablicę lub obiekt, JSONL przechowuje jeden rekord na linię, oddzielony znakami nowej linii (\n).
Ta struktura linia po linii sprawia, że JSONL jest idealny do strumieniowania dużych zbiorów danych, dodawania rekordów bez przepisywania pliku i przetwarzania danych równolegle. Jest szeroko stosowany przez OpenAI do zbiorów danych do dostrajania, przez systemy logowania takie jak stos ELK oraz przez narzędzia big data takie jak BigQuery i Apache Spark.
{"id":1,"name":"Alice","role":"engineer"}{"id":2,"name":"Bob","role":"designer"}{"id":3,"name":"Charlie","role":"manager"}
Jak tworzyć pliki JSONL
Tworzenie pliku JSONL jest proste: serializuj każdy rekord jako ciąg JSON w jednej linii i zapisz go z następującym znakiem nowej linii. Oto przykłady w najpopularniejszych językach.
import jsonrecords = [{"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`);
Ręcznie / Edytor tekstu
Możesz również tworzyć pliki JSONL w dowolnym edytorze tekstu. Po prostu wpisz jeden prawidłowy obiekt JSON na linię bez przecinków między liniami i zapisz plik z rozszerzeniem .jsonl. Upewnij się, że każda linia jest kompletna i zawiera prawidłowy JSON.
Jak odczytywać pliki JSONL
Ponieważ każda linia jest niezależną wartością JSON, odczytywanie plików JSONL jest tak proste jak iterowanie po liniach. Oto najpopularniejsze podejścia.
import jsonwith 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 linesrecord = 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 lineslineNumber++;const record = JSON.parse(line);console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);}
# Wyświetl pierwsze 10 liniihead -n 10 data.jsonl# Policz wszystkie rekordywc -l data.jsonl# Formatuj każdą linię z jqcat data.jsonl | jq .# Filtruj rekordy gdzie role to "engineer"cat data.jsonl | jq 'select(.role == "engineer")'# Wydobądź tylko pole namecat data.jsonl | jq -r '.name'# Szukaj linii zawierających słowo kluczowegrep '"Alice"' data.jsonl
Jak konwertować JSON do JSONL
Jeśli masz standardową tablicę JSON, konwersja do JSONL polega na zapisaniu każdego elementu jako osobnej linii. To jedna z najczęstszych operacji JSONL.
import json# Odczytaj tablicę JSONwith open("data.json", "r", encoding="utf-8") as f:data = json.load(f) # expects a JSON array# Zapisz jako JSONLwith 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';// Odczytaj tablicę JSONconst data = JSON.parse(readFileSync('data.json', 'utf-8'));// Zapisz jako JSONLconst 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`);
Jak konwertować CSV do JSONL
Konwersja CSV do JSONL mapuje każdy wiersz na obiekt JSON, używając nagłówka CSV jako nazw pól. Jest to przydatne przy migracji danych tabelarycznych do formatu odpowiedniego dla strumieniowania lub uczenia maszynowego.
import csvimport jsonwith 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');
Najlepsze praktyki JSONL
Używaj kodowania UTF-8 dla wszystkich plików JSONL. Zapewnia to kompatybilność między platformami i obsługę znaków międzynarodowych.
Zapisuj dokładnie jeden obiekt JSON na linię. Nigdy nie dziel obiektu JSON na wiele linii ani nie umieszczaj wielu obiektów w tej samej linii.
Nie dodawaj przecinków między liniami. W przeciwieństwie do tablic JSON, JSONL używa znaków nowej linii jako jedynego separatora.
Waliduj każdą linię niezależnie. Każda linia musi być kompletną, parsowalną wartością JSON. Używaj walidatora JSONL, aby wcześnie wychwycić błędy składni.
Używaj strumieniowego odczytu dla dużych plików. Zamiast ładować cały plik do pamięci, przetwarzaj go linia po linii używając readline (Node.js) lub iteracji pliku (Python).
Utrzymuj spójną strukturę rekordów. Chociaż JSONL pozwala na różne schematy w każdej linii, utrzymanie jednolitej struktury znacznie ułatwia przetwarzanie danych.
Unikaj końcowych białych znaków. Upewnij się, że linie nie mają dodatkowych spacji lub tabulatorów, które mogą powodować problemy z parsowaniem.
Kończ plik znakiem nowej linii. Końcowy znak nowej linii po ostatnim rekordzie pomaga narzędziom takim jak wc i cat poprawnie obsłużyć plik.
Typowe błędy JSONL
[
{"name":"Alice"},
{"name":"Bob"}
]{"name":"Alice"}
{"name":"Bob"}JSONL nie jest tablicą JSON. Nie owijaj linii w nawiasy kwadratowe ani nie dodawaj między nimi przecinków. Każda linia stoi samodzielnie.
{"name":"Alice"},
{"name":"Bob"},{"name":"Alice"}
{"name":"Bob"}Końcowe przecinki po każdej linii lub przecinki między liniami są nieprawidłowe w JSONL. Znak nowej linii jest jedynym separatorem.
{
"name": "Alice",
"age": 30
}{"name":"Alice","age":30}Każdy obiekt JSON musi zmieścić się w jednej linii. Czytelnie sformatowany JSON z wcięciami i przerwami linii nie jest prawidłowym JSONL.
{"text":"She said "hello""}{"text":"She said \"hello\""}Cudzysłowy i znaki specjalne wewnątrz ciągów JSON muszą być prawidłowo ucieczkowane ukośnikami wstecznymi. Nieucieczkowione cudzysłowy złamią parser JSON.