Hugging Face Transformers 分词分类（Token Classification）实战：用 DistilBERT 微调 NER 并源码级解析标签对齐原理

本文以 Transformers 官方任务指南中的 Token Classification（分词分类）主题为主线，完整讲解如何用 DistilBERT 在 WNUT 17 数据集上微调命名实体识别（NER）模型并用于推理：涵盖数据集加载、is_split_into_words 子词切分与标签对齐（-100 忽略机制）、DataCollatorForTokenClassification 动态填充、seqeval 评估指标、Trainer 训练参数配置与 pipeline("ner") 推理。读完后你将掌握一条可复制运行的完整 NER 微调流程，并理解子词切分后"词-标签错位"问题在源码层面是如何被解决的。

1. 任务定义：为每个 token 单独打标签

分词分类的目标是给句子里每一个 token 单独赋予一个标签。其最常见形态是命名实体识别（NER）：为句子中的每个实体确定标签，例如人名（person）、地名（location）、组织（group/corporation）。

与序列分类不同，Token Classification 的预测粒度是逐 token 的：模型输出形状为 [batch, sequence_length, num_labels] 的 logits，训练时用 CrossEntropyLoss（带 ignore_index=-100）对每个位置独立计算损失。

官方指南以两个目标组织全文：

1. 用 DistilBERT 在 WNUT 17 数据集上微调，识别新实体类别（WNUT 17 含 creative-work、product 等 Web 场景下的新实体，适合检验模型的开放世界泛化能力）；
2. 使用微调后的模型进行精确推理。

1.1 环境准备

在开始前，安装所有必需库：

pip install transformers datasets evaluate seqeval

如需将模型推送到 Hub，先登录账号：

>>> from huggingface_hub import notebook_login

>>> notebook_login()

2. 加载 WNUT 17 数据集与标签体系

第一步通过 🤗 Datasets 加载 WNUT 17：

>>> from datasets import load_dataset

>>> wnut = load_dataset("wnut_17")

查看一条训练样本，它包含 id、tokens（已按词切分的文本）和 ner_tags（与 token 一一对应的标签编号）三个字段：

>>> wnut["train"][0]
{'id': '0',
 'ner_tags': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 7, 8, 8, 0, 7, 0, 0, 0, 0, 0, 0, 0, 0],
 'tokens': ['@paulwalk', 'It', "'s", 'the', 'view', 'from', 'where', 'I', "'m", 'living', 'for', 'two', 'weeks', '.', 'Empire', 'State', 'Building', '=', 'ESB', '.', 'Pretty', 'bad', 'storm', 'here', 'last', 'evening', '.']
}

ner_tags 中的每个数字对应一个实体类别。把数字还原为类别名，可以看到 WNUT 17 的 13 个标签：

>>> label_list = wnut["train"].features[f"ner_tags"].feature.names
>>> label_list
[
    "O",
    "B-corporation",
    "I-corporation",
    "B-creative-work",
    "I-creative-work",
    "B-group",
    "I-group",
    "B-location",
    "I-location",
    "B-person",
    "I-person",
    "B-product",
    "I-product",
]

这是典型的 BILO 体系（本数据集只用了 B 和 I）：

• B- 表示实体的开头 token；
• I- 表示 token 位于同一实体内部（例如 State 是 Empire State Building 的一部分，因此标签为 I-location）；
• 0（即 O）表示该 token 不属于任何实体。

这一编号体系后面会在训练配置中复用：id2label / label2id 必须与它严格一致。

3. 预处理：子词切分后的标签对齐（本任务最核心的一步）

3.1 为什么要对齐

加载 DistilBERT 分词器处理 tokens 字段：

>>> from transformers import AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased")

tokens 字段看似已经"切好词"了，但那只是按词切分，尚未做**子词（subword）**切分。必须设置 is_split_into_words=True，告诉分词器输入是词列表而非原始字符串：

>>> example = wnut["train"][0]
>>> tokenized_input = tokenizer(example["tokens"], is_split_into_words=True)
>>> tokens = tokenizer.convert_ids_to_tokens(tokenized_input["input_ids"])
>>> tokens
['[CLS]', '@', 'paul', '##walk', 'it', "'", 's', 'the', 'view', 'from', 'where', 'i', "'", 'm', 'living', 'for', 'two', 'weeks', '.', 'empire', 'state', 'building', '=', 'es', '##b', '.', 'pretty', 'bad', 'storm', 'here', 'last', 'evening', '.', '[SEP]']

