Transformers 怎样用 word_ids 对齐词级标注

Transformers 的 word_ids() 给出每个 token 对应的原始词索引。对已经按词标注的数据，使用 Fast tokenizer 并设置 is_split_into_words=True，再按 word_ids 把词标签映射到 token 位置；特殊 token 对应 None，通常使用 -100 忽略。一个词拆成多个子词时，还必须明确监督策略。

官方文档：https://huggingface.co/docs/transformers/en/main_classes/tokenizer

把标签错位定位到词与子词的对应关系

假设一份实体标注表每个词只有一个标签，编码后输入长度却变长，直接把原标签交给模型就会错位。这里是一个用于说明的排查场景，不是亲历训练事故。我会先检查编码映射，再看模型，因为标签长度差异往往在进入模型前就已经产生。

原因包括特殊 token 占位，以及一个词被拆成多个子词。词索引与 token 索引因此不是同一套坐标。word_ids 的数值是词位置，不是词表中的 token ID；同一词的多个子词会对应同一个词索引。

先固定输入粒度与编码器类型

本例采用已经切好的英语词列表，标签0表示非实体，1表示地点实体起始。模型名称只用于加载分词器，不需要下载模型权重。实际项目应选择与训练模型相匹配的 tokenizer；中文数据的词粒度也应以标注规范为准，不能默认按空格拆分。

from transformers import AutoTokenizer

# 每个样本的词列表与词级标签必须等长。
batch = {
    "tokens": [
        ["Visit", "Reykjavik", "today"],
        ["Cloud", "services", "expand"],
    ],
    "tags": [
        [0, 1, 0],
        [0, 0, 0],
    ],
}
tokenizer = AutoTokenizer.from_pretrained(
    "google-bert/bert-base-cased", use_fast=True
)
if not tokenizer.is_fast:
    raise ValueError("本例需要提供 word_ids 的 Fast tokenizer")

for words, tags in zip(batch["tokens"], batch["tags"]):
    if len(words) != len(tags):
        raise ValueError("词数与词级标签数不一致")

# 输入已经按词切分，明确告知分词器每一项是一个原始词。
encoded = tokenizer(
    batch["tokens"],
    is_split_into_words=True,
    truncation=True,
    max_length=64,
)

以上未预设具体词会拆成几个子词，也没有声称已执行。实际观察时可以同时打印 tokens 与 word_ids，但不能把特定词表版本的切分结果硬编码成映射规则。

只为每个词的第一个子词保留标签

下面采用首子词监督：每个词的第一个 token 使用词标签，其余子词忽略。这样的取舍让每个保留下来的词只贡献一次标签监督，便于先把映射讲清楚；它不是所有任务的唯一方案。

aligned_labels = []

for sample_index, word_tags in enumerate(batch["tags"]):
    # batch_index 选择编码批次中的对应样本。
    mapping = encoded.word_ids(batch_index=sample_index)
    labels = []
    previous_word = None

    for word_index in mapping:
        if word_index is None:
            # CLS、SEP 等特殊位置不参与普通词级监督。
            labels.append(-100)
        elif word_index != previous_word:
            labels.append(word_tags[word_index])
        else:
            # 同一个词的后续子词使用忽略值。
            labels.append(-100)
        previous_word = word_index

    aligned_labels.append(labels)

encoded["labels"] = aligned_labels
# 示例阶段可观察每行标签数是否与 input_ids 数一致。
for ids, labels in zip(encoded["input_ids"], encoded["labels"]):
    print(len(ids), len(labels))

-100 的作用来自训练损失的忽略约定，并非 word_ids 自动替你填充的标签。使用自定义损失函数时，要让忽略值与损失配置保持一致，不能只在预处理里写入一个数字就假定训练会自动跳过。

处理批量、截断与补齐边界

批量输入必须对每个样本使用对应的 batch_index，且 previous_word 要在每个样本开始时重置。截断后只给实际保留的 token 生成标签，不把被截去的原词标签补回 input_ids 后面。本文代码只处理普通单序列批量编码，没有开启溢出窗口。

若改用 return_overflowing_tokens 处理长文，编码条目数量可能多于原始样本数，需要借助窗口到原样本的映射取标签，并明确窗口首个子词的策略。若改成句对输入，不同序列中的词索引也需要结合 sequence_ids 判断，不能照搬单序列逻辑。

需要组成等长张量时，可以使用 DataCollatorForTokenClassification 同步补齐输入与标签。我的选择是先保持未补齐样本便于观察，再让专用 collator 负责批次补齐，避免手工把标签补成普通类别0。

保留监督策略并避免复发

如果选择对全部子词都打标签，应把规则写进数据处理配置。BIO 标注中的 B 类别是否在后续子词转成 I 类别，需要依据项目标签体系处理，不能直接复制同一个数字后就认为序列语义正确。训练和评估也要使用一致的忽略位置。

word_ids 是字符偏移吗？不是，字符范围需要相应偏移映射。所有 tokenizer 都能调用吗？这种对齐依赖 Fast tokenizer 提供的编码资料。必须用首子词方案吗？不必，但替代策略必须同时约定标签转换、损失和评估处理。