- Strona główna
- Przewodnik
- Poradnik JSONL: tworzenie, odczyt i konwersja plików JSONL
Poradnik JSONL: tworzenie, odczyt i konwersja plików JSONL
Poznaj krok po kroku wszystko, co musisz wiedzieć o pracy z plikami JSONL (JSON Lines). W poradniku znajdziesz przykłady kodu w Pythonie i JavaScripcie oraz polecenia narzędzi CLI.
Czym jest JSONL?
JSONL (JSON Lines) to lekki format tekstowy, w którym każda linia zawiera osobną, poprawną wartość JSON. W standardowym formacie JSON wszystkie dane są zapisane w jednej tablicy lub jednym obiekcie. JSONL przechowuje po jednym rekordzie w każdej linii, a rekordy rozdziela znakami nowej linii (\n).
Dzięki takiej strukturze JSONL świetnie nadaje się do strumieniowego przetwarzania dużych zbiorów danych, dopisywania rekordów bez ponownego zapisywania całego pliku oraz równoległego przetwarzania danych. Format ten jest powszechnie stosowany przez OpenAI do zbiorów danych używanych w fine-tuningu, w systemach zbierania logów, takich jak stos ELK, oraz w narzędziach big data, takich 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
Utworzenie pliku JSONL jest proste: serializuj każdy rekord do postaci JSON w jednej linii, a następnie zapisz go w pliku, dodając na końcu znak nowej linii. Poniżej znajdziesz przykłady w najpopularniejszych językach programowania.
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`);Ręcznie w edytorze tekstu
Plik JSONL możesz też utworzyć w dowolnym edytorze tekstu. Wpisz w każdej linii jeden poprawny obiekt JSON, bez przecinków między liniami, i zapisz plik z rozszerzeniem .jsonl. Upewnij się, że każda linia zawiera kompletną, poprawną wartość JSON.
Jak odczytywać pliki JSONL
Każda linia zawiera niezależną wartość JSON, więc odczyt pliku JSONL sprowadza się do iterowania po jego liniach. Poniżej znajdziesz najczęściej stosowane sposoby.
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}`);
}# Wyświetl pierwsze 10 linii
head -n 10 data.jsonl
# Policz wszystkie rekordy
wc -l data.jsonl
# Formatuj każdą linię z jq
cat data.jsonl | jq .
# Filtruj rekordy gdzie role to "engineer"
cat data.jsonl | jq 'select(.role == "engineer")'
# Wydobądź tylko pole name
cat data.jsonl | jq -r '.name'
# Szukaj linii zawierających słowo kluczowe
grep '"Alice"' data.jsonlJak przekonwertować JSON na JSONL
Jeśli masz zwykłą tablicę JSON, wystarczy zapisać każdy jej element w osobnej linii, aby otrzymać JSONL. To jedna z najczęstszych operacji przy pracy z tym formatem.
import json
# Odczytaj tablicę JSON
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f) # expects a JSON array
# Zapisz jako 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';
// Odczytaj tablicę JSON
const data = JSON.parse(readFileSync('data.json', 'utf-8'));
// Zapisz jako 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`);Jak przekonwertować CSV na JSONL
Podczas konwersji CSV na JSONL każdy wiersz staje się obiektem JSON, a nagłówki kolumn CSV służą jako nazwy pól. Przydaje się to przy przenoszeniu danych tabelarycznych do formatu odpowiedniego do przetwarzania strumieniowego lub uczenia maszynowego.
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');Dobre praktyki pracy z JSONL
Używaj kodowania UTF-8 we wszystkich plikach JSONL. Zapewnia ono zgodność między platformami i obsługę znaków z różnych języków.
Zapisuj dokładnie jeden obiekt JSON w każdej linii. Nigdy nie dziel obiektu na kilka linii ani nie umieszczaj kilku obiektów w jednej linii.
Nie dodawaj przecinków między liniami. W JSONL jedynym separatorem jest znak nowej linii, inaczej niż w tablicach JSON.
Waliduj każdą linię osobno. Każda musi zawierać kompletną, poprawną wartość JSON. Korzystaj z walidatora JSONL, aby wcześnie wychwytywać błędy składni.
Duże pliki odczytuj strumieniowo. Zamiast wczytywać cały plik do pamięci, przetwarzaj go linia po linii za pomocą readline (Node.js) lub iteracji po pliku (Python).
Dbaj o spójną strukturę rekordów. JSONL dopuszcza inny schemat w każdej linii, ale jednolita struktura znacznie ułatwia przetwarzanie danych.
Unikaj białych znaków na końcach linii. Sprawdź, czy nie ma tam zbędnych spacji lub tabulatorów, które mogłyby powodować problemy z parsowaniem.
Zakończ plik znakiem nowej linii. Znak nowej linii po ostatnim rekordzie ułatwia narzędziom takim jak wc i cat poprawną obsługę pliku.
Typowe błędy w plikach JSONL
[
{"name":"Alice"},
{"name":"Bob"}
]{"name":"Alice"}
{"name":"Bob"}JSONL nie jest tablicą JSON. Nie ujmuj rekordów w nawiasy kwadratowe ani nie dodawaj przecinków między liniami. Każda linia stanowi samodzielną całość.
{"name":"Alice"},
{"name":"Bob"},{"name":"Alice"}
{"name":"Bob"}W JSONL przecinki na końcach linii ani między liniami są niedozwolone. Jedynym separatorem jest znak nowej linii.
{
"name": "Alice",
"age": 30
}{"name":"Alice","age":30}Każdy obiekt JSON musi mieścić się w jednej linii. JSON sformatowany z wcięciami i podziałem na linie nie jest poprawnym JSONL.
{"text":"She said "hello""}{"text":"She said \"hello\""}Cudzysłowy i znaki specjalne wewnątrz ciągów znaków JSON wymagają odpowiednich sekwencji ucieczki z ukośnikiem wstecznym. Cudzysłowy zapisane bez takiej sekwencji spowodują błąd parsowania JSON.
Sprawdź poprawność pliku JSONL
Po utworzeniu pliku JSONL sprawdź jego poprawność, aby wcześnie wykryć błędy składni. Nasz bezpłatny walidator błyskawicznie sprawdza każdą linię.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Formatuj pliki JSONL, nadając im czytelny układ z odpowiednimi wcięciami. Ułatw sobie debugowanie i przeglądanie danych.
Konwertuj tablice JSON na JSONL. To idealny sposób na przygotowanie danych do przetwarzania strumieniowego i trenowania modeli ML.
Eksportuj dane JSONL do arkuszy CSV, aby wygodnie analizować je w Excelu lub Google Sheets.
Pełny przewodnik po pracy z plikami JSONL w Pythonie. Naucz się odczytywać, zapisywać i parsować JSONL przy użyciu json, pandas i orjson oraz przetwarzać duże pliki strumieniowo.