对齐问题由此产生：

1. 分词器额外注入了 [CLS] 和 [SEP] 两个特殊 token，它们在原始 ner_tags 中不存在对应项；
2. 一个词可能被拆成多个子词（@paulwalk → @、paul、##walk，ESB → es、##b），而原始标签只有一个。

3.2 对齐的三条规则

Transformers 提供 word_ids 方法（从源码看，它返回一个列表，把每个 token 映射回其所属词的索引：特殊 token 映射为 None，同词的多个子词映射为同一个词索引）。基于它可以按三条规则重对齐：

1. 用 word_ids() 把每个 token 关联回它对应的原始词；
2. 给特殊 token（[CLS]、[SEP]）赋标签 -100——这是 PyTorch CrossEntropyLoss 的 ignore_index 约定值，这些位置不参与损失计算；
3. 一个词只标注其第一个子词，其余子词赋 -100。

完整实现如下（truncation=True 同时保证输入不超过 DistilBERT 的序列上限）：

>>> def tokenize_and_align_labels(examples):
...     tokenized_inputs = tokenizer(examples["tokens"], truncation=True, is_split_into_words=True)

...     labels = []
...     for i, label in enumerate(examples[f"ner_tags"]):
...         word_ids = tokenized_inputs.word_ids(batch_index=i)  # 把 token 关联到对应的词
...         previous_word_idx = None
...         label_ids = []
...         for word_idx in word_ids:
...             if word_idx is None:               # 规则2：特殊 token 置 -100
...                 label_ids.append(-100)
...             elif word_idx != previous_word_idx: # 规则3：只标注该词的第一个子词
...                 label_ids.append(label[word_idx])
...             else:
...                 label_ids.append(-100)
...             previous_word_idx = word_idx
...         labels.append(label_ids)

...     tokenized_inputs["labels"] = labels
...     return tokenized_inputs

用 Dataset.map 批量应用，batched=True 可显著加速：

>>> tokenized_wnut = wnut.map(tokenize_and_align_labels, batched=True)

3.3 动态填充：DataCollatorForTokenClassification

组 batch 时使用 DataCollatorForTokenClassification。它的关键设计是动态填充：把每条句子填充到 batch 内的最长长度，而不是把整个数据集填充到全局最大长度，从而避免大量无意义的 padding 计算：

>>> from transformers import DataCollatorForTokenClassification

>>> data_collator = DataCollatorForTokenClassification(tokenizer=tokenizer)

从源码看，该 Collator 的几个要点（src/transformers/data/data_collator.py）：

• padding 默认为 True/'longest'，即填充到 batch 内最长序列；
• label_pad_token_id 默认为 -100，与上文的忽略约定完全一致——填充出来的标签位置同样被损失函数跳过；
• 填充方向跟随 tokenizer.padding_side：右填充时把 -100 追加到 label 尾部，左填充时前置（见 data_collator.py#L307-L314），保证 padding 位置的标签与输入严格同长对齐。

4. 评估：seqeval 与 compute_metrics

训练过程中嵌入指标，可以在每个评估周期直观看到模型效果。用 🤗 Evaluate 加载 seqeval（它输出 precision、recall、F1 和 accuracy 四项总体指标）：

>>> import evaluate

>>> seqeval = evaluate.load("seqeval")

seqeval 以"完整实体"为单位计分（例如 Empire State Building 作为一个实体整体判断对错），因此 compute_metrics 需要先把逐 token 的预测转回实体序列——argmax 取每个位置的最高分类别，再过滤掉 -100 位置：

>>> import numpy as np

>>> labels = [label_list[i] for i in example[f"ner_tags"]]

>>> def compute_metrics(p):
...     predictions, labels = p
...     predictions = np.argmax(predictions, axis=2)

...     true_predictions = [
...         [label_list[p] for (p, l) in zip(prediction, label) if l != -100]
...         for prediction, label in zip(predictions, labels)
...     ]
...     true_labels = [
...         [label_list[l] for (p, l) in zip(prediction, label) if l != -100]
...         for prediction, label in zip(predictions, labels)
...     ]

