中文命名实体识别实战：BERT-BiLSTM-CRF模型搭建与避坑指南

简介：本资源面向中文命名实体识别（NER）方向的初学者与毕业设计、课程设计需求者，提供一套基于PyTorch实现的BERT-BiLSTM-CRF完整项目。项目将预训练BERT、双向LSTM与条件随机场结合，覆盖数据加载、模型构建、训练、评估与预测全流程，代码含详细注释，新手也能看懂并快速部署。压缩包共22个文件，约2.4MB，包含8个py源码文件、5个txt数据集与标签文件、5个xml配置、1个md说明文档及json等辅助文件，源码、数据与说明齐备，目录结构清晰。目前已有663人学习下载，属于导师认可的高分项目。读者可获得可直接运行的NER训练与预测脚本、中文数据集、参数配置与项目说明，便于理解BERT-BiLSTM-CRF的工程实现，并在此基础上完成模型调优、实验复现或二次开发。

1. 中文命名实体识别为什么还在用 BERT-BiLSTM-CRF：从一次标注翻车说起

如果你手头有一批中文文本，需要把里面的人名、地名、机构名、时间、金额甚至行业专有名词自动抽出来，大概率绕不开命名实体识别（NER）。我最早做这块时，试过纯规则、试过词典匹配，也试过直接用 BERT 加一个分类头，结果在「嵌套实体」和「标签边界」上反复翻车——比如「北京市海淀区」被切成「北京市」和「海淀区」两个地名，或者「张三丰」被识别成「张三」加「丰」。后来换成 BERT-BiLSTM-CRF 这套组合，边界和标签依赖的问题才明显收敛。

这套模型的结构并不复杂：BERT 负责把字变成带上下文的向量，BiLSTM 负责捕捉前后文序列关系，CRF 负责约束标签之间的转移合法性（比如 I-ORG 不能直接接 B-PER）。它适合谁？适合手头有几千到几万条标注数据、想快速搭一个中文 NER 基线、又不想从零训词向量的 Python 开发者。下面我按「数据怎么准备 → 模型怎么搭 → 怎么训 → 怎么避坑 → 怎么进阶」的顺序，把可复现的路径讲清楚。

2. 数据准备与标注格式：把原始文本变成 BERT-BiLSTM-CRF 能吃的输入

2.1 中文 NER 常见标注体系与标签设计

中文 NER 最常用的标注体系是 BIO 和 BIOES。BIO 只有 B、I、O 三种前缀，BIOES 多了 E（实体结束）和 S（单字实体）。我一般推荐 BIOES，因为它在边界上更明确，CRF 的转移约束也更好设计。标签集合取决于你的业务：通用领域常用 PER（人名）、LOC（地名）、ORG（机构名）；垂直领域比如医疗要加 DIS（疾病）、DRUG（药物），金融要加 MONEY、TIME。

标签设计有个血泪经验：不要一开始就堆几十个标签。标签越多，每个标签的样本越少，CRF 转移矩阵越难学。我通常先做 4 到 8 个核心标签，跑通基线后再逐步加。标签文件单独存成labels.txt，每行一个标签，顺序固定，训练和推理必须用同一份。

2.2 把原始语料转成 BIOES 格式的 Python 脚本

假设你有一份raw.txt，每行是一句中文，实体信息存在另一个entities.json里，格式是{"句子索引": [[起始位置, 结束位置, 实体类型], ...]}。下面这个脚本把它转成 BIOES 标注：

import json def bioes_tag(sentence, entities): # 初始化全 O tags = ['O'] * len(sentence) for start, end, label in entities: if start == end: tags[start] = f'S-{label}' else: tags[start] = f'B-{label}' for i in range(start + 1, end): tags[i] = f'I-{label}' tags[end] = f'E-{label}' return tags with open('raw.txt', 'r', encoding='utf-8') as f: sentences = [line.strip() for line in f if line.strip()] with open('entities.json', 'r', encoding='utf-8') as f: entity_map = json.load(f) with open('train.bioes', 'w', encoding='utf-8') as out: for idx, sent in enumerate(sentences): ents = entity_map.get(str(idx), []) tags = bioes_tag(sent, ents) for ch, tag in zip(sent, tags): out.write(f'{ch}\t{tag}\n') out.write('\n') # 句子之间空行分隔

