尧图网页设计 
简介命名实体识别NER是自然语言处理与信息抽取中的基础任务目标是从非结构化文本中定位人名、地名、机构名等实体广泛应用于知识图谱构建、文本结构化及专业领域检索。凭借预训练语言模型BERT能将中文汉字编码为富含上下文语义的向量BiLSTM通过双向聚合进一步捕捉相邻字间的局部顺序模式CRF则在解码时引入标签转移约束避免非法序列的出现。三者各司其职、互为补足在医疗、法律、金融等专业领域的中文NER任务中能够显著提升识别精度与F1值。围绕这一经典组合从数据标注格式、环境依赖、模型定义到学习率调节、显存优化与常见踩坑点均有系统梳理适合正在实践信息抽取与序列标注的工程师参考。1. 中文命名实体识别为什么要选BERTBILSTMCRF先看懂这个组合在解决什么问题做中文命名实体识别NER的人迟早会遇到一个“老三样”组合BERT做编码BiLSTM做上下文聚合CRF做标签约束。这个组合在工业界和学术界的复现率极高尤其是处理医疗、法律、金融这类专业领域文本时直接拿通用BERT微调的效果往往不如加上BiLSTM和CRF。原因不复杂BERT擅长把字映射成富含语义的向量但对“标签之间的合法转移”没有概念BiLSTM能把句子两边的信息揉进当前字但输出的是独立概率CRF则负责在解码时强制“B-Person后面必须跟I-Person或O”这类规则。三者各管一段正好补上彼此的短板。这个标题里的zip包本质上就是一套可以直接落地的NER训练工程里面通常包含预处理脚本、模型定义、训练逻辑、评估代码外加训练好的权重和标注好的中文数据。对于正在做信息抽取、知识图谱构建或文本结构化的人来说这套东西的价值不只是“能跑”而是能作为基座替换自己的数据集和标签体系。下面我会把这条链路拆开讲从环境搭建讲到参数调整再讲到那些最容易让你半夜对着屏幕怀疑人生的边界坑。如果你已经在用纯BERT做序列标注这篇文章能帮你理解为什么加一层BiLSTM和CRF会让F1值明显上涨如果你刚接触NER照着操作也能在半天内把第一个模型训出来。2. 把项目跑起来环境准备、数据格式与最小可运行命令2.1 环境依赖Python版本、torch与transformers的搭配建议这几年我反复装BERT相关环境最省心的组合是Python 3.8或3.10搭配PyTorch 1.10以上的版本transformers库用4.x系列。Python 3.11以下对老代码的兼容性更好因为很多BERT源码里用了torch.nn.utils.rnn.pack_padded_sequence这类API不同版本行为有差异。如果你下载的zip里带了requirements.txt先别急着全装我一般只装核心项pip install torch1.13.1 --index-url https://download.pytorch.org/whl/cu117 pip install transformers4.26.1 pip install numpy1.24.3 pip install tqdm scikit-learn说明这里固定PyTorch版本是为了避免新版把LSTM的默认batch_first行为改掉也避免transformers自动下载比我预期更新的tokenizer。sklearn只用来算f1_score和classification_report如果工程里自己写了评估函数装不装都行。装完后在Python里执行import torch; print(torch.__version__)确认能识别GPU再from transformers import BertTokenizer确认transformers没有报缺失依赖。很多“项目跑不起来”的根源不是代码错了而是transformers和torch的版本错配比如老代码用from transformers import BertModel新版本返回的BaseModelOutput结构变了取值方式就要跟着改。2.2 数据格式BIO标注与中文数据集的组织方式中文NER最通用的标注格式是BIOB表示实体开始I表示实体中间或结尾O表示非实体。每个字一行句子之间用空行隔开。以人名识别为例数据长这样张 B-PER 三 I-PER 在 O 北 B-LOC 京 I-LOC 出 O 差 O 李 O 四 O 在 O 上 O 海 B-LOC 工 O 作 O这套格式几乎所有NER代码都认你的zip包里大概率也有一个类似data/train.txt的文件。读取时注意两点第一必须按字切分不能按词切分因为BERT的中文tokenizer本身就是字级别的你按词切反会让预训练模型的词向量优势失效第二空行是句子边界不要丢掉训练序列长度是按句子截断的丢掉空行后一个超长段落会被硬塞进模型导致截断时实体标签被切碎。如果你的数据是JSON或CSV格式比如{text: 张三在北京出差, entities: [{type: PER, start: 0, end: 2}]}需要先转成上面的BIO格式。这个转换脚本虽然简单但是坑很多后面避坑章节我会专门说标签错位的问题。2.3 最小训练命令与参数说明假设zip包里已经整理好了train.txt、dev.txt、test.txt和main.py那么最小启动命令通常是python main.py --do_train --data_dir ./data --bert_model bert-base-chinese --num_epochs 5 --batch_size 16 --learning_rate 5e-5 --max_seq_len 128 --gpu_id 0这段命令里有几个参数是新手最容易忽略的。--bert_model指定的是HuggingFace上的模型名第一次运行会从网络下载约400MB的权重如果网络受限需要提前用hf-mirror或离线方式把模型放到本地目录然后把参数改成--bert_model ./bert-base-chinese。--max_seq_len决定每个句子被截断或填充到的长度128对大多数中文句子够用如果你处理的是法律文书或病历这类长句建议拉到256但显存占用会接近翻倍。--learning_rate我用的是5e-5这个值是BERT微调的标准起点但如果你发现loss震荡降到2e-5到3e-5会更稳。--num_epochs不要拍脑袋设成100BERT微调普遍3到10轮就够了设太大容易把下游BiLSTM和CRF训得过度自信验证集F1反而掉下去。跑起来之后你会看到每个epoch结束输出类似precision0.85, recall0.82, f10.83的日志。如果第一轮就出现F1接近0先别怀疑模型优先检查数据标签是不是全O或者label2id映射是不是写错了。如果loss一直是nan十有八九是CRF层里涉及mask的logsumexp计算出现了分母为0这个我们放到避坑章节细说。3. 三个核心模块逐个拆解BERT编码、BiLSTM上下文、CRF解码3.1 BERT层为什么用预训练权重而不是随机初始化在这个组合里BERT的作用是把每个字编码成768维的向量。中文BERT用的是字级别的tokenizer所以输入张三在北京实际上会被拆成[[CLS], 张, 三, 在, 北, 京, [SEP]]每个字对应一个embedding向量。关键点在于这个embedding不是随机初始化的它是在海量中文语料上预训练出来的已经包含了字的上下文语义。你直接拿随机初始化的BERT去训练相当于用一台没学过中文的机器去理解句子效果会比预训练模型低10到20个百分点的F1而且需要更多数据才能拟合。这里有一个常被忽略的细节BERT的输出应该取last_hidden_state而不是pooler_output。last_hidden_state的形状是[batch_size, seq_len, hidden_size]它保留了每个位置的向量正好喂给下一层BiLSTM。pooler_output是BERT内部经过一个全连接和tanh的句子级向量只适合做文本分类做序列标注用它等于把每个字的信息全丢了。源码里常见写法是encoded bert_model(input_ids, attention_maskmask)[0] # 取last_hidden_state注意后面的[0]如果你写[1]就会拿到pooler_output模型训起来怎么都不涨。另外BERT输出要不要进行梯度回传我一般默认回传也就是微调BERT参数。如果你的数据集很大超过10万句微调能让BERT适应你的领域词汇如果数据集很小几千句冻结BERT只训练下游层反而更稳不然容易过拟合。实践中可以两种都试一下看验证集F1再决定。3.2 BiLSTM层双向语义的取舍与dropout设置BiLSTM接在BERT后面输入是每个字的768维向量输出是2倍hidden_size因为正向和反向各一个。这一层存在的意义是把整句的上下文信息进一步融合——虽然BERT内部已经有多层注意力但注意力更擅长捕捉全局关系对“相邻字之间的局部顺序敏感度”不如循环网络。比如在人名识别中“张”后面紧跟着“三”是一个强模式BiLSTM对这种局部顺序模式的编码比BERT更直接。hidden_size我常用的是128或256。128对中文NER已经够用再大了容易过拟合且增加显存和推理延迟。一个关键参数是num_layers不要盲目加到2层以上。两层BiLSTM的参数量很大而且在这个组合里BERT已经提过特征一层BiLSTM通常就够。如果你想调深建议同时把dropout提高到0.5以上否则验证集很快出现震荡。代码里的定义一般是self.bilstm nn.LSTM( input_size768, hidden_size128, num_layers1, batch_firstTrue, bidirectionalTrue, ) self.dropout nn.Dropout(p0.5) lstm_out, _ self.bilstm(encoded) # encoded: [batch, seq, 768] lstm_out self.dropout(lstm_out)这里batch_firstTrue和前面BERT输出的维度对齐省去转置的麻烦。nn.Dropout放在BiLSTM之后、CRF之前而不是放在BiLSTM内部——因为BiLSTM内部自带dropout参数但它只作用于层与层之间num_layers1时内部dropout根本不生效必须自己加一层Dropout。3.3 CRF层标签约束与转移矩阵的作用CRF层是整个模型的决策层。前面BERT和BiLSTM输出的每一个位置的logits都是独立判断这个字属于哪个标签的概率但独立判断会违反一些常识。比如在BIO标注里B-PER后面直接跟B-LOC就不合法一个实体不可能在“张三”之后立刻跳到“北京”而不经过I-PER或O。CRF会学习一个tag_size x tag_size的转移矩阵矩阵里的值表示从某一个标签跳到另一个标签的得分这个矩阵在训练过程中自动更新学到的正是你数据里实体的起始、延续和结束模式。核心逻辑在解码时体现我们用维特比算法在全体合法标签序列中找得分最高的一条路径而不是对每个位置取argmax。训练时则计算所有路径的log-sum-exp用它作为规范化项让正确路径的得分与所有路径得分总和的距离尽量小。这一来一回模型学到的就不只是“这个字像PER”还包括“PER后面不能直接跟LOC”这类序列约束。代码实现有不少现成库常用的有torchcrf和pytorch-crf。我一般自己实现一个轻量CRF类因为现成库有时对mask的处理有bugclass CRF(nn.Module): def __init__(self, num_tags): super().__init__() self.num_tags num_tags self.trans nn.Parameter(torch.randn(num_tags, num_tags)) def forward(self, emissions, mask): # emissions: [batch, seq, num_tags] # mask: [batch, seq], 1表示有效位 return self._score(emissions, mask) - self._normalizer(emissions, mask) def decode(self, emissions, mask): return self._viterbi(emissions, mask)注意trans矩阵初始化为随机值即可不要用全0初始化否则训练初期梯度可能消失。mask必须用attention_mask一样的值把padding位设成0这样CRF在计算转移和归一化时会把padding位置的标签忽略掉。我遇到过一个隐蔽bugattention_mask是[batch, seq]但CRF里用的mask忘了乘seq_len导致padding部分的loss总是计入验证集上表现正常但测试集一塌糊涂。这类问题只有靠对比两个mask的张量形状才能发现。4. 训练参数怎么调学习率、batch size、序列长度的血泪经验4.1 学习率BERT层与下游层的差异化设置BERTBILSTMCRF这个模型里BERT参数占比最大但下游层的参数是从零开始学的。两者对学习率的要求完全不同BERT已经在海量语料上收敛过微调时学习率过大会把预训练的知识“洗掉”而过小则学不动新数据里的领域特征。我一般的做法是给BERT一个较小的学习率比如2e-5到5e-5给BiLSTM和CRF一个较大的学习率比如1e-3到2e-3。在PyTorch里可以用GroupedOptimizer实现bert_params list(map(id, model.bert.parameters())) other_params filter(lambda p: id(p) not in bert_params, model.parameters()) optimizer torch.optim.AdamW([ {params: model.bert.parameters(), lr: 2e-5}, {params: other_params, lr: 1e-3}, ])这样设置之后你会发现loss下降速度比单一lr快很多而且验证集F1的峰值更高。如果你用的是HuggingFace的Trainer可以在TrainingArguments里设learning_rate5e-5再通过参数分组的方式覆盖BERT层但麻烦一点。我习惯直接手写训练循环因为NER的评估和掩码处理在Trainer里反而不灵活。还有一个容易踩的坑使用AdamW时权重衰减默认是0.01但BERT层的weight_decay应该设成0.01而bias和LayerNorm的weight_decay应该设成0否则训练不稳定。获取参数时要用param.requires_grad过滤掉冻结层我在冻结BERT时经常忘记这个导致梯度传到冻结层上模型表现时好时坏。4.2 batch size与梯度累积显存不够时的替代方案BERT系列的显存占用大头在Self-Attentionbatch size一大就容易OOM。我的经验是在12GB显存的显卡上max_seq_len128时batch size最多到16如果max_seq_len256batch size降到8才安全。如果你只有8GB显存batch size设为4或2也不是不行但训练会慢很多。不要为了让batch size变大而直接减小输入维度或隐藏层维度那样损失的信息可能比获益更大。更优雅的替代方案是梯度累积。用accumulation_steps把多个小batch的梯度累加后再更新一次参数效果近似于大batchfor step, batch in enumerate(train_loader): loss model(batch) loss loss / accumulation_steps # 平均梯度 loss.backward() if (step 1) % accumulation_steps 0: optimizer.step() scheduler.step() optimizer.zero_grad()这里accumulation_steps4配上batch_size4等效于batch_size16但显存只占4条样本的量。注意loss要除以accumulation_steps不然等效batch下学习率偏大训练会不稳。如果你用的是多卡还要注意每个卡的loss已经平均过了梯度累积时不要再额外乘卡数。另外CRF层的loss是所有路径的总和对batch size很敏感。我遇到过一个现象batch size从4增加到8验证集F1反而掉了1到2个点。这是因为CRF的归一化项里涉及所有可能的标签序列batch size变大后模型看到更多噪声样本转移矩阵被拉偏。所以NER场景下batch size不是越大越好我一般固定16再通过梯度累积解决显存问题。4.3 序列长度与填充策略中文分字与padding的坑中文NER里序列长度直接决定了你能容纳多少上下文。短句子截断到128没问题但医疗文书经常有一整段几百字的病史描述里面实体分布很密截断会把后半段的实体全部扔掉。我处理这种情况的常见做法是分句而不是粗暴截断。按句号和分号把长文本切成多个短句每个短句单独过模型然后拼接结果。这样既保留了完整语义又不超过max_seq_len。如果你非要用长序列记得调整BERT的位置编码。bert-base-chinese支持的最大位置是512所以max_seq_len最多设为512。设为512时不仅显存爆涨而且推理时间接近线性的2倍以上。我一般建议128作为默认256用于专业领域512只在你确信数据里有极长且不可切分的实体时才用。Padding的坑更隐蔽。模型在计算loss时必须忽略padding位置的预测。如果忘记传attention_mask给BERTpadding位也被当作真实字参与注意力计算模型会把[PAD]当普通字学出荒谬的模式。CRF层的mask和BERT的attention_mask必须完全一致而且这两个mask要放在同一个设备上。我经常因为mask.cuda()和input_ids.cuda()顺序不一致导致类型不匹配报错或者更恶心的mask没有cast成torch.long在CRF里索引时报IndexError。这些小问题排查起来很费时间建议在数据加载器里就把mask统一处理好。下面是一段典型的批处理逻辑我把padding和mask的生成写在一起尽量避免后面踩坑def collate_fn(batch): texts, labels, max_len [], [], 0 for token_list, label_list in batch: texts.append(token_list) labels.append(label_list) max_len max(max_len, len(token_list)) input_ids [] attention_masks [] label_ids [] for text, label in zip(texts, labels): # 这里用的是BERT tokenizer中文是字级所以可以直接编码 encoding tokenizer(text, paddingmax_length, truncationTrue, max_lengthmax_len, return_tensorspt) input_ids.append(encoding[input_ids][0]) attention_masks.append(encoding[attention_mask][0]) # 标签对齐把O填充到max_len多出来的截掉 padded_label label [label2id[O]] * (max_len - len(label)) label_ids.append(padded_label[:max_len]) return torch.stack(input_ids), torch.stack(attention_masks), torch.tensor(label_ids)注意标签对齐时padded_label用的是label2id[O]不是0。如果O的id不是0填充值用错了会导致所有padding位的预测都算成某个实体类别评估时F1直接崩盘。最好先打印label2id确认一下。5. 避坑指南BERTBILSTMCRF落地最常见的5个翻车点5.1 现象loss很低但验证F1一直为0这个现象很典型训练loss从5降到0.2但验证集上模型预测全是O一个实体都识别不出来。根源多数是标签和输入错位。中文BERT的字级tokenizer虽然基本是一字一token但遇到特殊符号如“·”或全角空格时会拆成多个token导致标签长度和输入长度对不上。比如“赵·丽颖”这种名字tokenizer可能把“·”当成一个token但你的数据里“赵”、“·”、“丽”、“颖”各占一个位置长度一致但如果中间混入了一个空格长度就不一致了模型自然学不到实体。解决方法是做标签对齐时用tokenizer的offset_mapping逐个映射。简单粗暴的办法是预处理数据时去掉所有空格和特殊符号只保留中英文数字和常见标点。另外如果max_seq_len小于句子长度截断时要把尾部的实体标签一起扔掉否则标签错位会让loss收敛不了。我习惯在数据加载后打印一条“最长标签长度”和“最长输入长度”如果两者不相等说明预处理有bug。另外一个不罕见的原因是label2id里O的id设置成了0但在CRF解码时转移矩阵里O到O的得分初始值太大导致维特比路径全部偏向O。我碰过这种把O的id设为0又在CRF初始化时把trans矩阵前几行设成全0结果模型训练到后期解码时发现所有路径中“全部O”路径得分居然最高于是永远输出全O。解决办法是不要把O的id固定在0可以让O排在后面或者手动打印一个batch的预测分布看看。5.2 现象预训练模型下载失败或路径错误很多人在跑BERT时卡在下载权重上。第一次运行BertModel.from_pretrained(bert-base-chinese)会从HuggingFace下载约400MB的文件如果网络环境不畅会报ConnectionError或OSError。这个下载过程没有进度条容易让人觉得程序死了。解决手法有三种一是用国内镜像站设置环境变量HF_ENDPOINThttps://hf-mirror.com后再运行二是在有网络的地方手动下载config.json、pytorch_model.bin、vocab.txt到本地目录再用from_pretrained(./path)加载三是直接用别人打包好的模型文件但要注意文件名必须匹配不能把tf_model.h5和pytorch_model.bin搞混。还有一类路径错误是项目里写死了相对路径./pretrained/bert-base-chinese但你解压zip后目录结构变了。我建议第一步先tree或ls -R看一下解压出来的完整目录找到模型权重实际在哪再修改代码里的路径。不要用os.path.exists去猜打印一下绝对路径最踏实。5.3 现象CRF相关loss出现NaN或者解码时报索引越界这类问题多半出在mask的dtype和设备上。CRF里计算转移得分时要用mask把padding位置剔除如果mask是torch.float而后续操作把它当成torch.long来索引就会报RuntimeError。解决方法是统一mask的类型并确保它和input_ids在同一个设备attention_mask attention_mask.long()另一个NaN源头是torch.logsumexp在路径长度太短时出现数值不稳定。如果max_seq_len设为1CRF的归一化项里只有很少的路径logsumexp可能溢出。实际上BERT中文模型很少用长度为1的序列但我在写测试用例时遇到过所以提醒一句CRF的输入序列长度不能小于2。如果你的实现是自写的CRF还要注意trans矩阵在训练时是否有一个维度是num_tags2因为有些实现会加START和END状态。我常用的pytorch-crf库内部已经管理好这些状态只要传emissions和mask即可。如果自己实现建议先跑一个batch大小为1、序列长度为3的用例打印出score和normalizer的形状确认没有维度错位。5.4 现象评测代码算出的F1和训练日志里的F1对不上训练日志是在每个epoch结束后用验证集算的如果你的评估函数把O标签也当成需要预测的类别那么O占大多数整体F1虚高且没有参考价值。正确做法是在计算F1时排除O标签或者至少用labels参数指定只关心实体类别。另一个常见问题是没有忽略padding位置测试时如果attention_mask是0的位置也计入预测模型在padding上大概率预测为O这会人为拉高准确率因为O太多了。我一般用seqeval库计算实体级别的F1它能自动按BIO合并实体并且忽略以-开头的内部标签pip install seqevalfrom seqeval.metrics import classification_report true_entities [[entity for entity in sent if entity ! O] for sent in true_labels] pred_entities [[entity for entity in sent if entity ! O] for sent in pred_labels] print(classification_report(true_entities, pred_entities))注意classification_report要求标签是字符串比如B-PER所以你需要把id转换回标签名。如果seqeval报ValueError: I-PER requires B-PER说明预测的标签序列里出现了I-PER开头而没有前置B-PER这其实是CRF没学好或者你在解码后没有修正非法序列。遇到这种情况我建议把CRF的维特比输出强制校正一下如果I出现在B之前把I改成B直到整个序列合法为止。5.5 现象验证集F1高测试集F1断崖式下跌这是典型的过拟合信号。BERT微调在少量数据上特别容易过拟合验证集因为你反复用验证集调参验证集的噪声也被模型记进去了。出现这种情况时优先检查训练集和测试集是不是同分布。如果来自不同来源比如训练集是新闻测试集是医疗文本那模型再强也白搭。排除分布问题后再看是不是验证集太小。如果你的dev集只有500句F1方差会很大调参时看到的0.83可能是运气好。解决办法是增加验证集比例或者用交叉验证。还有一招是早停当验证集F1连续2个epoch不再上升时保存当前模型而不是继续训到固定epoch。我自己的血泪经验是BERT微调第1个epoch通常F1很低第2个epoch暴涨第3个epoch好好珍惜第4个epoch开始过拟合。所以不要因为第2个epoch涨得猛就把num_epochs设成10那只是纸面F1好看罢了。后来我习惯在训练过程中每个epoch保存一次模型最后回看哪个epoch的测试集F1最高。6. 让模型跑得更稳的收尾技巧早停、模型保存与bad case分析把模型训练跑通只是第一步真正能拿去上线还得靠这两件事。第一把“保存哪个模型”从拍脑袋变成有依据。我一般不在每个epoch结束时无脑覆盖保存而是在验证集F1创新高时保存一份best_model.bin并同时保存参数配置和标签映射这样即使后面训练跑崩了也有后悔药if best_f1 eval_f1: best_f1 eval_f1 torch.save(model.state_dict(), fbest_model_{eval_f1:.4f}.bin) with open(tag_map.json, w, encodingutf-8) as f: json.dump(label2id, f, ensure_asciiFalse)第二固定随机种子。BERT微调本身有随机性不同种子可能带来1到2个F1的浮动。训练开头设torch.manual_seed(42)、np.random.seed(42)、random.seed(42)如果用了DataLoader的shuffleTrue最好在generator里也指定seed否则实验结果没法复现。再看bad case分析。训完模型后我习惯把测试集里预测错的句子单独抽出来打印成表格表格内容包含原始句子、真实标签、预测标签、模型对每个位置的置信度。这个做法能直接暴露两个常见问题一是实体边界对不齐比如预测北为B-LOC但漏掉京的I-LOC说明CRF的转移矩阵对I标签的延续不够自信二是嵌套实体丢失比如“北京人民医院”里既有ORG又有LOC模型只识别出ORG是因为训练数据里没有嵌套标注。这类分析没法靠调参解决要么改标注规范要么换成阅读理解式NER模型。我在落地时还有一个习惯给模型留一个“阈值修正”接口。CRF解码输出的得分虽然没有概率意义但可以通过比较最优路径和第二优路径的差值来当置信度。在工程里对置信度低于某个阈值的句子不抽取实体宁可漏不可错这样上线后人工复核量会大幅降低。具体实现可以在CRF解码时同时返回路径得分scores, paths crf.decode(emissions, mask) confidence scores - scores_second_best不过这套操作需要你手写CRF的解码函数对多数人来说有点重。建议先不做而是把bad case保存下来和标注团队对齐数据往往改十处标注比调十个参数更见效。结尾从环境搭建到CRF解码这套组合看起来像个黑匣子但把它拆成三块后每块的职责都特别清楚。我自己最早跑通这个工程时也踩过标签错位、mask传错、验证集过拟合这些坑后来慢慢养成了一个习惯每次训练前先打印一条样本的input_ids和label_ids的长度每次评估前先跑一个batch的预测结果和真实标签做对比这样能在几分钟内发现大多数低级失误。如果你也被中文命名实体识别折磨得够呛希望这篇笔记能让你少走一点弯路至少让你下次遇到“loss很低但F1为0”时知道该从哪里下手。希望帮到你。本文还有配套的精品资源点击获取 中文NER为何选BERT+BiLSTM+CRF：原理拆解与工程落地避坑指南
简介命名实体识别NER是自然语言处理与信息抽取中的基础任务目标是从非结构化文本中定位人名、地名、机构名等实体广泛应用于知识图谱构建、文本结构化及专业领域检索。凭借预训练语言模型BERT能将中文汉字编码为富含上下文语义的向量BiLSTM通过双向聚合进一步捕捉相邻字间的局部顺序模式CRF则在解码时引入标签转移约束避免非法序列的出现。三者各司其职、互为补足在医疗、法律、金融等专业领域的中文NER任务中能够显著提升识别精度与F1值。围绕这一经典组合从数据标注格式、环境依赖、模型定义到学习率调节、显存优化与常见踩坑点均有系统梳理适合正在实践信息抽取与序列标注的工程师参考。1. 中文命名实体识别为什么要选BERTBILSTMCRF先看懂这个组合在解决什么问题做中文命名实体识别NER的人迟早会遇到一个“老三样”组合BERT做编码BiLSTM做上下文聚合CRF做标签约束。这个组合在工业界和学术界的复现率极高尤其是处理医疗、法律、金融这类专业领域文本时直接拿通用BERT微调的效果往往不如加上BiLSTM和CRF。原因不复杂BERT擅长把字映射成富含语义的向量但对“标签之间的合法转移”没有概念BiLSTM能把句子两边的信息揉进当前字但输出的是独立概率CRF则负责在解码时强制“B-Person后面必须跟I-Person或O”这类规则。三者各管一段正好补上彼此的短板。这个标题里的zip包本质上就是一套可以直接落地的NER训练工程里面通常包含预处理脚本、模型定义、训练逻辑、评估代码外加训练好的权重和标注好的中文数据。对于正在做信息抽取、知识图谱构建或文本结构化的人来说这套东西的价值不只是“能跑”而是能作为基座替换自己的数据集和标签体系。下面我会把这条链路拆开讲从环境搭建讲到参数调整再讲到那些最容易让你半夜对着屏幕怀疑人生的边界坑。如果你已经在用纯BERT做序列标注这篇文章能帮你理解为什么加一层BiLSTM和CRF会让F1值明显上涨如果你刚接触NER照着操作也能在半天内把第一个模型训出来。2. 把项目跑起来环境准备、数据格式与最小可运行命令2.1 环境依赖Python版本、torch与transformers的搭配建议这几年我反复装BERT相关环境最省心的组合是Python 3.8或3.10搭配PyTorch 1.10以上的版本transformers库用4.x系列。Python 3.11以下对老代码的兼容性更好因为很多BERT源码里用了torch.nn.utils.rnn.pack_padded_sequence这类API不同版本行为有差异。如果你下载的zip里带了requirements.txt先别急着全装我一般只装核心项pip install torch1.13.1 --index-url https://download.pytorch.org/whl/cu117 pip install transformers4.26.1 pip install numpy1.24.3 pip install tqdm scikit-learn说明这里固定PyTorch版本是为了避免新版把LSTM的默认batch_first行为改掉也避免transformers自动下载比我预期更新的tokenizer。sklearn只用来算f1_score和classification_report如果工程里自己写了评估函数装不装都行。装完后在Python里执行import torch; print(torch.__version__)确认能识别GPU再from transformers import BertTokenizer确认transformers没有报缺失依赖。很多“项目跑不起来”的根源不是代码错了而是transformers和torch的版本错配比如老代码用from transformers import BertModel新版本返回的BaseModelOutput结构变了取值方式就要跟着改。2.2 数据格式BIO标注与中文数据集的组织方式中文NER最通用的标注格式是BIOB表示实体开始I表示实体中间或结尾O表示非实体。每个字一行句子之间用空行隔开。以人名识别为例数据长这样张 B-PER 三 I-PER 在 O 北 B-LOC 京 I-LOC 出 O 差 O 李 O 四 O 在 O 上 O 海 B-LOC 工 O 作 O这套格式几乎所有NER代码都认你的zip包里大概率也有一个类似data/train.txt的文件。读取时注意两点第一必须按字切分不能按词切分因为BERT的中文tokenizer本身就是字级别的你按词切反会让预训练模型的词向量优势失效第二空行是句子边界不要丢掉训练序列长度是按句子截断的丢掉空行后一个超长段落会被硬塞进模型导致截断时实体标签被切碎。如果你的数据是JSON或CSV格式比如{text: 张三在北京出差, entities: [{type: PER, start: 0, end: 2}]}需要先转成上面的BIO格式。这个转换脚本虽然简单但是坑很多后面避坑章节我会专门说标签错位的问题。2.3 最小训练命令与参数说明假设zip包里已经整理好了train.txt、dev.txt、test.txt和main.py那么最小启动命令通常是python main.py --do_train --data_dir ./data --bert_model bert-base-chinese --num_epochs 5 --batch_size 16 --learning_rate 5e-5 --max_seq_len 128 --gpu_id 0这段命令里有几个参数是新手最容易忽略的。--bert_model指定的是HuggingFace上的模型名第一次运行会从网络下载约400MB的权重如果网络受限需要提前用hf-mirror或离线方式把模型放到本地目录然后把参数改成--bert_model ./bert-base-chinese。--max_seq_len决定每个句子被截断或填充到的长度128对大多数中文句子够用如果你处理的是法律文书或病历这类长句建议拉到256但显存占用会接近翻倍。--learning_rate我用的是5e-5这个值是BERT微调的标准起点但如果你发现loss震荡降到2e-5到3e-5会更稳。--num_epochs不要拍脑袋设成100BERT微调普遍3到10轮就够了设太大容易把下游BiLSTM和CRF训得过度自信验证集F1反而掉下去。跑起来之后你会看到每个epoch结束输出类似precision0.85, recall0.82, f10.83的日志。如果第一轮就出现F1接近0先别怀疑模型优先检查数据标签是不是全O或者label2id映射是不是写错了。如果loss一直是nan十有八九是CRF层里涉及mask的logsumexp计算出现了分母为0这个我们放到避坑章节细说。3. 三个核心模块逐个拆解BERT编码、BiLSTM上下文、CRF解码3.1 BERT层为什么用预训练权重而不是随机初始化在这个组合里BERT的作用是把每个字编码成768维的向量。中文BERT用的是字级别的tokenizer所以输入张三在北京实际上会被拆成[[CLS], 张, 三, 在, 北, 京, [SEP]]每个字对应一个embedding向量。关键点在于这个embedding不是随机初始化的它是在海量中文语料上预训练出来的已经包含了字的上下文语义。你直接拿随机初始化的BERT去训练相当于用一台没学过中文的机器去理解句子效果会比预训练模型低10到20个百分点的F1而且需要更多数据才能拟合。这里有一个常被忽略的细节BERT的输出应该取last_hidden_state而不是pooler_output。last_hidden_state的形状是[batch_size, seq_len, hidden_size]它保留了每个位置的向量正好喂给下一层BiLSTM。pooler_output是BERT内部经过一个全连接和tanh的句子级向量只适合做文本分类做序列标注用它等于把每个字的信息全丢了。源码里常见写法是encoded bert_model(input_ids, attention_maskmask)[0] # 取last_hidden_state注意后面的[0]如果你写[1]就会拿到pooler_output模型训起来怎么都不涨。另外BERT输出要不要进行梯度回传我一般默认回传也就是微调BERT参数。如果你的数据集很大超过10万句微调能让BERT适应你的领域词汇如果数据集很小几千句冻结BERT只训练下游层反而更稳不然容易过拟合。实践中可以两种都试一下看验证集F1再决定。3.2 BiLSTM层双向语义的取舍与dropout设置BiLSTM接在BERT后面输入是每个字的768维向量输出是2倍hidden_size因为正向和反向各一个。这一层存在的意义是把整句的上下文信息进一步融合——虽然BERT内部已经有多层注意力但注意力更擅长捕捉全局关系对“相邻字之间的局部顺序敏感度”不如循环网络。比如在人名识别中“张”后面紧跟着“三”是一个强模式BiLSTM对这种局部顺序模式的编码比BERT更直接。hidden_size我常用的是128或256。128对中文NER已经够用再大了容易过拟合且增加显存和推理延迟。一个关键参数是num_layers不要盲目加到2层以上。两层BiLSTM的参数量很大而且在这个组合里BERT已经提过特征一层BiLSTM通常就够。如果你想调深建议同时把dropout提高到0.5以上否则验证集很快出现震荡。代码里的定义一般是self.bilstm nn.LSTM( input_size768, hidden_size128, num_layers1, batch_firstTrue, bidirectionalTrue, ) self.dropout nn.Dropout(p0.5) lstm_out, _ self.bilstm(encoded) # encoded: [batch, seq, 768] lstm_out self.dropout(lstm_out)这里batch_firstTrue和前面BERT输出的维度对齐省去转置的麻烦。nn.Dropout放在BiLSTM之后、CRF之前而不是放在BiLSTM内部——因为BiLSTM内部自带dropout参数但它只作用于层与层之间num_layers1时内部dropout根本不生效必须自己加一层Dropout。3.3 CRF层标签约束与转移矩阵的作用CRF层是整个模型的决策层。前面BERT和BiLSTM输出的每一个位置的logits都是独立判断这个字属于哪个标签的概率但独立判断会违反一些常识。比如在BIO标注里B-PER后面直接跟B-LOC就不合法一个实体不可能在“张三”之后立刻跳到“北京”而不经过I-PER或O。CRF会学习一个tag_size x tag_size的转移矩阵矩阵里的值表示从某一个标签跳到另一个标签的得分这个矩阵在训练过程中自动更新学到的正是你数据里实体的起始、延续和结束模式。核心逻辑在解码时体现我们用维特比算法在全体合法标签序列中找得分最高的一条路径而不是对每个位置取argmax。训练时则计算所有路径的log-sum-exp用它作为规范化项让正确路径的得分与所有路径得分总和的距离尽量小。这一来一回模型学到的就不只是“这个字像PER”还包括“PER后面不能直接跟LOC”这类序列约束。代码实现有不少现成库常用的有torchcrf和pytorch-crf。我一般自己实现一个轻量CRF类因为现成库有时对mask的处理有bugclass CRF(nn.Module): def __init__(self, num_tags): super().__init__() self.num_tags num_tags self.trans nn.Parameter(torch.randn(num_tags, num_tags)) def forward(self, emissions, mask): # emissions: [batch, seq, num_tags] # mask: [batch, seq], 1表示有效位 return self._score(emissions, mask) - self._normalizer(emissions, mask) def decode(self, emissions, mask): return self._viterbi(emissions, mask)注意trans矩阵初始化为随机值即可不要用全0初始化否则训练初期梯度可能消失。mask必须用attention_mask一样的值把padding位设成0这样CRF在计算转移和归一化时会把padding位置的标签忽略掉。我遇到过一个隐蔽bugattention_mask是[batch, seq]但CRF里用的mask忘了乘seq_len导致padding部分的loss总是计入验证集上表现正常但测试集一塌糊涂。这类问题只有靠对比两个mask的张量形状才能发现。4. 训练参数怎么调学习率、batch size、序列长度的血泪经验4.1 学习率BERT层与下游层的差异化设置BERTBILSTMCRF这个模型里BERT参数占比最大但下游层的参数是从零开始学的。两者对学习率的要求完全不同BERT已经在海量语料上收敛过微调时学习率过大会把预训练的知识“洗掉”而过小则学不动新数据里的领域特征。我一般的做法是给BERT一个较小的学习率比如2e-5到5e-5给BiLSTM和CRF一个较大的学习率比如1e-3到2e-3。在PyTorch里可以用GroupedOptimizer实现bert_params list(map(id, model.bert.parameters())) other_params filter(lambda p: id(p) not in bert_params, model.parameters()) optimizer torch.optim.AdamW([ {params: model.bert.parameters(), lr: 2e-5}, {params: other_params, lr: 1e-3}, ])这样设置之后你会发现loss下降速度比单一lr快很多而且验证集F1的峰值更高。如果你用的是HuggingFace的Trainer可以在TrainingArguments里设learning_rate5e-5再通过参数分组的方式覆盖BERT层但麻烦一点。我习惯直接手写训练循环因为NER的评估和掩码处理在Trainer里反而不灵活。还有一个容易踩的坑使用AdamW时权重衰减默认是0.01但BERT层的weight_decay应该设成0.01而bias和LayerNorm的weight_decay应该设成0否则训练不稳定。获取参数时要用param.requires_grad过滤掉冻结层我在冻结BERT时经常忘记这个导致梯度传到冻结层上模型表现时好时坏。4.2 batch size与梯度累积显存不够时的替代方案BERT系列的显存占用大头在Self-Attentionbatch size一大就容易OOM。我的经验是在12GB显存的显卡上max_seq_len128时batch size最多到16如果max_seq_len256batch size降到8才安全。如果你只有8GB显存batch size设为4或2也不是不行但训练会慢很多。不要为了让batch size变大而直接减小输入维度或隐藏层维度那样损失的信息可能比获益更大。更优雅的替代方案是梯度累积。用accumulation_steps把多个小batch的梯度累加后再更新一次参数效果近似于大batchfor step, batch in enumerate(train_loader): loss model(batch) loss loss / accumulation_steps # 平均梯度 loss.backward() if (step 1) % accumulation_steps 0: optimizer.step() scheduler.step() optimizer.zero_grad()这里accumulation_steps4配上batch_size4等效于batch_size16但显存只占4条样本的量。注意loss要除以accumulation_steps不然等效batch下学习率偏大训练会不稳。如果你用的是多卡还要注意每个卡的loss已经平均过了梯度累积时不要再额外乘卡数。另外CRF层的loss是所有路径的总和对batch size很敏感。我遇到过一个现象batch size从4增加到8验证集F1反而掉了1到2个点。这是因为CRF的归一化项里涉及所有可能的标签序列batch size变大后模型看到更多噪声样本转移矩阵被拉偏。所以NER场景下batch size不是越大越好我一般固定16再通过梯度累积解决显存问题。4.3 序列长度与填充策略中文分字与padding的坑中文NER里序列长度直接决定了你能容纳多少上下文。短句子截断到128没问题但医疗文书经常有一整段几百字的病史描述里面实体分布很密截断会把后半段的实体全部扔掉。我处理这种情况的常见做法是分句而不是粗暴截断。按句号和分号把长文本切成多个短句每个短句单独过模型然后拼接结果。这样既保留了完整语义又不超过max_seq_len。如果你非要用长序列记得调整BERT的位置编码。bert-base-chinese支持的最大位置是512所以max_seq_len最多设为512。设为512时不仅显存爆涨而且推理时间接近线性的2倍以上。我一般建议128作为默认256用于专业领域512只在你确信数据里有极长且不可切分的实体时才用。Padding的坑更隐蔽。模型在计算loss时必须忽略padding位置的预测。如果忘记传attention_mask给BERTpadding位也被当作真实字参与注意力计算模型会把[PAD]当普通字学出荒谬的模式。CRF层的mask和BERT的attention_mask必须完全一致而且这两个mask要放在同一个设备上。我经常因为mask.cuda()和input_ids.cuda()顺序不一致导致类型不匹配报错或者更恶心的mask没有cast成torch.long在CRF里索引时报IndexError。这些小问题排查起来很费时间建议在数据加载器里就把mask统一处理好。下面是一段典型的批处理逻辑我把padding和mask的生成写在一起尽量避免后面踩坑def collate_fn(batch): texts, labels, max_len [], [], 0 for token_list, label_list in batch: texts.append(token_list) labels.append(label_list) max_len max(max_len, len(token_list)) input_ids [] attention_masks [] label_ids [] for text, label in zip(texts, labels): # 这里用的是BERT tokenizer中文是字级所以可以直接编码 encoding tokenizer(text, paddingmax_length, truncationTrue, max_lengthmax_len, return_tensorspt) input_ids.append(encoding[input_ids][0]) attention_masks.append(encoding[attention_mask][0]) # 标签对齐把O填充到max_len多出来的截掉 padded_label label [label2id[O]] * (max_len - len(label)) label_ids.append(padded_label[:max_len]) return torch.stack(input_ids), torch.stack(attention_masks), torch.tensor(label_ids)注意标签对齐时padded_label用的是label2id[O]不是0。如果O的id不是0填充值用错了会导致所有padding位的预测都算成某个实体类别评估时F1直接崩盘。最好先打印label2id确认一下。5. 避坑指南BERTBILSTMCRF落地最常见的5个翻车点5.1 现象loss很低但验证F1一直为0这个现象很典型训练loss从5降到0.2但验证集上模型预测全是O一个实体都识别不出来。根源多数是标签和输入错位。中文BERT的字级tokenizer虽然基本是一字一token但遇到特殊符号如“·”或全角空格时会拆成多个token导致标签长度和输入长度对不上。比如“赵·丽颖”这种名字tokenizer可能把“·”当成一个token但你的数据里“赵”、“·”、“丽”、“颖”各占一个位置长度一致但如果中间混入了一个空格长度就不一致了模型自然学不到实体。解决方法是做标签对齐时用tokenizer的offset_mapping逐个映射。简单粗暴的办法是预处理数据时去掉所有空格和特殊符号只保留中英文数字和常见标点。另外如果max_seq_len小于句子长度截断时要把尾部的实体标签一起扔掉否则标签错位会让loss收敛不了。我习惯在数据加载后打印一条“最长标签长度”和“最长输入长度”如果两者不相等说明预处理有bug。另外一个不罕见的原因是label2id里O的id设置成了0但在CRF解码时转移矩阵里O到O的得分初始值太大导致维特比路径全部偏向O。我碰过这种把O的id设为0又在CRF初始化时把trans矩阵前几行设成全0结果模型训练到后期解码时发现所有路径中“全部O”路径得分居然最高于是永远输出全O。解决办法是不要把O的id固定在0可以让O排在后面或者手动打印一个batch的预测分布看看。5.2 现象预训练模型下载失败或路径错误很多人在跑BERT时卡在下载权重上。第一次运行BertModel.from_pretrained(bert-base-chinese)会从HuggingFace下载约400MB的文件如果网络环境不畅会报ConnectionError或OSError。这个下载过程没有进度条容易让人觉得程序死了。解决手法有三种一是用国内镜像站设置环境变量HF_ENDPOINThttps://hf-mirror.com后再运行二是在有网络的地方手动下载config.json、pytorch_model.bin、vocab.txt到本地目录再用from_pretrained(./path)加载三是直接用别人打包好的模型文件但要注意文件名必须匹配不能把tf_model.h5和pytorch_model.bin搞混。还有一类路径错误是项目里写死了相对路径./pretrained/bert-base-chinese但你解压zip后目录结构变了。我建议第一步先tree或ls -R看一下解压出来的完整目录找到模型权重实际在哪再修改代码里的路径。不要用os.path.exists去猜打印一下绝对路径最踏实。5.3 现象CRF相关loss出现NaN或者解码时报索引越界这类问题多半出在mask的dtype和设备上。CRF里计算转移得分时要用mask把padding位置剔除如果mask是torch.float而后续操作把它当成torch.long来索引就会报RuntimeError。解决方法是统一mask的类型并确保它和input_ids在同一个设备attention_mask attention_mask.long()另一个NaN源头是torch.logsumexp在路径长度太短时出现数值不稳定。如果max_seq_len设为1CRF的归一化项里只有很少的路径logsumexp可能溢出。实际上BERT中文模型很少用长度为1的序列但我在写测试用例时遇到过所以提醒一句CRF的输入序列长度不能小于2。如果你的实现是自写的CRF还要注意trans矩阵在训练时是否有一个维度是num_tags2因为有些实现会加START和END状态。我常用的pytorch-crf库内部已经管理好这些状态只要传emissions和mask即可。如果自己实现建议先跑一个batch大小为1、序列长度为3的用例打印出score和normalizer的形状确认没有维度错位。5.4 现象评测代码算出的F1和训练日志里的F1对不上训练日志是在每个epoch结束后用验证集算的如果你的评估函数把O标签也当成需要预测的类别那么O占大多数整体F1虚高且没有参考价值。正确做法是在计算F1时排除O标签或者至少用labels参数指定只关心实体类别。另一个常见问题是没有忽略padding位置测试时如果attention_mask是0的位置也计入预测模型在padding上大概率预测为O这会人为拉高准确率因为O太多了。我一般用seqeval库计算实体级别的F1它能自动按BIO合并实体并且忽略以-开头的内部标签pip install seqevalfrom seqeval.metrics import classification_report true_entities [[entity for entity in sent if entity ! O] for sent in true_labels] pred_entities [[entity for entity in sent if entity ! O] for sent in pred_labels] print(classification_report(true_entities, pred_entities))注意classification_report要求标签是字符串比如B-PER所以你需要把id转换回标签名。如果seqeval报ValueError: I-PER requires B-PER说明预测的标签序列里出现了I-PER开头而没有前置B-PER这其实是CRF没学好或者你在解码后没有修正非法序列。遇到这种情况我建议把CRF的维特比输出强制校正一下如果I出现在B之前把I改成B直到整个序列合法为止。5.5 现象验证集F1高测试集F1断崖式下跌这是典型的过拟合信号。BERT微调在少量数据上特别容易过拟合验证集因为你反复用验证集调参验证集的噪声也被模型记进去了。出现这种情况时优先检查训练集和测试集是不是同分布。如果来自不同来源比如训练集是新闻测试集是医疗文本那模型再强也白搭。排除分布问题后再看是不是验证集太小。如果你的dev集只有500句F1方差会很大调参时看到的0.83可能是运气好。解决办法是增加验证集比例或者用交叉验证。还有一招是早停当验证集F1连续2个epoch不再上升时保存当前模型而不是继续训到固定epoch。我自己的血泪经验是BERT微调第1个epoch通常F1很低第2个epoch暴涨第3个epoch好好珍惜第4个epoch开始过拟合。所以不要因为第2个epoch涨得猛就把num_epochs设成10那只是纸面F1好看罢了。后来我习惯在训练过程中每个epoch保存一次模型最后回看哪个epoch的测试集F1最高。6. 让模型跑得更稳的收尾技巧早停、模型保存与bad case分析把模型训练跑通只是第一步真正能拿去上线还得靠这两件事。第一把“保存哪个模型”从拍脑袋变成有依据。我一般不在每个epoch结束时无脑覆盖保存而是在验证集F1创新高时保存一份best_model.bin并同时保存参数配置和标签映射这样即使后面训练跑崩了也有后悔药if best_f1 eval_f1: best_f1 eval_f1 torch.save(model.state_dict(), fbest_model_{eval_f1:.4f}.bin) with open(tag_map.json, w, encodingutf-8) as f: json.dump(label2id, f, ensure_asciiFalse)第二固定随机种子。BERT微调本身有随机性不同种子可能带来1到2个F1的浮动。训练开头设torch.manual_seed(42)、np.random.seed(42)、random.seed(42)如果用了DataLoader的shuffleTrue最好在generator里也指定seed否则实验结果没法复现。再看bad case分析。训完模型后我习惯把测试集里预测错的句子单独抽出来打印成表格表格内容包含原始句子、真实标签、预测标签、模型对每个位置的置信度。这个做法能直接暴露两个常见问题一是实体边界对不齐比如预测北为B-LOC但漏掉京的I-LOC说明CRF的转移矩阵对I标签的延续不够自信二是嵌套实体丢失比如“北京人民医院”里既有ORG又有LOC模型只识别出ORG是因为训练数据里没有嵌套标注。这类分析没法靠调参解决要么改标注规范要么换成阅读理解式NER模型。我在落地时还有一个习惯给模型留一个“阈值修正”接口。CRF解码输出的得分虽然没有概率意义但可以通过比较最优路径和第二优路径的差值来当置信度。在工程里对置信度低于某个阈值的句子不抽取实体宁可漏不可错这样上线后人工复核量会大幅降低。具体实现可以在CRF解码时同时返回路径得分scores, paths crf.decode(emissions, mask) confidence scores - scores_second_best不过这套操作需要你手写CRF的解码函数对多数人来说有点重。建议先不做而是把bad case保存下来和标注团队对齐数据往往改十处标注比调十个参数更见效。结尾从环境搭建到CRF解码这套组合看起来像个黑匣子但把它拆成三块后每块的职责都特别清楚。我自己最早跑通这个工程时也踩过标签错位、mask传错、验证集过拟合这些坑后来慢慢养成了一个习惯每次训练前先打印一条样本的input_ids和label_ids的长度每次评估前先跑一个batch的预测结果和真实标签做对比这样能在几分钟内发现大多数低级失误。如果你也被中文命名实体识别折磨得够呛希望这篇笔记能让你少走一点弯路至少让你下次遇到“loss很低但F1为0”时知道该从哪里下手。希望帮到你。本文还有配套的精品资源点击获取