OpenAI の JSONL 形式ガイド
OpenAI のモデルのファインチューニングと Batch API で使う JSONL 形式について解説します。形式の仕様からコード例、よくある注意点まで、必要な知識をまとめています。
OpenAI の JSONL 形式とは?
OpenAI では、ファインチューニング用データセットと Batch API リクエストの標準ファイル形式として JSONL(JSON Lines)を採用しています。各行がそれぞれ独立した完全な JSON オブジェクトになっており、全体を配列で囲んだり、行と行の間にカンマを入れたりしません。
この形式なら、ストリーミングや行単位の処理を効率よく行えます。学習データの各サンプルや API リクエストを個別に検証でき、データセット全体をメモリに読み込まずにファイルを処理できます。
形式の要件は正確に把握しておく必要があります。末尾のカンマやフィールドの欠落など、わずかな不備でもファイル全体が拒否されます。
ファインチューニング用の JSONL 形式
チャットモデル(GPT-4o、GPT-4o-mini、GPT-3.5 Turbo)をファインチューニングする場合は、各行に会話のやり取りを格納した「messages」配列が必要です。
{"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."}]}必須フィールド
- messages — メッセージオブジェクトの配列(必須)
- role — "system"、"user"、"assistant" のいずれか(必須)
- content — メッセージの本文(テキスト、必須)
system メッセージは任意ですが、含めることを推奨します。各会話には、user メッセージが少なくとも 1 つ、assistant メッセージも少なくとも 1 つ必要です。モデルは、assistant メッセージの内容を生成できるように学習します。
Batch API 用の JSONL 形式
Batch API では、ファインチューニング用とは異なる JSONL 形式を使います。各行には、カスタム ID を付けた API リクエストを記述します。
{"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?"}]}}必須フィールド
- custom_id — 各リクエストを一意に識別する ID(必須)
- method — HTTP メソッド。通常は "POST"(必須)
- url — API エンドポイントのパス(必須)
- body — 通常の API 呼び出しと同じリクエストボディ(必須)
形式の要件
OpenAI に受け付けられる JSONL ファイルを作成するには、以下のルールに従ってください。
- 各行を、構文エラーのない有効な JSON にしてください。
- 各行を JSON オブジェクトにしてください({ で始まり、} で終わります)。
- ファインチューニング用ファイルでは、各行に「messages」配列を含めてください。
- 各メッセージには「role」と「content」の両方のフィールドが必要です。
- role に指定できる値は "system"、"user"、"assistant" です。
- ファイルは BOM(バイトオーダーマーク)なしの UTF-8 で保存してください。
- 末尾のカンマ、コメント、行間の余分な空白は含めないでください。
- 空行は含めてもかまいません。処理時には無視されます。
よくある間違い
OpenAI 用の JSONL ファイルを作成する際によくあるエラーを紹介します。
JSONL の代わりに JSON 配列を使っている
すべてのオブジェクトを [ ] で囲むのは誤りです。JSONL ファイルでは全体を配列で囲まず、1 行に 1 つのオブジェクトを記述します。
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}必須フィールドが抜けている
すべてのメッセージに「role」と「content」が必要です。どちらかが欠けていると検証に失敗します。
{"messages":[{"role":"user"}]}{"messages":[{"role":"user","content":"Hello"}]}JSON の末尾にカンマがある
JSON では、配列やオブジェクトの最後の要素の後にカンマを付けることはできません。
{"messages":[{"role":"user","content":"Hi",}]}{"messages":[{"role":"user","content":"Hi"}]}BOM が含まれている、または文字コードが正しくない
ファイルは BOM なしの UTF-8 で保存してください。テキストエディタによっては目に見えない BOM が追加され、JSON の解析に失敗することがあります。
\uFEFF{"messages":[...]}{"messages":[...]}コード例
プログラムから OpenAI 用の JSONL ファイルを作成する例を紹介します。
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")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`);関連ツールとガイド
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
JSONL ファイルに適切なインデントを付けて、読みやすく整形できます。デバッグやデータのレビューがしやすくなります。
大容量の JSONL ファイルを、行数やファイルサイズに応じて小さく分割できます。バッチ API の制限に合わせた分割や、並列処理に適しています。
OpenAI Batch API 向けの JSONL ファイルの構造を解説します。リクエスト形式、レスポンスのパース、一連のワークフローをコード例とともに紹介します。
AI/ML のファインチューニング向けに JSONL の学習データを準備する方法を解説します。OpenAI、Anthropic Claude、HuggingFace のデータセット形式に加え、検証やデータ準備パイプラインも紹介します。