JSONL 檔案:如何為 AI 上傳一步步建立
簡短回答 JSONL 檔案是純文字,每行一個完整的 JSON 物件,以 UTF-8 儲存,副檔名為 .jsonl。製作方法:把試算表另存為 CSV,執行一段簡短的 Python 指令碼,每列資料寫成一行,然後檢查每一行都能被解析。動手前,先確認您的 AI 平台要求的確切欄位。
想把這些用在您的生意上?預約一次 30 分鐘的免費通話,一起聊聊。
預約通話如何建立 JSONL 檔案:四個步驟
從一張試算表開始,最後得到 AI 平台能接受的檔案。Python 免費,做這件事也不需要安裝額外的套件。
| 步驟 | 做什麼 | 容易出錯的地方 |
|---|---|---|
| 1. 弄清目標格式 | 閱讀您要上傳的平台的上傳說明頁面 | 每個平台的欄位名稱都不一樣 |
| 2. 把資料存為 CSV | 每列一個範例,每欄一個欄位,第 1 列是標題 | 合併儲存格和表格下方的備註會變成垃圾列 |
| 3. 用 Python 轉換 | 一段三行指令碼,每列資料寫成一個 JSON 物件 | 把整個清單寫成一個 JSON 陣列 |
| 4. 逐行檢查 | Python 內建的檢查工具逐行讀取,遇到第一處錯誤就停下 | 一個空行或一個多餘的逗號就會讓整個上傳失敗 |
JSONL 檔案長什麼樣子
每行是一筆記錄,每筆記錄本身都是完整的。JSON Lines 格式有三條規則:檔案為 UTF-8,每行是一個有效的 JSON 值,每行以換行字元結尾。有兩個細節常讓人出錯:
"a byte order mark (U+FEFF) must NOT be included" (JSON Lines specification) 譯文:「不得包含位元組順序標記(U+FEFF)」
"e.g. null is a valid value but a blank line is not." (JSON Lines specification) 譯文:「例如,null 是有效值,但空行不是。」
最後一筆記錄後面加換行字元是「strongly recommended but not required」(強烈建議,但非必要)。常用副檔名是 .jsonl。
| 一般 JSON | JSONL | |
|---|---|---|
| 結構 | 一個大的物件或陣列,常跨很多行 | 每行一個物件,沒有外層括號,行與行之間沒有逗號 |
| 程式如何讀取 | 通常一次讀完 | 一次讀一行 |
| 新增一筆記錄 | 在陣列裡面編輯 | 在結尾加一行 |
| 一筆記錄損壞 | 整個檔案解析失敗 | 只有那一行失敗,其餘照常讀取 |
批次工作中的一行簡短內容如下,在檔案裡它全部寫在同一行:
{"custom_id": "faq-1", "method": "POST", "url": "/v1/responses", "body": {"model": "...", "input": "Write a 2-sentence answer: do you work Saturdays?"}}
哪些 AI 工具要求 JSONL 檔案?
主要是兩類工作:用您的範例訓練模型(微調),以及一次以折扣價送出大量請求(批次處理)。動手之前先看平台自己的說明頁面,因為欄位名稱各不相同。
| 平台 | JSONL 的用途 | 主要限制(2026 年 11 月) |
|---|---|---|
| OpenAI Batch API | 一次送出大量請求;每行需要唯一的 custom_id | 比一般呼叫便宜 50%;24 小時內完成;每個檔案最多 50,000 個請求、200 MB;每個檔案只能用一個模型 |
| Gemini API Batch | 一次送出大量請求;每行有一個 key 和一個 request | 標準費用的 50%;目標 24 小時完成;輸入檔案最大 2 GB |
| Google Cloud(Gemini 微調) | 微調,每行一個範例,上傳到 Cloud Storage | Google 建議從 100 個範例開始 |
| Amazon Bedrock | 微調;格式取決於模型 | 每個模型有各自的大小規定 |
| Microsoft Foundry | 微調;訓練檔和驗證檔分開,每行一段對話 | 每個模型有範例數量和大小的最低要求 |
| OpenAI 微調 | 即將關閉;見下文 | 至少 10 行;OpenAI 建議從 50 行開始 |
大多數舊教學都以 OpenAI 的微調為基礎,而它正在關閉:
"OpenAI is winding down the fine-tuning platform. The platform is no longer accessible to new users." (OpenAI API docs: Supervised fine-tuning) 譯文:「OpenAI 正在逐步關閉微調平台。新使用者已無法使用該平台。」
符合資格的現有客戶在 2027 年 1 月 6 日之前仍可啟動訓練工作,gpt-4.1 和 gpt-4.1-mini 的微調模型將於 2027 年 1 月 14 日停用。如果您是新使用者,請改用 Google Cloud、Bedrock 或 Foundry,或乾脆不做微調。
您真的需要微調嗎?
通常不需要。老闆們的大多數工作,例如用您的口吻回答常見問題或起草報價,用一個好的提示詞再貼幾個範例就能完成。OpenAI 自己的建議也是先測試:「Only invest in fine-tuning after setting up evals」(先建立評估,再投入微調);如果 50 個好範例都沒有帶來改變,就要「rethink your task or prompt before adding training data」(在增加訓練資料之前,重新思考您的任務或提示詞)。先從更好的提示詞開始,等它們遇到瓶頸再回來。
用 Python 把試算表轉成 JSONL
把試算表另存為 CSV(在 Excel 中選擇 CSV UTF-8)。然後把下面幾行放進一個檔案(例如 convert.py)執行,把檔名換成您自己的:
import csv, jsonrows = csv.DictReader(open("faq.csv", encoding="utf-8-sig", newline=""))with open("faq.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps(r, ensure_ascii=False) + "\n" for r in rows)
每個部分的作用:
| 部分 | 作用 |
|---|---|
| csv.DictReader | 把每列變成一筆記錄,以第 1 列作為欄位名稱 |
| utf-8-sig | 據 Python 文件,如果檔案開頭有隱藏的位元組順序標記,它會略過,讓第一欄的欄位名稱保持乾淨 |
| json.dumps(...) + "\n" | 一筆記錄,再加一個換行:這就是 JSONL 的全部規則 |
| ensure_ascii=False | 讓重音符號和非英文字元保持可讀,而不是變成跳脫碼 |
| encoding="utf-8" | 以 UTF-8 寫入,不帶格式所禁止的標記 |
已經在用 pandas?一行就能完成同樣的工作:pd.read_csv("faq.csv").to_json("faq.jsonl", orient="records", lines=True, force_ascii=False)。根據 pandas 文件,lines 選項只有在 orient 設為 records 時才有效。
如何編寫微調範例
對話式訓練檔把每個範例包在一個 messages 清單裡:客戶問了什麼,以及您希望得到的回答。這是 Microsoft Foundry 展示的結構。如果 CSV 有 question 和 answer 兩欄,把指令碼第 3 行改成:
with open("train.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps({"messages": [{"role": "user", "content": r["question"]}, {"role": "assistant", "content": r["answer"]}]}, ensure_ascii=False) + "\n" for r in rows)
這樣每列資料會變成這樣的一行:
{"messages": [{"role": "user", "content": "Do you work Saturdays?"}, {"role": "assistant", "content": "Yes, 8am to 2pm."}]}
Google 的 Gemini 微調用的是不同的名稱(contents 和 parts,可選 systemInstruction),所以同樣的做法在那裡要換用不同的鍵。無論哪個平台,都要用真實的問題和您最好的員工給出的回答。另外保留一組範例不參與訓練,用來測試結果。
上傳前檢查檔案
Python 內建檢查工具。在終端機執行:
python3 -m json.tool --json-lines faq.jsonl
它把每一行當作獨立的 JSON 物件讀取(Python 3.8 起提供)。如果每行都沒問題,它會全部印出來。如果有問題,它會報錯停下;最後印出的那筆記錄是最後一行正確的內容,所以問題出在下一行。
| 您看到的錯誤 | 常見原因 | 解決方法 |
|---|---|---|
| Expecting value | 一個空行,常出現在貼上的檔案結尾 | 刪除空行 |
| Expecting property name enclosed in double quotes | 手動輸入時用了單引號或多了結尾逗號 | 用指令碼產生各行,不要手打 |
| 上傳被拒,格式看起來沒問題 | 欄位名稱和平台不一致 | 拿一行和平台給的範例對照 |
| 執行指令碼時出現 UnicodeDecodeError | CSV 用舊編碼儲存,不是 UTF-8 | 重新另存為 CSV UTF-8 再執行 |
不用 Python 能做 JSONL 檔案嗎?
可以,只要行數不多。在純文字編輯器(Notepad、純文字模式下的 TextEdit)裡輸入,每行一筆記錄,以 UTF-8 儲存,副檔名為 .jsonl。超過 20 行左右,手打就容易出現上面那些錯誤。
網路上有免費的 CSV 轉 JSONL 工具,但您得把檔案上傳到別人的伺服器。訓練資料常包含客戶姓名、電子郵件和工作細節,所以傳送之前,先了解您如何收集這些資料、客戶同意了什麼。
範例
水電工的常見問題批次處理
試算表裡有 60 個常見問題。老闆把它另存為 CSV,轉換後給每行包上帶 custom_id 的批次格式,一次送出一個批次工作,以一般價格的一半起草網站上的回答。檢查工具事先發現了檔案結尾的一個空行。
美髮沙龍訓練回覆風格
200 則過去回覆預約問題的訊息,已去除客戶姓名。老闆先試了一個貼了 10 個範例的提示詞,草稿已經夠接近了。微調就此擱置。
拿著舊 OpenAI 教學的記帳師
教學說要上傳到 OpenAI 微調。帳戶是新的,所以沒有這個選項。同樣的範例改用 Google 的 contents 和 parts 欄位名稱後,改傳到 Google Cloud。
常見問題
JSON 和 JSONL 有什麼差別?
JSON 存放一個物件或陣列,常跨很多行。JSONL 每行存放一個完整的物件,所以程式可以一次讀取或新增一筆記錄。
能用 Excel 開啟 JSONL 檔案嗎?
不能直接按列開啟。用 pandas(read_json 加 lines=True)轉回來再存為 CSV,或用任何文字編輯器開啟閱讀。
微調模型需要多少範例?
取決於平台。OpenAI 的最低要求是 10 行,建議從 50 行開始;Google 建議 Gemini 微調從 100 個開始。在兩個平台上,品質都比數量更重要。
大的 JSONL 檔案要壓縮嗎?
JSON Lines 規範建議用 gzip 或 bzip2 節省空間。除非平台頁面說明接受壓縮檔,否則請上傳未壓縮的檔案。
您的情況不同?
- 您希望 AI 直接完成任務,不用自己做檔案: 請看 AI 行銷自動化設定。
- 您的資料包含客戶資訊: 先看第一方資料與同意。
- 您只需要更好的 AI 輸出: 從 AI 行銷提示詞或用 ChatGPT 做行銷開始。
- 您希望網站上也有這樣的回答: 請看網站代理。