简介：面向中文命名实体识别（NER）研究与实践的Python源码资源，整合了双向长短期记忆网络与条件随机场（BILSTM+CRF）、膨胀卷积与条件随机场（IDCNN+CRF）、预训练模型BERT结合双向长短期记忆网络与条件随机场（BERT+BILSTM+CRF）三条主流模型路线，并附带人民日报、MSRA等经典中文语料的预处理脚本，适合自然语言处理方向的学生、算法工程师以及以毕设、课设为目标的初学者参考。压缩包内共有五十八个文件，核心是十六个Python脚本，涵盖模型定义、数据清洗、训练与预测全流程；另有十九个编译后的缓存文件、九个文本说明、五张示意图、四个说明文档和三个XML工程配置文件，整体大小约十三点七五MB，目录结构清晰，便于按模块查阅。代码均经过运行测试，并配有说明文档和可视化结果图，学习与二次开发门槛较低。目前已有五百二十五人学习，多模型对比实现可帮助读者直观理解不同结构在中文实体识别任务中的表现差异，也能直接用于毕业设计或课程设计、项目初期立项演示。

1. 中文命名实体识别：三套主流模型的 Python 源码怎么落地

先回答最直接的问题：中文命名实体识别到底难在哪？难在中文没有天然空格分词、实体的边界和类别常常要依赖上下文，而常见的规则匹配和 HMM 在真实语料上很快就到天花板。这份 NER_DEMO 源码包把三条主流路线放在一起对比：BILSTM+CRF、IDCNN+CRF，以及热度最高的 BERT+BILSTM+CRF，并自带人民日报、MSRA 等数据集的预处理脚本和训练入口，对正在做课程设计、毕设或者刚接触序列标注的开发者来说，是少见的能直接跑起来的完整工程。它解决的是一类很具体的问题：从原始标注文本到最终能识别出人名、地名、组织名的完整链路，包含数据清洗、vocab 构建、模型训练、日志输出和预测。适合的人群是已经会写 Python、能看懂神经网络基本结构但没完整跑过 NER 项目的同学，或者想快速对比三种模型效果的候选人。

2. 目录结构和数据准备：先看懂这份资源怎么组织，再谈训练

2.1 源码包的文件清单和职责划分

拿到 NER_DEMO-master.zip 解压后，第一件事不是急着装环境，而是把目录结构摸清楚。整个工程可以分成四块：模型定义、数据预处理、公共工具、入口脚本。

• 模型定义部分放在根目录下，五个 Python 文件对应五种网络结构：BILSTM_CRF.py 是最经典的 BiLSTM 加 CRF 序列标注；IDCNN_CRF.py 是膨胀卷积替代 LSTM 的变体；IDCNN5_CRF.py 是 IDCNN 的加深版本；BILSTM_Attetion_CRF.py 在 BiLSTM 基础上加了 attention 层；BERT_BILSTM_CRF.py 则是用预训练 BERT 接 BiLSTM 再接 CRF 的最强组合。
• 预处理脚本在 DataProcess 目录下，msra_preprocessing.py、renminribao_preprocessing.py、data2_preprocessing.py 分别处理不同来源的数据集。process_data.py 负责统一流程。
• 工具层是 utils.py 和 path.py，前者存放标签映射、数据读取、批次生成这一类公共函数，后者统一管理数据、模型、日志的文件路径。
• 入口脚本是 train.py，所有模型的训练都从这里启动，日志输出到 log 目录下。

提示：先打开 README.md 再动手，它会说明当前代码依赖的深度学习框架版本以及各模型对应哪个数据集格式。这能帮你省掉最常见的框架不兼容问题。

2.2 数据集的格式标准和 vocab 构建流程

NER 训练数据的标准格式是每一行一个词，空行分隔句子，标签序列和词语序列按行对齐。以人民日报语料为例，预处理脚本会把原始文本解析成这种格式保存，比如“中 国 B-ORG”“人 民 E-ORG”“银 行 B-ORG”这种 BIESO 标注体系。

vocab.py 和 process_data.py 负责把清洗后的文本转成训练用的 id 序列。vocab 构建的核心逻辑是把每个字符映射到一个唯一的索引，再补充特殊标记。常见做法是把 vocab 分成四个部分：<pad> 用于批内补齐、<unk> 用于未登录词、<sos> 和 <eos> 用于句子边界。具体代码逻辑一般是：

