Przewodnik po formacie OpenAI JSONL
Wszystko, co musisz wiedzieć o formacie JSONL używanym przez OpenAI do fine-tuningu modeli i Batch API. Zawiera specyfikacje formatu, przykłady kodu i typowe pułapki.
Ostatnia aktualizacja: luty 2026
Czym jest format OpenAI JSONL?
OpenAI używa JSONL (JSON Lines) jako standardowego formatu plików do zbiorów danych fine-tuningowych i żądań Batch API. Każda linia w pliku jest kompletnym, niezależnym obiektem JSON — bez opakowującej tablicy, bez przecinków między liniami.
Ten format został wybrany, ponieważ umożliwia wydajne strumieniowanie i przetwarzanie linia po linii. Każdy przykład treningowy lub żądanie API może być walidowane niezależnie, a pliki mogą być przetwarzane bez ładowania całego zbioru danych do pamięci.
Zrozumienie dokładnych wymagań formatu jest kluczowe. Nawet małe błędy formatowania — jak końcowy przecinek lub brakujące pole — spowodują odrzucenie całego pliku.
Format JSONL do fine-tuningu
Do fine-tuningu modeli czatowych (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) każda linia musi zawierać tablicę "messages" z turami konwersacji.
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}
Wymagane pola
- messages — Tablica obiektów wiadomości (wymagane)
- role — Jedna z wartości: "system", "user" lub "assistant" (wymagane)
- content — Treść tekstowa wiadomości (wymagane)
Wiadomość systemowa jest opcjonalna, ale zalecana. Każda konwersacja musi mieć co najmniej jedną wiadomość użytkownika i jedną wiadomość asystenta. Wiadomość asystenta to to, czego model uczy się generować.
Format JSONL dla Batch API
Batch API używa innego formatu JSONL, w którym każda linia jest żądaniem API z własnym identyfikatorem.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, how are you?"}]}'}{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"What is the weather today?"}]}'}
Wymagane pola
- custom_id — Unikalny identyfikator każdego żądania (wymagane)
- method — Metoda HTTP, zazwyczaj "POST" (wymagane)
- url — Ścieżka endpointu API (wymagane)
- body — Treść żądania, taka sama jak w zwykłym wywołaniu API (wymagane)
Wymagania formatu
Przestrzegaj tych zasad, aby upewnić się, że Twój plik JSONL zostanie zaakceptowany przez OpenAI:
- Każda linia musi być prawidłowym JSON — żadne błędy składni nie są dozwolone
- Każda linia musi być obiektem JSON (zaczyna się od '{' i kończy na '}')
- Pliki fine-tuningowe muszą zawierać tablicę "messages" w każdej linii
- Każda wiadomość musi mieć oba pola "role" i "content"
- Prawidłowe role to: "system", "user" i "assistant"
- Plik musi być zakodowany w UTF-8 bez BOM (Byte Order Mark)
- Bez końcowych przecinków, komentarzy lub dodatkowych białych znaków między liniami
- Puste linie są dozwolone i będą ignorowane
Typowe błędy
Oto najczęstsze błędy przy tworzeniu plików OpenAI JSONL:
Użycie tablicy JSON zamiast JSONL
Błąd: opakowywanie wszystkich obiektów w [ ]. Pliki JSONL muszą mieć jeden obiekt na linię bez opakowującej tablicy.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Brakujące wymagane pola
Każda wiadomość musi mieć oba pola "role" i "content". Pominięcie któregokolwiek spowoduje niepowodzenie walidacji.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Końcowe przecinki w JSON
JSON nie pozwala na końcowe przecinki po ostatnim elemencie w tablicy lub obiekcie.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'Znaki BOM lub nieprawidłowe kodowanie
Zapisz plik jako UTF-8 bez BOM. Niektóre edytory tekstu dodają niewidoczne znaki BOM, które uniemożliwiają parsowanie JSON.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Przykłady kodu
Oto jak programowo tworzyć pliki OpenAI JSONL:
import jsontraining_data = [{"messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "What is JSONL?"},{"role": "assistant", "content": "JSONL (JSON Lines) is a text format where each line is a valid JSON object."}]},{"messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "How do I fine-tune a model?"},{"role": "assistant", "content": "Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API."}]},]with open("training.jsonl", "w", encoding="utf-8") as f:for entry in training_data:f.write(json.dumps(entry, ensure_ascii=False) + "\n")print(f"Created training.jsonl with {len(training_data)} examples")
const fs = require('fs');const trainingData = [{ messages: [{ role: 'system', content: 'You are a helpful assistant.' },{ role: 'user', content: 'What is JSONL?' },{ role: 'assistant', content: 'JSONL (JSON Lines) is a text format where each line is a valid JSON object.' },]},{ messages: [{ role: 'system', content: 'You are a helpful assistant.' },{ role: 'user', content: 'How do I fine-tune a model?' },{ role: 'assistant', content: 'Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API.' },]},];const jsonl = trainingData.map(d => JSON.stringify(d)).join('\n');fs.writeFileSync('training.jsonl', jsonl + '\n', 'utf-8');console.log(`Created training.jsonl with ${trainingData.length} examples`);