Hugging Face Datasets 怎样从 JSON 加载数据集

把本地 JSON 交给 Hugging Face Datasets 时，真正容易出错的不是函数名，而是文件根结构和 split 的对应关系。JSONL 每行一个对象时，通常可以直接用 load_dataset("json", data_files=...)；如果文件根对象里还有一个 data 数组，就要用 field="data" 指向真正的样本集合。多个文件则应在 data_files 中明确写出 train、validation 等 split 名称。

官方地址：https://huggingface.co/docs/datasets/loading

最小判断口诀是：先看 JSON 的根，决定要不要填 field；再看文件数量，决定是否用 data_files 字典；最后用 split 选择单个 Dataset，并用 features 或 dataset.features 处理字段类型。

先看 JSON 的根结构，再决定 field

Datasets 的 JSON loader 可以读取 JSON 和 JSONL 文件。最省事的形状是 JSONL：每一行都是一条记录，每条记录的顶层键会成为 Dataset 的字段。例如下面的文件有两个样本，字段是 text 和 label：

{"text":"第一条文本","label":0}
{"text":"第二条文本","label":1}

如果 JSON 是一个根对象，样本放在 data 数组中，就不能把整个根对象当成行记录。此时用 field="data" 告诉 loader 从哪个字段取出样本数组。这个参数解决的是“样本在哪一层”，不是“字段叫什么”。

{
  "version": "1.0",
  "data": [
    {"text": "第一条文本", "label": 0},
    {"text": "第二条文本", "label": 1}
  ]
}

可以先用下面的最小写法判断加载结果。这里没有把输出写死成某种运行结果，而是通过 column_names、features 和一条样本记录观察字段推断结果：

from datasets import load_dataset

# JSONL 每行就是一条记录时，不需要 field 参数
dataset = load_dataset("json", data_files="records.json")

# 先看字段名和推断出的类型，再把它交给后续预处理
print(dataset.column_names)
print(dataset.features)
print(dataset[0])

如果你的文件是上面的嵌套根对象，改成下面的调用即可：

from datasets import load_dataset

# 根对象中的 data 数组才是样本集合，因此显式指定 field
dataset = load_dataset(
    "json",
    data_files="records.json",
    field="data",
)

# 用字段定义检查 loader 是否进入了预期的样本层级
print(dataset.features)

最小配方：单个 JSON 文件怎样得到 Dataset

单文件场景的核心参数只有两个：第一个位置参数是 json，data_files 指向本地文件或远程文件。文件扩展名会帮助 Datasets 选择对应的加载器，但字段是否在根对象的嵌套数组里，仍然需要你根据实际 JSON 形状决定 field。

如果后面要把它送进训练或 map 预处理，建议在加载后立刻记录字段名。这样当字段为空、列名不对或样本层级错了时，问题会在入口暴露，而不会拖到更后面的 tokenizer 或 collator 才报错。

from datasets import load_dataset

def load_json_records(path, nested_field=None):
    # 只有根对象包着样本数组时才传 field，普通 JSONL 传 None
    options = {
        "path": "json",
        "data_files": path,
    }
    if nested_field:
        # field 的值必须是 JSON 根对象中承载样本数组的键名
        options["field"] = nested_field

    dataset = load_dataset(**options)

    # 入口处记录字段定义，便于区分文件形状问题和后处理问题
    print("columns:", dataset.column_names)
    print("features:", dataset.features)
    return dataset


# JSONL 或根数组文件：不指定嵌套字段
plain_dataset = load_json_records("records.json")

# 根对象为 {"data": [...]} 时：指定实际样本字段
nested_dataset = load_json_records("wrapped.json", nested_field="data")

上面的函数只封装了“文件形状 → loader 参数”的映射，没有替你猜测字段。对外部数据尤其要先确认根对象到底是数组、对象还是 JSONL；不要因为文件后缀是 .json 就默认所有 JSON 都有同一种结构。

用 data_files 把文件绑定到 split

当训练集和验证集分别放在不同文件中时，推荐让 data_files 的字典键直接表达 split。这样加载结果通常是一个 DatasetDict，通过 dataset["train"] 或 dataset["validation"] 取得具体的 Dataset。

from datasets import load_dataset

# 字典键就是 split 名称，文件路径是对应的数据来源
data_files = {
    "train": "train.json",
    "validation": "validation.json",
}

# 同一份 schema 入口下管理两个 split，便于后续统一 map
dataset_dict = load_dataset("json", data_files=data_files)

# 按调用方需要取出单个 Dataset，而不是把 DatasetDict 当成样本表
train_dataset = dataset_dict["train"]
validation_dataset = dataset_dict["validation"]

print(train_dataset.features)
print(validation_dataset.features)

如果调用方只需要一个 split，可以在加载时直接填写 split，避免后面再从字典取值：

from datasets import load_dataset

