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