...     results = seqeval.compute(predictions=true_predictions, references=true_labels)
...     return {
...         "precision": results["overall_precision"],
...         "recall": results["overall_recall"],
...         "f1": results["overall_f1"],
...         "accuracy": results["overall_accuracy"],
...     }

注意 p 是 (predictions, labels) 元组，predictions 是模型 logits（[batch, seq_len, 13]），np.argmax(predictions, axis=2) 沿类别维取最大值即得到逐 token 的预测编号。该函数在下一步训练配置中直接使用。

5. 训练：id2label/label2id 与 Trainer 配置

5.1 标签映射表

训练前先准备编号与标签的双向映射。它与第 2 节的 label_list 顺序一一对应，num_labels=13 由它决定：

>>> id2label = {
...     0: "O",
...     1: "B-corporation",
...     2: "I-corporation",
...     3: "B-creative-work",
...     4: "I-creative-work",
...     5: "B-group",
...     6: "I-group",
...     7: "B-location",
...     8: "I-location",
...     9: "B-person",
...     10: "I-person",
...     11: "B-product",
...     12: "I-product",
... }
>>> label2id = {
...     "O": 0,
...     "B-corporation": 1,
...     "I-corporation": 2,
...     "B-creative-work": 3,
...     "I-creative-work": 4,
...     "B-group": 5,
...     "I-group": 6,
...     "B-location": 7,
...     "I-location": 8,
...     "B-person": 9,
...     "I-person": 10,
...     "B-product": 11,
...     "I-product": 12,
... }

从源码看，id2label 与 label2id 是模型 config 上的一等字段（src/transformers/configuration_utils.py#L223-L228），保存模型时会被写入 config.json——这也是为什么推理阶段可以直接用 model.config.id2label 把预测编号转回文本标签（见第 6 节）。

（如果你还不熟悉 Trainer 微调流程，可先阅读 PyTorch Trainer 训练教程。）

5.2 加载模型

用 AutoModelForTokenClassification 加载 DistilBERT，指定类别数与标签映射：

>>> from transformers import AutoModelForTokenClassification, TrainingArguments, Trainer

>>> model = AutoModelForTokenClassification.from_pretrained(
...     "distilbert/distilbert-base-uncased", num_labels=13, id2label=id2label, label2id=label2id
... )

num_labels=13 决定了模型分类头（SequenceClassificationHead 类结构）的输出维度：预训练编码器后接一个 Linear(hidden_size, 13) 投影，输出逐 token 的类别 logits。

5.3 训练参数与启动

剩余三步：配置 TrainingArguments、组装 Trainer、调用 train()。

>>> training_args = TrainingArguments(
...     output_dir="my_awesome_wnut_model",
...     learning_rate=2e-5,
...     per_device_train_batch_size=16,
...     per_device_eval_batch_size=16,
...     num_train_epochs=2,
...     weight_decay=0.01,
...     eval_strategy="epoch",
...     save_strategy="epoch",
...     load_best_model_at_end=True,
...     push_to_hub=True,
... )

>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=tokenized_wnut["train"],
...     eval_dataset=tokenized_wnut["test"],
...     processing_class=tokenizer,
...     data_collator=data_collator,
...     compute_metrics=compute_metrics,
... )

>>> trainer.train()

参数要点说明：

参数	取值	说明
output_dir	"my_awesome_wnut_model"	唯一必填项，模型与 checkpoint 的本地保存位置
learning_rate	2e-5	微调预训练编码器的常用量级
per_device_train_batch_size / per_device_eval_batch_size	16	每设备训练/评估 batch 大小
num_train_epochs	2	训练轮数
weight_decay	0.01	权重衰减，抑制过拟合
eval_strategy	"epoch"	每个 epoch 结束时跑一次 seqeval 评估
save_strategy	"epoch"	每个 epoch 保存一次 checkpoint
load_best_model_at_end	True	训练结束自动加载历史最优 checkpoint（需与评估策略配套）
push_to_hub	True	训练完成后推送到 Hugging Face Hub（需已登录）

Trainer 的组装中，train_dataset/eval_dataset 使用第 3 节对齐好的 tokenized_wnut 分片，data_collator 提供动态填充，compute_metrics 即第 4 节定义的 seqeval 函数——训练、评估、保存三条链路在这里闭环。

