作者： Jerry Fan更新于 2026年6月
OpenAI JSONL 格式指南
关于 OpenAI 模型微调和 Batch API 所使用的 JSONL 格式，您需要了解的一切。包含格式规范、代码示例和常见陷阱。
什么是 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`);