逻辑说明：bioes_tag按实体起止位置打标签，单字实体用 S，多字实体首尾用 B/E，中间用 I。参数说明：entities.json的 key 必须和句子索引对应，位置是闭区间。转换后每行是「字 + tab + 标签」，空行分句。这个格式后面喂给 Dataset 类时直接按空行切句即可。

2.3 数据集划分与标签对齐检查

划分比例我一般用 8:1:1，但中文 NER 数据少的时候会用 7:1.5:1.5。关键是标签对齐：训练集里出现过的标签，验证集和测试集可以没有，但推理时的标签列表必须和训练时完全一致，否则 CRF 转移矩阵对不上。我习惯在训练前跑一个检查脚本，统计每个标签的出现次数，出现次数少于 5 的标签要么合并要么删掉，不然 CRF 学出来的转移分数基本是噪声。

提示：如果你的数据里实体有重叠（比如「北京大学人民医院」既是 ORG 又包含 LOC），BIOES 单层标注放不下，需要改成多层标注或改用 span 抽取方案，这套 BERT-BiLSTM-CRF 就不适用了。

3. 模型搭建：BERT 输出怎么接 BiLSTM 再接 CRF

3.1 BERT 层：选中文预训练模型与输出维度处理

BERT 层直接用 HuggingFace 的transformers加载中文预训练模型。常见做法是选bert-base-chinese，它输出的是每个字的 768 维向量。注意 BERT 的 tokenizer 对中文是按字切分，但遇到英文和数字会按子词切，所以你的标签也要按 tokenizer 的实际切分对齐。我一般用is_split_into_words=True，先按字切好再喂给 tokenizer，这样标签和 token 一一对应。

from transformers import BertTokenizer, BertModel import torch import torch.nn as nn class BertEncoder(nn.Module): def __init__(self, model_name='bert-base-chinese'): super().__init__() self.bert = BertModel.from_pretrained(model_name) self.hidden_size = self.bert.config.hidden_size # 768 def forward(self, input_ids, attention_mask): outputs = self.bert(input_ids=input_ids, attention_mask=attention_mask) # outputs.last_hidden_state: [batch, seq_len, 768] return outputs.last_hidden_state

参数说明：model_name换成你本地的预训练模型路径也行，离线环境提前下载好。attention_mask必须传，否则 padding 位置会参与 BiLSTM 计算，导致标签偏移。BERT 层一般不加额外投影，直接输出 768 维给 BiLSTM。

3.2 BiLSTM 层：隐藏维度、层数与 dropout 的设置

BiLSTM 接在 BERT 后面，输入维度 768，隐藏维度我一般设 256，双向拼接后是 512。层数 1 到 2 层足够，再深容易过拟合且训练慢。dropout 设 0.3 到 0.5，放在 BiLSTM 输出之后、CRF 之前。

class BiLSTMEncoder(nn.Module): def __init__(self, input_dim=768, hidden_dim=256, num_layers=1, dropout=0.4): super().__init__() self.lstm = nn.LSTM( input_dim, hidden_dim, num_layers=num_layers, bidirectional=True, batch_first=True, dropout=dropout if num_layers > 1 else 0 ) self.dropout = nn.Dropout(dropout) self.output_dim = hidden_dim * 2 # 512 def forward(self, x, attention_mask): # x: [batch, seq_len, 768] lstm_out, _ = self.lstm(x) lstm_out = self.dropout(lstm_out) return lstm_out # [batch, seq_len, 512]

参数说明：hidden_dim=256是经验值，数据量小可以降到 128，数据量大可以升到 384。num_layers=1时 dropout 不生效，这是 PyTorch 的行为，别误以为设了没用。attention_mask在这里没直接用到，但后面 CRF 的 mask 要用它来屏蔽 padding。

3.3 CRF 层：转移矩阵与维特比解码的实现要点

CRF 层是这套模型的「后悔药」——它保证输出的标签序列合法。核心是一个转移矩阵transitions[i][j]表示从标签 i 转到标签 j 的分数，加上发射分数（BiLSTM 输出经过一个线性层映射到标签数）。训练时用负对数似然，推理时用维特比解码。

