從單一資料管道匯出多種格式：JSONL、COCO、YOLO 和 RAG 區塊

你已經攝取、清理、標記和增強了你的資料集。現在你需要匯出它——而下游系統決定了格式。

微調語言模型？JSONL。訓練物件偵測模型？YOLO 或 COCO。構建 RAG 管道？帶元資料的分塊文字。訓練傳統 ML 分類器？CSV。餵給 AI 代理？帶工具呼叫架構的結構化 JSON。

問題：大多數資料準備工具匯出一種格式。也許兩種。如果你的專案需要三種匯出格式——當客戶想從同一源資料進行微調、RAG 和儀表板時，這是常見情況——你最終會維護三個匯出腳本，每個都有自己的格式特定錯誤和驗證缺口。

本指南涵蓋每種格式需要什麼、它們在哪裡出錯，以及如何從單一管道可靠地匯出。

---

格式要求：每種格式實際上需要什麼

LLM 微調的 JSONL

JSONL（JSON Lines）是微調語言模型的標準格式。每行是一個自包含的 JSON 對象，代表一個訓練範例。

指令微調格式：

{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}

關鍵要求：

• 每行上的有效 JSON——一個格式錯誤的行可能導致訓練腳本崩潰
• 所有行的一致架構（相同字段、相同角色）
• UTF-8 編碼，無 BOM
• 無尾隨逗號，無注釋
• 每個範例的 token 數量在模型的背景視窗內

常見問題：

• 文字內容中的未轉義引號（最常見的 JSONL 格式錯誤）
• 內容字段中的換行未正確轉義
• 混合架構（有些行使用 prompt/completion，其他使用 messages）
• 訓練框架無法處理的空或 null 字段

電腦視覺的 COCO 格式

COCO（Common Objects in Context）格式使用包含圖像元資料、類別定義和標記的單個 JSON 文件。

結構：

{
  "images": [{"id": 1, "file_name": "img001.jpg", "width": 1920, "height": 1080}],
  "categories": [{"id": 1, "name": "defect"}, {"id": 2, "name": "normal"}],
  "annotations": [{"id": 1, "image_id": 1, "category_id": 1, "bbox": [x, y, w, h], "area": 1234}]
}

關鍵要求：

• 所有 ID 必須唯一且正確交叉引用
• 邊界框格式為 [x, y, width, height]（左上角原點）
• 面積必須與邊界框尺寸匹配
• 圖像尺寸必須與實際文件尺寸匹配
• 分割遮罩（如果使用）必須是有效的多邊形

常見問題：

• 圖像和標記之間的 ID 不匹配
• 超出圖像邊界的邊界框
• 來自標記錯誤的零面積標記
• 與類別列表不匹配的類別 ID

物件偵測的 YOLO 格式

YOLO 使用帶有每個圖像一個文字文件的目錄結構，每行代表一個標記。

結構：

<class_id> <x_center> <y_center> <width> <height>

所有座標都被規範化為相對於圖像尺寸的 0-1。

關鍵要求：

• 每個圖像一個 .txt 文件，相同的文件名（不同的擴展名）
• 座標規範化為 [0, 1]
• 類別 ID 為從零開始的整數
• 將類別 ID 映射到名稱的 data.yaml 文件

常見問題：

• 座標未規範化（使用像素值而不是 0-1 範圍）
• 圖像文件和標記文件之間的文件名不匹配
• 類別 ID 從 1 開始而不是 0
• 沒有物件的圖像的缺失標記文件（YOLO 期望空文件，而不是缺失文件）

RAG 的分塊文字

RAG（檢索增強生成）管道需要將文字分割成帶有用於檢索的元資料的區塊。

典型結構：

{"chunk_id": "doc001_chunk_003", "text": "...", "metadata": {"source": "policy_v2.pdf", "page": 12, "section": "Termination"}}

關鍵要求：

• 適合嵌入模型的區塊大小（通常 256-512 個 token）
• 相鄰區塊之間的重疊（通常為區塊大小的 10-20%）以避免分割相關背景
• 保留用於引用的源元資料
• 不分割句子或語義單元的區塊邊界

常見問題：

• 在句子中間分割的區塊，產生嵌入效果差的片段
• 缺失或不正確的源元資料（使引用變得不可能）
• 區塊大小不一致（一些區塊為 50 個 token，其他為 2,000 個）
• 以原始文字形式分塊的表格內容，丟失了行列結構

傳統 ML 的 CSV

每個範例一行、每個特徵一列的平面表格格式。

關鍵要求：

• 所有行的一致列數
• 正確轉義字段值中的逗號、引號和換行
• 帶描述性列名的標題行
• 每列的一致資料類型（不混合字符串和數字）

常見問題：

• 包含破壞解析的逗號的文字字段
• 不一致的 null 表示（空字符串 vs "null" vs "N/A" vs "None"）
• 非 ASCII 文字中的編碼問題
• 使 CSV 對非文字工具難以使用的大型文字字段

