中文NER实战：BERT-BiLSTM-CRF源码解析与可复现训练指南

简介：本资源面向中文命名实体识别（NER）的入门与进阶学习者，提供一套基于PyTorch实现的BERT-BiLSTM-CRF完整项目，适合毕业设计、期末大作业与课程设计场景，也便于新手通过注释理解模型原理。压缩包共22个文件，约2.4MB，以8个Python源码文件为核心，涵盖模型定义、训练、预测与评估脚本；另有5个txt数据集文件、5个xml与1个iml等IDE配置、1个md说明文档及json配置，结构清晰、便于部署。项目将BERT预训练、BiLSTM特征提取与CRF标签约束串联，配套数据集可直接跑通训练与推理流程。目前已有663人学习下载，代码注释详尽，个人手打98分，导师认可度高，下载后简单配置即可使用，能帮助读者快速掌握中文NER的建模思路与工程实现。

1. 中文 NER 项目落地：从 BERT-BiLSTM-CRF 源码包到可复现训练

命名实体识别（NER）是 NLP 里最容易被低估、也最容易翻车的一类任务。你拿到一份标注好的中文语料，想从里面抽出人名、地名、机构名，用正则和词典硬怼，召回率上不去；换成 BERT 微调做序列标注，又会遇到标签转移非法、实体边界断裂、CRF 层接不上的问题。这份基于 PyTorch + BERT + BiLSTM + CRF 的中文命名实体识别源码包，解决的正是这条链路：它把预训练语言模型、上下文序列建模和全局标签约束拼成一个完整可训练的系统，附带 train/dev/test 三份数据和一份项目说明。适合正在做毕业设计、课程大作业，或者第一次把 NER 从论文公式落到可跑代码的从业者。下面按「结构是什么 → 怎么跑起来 → 参数怎么调 → 坑在哪」的顺序拆开讲。

2. 拆开源码包：BERT-BiLSTM-CRF 三层结构到底各干什么

2.1 三个模块的分工与选型理由

先把这个模型的骨架说清楚，不然后面调参就是盲调。整个网络是串行的三层：BERT 负责把中文字符变成带上下文的向量，BiLSTM 负责在向量序列上再抽一层时序特征，CRF 负责在输出层约束标签之间的转移合法性。

为什么不能只用 BERT 加一个线性分类头？因为序列标注的每个位置不是独立的。以 BIO 标注为例，I-PER前面必须跟B-PER或I-PER，绝不能直接跟O。线性分类头对每个位置单独做 softmax，学不到这种全局约束，预测时就会冒出大量非法标签序列。CRF 把整条标签路径的分数一起算，用维特比解码取全局最优，这是它存在的唯一理由。

那 BiLSTM 是不是多余？在 BERT 已经很强的前提下，它确实有争议。但在这份源码的结构里，BiLSTM 接在 BERT 输出之后，起到一个轻量的序列平滑作用，对长实体和跨词边界的连续性有帮助。代价是参数量和显存上升。如果你显存紧张，这一层是可以摘掉的，后面 4.2 会讲怎么改。

对应到文件结构，核心逻辑集中在model/BERT_BiLSTM_CRF.py，训练入口是main.py，推理入口是predict.py，评估脚本是estimate.py，超参和路径都收在config.py，数据处理工具在scripts/utils.py。数据集放在dataset/下，train.txt、dev.txt、test.txt是标注语料，tag.txt是标签集合。

2.2 数据格式与标签体系

在跑任何命令之前，先确认你的数据长什么样。这份项目用的是「字符 + 标签」逐行排列、句子之间空行分隔的经典格式，和 CoNLL-2003 一致。常见做法是每行两列，用空格或制表符分开：

北 B-LOC 京 I-LOC 大 I-LOC 学 I-LOC 李 B-PER 明 I-PER 在 O 上 O 海 O

tag.txt里存的是全部标签，通常包含O、B-PER、I-PER、B-LOC、I-LOC、B-ORG、I-ORG这几类，具体以你下载包里的实际内容为准。这里有个容易被忽略的点：标签集合必须和config.py里读取tag.txt的逻辑对齐，标签顺序变了，模型输出的索引含义就全乱了，加载旧权重会直接错位。

2.3 从 config 到训练入口的调用链

理解调用链能帮你在报错时快速定位。main.py启动后，先读config.py里的配置，再通过scripts/utils.py加载数据、构建词表和标签表，然后实例化BERT_BiLSTM_CRF，进入训练循环。config.py里一般会有这些关键项：

crf_lr单独设置是这份代码里一个值得注意的细节。CRF 层是随机初始化的，而 BERT 是预训练好的，两者用同一个学习率会导致 CRF 收敛太慢或者 BERT 被带偏。常见做法是给 CRF 一个更大的学习率，让它快速跟上。

3. 把环境跑通：依赖、BERT 权重与训练命令

3.1 环境与依赖安装