from torchcrf import CRF class BertBiLSTMCRF(nn.Module): def __init__(self, num_labels, model_name='bert-base-chinese'): super().__init__() self.bert = BertEncoder(model_name) self.bilstm = BiLSTMEncoder(input_dim=self.bert.hidden_size) self.classifier = nn.Linear(self.bilstm.output_dim, num_labels) self.crf = CRF(num_labels, batch_first=True) def forward(self, input_ids, attention_mask, labels=None): bert_out = self.bert(input_ids, attention_mask) lstm_out = self.bilstm(bert_out, attention_mask) emissions = self.classifier(lstm_out) # [batch, seq_len, num_labels] if labels is not None: # 训练：返回负对数似然 loss = -self.crf(emissions, labels, mask=attention_mask.bool(), reduction='mean') return loss else: # 推理：维特比解码 return self.crf.decode(emissions, mask=attention_mask.bool())

逻辑说明：torchcrf的CRF类封装了前向算法和维特比解码。mask参数必须传，否则 padding 位置的标签会参与转移计算。参数说明：num_labels等于标签文件行数；reduction='mean'对 batch 内取平均，数据不平衡时可以改成'sum'再手动加权。推理返回的是每条序列的标签 id 列表，需要映射回标签名。

4. 训练与推理：从配置到跑通的完整命令

4.1 训练脚本与关键超参配置

训练脚本我一般写成train.py，核心超参如下表：

import torch from torch.utils.data import DataLoader from transformers import BertTokenizer tokenizer = BertTokenizer.from_pretrained('bert-base-chinese') model = BertBiLSTMCRF(num_labels=len(label_list)).cuda() optimizer = torch.optim.AdamW(model.parameters(), lr=2e-5, weight_decay=0.01) for epoch in range(epochs): model.train() 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_norm=1.0) optimizer.step() optimizer.zero_grad() # 验证集评估见 4.2

逻辑说明：clip_grad_norm_防止梯度爆炸，BERT 微调时尤其重要。参数说明：max_norm=1.0是常用值，训练不稳定可以降到 0.5。optimizer.zero_grad()放在step()之后是个人习惯，放前面也行，但别漏。

4.2 用 seqeval 算实体级 F1 而不是 token 级准确率

token 级准确率在 NER 里会骗人——因为大部分标签是 O，模型全预测 O 也能有 90% 以上准确率。必须用实体级 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) for pred, label in zip(preds, labels): pred_tags = [id2label[p] for p in pred] true_tags = [id2label[l.item()] for l in label if l.item() != -100] all_preds.append(pred_tags) all_labels.append(true_tags) print(classification_report(all_labels, all_preds)) return f1_score(all_labels, all_preds)

逻辑说明：-100是 padding 标签的忽略值，评估时要过滤掉。参数说明：seqeval要求输入是标签字符串列表的列表，不是 id。classification_report会输出每个实体类型的 precision、recall、F1。

4.3 推理脚本：加载模型并对新句子做实体抽取

推理时把模型切到eval()，关掉 dropout，按同样的 tokenizer 处理输入。

def predict(text, model, tokenizer, id2label, max_len=128): model.eval() tokens = list(text) encoding = tokenizer(tokens, is_split_into_words=True, max_length=max_len, truncation=True, padding='max_length', return_tensors='pt') input_ids = encoding['input_ids'].cuda() attention_mask = encoding['attention_mask'].cuda() with torch.no_grad(): pred_ids = model(input_ids, attention_mask)[0] tags = [id2label[i] for i in pred_ids] # 按 BIOES 合并实体 entities = [] current = None for ch, tag in zip(tokens, tags): if tag.startswith('B-'): current = [ch, tag[2:]] elif tag.startswith('I-') and current: current[0] += ch elif tag.startswith('E-') and current: current[0] += ch entities.append(tuple(current)) current = None elif tag.startswith('S-'): entities.append((ch, tag[2:])) else: if current: entities.append(tuple(current)) current = None return entities

