简介：这份资源围绕自然语言处理中的命名实体识别任务，讲解如何基于BERT预训练模型进行微调落地，面向具备一定深度学习基础、希望掌握中文NER实战的开发者与学习者。内容涵盖实体类型定义、B-/I-标签编码、BertTokenizer中文分词、input_ids与attention_mask等输入构造，以及标签对齐、模型微调、评估与应用等关键环节，并给出可直接参考的代码片段。资源包为1个PDF文档，约545KB，以图文与代码结合的方式梳理完整流程，便于按章节顺序阅读与复现。目前已有1242人学习下载。读者可借此理解从预训练模型加载到NER系统搭建的整体思路，掌握实体边界标注与序列标记的对应关系，并参考评估指标与推理输出方式，为信息抽取、问答系统等场景提供可迁移的实践基础。
1. 从一份 BERT 微调 NER 代码包说起：它到底能跑通什么
如果你手头有一批中文标注语料，想快速搭一个能识别地址、书籍、公司、游戏、政府机构、电影、姓名、组织、职位、场景这十类实体的命名实体识别服务，这份基于bert-base-chinese的微调代码包值得先拆一遍。它没有堆花哨的架构，核心就三件事：把 BIO 标注对齐到 BERT 的 subword 序列、用transformers加载预训练权重接一个分类头、跑通训练与推理。真正卡人的从来不是模型本身，而是标签对齐——分词后[CLS]、[SEP]、##子词、[UNK]会把原始字符级 label 冲得七零八落，这份资源把get_token_label这个对齐函数写透了，属于能直接抄作业的那类。适合刚接触 NLP 落地、需要一套可复现 NER 流水线的从业者，也适合想核对标签对齐边界的老手。
2. 标签体系与分词：先把 label2id 和 input_ids 这两块地基砸实
命名实体识别落地第一道坎不是模型选型，而是标签体系设计。这份代码包把实体定义、BIO 编码、id 映射三件事串成了一条线，先把这条线捋直，后面训练才不会出现「loss 降不下去但不知道哪错了」的玄学。
2.1 实体定义与 BIO 标签编码
代码里定义了 10 类实体，每类实体拆成B-（Begin，实体开始）和I-（Inside，实体内部）两种标签，加上一个O（Outside，非实体），总共 21 个标签。这个设计遵循的是 BIO 标注规范，也是目前 NER 任务里最通用的方案。
# 定义实体类别，覆盖地址、书籍、公司等 10 类 entities = ['address', 'book', 'company', 'game', 'government', 'movie', 'name', 'organization', 'position', 'scene'] # 构造标签列表：O + 所有 B- 标签 + 所有 I- 标签 label_names = ['O'] + ['B-' + x for x in entities] + ['I-' + x for x in entities] # 建立 id 与 label 的双向映射 id2label = {i: label for i, label in enumerate(label_names)} label2id = {v: k for k, v in id2label.items()}逻辑说明：label_names的顺序决定了 id 分配，O固定为 0，B-address为 1，依次类推到I-scene为 20。参数上唯一需要注意的是实体列表的顺序——一旦训练完成，label2id的映射关系就固化了，推理阶段必须用同一份映射，否则预测出来的 id 会对应到错误的实体类型。常见做法是把id2label和label2id序列化保存成 JSON，跟模型权重放一起。
提示：实体类别不是越多越好。10 类实体已经需要至少几千条标注句子才能让每个类别的 F1 站住，类别太细会导致长尾实体召回率极低。
2.2 BERT 分词器与三个输入张量
bert-base-chinese用的是字级别为主的 WordPiece 分词，中文句子基本一字一 token，但英文单词、数字、特殊符号会被拆成 subword。分词后返回的input_ids、token_type_ids、attention_mask三个张量是 BERT 的标准输入。
from transformers import BertTokenizer model_name = 'bert-base-chinese' tokenizer = BertTokenizer.from_pretrained(model_name) text = "这是一个用于演示的例子" tokenized_input = tokenizer(text) print(tokenized_input["input_ids"]) # [101, 6821, 7027, 671, 1745, 122, 118, 10842, 9102, 8156, 4638, 4197, 511, 102] print(tokenized_input["token_type_ids"]) # 全 0，单句任务不需要区分句子对 print(tokenized_input["attention_mask"]) # 全 1，无 padding 时所有位置都参与注意力计算逻辑说明：input_ids首尾的 101 和 102 分别是[CLS]和[SEP]，中间每个数字对应一个汉字或 subword。token_type_ids在单句 NER 任务里恒为 0，只有句子对任务（如问答）才需要区分。attention_mask标记哪些位置是真实 token、哪些是 padding，batch 内做 padding 对齐时这个张量必须正确设置，否则模型会把 padding 位置也纳入注意力计算，直接影响梯度质量。
参数上，BertTokenizer.from_pretrained会自动拉取词表文件，首次运行需要联网下载。如果部署环境不能联网，常见做法是提前把vocab.txt和配置下载到本地目录，用本地路径加载。
2.3 从 id 还原 token：看清 [UNK] 和 ## 子词
分词结果不是给人看的，但调试标签对齐时必须把 token 打出来核对。
tokens = tokenizer.convert_ids_to_tokens(tokenized_input["input_ids"]) for t in tokens: print(t) # [CLS] 这 是 一 个 用 于 演 示 的 例 子 [SEP]逻辑说明：convert_ids_to_tokens把数字 id 还原成可读 token。中文场景下大部分 token 是单字，但遇到英文单词如charles会被拆成char、##les这种 subword 形式，##前缀表示它跟前一个 token 属于同一个词。还有一类是[UNK]，即词表中不存在的字符被统一映射到未知标记。这两类 token 是标签对齐时最容易翻车的地方——原始字符级 label 是按字给的，但 token 序列长度和字符序列长度对不上，必须逐 token 重新映射。
3. 标签对齐：get_token_label 函数逐行拆解与边界处理
标签对齐是这份代码包里技术密度最高的部分。原始标注数据是字符级的，每个汉字对应一个 label；BERT 分词后序列里多了[CLS]、[SEP]，英文被拆成 subword，生僻字变成[UNK]。如果直接把字符级 label 按位置贴到 token 序列上，从第一个 subword 开始后面全部错位，训练出来的模型预测结果会整体偏移。get_token_label就是解决这个错位问题的。
3.1 原始 BIO 数据读取：text 与 char_label 分开处理
代码包假设标注数据是 BIO 格式的纯文本，句子之间用空行分隔。text 文件和 label 文件分开存放，读取逻辑是按空行切分句子。
# 读取文本，按空行切分句子 file_path = "text.txt" texts = [] current_sentence = "" with open(file_path, "r", encoding='utf-8') as file: for line in file: line = line.strip() if line: current_sentence += line else: if current_sentence: texts.append(current_sentence) current_sentence = "" if current_sentence: texts.append(current_sentence)逻辑说明：line.strip()去掉行首尾空白，非空行拼接到current_sentence，遇到空行说明一个句子结束，把累积的句子存入texts并重置。文件末尾如果还有未提交的句子，循环结束后补一次。参数上唯一要改的是file_path，换成自己的数据路径。注意编码必须指定utf-8，中文语料用默认编码在某些系统上会直接报UnicodeDecodeError。
label 文件的读取逻辑完全对称，只是把字符串拼接换成列表追加：
file_path = "char_label.txt" char_label = [] item = [] with open(file_path, "r", encoding='utf-8') as file: for line in file: line = line.strip() if line: item.append(line) else: if item: char_label.append(item) item = [] if item: char_label.append(item)逻辑说明：char_label是一个二维列表，每个子列表对应一个句子的字符级标签序列。texts[i]和char_label[i]必须严格一一对应，句子数量、每句字符数都要对齐。常见坑是 text 文件里有多余空格或全角空格，导致字符数跟 label 数对不上，assert会直接抛异常。我一般会在读取后加一步校验：assert len(texts[i]) == len(char_label[i])，提前暴露数据问题。
3.2 get_token_label：三类 token 的对齐策略
这个函数是整份代码的核心，处理逻辑按 token 类型分三条分支：单字符 token、特殊 token、多字符 token。
def get_token_label(text, char_label, tokenizer): tokenized_input = tokenizer(text) tokens = tokenizer.convert_ids_to_tokens(tokenized_input["input_ids"]) iter_tokens = iter(tokens) iter_char_label = iter(char_label) iter_text = iter(text.lower()) token_labels = [] t = next(iter_tokens) char = next(iter_text) char_tp = next(iter_char_label) while True: # 分支一：单字符 token（如汉字），直接对齐 if len(t) == 1: assert t == char token_labels.append(char_tp) try: char = next(iter_text) char_tp = next(iter_char_label) except StopIteration: pass # 分支二：特殊 token，[CLS]/[SEP] 标 O，[UNK] 继承当前字符 label elif t in tokenizer.special_tokens_map.values() and t != '[UNK]': token_labels.append('O') elif t == '[UNK]': token_labels.append(char_tp) # 分支三：多字符 token（英文 subword），逐字符消费 else: t_label = char_tp t = t.replace('##', '') for c in t: assert c == char or char not in tokenizer.vocab if t_label != 'O': t_label = char_tp try: char = next(iter_text) char_tp = next(iter_char_label) except StopIteration: pass token_labels.append(t_label) try: t = next(iter_tokens) except StopIteration: break assert len(token_labels) == len(tokens) return token_labels逻辑说明：三个迭代器分别遍历 token 序列、字符序列、字符级 label 序列。分支一处理中文汉字，token 和字符一一对应，直接取 label。分支二处理特殊 token，[CLS]和[SEP]不属于任何实体，统一标O；[UNK]虽然也是特殊 token，但它对应的是原文中某个真实字符，所以继承该字符的 label。分支三处理英文 subword，先把##前缀去掉，然后逐字符消费原文，只要 subword 中任一字符属于实体，整个 token 就标成对应的 B- 或 I- 标签。
参数上，text.lower()是为了跟 BERT 词表的小写化处理保持一致，如果语料里有大写英文，不做 lower 会导致assert t == char失败。最后的assert len(token_labels) == len(tokens)是兜底校验，长度不一致说明对齐逻辑有漏洞，必须排查而不是跳过。
3.3 对齐结果验证：打印 token 与 label 对照表
对齐完不验证等于没对齐。把 token 和 label 逐行打出来，肉眼扫一遍特殊位置。
for t, t_label in zip(tokens, token_labels): print(t, '\t', t_label)输出示例中可以看到：[CLS]和[SEP]都是O，[UNK]继承了B-name，《标了B-book，后面每个汉字标I-book直到》。这个对照表是排查对齐问题的唯一可靠手段。常见翻车场景是英文实体如charles被拆成char和##les，如果两个 subword 都标了B-而不是B-+I-，解码时会被当成两个独立实体。代码里t_label = char_tp的逻辑保证了 subword 内部标签跟随当前字符，但跨 subword 的 B/I 切换需要额外处理，这是这份代码可以改进的地方。
4. 训练样本构造与常见坑排查
对齐函数跑通之后，构造训练样本就是把input_ids、attention_mask、labels打包成模型能吃的格式。这一步看起来简单，但 padding、label 对齐、batch 组装几个环节都有坑。
4.1 make_sample：把对齐结果转成模型输入
def make_sample(text, label, tokenizer): sample = tokenizer(text) char_label = label token_label = get_token_label(text, char_label, tokenizer) sample['labels'] = [label2id[x] for x in token_label] return sample逻辑说明：tokenizer(text)返回input_ids、token_type_ids、attention_mask三个字段，get_token_label返回对齐后的字符串标签序列，最后用label2id把字符串标签转成数字 id 存入labels字段。这个labels就是模型计算交叉熵损失时的监督信号。参数上，label2id必须是训练前定义好的那一份，不能重新生成，否则 id 映射会错位。
构造完的样本结构里，input_ids和labels长度必须一致，attention_mask全 1 表示无 padding。如果要做 batch 训练，需要用DataCollatorForTokenClassification或手动 padding，padding 位置的labels要设成-100，这样损失函数会自动忽略这些位置。
4.2 避坑：标签对齐与训练中的五类翻车现场
现象一：训练 loss 从第一个 epoch 就卡在 0.7 左右不降。原因：labels里 padding 位置没有设成-100，模型在 padding 上也算损失，梯度被稀释。 解决：用DataCollatorForTokenClassification自动处理，或手动把 padding 位置的 label 替换为-100。
现象二：推理时实体边界整体偏移一个字符。原因：get_token_label里text.lower()后字符数跟原始char_label长度不一致，比如原文有全角字符被 lower 后变成半角。 解决：在读取数据阶段统一做全角转半角，或者去掉lower()改用text原始形式，前提是词表匹配。
现象三：英文实体被拆成多个独立实体。原因：subword 的 B/I 标签没有正确切换，char和##les都标了B-。 解决：在分支三里增加判断，如果当前 token 以##开头，标签强制设为I-对应类型。
现象四：assert t == char频繁失败。原因：text 文件里混入了不可见字符（如\u200b零宽空格），或者 label 文件行数与 text 不一致。 解决：读取时用line.replace('\u200b', '')清洗，并在读取后加assert len(texts) == len(char_label)。
现象五：模型预测全是O。原因：实体类别样本极度不均衡，O标签占比超过 95%，模型学到全部预测O就能拿到高准确率。 解决：损失函数加class_weight，或对非O标签做上采样，评估指标看 F1 而不是 accuracy。
注意：
bert-base-chinese的最大序列长度是 512，超过的句子必须截断。截断时labels也要同步截断，否则长度不匹配会直接报错。
4.3 训练参数与评估指标
模型结构是在BertForTokenClassification基础上指定num_labels=21。训练超参常见起点是learning_rate=2e-5、batch_size=16、epochs=3到 5。学习率再大会导致预训练权重被冲垮，再小则收敛太慢。评估用seqeval库算实体级别的 precision、recall、F1，不要用 token 级别的 accuracy，后者在类别不均衡时严重虚高。
from transformers import BertForTokenClassification model = BertForTokenClassification.from_pretrained( 'bert-base-chinese', num_labels=len(label_names) # 21 )逻辑说明：num_labels必须等于label_names的长度，分类头输出维度跟标签数对齐。from_pretrained会加载 BERT 主体权重，分类头随机初始化。参数上，如果显存不够，可以把batch_size降到 8 并开梯度累积，等效 batch 不变。
5. 推理部署与一个提 F1 的实用技巧
训练完的模型要落到实际识别场景，推理流程比训练简单，但有几个细节决定线上效果。加载模型和分词器，对输入文本做同样的分词和对齐，取 argmax 得到每个 token 的预测 id，再映射回标签字符串，最后按 B/I 规则合并成完整实体。
import torch model.eval() text = "某公司在某地发布了新款游戏" inputs = tokenizer(text, return_tensors="pt") with torch.no_grad(): logits = model(**inputs).logits predictions = torch.argmax(logits, dim=-1)[0].tolist() tokens = tokenizer.convert_ids_to_tokens(inputs["input_ids"][0]) pred_labels = [id2label[p] for p in predictions] for t, l in zip(tokens, pred_labels): print(t, l)逻辑说明：return_tensors="pt"把输入转成 PyTorch 张量，model(**inputs)前向传播拿到 logits，argmax取每个位置概率最大的标签 id。id2label必须是训练时保存的那一份。参数上，推理时model.eval()和torch.no_grad()都要开，前者关闭 dropout，后者省显存。
解码阶段把 token 级标签合并成实体时，遇到B-xxx开始一个新实体，后续I-xxx追加到当前实体，遇到O或其他类型则结束当前实体。这里有个容易忽略的点：[CLS]和[SEP]的预测结果直接跳过，不要参与实体合并。
提 F1 的一个实用技巧是在分类头后面加一层 CRF。BERT 输出的每个 token 独立分类，不考虑标签之间的转移约束，比如I-company前面理论上不应该直接跟O再跟B-company。CRF 层学习标签转移矩阵，能强制输出合法的 BIO 序列，在实体边界清晰的数据集上通常能提 1 到 3 个点 F1。实现上用torchcrf或pytorch-crf，把 BERT 的 logits 作为发射分数传入 CRF，训练时用 CRF 的负对数似然做损失。代价是训练速度慢一些，解码用维特比算法，推理延迟略有增加。
从那以后我每次做 NER 微调，都会先把get_token_label的对齐结果打印出来逐句核对，再开始训练。这个习惯帮我省掉了至少三次「训练 loss 正常但推理全错」的排查时间。希望帮到你。
本文还有配套的精品资源，点击获取
