Hugging Face Datasets 怎样按特征层级展开嵌套字段

Hugging Face Datasets 可以用 Dataset.flatten() 把结构体（struct）列中的子字段展开为独立列，名称沿用“父字段.子字段”的层级形式。若只是查看展开后的特征定义，可以使用 dataset.features.flatten()；它返回特征定义，不会代替数据集列转换。

先明确下游要的是什么：把嵌套字段变成列，与把一条记录中的列表拆成多行，是两种不同的数据处理。flatten解决前者，不能把名字理解成“任意嵌套内容全部摊平”。

官方文档：https://huggingface.co/docs/datasets/process

按下游列需求选择方案

假设训练前的样本有id、正文和meta，其中meta保存source和language。评估脚本希望直接访问meta.source，而原始采集格式更适合保留meta字典。这时可以保留原始Dataset，在预处理入口派生一个展开后的Dataset。

这组选择不依赖部署在云端还是本地。对已有嵌套数据，优先选择能直接表达列转换的操作，避免为了几个结构字段先把整批数据转成大量Python字典，再手写重复拷贝逻辑。这里没有承诺具体速度或内存节省比例。

先看features，再判断“嵌套”是什么

Dataset的features描述列的类型。字典样式的struct可以包含子字段，列表列则保存一个序列。列表元素本身也可能有结构，但不能由“外观像嵌套JSON”推出flatten会对每个元素递归拆行。

此外，字符串里存着JSON文本也不是struct。若采集端把meta保存成一段文本，需要先按业务规则解析和构建正确的类型，不能指望flatten自动理解字符串的内容。

用一个完整例子展开数据列

下面在内存中创建两条原创样本，不下载Hub数据，也不访问凭据。labels是列表列，meta是包含两个字符串子字段的结构列。示例未实际执行，打印语句用于读者观察自己环境中的结构。

from datasets import Dataset

# 原始采集结构：meta为结构字段，labels为列表字段。
source = Dataset.from_list([
    {
        "id": "sample-a",
        "text": "设备维护记录",
        "meta": {"source": "workshop", "language": "zh"},
        "labels": ["maintenance", "device"],
    },
    {
        "id": "sample-b",
        "text": "巡检交接摘要",
        "meta": {"source": "inspection", "language": "zh"},
        "labels": ["inspection"],
    },
])

# 特征定义和数据列分开观察，避免把类型对象误当成数据集。
schema_only = source.features.flatten()
flat = source.flatten()

print(source.features)
print(schema_only)
print(flat.column_names)
print(flat.num_rows)

# 点号是展开后的真实列名，不是Python属性访问语法。
print(flat[0]["meta.source"])
print(flat[0]["labels"])

按本例结构推导，展开后包含id、text、meta.source、meta.language、labels，仍然是两行。第一条样本的meta.source对应workshop，labels仍然是含两个字符串的列表；这些是样例的预期语义，不是伪造的执行输出。

需要使用返回对象：写成source.flatten()却继续把原来的source交给训练脚本，容易让人以为转换没有生效。保留source与flat两个名字，也有助于明确原始层级和下游列契约各自的位置。

特征展开不等于列表拆行

schema_only是Features定义，不具有Dataset的样本读取职责。它适合帮助理解展开后的列名和类型，但不能直接替换数据集变量。实际训练数据需要展开时，传递的是flat。

本例labels第一行有两项，第二行有一项。flatten不会因此生成三行，也不会自动把id复制到每个标签。如果确实要“一标签一行”，需要另外定义空列表如何处理、父记录标识如何保留、标签之间是否存在对应关系，再写行变换。

对“结构体里有列表”和“列表里有结构体”也应分别看待。结构列展开后，子字段本身为列表时仍可以保留列表类型；列表容器不等于普通struct列。遇到复杂数据先确认实际features，不要凭JSON展示形状直接承诺输出列。

把列契约放进预处理设计

官方API提供max_depth参数，当前签名默认值为16。它用于限制展开深度；层级较深时应结合实际类型确定需要保留的结构，而不是把一个更大的值当成通用修复。不要把max_depth看成“只展开第几个指定字段”的选择器。

点号列名也会传到后续代码中。下游若要求source这样的短名称，可以在转换后明确重命名，同时处理已有同名列；不要用字符串切分随意去掉所有前缀，否则不同父字段下的source可能撞名。

# 沿用前例flat：在显式确认无重名后，才改为下游约定的短列名。
if "source" in flat.column_names:
    raise ValueError("目标列source已存在，需先确定命名策略")

training_view = flat.rename_column("meta.source", "source")
print(training_view.column_names)

大数据集还需要考虑列展开对后续保存格式、批处理函数和训练输入的影响。原始采集结构可以留在上游，展开视图服务于特定任务；不必把一次方便的预处理变成所有消费者必须接受的永久格式。

flatten_indices能展开meta吗？

不能把二者混用。flatten_indices针对数据集索引映射，本例的结构列转换使用flatten。

为什么展开后仍然有列表类型？

列表本来就是一个字段值的容器。将struct子字段提成列，不意味着把列表元素变成独立样本。

列名里的点号能用flat.meta.source访问吗？

本例使用完整列名字符串，例如读取行字典中的["meta.source"]。不要把层级命名误写成Python对象属性链。

依据：Datasets数据处理指南与Dataset及Features API参考。样本数据与预处理场景为原创示例。