逻辑说明：BIOES 合并时 B 开头、I 延续、E 结束、S 单独成实体。参数说明：max_len要和训练时一致，截断策略默认是尾部截断。注意 tokenizer 对英文数字的子词切分会让tokens和tags长度不一致，稳妥做法是用word_ids()对齐，这里为简洁按纯中文处理。

5. 避坑与排查：BERT-BiLSTM-CRF 训练中常见的 5 个翻车点

5.1 损失不下降，CRF 转移矩阵全是噪声

现象：训练几个 epoch 后 loss 卡在 2.0 左右不降，验证集 F1 接近 0。原因：标签列表里有出现次数极少的标签，CRF 转移矩阵对这些标签的分数学不出来，反而干扰了其他标签。解决：统计标签频次，把少于 5 次的标签合并到 O 或相近标签，重新生成标签文件再训。

5.2 验证集 F1 很高但推理结果全是 O

现象：验证集 F1 0.9，但拿新句子推理，输出全是 O。原因：验证集和训练集同分布，而新句子长度超过max_seq_len被截断，实体正好在截断部分；或者 tokenizer 的is_split_into_words没开，标签和 token 错位。解决：检查推理输入长度，确认 tokenizer 配置和训练一致，打印 token 和标签对齐结果。

5.3 显存溢出，batch_size 降到 1 还报 OOM

现象：8G 显存跑 batch_size 16 直接 OOM，降到 1 仍然报错。原因：BERT 模型本身占显存，加上 BiLSTM 和 CRF 的中间变量，以及max_seq_len=256时的注意力矩阵。解决：先把max_seq_len降到 128，开启torch.cuda.amp混合精度，BiLSTM 的hidden_dim从 256 降到 128，通常能省一半显存。

5.4 实体边界识别错误，B 和 I 标签混淆

现象：模型把「北京市海淀区」识别成「北京市海」加「淀区」。原因：BIOES 的 E 标签样本太少，CRF 没学好 E 的转移。解决：检查标注质量，确认 E 标签没有漏标；增加 E 标签的样本；或者改用 BIO 标注，边界问题交给后处理规则。

5.5 加载预训练模型时报缺失 key 或维度不匹配

现象：from_pretrained报size mismatch或大量 missing keys。原因：用了非中文预训练模型，或者模型配置里的vocab_size和 tokenizer 不一致。解决：确认model_name和tokenizer来自同一个预训练模型；如果自己改过词表，需要 resize embedding 并重新微调。

6. 进阶技巧：用对抗训练和标签平滑把 F1 再提两个点

基线跑通后，想再提点，我一般先上两个技巧：FGM 对抗训练和标签平滑。FGM 在 embedding 层加扰动，让模型对输入噪声更鲁棒；标签平滑缓解 CRF 对硬标签的过拟合。这两个都不改模型结构，只改训练循环。

class FGM: def __init__(self, model, epsilon=1.0): self.model = model self.epsilon = epsilon self.backup = {} def attack(self): for name, param in self.model.named_parameters(): if 'embedding' in name and param.requires_grad: self.backup[name] = param.data.clone() norm = torch.norm(param.grad) if norm != 0: r_at = self.epsilon * param.grad / norm param.data.add_(r_at) def restore(self): for name, param in self.model.named_parameters(): if name in self.backup: param.data = self.backup[name] self.backup = {}

用法是在正常loss.backward()之后、optimizer.step()之前，先fgm.attack()，再算一次 loss 并 backward，然后fgm.restore()，最后 step。参数说明：epsilon=1.0是常用值，太大反而掉点。标签平滑在 CRF 里没有直接接口，常见做法是在发射分数上做平滑，或者改用CrossEntropyLoss(label_smoothing=0.1)替代 CRF 的 NLL——但这样会丢掉转移约束，我一般只在数据量很大时才这么干。

验证方法：每次改动只动一个变量，跑三次不同随机种子取平均 F1，避免被单次波动骗了。我自己的习惯是，任何「提点」技巧，如果三次平均提升不到 0.5 个点，就不加进最终方案，保持训练脚本干净。这套 BERT-BiLSTM-CRF 的代码结构不复杂，难的是数据质量和标签一致性，把这两块守住，F1 不会差。希望帮到你。

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