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."}]}