Autor: Jerry Fan

Przewodnik po formacie JSONL w OpenAI

Wszystko, co musisz wiedzieć o formacie JSONL używanym przez OpenAI do fine-tuningu modeli i obsługi Batch API: specyfikacja formatu, przykłady kodu i typowe pułapki.

Czym jest format JSONL używany przez OpenAI?

OpenAI używa JSONL (JSON Lines) jako standardowego formatu plików ze zbiorami danych do fine-tuningu oraz żądaniami do Batch API. Każdy wiersz pliku zawiera kompletny, niezależny obiekt JSON — bez nadrzędnej tablicy i bez przecinków między wierszami.

Ten format pozwala wydajnie przesyłać dane strumieniowo i przetwarzać je wiersz po wierszu. Każdy przykład treningowy lub żądanie do API można zweryfikować niezależnie, a pliki można przetwarzać bez wczytywania całego zbioru danych do pamięci.

Trzeba dokładnie znać wymagania dotyczące formatu. Nawet drobne błędy formatowania — takie jak nadmiarowy przecinek na końcu lub brak wymaganego pola — spowodują odrzucenie całego pliku.

Sprawdź poprawność pliku JSONL

Przed przesłaniem pliku do OpenAI sprawdź go w naszym bezpłatnym walidatorze. Wybierz format fine-tuningu OpenAI, aby sprawdzić wiadomości, role i odpowiedzi assistant w każdej linii, a także składnię JSON.

Format JSONL do fine-tuningu

W plikach do fine-tuningu modeli czatowych (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) każdy wiersz musi zawierać tablicę "messages" z kolejnymi wiadomościami rozmowy.

Wymagany format
{"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 (pole wymagane)
  • role — jedna z wartości: "system", "user" lub "assistant" (pole wymagane)
  • content — tekstowa treść wiadomości (pole wymagane)

Wiadomość systemowa jest opcjonalna, ale zalecana. Każda rozmowa musi zawierać co najmniej jedną wiadomość użytkownika i jedną wiadomość asystenta. Model uczy się generować wiadomości asystenta.

Format JSONL dla Batch API

Batch API korzysta z innego formatu JSONL: każdy wiersz zawiera żądanie do API z własnym identyfikatorem.

Wymagany format
{"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 (pole wymagane)
  • method — metoda HTTP, zwykle "POST" (pole wymagane)
  • url — ścieżka endpointu API (pole wymagane)
  • body — treść żądania, taka sama jak w zwykłym wywołaniu API (pole wymagane)

Wymagania dotyczące formatu

Aby OpenAI zaakceptowało Twój plik JSONL, przestrzegaj następujących zasad:

  • Każdy wiersz musi zawierać poprawny JSON — błędy składni są niedopuszczalne
  • Każdy wiersz musi zawierać obiekt JSON (zaczynający się od { i kończący się na })
  • W plikach do fine-tuningu każdy wiersz musi zawierać tablicę "messages"
  • Każda wiadomość musi zawierać oba pola: "role" i "content"
  • Dozwolone role to: "system", "user" i "assistant"
  • Plik musi mieć kodowanie UTF-8 bez BOM (Byte Order Mark)
  • Nie używaj przecinków po ostatnim elemencie, komentarzy ani dodatkowych białych znaków między wierszami
  • Puste wiersze są dozwolone i będą ignorowane

Typowe błędy

Oto najczęstsze błędy popełniane podczas tworzenia plików JSONL dla OpenAI:

Użycie tablicy JSON zamiast JSONL

Błąd: umieszczenie wszystkich obiektów w [ ]. W pliku JSONL każdy wiersz musi zawierać jeden obiekt, bez nadrzędnej tablicy.

Źle
[{"messages":[...]}, {"messages":[...]}]
Dobrze
{"messages":[...]}
{"messages":[...]}

Brak wymaganych pól

Każda wiadomość musi zawierać oba pola: "role" i "content". Jeśli zabraknie któregokolwiek z nich, walidacja zakończy się błędem.

Źle
{"messages":[{"role":"user"}]}
Dobrze
{"messages":[{"role":"user","content":"Hello"}]}

Przecinki po ostatnim elemencie w JSON

JSON nie dopuszcza przecinka po ostatnim elemencie tablicy lub obiektu.

Źle
{"messages":[{"role":"user","content":"Hi",}]}
Dobrze
{"messages":[{"role":"user","content":"Hi"}]}

Znaki BOM lub nieprawidłowe kodowanie

Zapisz plik w kodowaniu UTF-8 bez BOM. Niektóre edytory tekstu dodają niewidoczne znaki BOM, które uniemożliwiają parsowanie JSON.

Źle
\uFEFF{"messages":[...]}
Dobrze
{"messages":[...]}

Przykłady kodu

Tak możesz tworzyć pliki JSONL dla OpenAI w kodzie:

Python — tworzenie pliku JSONL do fine-tuningu
import json


training_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")
JavaScript — tworzenie pliku JSONL do fine-tuningu
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`);

Przeglądaj i edytuj pliki JSONL dla OpenAI

Korzystaj z naszej bezpłatnej przeglądarki JSONL online, aby przeglądać zbiory danych do fine-tuningu i pliki Batch API. Do dyspozycji masz widok obok siebie, podświetlanie składni i walidację w czasie rzeczywistym.

Najczęściej zadawane pytania

Źródła