AI 代理的結構化 JSON

代理訓練資料需要工具呼叫架構、動作-觀察對和結構化決策記錄。

關鍵要求：

• 工具呼叫架構與實際工具簽名匹配
• 動作-觀察序列按時間順序排列
• 每個決策點包括可用動作和選擇的動作
• 代表了錯誤案例和邊緣案例

---

並行管道問題

當每種格式需要一個單獨的匯出管道時，你最終會維護並行程式碼路徑：

源資料 → JSONL 匯出腳本 → jsonl_output/
源資料 → COCO 匯出腳本 → coco_output/
源資料 → RAG 分塊腳本 → chunks_output/
源資料 → CSV 匯出腳本 → csv_output/

每個腳本都是潛在的來源：

格式錯誤：JSONL 匯出器中只在某些記錄上觸發的未轉義引號。YOLO 匯出器中的座標規範化錯誤，對某些圖像尺寸產生超出範圍的值。

資料漂移：如果你更新源資料並重新匯出，所有四個腳本是否都獲取了更改？如果 JSONL 腳本處理了更新的資料，但 COCO 腳本指向了緩存副本，你的匯出是不一致的。

驗證缺口：每個腳本可能包含也可能不包含驗證。JSONL 腳本可能驗證 JSON 語法，但不檢查空字段。COCO 腳本可能檢查 ID 引用，但不驗證邊界框尺寸。

維護負擔：四種格式的四個腳本，每個都有格式特定的邊緣案例，每個都需要在源資料架構更改時更新。

對於處理多個客戶專案的服務提供商，這擴展性很差。影響一個專案的格式錯誤可能影響其他專案——但每個專案的腳本是獨立的。

---

匯出驗證：需要檢查什麼

驗證應該是必需的步驟，而不是可選的。在考慮任何匯出完成之前，請檢查以下內容：

通用檢查（所有格式）

• 記錄數：匯出包含預期數量的記錄
• 完整性：沒有缺失字段，在需要值的地方沒有 null 值
• 編碼：全程 UTF-8，沒有編碼工件
• 去重複：匯出中沒有重複記錄
• 可追溯性：每個匯出的記錄都映射回管道中的源記錄

格式特定檢查

下游相容性檢查

• JSONL：加載到目標訓練框架並驗證它無錯誤地解析
• COCO：在樣本上運行 COCO 評估 API 以驗證格式相容性
• YOLO：加載到目標 YOLO 訓練腳本並驗證它正確讀取標記
• RAG 區塊：嵌入樣本並驗證檢索產生預期結果

---

單一管道匯出架構

並行腳本的替代方案是從一個資料模型產生多種匯出格式的單一管道：

源資料 → 統一管道 → 匯出模塊 → JSONL
                              → COCO
                              → YOLO
                              → RAG 區塊
                              → CSV
                              → 結構化 JSON

這種架構有特定的優勢：

一個資料模型：所有記錄存在於單一表示中。匯出到每種格式是從那個表示的轉換——而不是帶有自己解析邏輯的獨立管道。

一次驗證通過：在統一模型中一次驗證資料。格式特定驗證發生在匯出邊界，而不是上游。

一致的匯出：當源資料更改時，每種匯出格式都反映了更改。格式之間沒有漂移。

稽核追蹤：每個匯出都以匯出格式、時間戳、記錄數和驗證結果記錄。當合規團隊詢問「訓練資料集中究竟包含什麼？」時，答案在一個地方。

---

實用建議

1. 早期匯出，立即驗證。 不要等到微調日才發現格式問題。在管道設置期間以每個目標格式匯出 100 條記錄的樣本。

2. 為你的匯出版本化。 使用與管道狀態關聯的版本識別符標記每個匯出。當你在資料更新後重新匯出時，之前的版本仍然可供比較。

3. 包含匯出元資料。 每個匯出都應該包含一個清單：記錄數、匯出格式、管道版本、驗證結果和匯出資料的哈希值。

4. 下游測試。 最可靠的驗證是將匯出加載到下游系統並驗證它是否有效。看起來正確但導致訓練框架崩潰的 JSONL 文件有靜態驗證遺漏的格式問題。

Ertas Data Suite 的匯出模塊從單個專案產生所有主要格式——JSONL、COCO、YOLO、CSV、分塊文字和結構化 JSON。每個匯出都包括架構驗證、下游相容性檢查和完整的稽核日誌。切換匯出格式不需要重新配置管道——相同的準備資料一鍵匯出到任何格式。

---

連接到管道

匯出是資料準備管道的最後階段。每個上游階段的品質——攝取、清理、標記和增強——決定了匯出的資料集是否產生在生產環境中有效的模型。

有關完整管道概述，請參閱如何為 LLM 微調構建本地端資料準備管道。