Hugging Face Datasets 怎样让标签编号与模型标签映射一致

分类任务里最容易被忽略的一层，是“编号”本身也是模型接口的一部分。数据集把 0 解释成 neutral，模型却把 0 解释成 support 时，训练可能照常进行，预测结果却会整体错名。稳妥的做法是先确定一份有序标签表，再让 ClassLabel、id2label 和 label2id 都从它生成。

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

先把标签顺序定成唯一真相

ClassLabel 底层保存的是整数，names 列表的位置就是整数含义。下面把三个类别的顺序明确写成一份列表：以后看到 0，只能解释为 neutral；看到 2，只能解释为 reject。不要一会儿按字母排序，一会儿按样本首次出现顺序排序。

如果手里已经有训练好的模型，应优先读取它的既有 id2label 顺序；如果是新任务，则把业务定义写成配置文件或常量，并在数据预处理与模型初始化处共同引用。

用 ClassLabel 把字符串与整数绑在一起

原始数据常见的是字符串列，例如 neutral、support。先用 str2int 转成规范整数，再用 cast_column 把列声明为带有名称表的标签特征。这样调试时可以用 int2str 反查编号，而不是依赖人工记忆。

from datasets import ClassLabel, Dataset

# 这份顺序同时服务数据集和模型，不能在两个位置各写一份
label_names = ["neutral", "support", "reject"]
label_feature = ClassLabel(names=label_names)

ds = Dataset.from_dict({
    "text": ["样本甲", "样本乙", "样本丙"],
    "label_name": ["support", "neutral", "reject"],
})

def encode_label(row):
    # 统一从名称表取编号，遇到拼写错误会在这里暴露
    return {"labels": label_feature.str2int(row["label_name"])}

ds = ds.map(encode_label, remove_columns=["label_name"])
# 声明 labels 的语义，保证后续可用 int2str 反查
ds = ds.cast_column("labels", label_feature)

assert ds[0]["labels"] == label_feature.str2int("support")
assert label_feature.int2str(ds[1]["labels"]) == "neutral"

这里的关键不是把列名改成 labels，而是让整数生成和名称解释都来自同一份 ClassLabel。若原始列已经是整数，不能只更换 names 就假设底层编号被重排；应先列出旧 ID 到规范名称的显式对应关系，再用映射函数改写整数。

让模型配置复用同一份映射

Transformers 配置中的 id2label 是“索引到名称”，label2id 是“名称到索引”。不要手工维护三套字典，直接从 label_names 派生：

from transformers import AutoConfig

# 从官方模型配置加载基础结构，标签契约仍由本任务决定
config = AutoConfig.from_pretrained("distilbert/distilbert-base-uncased")
config.id2label = {index: name for index, name in enumerate(label_names)}
config.label2id = {name: index for index, name in enumerate(label_names)}
config.num_labels = len(label_names)  # 分类头的类别数必须与名称表一致

# 用断言阻止数据集与模型的顺序在训练前悄悄分叉
assert [config.id2label[i] for i in range(config.num_labels)] == label_names
assert {name: config.label2id[name] for name in label_names} == {
    name: index for index, name in enumerate(label_names)
}

如果加载的是已有微调模型，先打印其配置再决定是否覆盖。覆盖配置并不会重排已经训练好的分类头权重；旧模型的输出编号必须与新的名称表保持原有语义，否则应重新训练或显式迁移分类头。

训练前做双向核对

最后检查四个边界：名称集合、整数范围、类别数和未知标签。ClassLabel 的有效编号应落在 0 到 num_labels - 1；负数可代表缺失值，但不能直接交给 int2str 做名称转换。对于多标签任务，还要确认每个样本的标签容器和模型损失函数约定一致，不能把单标签的一个整数悄悄当成多标签数组。

实用的核对顺序是：先从 ds.features["labels"] 读取名称表，再与 config.id2label 按索引逐项比较，最后抽取一小批样本执行名称到编号、编号到名称的往返转换。任何一项不一致，都应在训练开始前修正，而不是等评估报告出现“类别整体错位”后再猜原因。

常见问题

只调用 cast_column 能自动完成标签重排吗？不能。它主要是把列声明为目标特征；如果旧整数含义不同，仍要先通过显式映射改写数据。

为什么不直接用数据集里出现过的标签排序？因为不同切分可能缺少某个类别，首次出现顺序也会随采样变化，最终导致训练、验证和模型配置使用不同编号。

小结

把标签对齐理解成一个小型接口契约即可：先固定有序名称表，再由它生成 ClassLabel、id2label、label2id 和 num_labels，并用双向断言检查边界。这样数据预处理改变时，模型输出的名称语义仍然稳定。