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 文件必须每行一个对象,不能有外层数组。
[{"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 文件。即时捕获语法错误、编码问题和格式问题。
使用适当的缩进格式化和美化 JSONL 文件。使调试和数据审查更加轻松。
按行数将大型 JSONL 文件拆分为更小、更易管理的文件块。
了解 OpenAI Batch API 所需的 JSONL 请求格式,包括完整示例和错误处理。
学习如何为 AI/ML fine-tuning 准备 JSONL 训练数据。涵盖 OpenAI、Anthropic Claude 和 HuggingFace 数据集格式以及验证和数据准备管道。