def build_vocab(files, min_count=1): word_count = {} for file in files: for line in open(file, encoding="utf-8"): for char in line.strip(): word_count[char] = word_count.get(char, 0) + 1 vocab = {word: idx for word, idx in zip(["<pad>", "<unk>", "<sos>", "<eos>"], range(4))} for word, count in word_count.items(): if count >= min_count: vocab[word] = len(vocab) return vocab

这段代码先统计所有字符的出现次数，再按最低频次过滤低频字符。min_count 取 1 时保留全部字符，取 2 或 3 时能过滤一部分错别字和噪声，但也会让模型对生僻字的泛化能力下降。我一般会先把 min_count 设为 1 跑通，再看训练集大小决定是否过滤。

2.3 预处理脚本的参数含义和实际用法

msra_preprocessing.py 是处理 MSRA 数据集的典型例子。原始 MSRA 语料以换行符分隔句子，每行是一句完整的中文句子，附带的标注文件需要按字符位置对齐才能生成训练数据。

python msra_preprocessing.py --input_dir ./data/msra_raw --output_dir ./data2

这个命令把 MSRA 原始文本和标注文件转换成统一的 BIO 格式输出到 data2 目录。脚本内部会检查句子长度、标签对齐关系，如果发现字符数和标签数不匹配会自动跳过该句。运行完检查 data2 下的文件行数是否和原始标注数据大致匹配，如果出现大量句子被跳过，通常是原始标注文件里有全角空格或空行，需要先做清洗。

参数说明：--input_dir 指向原始数据目录，--output_dir 指向处理后数据存放的位置。不同数据集脚本的输入输出参数基本一致，这套工程的预处理脚本是按统一接口设计的，所以换数据集时不需要改模型代码。

2.4 环境配置和快速验证数据完整性

训练前先确认三件事：PyTorch 版本、GPU 是否可用、transformers 库是否安装。BERT 模型需要从 huggingface 加载预训练权重，而国内网络环境下载中文预训练模型通常比较慢，建议先手动下载 chinese_L-12_H-768_A-12 到本地 data 目录。

pip install torch transformers tqdm numpy python train.py --model BERT_BILSTM_CRF --epochs 3 --batch_size 8 --gpu 0

注意：如果报 transformers 加载权重超时，直接把预训练模型下载到 data/chinese_L-12_H-768_A-12 目录，然后修改 path.py 里的预训练模型路径指向本地目录，能大幅缩短启动时间。

3. 三种模型的原理和训练配置：为什么选 BiLSTM+CRF、IDCNN+CRF 和 BERT+BiLSTM+CRF

3.1 BiLSTM+CRF 的原理和代码走读

BiLSTM+CRF 是序列标注领域的经典结构，很多线上 NER 系统到目前仍是这套组合。BiLSTM 负责编码上下文信息，把字符序列转换成每个位置对应的隐状态向量，而 CRF 层负责学习标签之间的转移约束，比如“B-PER 后面不能直接跟 E-ORG”这样的规则。

