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" 欄位
- 有效的角色為："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`);