简介本资源面向计算机、人工智能、数据科学等专业学生及企业开发者提供一套基于BERTBILSTMCRF的中文命名实体识别完整项目源码适合作为毕业设计、课程设计或大作业的实战参考也可用于初期项目立项演示。压缩包共58个文件约13.75MB包含16个Python源码文件、19个编译缓存文件、9个文本数据、5张效果图、4份Markdown说明文档及XML配置等覆盖模型定义、数据预处理、训练脚本与说明文档等模块。项目整合了BERT预训练语言模型、双向LSTM与CRF层并附带人民日报、MSRA等中文NER数据集及预处理代码目录中可见BERT_BILSTM_CRF、BILSTM_CRF、IDCNN_CRF等多种模型实现便于对比学习。目前已有1209人学习下载读者可据此掌握从数据清洗、词表构建到模型训练与评估的完整流程积累序列标注任务的排错与调参经验。1. 中文 NER 为什么总在「人名边界」上翻车从 BERTBILSTMCRF 这套组合说起做中文命名实体识别NER的工程师大概率都经历过这样的场景模型在测试集上 F1 刷到 0.95一上真实业务文本人名被切成了两半「张伟明」识别成「张伟」「欧阳娜娜」只认出「娜娜」。这不是模型不行而是中文 NER 的边界判定本身就是个硬骨头——没有空格分词实体嵌套、简称、别名混在一起单靠字向量分类根本压不住标签之间的依赖关系。BERTBILSTMCRF 这套组合就是目前工业界落地中文 NER 最稳的基线方案之一。BERT 负责把每个字编码成带上下文的向量BILSTM 捕捉字符级序列的前后依赖CRF 层则在输出端约束标签转移的合法性——比如「B-PER」后面不该直接跟「B-LOC」。三者叠加既解决了「字的多义性」又解决了「标签乱序」的问题。这套方案适合谁适合手上有几千到几万条标注数据、想快速搭一个可用的中文实体抽取服务、又不想从零训语言模型的团队。Python 生态下HuggingFace Transformers 加 torchcrf 就能跑通全流程不需要自己写底层算子。接下来我会按「数据怎么准备 → 模型怎么搭 → 训练怎么调 → 坑在哪 → 怎么验证」的顺序把这条链路拆开讲清楚。你照着做能复现一个可用的中文 NER 模型你踩过的坑我大概率也踩过。2. 数据准备与标签体系BIO 标注的四个实操细节2.1 中文 NER 的数据从哪来、怎么清洗中文 NER 的数据来源无非几类公开数据集MSRA、OntoNotes、Weibo NER、业务日志抽取、人工标注平台产出。公开数据集适合验证模型结构业务数据才是真正要落地的。我一般会先把原始文本做一轮清洗去掉 HTML 标签、统一全半角、处理连续空白符、过滤超长文本超过 512 字的先截断或分段。这一步不做后面 BERT 的 tokenizer 会给你一堆意外。清洗完的文本要转成「字 标签」的序列格式。中文 NER 通常按字切分不按词。原因很简单分词器本身会引入误差而 BERT 的 tokenizer 对中文是按字或子词切的按字标注能和 tokenizer 对齐减少后续对齐的麻烦。import re def clean_text(text): # 去掉 HTML 标签 text re.sub(r[^], , text) # 全角转半角 text .join([chr(ord(ch) - 0xFEE0) if 0xFF01 ord(ch) 0xFF5E else ch for ch in text]) # 合并连续空白 text re.sub(r\s, , text).strip() return text # 示例 raw p张三于2023年加入北京字节跳动。/p print(clean_text(raw)) # 输出: 张三于2023年加入北京字节跳动。这段代码做了三件事剥离 HTML、全角转半角、压缩空白。参数上没什么可调的但顺序有讲究——先剥标签再转半角否则标签里的全角字符会被误转。清洗后的文本按字拆开每个字对应一个标签就得到了训练所需的序列。2.2 BIO 标签体系怎么定别在 B 和 I 上省事BIO 是最常用的标注体系B-XXX 表示实体开头I-XXX 表示实体内部O 表示非实体。中文 NER 常见的实体类型包括 PER人名、LOC地点、ORG机构、MISC其他专名。有些团队为了省事只用 B 和 O不用 I结果就是「张三」和「张三四」在标签上没区别模型学不到边界。我一般会坚持用完整的 BIO并且在数据预处理阶段做一次标签合法性校验B 后面必须跟同类型的 I 或 O不能出现 B-PER 后面直接跟 I-LOC 这种非法转移。这个校验在训练前做能提前发现标注错误比训练完再回头查省事得多。def validate_bio(labels): # 检查 BIO 序列合法性 for i in range(1, len(labels)): prev, curr labels[i-1], labels[i] if curr.startswith(I-): entity_type curr[2:] if not (prev fB-{entity_type} or prev fI-{entity_type}): return False, f位置 {i}: {prev} - {curr} 非法转移 return True, 合法 labels [B-PER, I-PER, O, B-LOC, I-LOC] print(validate_bio(labels)) # (True, 合法)这个校验函数逻辑很直白遍历标签序列遇到 I-XXX 就检查前一个标签是不是同类型的 B 或 I。如果不是说明标注有问题。实际项目中我见过不少标注团队把「北京市朝阳区」标成 B-LOC I-LOC B-LOC I-LOC这种嵌套实体在 BIO 体系下需要拆成两个独立实体或者改用 BILOU 体系。选哪种取决于你的业务需求但一定要在标注规范里写清楚。2.3 标签映射表与数据格式转换标签要转成数字 ID 才能喂给模型。我一般会维护一个 label2id 字典把 O 设为 0其余按顺序编号。注意CRF 层对标签顺序敏感虽然理论上顺序不影响最终效果但固定顺序能让实验可复现。labels [O, B-PER, I-PER, B-LOC, I-LOC, B-ORG, I-ORG] label2id {label: idx for idx, label in enumerate(labels)} id2label {idx: label for label, idx in label2id.items()} print(label2id) # {O: 0, B-PER: 1, I-PER: 2, B-LOC: 3, I-LOC: 4, B-ORG: 5, I-ORG: 6}数据格式上我习惯把每条样本存成{text: 张三在北京, labels: [B-PER, I-PER, O, B-LOC, I-LOC]}的 JSON 行格式。这种格式易读易改加载时用jsonlines库逐行读内存友好。如果数据量特别大百万级以上可以转成 TFRecord 或 Arrow 格式但中小规模项目没必要。2.4 训练集/验证集/测试集的划分陷阱划分数据集时最常见的坑是按样本随机切分导致同一个实体的不同出现被分到训练集和测试集验证指标虚高。正确做法是按实体或按文档切分同一个文档里的所有句子要么全在训练集要么全在测试集。如果做不到按文档切至少保证同一个实体的不同表述不跨集。我一般用 8:1:1 的比例但会先按文档 ID 分组再在组级别做切分。这样验证集上的 F1 更接近真实上线表现。另外验证集和测试集的标签分布要尽量一致如果测试集里 ORG 特别多而验证集里几乎没有调参时就会跑偏。3. BERTBILSTMCRF 模型搭建从 tokenizer 到 CRF 层的完整代码3.1 BERT 输出怎么接 BILSTM维度对齐与 dropout 位置BERT 的输出是[batch_size, seq_len, hidden_size]BILSTM 要求输入是[batch_size, seq_len, input_size]所以 hidden_size 必须等于 BILSTM 的 input_size。BERT-base 中文模型的 hidden_size 是 768BILSTM 的 hidden_dim 我一般设 128 或 256双向拼接后输出维度是2 * hidden_dim。dropout 放哪我的经验是放两处BERT 输出后放一层0.1~0.3BILSTM 输出后、CRF 之前再放一层0.1~0.3。第一层防止 BERT 过拟合第二层防止 BILSTM 过拟合。如果数据量小于 5000 条dropout 可以调到 0.3~0.5数据量上万0.1~0.2 就够了。import torch import torch.nn as nn from transformers import BertModel class BertBiLSTMCRF(nn.Module): def __init__(self, bert_path, num_labels, lstm_hidden128, dropout0.2): super().__init__() self.bert BertModel.from_pretrained(bert_path) self.dropout1 nn.Dropout(dropout) self.bilstm nn.LSTM( input_size768, hidden_sizelstm_hidden, num_layers1, bidirectionalTrue, batch_firstTrue ) self.dropout2 nn.Dropout(dropout) self.classifier nn.Linear(lstm_hidden * 2, num_labels) self.crf CRF(num_labels, batch_firstTrue) def forward(self, input_ids, attention_mask, labelsNone): outputs self.bert(input_ids, attention_maskattention_mask) sequence_output outputs.last_hidden_state # [B, L, 768] sequence_output self.dropout1(sequence_output) lstm_output, _ self.bilstm(sequence_output) # [B, L, 2*hidden] lstm_output self.dropout2(lstm_output) emissions self.classifier(lstm_output) # [B, L, num_labels] if labels is not None: loss -self.crf(emissions, labels, maskattention_mask.bool()) return loss else: return self.crf.decode(emissions, maskattention_mask.bool())这段代码里CRF来自torchcrf库需要pip install torchcrf。注意mask参数CRF 计算损失时要传入 attention_mask把 padding 位置排除掉否则 padding 的标签会干扰转移矩阵的学习。batch_firstTrue在 LSTM 和 CRF 里都要设保持一致。3.2 CRF 层的转移矩阵为什么它比 softmax 强不用 CRF直接对 BILSTM 输出做 softmax 分类每个位置独立预测标签。问题在于标签之间有依赖关系比如「B-PER」后面跟「I-PER」是合理的跟「I-LOC」就不合理。softmax 不管这些它只看当前字的发射分数。CRF 则引入一个转移矩阵[num_labels, num_labels]学习标签之间的转移概率解码时用 Viterbi 算法找全局最优路径。转移矩阵是 CRF 的核心参数初始化时通常设成对角占优自己转移到自己概率高训练中自动调整。torchcrf库已经封装好了这些你只需要传 emissions 和 labels 就行。但要注意CRF 的损失函数是负对数似然数值上可能不稳定训练时如果 loss 突然变成 nan先检查学习率是不是太大或者 emissions 里有没有 inf。3.3 完整训练循环优化器、学习率与梯度裁剪BERT 微调的学习率要小一般 2e-5 到 5e-5。BILSTM 和 CRF 是随机初始化的学习率可以大一点1e-3 到 1e-2。我一般用分层学习率BERT 部分 2e-5其余部分 1e-3。优化器用 AdamW权重衰减设 0.01。from transformers import AdamW, get_linear_schedule_with_warmup def train(model, train_loader, val_loader, epochs5, bert_lr2e-5, other_lr1e-3): # 分层学习率 bert_params list(model.bert.named_parameters()) other_params [(n, p) for n, p in model.named_parameters() if not n.startswith(bert)] optimizer AdamW([ {params: [p for _, p in bert_params], lr: bert_lr}, {params: [p for _, p in other_params], lr: other_lr} ], weight_decay0.01) total_steps len(train_loader) * epochs scheduler get_linear_schedule_with_warmup( optimizer, num_warmup_stepsint(0.1 * total_steps), num_training_stepstotal_steps ) for epoch in range(epochs): model.train() total_loss 0 for batch in train_loader: input_ids batch[input_ids].cuda() attention_mask batch[attention_mask].cuda() labels batch[labels].cuda() loss model(input_ids, attention_mask, labels) loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0) optimizer.step() scheduler.step() optimizer.zero_grad() total_loss loss.item() print(fEpoch {epoch1}, Loss: {total_loss / len(train_loader):.4f})梯度裁剪max_norm1.0是必须的BILSTM 和 CRF 的梯度容易爆炸不裁剪的话 loss 可能几轮后就飞了。warmup 设总步数的 10%让学习率从 0 线性升到设定值再线性衰减。这套配置在几千条数据上跑 5 到 10 轮基本能收敛。3.4 批次构造与动态 padding中文句子长度差异大短句 10 个字长句 200 个字。如果按最大长度 padding短句浪费大量计算。我一般用动态 padding每个 batch 内按最长句子 padding不同 batch 长度不同。HuggingFace 的DataCollatorForTokenClassification已经支持这种模式直接拿来用就行。from transformers import DataCollatorForTokenClassification collator DataCollatorForTokenClassification( tokenizertokenizer, paddingTrue, pad_to_multiple_of8 # 对齐到 8 的倍数GPU 友好 )pad_to_multiple_of8是个小技巧让序列长度对齐到 8 的倍数GPU 计算时更高效。标签的 padding 值要设成 -100 或忽略索引CRF 计算损失时会自动跳过。如果自己写 collator记得把 padding 位置的标签设成 0对应 O但 mask 里要标成 0让 CRF 忽略。4. 训练调参与排错中文 NER 的五个血泪坑4.1 坑一BERT tokenizer 把字切碎了标签对不上现象用bert-base-chinese的 tokenizer 处理文本发现有些字被切成了子词比如「尴尬」变成「尴」和「尬」两个 token但你的标签是按字标的长度对不上。原因BERT 中文 tokenizer 虽然大部分情况按字切但遇到生僻字或特殊符号时会退化成按 subword 切。如果你的标注是按字来的tokenizer 输出长度可能和标签长度不一致。解决用tokenizer(text, add_special_tokensFalse)先看切分结果如果长度和标签不一致要么改用按 token 标注要么在 tokenizer 里加do_basic_tokenizeFalse强制按字切。我一般会在数据预处理阶段加一层校验tokenizer 输出长度必须等于标签长度不等就报错提前发现。4.2 坑二CRF 的 mask 没传对padding 位置污染转移矩阵现象训练 loss 正常下降但验证集 F1 很低解码结果里 padding 位置出现奇怪标签。原因CRF 计算损失时如果没传 maskpadding 位置的标签通常是 0对应 O也会参与转移矩阵的学习导致模型在真实边界上判断不准。解决crf(emissions, labels, maskattention_mask.bool())mask 里 1 表示真实 token0 表示 padding。torchcrf的decode方法也要传 mask否则解码时会输出 padding 位置的标签。这个坑我踩过两次每次都是 loss 看着正常但指标上不去查半天才发现是 mask 的问题。4.3 坑三学习率太大BERT 微调直接崩现象第一轮 loss 就变成 nan或者 loss 先降后升剧烈震荡。原因BERT 预训练权重已经很好微调时学习率太大会破坏原有参数。有人直接用 1e-3 训 BERT不崩才怪。解决BERT 部分学习率控制在 2e-5 到 5e-5BILSTM 和 CRF 部分可以到 1e-3。用分层学习率别一刀切。如果还是崩先冻结 BERT 训几轮 BILSTMCRF再解冻 BERT 一起微调。另外梯度裁剪max_norm1.0一定要加。4.4 坑四标签不平衡O 标签占了 90% 以上现象模型把所有字都预测成 O准确率看着很高90%但 F1 接近 0。原因中文 NER 数据里非实体字O通常占 85%~95%实体字很少。模型学到「全预测 O」就能拿到高准确率但完全没用。解决损失函数里给实体标签加权或者用 focal loss。torchcrf不直接支持类别权重但可以在 emissions 上做文章对 O 标签的发射分数乘一个小于 1 的系数降低其优势。更简单的做法是过采样含实体的句子让训练集里实体比例提高到 20%~30%。我一般用后者实现简单效果稳定。4.5 坑五验证集指标虚高上线就翻车现象验证集 F1 0.95上线后人工抽检发现准确率不到 0.7。原因验证集和测试集同分布但和真实业务数据分布不一致。或者验证集里实体类型单一模型没见过复杂场景。解决验证集一定要从真实业务数据里抽别只用公开数据集。另外做一轮「对抗验证」训一个分类器区分训练集和验证集如果分类器准确率远高于 0.5说明两个分布差异大需要调整数据。上线前再用一批完全没见过的业务数据做盲测指标打七折才是真实水平。5. 模型验证与推理怎么确认你的 NER 真的能用5.1 用 seqeval 算 F1别自己写评估脚本序列标注的评估不能用普通分类的 accuracy要用实体级别的 precision/recall/F1。seqeval库是标准工具直接调就行。from seqeval.metrics import classification_report, f1_score def evaluate(model, val_loader, id2label): model.eval() all_preds, all_labels [], [] with torch.no_grad(): for batch in val_loader: input_ids batch[input_ids].cuda() attention_mask batch[attention_mask].cuda() labels batch[labels] preds model(input_ids, attention_mask) # 把 padding 位置去掉 for pred, label, mask in zip(preds, labels, attention_mask): length mask.sum().item() pred_labels [id2label[p] for p in pred[:length]] true_labels [id2label[l.item()] for l in label[:length]] all_preds.append(pred_labels) all_labels.append(true_labels) print(classification_report(all_labels, all_preds)) return f1_score(all_labels, all_preds)seqeval的classification_report会输出每个实体类型的 P/R/F1以及整体 micro/macro 平均。注意传入的标签必须是字符串形式如B-PER不能是数字 ID。padding 位置一定要去掉否则 O 标签会拉高准确率但拉低 F1。5.2 推理阶段的 batch 处理与后处理上线推理时请求是一条条来的但为了吞吐量一般会攒一个 batch 再跑。我一般设 batch_size32超时 50ms 就强制触发。推理完的输出是标签序列需要后处理成实体列表遇到 B-XXX 开始记录遇到 I-XXX 继续遇到 O 或不同类型标签就结束当前实体。def decode_entities(text, labels): entities [] start None current_type None for i, label in enumerate(labels): if label.startswith(B-): if start is not None: entities.append((start, i, current_type, text[start:i])) start i current_type label[2:] elif label.startswith(I-) and start is not None and label[2:] current_type: continue else: if start is not None: entities.append((start, i, current_type, text[start:i])) start None current_type None if start is not None: entities.append((start, len(text), current_type, text[start:])) return entities text 张三在北京工作 labels [B-PER, I-PER, O, B-LOC, I-LOC, O, O] print(decode_entities(text, labels)) # [(0, 2, PER, 张三), (3, 5, LOC, 北京)]这段后处理逻辑处理了实体在句尾结束的情况以及 B 后面直接跟 O 的情况。实际项目中还要处理嵌套实体和重叠实体那需要更复杂的解码策略但 BIO 体系下这套够用了。5.3 错误分析与迭代方向验证集 F1 到 0.9 以上后提升空间主要在错误分析。我一般会把预测错误的样本按类型分类边界错误实体多字或少字、类型错误PER 识别成 ORG、漏识别实体完全没出来。边界错误通常是 BILSTM 层不够强或 CRF 转移矩阵没学好可以加 BILSTM 层数或调 CRF 学习率。类型错误往往是训练数据里该类型的样本太少需要补充标注。漏识别可能是文本太短或实体太罕见考虑加词典特征或做数据增强。错误分析不用做太频繁每轮训练后抽 50~100 条错误样本看看就行。关键是别只看总体 F1要看每个实体类型的 F1短板往往在某个特定类型上。6. 把模型塞进生产环境量化、导出与一个提速技巧训练完的模型要上线绕不开推理速度问题。BERT-base 在 CPU 上单条推理 50~100msGPU 上 10~20ms如果 QPS 要求高这个速度不够看。我一般会做两件事动态量化和 ONNX 导出。动态量化把 BERT 的线性层权重从 float32 降到 int8模型体积缩小 4 倍CPU 推理速度提升 2~3 倍F1 掉不到 0.5 个点。代码很简单import torch.quantization model.eval() quantized_model torch.quantization.quantize_dynamic( model, {torch.nn.Linear}, dtypetorch.qint8 ) torch.save(quantized_model.state_dict(), ner_quantized.pt)注意量化只对nn.Linear层做LSTM 和 CRF 不动。量化后的模型在 CPU 上跑GPU 上反而可能变慢因为 int8 算子 GPU 支持不如 CPU 成熟。ONNX 导出适合跨平台部署尤其是用 TensorRT 或 OpenVINO 做加速的场景。导出时要把 CRF 层单独处理因为 CRF 的 Viterbi 解码不是标准 ONNX 算子。我的做法是BERTBILSTMLinear 导出成 ONNXCRF 解码用 Python 或 C 单独实现。这样推理速度能再提升 30%~50%。torch.onnx.export( model, (dummy_input_ids, dummy_attention_mask), ner_bert_bilstm.onnx, input_names[input_ids, attention_mask], output_names[emissions], dynamic_axes{ input_ids: {0: batch, 1: seq_len}, attention_mask: {0: batch, 1: seq_len}, emissions: {0: batch, 1: seq_len} }, opset_version13 )导出时dynamic_axes必须设否则 batch 和序列长度被固定上线后换个长度就报错。opset_version13对 Transformer 类模型支持较好低于 11 可能缺算子。最后一个提速技巧把 BILSTM 的 hidden_dim 从 256 降到 128F1 通常只掉 0.2~0.5 个点但推理速度提升 20% 左右。如果业务对延迟敏感这个 trade-off 很划算。我现在的习惯是先训一个 hidden_dim256 的模型看上限再训一个 128 的看实际部署效果两者对比后再决定上线哪个。这套方案我从头到尾跑过不下十次每次都有新坑但整体链路是稳的。数据质量决定上限模型结构决定下限调参决定你能不能摸到上限。希望帮到你。本文还有配套的精品资源点击获取