Autor: Jerry Fan

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.

example.jsonl
{"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.

Python
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")
JavaScript / Node.js
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.

Python
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']}")
JavaScript / Node.js
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}`);
}
Wiersz poleceń (grep / jq)
# 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.jsonl

Jak 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.

Python
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")
JavaScript / Node.js
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`);

Skorzystaj z konwertera online

Nie chcesz pisać kodu? Skorzystaj z naszego bezpłatnego konwertera JSON na JSONL online — wklej dane lub prześlij plik i od razu otrzymaj wynik.

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.

Python
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")
JavaScript / Node.js
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');

Konwertuj CSV online

Błyskawicznie konwertuj pliki CSV na JSONL za pomocą naszego bezpłatnego narzędzia online — bez pisania kodu.

Dobre praktyki pracy z JSONL

1

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.

2

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.

3

Nie dodawaj przecinków między liniami. W JSONL jedynym separatorem jest znak nowej linii, inaczej niż w tablicach JSON.

4

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.

5

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).

6

Dbaj o spójną strukturę rekordów. JSONL dopuszcza inny schemat w każdej linii, ale jednolita struktura znacznie ułatwia przetwarzanie danych.

7

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.

8

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

Umieszczanie rekordów w tablicy
Źle
[
  {"name":"Alice"},
  {"name":"Bob"}
]
Dobrze
{"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ść.

Przecinki między liniami
Źle
{"name":"Alice"},
{"name":"Bob"},
Dobrze
{"name":"Alice"}
{"name":"Bob"}

W JSONL przecinki na końcach linii ani między liniami są niedozwolone. Jedynym separatorem jest znak nowej linii.

Obiekty JSON zapisane w kilku liniach
Źle
{
  "name": "Alice",
  "age": 30
}
Dobrze
{"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.

Znaki specjalne bez sekwencji ucieczki
Źle
{"text":"She said "hello""}
Dobrze
{"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.

Wypróbuj nasze bezpłatne narzędzia JSONL

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez przesyłania plików na serwer, ze 100% prywatnością.

Najczęściej zadawane pytania

Źródła