BERT-MRC中文命名实体识别源码实战：从训练到评估全流程解析

简介这份资源面向自然语言处理方向的学生与开发者提供一套基于BERT-MRC机器阅读理解范式实现中文命名实体识别的完整源码与配套数据适合用作课程设计、期末大作业或入门序列标注任务的实战参考。压缩包共23个文件以15个Python脚本为核心涵盖模型定义、数据加载、预处理、训练与测试、实体抽取及MRC评估指标等模块另含4个txt说明与占位文件、4个pyc缓存文件整体约39KB结构清晰便于按模块阅读。资源已积累302人学习下载说明其在同类课程项目中具有一定参考价值。读者可借此理解将命名实体识别转化为阅读理解问答的思路掌握扁平与嵌套实体F1评估、tokenization处理及预测流程并可直接运行验证省去从零搭建的调试成本。1. 从一句“模型跑不动”说起这份 BERT-MRC 中文 NER 源码到底能干什么如果你做过中文命名实体识别大概率经历过这种场面CRF 序列标注的代码跑通了但一遇到嵌套实体、长实体、实体边界模糊的句子F1 就往下掉调参调到怀疑人生。这份python实现基于bert-mrc的中文命名实体识别源码全部数据.zip走的是另一条路——把 NER 从“逐字打标签”改成“阅读理解式问答”也就是 MRCMachine Reading Comprehension框架。它把“找出文本里所有的人名/地名/机构名”变成“回答‘文本中的人名是什么’这个问题”用 BERT 的问答头去预测 span 起止位置。对正在做课程设计、期末大作业或者想找一个能直接跑通、结构清晰的中文 NER 基线的人来说这份源码的价值在于目录完整、训练/预测/评估脚本齐全、自带数据处理和 span 级 F1 计算不用自己从零搭评估逻辑。它适合已经会 Python、装过 PyTorch 和 transformers但不想在数据格式和评估指标上反复踩坑的从业者。2. BERT-MRC 做 NER 的原理与这份源码的目录拆解2.1 为什么用 MRC 而不是序列标注传统 NER 用 BIO/BIOES 标签本质是给每个 token 分类。问题在于标签之间没有显式建模实体边界嵌套实体几乎没法处理而且标签体系一换就要重做数据。MRC 的思路是把查询query拼到原文前面比如“找出文中的人名张三在北京大学读书”让 BERT 去预测答案在原文中的 start/end 位置。这样每个实体类型对应一个 query实体识别变成 span 抽取天然支持嵌套也方便做 zero-shot 迁移——换实体类型只改 query 模板。这份源码里model.py就是干这个的BERT 编码[CLS] query [SEP] text [SEP]然后在 text 部分接一个 span 预测头输出每个位置作为 start 和 end 的 logits。mrc_utils.py负责把原始标注转成 MRC 格式的样本data_loader.py做 batch 组织。评估部分没有用常见的 seqeval而是自己实现了flat_span_f1.py和nest_span_f1.py分别算扁平实体和嵌套实体的 F1mrc_ner_evaluate.py做统一入口。这个设计比直接调库更透明也方便你改指标。2.2 目录结构与各文件职责拿到压缩包后先别急着python train.py。花五分钟把目录过一遍后面排错会快很多。核心文件分布如下文件/目录作用是否要改train.py训练入口读配置、建模型、跑 epoch改路径和超参predict.py单句/批量预测输出实体改输入文本test.py加载 checkpoint 做测试集评估改模型路径model.pyBERT span 头的网络定义一般不动data_loader.pyDataset 和 collate 逻辑按数据格式微调prepocess.py原始数据转 MRC 样本注意文件名拼写mrc_utils.pyquery 模板、span 对齐工具改实体类型时动tokenization.py中文分词/字级 tokenize一般不动get_entity.py从预测 span 还原实体文本一般不动metric/flat/nest span F1 计算评估逻辑pretrained_model/放 BERT 权重必须放data/训练/测试数据按格式放output/模型保存目录自动生成注意prepocess.py这个拼写不是preprocess.py导入的时候别写错否则会报ModuleNotFoundError。这是血泪经验我第一次跑就卡在这。2.3 环境依赖与版本选择这份代码基于 PyTorch 和 transformers常见做法是 Python 3.8 torch 1.10 左右 transformers 4.x。不建议上太新的 transformers因为BertModel的返回结构在 4.30 之后有细微变化老代码里如果直接取outputs[0]可能还能跑但取outputs.last_hidden_state之外的东西容易翻车。安装命令# 建议先建虚拟环境避免和系统包冲突 python -m venv venv_ner source venv_ner/bin/activate # Windows 用 venv_ner\Scripts\activate # 安装核心依赖版本不要盲目追新 pip install torch1.10.0 pip install transformers4.10.0 pip install numpy tqdm参数说明torch版本和 CUDA 驱动要对上如果你用 CPU 跑装 CPU 版即可transformers选 4.10 是因为这份代码的tokenization.py里用了BertTokenizer的老接口新版本虽然兼容但 warning 很多。装完后python -c import torch; print(torch.cuda.is_available())确认 GPU 可用。3. 从零跑通训练数据准备、query 构造与 train.py 参数3.1 数据格式与 MRC 样本构造这份源码的data/目录下通常放的是 JSON 或 BIO 格式的标注数据。prepocess.py会把每条样本转成 MRC 格式对每个实体类型生成一个 query比如“找出文中的人名”然后把 query 和原文拼起来标注答案的 start/end 在原文中的位置。核心逻辑是先定位实体在原文的字符级 span再映射到 tokenizer 后的 token 级 span。中文如果按字切基本一一对应如果按词切就要处理 offset 对齐。常见做法是直接用字级 tokenize避免分词带来的边界问题。tokenization.py里如果用的是BertTokenizer的tokenize中文会被拆成单字这样 span 对齐最简单。如果你换成BertTokenizerFast可以用return_offsets_mappingTrue拿到字符偏移更稳。改数据时注意query 模板要和实体类型一一对应mrc_utils.py里一般有个query_list或label_list加类型时两处都要改。3.2 train.py 关键参数逐项说明train.py是训练入口里面通常有一堆 argparse 参数。不要直接默认跑先看清楚每个参数的含义# train.py 中常见的参数定义示意以实际代码为准 parser.add_argument(--data_dir, default./data, typestr) # 数据目录 parser.add_argument(--bert_dir, default./pretrained_model, typestr) # BERT 权重路径 parser.add_argument(--max_seq_len, default128, typeint) # 最大序列长度 parser.add_argument(--batch_size, default16, typeint) # 批大小 parser.add_argument(--lr, default2e-5, typefloat) # 学习率 parser.add_argument(--epochs, default10, typeint) # 训练轮数 parser.add_argument(--output_dir, default./output, typestr) # 模型保存路径参数说明max_seq_len要覆盖 query 原文的总长度中文 NER 句子一般不长128 够用但如果你数据里有长文档要加到 256 或 512注意显存。batch_size在 8G 显存上 16 比较稳OOM 就降到 8。lr用 2e-5 是 BERT 微调的经典值太大容易震荡太小收敛慢。epochs看数据量几千条样本 10 轮左右观察验证集 F1 不再涨就可以停。3.3 启动训练与日志观察确认pretrained_model/下已经放好 BERT 的pytorch_model.bin、vocab.txt、config.json然后启动# 训练命令注意路径和实际代码保持一致 python train.py \ --data_dir ./data \ --bert_dir ./pretrained_model \ --max_seq_len 128 \ --batch_size 16 \ --lr 2e-5 \ --epochs 10 \ --output_dir ./output跑起来后重点看三处loss 是否稳定下降、验证集 F1 是否在涨、有没有出现lossnan。如果 loss 一开始就 nan多半是学习率太大或者数据里有空 span如果 F1 一直不涨检查 query 模板和标签是否对得上。训练完output/下会存pytorch_model.bin和config.json后面预测和测试都用它。4. 预测与评估predict.py 推理、span 还原与 F1 计算4.1 用 predict.py 做单句推理训练完最想干的事就是拿一句话试试。predict.py一般会加载 checkpoint对输入文本跑一遍模型输出实体列表。典型用法# 单句预测具体参数名以代码为准 python predict.py \ --model_dir ./output \ --bert_dir ./pretrained_model \ --text 张三在北京大学读书后来去了阿里巴巴输出可能是{人名: [张三], 机构名: [北京大学, 阿里巴巴]}这样的结构。如果输出为空先确认max_seq_len和训练时一致再确认 query 模板没变。get_entity.py负责把 start/end logits 解码成 span常见做法是取 start 和 end 概率都超过阈值的组合再过滤掉 start end 的非法 span。阈值一般设 0.5太低会出很多碎片实体太高会漏。4.2 flat_span_f1 与 nest_span_f1 的区别评估是这份源码比较扎实的地方。flat_span_f1.py算的是扁平实体 F1预测的 span 和标注 span 完全一致才算对部分重叠不算。nest_span_f1.py算嵌套实体允许一个 span 包含另一个 span分别匹配。mrc_ner_evaluate.py把两者串起来输出 precision、recall、F1。为什么要分开因为很多 NER 数据集只标扁平实体用 nest 评估会虚高而有些场景比如“北京大学”里嵌套“北京”必须用 nest。跑评估# 测试集评估加载训练好的模型 python test.py \ --model_dir ./output \ --data_dir ./data \ --bert_dir ./pretrained_model看结果时注意如果 flat F1 高但 nest F1 低说明模型对嵌套结构学得不好可以加 query 类型或增加嵌套样本。如果两者都低先查数据预处理有没有把 span 对齐错。4.3 评估指标异常时的排查顺序F1 出来不对劲按这个顺序查第一看data/里的测试集和训练集有没有重叠重叠会导致虚高第二看prepocess.py生成的 MRC 样本里 start/end 是否落在原文范围内越界说明 offset 算错第三看metric/里的匹配逻辑是不是大小写敏感、是否去空格中文一般没这问题但标点符号可能影响第四看模型是不是加载了未训练的权重output/下如果只有 config 没有 bin评估就是随机结果。这四步走完基本能定位到问题。5. 避坑与常见问题那些让我重跑三次的细节5.1 现象ModuleNotFoundError: No module named prepocess原因文件名拼写是prepocess.py而不是preprocess.py导入时写错或者 IDE 自动补全成正确拼写。解决统一用from prepocess import ...或者把文件名改成preprocess.py并同步改所有 import。我一般不改名避免和说明文档不一致。5.2 现象训练 loss 正常但预测全是空原因max_seq_len在预测时和训练时不一致导致 query 被截断模型看不到实体类型。解决把predict.py里的max_seq_len改成和train.py一样或者把训练时的参数存进 config 一起加载。5.3 现象CUDA out of memory原因batch_size太大或max_seq_len太长。解决先降 batch 到 8再降 seq_len 到 64 试跑确认能跑通再逐步加。如果还是 OOM检查是不是在 CPU 上跑却加载了 GPU 权重用map_locationcpu。5.4 现象F1 计算报 span 越界原因prepocess.py里字符级 span 映射到 token 级时没有考虑[CLS]、[SEP]和 query 占用的位置导致 start/end 偏移。解决在mrc_utils.py里打印几个样本的start_ids、end_ids和原文对照确认偏移量。常见做法是记录 query 长度span 位置加上 query 长度再加特殊 token 数。5.5 现象换了自己的数据后评估指标为 0原因实体类型和 query 模板没对上或者数据格式不是代码预期的 JSON 结构。解决先拿源码自带的数据跑通确认流程没问题再按同样格式替换。mrc_utils.py里的label_list要和你的实体类型完全一致多一个空格都会导致 query 匹配失败。6. 进阶技巧把这份源码改成你自己的 NER 项目跑通只是第一步真正要用起来得会改。第一个技巧是自定义 query 模板。mrc_utils.py里通常有个字典把实体类型映射到 query比如{PER: 找出文中的人名, LOC: 找出文中的地名}。你可以改成更细的模板比如“文中提到的组织机构有哪些”实测对边界模糊的实体有提升。改完记得同步改label_list和评估时的类型映射。第二个技巧是处理长文本。BERT 最大 512超过就要切窗。常见做法是按句切分每句单独预测再合并或者用滑动窗口加重叠。这份源码默认按max_seq_len截断长文档会丢实体。我一般会在data_loader.py里加一个切窗逻辑把长文本切成多个 chunk每个 chunk 保留 50 token 重叠预测完再去重合并。第三个技巧是换预训练模型。pretrained_model/里放的是通用 BERT如果你做医疗 NER换成bert-base-chinese在医疗语料上继续预训练的版本F1 通常能涨几个点。换模型时注意 vocab 是否一致不一致要重新 tokenize 数据。加载时用BertModel.from_pretrained(bert_dir)bert_dir指向新模型目录即可。第四个技巧是导出 ONNX 做推理加速。训练完的 PyTorch 模型可以用torch.onnx.export导出然后用 onnxruntime 跑CPU 上也能到毫秒级。导出时注意把input_ids、attention_mask、token_type_ids作为输入动态轴设好 batch 和 seq_len。导出后拿几条样本对比 ONNX 和 PyTorch 的输出确保数值一致再上线。最后一个习惯每次改完数据或 query先跑test.py看 F1再跑predict.py看几个具体例子。只看指标容易被虚高骗看例子才能发现“把‘北京’识别成机构名”这种低级错误。从那以后我每次换数据集都强制先跑一遍自带数据确认环境没问题再动自己的数据。希望帮到你。本文还有配套的精品资源点击获取