# 直接得到 train 对应的 Dataset，适合单 split 处理函数
train_dataset = load_dataset(
    "json",
    data_files={"train": "train.json", "validation": "validation.json"},
    split="train",
)

# 需要验证集时，改为 split="validation"，参数语义保持不变
validation_dataset = load_dataset(
    "json",
    data_files={"train": "train.json", "validation": "validation.json"},
    split="validation",
)

这里有一个常见的变量边界：不填写 split 时，调用方要准备接收带 split 的集合；填写 split 时，调用方接收的是单个 Dataset。若下游函数只接受行记录表，提前选择 split 会让接口更清楚。

字段推断不稳定时，用 features 约束类型

JSON loader 会根据记录内容构造字段定义。你可以用 dataset.features 观察结果；如果数据契约已经确定，还可以显式传入 Features，把字段类型写成加载入口的一部分。这样做适合训练集和验证集必须保持同一字段类型的场景。

from datasets import Features, Value, load_dataset

# 先把数据契约写清楚，避免不同文件把同一列推成不同类型
features = Features({
    "text": Value("string"),
    "label": Value("int64"),
})

# 仍然由 JSON loader 读取内容，但字段类型由 features 明确约束
dataset = load_dataset(
    "json",
    data_files="records.json",
    features=features,
)

# 入口处再次查看最终字段定义，确认列名与类型和契约一致
print(dataset.features)

features 不是修复脏 JSON 的转换器。如果文件里的值无法按声明的类型读取，应该回到源文件处理，而不是在后续代码里默默把异常值转成字符串。对于字段结构本身还没有稳定下来的探索阶段，先省略 features，观察推断结果通常更合适。

一份可复用的加载函数：把 field 和 split 变成显式参数

在项目里，最值得固定的是入口契约：调用者要明确文件路径、嵌套字段和目标 split。下面这个版本同时兼容单文件、多个 split 和嵌套 data 数组，返回值始终是调用方指定的对象。

from datasets import load_dataset

def load_json_dataset(data_files, *, field=None, split=None, features=None):
    # 把可选参数统一放入调用配置，避免不同分支漏传 field
    options = {
        "path": "json",
        "data_files": data_files,
    }
    if field is not None:
        # 只有根对象包裹样本数组时才设置 field
        options["field"] = field
    if features is not None:
        # 固定字段类型时显式传入 Features 契约
        options["features"] = features
    if split is not None:
        # 填 split 就返回单个 Dataset，否则保留 DatasetDict 结构
        options["split"] = split

    return load_dataset(**options)


# 多 split 文件：返回值保留 train 和 validation 两个键
all_splits = load_json_dataset({
    "train": "train.json",
    "validation": "validation.json",
})

# 只取验证集：返回值是单个 Dataset
validation = load_json_dataset(
    {"train": "train.json", "validation": "validation.json"},
    split="validation",
)

# 根对象为 {"data": [...]} 时，把样本所在字段写在入口
wrapped = load_json_dataset("wrapped.json", field="data")

遇到列为空或 split 不对，按四项信息排查

这类问题不需要一开始就修改 tokenizer 或训练循环，先把加载入口的四项信息对齐：

• 根结构：每行是否是一条对象，或者样本是否被包在根对象的某个数组字段里。
• field：只有嵌套数组需要它；键名写错时，loader 取不到真正的样本层。
• data_files：字典键决定 split 名称，后续访问必须使用完全相同的键。
• split：填写后返回单个 Dataset，不填写时要按 DatasetDict 的方式取 split。

如果字段名看起来正确但类型不一致，再查看 dataset.features。当训练和验证文件的字段契约已经明确时，使用同一份 Features；当数据仍在探索阶段，先保留推断结果并修正源 JSON。不要把“DatasetDict 还是 Dataset”的返回层级问题误判成字段缺失。

常见问题

JSON 数组和 JSONL 应该怎么选？

如果数据按行追加、体量较大或需要流式处理，JSONL 更容易逐条组织；如果已有标准 JSON 文件，先判断样本是不是根数组或嵌套数组，再决定是否填写 field。关键不是后缀，而是样本记录所在的层级。

为什么加载后有 train，找不到 validation？

检查 data_files 是否真的使用了 {"validation": "..."} 这样的键，并确认读取时访问的是同名 split。文件名叫 validation 并不会自动替代字典键表达 split。

什么时候应该填写 features？

当字段类型是稳定的数据契约，且多个文件必须保持一致时填写；当你还在探索源数据结构时，先查看 dataset.features 再决定是否约束，避免把源数据问题隐藏在类型转换里。

归纳起来，Hugging Face Datasets 从 JSON 加载数据集可以拆成一个很短的决策：JSONL 或直接样本文件就省略 field，嵌套样本数组就指向它；单文件可以直接拿 Dataset，多文件用 data_files 建立 split，再按需填写 split 取出单个对象。入口把这几项写清楚，后面的预处理和训练代码就不必反复猜测数据形状。