OpenAI Batch API JSONL 格式指南
学习如何构建 OpenAI Batch API 的 JSONL 文件,节省 50% 的成本
什么是 OpenAI Batch API?
OpenAI Batch API 允许您将大量 API 请求作为单个批处理任务发送。无需发起数千个独立的 API 调用,您只需上传一个包含所有请求的 JSONL 文件,OpenAI 会在 24 小时内异步处理它们。
核心优势是成本:批处理请求比实时 API 调用便宜 50%。这使得 Batch API 非常适合不需要即时响应的任务,例如内容生成、数据分类、嵌入向量计算和评估管道。
JSONL 请求格式
批处理输入 JSONL 文件中的每一行代表一个 API 请求。每行必须包含三个必填字段,并遵循特定的结构。
custom_id — 每个请求的唯一标识符。用于将请求与响应匹配。可以是最长 512 个字符的任意字符串。method — HTTP 方法。目前仅支持 POST。url — API 端点路径。聊天补全:/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"}]}}聊天补全批处理
Batch API 最常见的用例是发送多个聊天补全请求。每行包含一个完整的请求,包括 model、messages 和可选参数如 max_tokens 或 temperature。
单个请求
每行包含一个完整的聊天补全请求,包括模型、消息和可选参数。
{"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 文件
批处理文件通常包含数百或数千个请求。以下是一个包含三个不同任务的文件:摘要、分类和翻译。
{"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。
嵌入向量请求使用更简单的请求体结构,包含模型和输入文本。
{"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 文件,其中每行包含一个请求的响应。响应包含原始的 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 文件到下载和解析结果。
- 1创建 JSONL 文件,每行一个请求
- 2使用 Files API 上传文件,purpose 设为 batch
- 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 文件拆分为更小、更易管理的文件块。
逐行验证 JSONL 文件。即时捕获语法错误、编码问题和格式问题。
学习处理大型 JSONL 文件的策略,包括流式读取、内存管理、文件分割和压缩技巧。
学习如何为 AI/ML fine-tuning 准备 JSONL 训练数据。涵盖 OpenAI、Anthropic Claude 和 HuggingFace 数据集格式以及验证和数据准备管道。