使用 Transformers 微调 DistilBERT 完成 Token Classification（词元分类）实战指南

使用 Transformers 微调 DistilBERT 完成 Token Classification（词元分类）实战指南

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers

导读

词元分类（Token Classification）是自然语言处理的基础任务之一：它要求模型为句子中的每一个词元（token）预测一个标签。本文以命名实体识别（NER）为典型场景，基于当前transformers仓库，带你从零开始将 DistilBERT 在 WNUT 17 数据集上微调成可识别"人、地点、组织"等实体的专用模型，并给出完整的预处理、训练配置、评估与推理代码。读完本文，你将掌握词元与标签的对齐技巧、DataCollatorForTokenClassification的填充原理、基于 seqeval 的 NER 评估体系，以及pipeline与手动推理两种落地方式。

任务定义：为什么词元分类需要"逐词元"建模

Token classification assigns a label to individual tokens in a sentence（词元分类为句子中的每个词元分配一个标签）。在 NER 中，模型要对每个词元回答"它是不是一个命名实体、是什么类型的实体"。这一任务与整句分类（text-classification）最大的区别在于输出粒度：模型对每个位置都要产出一个分类结果。

在transformers仓库中，该任务由以*ForTokenClassification结尾的模型类承担，例如 DistilBertForTokenClassification。从其实现可以看到任务头（classification head）的构造方式：在编码器输出的sequence_output之上加一层 Dropout 与一层nn.Linear(config.hidden_size, config.num_labels)线性分类器，把每个位置的隐藏向量映射为num_labels维的 logits：

self.distilbert = DistilBertModel(config) self.dropout = nn.Dropout(config.dropout) self.classifier = nn.Linear(config.hidden_size, config.num_labels)

训练时若传入labels，则把 logits 展平为(-1, num_labels)后与同样展平的标签计算CrossEntropyLoss（modeling_distilbert.py#L794-L797）。这也是后文"用-100屏蔽特殊词元与子词"这一技巧的底层原因：CrossEntropyLoss会默认忽略目标值为-100的位置。

从源码的自动映射表 MODEL_FOR_TOKEN_CLASSIFICATION_MAPPING_NAMES 可以看出，支持该任务的架构覆盖面极广：BERT、DistilBERT、RoBERTa、ELECTRA、DeBERTa、GPT-2、Llama、Mistral、Gemma、Falcon 等数十种模型都实现了对应的分类头。因此本文以 DistilBERT 为例讲解的完整流水线，可无缝迁移到上述任一架构。

环境准备与数据集加载

先安装本次实战所需的全部依赖：

pip install transformers datasets evaluate seqeval

其中seqeval是 NER/词元分类场景的标准评估库，它基于 BIO（Begin/Inside/Outside）标注体系计算精确率、召回率、F1 与准确率。

提示：本文使用TrainerAPI 微调。若你尚未接触过该 API，可先阅读 trainer 使用指南。训练完成后还可以把模型上传并分享到社区（需先在终端按提示输入访问令牌完成登录）：

>>> from huggingface_hub import notebook_login >>> notebook_login()

加载 WNUT 17 数据集

WNUT 17 是一个专为"稀有/未知实体识别"设计的评测数据集。使用datasets库一行即可加载：

>>> from datasets import load_dataset >>> wnut = load_dataset("wnut_17")

查看一条训练样本：

>>> 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', '.']}

样本由两个字段组成：tokens是已经切好的"词"序列，ner_tags是与每个词一一对应的标签编号。把编号还原为标签名即可看清标注内容：

>>> 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", ]

WNUT 17 共定义 6 类实体：corporation（机构）、creative-work（作品）、group（群体）、location（地点）、person（人名）、product（产品），每一类都遵循 BIO 标注。

读懂 BIO 标注约定

每个标签前的字母代表词元在实体中的位置，这是理解整个任务与评估逻辑的关键：

• B-（Begin）：标注一个实体的起始词，例如B-location表示"一个地点实体的开头"；
• I-（Inside）：标注同一实体内部的后续词。例如Empire（B-location）、State（I-location）、Building（I-location）共同组成多词地点Empire State Building；
• O（Outside）：表示该词不属于任何实体。

B-前缀还有一个语义作用：当两个同类实体相邻时（如两个连续的地点），B-用于标示第二个实体的重新开始，这正是基于B-/I-前缀做序列解码与评估的前提。

预处理：子词切分后的标签重对齐