这份代码基于 PyTorch，Python 版本建议 3.7 到 3.9，太新的版本有时会和某些依赖冲突。先建一个独立环境，避免污染全局：

conda create -n ner python=3.8 -y conda activate ner pip install torch==1.10.0 pip install transformers==4.10.0 pip install pytorch-crf==0.7.2 pip install numpy tqdm

逻辑说明：torch是深度学习框架，版本要和你的 CUDA 匹配，没有 GPU 就装 CPU 版；transformers用来加载 BERT 的配置和分词器；pytorch-crf提供 CRF 层实现，如果你的源码包里 CRF 是自己手写的，这一步可以跳过。参数上，torch版本不要盲目追新，1.10 附近和这份代码的兼容性比较稳。

3.2 BERT 中文预训练权重怎么放

代码本身不含 BERT 权重，需要你单独准备bert-base-chinese。下载后解压，目录里应该有config.json、vocab.txt、pytorch_model.bin三个核心文件。把config.py里的bert_path指向这个目录：

# config.py 片段 class Config: def __init__(self): self.bert_path = "./bert-base-chinese" # 指向解压后的权重目录 self.data_dir = "./dataset" self.tag_path = "./dataset/tag.txt" self.max_seq_len = 128 self.batch_size = 16 self.lr = 2e-5 self.crf_lr = 1e-3 self.epoch = 20 self.device = "cuda" if torch.cuda.is_available() else "cpu"

逻辑说明：bert_path必须是包含config.json和vocab.txt的目录，不是单个.bin文件。device自动判断有没有 GPU，没有就退回 CPU，但 CPU 训练 BERT 会非常慢，建议至少用一张显存 6G 以上的卡。max_seq_len设 128 是中文 NER 的常见起点，句子普遍不长，设太大只是浪费显存。

3.3 启动训练与观察日志

配置改好后，直接跑训练入口：

python main.py

正常启动后，日志里会先打印标签数量和样本数量，然后每个 epoch 输出训练 loss 和验证集上的评估指标。你要盯的是验证集的 F1，而不是训练 loss。训练 loss 一直降但验证 F1 不涨，说明过拟合了，这时候该做的是减小 epoch 或者加 dropout，而不是继续等。

如果显存不够报 OOM，优先把batch_size从 16 降到 8，再不行降到 4，同时把max_seq_len从 128 降到 64。这两个参数是显存占用的主要来源，调它们比换模型结构见效快。

3.4 用 predict.py 做单句推理

训练完会保存权重，predict.py负责加载权重对新句子做预测：

python predict.py --text "李明在北京大学读书"

预期输出会把每个字符对应的实体标签打出来，比如「李明」被标成B-PER I-PER，「北京大学」被标成B-LOC I-LOC I-LOC I-LOC。如果输出全是O，先别怀疑模型，八成是权重路径没对上，或者标签表和训练时不一致。推理脚本里的权重路径要和训练保存的路径一致，这是最常见的低级错误。

4. 参数怎么调：学习率、序列长度与结构取舍

4.1 学习率与优化器分组

BERT 微调的学习率是这套模型里最敏感的参数。设大了，预训练权重被破坏，loss 直接飞；设小了，几十个 epoch 都不收敛。2e-5 到 5e-5 是安全区间，中文小数据集建议从 2e-5 起步。前面提到的 CRF 单独学习率，实现上通常是把参数分组传给优化器：

# 参数分组示例 bert_params = list(model.bert.named_parameters()) crf_params = list(model.crf.named_parameters()) optimizer = torch.optim.AdamW([ {"params": [p for _, p in bert_params], "lr": config.lr}, {"params": [p for _, p in crf_params], "lr": config.crf_lr}, ])

逻辑说明：AdamW比Adam在带权重衰减的微调场景下更稳。把 BERT 和 CRF 分成两组，各自用不同学习率，是这类模型的标配做法。参数上，crf_lr设成lr的 50 倍左右是个经验值，具体看你数据规模，数据越小，CRF 收敛越快，倍数可以适当降。

4.2 要不要保留 BiLSTM

前面说过 BiLSTM 有争议，这里给出取舍依据。如果你的实体普遍较短（人名、地名两三个字），BERT 加 CRF 已经够用，BiLSTM 带来的增益有限，反而增加显存和训练时间。如果你的实体偏长、跨词多（机构名、产品名），BiLSTM 的序列建模能补一点边界信息。

摘掉 BiLSTM 的做法是改BERT_BiLSTM_CRF.py里的前向逻辑，让 BERT 输出直接进 CRF，跳过 LSTM 层。改完记得同步调整 CRF 的输入维度，从2 * hidden_size变回hidden_size，否则维度对不上会直接报错。这是改结构时最容易漏的一步。

4.3 序列长度与批大小的联动

max_seq_len和batch_size是一对联动参数，显存占用大致和两者乘积成正比。常见做法是先固定max_seq_len覆盖你数据里 95% 以上句子的长度，再在这个前提下把batch_size调到显存上限。中文 NER 语料里，128 通常能覆盖绝大多数句子，个别超长句会被截断，截断位置如果正好切在实体中间，会引入噪声标签，这点在数据预处理时要留意。

