- Strona główna
- Przewodnik
- JSONL jako format danych do trenowania AI
JSONL jako format danych do trenowania AI
Kompletny przewodnik po przygotowywaniu danych treningowych w formacie JSONL na potrzeby AI i uczenia maszynowego. Omawia fine-tuning modeli OpenAI, modele Anthropic Claude, zbiory danych HuggingFace, walidację danych oraz przetwarzanie danych na dużą skalę.
Dlaczego JSONL jest standardem w danych treningowych AI
JSONL (JSON Lines) stał się de facto standardem zapisu danych do trenowania AI i modeli uczenia maszynowego. Wszyscy główni dostawcy AI, od OpenAI przez Anthropic po HuggingFace, używają JSONL jako podstawowego formatu zbiorów danych do fine-tuningu. Powód jest prosty: JSONL zapisuje po jednym przykładzie w każdym wierszu. Dzięki temu łatwo odczytywać dane strumieniowo podczas treningu, losowo mieszać przykłady, liczyć rekordy, dzielić dane na zbiory treningowe i testowe oraz dopisywać nowe próbki bez ponownego zapisywania całego pliku.
Pojedynczą tablicę JSON trzeba w całości sparsować przed użyciem, natomiast pliki JSONL można przetwarzać wiersz po wierszu. Ma to znaczenie, gdy zbiory treningowe rozrastają się do milionów przykładów zajmujących gigabajty. W tym przewodniku poznasz szczegółowe wymagania dotyczące formatów JSONL używanych przez OpenAI, Anthropic Claude i HuggingFace. Dowiesz się też, jak walidować i czyścić dane oraz przygotowywać duże zbiory danych do treningu w środowisku produkcyjnym.
Format JSONL do fine-tuningu modeli OpenAI
OpenAI używa JSONL zarówno do fine-tuningu, jak i w Batch API. Przy fine-tuningu modeli czatowych, takich jak GPT-4o-mini, każdy wiersz musi zawierać tablicę messages o standardowej strukturze chat completion. Trzy role — system, user i assistant — opisują rozmowę, którą model ma nauczyć się odtwarzać.
Każdy wiersz to jeden przykład treningowy. Wiadomość systemowa określa zachowanie modelu, wiadomość użytkownika stanowi dane wejściowe, a wiadomość asystenta to oczekiwana odpowiedź, którą model ma nauczyć się generować.
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "Where is my order #12345?"}, {"role": "assistant", "content": "I can see that order #12345 was shipped on February 10th via FedEx. The tracking number is FX987654321. Based on the latest update, it should arrive by February 14th."}]}
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "I want to return my purchase."}, {"role": "assistant", "content": "I would be happy to help with your return. Could you please provide the order number and the reason for the return? Our return policy allows returns within 30 days of delivery for most items."}]}W przypadku rozmów z wieloma wymianami wiadomości uwzględnij pełną historię rozmowy. Model uczy się na podstawie każdej odpowiedzi asystenta w tablicy messages. W ten sposób uczysz go odpowiadać na kolejne pytania nawiązujące do wcześniejszych wiadomości.
{"messages": [{"role": "system", "content": "You are a Python programming tutor."}, {"role": "user", "content": "What is a list comprehension?"}, {"role": "assistant", "content": "A list comprehension is a concise way to create lists in Python. Instead of writing a for loop to build a list, you can write it in one line: [expression for item in iterable if condition]."}, {"role": "user", "content": "Can you show me an example?"}, {"role": "assistant", "content": "Sure! Here is an example that creates a list of squares for even numbers:\n\nsquares = [x**2 for x in range(10) if x % 2 == 0]\n# Result: [0, 4, 16, 36, 64]\n\nThis is equivalent to:\nsquares = []\nfor x in range(10):\n if x % 2 == 0:\n squares.append(x**2)"}]}OpenAI wymaga co najmniej 10 przykładów treningowych, ale zaleca 50-100, aby uzyskać zauważalną poprawę. Wszystkie wiadomości muszą zawierać pola role i content. Wiadomość systemowa jest opcjonalna, ale warto ją dodać, by zapewnić spójne zachowanie modelu. Przed przesłaniem pliku zwaliduj go za pomocą CLI OpenAI: openai tools fine_tunes.prepare_data -f training.jsonl
Format danych treningowych dla modeli Anthropic Claude
Anthropic używa JSONL do fine-tuningu modeli Claude. Format opisuje uporządkowaną rozmowę z wypowiedziami human i assistant. Szczegóły zależą od metody fine-tuningu i wersji API, ale podstawowy układ odpowiada strukturze Messages API.
Każdy wiersz zawiera rozmowę z promptem systemowym oraz naprzemiennymi wiadomościami użytkownika i asystenta. Model uczy się generować odpowiedzi asystenta na podstawie kontekstu rozmowy.
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "What are the symptoms of vitamin D deficiency?"}, {"role": "assistant", "content": "Common symptoms of vitamin D deficiency include fatigue and tiredness, bone pain and muscle weakness, mood changes including depression, slow wound healing, and frequent infections. However, many people with mild deficiency may not notice symptoms. A blood test is the only way to confirm your vitamin D levels. I recommend speaking with your doctor who can order the appropriate test and recommend supplementation if needed."}]}
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "Is it safe to take ibuprofen daily?"}, {"role": "assistant", "content": "Taking ibuprofen daily for extended periods can carry risks including stomach ulcers and gastrointestinal bleeding, increased risk of heart attack and stroke, kidney problems with long-term use, and potential interactions with other medications. For occasional pain relief, short-term use at recommended doses is generally considered safe for most adults. However, if you find yourself needing daily pain relief, please consult your doctor. They can evaluate the underlying cause and recommend a safer long-term treatment plan."}]}W danych treningowych obejmujących wiele wymian wiadomości uwzględnij całą rozmowę z naprzemiennymi wiadomościami użytkownika i asystenta. Model uczy się w ten sposób prowadzić rozmowę i zachowywać kontekst między kolejnymi wypowiedziami.
{"system": "You are a cooking assistant specializing in Italian cuisine.", "messages": [{"role": "user", "content": "How do I make carbonara?"}, {"role": "assistant", "content": "Authentic carbonara uses just five ingredients: spaghetti, guanciale (cured pork cheek), eggs, Pecorino Romano cheese, and black pepper. The key technique is tempering the egg mixture with the hot pasta water so it creates a creamy sauce without scrambling."}, {"role": "user", "content": "Can I use bacon instead of guanciale?"}, {"role": "assistant", "content": "While guanciale gives the most authentic flavor, pancetta is a closer substitute. Bacon works in a pinch but its smoky flavor changes the dish significantly. If using bacon, choose an unsmoked variety. Whichever you use, cut it into small pieces and render the fat slowly over medium-low heat until crispy."}]}Zbiory danych HuggingFace w formacie JSONL
Biblioteka datasets od HuggingFace ma wbudowaną obsługę JSONL jako formatu wejściowego. Możesz wczytywać lokalne pliki JSONL, odczytywać zdalne zbiory danych strumieniowo i łatwo konwertować dane między formatami. JSONL to zalecany format udostępniania zbiorów danych w HuggingFace Hub.
Użyj biblioteki datasets, aby wczytać pliki JSONL do obiektu Dataset. Zapewnia on wydajny dostęp do danych dzięki mapowaniu plików do pamięci, wbudowany podział na zbiory treningowe i testowe oraz łatwą integrację z Trainer API.
from datasets import load_dataset
# Load a local JSONL file
dataset = load_dataset('json', data_files='training.jsonl')
print(dataset)
# DatasetDict({
# train: Dataset({
# features: ['messages', 'system'],
# num_rows: 5000
# })
# })
# Load with train/test split
dataset = load_dataset('json', data_files={
'train': 'train.jsonl',
'test': 'test.jsonl'
})
# Stream a large remote dataset
dataset = load_dataset(
'json',
data_files='https://example.com/large_dataset.jsonl',
streaming=True
)
for example in dataset['train']:
print(example)
breakPrzekonwertuj dowolny zbiór danych HuggingFace do formatu JSONL, aby wykorzystać go w innych pipeline’ach treningowych. Metoda to_json zapisuje każdy przykład jako osobny wiersz JSON.
from datasets import load_dataset
# Load a dataset from the Hub
dataset = load_dataset('squad', split='train')
# Export to JSONL
dataset.to_json('squad_train.jsonl')
print(f'Exported {len(dataset)} examples')
# Export with specific columns
dataset.select_columns(['question', 'context', 'answers']).to_json(
'squad_filtered.jsonl'
)
# Process and export
def format_for_finetuning(example):
return {
'messages': [
{'role': 'user', 'content': example['question']},
{'role': 'assistant', 'content': example['answers']['text'][0]}
]
}
formatted = dataset.map(format_for_finetuning, remove_columns=dataset.column_names)
formatted.to_json('squad_chat_format.jsonl')Walidacja i czyszczenie danych
Jakość danych treningowych bezpośrednio wpływa na wyniki modelu. Niepoprawny JSON, brakujące pola, zbyt długie przykłady i duplikaty mogą pogorszyć efekty fine-tuningu. Zawsze waliduj i czyść pliki JSONL przed rozpoczęciem treningu.
Ten skrypt sprawdza każdy wiersz pliku JSONL pod kątem typowych problemów: niepoprawnego JSON, brakujących wymaganych pól, pustej treści i długości przykładów w tokenach. Uruchom go przed przesłaniem pliku, aby zawczasu wykryć problemy.
import json
import sys
from collections import Counter
def validate_training_data(path: str) -> dict:
"""Validate a JSONL file for AI fine-tuning."""
stats = Counter()
errors = []
with open(path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
stats['total'] += 1
# Check valid JSON
try:
data = json.loads(line)
except json.JSONDecodeError as e:
errors.append(f'Line {line_num}: Invalid JSON - {e}')
stats['invalid_json'] += 1
continue
# Check messages field exists
if 'messages' not in data:
errors.append(f'Line {line_num}: Missing "messages" field')
stats['missing_messages'] += 1
continue
messages = data['messages']
# Check message structure
for i, msg in enumerate(messages):
if 'role' not in msg:
errors.append(f'Line {line_num}, msg {i}: Missing "role"')
stats['missing_role'] += 1
if 'content' not in msg:
errors.append(f'Line {line_num}, msg {i}: Missing "content"')
stats['missing_content'] += 1
elif not msg['content'].strip():
errors.append(f'Line {line_num}, msg {i}: Empty content')
stats['empty_content'] += 1
# Check has at least one assistant message
roles = [m.get('role') for m in messages]
if 'assistant' not in roles:
errors.append(f'Line {line_num}: No assistant message')
stats['no_assistant'] += 1
stats['valid'] += 1
return {'stats': dict(stats), 'errors': errors[:50]}
result = validate_training_data('training.jsonl')
print(f"Total: {result['stats'].get('total', 0)}")
print(f"Valid: {result['stats'].get('valid', 0)}")
if result['errors']:
print(f"\nFirst {len(result['errors'])} errors:")
for err in result['errors']:
print(f' {err}')Powtarzające się przykłady treningowe marnują zasoby obliczeniowe i mogą sprawić, że model będzie nadmiernie preferował zbyt często występujące wzorce. Ten skrypt usuwa identyczne duplikaty na podstawie hasha zawartości każdego wiersza.
import json
import hashlib
def deduplicate_jsonl(input_path: str, output_path: str) -> dict:
"""Remove duplicate training examples from a JSONL file."""
seen_hashes = set()
total = 0
unique = 0
with open(input_path, 'r') as fin, open(output_path, 'w') as fout:
for line in fin:
line = line.strip()
if not line:
continue
total += 1
# Hash the normalized JSON to catch formatting differences
data = json.loads(line)
canonical = json.dumps(data, sort_keys=True)
content_hash = hashlib.sha256(canonical.encode()).hexdigest()
if content_hash not in seen_hashes:
seen_hashes.add(content_hash)
fout.write(json.dumps(data) + '\n')
unique += 1
duplicates = total - unique
print(f'Total: {total}, Unique: {unique}, Removed: {duplicates}')
return {'total': total, 'unique': unique, 'duplicates': duplicates}
deduplicate_jsonl('training.jsonl', 'training_deduped.jsonl')Przygotowywanie danych na dużą skalę
Zbiory danych wykorzystywane do treningu w środowisku produkcyjnym często zawierają setki tysięcy lub miliony przykładów. Przy takiej skali potrzebujesz zautomatyzowanych pipeline’ów do losowego mieszania danych JSONL, dzielenia ich na zbiory i rozdzielania na mniejsze pliki. Właściwe przygotowanie zapobiega problemom podczas treningu, takim jak katastrofalne zapominanie, i zapewnia powtarzalność eksperymentów.
Ten skrypt losowo miesza dane i dzieli je na zbiór treningowy i testowy. Mieszanie jest kluczowe, ponieważ pliki JSONL często powstają w określonej kolejności, a trening na tak uporządkowanych danych może osłabić zdolność modelu do uogólniania.
import json
import random
from pathlib import Path
def prepare_training_data(
input_path: str,
output_dir: str,
test_ratio: float = 0.1,
seed: int = 42
) -> dict:
"""Shuffle and split JSONL into train/test sets."""
random.seed(seed)
output = Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
# Load all examples
examples = []
with open(input_path, 'r') as f:
for line in f:
line = line.strip()
if line:
examples.append(json.loads(line))
# Shuffle
random.shuffle(examples)
# Split
split_idx = int(len(examples) * (1 - test_ratio))
train_data = examples[:split_idx]
test_data = examples[split_idx:]
# Write output files
train_path = output / 'train.jsonl'
test_path = output / 'test.jsonl'
for data, path in [(train_data, train_path), (test_data, test_path)]:
with open(path, 'w') as f:
for example in data:
f.write(json.dumps(example) + '\n')
print(f'Train: {len(train_data)} examples -> {train_path}')
print(f'Test: {len(test_data)} examples -> {test_path}')
return {'train': len(train_data), 'test': len(test_data)}
prepare_training_data(
'all_examples.jsonl',
'./prepared_data/',
test_ratio=0.1,
seed=42
)Gdy zbiór danych jest zbyt duży, by przechowywać go w jednym pliku, lub chcesz rozłożyć trening na wiele GPU, podziel plik JSONL na mniejsze części. Każdą z nich można przetwarzać niezależnie.
import json
from pathlib import Path
def shard_jsonl(
input_path: str,
output_dir: str,
shard_size: int = 50000
) -> int:
"""Split a large JSONL file into smaller shards."""
output = Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
shard_num = 0
line_count = 0
current_file = None
with open(input_path, 'r') as fin:
for line in fin:
line = line.strip()
if not line:
continue
if line_count % shard_size == 0:
if current_file:
current_file.close()
shard_path = output / f'shard_{shard_num:04d}.jsonl'
current_file = open(shard_path, 'w')
shard_num += 1
current_file.write(line + '\n')
line_count += 1
if current_file:
current_file.close()
print(f'Created {shard_num} shards from {line_count} examples')
return shard_num
shard_jsonl('large_dataset.jsonl', './shards/', shard_size=50000)Sprawdź poprawność danych treningowych online
Skorzystaj z naszych bezpłatnych narzędzi działających w przeglądarce, aby zwalidować, sformatować i przekonwertować dane treningowe JSONL przed przesłaniem ich do OpenAI, Anthropic lub HuggingFace.
Pełny przewodnik po przygotowywaniu plików JSONL dla OpenAI. Poznaj format danych do fine-tuningu, żądania Batch API, typowe błędy i wskazówki dotyczące walidacji.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Podziel duze pliki JSONL na mniejsze, latwiejsze do zarzadzania czesci wedlug liczby wierszy.
Konwertuj arkusze CSV na JSONL. Przydatne przy migracji danych i przetwarzaniu wsadowym.
Poznaj dobre praktyki pracy z JSONL: formatowanie, spójność schematu, obsługę błędów, optymalizację wydajności i organizację plików. Praktyczne przykłady pomogą Ci uniknąć typowych pułapek.