class BiLSTM_CRF(nn.Module): def __init__(self, vocab_size, tag_size, embedding_dim=128, hidden_dim=256): super(BiLSTM_CRF, self).__init__() self.embedding = nn.Embedding(vocab_size, embedding_dim) self.lstm = nn.LSTM(embedding_dim, hidden_dim // 2, num_layers=1, bidirectional=True, batch_first=True) self.hidden2tag = nn.Linear(hidden_dim, tag_size) self.crf = CRF(tag_size)

这段代码里 embedding_dim 是字符向量维度，hidden_dim 是 LSTM 隐层大小，因为是双向结构所以 hidden_dim 会被平分到两个方向。CRF 层接收 LSTM 输出的发射分数矩阵，然后通过维特比解码找到最优标签序列。训练时使用负对数似然损失，这个损失由真实路径分数减去所有可能路径的 logsumexp 分数得到。

3.2 IDCNN+CRF 的结构差异和适用场景

IDCNN 是膨胀卷积网络的缩写，它在普通 CNN 的基础上引入了不同膨胀率的卷积核，让感受野在不增加参数量和层数的情况下指数级扩大。和 BiLSTM 相比，IDCNN 的训练速度更快，推理时也不需要逐步计算，适合对实时性有要求的场景。

class IDCNN_CRF(nn.Module): def __init__(self, vocab_size, tag_size, filters=128, dilations=[1, 1, 2]): super(IDCNN_CRF, self).__init__() self.embedding = nn.Embedding(vocab_size, embedding_dim) self.idcnn = IDCNN(filters=filters, dilations=dilations) self.linear = nn.Linear(filters, tag_size) self.crf = CRF(tag_size)

dilations 参数是 IDCNN 的核心控制项，[1, 1, 2] 表示三层卷积的膨胀率分别是 1、1、2。膨胀率为 1 时是普通卷积，膨胀率为 2 时每个卷积核的采样点间隔为 1 个字符。实际使用中 IDCNN5_CRF.py 会叠加更多层以扩大感受野。这里的核心权衡是：膨胀率越大感受野越大，但过大会导致局部信息丢失，所以工程上常采用多组小膨胀率的堆叠而不是一组大膨胀率。

3.3 BERT+BiLSTM+CRF 的模型结构和训练技巧

BERT+BILSTM+CRF 是目前效果最好的组合之一，原理是先用 BERT 预训练模型生成融合上下文语义的字符向量，再把向量序列输入 BiLSTM 进一步编码，最后由 CRF 解码。这份源码里 BERT 部分用的是 chinese_L-12_H-768_A-12，即 12 层 transformer、768 维隐层，这是 BERT-base 的中文版本。

class BERT_BILSTM_CRF(nn.Module): def __init__(self, bert_path, tag_size, hidden_dim=256): super(BERT_BILSTM_CRF, self).__init__() self.bert = BertModel.from_pretrained(bert_path) self.lstm = nn.LSTM(768, hidden_dim // 2, bidirectional=True, batch_first=True) self.hidden2tag = nn.Linear(hidden_dim, tag_size) self.crf = CRF(tag_size) def forward(self, input_ids, attention_mask, labels=None): outputs = self.bert(input_ids, attention_mask=attention_mask) sequence_output = outputs[0] lstm_out, _ = self.lstm(sequence_output) emissions = self.hidden2tag(lstm_out) if labels is not None: loss = -self.crf(emissions, labels, mask=attention_mask) return loss return self.crf.decode(emissions, mask=attention_mask)

训练 BERT 系模型时有几个关键点。一是学习率要比 BiLSTM 模型低一等数量级，BERT 部分的微调学习率一般设置在 5e-5 到 2e-5，而 BiLSTM 部分可以用 1e-3；二是 batch_size 受显存限制通常只能设 8 到 16，所以训练轮数要相应增加；三是最耗时间的不是构思模型而是 BERT 预训练权重的加载，建议固定随机种子保证可复现。

3.4 三种模型的选型对比和场景建议

三种模型的效果和代价差异非常明显。在一个 2 万句规模的中文语料上，BiLSTM+CRF 训练大约需要 2 到 4 小时，IDCNN+CRF 能快 30% 以上，而 BERT+BiLSTM+CRF 在同样数据上可能要多花 4 到 8 小时，但 F1 值通常能高 3 到 8 个百分点。

4. 训练与调参实战：从启动命令到日志分析，全流程可复现

4.1 训练入口的参数体系和启动方式

train.py 是整个工程的统一入口，通过 --model 参数选择不同的模型结构。这个脚本定义了完整的训练循环，包括批次生成、反向传播、梯度裁剪、验证集评估和模型保存。

# 训练 BiLSTM+CRF 模型 python train.py --model BILSTM_CRF --epochs 10 --batch_size 32 --lr 0.001 # 训练 IDCNN+CRF 模型 python train.py --model IDCNN_CRF --epochs 10 --batch_size 32 --lr 0.001 # 训练 BERT+BiLSTM+CRF 模型 python train.py --model BERT_BILSTM_CRF --epochs 3 --batch_size 8 --lr 5e-5

第二个命令运行时会在根目录创建一个 log 目录，每次训练会生成一个以时间戳命名的输出文件。日志里记录了 loss 和准确率等指标，训练到最优 F1 时保存模型权重。这里 --lr 的选择很讲究：对于 BiLSTM 和 IDCNN，0.001 是 Adam 优化器的默认推荐值；BERT 模型必须调低，否则预训练权重很快会被冲掉。

提示：使用 BERT_BILSTM_CRF 模型前先检查 python train.py --help 输出的参数列表，确认当前代码里 BERT 相关参数名是否带 bert_ 前缀，不同版本的源码差异很大。

4.2 train.py 核心训练循环的代码走读

for epoch in range(args.epochs): for batch in train_batches: optimizer.zero_grad() loss = model(batch.ids, batch.labels) loss.backward() nn.utils.clip_grad_norm_(model.parameters(), 5.0) optimizer.step() val_f1 = evaluate(model, valid_batches) print(f"epoch {epoch}, loss {loss.item():.4f}, F1 {val_f1:.4f}")

这里最关键的是 clip_grad_norm_ 这一行，把梯度的 L2 范数裁剪到 5.0，防止 LSTM 在长序列上出现梯度爆炸。设置太小会导致模型收敛变慢，设置太大等于没裁剪。在 BiLSTM+CRF 的序列标注任务里，我一般会先用 5.0 起步，如果 loss 出现 NaN 就降到 1.0。evaluate 函数在验证集上做维特比解码，统计实体的精确率、召回率和 F1 值。

4.3 验证集和测试集的划分逻辑

数据切分时训练集、验证集、测试集的比例按照 8:1:1 划分，验证集用于每个 epoch 结束后评估并选择保存哪一版模型，测试集只做最终评估不参与调参。在实际使用中验证集切分时需要按句子分而不是按字符分，因为同一句子的字符同时出现在训练集和验证集会污染数据。此外数据文件在预处理阶段就做了随机打乱，所以训练时 story 层的批次生成不再重复 shuffle。

4.4 从日志判断模型是否正常收敛

模型跑起来后的 30 分钟内基本就能看出问题。正常收敛的 loss 曲线是平滑下降的，偶尔有小幅波动但在合理范围内；如果 loss 在前 100 个 batch 内直接降到接近 0，大概率是标签对齐错了，或者 CRF 层的转移矩阵初始化出了问题。另一个常见现象是训练集 F1 很高但验证集 F1 很低，这说明过拟合已经出现，把 dropout 打开或者提前停止训练即可。

参数组合建议：语料在 1 万句以下时用 BiLSTM+CRF，embedding_dim 设 128，hidden_dim 设 256，dropout 设 0.5，训练 15 轮左右；语料在 3 万句以上且 GPU 显存大于 8G 时再上 BERT+BiLSTM+CRF，batch_size 从 4 起步，显存不够就加梯度累积，用 4 个 batch 累积一次反向传播，等效于 batch_size 为 16。

5. 避坑与常见问题：我在复现这套源码时踩过的五个真实坑

5.1 Python 版本和依赖冲突

现象是运行 train.py 时 import 阶段报错，错误信息显示某个库的模块里没有需要的函数，比如 transformers 的 BertModel 加载失败。原因是源码是基于较老的 PyTorch 版本编写的，现代版本的 transformers 接口不再兼容旧版写法。解决办法是把 transformers 降级到 4.x 早期版本，同时 PyTorch 安装在 1.8 到 2.0 之间。如果非要使用新版，需要手动修改 BERT_BILSTM_CRF.py 中的 from_pretrained 调用方式。

5.2 预处理阶段句子被大量跳过

现象是 msra_preprocessing.py 运行结束后输出文件的行数比原始标注文件少了很多。原因是原始语料里有很多全角空格、连续换行和编码不一致的字符，脚本在检查标签对齐时会跳过这些异常句子。解决方法是先用文本编辑器把原始数据统一转成 UTF-8 编码，删除所有全角空格，再重新运行预处理。如果 skip 率还是超过 5%，用 Python 脚本打印几条被跳过的样本，看看具体是在哪个环节断掉的。

5.3 BERT 权重加载超时

现象是第一次启动 BERT_BILSTM_CRF 训练时，程序长时间卡在 from_pretrained 这一步，最后报网络超时错误。原因是 huggingface 的预训练权重下载地址在国内访问不稳定，尤其是 chinese_L-12_H-768_A-12 这个文件，体积接近 400M。解决方法是手动下载权重文件后放到 data/chinese_L-12_H-768_A-12 目录，然后在 path.py 或直接用 from_pretrained 指定本地路径。

5.4 Sigmoid 和 Softmax 混淆导致的实体边界错误

现象是 BERT_BILSTM_CRF 的 loss 一直在下降，但验证集上预测出来的实体永远只有单字，不会有连续的多个字。原因是部分实现把输出层误写成 sigmoid 激活然后按阈值判定，而不是用线性层输出发射分数交给 CRF 解码。CRF 的维度数量必须等于标签数加一，因为起始标记要单独占一个位置，这个细节属于最隐蔽的那类问题，排查时直接看标签类别数量和预测结果来定位。

5.5 显存不足和 OOM 崩溃

现象是 BERT_BILSTM_CRF 模型训练到第二个 epoch 时直接报 CUDA out of memory 崩溃。原因是 BERT 本身占用显存非常高，batch_size 设成 32 对 12G 显存来说完全不现实。解决办法是把 batch_size 降到 4，同时在 data 加载时用 num_workers 提高数据吞吐。要是还撑不住，就检查训练代码里是否每个 epoch 结束后把梯度和中间变量都释放了，这通常能省出 30% 的显存。

6. 进阶验证与微调技巧：让三套模型在自定义数据集上真正可用

6.1 用模型预测结果做人工校验

训练好模型后，不能只看 F1 值就认为完事了。我习惯准备一份不带标签的测试文本，直接跑预测来看实际输出。抽取一段新闻文本，模型输出的实体列表如果能把“北京”“腾讯”“小明”等实体准确切分出来，说明边界没有问题；如果连续出现实体被拆分或合并，大概率是标签体系的 BIO 和 BIESO 不一致。

python train.py --model BILSTM_CRF --predict --input_text "小明来自北京，在腾讯担任算法工程师。"

这段伪代码展示的是预测入口的方式。实际源码中会把预测逻辑封装在 eval 分支，或者提供单独的小脚本读取训练好的模型参数。输出格式通常是一行文字加一行对应标签，人工检查时重点看三类错误：实体漏召回、实体内多字、实体间粘连。

6.2 自定义数据集的标签体系对齐

每个数据集都有自己的一套标签体系。人民日报语料常用 PER、ORG、LOC 三类，一些金融语料还会增加 DATE、MONEY 等类别。在换数据集前，必须做两件事：把原始标注统一成 BIO 格式，标签类别映射表要和 utils.py 里的 category_to_index 对应。

常见做法是先写小脚本把数据转成通用格式，标签用 B-xxx、I-xxx、O 这三种基础标记，然后在需要的时候转换成 BIESO 的 B、I、E、S、O 五种标记来切分单字实体。这里的核心准则是：标签不统一的问题要在预处理阶段解决，不要指望模型自己适应不同标签体系。

def convert_bio_to_bieso(labels): # labels 是一串 Bio 标签的列表 converted = [] for idx, label in enumerate(labels): if label.startswith("B-"): # 如果下一个是 O 或者 B 开头，说明这是单字实体 if idx + 1 >= len(labels) or labels[idx + 1] == "O" or labels[idx + 1].startswith("B-"): converted.append("S-" + label[2:]) else: converted.append("B-" + label[2:]) elif label.startswith("I-"): if idx + 1 >= len(labels) or labels[idx + 1].startswith("B-") or labels[idx + 1] == "O": converted.append("E-" + label[2:]) else: converted.append("I-" + label[2:]) else: converted.append("O") return converted

这段转换逻辑的处理顺序是：先判断是否为单字实体，再决定标记是 B、I、E 还是 S。转换完成后必须检查一下代码里 CRF 层的标签数量是否等于五类乘实体类别数加 O，否则张量维度就会报错。

6.3 学习率衰减和早停策略

如果训练到后期 F1 值一直在 80 到 82 之间震荡不上升，问题大概率是学习率没做衰减。我的习惯是每两个 epoch 把学习率乘 0.8，或者在验证集 F1 连续三个 epoch 不增长时把学习率减半。早停设置在验证 F1 连续五个 epoch 不提升时直接停止训练，并加载历史上最优权重，这个办法能明显减少 BERT 模型在过拟合边缘的无效训练时间。

6.4 多模型集成的一个轻量技巧

资源包里五套模型经常被当成选择题，其实可以做成组合。时间允许的话，用同一个验证集分别训练 BiLSTM+CRF、IDCNN+CRF 和 BERT+BILSTM+CRF，在预测阶段把三个模型的输出做投票，或者对每个 token 计算不同模型的概率平均。实际体验中 BERT 模型的权重通常要比其他两个略高，0.5 比 0.3 比 0.2 的组合在多数数据集上效果不错。虽然比单一模型增加了一些推理耗时，但性能不稳定时用 10 分钟换取几个点的准确率提升是划算的。

这类的坑我在每一次换数据集时都会再踩一遍，尤其是标签体系对齐和预处理阶段的数据清洗。后来养成的习惯是：不管用什么数据集，先跑完预处理脚本后马上检查行数和异常样本，再进入训练环节。从拿到这份源码到完全跑通，我前前后后花了大半天时间，但把里面的坑摸清后，后续换任何数据都能在两小时内完成全流程。

希望这份实战笔记能帮到你，沿着这个流程走，三套模型都能顺利跑起来。

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