简介本资源为基于Python的实体关系抽取系统源码包面向自然语言处理学习者、知识图谱构建开发者及参加相关算法竞赛的选手重点解决从非结构化文本中自动提取实体与关系、支撑高端装备制造领域知识图谱自动化构建的问题。压缩包共22个文件以8个py脚本、12个json数据与配置、1个txt词表及1个md说明为主整体约1.97MB涵盖数据加载、模型定义、训练入口与预测推理等模块。项目以BERT预训练模型为核心通过gpNet.py搭建实体关系抽取网络配合dataloader.py与datagen系列脚本完成数据生成与批处理并引入FGM对抗训练和EMA参数平滑更新策略以增强模型鲁棒性与训练稳定性。已有208人学习读者可据此掌握从数据准备、模型训练到结果提交的完整流程理解对抗训练与参数平滑在关系抽取任务中的落地方式并参考目录结构快速复现与二次开发。1. 从一份 Python 实体关系抽取系统源码说起它到底能抽出什么一份标注为「基于 Python 的实体关系抽取系统」的源码包通常不是单一脚本而是一套把「原始句子 → 实体识别 → 关系分类 → 结构化三元组」串起来的工程骨架。它要解决的问题很具体给你一段中文或英文文本自动找出里面的人名、机构、时间、地点等实体再判断这些实体之间是什么关系比如「某公司的 CEO 是谁」「某药物对某疾病有什么作用」。这类系统在知识图谱构建、舆情监控、金融公告解析、医疗病历结构化里都是刚需也是很多 Python 入门到进阶的必经项目。如果你手里正好有这样一份源码或者准备自己搭一套最关心的无非三件事跑起来要装什么、数据从哪来、关系抽不准时怎么调。这篇笔记就按这个顺序拆把源码里常见的模块结构、训练流程、参数含义和翻车点讲清楚。适合已经会写 Python、想把这个方向真正落地的人也适合拿它当课程设计或毕设底稿的读者。下面所有命令和配置都按「能复现」的标准写不堆概念。2. 拆开源码目录实体关系抽取系统一般由哪几块拼成拿到一个压缩包先别急着pip install。实体关系抽取系统的源码结构往往比普通爬虫复杂因为它同时包含数据处理、模型定义、训练循环和推理接口。先看清目录能省掉后面一半的报错排查时间。2.1 典型目录结构与各模块职责常见的 Python 实体关系抽取项目目录大致长这样不同作者命名略有差异但职责基本一致relation-extraction/ ├── config/ # 配置文件模型超参、路径、标签映射 ├── data/ # 原始语料、标注文件、预处理后的中间文件 ├── models/ # 模型定义如 BiLSTMAttention、BERTSoftmax ├── utils/ # 数据加载、分词、评估指标、日志 ├── train.py # 训练入口 ├── predict.py # 推理入口 ├── evaluate.py # 评估脚本 └── requirements.txt # 依赖清单config/里通常有一个config.py或*.yaml里面写着max_seq_len、batch_size、learning_rate、num_relations这些关键参数。data/下一般会有train.txt、dev.txt、test.txt格式多为「句子 实体对 关系标签」。models/是核心决定这套系统是走传统 BiLSTM 路线还是 BERT 微调路线。utils/里的评估脚本往往被忽略但它决定了你后面怎么判断模型到底有没有变好。提示先打开requirements.txt和config确认作者用的框架版本。很多「跑不起来」的根源是 PyTorch 或 transformers 版本和代码不匹配而不是代码本身有问题。2.2 数据格式实体关系抽取的输入长什么样实体关系抽取的数据标注格式直接决定你后面能不能换自己的数据。常见的有两种一种是「句子级 实体位置 关系标签」另一种是「三元组列表」。下面是一个典型的 JSON 行格式示例{ text: 张三于2019年加入阿里巴巴担任首席技术官。, entities: [ {id: 0, type: Person, start: 0, end: 2, mention: 张三}, {id: 1, type: Org, start: 8, end: 12, mention: 阿里巴巴}, {id: 2, type: Title, start: 15, end: 20, mention: 首席技术官} ], relations: [ {head: 0, tail: 1, type: 任职于}, {head: 0, tail: 2, type: 担任} ] }text是原始句子entities里用start和end标出实体在句子中的字符位置relations用实体 id 表示头尾实体和关系类型。这种格式的好处是实体和关系解耦方便先做实体识别再做关系分类。如果你的源码用的是「头实体 尾实体 关系」的扁平格式转换时要注意字符偏移量中文按字符算英文按 token 算混用会直接导致实体错位。2.3 环境安装把依赖装到能跑通的最小集合在动手训练之前先把环境跑通。下面这套命令适用于大多数基于 PyTorch 的实体关系抽取源码Python 版本建议 3.8 到 3.10太新的版本有时会和旧版 transformers 冲突。# 创建独立环境避免污染系统 Python python -m venv re_env source re_env/bin/activate # Windows 用 re_env\Scripts\activate # 安装核心依赖版本按 requirements.txt 来这里给常见组合 pip install torch1.13.1 --index-url https://download.pytorch.org/whl/cu117 pip install transformers4.28.1 pip install numpy pandas scikit-learn tqdm # 验证 torch 是否能用 GPU python -c import torch; print(torch.__version__, torch.cuda.is_available())torch的版本要和你的 CUDA 驱动匹配cu117表示 CUDA 11.7。如果输出False说明 GPU 没被识别先别急着改代码去确认显卡驱动和 CUDA 版本。transformers负责加载预训练模型scikit-learn用来算 precision、recall、F1。装完后跑一遍python train.py --help能打印出参数说明说明入口脚本至少没语法错误。3. 把模型跑起来训练、推理与参数调整的完整链路环境通了接下来是让模型真正学起来。实体关系抽取的训练链路比普通分类多一层要先拿到实体表示再做关系分类。中间任何一步参数设错loss 都会不降或者直接 NaN。3.1 训练入口与关键参数含义大多数源码的train.py会暴露一批命令行参数下面这张表是必须看懂的几个参数常见取值作用与调整建议max_seq_len128 / 256句子截断长度中文长句建议 256短文本 128 够用batch_size16 / 32显存不够先降到 8再考虑换小模型learning_rate2e-5 / 1e-3BERT 微调用 2e-5BiLSTM 从零训练用 1e-3num_epochs10 / 30BERT 一般 3 到 5 轮就收敛BiLSTM 需要更多num_relations按标签数必须和你的关系类别数完全一致多一个少一个都报错启动训练的命令通常是这样python train.py \ --data_dir ./data \ --model_name bert-base-chinese \ --max_seq_len 256 \ --batch_size 16 \ --learning_rate 2e-5 \ --num_epochs 5 \ --save_dir ./checkpointsmodel_name指定预训练模型中文任务用bert-base-chinese英文用bert-base-uncased。save_dir是模型保存路径训练完会在里面生成pytorch_model.bin和config.json。如果显存报 OOM优先降batch_size其次降max_seq_len最后才考虑换更小的模型。3.2 关系分类头实体表示怎么拼进分类器关系分类的核心是把头实体和尾实体的表示拼在一起送进分类层。常见做法是「实体起始位置向量 实体结束位置向量 句子向量」拼接。下面是一段简化后的模型前向代码帮你理解源码里models/在干什么import torch import torch.nn as nn class RelationClassifier(nn.Module): def __init__(self, encoder, hidden_size, num_relations): super().__init__() self.encoder encoder # 头尾实体各取 start 和 end共 4 段拼上句子向量 self.classifier nn.Linear(hidden_size * 5, num_relations) self.dropout nn.Dropout(0.1) def forward(self, input_ids, attention_mask, head_start, head_end, tail_start, tail_end): outputs self.encoder(input_ids, attention_maskattention_mask) hidden outputs.last_hidden_state # [B, L, H] # 按位置取出实体表示这里用 gather 保证可导 h_start hidden[torch.arange(hidden.size(0)), head_start] h_end hidden[torch.arange(hidden.size(0)), head_end] t_start hidden[torch.arange(hidden.size(0)), tail_start] t_end hidden[torch.arange(hidden.size(0)), tail_end] sent hidden[:, 0] # [CLS] 作为句子表示 feat torch.cat([h_start, h_end, t_start, t_end, sent], dim-1) logits self.classifier(self.dropout(feat)) return logitshidden_size * 5对应四段实体向量加一段句子向量。head_start、head_end是实体在 token 序列里的下标不是字符下标预处理时要对齐。dropout设 0.1 是常规操作数据量小可以调到 0.3 防过拟合。如果源码里用的是平均池化而不是首尾拼接效果通常略差但训练更稳。3.3 推理与结果输出把模型变成能用的接口训练完只是第一步真正要用起来得靠推理脚本。下面这段代码展示如何加载 checkpoint 并对单句做预测from transformers import BertTokenizer, BertModel import torch tokenizer BertTokenizer.from_pretrained(bert-base-chinese) encoder BertModel.from_pretrained(bert-base-chinese) model RelationClassifier(encoder, hidden_size768, num_relations10) model.load_state_dict(torch.load(./checkpoints/pytorch_model.bin, map_locationcpu)) model.eval() text 张三于2019年加入阿里巴巴担任首席技术官。 inputs tokenizer(text, return_tensorspt, max_length256, truncationTrue) # 这里 head_start 等位置需要根据实体识别结果填入示例省略具体计算 with torch.no_grad(): logits model(inputs[input_ids], inputs[attention_mask], torch.tensor([1]), torch.tensor([2]), torch.tensor([8]), torch.tensor([9])) pred torch.argmax(logits, dim-1) print(预测关系类别:, pred.item())map_locationcpu保证没有 GPU 也能加载。model.eval()必须调用否则 dropout 会随机丢神经元同一句话每次预测结果都不一样。实体位置的计算要和训练时保持一致训练用 token 下标推理也必须用 token 下标这是最常见的翻车点之一。4. 避坑与排查实体关系抽取源码跑不通的 5 个真实原因这一章按「现象 → 原因 → 解决」写都是我在实际跑这类源码时踩过的坑。如果你正卡在某个报错上先对照这里排查比盲目改代码快得多。4.1 现象loss 一直是 nan训练几个 step 就崩原因通常是学习率太大或者数据里有空句子、实体位置越界。BERT 微调时用 1e-3 的学习率几乎必炸。解决方法是把learning_rate降到 2e-5同时在数据加载阶段加一层校验过滤掉head_start max_seq_len的样本。如果还不行检查标签里有没有负数或超出num_relations的值。4.2 现象实体位置对不上预测结果全是错的关系原因是字符下标和 token 下标混用。中文 BERT 的 tokenizer 会把一个词拆成多个 subword字符位置 8 对应的 token 位置可能是 6。解决办法是在预处理阶段就用 tokenizer 的offset_mapping把字符位置转成 token 位置并统一存进数据文件。推理时直接读 token 位置不要再做二次转换。4.3 现象训练集 F1 很高测试集一塌糊涂这是典型过拟合。原因可能是数据量太小、模型太大、没有加正则。解决方法是先加 dropout 和 weight decay再把num_epochs降下来用 early stopping 按验证集 F1 选最优 checkpoint。如果数据只有几百条建议先用 BiLSTM 而不是 BERT参数量小反而更稳。4.4 现象换自己的数据后标签映射报 KeyError原因是源码里的label2id是写死的你的关系类型和它不一致。解决办法是找到config或utils里的标签定义改成你自己的关系列表并确保num_relations同步更新。改完后清空旧的 checkpoint重新训练否则加载旧模型时分类层维度对不上。4.5 现象推理速度极慢一条句子要好几秒原因通常是每次推理都重新加载模型或者没有用torch.no_grad()。解决办法是把模型加载提到循环外面只加载一次推理时包在with torch.no_grad():里如果还是慢考虑把max_seq_len从 256 降到 128或者用 ONNX 导出后推理。CPU 上跑 BERT 本来就慢批量推理比单条循环快很多。5. 进阶技巧用规则兜底和阈值过滤把关系抽取的准确率再抬一截模型跑通之后真正决定这套系统能不能上线的往往不是模型本身而是后处理。我一般会在模型输出后面加两层一层是置信度阈值过滤一层是规则兜底。下面这段代码展示怎么把 softmax 概率和规则结合起来import torch.nn.functional as F def post_process(logits, text, head_mention, tail_mention, threshold0.6): probs F.softmax(logits, dim-1) conf, pred torch.max(probs, dim-1) if conf.item() threshold: return 无关系, conf.item() relation id2label[pred.item()] # 规则兜底如果头实体是人名、尾实体是机构且预测为「任职于」直接通过 if relation 任职于 and is_person(head_mention) and is_org(tail_mention): return relation, conf.item() # 规则否决头尾实体类型明显不匹配时降级 if relation 出生于 and not is_location(tail_mention): return 无关系, conf.item() return relation, conf.item()threshold设 0.6 是经验值数据干净可以降到 0.5噪声多就提到 0.7。is_person、is_org、is_location可以用实体识别模块的输出也可以维护一个小词典。规则兜底的好处是能把模型偶尔犯的明显错误拉回来代价是要维护规则表。我的习惯是先用模型跑一遍测试集把置信度在 0.5 到 0.7 之间的样本挑出来人工看根据错误模式再决定加哪些规则。另一个实用技巧是「关系方向校验」。很多关系是有方向的比如「任职于」是人对机构「成立于」是机构对时间。如果模型预测出的头尾实体类型和关系方向矛盾直接判为无效。这个校验不需要额外训练纯靠实体类型组合就能过滤掉一批错误。验证方法也简单在测试集上统计加规则前后的 F1 变化如果 F1 提升超过 2 个点说明规则有效如果反而下降说明规则太激进需要放宽条件。最后说个我自己的教训别一上来就追求 BERT 微调先用 BiLSTM 把整条链路跑通确认数据格式、标签映射、评估脚本都没问题再换大模型。我见过太多人卡在环境配置和维度不匹配上连模型长什么样都没看到就放弃了。源码是死的数据是活的把数据理顺模型换哪个都能跑。希望帮到你。本文还有配套的精品资源点击获取