4.4 评估指标怎么读

estimate.py一般会输出精确率、召回率和 F1。别只看 F1 一个数，要拆开看。精确率高、召回率低，说明模型保守，很多实体没识别出来，可能是训练不充分或者标签不平衡；召回率高、精确率低，说明模型乱标，可能是 CRF 约束没起作用或者学习率太大。按实体类别分别看指标也很重要，ORG类通常最难，因为机构名边界模糊、写法多样。

5. 避坑与排查：训练不收敛、标签错位、显存爆炸

5.1 训练 loss 不降或直接变 NaN

现象：第一个 epoch 的 loss 就是nan，或者几十步之后突然爆掉。原因通常是学习率过大，或者数据里有空句子、超长句子没处理干净。解决：先把lr降到 1e-5 试一轮，确认不是学习率问题；再检查scripts/utils.py里的数据加载，过滤掉长度为 0 的样本，对超长句做截断。梯度裁剪也是常用手段，在反向传播后加torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)，能挡住大部分梯度爆炸。

5.2 预测结果全是 O 或者标签整体错位

现象：推理时所有字符都被标成O，或者明明是人名却标成了地名。原因有两个方向：一是权重没加载成功，模型还是随机初始化状态；二是标签表和训练时不一致，索引对不上。解决：先确认predict.py里的权重路径存在且能加载，打印一下加载前后的参数是否变化；再对比训练和推理用的tag.txt是不是同一个文件，标签顺序必须完全一致。这个坑我踩过不止一次，标签错位是最隐蔽的，因为模型照样能跑，只是结果全错。

5.3 显存爆炸（CUDA out of memory）

现象：训练刚开始就报 OOM，或者跑到某个 batch 突然爆。原因：batch_size或max_seq_len太大，或者没有及时释放中间变量。解决：按 3.3 说的先降batch_size和max_seq_len；确认训练循环里每个 batch 结束后没有累积计算图，loss.backward()之后要optimizer.zero_grad()；如果用了梯度累积，注意累积步数不要设太大。另外，验证阶段记得加torch.no_grad()，否则验证也会建计算图，显存翻倍。

5.4 验证集 F1 虚高但实际效果差

现象：验证集 F1 很好看，换一批真实文本预测就拉胯。原因：训练集、验证集、测试集可能来自同一批数据随机切分，分布太接近，模型记住了模板而不是学到了泛化能力；或者数据里O标签占比过高，模型倾向于全预测O也能拿到不错的准确率。解决：看指标时优先看实体级别的 F1，而不是字符级准确率；如果条件允许，留一份完全不同来源的文本做最终验证。数据量太小的话，交叉验证比单次切分更可信。

6. 进阶技巧：用维特比解码和标签约束验证模型是否真的学到了

训练跑通只是第一步，真正判断这个 BERT-BiLSTM-CRF 有没有学到东西，要看它的解码过程。CRF 的维特比解码会输出最优标签路径，你可以把这条路径的分数打出来，和次优路径对比。如果最优和次优分数很接近，说明模型对这条序列没把握，实体边界可能就在附近摇摆。

一个具体做法是在predict.py里加一段调试代码，把 CRF 的发射分数和转移分数分别取出来看：

# 调试：查看 CRF 解码路径分数 with torch.no_grad(): emissions, _ = model(input_ids, attention_mask) best_path = model.crf.decode(emissions, mask=attention_mask) # 打印每个位置的发射分数，观察模型对边界的置信度 print("emissions shape:", emissions.shape) print("best path:", best_path)

逻辑说明：emissions是 CRF 层的输入分数，形状是[batch, seq_len, num_tags]，每个位置对每个标签都有一个分数。decode返回的是维特比解码后的最优路径。参数上，mask用来屏蔽 padding 位置，不加 mask 的话 padding 也会参与解码，结果会乱。通过观察emissions在实体边界处的分数分布，你能判断模型是真的区分开了B和I，还是靠 CRF 的转移约束硬撑。

另一个验证手段是人为构造非法标签序列，看 CRF 会不会给它低分。比如把O后面直接接I-PER这种非法转移喂进去，如果 CRF 的转移矩阵学得好，这条路径的分数应该明显低于合法路径。这一步能帮你确认 CRF 层是不是真的在起作用，而不是被 BERT 的输出淹没了。

我自己的习惯是，每次换数据集或者改结构之后，都强制走一遍「打印解码路径 + 构造非法序列对比分数」这两步。有一次我偷懒跳过，结果模型在测试集上 F1 看着还行，上线后实体边界错得一塌糊涂，回头查才发现 CRF 的转移矩阵几乎没更新，等于白接了一层。从那以后，不管多赶时间，这两步验证我都会跑一遍。希望这份拆解能帮你少走点弯路，把这份源码真正跑成自己的东西。

本文还有配套的精品资源，点击获取