加载 DistilBERT 分词器：

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

数据集中的tokens字段看起来已经"tokenized"，但实际上只是按空白/词法完成的词切分。要让模型能处理，还需把每个词进一步拆成子词（subword）。由于tokens是词列表而非原始字符串，需要在调用分词器时指定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]；
2. 出现了子词拆分，例如@paulwalk被拆成@+paul+##walk，ESB被拆成es+##b。

这直接导致输入序列与标签在长度和位置上失配：原来一个"词"对应一个标签，拆分后可能对应多个子词。因此必须在预处理阶段把标签重新对齐到子词序列上，规则如下：

1. 使用分词器的word_ids()方法建立"每个 token 属于哪个原始词"的映射；
2. 将特殊词元[CLS]、[SEP]（word_ids返回None）的标签设为-100，使其在CrossEntropyLoss中被自动忽略；
3. 对同一原始词拆分出的多个子词，只保留第一个子词的标签，其余子词同样设为-100。

基于以上规则实现tokenize_and_align_labels，并用truncation=True把超长样本截断到模型的最大输入长度：

>>> 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) # Map tokens to their respective word. ... previous_word_idx = None ... label_ids = [] ... for word_idx in word_ids: # Set the special tokens to -100. ... if word_idx is None: ... label_ids.append(-100) ... elif word_idx != previous_word_idx: # Only label the first token of a given word. ... 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

应用map处理整个数据集，batched=True能利用底层批处理加速：

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

提示：word_ids()只在 fast tokenizer（基于 Rust tokenizers 的PreTrainedTokenizerFast）上可用。这也是选择 fast 版分词器（默认加载）的理由之一。

DataCollatorForTokenClassification：动态填充

Trainer在每步训练时会从数据集中抽出一个 batch。由于样本长度不一，需要用 Data Collator 把同一个 batch 内的样本补齐到相同长度。推荐使用DataCollatorForTokenClassification做动态填充——只把当前 batch 内序列填充到最长长度，而不是把全数据集填充到统一的最大长度，从而显著减少无效计算：

>>> from transformers import DataCollatorForTokenClassification >>> data_collator = DataCollatorForTokenClassification(tokenizer=tokenizer)

从该类的源码（data/data_collator.py）可以看到它的核心参数与行为：

参数	默认值	说明
tokenizer	必填	用于按模型的 padding 侧与 padding index 填充
padding	True	True/'longest'填充到 batch 内最长序列；'max_length'填充到max_length；False不填充
max_length	None	与padding='max_length'配合使用的上限长度
pad_to_multiple_of	None	填充到该值的整数倍，利于在 Volta 及以后的 NVIDIA GPU 上启用 Tensor Cores
label_pad_token_id	-100	标签填充所用的占位 id，-100会被 PyTorch 损失函数自动忽略
return_tensors	"pt"	返回张量类型，可选"pt"或"np"

实现上它把labels从样本中抽出，对input_ids、attention_mask等做动态 padding，再按tokenizer.padding_side把labels用label_pad_token_id填充到与输入等长并转为int64张量。这样即使trainer传入的样本标签长度不一，也能与输入严格对齐并进入损失计算。

评估指标：用 seqeval 计算 NER 分数

用evaluate库加载seqeval。它不仅能输出准确率，还会输出 NER 领域更关键的精确率、召回率与 F1：

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

compute_metrics函数是Trainer的钩子，会在每个评估点接收模型的原始predictions（形状为[batch, seq_len, num_labels]的 logits）与labels。函数需要完成两步：先用argmax取每个位置概率最高的类别 id，再剔除标签为-100的位置（这些是特殊词元与被屏蔽的子词，不参与打分），最后把 id 还原为标签名交给 seqeval：

>>> 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"], ... }

注意compute_metrics的入参p是(predictions, labels)的元组，这里的labels变量是解包出来的真实标签张量，与上方示例行的labels列表无关。seqeval 对"标签序列"按实体级别（而非 token 级别）匹配，因此它能正确惩罚把B-location, I-location断开成两个实体之类的边界错误。

训练：加载模型并配置 Trainer

准备 id2label / label2id 映射

模型输出的是类别 id，为了让结果可读且推理时能自动反查标签名，需要建立双向映射并注入模型配置：

>>> 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, ... }

加载带分类头的预训练模型

用AutoModelForTokenClassification加载 DistilBERT，并通过num_labels指定输出类别数（13 类），同时传入两个映射。库会自动把模型的顶层分类头替换为 13 类的随机初始化线性层，只保留编码器的预训练权重：

