OpenAI JSONL 格式指南
关于 OpenAI 模型微调和 Batch API 所使用的 JSONL 格式，您需要了解的一切。包含格式规范、代码示例和常见陷阱。
最后更新：2026 年 2 月
什么是 OpenAI JSONL 格式？
OpenAI 使用 JSONL（JSON Lines）作为微调数据集和 Batch API 请求的标准文件格式。文件中的每一行都是一个完整、独立的 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 消息和一条 assistant 消息。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 — 每个请求的唯一标识符（必需）
- method — HTTP 方法，通常为 "POST"（必需）
- url — API 端点路径（必需）
- body — 请求体，与常规 API 调用相同（必需）
格式要求
遵循以下规则确保您的 JSONL 文件被 OpenAI 接受：
- 每行必须是有效的 JSON——不允许语法错误
- 每行必须是 JSON 对象（以 '{' 开头，以 '}' 结尾）
- 微调文件每行必须包含 "messages" 数组
- 每条消息必须包含 "role" 和 "content" 字段
- 有效的 role 值为："system"、"user" 和 "assistant"
- 文件必须使用 UTF-8 编码，不带 BOM（字节顺序标记）
- 行与行之间不允许有尾随逗号、注释或多余的空白
- 允许空行，空行将被忽略
常见错误
以下是创建 OpenAI JSONL 文件时最常见的错误：
使用 JSON 数组而非 JSONL
错误做法：将所有对象包裹在 [ ] 中。JSONL 文件必须每行一个对象，不能有外层数组。
Wrong
['{'"messages":[...]'}', '{'"messages":[...]'}']Correct
'{'"messages":[...]'}'
'{'"messages":[...]'}'缺少必需字段
每条消息必须同时包含 "role" 和 "content"。遗漏任何一个都会导致验证失败。
Wrong
'{'"messages":['{'"role":"user"'}']'}'Correct
'{'"messages":['{'"role":"user","content":"Hello"'}']'}'JSON 中的尾随逗号
JSON 不允许在数组或对象的最后一项之后有尾随逗号。
Wrong
'{'"messages":['{'"role":"user","content":"Hi",'}']'}'Correct
'{'"messages":['{'"role":"user","content":"Hi"'}']'}'BOM 字符或编码错误
将文件保存为不带 BOM 的 UTF-8 编码。某些文本编辑器会添加不可见的 BOM 字符，导致 JSON 解析失败。
Wrong
\uFEFF'{'"messages":[...]'}'Correct
'{'"messages":[...]'}'代码示例
以下是如何通过编程方式创建 OpenAI JSONL 文件：
Python — 创建微调 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")
JavaScript — 创建微调 JSONL
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`);