简介这份源码面向医疗信息化开发者、自然语言处理学习者与科研人员提供一套基于BERT模型的电子病历命名实体识别完整实现用于从病历文本中抽取疾病、药物、治疗手段等关键实体支撑临床决策与医疗数据分析。资源包共38个文件约395KB以21个Python源码文件为核心覆盖模型定义、数据加载、训练与预测全流程另含txt数据与说明、xml配置、md文档、Jupyter Notebook实验笔记及许可证等目录结构清晰便于按模块阅读与二次开发。目前已有320人学习下载。读者可据此掌握BERT在医疗NER任务中的落地方式理解数据预处理、特征提取、模型训练与性能评估的完整链路并借助conlleval评价工具与预训练脚本快速复现实验适合作为课程设计、毕业项目或医疗AI研究的参考基线。1. 电子病历 NER 为什么绕不开 BERT一份能跑通的源码长什么样电子病历里塞满了疾病、药物、手术、检查这类实体但写法极其随意——“2型糖尿病”可能写成“T2DM”“阿司匹林”可能写成“拜阿司匹林”同一个词在不同科室还有不同缩写。传统 CRF 或者 BiLSTM-CRF 靠词向量和人工特征遇到这种缩写、嵌套、长距离依赖就翻车。这份源码把 BERT 预训练语言模型直接接到 NER 任务上用run_classifier.py的思路改造成序列标注配合conlleval做标准评估从train.txt、dev.txt、test.txt三份数据一路走到predict.py输出实体。它适合两类人一是想拿电子病历做科研或课程设计的学生需要一份结构完整、能改能跑的基线二是医疗 NLP 方向的一线开发想快速验证 BERT 在自己数据上的上限。整个工程 39 个文件核心逻辑集中在model.py、utils.py、loader.py、train.py、predict.py这五个 Python 文件里BERT 官方代码作为子模块放在根目录不依赖 pip 安装的 transformers改起来更直接。2. 拆开工程看数据流从loader.py到conlleval的完整链路2.1 数据格式与loader.py的读取逻辑电子病历 NER 的数据通常按 CoNLL 格式组织每行一个 token 加标签空行分隔句子。这份源码的data目录下train.txt、dev.txt、test.txt就是这种结构。loader.py负责把文本转成 BERT 需要的input_ids、input_mask、segment_ids同时把标签映射成 id。关键点在于标签体系常见做法是B-DIS、I-DIS、B-DRU、I-DRU、O源码里用label2id和id2label两个字典维护。我一般会先跑一遍loader.py里的read_data函数确认句子数和标签分布避免后面训练时发现某个实体类别样本极少导致 F1 为 0。# loader.py 中读取 CoNLL 格式的核心逻辑示意 def read_data(file_path): sentences [] labels [] with open(file_path, r, encodingutf-8) as f: tokens [] tags [] for line in f: line line.strip() if not line: # 空行表示句子结束 if tokens: sentences.append(tokens) labels.append(tags) tokens, tags [], [] continue parts line.split() tokens.append(parts[0]) tags.append(parts[-1]) return sentences, labels这段代码的逻辑很直白按空行切句每行取第一个字段为 token、最后一个字段为标签。参数上要注意encodingutf-8电子病历里常有中文和特殊符号用默认编码会直接报UnicodeDecodeError。另外如果数据里用空格分隔而 token 本身含空格需要改成制表符分隔否则标签会对齐错位。2.2model.py里的 BERT 微调结构model.py定义了一个BertNER类继承 BERT 的BertModel在[CLS]对应的输出后面接一个全连接层输出维度等于标签数量。前向传播时取output_layer[:, 1:-1, :]去掉[CLS]和[SEP]再算交叉熵损失。这里有个容易忽略的参数max_seq_length。电子病历句子长度差异大设 128 可能截断长句设 512 又吃显存。我一般先统计训练集 token 长度的 95 分位数再定这个值。源码里默认在train.py的FLAGS里配置改的时候要同步改loader.py里的 padding 逻辑否则 mask 对不上。# model.py 中 NER 头部的关键代码示意 class BertNER(nn.Module): def __init__(self, bert_config, num_labels): super().__init__() self.bert BertModel(bert_config) self.classifier nn.Linear(bert_config.hidden_size, num_labels) self.num_labels num_labels def forward(self, input_ids, input_mask, segment_ids, labelsNone): outputs self.bert(input_ids, attention_maskinput_mask, token_type_idssegment_ids) sequence_output outputs[0] # 去掉 [CLS] 和 [SEP] 对应的位置 sequence_output sequence_output[:, 1:-1, :] logits self.classifier(sequence_output) if labels is not None: loss_fct nn.CrossEntropyLoss() loss loss_fct(logits.view(-1, self.num_labels), labels.view(-1)) return loss, logits return logits参数说明bert_config.hidden_size通常是 768base 版num_labels等于实体标签总数。labels.view(-1)把 batch 和序列维度拉平这是 PyTorch 交叉熵的常规操作。如果显存不够把 batch size 降到 8 或 16同时梯度累积步数调大效果接近大 batch。2.3 训练入口train.py与评估工具conllevaltrain.py是主入口里面用tf.flags或argparse定义了一堆超参learning_rate、num_train_epochs、batch_size、do_train、do_eval。BERT 微调一般用 2e-5 到 5e-5 的学习率太大直接发散太小收敛慢。源码里默认 3e-5我试过在电子病历数据上 2e-5 更稳。训练完在dev.txt上跑评估conlleval脚本会输出 precision、recall、F1按实体类别分别统计。注意conlleval要求输入格式是token predicted_label true_label源码里utils.py有个write_eval_file函数负责拼这个格式如果自己改数据流这一步别漏。# 训练命令示例 python train.py \ --data_dir./data \ --bert_config_file./bert/bert_config.json \ --init_checkpoint./bert/bert_model.ckpt \ --output_dir./output \ --do_traintrue \ --do_evaltrue \ --max_seq_length128 \ --train_batch_size16 \ --learning_rate2e-5 \ --num_train_epochs3参数含义init_checkpoint指向预训练权重没有这个就是随机初始化F1 会低得离谱output_dir存 checkpoint 和评估结果num_train_epochs在电子病历小数据集上 3 到 5 就够再多容易过拟合。跑完看output/eval_results.txt如果某个实体类 F1 明显低于其他先查训练样本里该类数量再查标签是否写错。3. 避坑与排查电子病历 NER 训练中常见的五个翻车点3.1 标签体系不统一导致 F1 虚低现象训练 loss 正常下降但conlleval输出的 F1 只有 0.3 左右且B-DIS和I-DIS的召回率差异巨大。原因训练数据里同一实体在不同文件用了不同标签名比如B-Disease和B-DIS混用label2id把它们当成两个类。解决在loader.py里加一层标签归一化把所有别名映射到统一标签再重新生成label2id。我一般会先跑一个set(labels)把所有标签打印出来肉眼确认没有同义不同名的情况。3.2max_seq_length截断长病历导致实体丢失现象预测时某些长句里的实体完全识别不出来但短句正常。原因max_seq_length设了 128而电子病历里一段病程记录可能 300 多个 token截断后实体落在截断部分。解决统计训练集长度分布把max_seq_length调到 256 或 512同时把 batch size 减半。如果显存实在不够可以用滑动窗口切分长句预测时再合并结果但要注意实体跨窗口的边界处理。3.3 学习率过大导致 loss 震荡不收敛现象训练前几个 step loss 从 2.3 跳到 8.7 再跳回来一直不下降。原因BERT 微调对学习率极其敏感源码默认 3e-5 在某些数据上偏大。解决降到 2e-5 或 1e-5同时加 warmup前 10% 的 step 线性增加学习率。如果还震荡检查init_checkpoint是否加载成功有时候路径写错但代码不报错实际是随机初始化在跑。3.4conlleval格式不对导致评估报错现象训练完跑评估conlleval输出Error: invalid format或者直接空结果。原因utils.py里拼评估文件的顺序是token true_label predicted_label而conlleval默认期望token predicted_label true_label。解决打开conlleval脚本看它读的是哪两列调整write_eval_file里的写入顺序。这个坑很隐蔽因为训练本身不报错只有评估阶段才暴露。3.5 中文 token 被拆成单字导致实体边界模糊现象模型把“阿司匹林肠溶片”识别成“阿司匹林”和“肠溶片”两个实体或者只识别出“阿司匹林”。原因BERT 中文版按字切分tokenization.py里FullTokenizer对中文逐字处理实体边界依赖模型自己学。解决在数据预处理阶段加入词典特征或者换用 BERT-wwm 整词掩码版本。源码里tokenization.py是官方实现改的时候注意do_lower_case参数中文场景设 False。4. 从predict.py到自定义数据把模型用起来的三个关键操作4.1 用predict.py跑单句推理predict.py加载训练好的 checkpoint对输入句子做 tokenize、padding、前向传播再根据id2label还原标签序列。关键参数是--output_dir要指向训练时保存的目录里面得有model.ckpt或pytorch_model.bin。我一般会先用sample_text.txt里的样例跑一遍确认输出格式是token label对再换自己的病历文本。# predict.py 中推理的核心步骤示意 def predict(text, model, tokenizer, id2label, max_seq_length128): tokens tokenizer.tokenize(text) tokens [[CLS]] tokens [[SEP]] input_ids tokenizer.convert_tokens_to_ids(tokens) input_mask [1] * len(input_ids) segment_ids [0] * len(input_ids) # padding while len(input_ids) max_seq_length: input_ids.append(0) input_mask.append(0) segment_ids.append(0) input_ids torch.tensor([input_ids]) input_mask torch.tensor([input_mask]) segment_ids torch.tensor([segment_ids]) with torch.no_grad(): logits model(input_ids, input_mask, segment_ids) preds torch.argmax(logits, dim-1).squeeze().tolist() # 去掉 [CLS] 和 [SEP] 对应的预测 preds preds[1:len(tokens)-1] return list(zip(tokens[1:-1], [id2label[p] for p in preds]))逻辑说明先 tokenize 再加特殊符号padding 到固定长度前向传播后取 argmax。注意preds要截掉[CLS]和[SEP]的位置否则标签和 token 对不齐。如果预测结果全是O先检查 checkpoint 是否加载成功再检查id2label映射是否和训练时一致。4.2 替换成自己的电子病历数据源码自带的data目录是示例数据换成自己的病历需要三步第一把病历文本按 CoNLL 格式标注每行token 标签空行分句第二更新label2id和id2label确保标签集合和标注一致第三重新跑train.py把--data_dir指向新数据目录。标注工具常见的是 brat 或 doccano导出后写个脚本转 CoNLL。我一般会留 10% 做测试集不参与训练只在最后评估用。4.3 用conlleval做类别级评估conlleval的输出不只是总体 F1还有每个类别的 precision、recall、F1。电子病历 NER 里疾病和药物通常 F1 较高手术和检查因为样本少可能偏低。看评估结果时先关注召回率低的类别再查训练样本是否足够。如果某个类别 F1 为 0大概率是标签写错或者样本数为 0。源码里conlleval是 Perl 脚本Linux 和 macOS 直接跑Windows 需要装 Perl 环境或者用 Python 版conlleval.py替代。评估指标含义关注点Precision预测为某类的实体中真正属于该类的比例低 precision 说明误报多Recall真实某类实体中被正确预测的比例低 recall 说明漏报多F1Precision 和 Recall 的调和平均综合指标低于 0.7 需排查Support该类真实实体数量数量少于 50 时 F1 波动大5. 进阶技巧用extract_features.py做实体嵌入与错误分析extract_features.py是 BERT 官方代码里用来提取隐层向量的脚本很多人直接忽略但它对 NER 错误分析非常有用。具体做法把dev.txt里预测错误的句子挑出来用extract_features.py提取每个 token 的最后一层向量然后算错误实体和正确实体之间的余弦相似度。如果相似度很高但标签不同说明模型学到了相近表示但分类边界没学好可以考虑加 CRF 层或者调整标签权重。如果相似度很低说明模型根本没学到该类实体的特征需要检查训练样本是否足够或者 tokenization 是否把关键字符切碎了。# 提取 dev 集特征向量 python extract_features.py \ --input_file./data/dev.txt \ --output_file./output/dev_features.jsonl \ --vocab_file./bert/vocab.txt \ --bert_config_file./bert/bert_config.json \ --init_checkpoint./output/model.ckpt \ --layers-1 \ --max_seq_length128 \ --batch_size8参数--layers-1表示取最后一层也可以取-2或-3看不同层的表示质量。输出是 JSONL 格式每行一个 token 的向量。我一般会写个 Python 脚本读这个文件把预测错误的实体对找出来算平均余弦相似度。如果某个类别的错误实体相似度普遍高于 0.9说明模型区分不开这时候加 CRF 或者换用BERT-wwm往往能提升几个点。另一个技巧是用predict.py的输出做混淆矩阵看哪些类别之间互相误判最多比如“疾病”和“症状”经常混那就需要在标注规范里把边界定义清楚。从那以后我每次跑 NER 实验都会先用extract_features.py抽一遍 dev 集特征把错误样本的向量相似度算出来再决定下一步是调模型还是调数据。这个习惯帮我省了很多盲目调参的时间。希望帮到你。本文还有配套的精品资源点击获取