>>> from transformers import AutoModelForTokenClassification, TrainingArguments, Trainer >>> model = AutoModelForTokenClassification.from_pretrained( ... "distilbert/distilbert-base-uncased", num_labels=13, id2label=id2label, label2id=label2id ... )

配置 TrainingArguments 并启动训练

随后只需三步：

1. 在TrainingArguments中定义训练超参。唯一必填参数是output_dir（模型保存目录）。若想训练结束后把模型推送到 Hub 社区，可设push_to_hub=True（需已登录）。eval_strategy="epoch"让 Trainer 在每个 epoch 结束时用你的compute_metrics评测并打印 seqeval 分数，同时保存 checkpoint；
2. 把训练参数连同模型、数据集、tokenizer（以processing_class传入）、data collator 与compute_metrics一起交给Trainer；
3. 调用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()

上述超参（学习率2e-5、batch size16、2 个 epoch、权重衰减0.01）是该类任务经过验证的通用起点。训练结束后，调用trainer.push_to_hub()即可把最终模型与config.json（内含id2label/label2id）一起上传，供社区直接使用：

>>> trainer.push_to_hub()

推理：两种落地方式

方式一：使用 pipeline（推荐）

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}]

输出的每一项都包含entity（标签名）、score（置信度）、word（文本片段）以及start/end（该片段在原始字符串中的字符偏移），可直接用于高亮展示。这里的model参数可替换为你自己output_dir中保存的本地模型，或训练后推送的任意仓库名。

从 TokenClassificationPipeline 的源码可看到该 pipeline 还暴露了若干进阶参数：

• ignore_labels（默认["O"]）：从输出中过滤掉哪些标签，默认剔除O后仅保留实体；
• aggregation_strategy：实体聚合策略，取值为none/simple/first/average/max（定义见 AggregationStrategy）。simple会按 BIO 规则把(B-TAG)…(I-TAG)连续片段合并为一个实体输出；若模型把多词实体误切成多个B-，可用first/max/average结合子词信息按词合并。注意基于"词"合并（first/max/average）要求使用 fast tokenizer，stride滑窗处理超长文本同样只支持 fast tokenizer；
• stride：文本超过model_max_length时按步长切块处理，重叠 token 数即stride，要求aggregation_strategy非none。

方式二：手动复现 pipeline 内部流程

不依赖pipeline时，可以自己复现其三步流程，这在需要把模型嵌入自定义服务或调试时非常有用。

第一步，分词并返回 PyTorch 张量：

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

第二步，前向传播取得logits：

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

第三步，在最后一个维度上取argmax得到每个位置的预测类别 id，再通过模型的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']

可见模型成功识别出Golden State（B-location/I-location）、Warriors（B-group）、San Francisco（两个B-location）等实体。手动方式的输出是逐词元粒度的标签序列，未做实体聚合与去重，因此San与Francisco会被标注为两个独立的B-location，这是与pipeline默认输出格式的差异所在——若需合并，需要自行实现或改用pipeline的聚合策略。

小结与延伸

本文以 WNUT 17 上的命名实体识别为例，完整走通了"数据集加载 → BIO 标签理解 → 子词重对齐 → 动态填充 → seqeval 评估 → Trainer 微调 → 双路径推理"的 Token Classification 标准流程。核心要点可归结为三条：

1. 标签对齐决定训练成败：子词切分会破坏词与标签的一一对应，必须基于word_ids()只给每个原始词的第一个子词打标签，并把特殊词元与其余子词标记为-100；
2. -100贯穿始终：它在预处理中屏蔽不参与学习的词元，在DataCollatorForTokenClassification中作为label_pad_token_id兜底 padding，并被compute_metrics用作过滤点；
3. 评估与推理需区分粒度：seqeval 按实体（B/I 边界）评估，pipeline可按聚合策略输出实体级结果，而手动推理得到的是 token 级标签。

该流水线不局限于 NER——词性标注（POS）、中文分词、方面级情感分析等同样属于 Token Classification，只要把数据集换成对应标注（如 UPOS/XPOS 标签）并调整label_list即可复用。若需要完整的可运行训练脚本与更多工程化细节，仓库中还提供了 pytorch 文本分类示例、任务相关的 测试用例 以及 TokenClassificationPipeline 的端到端行为定义，可作进一步参考。

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers