OpenAI Batch API の JSONL フォーマットガイド
OpenAI の Batch API でコストを 50% 削減するための JSONL ファイルの作り方を解説します
OpenAI Batch API とは?
OpenAI Batch API を使うと、大量の API リクエストを1つのバッチジョブにまとめて送信できます。個別に数千回の API 呼び出しを行う代わりに、すべてのリクエストを記述した JSONL ファイルをアップロードすると、OpenAI が 24 時間以内に非同期で処理します。
最大のメリットは、コストを削減できることです。バッチリクエストの料金は、リアルタイムの API 呼び出しより 50% 安くなります。そのため、コンテンツ生成、データ分類、埋め込みベクトルの計算、評価パイプラインなど、すぐにレスポンスを必要としないタスクに適しています。
JSONL リクエストのフォーマット
バッチ処理の入力となる JSONL ファイルには、1行につき1つの API リクエストを記述します。各行は決められた構造に従い、3つの必須フィールドを含める必要があります。
custom_id — リクエストごとの一意な識別子です。リクエストとレスポンスを対応付けるために使います。512文字以内の任意の文字列を指定できます。method — HTTP メソッドです。現在サポートされているのは POST のみです。url — API エンドポイントのパスです。Chat Completions では /v1/chat/completions、埋め込みベクトルの生成では /v1/embeddings を指定します。body — リクエストボディです。対応する API エンドポイントのリクエストボディと同じ形式で記述します。{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Chat Completions のバッチ処理
Batch API の最も一般的な用途は、複数の Chat Completions リクエストをまとめて送信することです。各行には、model、messages と、必要に応じて max_tokens や temperature などの任意パラメータを指定し、1件分のリクエストをすべて記述します。
1件のリクエスト
各行には、model、messages、任意パラメータを含め、1件分の Chat Completions リクエストをすべて記述します。
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}複数のリクエストを記述した JSONL ファイル
バッチファイルには通常、数百から数千件のリクエストを記述します。以下は、要約、分類、翻訳という3つの異なるタスクを記述した例です。
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}埋め込みベクトル生成のバッチ処理
Batch API は埋め込みベクトルの生成リクエストにも対応しており、大量のドキュメントを処理する際に便利です。JSONL の構造は同じですが、送信先には /v1/embeddings エンドポイントを指定します。
埋め込みベクトルの生成リクエストでは、model と入力テキストを指定する、よりシンプルなリクエストボディを使います。
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}レスポンスのフォーマット
バッチジョブが完了すると、OpenAI から出力 JSONL ファイルが提供されます。各行には1件のリクエストに対するレスポンスが格納されます。レスポンスには元の custom_id が含まれるため、どのリクエストに対する結果かを確認できます。
成功時のレスポンス
成功時のレスポンスには、custom_id、レスポンスのステータスコード、API レスポンスボディの全体が含まれます。
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}エラーレスポンス
リクエストが失敗すると、エラーコードと問題の内容を示すメッセージを持つエラーオブジェクトが返されます。
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Batch API を使う一連の手順
Python SDK を使って Batch API を利用する手順を、JSONL ファイルの作成から結果のダウンロードと解析まで、5つのステップで紹介します。
- 11行につき1つのリクエストを記述した JSONL ファイルを作成します
- 2purpose を batch に設定し、Files API でファイルをアップロードします
- 3アップロードしたファイルの ID を指定して、バッチジョブを作成します
- 4バッチのステータスが completed、failed、cancelled のいずれかになるまでポーリングします
- 5出力 JSONL ファイルをダウンロードして解析し、結果を取り出します
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())Batch API とリアルタイム API の比較
Batch API と通常のリアルタイム API を用途に応じて使い分けることで、コストとパフォーマンスの両方を最適化できます。
OpenAI のファインチューニングで使う JSONL フォーマットについては、次のガイドをご覧ください: OpenAI JSONL フォーマットガイド.
バッチファイルの準備
OpenAI に送信する前に、無料ツールで JSONL バッチファイルを作成・検証し、内容を確認できます。
OpenAI 向けの JSONL ファイルの準備方法をまとめた完全ガイドです。ファインチューニングのデータ形式、Batch API のリクエスト、よくある間違い、検証のコツを解説します。
大容量の JSONL ファイルを、行数やファイルサイズに応じて小さく分割できます。バッチ API の制限に合わせた分割や、並列処理に適しています。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
AI/ML のファインチューニング向けに JSONL の学習データを準備する方法を解説します。OpenAI、Anthropic Claude、HuggingFace のデータセット形式に加え、検証やデータ準備パイプラインも紹介します。