作者: Jerry Fan

OpenAI JSONL 格式指南

關於 OpenAI 用於微調模型和 Batch API 的 JSONL 格式,您需要知道的一切。包含格式規範、程式碼範例和常見陷阱。

什麼是 OpenAI JSONL 格式?

OpenAI 使用 JSONL(JSON Lines)作為微調資料集和 Batch API 請求的標準檔案格式。檔案中的每一行都是一個完整、獨立的 JSON 物件——不需要外層陣列,行與行之間也不需要逗號。

選擇這種格式是因為它允許高效的串流處理和逐行處理。每個訓練範例或 API 請求都可以獨立驗證,且檔案可以在不將整個資料集載入記憶體的情況下處理。

理解精確的格式要求至關重要。即使是很小的格式錯誤——例如尾隨逗號或缺少欄位——都會導致整個檔案被拒絕。

驗證您的 JSONL 檔案

上傳至 OpenAI 前,請先使用我們的免費驗證器檢查檔案。將檢查標準切換為「OpenAI 微調格式」,即可逐行檢查訊息、角色與 assistant 回覆,以及 JSON 語法。

微調 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 檔案必須每行一個物件,不需要外層陣列。

錯誤
[{"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 檔案:

Python — 建立微調 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")
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`);

檢視與編輯 OpenAI JSONL 檔案

使用我們的免費線上 JSONL 檢視器來檢查微調資料集和 Batch API 檔案。並排檢視、語法高亮和即時驗證。

常見問題

參考資料