JSONL (JSON Lines) Format Guide

Specification

JSONL（JSON Lines），也稱為換行分隔 JSON（NDJSON），是一種基於文字的資料格式，其中每行是由換行符分隔的有效 JSON 物件。與將所有資料包裝在單一陣列或物件中的標準 JSON 不同，JSONL 每行儲存一條記錄，使其非常適合串流、追加和處理大型資料集，而無需將整個檔案載入記憶體。該格式由 jsonlines.org 規格非正式定義，已成為 LLM 微調資料集的事實標準。

JSONL 檔案中的每行必須是一個自包含的、有效的 JSON 物件。行由換行符（\n）分隔，允許尾隨換行。沒有標頭行、沒有封閉括號、記錄之間沒有逗號。這種簡潔性使 JSONL 極其容易使用標準 Unix 工具進行解析、生成和操作——您可以使用 grep 篩選行、使用 wc -l 計數記錄、使用 shuf 取樣，以及使用 cat 串接檔案。

該格式的串流友善特性使其特別適合增量處理資料的機器學習管線。Hugging Face Transformers、OpenAI 的微調 API、Axolotl 和 LLaMA-Factory 等訓練框架都接受 JSONL 作為其主要輸入格式。pandas、Polars、DuckDB 和 Apache Spark 等資料處理工具提供原生 JSONL 支援，實現資料準備和模型訓練階段之間的無縫整合。

When to Use JSONL (JSON Lines)

每當您為大型語言模型微調準備基於文字的訓練資料時，JSONL 是推薦的格式。它是 OpenAI 微調、Hugging Face datasets 和大多數開源訓練框架的預期輸入格式。如果您的訓練資料由指令-回應配對、對話交流、文字分類範例或任何其他結構化文字資料組成，JSONL 應該是您的預設選擇。

當您的資料包含巢狀結構、可變長度欄位或在 CSV 格式中需要複雜轉義的特殊字元時，選擇 JSONL 而非 CSV。JSONL 自然處理陣列、巢狀物件和 Unicode 文字，沒有困擾 CSV 檔案的分隔符和引用問題。當您需要可用文字編輯器檢查和編輯的人類可讀資料時，或當您的資料集小到 Parquet 的壓縮優勢不顯著時，選擇 JSONL 而非 Parquet。

JSONL 不太適合非常大的數值資料集，其中 Parquet 等欄式格式提供顯著更好的壓縮和查詢性能。對於多次讀取但很少修改的資料集，它也不如二進位格式高效，因為每次讀取都需要解析 JSON 文字。對於超過數十 GB 的資料集，考慮轉換為 Parquet 進行儲存，並在最後的訓練步驟中轉換回 JSONL。

Schema / Structure

// OpenAI-compatible fine-tuning format
interface ChatCompletionMessage {
  role: "system" | "user" | "assistant";
  content: string;
}

interface FineTuningExample {
  messages: ChatCompletionMessage[];
}

// Instruction-following format (Alpaca-style)
interface InstructionExample {
  instruction: string;
  input?: string;
  output: string;
}

// Text classification format
interface ClassificationExample {
  text: string;
  label: string;
}

Example Data

{"messages": [{"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Write a Python function to reverse a string."}, {"role": "assistant", "content": "def reverse_string(s: str) -> str:\n    return s[::-1]"}]}
{"messages": [{"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "How do I read a CSV file in Python?"}, {"role": "assistant", "content": "import pandas as pd\ndf = pd.read_csv('data.csv')\nprint(df.head())"}]}
{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."}]}