简介：这是一套基于BERT模型的电子病历命名实体识别系统源码，面向医疗信息化开发者、NLP研究与工程人员，用于从电子病历文本中自动识别疾病、药物、治疗手段等关键实体，支撑临床决策与医疗数据处理。资源共38个文件，含21个Python源文件、6个文本说明、3个XML配置、2个Markdown文档及Jupyter Notebook交互脚本，整体约395KB。代码覆盖数据预处理、模型定义、训练、预测与评估全流程，并附带readme说明、license许可及Git忽略配置，目录结构清晰，便于直接改造与二次实验。目前已吸引320人学习参考，对希望快速上手医疗NER任务的读者具有实用价值。
1. 电子病历命名实体识别：为什么“BERT + 源码”是这个方向的起点
把一份电子病历交给算法，让它自动抽取出“患者右上腹疼痛3天”里的症状、“CT提示胆囊结石”里的检查结果和疾病诊断——这就是电子病历命名实体识别（NER）要解决的事。它不是医疗NLP里最炫的方向，但绝对是所有结构化病历分析的第一步：没有实体抽取，后面的关系抽取、知识图谱、辅助诊断全是空中楼阁。
我为什么推荐从“基于BERT的电子病历NER设计源码”入手？因为BERT把中文文本的语义编码能力拉高了一个量级，在医疗这种词汇专业、表述不规范的场景里，预训练语义比任何人工特征都好使。而且序列标注任务有成熟的范式：BERT编码文本 + 全连接层（或CRF）解码标签。本文会把这套从数据标注、模型构建到训练调参、踩坑排错的完整路径拆开讲，新手能照着跑，熟手能避坑。
2. 电子病历 NER 的标签体系与数据准备工作：先弄清识别什么
2.1 电子病历里到底抽哪几类实体：六类标签的设计逻辑
电子病历和新闻、法律文本不一样，它的实体类型高度集中，而且不同科室略有差异。我一般把实体类型划成六类：症状、体征、检查、检验、疾病、药物。听起来简单，但到了标注环节就麻烦——比如“发热”既是症状也可以是体征，“示指骨折”是疾病还是体征？不同标注规范下答案不一样。所以做这个项目的第一步不是写代码，而是定标注规范，规范定了，模型的上限就锁了。
标注体系我选BIO（Begin, Inside, Outside），因为简单且实现稳定。每个token对应一个标签，非实体为O，实体首字为B-实体类型，实体中间和结尾为I-实体类型。比如“患者右上腹疼痛”中，“疼痛”标注为B-SYMPTOM、I-SYMPTOM。BIOES（增加E结尾、S单字）效果略好，但代码复杂度高一点，新手项目没必要一上来就上BIOES。
2.2 把原始病历文本转成训练样本：BIO标签转换脚本
拿到标注数据（通常来自医学生或标注平台）后，第一步是把原始文本和实体位置转换成BERT能消费的BIO标签序列。下面这段代码是我常用做法，输入是纯文本加实体标注列表，输出是token级别的BIO标签序列：
def create_bio_labels(text: str, entities: list) -> list: """ 将文本和实体标注转为BIO标签序列，按字符粒度。 entities: [{"start": 3, "end": 5, "type": "SYMPTOM"}] end为开区间, 不含末尾 返回: ["O", "O", "O", "B-SYMPTOM", "I-SYMPTOM", "O", ...] """ labels = ["O"] * len(text) # 先给每个实体打上BIO for ent in entities: start, end = ent["start"], ent["end"] if start >= end: continue # 多字实体 labels[start] = f"B-{ent['type']}" for idx in range(start + 1, end): labels[idx] = f"I-{ent['type']}" return labels # 示例用法 text = "患者右上腹疼痛3天" ents = [{"start": 3, "end": 5, "type": "SYMPTOM"}] labels = create_bio_labels(text, ents) print(list(zip(text, labels))) # [('患','O'), ('者','O'), ('右','O'), ('上','B-SYMPTOM'), ('腹','I-SYMPTOM'), # ('疼','I-SYMPTOM'), ('痛','I-SYMPTOM'), ('3','O'), ('天','O')]这段代码的逻辑看着简单，实际有讲究：实体标注的 end 必须是开区间，因为 Python 切片本来就是这样习惯，但很多标注平台导出的是闭区间，这里不统一就会到处差一个字符。建议在读取标注文件后就统一成开区间，不要在 create_bio_labels 里再修，否则多个实体重叠时会出问题。另一个值得留意的是实体长度——单字实体照样能标，但B后必须跟I，否则CRF那一层会报错。
2.3 用BERT的Tokenizer做对齐：字符级标签如何映射到subword
电子病历文本进入BERT前要做tokenize，而中文BERT（bert-base-chinese）是按字切分的——"胃"变成 [unused] 或者一个 token，所以字符级标签和token级标签在中文里基本是1:1对齐。但病历里常嵌英文缩写和数字（比如"CT"、"3.5cm"、"AFP"），这时英文被拆成子词，标签就得跟着展开。这块是对齐代码里最容易翻车的地方，我单独写清楚：
from transformers import BertTokenizerFast def align_labels_with_tokens(tokenizer, text: str, char_labels: list): """ 把字符级BIO标签对齐到BERT token级。 BERT中文按字切分，但英文/数字会被切成subword，标签要跟着展开或分摊。 """ token_ids = tokenizer(text, add_special_tokens=False)["input_ids"] tokens = tokenizer.convert_ids_to_tokens(token_ids) token_labels = [] char_idx = 0 # 当前字符在原文中的游标 for token in tokens: if token in ("[UNK]", "[CLS]", "[SEP]"): token_labels.append("O") continue # BERT中文token基本等于原文一个字符；特殊符号如“##”开头的英文子词 if char_idx >= len(char_labels): token_labels.append("O") continue if token.startswith("##"): # 它是前面英文词的子词部分，标签跟着上一个词走 token_labels.append(token_labels[-1] if token_labels else "O") elif token in ("[UNK]",): token_labels.append("O") # 未知字符保守处理为O else: # 普通token，对应原文一个字符 token_labels.append(char_labels[char_idx]) char_idx += 1 return token_ids, token_labels这里关键点：BERT的decode后token不等于原文字符的情况主要是##开头的英语子词；中文生僻字会变成[UNK]，此时保持O而不是勉强对齐，因为我宁可在训练时少一个正样本，也不要在标签里掺脏数据。最后一个注意点是BertTokenizerFast和BertTokenizer的切分结果几乎一致，但Fast版的速度快得多，数据准备阶段建议用Fast版。
3. 用BERT做序列标注的最小复现：模型架构与训练管线
3.1 为什么选BERT而不是BiLSTM-CRF：预训练语义的价值
2018年之前，医疗NER的主流做法是BiLSTM+CRF，词向量用word2vec。这个方案的瓶颈在词覆盖——电子病历里“上腹部绞痛”“墨菲氏征阳性”这类专业表述，word2vec没见过的词太多，OOV（out-of-vocabulary）问题严重。换成BERT之后，预训练阶段见过的中文语料足够大，生僻专业词的上下文表示远比静态词向量可靠。
另一个被低估的点是BERT的双向编码。BiLSTM虽然是双向，但本质是拼接两个方向的隐状态，对长距离依赖的建模能力和Transformer相比还是差一截。电子病历里“患者3年前因胆囊结石行胆囊切除术，术后恢复可，近1周再发右上腹疼痛”——这个“再发”要能追溯到“胆囊结石”这个老毛病，就得有很强的上下文建模能力。
3.2 整体架构设计：BERT + 全连接 + CRF 还是 Softmax
我见过不少教程直接把BERT输出的[CLS]向量拿去分类，这是文本分类的做法，不能用于序列标注。序列标注的标准架构是：BERT输出每个token的768维向量，再接一个全连接层，把维度映射到标签数（比如B-SYMPTOM、I-SYMPTOM、O等13类），然后接Softmax或CRF解码。差别在于Softmax对每个token独立预测，可能预测出“I-SYMPTOM”开头却没有“B-SYMPTOM”这种非法序列，而CRF在解码时用转移矩阵约束标签间的合法性。
实战中我一般先跑通“BERT + 全连接 + Softmax”，拿到baseline，再加CRF层。建议不要一开始就上CRF，理由有两条。一是Softmax版本的loss收敛更容易观察，以及诊断错误时更好定位（是BERT没学到语义，还是CRF转移约束搞错了）。二是CRF的loss对学习率敏感，初上手容易踩坑，第5章会专门讲。所以下面的最小复现用Softmax，但我在3.4节也给出CRF的完整代码。
3.3 训练管线代码：数据加载与标签重映射
import torch from torch.utils.data import Dataset from transformers import BertTokenizerFast class EMR_NER_Dataset(Dataset): def __init__(self, texts, label_seqs, tokenizer, max_len=256, label2id=None): self.texts = texts self.label_seqs = label_seqs # 字符级BIO标签 self.tokenizer = tokenizer self.max_len = max_len self.label2id = label2id # {"O": 0, "B-SYMPTOM": 1, ...} def __len__(self): return len(self.texts) def __getitem__(self, idx): text = self.texts[idx] char_labels = self.label_seqs[idx] token_ids, token_labels = align_labels_with_tokens( self.tokenizer, text, char_labels ) # 截断 + 加特殊token token_ids = token_ids[:self.max_len - 2] token_labels = token_labels[:self.max_len - 2] token_ids = [self.tokenizer.cls_token_id] + token_ids + [self.tokenizer.sep_token_id] token_labels = ["O"] + token_labels + ["O"] # CLS和SEP都标O attention_mask = [1] * len(token_ids) # 转id label_ids = [self.label2id.get(lbl, 0) for lbl in token_labels] return { "input_ids": torch.tensor(token_ids, dtype=torch.long), "attention_mask": torch.tensor(attention_mask, dtype=torch.long), "labels": torch.tensor(label_ids, dtype=torch.long), } # 使用示例 label_list = ["O", "B-SYMPTOM", "I-SYMPTOM", "B-SIGN", "I-SIGN", "B-DISEASE", "I-DISEASE", "B-TEST", "I-TEST", "B-TREATMENT", "I-TREATMENT", "B-MEDICINE", "I-MEDICINE"] label2id = {lbl: i for i, lbl in enumerate(label_list)}这段代码里max_len=256是调出来的经验值：电子病历的主诉和现病史段落一般不超过200字，但体格检查部分可能到400字。第5章会讲长文本截断导致实体切半的问题，那里有一个滑动窗口方案。然后标签里面出现了13个类别，其中每个实体类型都有B和I两个标签，这个设计在CRF里是必需的，Softmax里也会让模型更容易区分实体边界。
3.4 训练循环：从loss计算到CRF解码的完整代码
训练循环里有两个细节很多人第一次会做错。一是BERT的输出取last_hidden_state而不是pooler_output。pooler_output是[CLS]那个token过了一层tanh的结果，它只适合做句级分类。二是在计算loss时要设置ignore_index=-100，把padding位置的label忽略掉，否则模型会努力学习“预测pad为O”这种无意义的事情。
import torch.nn as nn from transformers import BertModel from torchcrf import CRF class BertNER(nn.Module): def __init__(self, bert_pretrained="bert-base-chinese", num_labels=13, use_crf=True): super().__init__() self.bert = BertModel.from_pretrained(bert_pretrained) self.dropout = nn.Dropout(0.1) self.classifier = nn.Linear(self.bert.config.hidden_size, num_labels) self.use_crf = use_crf if use_crf: self.crf = CRF(num_labels, batch_first=True) def forward(self, input_ids, attention_mask, labels=None): outputs = self.bert(input_ids=input_ids, attention_mask=attention_mask) seq_output = outputs.last_hidden_state # [batch, seq_len, 768] logits = self.classifier(self.dropout(seq_output)) # [batch, seq_len, num_labels] if labels is not None: if self.use_crf: # CRF要求mask是bool类型 mask = attention_mask.bool() loss = -self.crf(logits, labels, mask=mask, reduction="mean") else: loss_fct = nn.CrossEntropyLoss(ignore_index=-100) loss = loss_fct(logits.view(-1, logits.shape[-1]), labels.view(-1)) return loss, logits else: if self.use_crf: pred = self.crf.decode(logits, mask=attention_mask.bool()) return pred # list of lists return torch.argmax(logits, dim=-1)CRF那部分用到了torchcrf库，它在PyTorch 2.x下需要装个小补丁，否则decode时会报TypeError。具体在第5章避坑里讲。训练时优化器我用AdamW，BERT部分的学习率2e-5，分类层和CRF层的参数如果共用同一个学习率，会出现loss在某个step突然变成nan的情况，所以一般把分类层和CRF层单独设成1e-4。
4. 训练参数怎么调：从学习率到类别不均衡的处理
4.1 核心参数的推荐范围与调节优先级
BERT微调有一个很反直觉的地方：学习率大了必炸，小了收敛慢到怀疑人生。我一般用2e-5到5e-5之间，分类层（和CRF层）用1e-4到3e-4。优化器选AdamW，权重衰减0.01。warmup比例0.1，意思是前10%的step学习率从0线性升到设定值，用来避开预训练权重和任务头之间巨大的梯度差异。
batch size在BERT里特别吃显存，我是这么判断：电子病历文本的max_len是256，NVIDIA RTX 3090（24GB）能跑batch size=32，V100（16GB）只能到16，如果有两块卡就梯度累积。别硬塞到OOM，PyTorch的显存碎片问题在BERT上被放大得很厉害，一次性申请超出显存直接报错还难恢复。
training_args = { "learning_rate": 2e-5, # BERT主干 "head_learning_rate": 1e-4, # 分类层 / CRF "weight_decay": 0.01, "batch_size": 16, "max_epochs": 5, "warmup_ratio": 0.1, "max_grad_norm": 1.0, "scheduler": "linear", }参数调节顺序我给一个实用策略：先固定epoch=5、batch size=16，把learning_rate从5e-5往下降，每次减半跑2个epoch观察loss曲线；再撞一次batch size，最后看warmup。我见过有人在batch size=8和32之间切换，F1掉1.5个点，这个指标属于正常波动，不用焦虑。
4.2 类别不均衡：被“O”淹没的正样本
一个典型的电子病历数据集里，O标签占比可能高达85%~90%。这个比例下模型很狡猾——全部预测O就能拿到85%的token级准确率。所以评估时我不看accuracy，只看precision、recall和F1，并且必须用span级别的F1（实体级别的F1），不能看token级别。span级F1的计算方法是用seqeval库，它要求预测和标注都是实体级别的格式（['B-SYMPTOM', 'I-SYMPTOM'] 这种列表被它融合成 ['SYMPTOM'] 的span，然后比较起始位置）。
针对不均衡我有两个常用手段。第一是在Loss里给实体类（非O）更高的权重，CrossEntropyLoss的weight参数设为[1.0, 5.0, 5.0, ...]，O标签保持1.0。第二种是数据层面的做法：将长文本切段后做去重，让正样本的比例控制在15%到30%之间，这个方法对F1的影响比调loss权重更明显。
4.3 验证集划分与早停技巧
电子病历数据有很强的病人级别聚类效应——同一个病人的多段病历高度相似，如果按句随机划分，验证集会泄露大量同源信息，导致F1虚高3~5个点。正确做法是按病人ID分桶切分，训练集、验证集、测试集分别落在不同病人上。源码包里我一般会专门留一个split_by_patient的脚本，这是内部验收时被问最多的事情，因为很多团队是从公开数据集跑通模型再上自己的病历，分错组对效果评估是致命的。
早停我设置在验证集span级F1连续3个epoch不上升时触发。注意早停的patience参数不能设成1，BERT微调时F1曲线是波动上升的，epoch 2稍降、epoch 3又回来了是常态。
5. 电子病历 NER 的五条踩坑记录：现象、原因与解决
5.1 token对齐错位：[UNK]把标签序列打乱
现象：训练loss能降，但验证时所有实体都预测错位一个字符，或者某些标签完全预测不出来。
原因：病历里的生僻字、特殊符号（如±、②）在bert-base-chinese词表里不存在，被tokenize成[UNK]。我2.3节的align_labels_with_tokens里虽然对[UNK]做了处理，但如果你在数据预处理时不检查[UNK]的出现位置，char_idx游标会多发一位，导致后续所有token的标签错位。
解决：在构造数据集时统计[UNK]的占比，超过0.5%就单独打印这些样本的原文和token结果。如果有大量[UNK]，不要硬用bert-base-chinese，可以换更大的中文医疗预训练模型，它们词表更大。另一个思路是先把特殊符号替换成[unused1]，再fine-tune时把[unused1]当作一个普通token，让BERT自己学它的语义。
5.2 全角/半角混用导致实体边界被割裂
现象：同一个实体“右上腹”在训练集里是全角，在测试集里变成半角，模型有时识别为两个实体。
原因：电子病历录入时输入法状态不稳定，全角半角混用极其常见。“3.5cm”的“.”可能是全角“．”。BERT的tokenizer对全角和半角字符是区别对待的，同一含义的字符被映射到完全不同的embedding，模型学不到它们的等价性。
解决：数据预处理时统一做全角转半角，Python的str.maketrans把全角ASCII对应范围映射回半角即可。注意全角空格\u3000要单独处理成半角空格。做完之后检查一遍实体边界，确认没有因角转换产生新的切分问题。
5.3 CRF层的loss突然变成nan或者长时间不降
现象：BERT层用2e-5正常收敛，但加了CRF后第一个epoch loss就在0.5附近震荡，甚至某个step直接nan。
原因：还是学习率的问题，但不动脑的人会把锅甩给CRF“不稳定”。实际情况是CRF层的转移矩阵参数初始化范围比BERT输出大，同样的学习率下，CRF层的参数更新幅度远高于BERT层，导致转移矩阵出现极端值，解码时所有路径的得分都变成-1e8级别的数，exp之后就是nan。
解决：把CRF参数从主优化器里摘出来单独设学习率，官方一点的说法是参数分组（parameter groups）。我一般这样处理：optimizer = AdamW([{"params": bert.parameters(), "lr": 2e-5}, {"params": classifier.parameters(), "lr": 1e-4}, {"params": crf.parameters(), "lr": 1e-3}])。如果还nan，把max_grad_norm从1.0降到0.5。
5.4 长文本截断切掉实体尾巴
现象：一条记录明明有“胃镜检查提示慢性萎缩性胃炎”，模型只抽出了“胃镜”，后半截全丢了。模型不是笨，是max_len=256直接从第256个token处硬截断了。
原因：电子病历的“现病史”和“既往史”边界恰好落在256个token附近，把实体切断了。由于我采用的是简单截断策略，被切断的地方变成半个实体，模型的CRF（或softmax）无法判断这个残缺片段的类型。
解决：长文本按句子切分成多个窗口，每个窗口独立进模型，推理时再合并结果。窗口之间设置20~30个token的重叠（overlap）。这个方案在源码实现里就是多一层循环，但非常好用。如果不想写窗口逻辑，拆句器（按句号、分号切分）加简单的规则合并也可以。
5.5 torchcrf在PyTorch 2.x下的兼容性报错
现象：from torchcrf import CRF能过，但loss = -self.crf(logits, labels, mask=mask)报TypeError: 'ellipsis' object is not subscriptable。
原因：torchcrf内部使用了mask[...]的写法，PyTorch 2.x对ellipsis的运算规则做了更严格的检查，旧库没跟上。这是源码复现时最容易让新手卡住的兼容性问题，Google搜出来的中文论坛答案甚至会让降到PyTorch 1.x，不必那么折腾。
解决：两个选择。一是pip install pytorch-crf，它维护更新，接口几乎一样；二是干脆不用第三方CRF库，自己手写CRF的前向后向算法，代码量百来行，但把对数域的exp、log、mask细节处理好还是有点门槛的。新手建议用pytorch-crf，省时省心。
6. 从源码跑通到能交付：用slide window推理和span-F1验收
模型训练完，最后一步是把验证集里表现最好的checkpoint拿出来做推理验证。推理有一个小而关键的技巧——长文本窗口重叠合并。我一般在max_len之外再设一个stride参数，取max_len的一半。窗口滑过去之后，每个token可能被预测多次，取多次预测中最常出现的标签作为最终结果。这样处理的代价是推理耗时翻倍，但span-F1能回升1.5%左右，对电子病历这种对精度要求苛刻的场景来说非常值得。如果硬要省这个时间，可以只在“有实体候选”的窗口间做合并，没候选的直接取第一个窗口结果。
def predict_long_text(model, tokenizer, text, max_len=256, stride=128): model.eval() tokens = tokenizer.tokenize(text) total_len = len(tokens) if total_len <= max_len - 2: # 正常推理 enc = tokenizer(text, max_length=max_len, truncation=True, return_tensors="pt") with torch.no_grad(): logits = model(**enc)[1] # 或 model.compute_logits(enc) pred = torch.argmax(logits, dim=-1)[0].cpu().numpy() return pred # 多窗口预测 + 投票 all_preds = [] for start in range(0, total_len, stride): end = min(start + max_len - 2, total_len) window_tokens = tokens[start:end] window_text = tokenizer.convert_tokens_to_string(window_tokens) enc = tokenizer(window_text, max_length=max_len, truncation=True, return_tensors="pt") with torch.no_grad(): logits = model(**enc)[1] pred = torch.argmax(logits, dim=-1)[0].cpu().numpy() # 第一个token是CLS，去掉 all_preds.append((start, pred[1:end-start+1])) # 合并重叠区域（简化：取每个token第一次出现的预测） final = ["O"] * total_len for start, pred in all_preds: for i, p in enumerate(pred): if start + i < total_len: if final[start + i] == "O": final[start + i] = p return final验证时一定要用seqeval库算span级的P/R/F1，不要盯着token accuracy。seqeval要求输入是二维list（每个样本是list of strings），我用classification_report的先例比较少，通常直接调seqeval.metrics.performance_measure自己看数字。这里有个容易忽略的点：seqeval会把B-SYMPTOM和I-SYMPTOM自动拼成一个实体，但如果一个实体的内部标签切成了B-SYMPTOM、O、I-SYMPTOM，它会算两个实体，这正是我们要暴露给模型的问题。
最后一个经验，也是我吃过大亏的地方：不要只用公开数据集验证。公开的医疗NER数据集（如IMCS、CMeEE）清洗得比较干净，科室分布均衡，格式统一，模型在这些集上的F1在85%以上很正常，但一上真实病历就会掉到70%甚至更低。主要原因是真实文本里有大量口头表达、错别字、不规范缩写，标注规范的公开数据样本无法覆盖。我现在的习惯是：先拿公开数据跑通代码，再拿一个月真实病历（脱敏后）做二次标注和微调，最后交付的模型一定是两个阶段都完成的版本。这条路没有捷径，电子病历NER做好了是治病救人的基础设施，值得在这件事上花时间。希望帮到你。
本文还有配套的精品资源，点击获取