训练完成后，用 push_to_hub 分享模型：

>>> trainer.push_to_hub()

如需更详细的 NER 微调案例（含数据可视化、不同 base 模型对比等），可参考仓库中的官方示例脚本 examples/pytorch/token-classification/run_ner.py 与 examples/pytorch/token-classification/README.md。

6. 推理：pipeline 与手动前向两种姿势

6.1 用 pipeline("ner") 一行推理

最简单的推理方式是 pipeline，它会自动处理分词、聚合子词实体、过滤低分结果：

>>> text = "The Golden State Warriors are an American professional basketball team based in San Francisco."

>>> from transformers import pipeline

>>> classifier = pipeline("ner", model="stevhliu/my_awesome_wnut_model")
>>> classifier(text)
[{'entity': 'B-location',
  'score': 0.42658573,
  'index': 2,
  'word': 'golden',
  'start': 4,
  'end': 10},
 {'entity': 'I-location',
  'score': 0.35856336,
  'index': 3,
  'word': 'state',
  'start': 11,
  'end': 16},
 {'entity': 'B-group',
  'score': 0.3064001,
  'index': 4,
  'word': 'warriors',
  'start': 17,
  'end': 25},
 {'entity': 'B-location',
  'score': 0.65523505,
  'index': 13,
  'word': 'san',
  'start': 80,
  'end': 83},
 {'entity': 'B-location',
  'score': 0.4668663,
  'index': 14,
  'word': 'francisco',
  'start': 84,
  'end': 93}]

返回结构中 word/start/end 对应原文字符位置，score 是 softmax 后的置信度。可以看到模型正确识别出了 Golden State（location）与 Warriors（group）等 WNUT 17 风格的实体。

6.2 手动复现 pipeline 逻辑

分词并转为 PyTorch 张量：

>>> from transformers import AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("stevhliu/my_awesome_wnut_model")
>>> inputs = tokenizer(text, return_tensors="pt")

前向得到逐 token 的 logits：

>>> from transformers import AutoModelForTokenClassification

>>> model = AutoModelForTokenClassification.from_pretrained("stevhliu/my_awesome_wnut_model")
>>> with torch.no_grad():
...     logits = model(**inputs).logits

取每位置最大概率类别，并用模型 config 中保存的 id2label 表转回文本标签：

>>> predictions = torch.argmax(logits, dim=2)
>>> predicted_token_class = [model.config.id2label[t.item()] for t in predictions[0]]
>>> predicted_token_class
['O', 'O', 'B-location', 'I-location', 'B-group', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'B-location', 'B-location', 'O', 'O']

dim=2 即沿 13 个类别维度取 argmax；model.config.id2label 正是第 5.1 节训练时写入 config.json 的映射，形成"训练配置 → 保存 → 推理反查"的完整闭环。

手动方式与 pipeline 的差异在于：pipeline 内部额外做了子词结果聚合（把同一词的 B-/I- 子词合并为一个实体字符串）和分数阈值过滤，因此输出是实体级结果；手动方式输出的是逐 token 标签，适合需要自定义后处理（如 CRF 约束、置信度加权）的场景。

7. 小结：NER 微调的关键技术点

• 标签对齐是 Token Classification 的核心难点：word_ids() + -100 忽略值是标准解法，三个规则缺一不可（特殊 token、子词内部 token 都要 -100，否则损失被污染）；
• -100 贯穿全链路：预处理对齐、DataCollatorForTokenClassification 的 label_pad_token_id、compute_metrics 中的过滤，全部依赖 PyTorch CrossEntropyLoss 的 ignore_index=-100 约定；
• 动态填充优于全局填充：batch 内按最长序列填充（padding='longest'），配合 pad_to_multiple_of 还可适配 Tensor Core；
• id2label/label2id 是模型 config 的一部分：训练时传入、保存时落盘、推理时反查，保证标签语义在训练-推理两端一致；
• seqeval 按完整实体计分：与逐 token 的 accuracy 不同，它要求实体边界和类别都完全正确才算对，是 NER 任务更有参考价值的指标。

参考文件：任务指南原文（阿拉伯语）、DataCollatorForTokenClassification 实现、word_ids 实现、NER 训练示例脚本。