简介一套面向中文命名实体识别NER的完整项目源码基于BERTBILSTMCRF混合模型实现同时包含IDCNN、注意力机制等对比方案适合计算机相关专业学生用于毕业设计、课程设计、大作业或企业实战演练。资源压缩包共58个文件主要包含16个Python源码、19个pyc编译文件、9个txt说明文档、5张网络结构图、4份Markdown笔记以及少量配置文件整体约13.75MB目录按数据预处理、模型定义、训练入口、日志展示等模块清晰划分便于快速定位与二次开发。数据侧提供人民日报、MSRA等公开语料的预处理脚本可将原始文本转换为BERT标准输入格式并配备中文预训练模型chinese_L-12_H-768_A-12训练流程完整可复现。项目说明中详细介绍了模型原理、参数设置、训练步骤及效果评估方法可直接运行体验也可替换自有数据开展实验。目前已有1209人学习下载对希望系统掌握序列标注模型、快速搭建中文NER实验环境的读者具有较高借鉴价值。1. 拿到这份“BERTBILSTMCRF中文命名实体识别”源码包先别急着跑训练很多人刚下载这个zip第一反应是直接解压、装依赖、跑train.py然后盯着终端里的loss发呆。我见过太多人卡在模型跑起来但预测出全是“O”标签或者一改batch_size就显存爆炸。这个包解决的是中文序列标注里的一个核心任务从一段中文文本里自动抽出人名、地名、机构名等实体而它选用的模型结构是BERT做动态词向量、BiLSTM抓上下文、CRF做标签约束——这套组合在中文NER任务里几乎是“标准答案”。适合写过分类模型、但对序列标注和预训练模型接入还不熟的人也适合想快速在上线前验证BERT在自有数据上能提几个点的人。跟着这篇文章你能把原理、代码、参数和坑一次理清。2. 为什么是BERTBiLSTMCRF三个组件各守一道关在动手跑代码之前先花几分钟把这三层结构为什么叠在一起想清楚。单独一个BERT就能输出每个字的向量表示但BERT本身不擅长处理“标签之间的依赖关系”单独一个BiLSTM能利用上下文但它的输出是独立的字级概率没法保证“B-Person后面必须跟I-Person”这类规则单独一个CRF又缺乏语义特征。所以这三者是一个典型的“特征抽取器序列解码器”搭配。2.1 BERT把“一字多义”变成真正的动态向量中文里同一个字在不同语境里含义完全不同。“长”在“长度”和“成长”里应该有不同的向量表示。传统Word2Vec训练出来的词向量是静态的不管上下文是什么同一个词永远只有一个向量这对实体识别是硬伤——因为“苹果”可以是水果也可以是公司。BERT通过Transformer的多层自注意力机制让每一个字的向量都带着整个句子的上下文信息所以叫动态词向量。在代码实现里你一般会加载一个预训练的BERT中文模型比如huggingface的bert-base-chinese。这一步常见的做法是from transformers import BertModel, BertTokenizer tokenizer BertTokenizer.from_pretrained(bert-base-chinese) bert_model BertModel.from_pretrained(bert-base-chinese)这里的bert-base-chinese是12层、768维、约1.1亿参数的中文预训练模型。它按字切分不依赖分词器正好和中文NER的“按字标注”策略对齐。注意如果你用的是bert-base-multilingual-cased虽然也支持中文但它的词表是按多语言合并的在纯中文任务上通常比专用中文模型差一点。实际项目里我首选bert-base-chinese显存允许的话可以换huggingface上的chinese-roberta-wwm-ext后者用全词掩码预训练对中文实体边界更友好。2.2 BiLSTM从句子里抓“前看后看”的序列特征BERT已经输出了每个字的向量为什么还要再接一层BiLSTM两个原因。一是BERT的输出是字级别的上下文表示但实体识别需要更聚焦于“局部模式”比如“张三”这个人名BERT向量经过了全句信息融合反而可能被句中无关信息干扰BiLSTM对这种局部顺序模式更敏感。二是BERT的Transformer结构一次看全句而BiLSTM是真正地按时间步单向传播能捕捉到实体内部字与字的递进关系两者互补。BiLSTM的forward部分很直接import torch.nn as nn class BiLSTMDecoder(nn.Module): def __init__(self, input_size, hidden_size, num_labels): super().__init__() self.lstm nn.LSTM( input_size, hidden_size, bidirectionalTrue, batch_firstTrue ) self.dropout nn.Dropout(0.5) self.classifier nn.Linear(hidden_size * 2, num_labels) def forward(self, bert_outputs): lstm_out, _ self.lstm(bert_outputs) lstm_out self.dropout(lstm_out) logits self.classifier(lstm_out) return logits这里hidden_size通常取128或256num_labels是你标注体系里标签的数量比如BIO模式下是3个标签B、I、O还是更多类别。一个容易忽略的参数是batch_firstTrue这决定了输入张量是(batch, seq_len, hidden)而不是(seq_len, batch, hidden)。PyTorch默认是False如果你在组装batch时没注意维度的先后训练会直接报错或者loss越跑越不对劲。2.3 CRF让标签序列不说“不合法”的话BERT和BiLSTM输出的每个字对应各个标签的分数但这还不够。比如在BIO标注体系里“B-Person”后面跟了一个“O”是合法的但“B-Person”后面直接跟“I-Organization”就不合法——同一个实体内部的标签类型必须一致。CRF层就是干这个的它学习一个“标签转移矩阵”在解码时用维特比算法找到整条句子最可能的标签序列而不是逐字取最大概率。在PyTorch生态里最常用的是torchcrf库from torchcrf import CRF crf CRF(num_tagsnum_labels, batch_firstTrue)训练时你要把BiLSTM输出的logits和真实标签一起传给CRF它会返回负的对数似然损失推理时调用crf.decode(logits)就能拿到全局最优的标签序列。这个“全局最优”是CRF的灵魂也是它比纯Softmax多出来的那部分能力。2.4 三者串起来的整体结构把上面三层拼起来前向传播就是句子输入BERT得到每个字768维的向量序列接一个线性层降维常见降到256维进BiLSTM输出的双向隐层拼起来变成hidden_size * 2的向量再过一个线性层映射到num_labels个标签的得分最后丢给CRF解码。梯度会从CRF反向传播到整个网络所以BERT也会被微调。工程上微调BERT会让实体识别F1值在大多数数据集上提升3到5个百分点代价是显存和训练时间翻倍。如果你的数据量很少比如几千条可以选择冻结BERT参数只训练下半部分否则很容易过拟合。3. 复现环境的“最小可跑”清单从Python安装到数据格式拿到源码包第一步不是看模型代码而是先让你的电脑能跑起来。很多人在这个环节翻车是因为环境变量没配好导致装了Python却找不到命令。这里把常见做法写清楚照做就行。3.1 先把Python和依赖装干净这个项目需要Python 3.8以上版本。装完之后打开终端依次确认三件事python --version pip --version nvidia-smi如果python命令找不到多半是Windows下安装时没勾选“Add Python to PATH”。不用重新装直接进系统环境变量把Python的安装目录和Scripts子目录加到Path里再开一个新终端就生效了。依赖安装我通常会用一个requirements.txtpip install torch pip install transformers pip install torchcrf pip install tqdm scikit-learn numpy这里有几个容易踩的坑torch和torchcrf的版本要匹配纯CPU版也能跑但训练速度会慢到让你怀疑人生transformers版本太新可能会导致某些参数名变了常见做法是装4.x版本比如pip install transformers5。安装完跑一句import torch, transformers, torchcrf print(torch.__version__, transformers.__version__, torchcrf.__version__)能正常打印版本号环境就打通了。3.2 中文NER的标准标注格式BIO/BIOES这个项目的训练数据一般用BIO或者BIOES标注。BIO是三个标签B表示实体开头I表示实体内部O表示非实体。BIOES更细一点多了E表示实体结尾S表示单个字成实体。BIOES对小实体更友好但标签更多模型复杂度略高。数据文件常见格式是每一行一个字和一个标签用制表符分隔空行表示句子结束张 B-Person 三 I-Person 是 O 北 B-Organization 京 I-Organization 大 I-Organization 学 I-Organization 的 O 学 O 生 O这里的标签是B-Person、I-Person、B-Organization等每个实体类型都要有自己的B和I。也有数据集用JSON组织但最通用的是这种逐行格式因为它是BIO标注工具默认导出格式也是Huggingface的conll2003格式变种。3.3 这个压缩包里通常有什么文件清单根据标题推断这个zip里应该包含源码、项目说明、模型权重和标注数据。常见结构是文件/目录作用train.py训练入口model.py定义BERTBiLSTMCRF结构data_process.py读取原始标注并转换IDpredict.py加载模型做推理data/训练集、验证集、测试集model/训练好的BERT权重README.md项目说明如果你打开压缩包发现没有requirements.txt就按上面3.1节自己建一个。没有model/目录说明权重需要自己训练生成。别急着找别人要现成模型先用自己的数据跑通流程比什么都有用。4. 训练主流程源码里最核心的4段代码这一章是整个包的核心。通常源码会拆成数据加载、模型定义、训练循环和预测脚本四个文件但核心逻辑就几段。我按实际运行顺序拆开讲每一段都可以对照你自己的源码看。4.1 数据加载把字符和标签变成模型能吃的IDBERT模型接收的是token id不是原始汉字。所以要先把句子里的每个字映射到BERT词表里对应的id再把标签映射成数字。常见做法是def build_vocab(tag_list): tag2id {tag: idx for idx, tag in enumerate(tag_list)} id2tag {idx: tag for tag, idx in tag2id.items()} return tag2id, id2tag def encode_sentence(sentence, tokenizer, tag2id, max_len): tokens list(sentence) input_ids [] label_ids [] for char in tokens: tid tokenizer.convert_tokens_to_ids(char) input_ids.append(tid) # 截断和padding到max_len input_ids input_ids[:max_len] [0] * (max_len - len(input_ids)) label_ids label_ids[:max_len] [0] * (max_len - len(label_ids)) return input_ids, label_ids这里有个关键点max_len要设置成训练数据里最长句子的长度通常是128或256。如果设太短长句子里的实体会被截掉设太长显存开销白白增加。label_ids里的padding标签不能是0因为0在BIO里通常是O如果padding用0模型会学着把无效位置都预测成O。正确做法是给padding单独分配一个标签ID比如把标签ID从1开始或者用-100作为mask让loss计算跳过这些位置。后面第5章会详细讲这个坑。4.2 模型定义BERT底座BiLSTMCRF把前面2.4节的结构写成一个nn.Moduleclass BertBilstmCrfModel(nn.Module): def __init__(self, num_labels, pretrained_pathbert-base-chinese): super().__init__() self.bert BertModel.from_pretrained(pretrained_path) self.lstm nn.LSTM(768, 256, bidirectionalTrue, batch_firstTrue) self.dropout nn.Dropout(0.5) self.fc nn.Linear(256 * 2, num_labels) self.crf CRF(num_tagsnum_labels, batch_firstTrue) def forward(self, input_ids, attention_mask, labelsNone): bert_out self.bert(input_idsinput_ids, attention_maskattention_mask).last_hidden_state lstm_out, _ self.lstm(bert_out) lstm_out self.dropout(lstm_out) logits self.fc(lstm_out) if labels is not None: # 把attention_mask转成布尔mask让CRF跳过padding位置 mask attention_mask.bool() loss -self.crf(logits, labels, maskmask, reductionmean) return loss else: prediction self.crf.decode(logits, maskattention_mask.bool()) return prediction这里的last_hidden_state是BERT输出的所有token向量形状是(batch, seq_len, 768)。BiLSTM的输入维度必须是768和BERT保持一致。如果显存有限可以把BertModel换成bert-base-chinese的蒸馏版本比如distilbert-base-chinese输入维度变成768不变但层数少了速度能快一倍精度掉得不多。4.3 训练循环loss计算和梯度更新训练循环不复杂但有几个细节决定能不能收敛for epoch in range(epochs): model.train() total_loss 0.0 for batch in dataloader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[labels].to(device) optimizer.zero_grad() loss model(input_ids, attention_mask, labels) loss.backward() optimizer.step() total_loss loss.item()loss由CRF层返回是负对数似然。这里注意attention_mask必须传给CRF否则CRF会把padding位置当成普通标签参与转移计算导致label bias。另外BERT部分的学习率应该比BiLSTM小一个数量级常见做法是设置两组参数optimizer torch.optim.AdamW([ {params: model.bert.parameters(), lr: 2e-5}, {params: model.lstm.parameters(), lr: 1e-3}, {params: model.fc.parameters(), lr: 1e-3}, {params: model.crf.parameters(), lr: 1e-3}, ])这是BERT微调的通用配比BERT用2e-5下游层用1e-3。如果只跑10个epoch以内这个配比基本稳定。如果数据量大可以把BERT的学习率调到5e-5但要盯着验证集F1值防止过拟合。4.4 参数表learning_rate、batch_size、max_len怎么调训练时你会看到源码里有一堆超参数我把最重要的几个列出来方便照着调参数常见值调参方向max_len128大于训练数据中90%句子的长度即可batch_size8显存12G显存不足先减半不要直接改max_lenlearning_rate(BERT)2e-5微调时最好不要超过5e-5否则特征崩溃learning_rate(下游)1e-3过拟合就降到5e-4epochs10-30看验证集F1早停更可靠lstm_hidden_size256加大到512能学更多但训练时间变长还有两个你可能会遇到的困惑为什么batch_size不能设成32因为BERT加BiLSTM的显存占用比普通分类模型大很多12G显存下batch_size8已经算激进。为什么epochs设30还不够因为BERT微调在少量数据上很容易过拟合验证集F1会先升高后突然下降与其盲目加epoch不如加一个“如果连续3个epoch验证集F1没提升就停止”的早停逻辑。5. 避坑记中文NER最常见的5个翻车现场这部分是血泪经验汇总。每个坑我都详细拆成“现象→原因→解决”方便你对号入座。5.1 标签错位训练loss很低但预测全乱现象训练时loss降到零点几但拿一条新句子预测所有标签输出都是O或者全是乱序标签。原因数据加载环节标签和输入没对齐。最常见的是BERT的tokenizer对某些中文标点做了特殊处理比如全角空格被拆掉导致输入序列长度和标签序列长度不一致。还有一种是padding标签用了0CRF把大量padding位置当成真实标签来学习模型被带偏。解决在encode_sentence里加断言确保每个字符对应一个标签。使用attention_mask代替手动padding标签CRF计算时跳过mask为False的位置。推荐做法是在数据处理好后用一条测试样本打印len(input_ids)len(label_ids)确认后再进模型。5.2 GPU显存不够batch_size一调大就OOM现象batch_size从8改成16直接报CUDA out of memory。原因BERT的中间激活值占显存极大序列长度和batch_size乘积一旦超限就爆。另外很多人的代码里没有释放中间变量导致显存碎片化。解决先调小max_len比如从256降到128显存占用会立竿见影地下降。如果还不够用梯度累积模拟大batchaccumulation_steps 2 for i, batch in enumerate(dataloader): loss model(...) loss loss / accumulation_steps loss.backward() if (i 1) % accumulation_steps 0: optimizer.step() optimizer.zero_grad()这相当于用2个小batch合一个大batch。另外检查PyTorch的torch.cuda.empty_cache()是不是没在每个epoch后调用偶尔释放一下也能缓解碎片问题。5.3 BERT加载慢得离谱不是网速问题现象第一次执行BertModel.from_pretrained(bert-base-chinese)等了半小时还没下载完于是怀疑笔记本网络有问题。原因这是正常的预训练权重文件约400MB从Huggingface下载在国内网络环境下确实慢。但如果你已经下载过第二次加载还慢那就是缓存路径问题。解决先把模型下载到本地目录再改加载路径# 用huggingface-cli下载 huggingface-cli download bert-base-chinese --local-dir ./bert_base_chinese然后代码里改成model BertModel.from_pretrained(./bert_base_chinese)这样完全离线加载秒开。注意不要删掉config.json和vocab.txt他们和权重文件是配套的。5.4 CRF损失出现NaN手工实现和库版本冲突现象训练到第2个epochloss突然变成nan。原因可能是transformers新版和torchcrf的mask参数类型不兼容。torchcrf的mask需要布尔张量但你从attention_mask拿过来的是浮点张量[1,0]CRF内部在做布尔运算时出错梯度爆炸。解决在传mask前强制转换mask attention_mask.bool() loss -self.crf(logits, labels, maskmask, reductionmean)如果问题仍在检查学习率是不是太高。BERT微调时如果学习率超过1e-4很容易让CRF的转移分数发散。把BERT学习率降到2e-5同时给CLIP加一个梯度裁剪torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm5.0)5.5 中文按字切还是按词切结果差距很大现象用同样的代码同事把句子先分词再送BERT你的代码按字切两个人的F1差了好几个点。原因BERT的中文预训练模型本质是按字切分的词表里没有“北京大学”这种词只有“北”、“京”、“大”、“学”这些字。如果你强行分词再映射每个词被拆成多个token标签序列长度对不齐CRF学到的边界约束全乱了。解决直接按字切分。BertTokenizer会自动处理中文你只需要把原始字符串list(sentence)成字符列表。如果一定要用词级别的标注数据那就得用BERT配套的切词器把词转成子词并做标签的“有损对齐”——这是另一个复杂的工程新手期不建议碰。这个包既然叫中文命名实体识别默认就是按字级做。6. 让模型正式上岗推理脚本与性能验证技巧训练完的模型要能对新句子预测。这里的核心是不要重新走一遍训练时的forward而是加载已保存的权重在推理模式下输出。def predict(model, tokenizer, sentence, max_len128): model.eval() input_ids tokenizer.encode(sentence, max_lengthmax_len, truncationTrue, return_tensorspt).to(device) attention_mask (input_ids ! 0).long().to(device) with torch.no_grad(): pred_ids model(input_ids, attention_mask) # 返回decode后的标签id列表 id2tag ... # 从训练时保存的id2tag映射加载 tags [id2tag[i] for i in pred_ids[0]] entities [] current_entity None for char, tag in zip(sentence, tags): if tag.startswith(B-): if current_entity: entities.append(current_entity) current_entity [char, tag[2:]] elif tag.startswith(I-) and current_entity and current_entity[1] tag[2:]: current_entity[0] char else: if current_entity: entities.append(current_entity) current_entity None if current_entity: entities.append(current_entity) return entities这里注意model(input_ids, attention_mask)在推理模式下返回的是CRF解码出的标签ID序列不是概率分布所以不要再做argmax。decode用的维特比算法已经帮你找到了全局最优路径这是CRF相比softmax的优势。关于验证我给你三个实际验证技巧。第一不要只跑一遍测试集就下结论用5折交叉验证来看F1的均值和方差方差小才说明模型稳定。第二把预测错例打印出来按实体类型分类统计你会发现人名错误多半是生僻字地名错误多半是“北京”和“北京大学”的边界切分问题针对性修复标注比调参有用得多。第三如果线上实体有优先级比如识别出的多个实体互相重叠可以给每个实体类型设一个置信度阈值低于阈值就丢弃。这个包本身不带阈值机制你可以给CRF的Decode加一个nbest参数拿到候选序列后取top1和top2的分数差作为置信度。我自己做中文NER的习惯是先把模型训练到验证集F1不再变化然后冻结上半部分单独用标注数据微调CRF层通常能再涨一点。这招听起来玄学但确实在不少数据集上有效。希望你也能从这份源码里把该拿的拿稳别在标签错位和显存上耗掉太多时间。希望帮到你。本文还有配套的精品资源点击获取 BERT+BiLSTM+CRF中文命名实体识别实战与避坑指南
简介一套面向中文命名实体识别NER的完整项目源码基于BERTBILSTMCRF混合模型实现同时包含IDCNN、注意力机制等对比方案适合计算机相关专业学生用于毕业设计、课程设计、大作业或企业实战演练。资源压缩包共58个文件主要包含16个Python源码、19个pyc编译文件、9个txt说明文档、5张网络结构图、4份Markdown笔记以及少量配置文件整体约13.75MB目录按数据预处理、模型定义、训练入口、日志展示等模块清晰划分便于快速定位与二次开发。数据侧提供人民日报、MSRA等公开语料的预处理脚本可将原始文本转换为BERT标准输入格式并配备中文预训练模型chinese_L-12_H-768_A-12训练流程完整可复现。项目说明中详细介绍了模型原理、参数设置、训练步骤及效果评估方法可直接运行体验也可替换自有数据开展实验。目前已有1209人学习下载对希望系统掌握序列标注模型、快速搭建中文NER实验环境的读者具有较高借鉴价值。1. 拿到这份“BERTBILSTMCRF中文命名实体识别”源码包先别急着跑训练很多人刚下载这个zip第一反应是直接解压、装依赖、跑train.py然后盯着终端里的loss发呆。我见过太多人卡在模型跑起来但预测出全是“O”标签或者一改batch_size就显存爆炸。这个包解决的是中文序列标注里的一个核心任务从一段中文文本里自动抽出人名、地名、机构名等实体而它选用的模型结构是BERT做动态词向量、BiLSTM抓上下文、CRF做标签约束——这套组合在中文NER任务里几乎是“标准答案”。适合写过分类模型、但对序列标注和预训练模型接入还不熟的人也适合想快速在上线前验证BERT在自有数据上能提几个点的人。跟着这篇文章你能把原理、代码、参数和坑一次理清。2. 为什么是BERTBiLSTMCRF三个组件各守一道关在动手跑代码之前先花几分钟把这三层结构为什么叠在一起想清楚。单独一个BERT就能输出每个字的向量表示但BERT本身不擅长处理“标签之间的依赖关系”单独一个BiLSTM能利用上下文但它的输出是独立的字级概率没法保证“B-Person后面必须跟I-Person”这类规则单独一个CRF又缺乏语义特征。所以这三者是一个典型的“特征抽取器序列解码器”搭配。2.1 BERT把“一字多义”变成真正的动态向量中文里同一个字在不同语境里含义完全不同。“长”在“长度”和“成长”里应该有不同的向量表示。传统Word2Vec训练出来的词向量是静态的不管上下文是什么同一个词永远只有一个向量这对实体识别是硬伤——因为“苹果”可以是水果也可以是公司。BERT通过Transformer的多层自注意力机制让每一个字的向量都带着整个句子的上下文信息所以叫动态词向量。在代码实现里你一般会加载一个预训练的BERT中文模型比如huggingface的bert-base-chinese。这一步常见的做法是from transformers import BertModel, BertTokenizer tokenizer BertTokenizer.from_pretrained(bert-base-chinese) bert_model BertModel.from_pretrained(bert-base-chinese)这里的bert-base-chinese是12层、768维、约1.1亿参数的中文预训练模型。它按字切分不依赖分词器正好和中文NER的“按字标注”策略对齐。注意如果你用的是bert-base-multilingual-cased虽然也支持中文但它的词表是按多语言合并的在纯中文任务上通常比专用中文模型差一点。实际项目里我首选bert-base-chinese显存允许的话可以换huggingface上的chinese-roberta-wwm-ext后者用全词掩码预训练对中文实体边界更友好。2.2 BiLSTM从句子里抓“前看后看”的序列特征BERT已经输出了每个字的向量为什么还要再接一层BiLSTM两个原因。一是BERT的输出是字级别的上下文表示但实体识别需要更聚焦于“局部模式”比如“张三”这个人名BERT向量经过了全句信息融合反而可能被句中无关信息干扰BiLSTM对这种局部顺序模式更敏感。二是BERT的Transformer结构一次看全句而BiLSTM是真正地按时间步单向传播能捕捉到实体内部字与字的递进关系两者互补。BiLSTM的forward部分很直接import torch.nn as nn class BiLSTMDecoder(nn.Module): def __init__(self, input_size, hidden_size, num_labels): super().__init__() self.lstm nn.LSTM( input_size, hidden_size, bidirectionalTrue, batch_firstTrue ) self.dropout nn.Dropout(0.5) self.classifier nn.Linear(hidden_size * 2, num_labels) def forward(self, bert_outputs): lstm_out, _ self.lstm(bert_outputs) lstm_out self.dropout(lstm_out) logits self.classifier(lstm_out) return logits这里hidden_size通常取128或256num_labels是你标注体系里标签的数量比如BIO模式下是3个标签B、I、O还是更多类别。一个容易忽略的参数是batch_firstTrue这决定了输入张量是(batch, seq_len, hidden)而不是(seq_len, batch, hidden)。PyTorch默认是False如果你在组装batch时没注意维度的先后训练会直接报错或者loss越跑越不对劲。2.3 CRF让标签序列不说“不合法”的话BERT和BiLSTM输出的每个字对应各个标签的分数但这还不够。比如在BIO标注体系里“B-Person”后面跟了一个“O”是合法的但“B-Person”后面直接跟“I-Organization”就不合法——同一个实体内部的标签类型必须一致。CRF层就是干这个的它学习一个“标签转移矩阵”在解码时用维特比算法找到整条句子最可能的标签序列而不是逐字取最大概率。在PyTorch生态里最常用的是torchcrf库from torchcrf import CRF crf CRF(num_tagsnum_labels, batch_firstTrue)训练时你要把BiLSTM输出的logits和真实标签一起传给CRF它会返回负的对数似然损失推理时调用crf.decode(logits)就能拿到全局最优的标签序列。这个“全局最优”是CRF的灵魂也是它比纯Softmax多出来的那部分能力。2.4 三者串起来的整体结构把上面三层拼起来前向传播就是句子输入BERT得到每个字768维的向量序列接一个线性层降维常见降到256维进BiLSTM输出的双向隐层拼起来变成hidden_size * 2的向量再过一个线性层映射到num_labels个标签的得分最后丢给CRF解码。梯度会从CRF反向传播到整个网络所以BERT也会被微调。工程上微调BERT会让实体识别F1值在大多数数据集上提升3到5个百分点代价是显存和训练时间翻倍。如果你的数据量很少比如几千条可以选择冻结BERT参数只训练下半部分否则很容易过拟合。3. 复现环境的“最小可跑”清单从Python安装到数据格式拿到源码包第一步不是看模型代码而是先让你的电脑能跑起来。很多人在这个环节翻车是因为环境变量没配好导致装了Python却找不到命令。这里把常见做法写清楚照做就行。3.1 先把Python和依赖装干净这个项目需要Python 3.8以上版本。装完之后打开终端依次确认三件事python --version pip --version nvidia-smi如果python命令找不到多半是Windows下安装时没勾选“Add Python to PATH”。不用重新装直接进系统环境变量把Python的安装目录和Scripts子目录加到Path里再开一个新终端就生效了。依赖安装我通常会用一个requirements.txtpip install torch pip install transformers pip install torchcrf pip install tqdm scikit-learn numpy这里有几个容易踩的坑torch和torchcrf的版本要匹配纯CPU版也能跑但训练速度会慢到让你怀疑人生transformers版本太新可能会导致某些参数名变了常见做法是装4.x版本比如pip install transformers5。安装完跑一句import torch, transformers, torchcrf print(torch.__version__, transformers.__version__, torchcrf.__version__)能正常打印版本号环境就打通了。3.2 中文NER的标准标注格式BIO/BIOES这个项目的训练数据一般用BIO或者BIOES标注。BIO是三个标签B表示实体开头I表示实体内部O表示非实体。BIOES更细一点多了E表示实体结尾S表示单个字成实体。BIOES对小实体更友好但标签更多模型复杂度略高。数据文件常见格式是每一行一个字和一个标签用制表符分隔空行表示句子结束张 B-Person 三 I-Person 是 O 北 B-Organization 京 I-Organization 大 I-Organization 学 I-Organization 的 O 学 O 生 O这里的标签是B-Person、I-Person、B-Organization等每个实体类型都要有自己的B和I。也有数据集用JSON组织但最通用的是这种逐行格式因为它是BIO标注工具默认导出格式也是Huggingface的conll2003格式变种。3.3 这个压缩包里通常有什么文件清单根据标题推断这个zip里应该包含源码、项目说明、模型权重和标注数据。常见结构是文件/目录作用train.py训练入口model.py定义BERTBiLSTMCRF结构data_process.py读取原始标注并转换IDpredict.py加载模型做推理data/训练集、验证集、测试集model/训练好的BERT权重README.md项目说明如果你打开压缩包发现没有requirements.txt就按上面3.1节自己建一个。没有model/目录说明权重需要自己训练生成。别急着找别人要现成模型先用自己的数据跑通流程比什么都有用。4. 训练主流程源码里最核心的4段代码这一章是整个包的核心。通常源码会拆成数据加载、模型定义、训练循环和预测脚本四个文件但核心逻辑就几段。我按实际运行顺序拆开讲每一段都可以对照你自己的源码看。4.1 数据加载把字符和标签变成模型能吃的IDBERT模型接收的是token id不是原始汉字。所以要先把句子里的每个字映射到BERT词表里对应的id再把标签映射成数字。常见做法是def build_vocab(tag_list): tag2id {tag: idx for idx, tag in enumerate(tag_list)} id2tag {idx: tag for tag, idx in tag2id.items()} return tag2id, id2tag def encode_sentence(sentence, tokenizer, tag2id, max_len): tokens list(sentence) input_ids [] label_ids [] for char in tokens: tid tokenizer.convert_tokens_to_ids(char) input_ids.append(tid) # 截断和padding到max_len input_ids input_ids[:max_len] [0] * (max_len - len(input_ids)) label_ids label_ids[:max_len] [0] * (max_len - len(label_ids)) return input_ids, label_ids这里有个关键点max_len要设置成训练数据里最长句子的长度通常是128或256。如果设太短长句子里的实体会被截掉设太长显存开销白白增加。label_ids里的padding标签不能是0因为0在BIO里通常是O如果padding用0模型会学着把无效位置都预测成O。正确做法是给padding单独分配一个标签ID比如把标签ID从1开始或者用-100作为mask让loss计算跳过这些位置。后面第5章会详细讲这个坑。4.2 模型定义BERT底座BiLSTMCRF把前面2.4节的结构写成一个nn.Moduleclass BertBilstmCrfModel(nn.Module): def __init__(self, num_labels, pretrained_pathbert-base-chinese): super().__init__() self.bert BertModel.from_pretrained(pretrained_path) self.lstm nn.LSTM(768, 256, bidirectionalTrue, batch_firstTrue) self.dropout nn.Dropout(0.5) self.fc nn.Linear(256 * 2, num_labels) self.crf CRF(num_tagsnum_labels, batch_firstTrue) def forward(self, input_ids, attention_mask, labelsNone): bert_out self.bert(input_idsinput_ids, attention_maskattention_mask).last_hidden_state lstm_out, _ self.lstm(bert_out) lstm_out self.dropout(lstm_out) logits self.fc(lstm_out) if labels is not None: # 把attention_mask转成布尔mask让CRF跳过padding位置 mask attention_mask.bool() loss -self.crf(logits, labels, maskmask, reductionmean) return loss else: prediction self.crf.decode(logits, maskattention_mask.bool()) return prediction这里的last_hidden_state是BERT输出的所有token向量形状是(batch, seq_len, 768)。BiLSTM的输入维度必须是768和BERT保持一致。如果显存有限可以把BertModel换成bert-base-chinese的蒸馏版本比如distilbert-base-chinese输入维度变成768不变但层数少了速度能快一倍精度掉得不多。4.3 训练循环loss计算和梯度更新训练循环不复杂但有几个细节决定能不能收敛for epoch in range(epochs): model.train() total_loss 0.0 for batch in dataloader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[labels].to(device) optimizer.zero_grad() loss model(input_ids, attention_mask, labels) loss.backward() optimizer.step() total_loss loss.item()loss由CRF层返回是负对数似然。这里注意attention_mask必须传给CRF否则CRF会把padding位置当成普通标签参与转移计算导致label bias。另外BERT部分的学习率应该比BiLSTM小一个数量级常见做法是设置两组参数optimizer torch.optim.AdamW([ {params: model.bert.parameters(), lr: 2e-5}, {params: model.lstm.parameters(), lr: 1e-3}, {params: model.fc.parameters(), lr: 1e-3}, {params: model.crf.parameters(), lr: 1e-3}, ])这是BERT微调的通用配比BERT用2e-5下游层用1e-3。如果只跑10个epoch以内这个配比基本稳定。如果数据量大可以把BERT的学习率调到5e-5但要盯着验证集F1值防止过拟合。4.4 参数表learning_rate、batch_size、max_len怎么调训练时你会看到源码里有一堆超参数我把最重要的几个列出来方便照着调参数常见值调参方向max_len128大于训练数据中90%句子的长度即可batch_size8显存12G显存不足先减半不要直接改max_lenlearning_rate(BERT)2e-5微调时最好不要超过5e-5否则特征崩溃learning_rate(下游)1e-3过拟合就降到5e-4epochs10-30看验证集F1早停更可靠lstm_hidden_size256加大到512能学更多但训练时间变长还有两个你可能会遇到的困惑为什么batch_size不能设成32因为BERT加BiLSTM的显存占用比普通分类模型大很多12G显存下batch_size8已经算激进。为什么epochs设30还不够因为BERT微调在少量数据上很容易过拟合验证集F1会先升高后突然下降与其盲目加epoch不如加一个“如果连续3个epoch验证集F1没提升就停止”的早停逻辑。5. 避坑记中文NER最常见的5个翻车现场这部分是血泪经验汇总。每个坑我都详细拆成“现象→原因→解决”方便你对号入座。5.1 标签错位训练loss很低但预测全乱现象训练时loss降到零点几但拿一条新句子预测所有标签输出都是O或者全是乱序标签。原因数据加载环节标签和输入没对齐。最常见的是BERT的tokenizer对某些中文标点做了特殊处理比如全角空格被拆掉导致输入序列长度和标签序列长度不一致。还有一种是padding标签用了0CRF把大量padding位置当成真实标签来学习模型被带偏。解决在encode_sentence里加断言确保每个字符对应一个标签。使用attention_mask代替手动padding标签CRF计算时跳过mask为False的位置。推荐做法是在数据处理好后用一条测试样本打印len(input_ids)len(label_ids)确认后再进模型。5.2 GPU显存不够batch_size一调大就OOM现象batch_size从8改成16直接报CUDA out of memory。原因BERT的中间激活值占显存极大序列长度和batch_size乘积一旦超限就爆。另外很多人的代码里没有释放中间变量导致显存碎片化。解决先调小max_len比如从256降到128显存占用会立竿见影地下降。如果还不够用梯度累积模拟大batchaccumulation_steps 2 for i, batch in enumerate(dataloader): loss model(...) loss loss / accumulation_steps loss.backward() if (i 1) % accumulation_steps 0: optimizer.step() optimizer.zero_grad()这相当于用2个小batch合一个大batch。另外检查PyTorch的torch.cuda.empty_cache()是不是没在每个epoch后调用偶尔释放一下也能缓解碎片问题。5.3 BERT加载慢得离谱不是网速问题现象第一次执行BertModel.from_pretrained(bert-base-chinese)等了半小时还没下载完于是怀疑笔记本网络有问题。原因这是正常的预训练权重文件约400MB从Huggingface下载在国内网络环境下确实慢。但如果你已经下载过第二次加载还慢那就是缓存路径问题。解决先把模型下载到本地目录再改加载路径# 用huggingface-cli下载 huggingface-cli download bert-base-chinese --local-dir ./bert_base_chinese然后代码里改成model BertModel.from_pretrained(./bert_base_chinese)这样完全离线加载秒开。注意不要删掉config.json和vocab.txt他们和权重文件是配套的。5.4 CRF损失出现NaN手工实现和库版本冲突现象训练到第2个epochloss突然变成nan。原因可能是transformers新版和torchcrf的mask参数类型不兼容。torchcrf的mask需要布尔张量但你从attention_mask拿过来的是浮点张量[1,0]CRF内部在做布尔运算时出错梯度爆炸。解决在传mask前强制转换mask attention_mask.bool() loss -self.crf(logits, labels, maskmask, reductionmean)如果问题仍在检查学习率是不是太高。BERT微调时如果学习率超过1e-4很容易让CRF的转移分数发散。把BERT学习率降到2e-5同时给CLIP加一个梯度裁剪torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm5.0)5.5 中文按字切还是按词切结果差距很大现象用同样的代码同事把句子先分词再送BERT你的代码按字切两个人的F1差了好几个点。原因BERT的中文预训练模型本质是按字切分的词表里没有“北京大学”这种词只有“北”、“京”、“大”、“学”这些字。如果你强行分词再映射每个词被拆成多个token标签序列长度对不齐CRF学到的边界约束全乱了。解决直接按字切分。BertTokenizer会自动处理中文你只需要把原始字符串list(sentence)成字符列表。如果一定要用词级别的标注数据那就得用BERT配套的切词器把词转成子词并做标签的“有损对齐”——这是另一个复杂的工程新手期不建议碰。这个包既然叫中文命名实体识别默认就是按字级做。6. 让模型正式上岗推理脚本与性能验证技巧训练完的模型要能对新句子预测。这里的核心是不要重新走一遍训练时的forward而是加载已保存的权重在推理模式下输出。def predict(model, tokenizer, sentence, max_len128): model.eval() input_ids tokenizer.encode(sentence, max_lengthmax_len, truncationTrue, return_tensorspt).to(device) attention_mask (input_ids ! 0).long().to(device) with torch.no_grad(): pred_ids model(input_ids, attention_mask) # 返回decode后的标签id列表 id2tag ... # 从训练时保存的id2tag映射加载 tags [id2tag[i] for i in pred_ids[0]] entities [] current_entity None for char, tag in zip(sentence, tags): if tag.startswith(B-): if current_entity: entities.append(current_entity) current_entity [char, tag[2:]] elif tag.startswith(I-) and current_entity and current_entity[1] tag[2:]: current_entity[0] char else: if current_entity: entities.append(current_entity) current_entity None if current_entity: entities.append(current_entity) return entities这里注意model(input_ids, attention_mask)在推理模式下返回的是CRF解码出的标签ID序列不是概率分布所以不要再做argmax。decode用的维特比算法已经帮你找到了全局最优路径这是CRF相比softmax的优势。关于验证我给你三个实际验证技巧。第一不要只跑一遍测试集就下结论用5折交叉验证来看F1的均值和方差方差小才说明模型稳定。第二把预测错例打印出来按实体类型分类统计你会发现人名错误多半是生僻字地名错误多半是“北京”和“北京大学”的边界切分问题针对性修复标注比调参有用得多。第三如果线上实体有优先级比如识别出的多个实体互相重叠可以给每个实体类型设一个置信度阈值低于阈值就丢弃。这个包本身不带阈值机制你可以给CRF的Decode加一个nbest参数拿到候选序列后取top1和top2的分数差作为置信度。我自己做中文NER的习惯是先把模型训练到验证集F1不再变化然后冻结上半部分单独用标注数据微调CRF层通常能再涨一点。这招听起来玄学但确实在不少数据集上有效。希望你也能从这份源码里把该拿的拿稳别在标签错位和显存上耗掉太多时间。希望帮到你。本文还有配套的精品资源点击获取