Hugging Face Datasets flatten 怎么展开嵌套字段并保留特征类型

Hugging Face Datasets 里的嵌套字典字段可以用 Dataset.flatten() 展开成普通列，列名按父字段和子字段拼成点号路径，例如 meta.stats.score。如果只想查看展开后的 schema，可以调用 ds.features.flatten()；它返回新的 Features 描述，不会替你改写数据集。实际使用时，先用 Features 明确字段类型，再决定是立刻展开，还是把嵌套结构留到后面的 map 阶段。

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

先分清两个 flatten 处理的对象

最容易混淆的是把 ds.features.flatten() 当成数据转换。它只遍历当前特征树，返回一份扁平后的 Features；真正把嵌套列变成数据集顶层列，要调用 ds.flatten()。两者通常成对出现：先看 schema 会生成什么名字，再决定是否创建扁平数据集。

例如，顶层字段 meta 里有 source 和 stats，而 stats 里又有 score。展开后的名字会沿着结构拼成 meta.source 和 meta.stats.score，原来的 meta 字典列不再作为一个整体保留。

用 Features 先固定嵌套字段类型

如果数据来自 JSON 或多来源拼接，建议在创建 Dataset 时显式写出 Features。这样做的重点不是让代码更长，而是把后续展开的类型依据固定下来：字符串仍是 Value("string")，分数可以明确为 float32，计数可以明确为 int32。

from datasets import Dataset, Features, Value

# 用嵌套字典声明数据结构，避免自动推断把不同来源的类型混在一起。
features = Features({
    "id": Value("string"),
    "text": Value("string"),
    "meta": {
        "source": Value("string"),
        "stats": {
            "score": Value("float32"),
            "tokens": Value("int32"),
        },
    },
})

# 每条记录的嵌套键要和 Features 的层级对应。
rows = [
    {
        "id": "a-001",
        "text": "flatten example",
        "meta": {"source": "wiki", "stats": {"score": 0.92, "tokens": 18}},
    },
    {
        "id": "a-002",
        "text": "nested fields",
        "meta": {"source": "book", "stats": {"score": 0.81, "tokens": 11}},
    },
]

ds = Dataset.from_list(rows, features=features)
print(ds.features)

此时 ds.features 仍然是嵌套描述。它保存了每个叶子字段的类型，也保留了字段之间的父子关系。后面调用 flatten() 时，库会根据这个 schema 生成扁平列，而不是把所有值都当作无类型的 Python 对象。

展开后按点号路径读取列

准备好 schema 后，分别观察特征和数据结果。features.flatten() 可以先用于规划下游字段；ds.flatten() 返回一个新的 Dataset，原来的 ds 不会被原地改成扁平状态。

# 只查看展开后的特征名，适合在构造 map 逻辑前确定列路径。
flat_features = ds.features.flatten()
print(flat_features)

# 真正生成新的扁平数据集，原 ds 仍保留嵌套结构。
flat_ds = ds.flatten()
print(flat_ds.column_names)
print(flat_ds["meta.source"])
print(flat_ds["meta.stats.score"])

# 处理前先确认目标列存在，避免字段改名后静默取到错误数据。
required = {"meta.source", "meta.stats.score"}
missing = required.difference(flat_ds.column_names)
if missing:
    raise KeyError(f"缺少展开列: {sorted(missing)}")

对这组数据，列名会包含 id、text、meta.source、meta.stats.score 和 meta.stats.tokens。读取时要使用完整的点号字符串；flat_ds["meta"] 这种按原字典列读取的写法不再适用。

List 和多层字段不会被随意打散

嵌套字段里经常还有列表，例如一条样本带多个标签或多个答案。flatten() 主要展开字典层级，列表特征本身仍会作为列表保存。也就是说，answers.text 可能是 List(Value("string"))，它不会因为列名变成点号路径就自动变成多行记录。

from datasets import Dataset, Features, List, Value

# List 保持一条样本对应一个列表，flatten 只负责移除外层字典。
list_features = Features({
    "question": Value("string"),
    "answers": {
        "text": List(Value("string")),
        "start": List(Value("int32")),
    },
})

list_ds = Dataset.from_list([
    {
        "question": "What is flatten?",
        "answers": {"text": ["a method"], "start": [0]},
    },
], features=list_features)

# 展开后 answers.text 仍是一行中的列表，不要把它误当成字符串。
flat_list_ds = list_ds.flatten()
print(flat_list_ds.features["answers.text"])
print(flat_list_ds["answers.text"])

如果业务确实需要一条答案一行，应在 flatten 之后另做显式的行级转换，并重新设计字段约束；不要把这个需求交给 flatten() 猜测。这样能避免后续训练、批处理或导出时意外改变样本数量。

用 max_depth 控制展开边界

默认情况下，嵌套字典会继续向下展开。遇到结构很深的元数据，或者下游只需要第一层字段时，可以用 max_depth 限制展开深度。这个参数是结构边界，不是类型转换开关；限制深度后，未继续展开的部分仍然可能以嵌套特征形式存在。

# 只展开到第一层，保留更深的 stats 结构以便后续专门处理。
shallow_features = ds.features.flatten(max_depth=1)
shallow_ds = ds.flatten(max_depth=1)

print(shallow_features)
print(shallow_ds.column_names)

可以把 max_depth 看成 API 设计里的兼容边界：如果下游字段合同只承诺 meta.source，就不必让更深的实验字段变成新的公共列；如果后续任务需要精确读取 meta.stats.score，则应使用足够的深度并把该路径写进字段清单。

把 flatten 放在 map 流程的合适位置

是否立即展开，取决于调用方的输入合同。需要按列名批量筛选、导出或交给只识别顶层列的处理器时，可以先 flat_ds = ds.flatten()；需要同时读取多个嵌套字段、保留一条完整记录或按原结构做条件判断时，则可以先保留 ds，在 map 函数中访问嵌套对象。

def add_quality_flag(example):
    # 这里保留嵌套访问，适合规则同时依赖 score 和 tokens。
    stats = example["meta"]["stats"]
    example["quality"] = stats["score"] >= 0.8 and stats["tokens"] >= 10
    return example

# map 完成结构化判断后，再按需要展平给只接受顶层列的下游。
marked_ds = ds.map(add_quality_flag)
export_ds = marked_ds.flatten()
print(export_ds["quality"])

接口设计上，最好把“嵌套输入”与“扁平输出”看成两个明确阶段。这样当字段名称变化时，只需要在展开边界或字段清单处调整，不会让每个 map 回调都依赖一套隐含的点号命名规则。

常见问题

flatten 会把数据转换成 Pandas DataFrame 吗？

不会。它返回的是 Hugging Face Dataset 或 Features 结构，列仍由 Datasets 和 Arrow schema 管理，不是 Pandas 的对象列展开。

为什么展开后找不到原来的 meta 列？

字典列会被子字段替换，读取时应改用 meta.source、meta.stats.score 这样的完整路径。

List 字段能不能被 flatten 成多行？

不能直接依赖它完成行爆炸。List 特征仍保持列表语义，需要另写明确的行级转换，并重新确认样本数量和字段类型。