实体关系抽取实战：从依赖树到图卷积神经网络的完整实现

简介：基于图卷积神经网络的实体关系抽取项目，面向深度学习、自然语言处理方向的在校学生、研究人员及企业开发者，完整覆盖实体关系抽取中数据预处理、GCN模型构建、训练测试、结果评估与可视化展示的流程。整个资源包共41个文件，以Python源码为主体，包含17个py脚本和10个pyc文件，另提供PyTorch模型权重、JSON配置、文本字典、数据文件、说明文档及部署指南，包体大小约93.32MB。项目核心模块聚焦GCN关系抽取，涉及词表构建、语法树处理与模型评估，并配有可运行的训练与测试脚本、GUI交互界面以及官方评分工具，可支持在Windows/macOS环境下复现实验结果。同时，包内包含训练好的模型权重与全量数据，方便直接进行验证、扩展或继续微调，适合课设、毕设等场景。该项目为高分毕业设计源码，已有151人学习使用，非常适合作为实体关系抽取方向的进阶参考和二次开发基础。

1. 实体关系抽取用普通 CNN 还是图卷积：句法结构是分水岭

实体关系抽取的任务是从一句话里识别出两个实体之间是什么关系，并且分清方向。许多人在跑 SemEval 2010 数据集时会发现，普通 CNN 和 BiLSTM 对Cause-Effect(e1,e2)和Cause-Effect(e2,e1)这种反向关系经常混淆，因为它们依赖的是局部 n-gram 窗口，很难表达主语、宾语在句法树上的长距离联系。图卷积神经网络把依赖树构造成邻接矩阵，让消息沿树边传播，从而把句法路径编码进表示里。这个开箱项目正好是这条技术的完整实现，附带源码、部署教程、数据集、训练好的权重和 GUI 演示，适合用于毕业设计、课程设计，也适合想从数据处理到模型推理完整走一遍的人。

2. SemEval 数据预处理：从原始语料到依赖树邻接矩阵

2.1 项目里数据流是怎么排布的

以GCN_relation_extra-master的目录结构为例，dataset下一般会分raw_sem、sem、vocab三个目录。raw_sem放原始下载语料，sem存放预处理之后的干净句子，vocab里是训练时用到的词表。Python 文件里，pre_processing.py跑在最前，把原始数据转成 loader 能读的格式；loader.py负责构造 batch；tree.py负责生成依赖树；再往后是gcn.py和trainer.py。我第一次拿到这个资源时，并没有急着改网络，而是先把pre_processing.py的输出打印出来看，因为后面模型不管怎么调，输入不对一切白搭。

2.2 SemEval 2010 Task 8 的 19 类标签

这个数据集常见格式是id 实体1 实体2 句子，句子里用<e1>...</e1>和<e2>...</e2>标出实体。标签总数不是 10 类而是 19 类，因为除了 Other，剩下 9 种关系都分为正向、反向。比如Cause-Effect(e1,e2)表示 e1 是原因、e2 是结果；Cause-Effect(e2,e1)则是反过来。项目里如果直接做 19 分类，就必须在标签映射时保留方向信息，不能把两者合并。

这个表格对调试很关键，因为最后的 F1 分数是各类别单独统计后再算 macro，某个方向混淆会直接拖低成绩。

2.3 pre_processing.py 到底在做什么

我一般会观察预处理输出的三件事：分词粒度、是否保留大小写，以及依赖树解析器的选用。这个项目里通常会对原始句子做 token 化，再调用tree.py得到每个词的父节点 index。以下代码可以用来验证树是否构建正确：

def build_tree_mask(tokens, heads): seq_len = len(tokens) adj = torch.zeros(seq_len, seq_len) for i, head in enumerate(heads): if head >= 0: adj[i][head] = 1 # 从子节点指向父节点 adj[head][i] = 1 # 从父节点指向子节点 adj[i][i] = 1 # 自环保留自身信息 row_sum = adj.sum(dim=1, keepdim=True) adj_norm = adj / (row_sum + 1e-9) return adj_norm

这段代码把依赖树转成无向带自环的邻接矩阵，然后按行归一化。很多 GCN 实现都采用无向边，原因是有向边对解析错误更敏感：如果父节点识别错，反向消息还是能兜底一部分。1e-9是为了避免空行除零，批量填充出来的<PAD>token 那一行只有自环，归一化后不会出 NaN。实际项目中pre_processing.py会在写文件前把每个 token、实体标记、邻接矩阵都验证一遍，避免到了 loader 阶段才发现解析失败。

2.4 词表与自定义 DataLoader

vocab.py建立word2idx，同时放入<PAD>、<UNK>和实体标记。如果预训练词向量是直接加载的，文件里还会保存向量矩阵。loader.py则要对句子按 batch 内最大长度做 pad，并返回四个张量：token ids、mask、邻接矩阵、标签。一个自定义 collate 的关键是这样处理变长：

def collate_fn(batch): max_len = max(len(item["tokens"]) for item in batch) ids = torch.zeros(len(batch), max_len, dtype=torch.long) adj = torch.zeros(len(batch), max_len, max_len) label = torch.zeros(len(batch), dtype=torch.long) for i, item in enumerate(batch): cur_len = len(item["tokens"]) ids[i, :cur_len] = torch.tensor(item["tokens"]) adj[i, :cur_len, :cur_len] = item["adj"] label[i] = item["label"] return ids, adj, label

adj在 pad 区域保持全零，这样 GCN 层做批量矩阵乘时不会把<PAD>的表示引入真实 token；mask 则用于 BiLSTM 的 packed sequence 或之后的池化。这里需要特别说明：全零邻接矩阵会让该 token 的卷积结果变成零向量，所以模型输出阶段要保留真实长度，不让 pad 区参与分类。loader.py的核心就是解决这件事。

3. BiLSTM + 图卷积：模型如何在依赖树上抽取关系特征

3.1 为什么把 BiLSTM 放在 GCN 前面

直接用 GCN 吃词向量也可以，但效果通常会差很多。词向量给当前词一个孤立表示，实体关系却需要依赖语境才能判断方向。BiLSTM 沿时间顺序编码上下文，让每个 token 携带前后信息，再把这组表示放到 GCN 上做句法聚合。这样 GCN 接收的输入已经不纯粹是词本身，而是这个词在当前句子里所处的语义位置。gcn.py里的 embed_size、hidden_size 都集中在constant.py，把超参抽出来之后，做对照实验会方便很多。

3.2 GCN 层的核心计算

图卷积层的核心是一个线性变换加一个按邻接矩阵的聚合。常见写法是：

class GraphConvLayer(nn.Module): def __init__(self, in_dim, out_dim): super().__init__() self.W = nn.Linear(in_dim, out_dim, bias=False) self.bias = nn.Parameter(torch.zeros(out_dim)) def forward(self, x, adj): support = self.W(x) # [batch, seq_len, out_dim] output = torch.bmm(adj, support) + self.bias return F.relu(output)

W把所有节点表示映射到新的维度，bmm(adj, support)等价于对每个节点把邻居节点的变换结果做加权和。因为前面已经做了行归一化，所以可理解为求邻居平均。这里要注意bias是每个输出通道共享的，而不是每个节点独立；如果给每个节点加独立 bias，参数数量会失控，而且对变长序列不友好。工程上更实用的做法是每层 GCN 之间插入Dropout(0.2~0.5)，比单纯增加隐藏维度更有效。

3.3 实体位置信息怎么注入

方向敏感关系要求模型知道谁是 e1、谁是 e2。这个项目的常见做法是在 token 序列中插入类似<e1>、</e1>的特殊标记，并让这些标记也参与 embedding 训练。这样 BiLSTM 和 GCN 都能感知实体边界。模型最后从 GCN 输出里，把 e1 范围内 token 的向量和 e2 范围内 token 的向量分别做最大池化，再拼接后送给全连接分类器。也可以直接取第一个实体 token 的向量，但那样会丢失实体内部多词搭配的信息。从实际结果看，带实体标记的池化方式对Member-Collection这类需要完整实体语义的关系更友好。

3.4 多层图卷积与路径裁剪

单独一层 GCN 只能拿到直接父节点和子节点的信息。比如The fire caused the damage，如果fire和damage在树上的距离是 2，一层 GCN 无法把二者信息聚合到一起。解决办法有两种：堆多层图卷积，或者把两个实体之间的依赖路径单独建子图。项目配置通常把gcn_layers设置为 2 或 3，消息在树边上往返传播两次后，相当于两个相邻 token 和共同邻居都参与了聚合。继续叠层收益会递减，反而会把无关修饰语和附属从句的噪声带进表示。

第二种做法是后续改造时最常见的优化：不把整棵句法树都作为图，而是先取实体节点在依赖树上的最短路径，只保留路径上的节点，或者额外向外扩一跳。路径受限的好处是减少与关系无关的修饰词干扰，训练收敛更快，在长句上尤其明显。拿到这个项目后，可以先在tree.py之后加一个路径裁剪函数，再对比裁剪前后的宏 F1，通常能稳定提升 1 到 2 个点。

4. 训练器和超参数：从 tem_checkpoint 到 best_model

4.1 训练入口和 constant.py 里的默认值

train.py负责组装模型、加载 loader、调用trainer.py。constant.py通常会把学习率、batch_size、hidden_size、dropout、epoch 数全部抽出来，方便反复修改。我在微调时习惯用命令行参数覆盖默认值，典型训练命令如下：

python train.py \ --data_dir dataset/sem \ --vocab_dir dataset/vocab \ --embed_dim 300 \ --hidden_dim 200 \ --gcn_layers 2 \ --dropout 0.3 \ --batch_size 32 \ --epochs 30 \ --lr 0.001

如果train.py没有提供 argparse 入口，直接改constant.py里的同名常量效果一样。hidden_dim 200配合batch_size 32在普通显卡上就能跑得动。对 SemEval 这种只有 8000 条训练句的数据集来说，模型容量不需要很大，网络更深反而更容易过拟合。

4.2 关键超参数表

损失函数直接用nn.CrossEntropyLoss()就可以，不需要为方向关系额外加权，因为 19 类中 9 组方向关系样本数相对均衡。Other 类占比大，如果模型倾向把所有不确定样本都丢给 Other，可以在损失函数里把 Other 类权重压到 0.5 左右，测试时再看 macro F1 变化。

4.3 为什么会有两个 checkpoint 文件

tem_checkpoint.pt和best_model.pt的区别在保存时机。前一个通常每个 epoch 或固定 step 覆盖一次，只用于断点续训；后一个在验证集 F1 提升时才覆盖，是最终要保留的模型。加载时要特别注意键名：

checkpoint = torch.load("best_model.pt", map_location="cpu") model.load_state_dict(checkpoint["model_state"]) optimizer.load_state_dict(checkpoint["optimizer_state"]) start_epoch = checkpoint["epoch"] + 1

map_location="cpu"是关键，尤其在一台机器上训练、另一台机器上测试的情况。如果不加这个参数，模型里残留的 CUDA 设备信息会让 CPU 环境直接报错。optimizer_state只在断点续训时需要，纯推理可以不加载，但训练恢复时如果不恢复 optimizer 的动量状态，学习率衰减和动量信息都会错位。另外checkpoint["epoch"]要接住，否则接着训练时可能破坏已经算好的学习率调度。

4.4 验证集与早停

SemEval 2010 官方训练集约 8000 句，测试集 2717 句。项目里通常会在训练集里单独切 10% 做验证，而不是直接用官方测试集选择模型，否则选择的顶点会带上测试集噪声。trainer.py的循环会统计准确率和 macro F1，当验证集 F1 连续 3 到 5 个 epoch 不再上升时，停止训练并回滚到最佳状态。这种早停策略对 GCN 尤其重要，因为句法树特征本身结构性强，后期 epoch 很容易过度拟合训练集中的标点习惯和表达方式。

5. 官方评测脚本与测试输出：score.txt 里每个数字的来路

5.1 test.py 和 run_test.py 的分工

这个资源里同时有test.py和run_test.py。按项目常见的维护习惯，test.py适合跑单条数据或小批量验证，run_test.py负责对整个测试集生成预测文件。两个脚本都会先加载词表和 checkpoint，再做模型推理。区别是后者最后会调用官方 Perl 评分脚本，把结果写进score.txt。如果你的目标是复现论文分数，直接看run_test.py的输出路径就可以，不需要自己造测试轮子。

5.2 调用评分脚本的命令

在解压后的目录里，可以按下面顺序执行：

python run_test.py --checkpoint best_model.pt --output resoult.txt perl semeval2010_task8_scorer-v1.2.pl resoult.txt test_key.txt > score.txt

resoult.txt必须保持与测试集相同的行序，每行一个预测标签。官方评分器对格式要求非常死板：多一个空格、多一个空行、标签大小写不一致，都会导致该行按错误处理。常见错误是把Other写成other，或者把反向关系写成不带括号的形式。这类细节在跑分前要统一做一遍字符清洗，建议用sed -i 's/[[:space:]]*$//' resoult.txt去掉行尾空格。

5.3 精准率、召回率、macro F1 怎么统计

评分器统计的是 macro F1，不是准确率。它会对除了 Other 之外的 18 个方向性标签分别计算 precision 和 recall，然后求平均。score.txt里通常前 18 行是每个关系方向的结果，最后一行是 overall。如果你只盯准确率，会被 Other 类别误导：测试集中 Other 占比多，模型把难样本切成 Other 反而能掩盖错误。所以调参要始终看score.txt最后的 F1 值，而不是看 loss 或准确率。

5.4 读 resoult.txt 做错误分析

借助混淆矩阵可以快速定位问题类别。一个简洁的分析脚本长这样：

from collections import defaultdict def build_confusion(pred_file, gold_file): preds = [line.strip() for line in open(pred_file)] golds = [line.strip() for line in open(gold_file)] pairs = defaultdict(int) for p, g in zip(preds, golds): pairs[(g, p)] += 1 return pairs pairs = build_confusion("resoult.txt", "test_key.txt") for (g, p), cnt in sorted(pairs.items()): if g != p and cnt > 0: print(f"{g} -> {p}: {cnt}")

最后打印出来的通常是一大批真实关系被预测成 Other。SemEval 测试集里 Other 占比高，模型只要不确定就会往 Other 靠，所以先看这些样本的依赖树是不是解析错了；如果Entity-Origin和Entity-Destination经常互相混，则说明池化阶段没有抓住实体相对位置信息，可以考虑把实体间的距离特征拼接到分类层输入。这个分析手段比单独看 F1 更能定位问题。

6. 部署 GUI 与推理检查：把 best_model.pt 真正用起来

6.1 启动 GUI.py 的前置条件

项目里保留的GUI.py可以直接用python GUI.py启动。启动前先确认三件事：词表必须和训练时一致，best_model.pt路径能访问，依赖树解析器已经初始化好。很多部署报错不是出在模型结构，而是出在词表不匹配，GUI 加载到不认识的 token 时会直接映射到<UNK>，关系结果自然不准。

6.2 模型推理的核心路径

model.eval() with torch.no_grad(): ids, adj = preprocess_sentence( "The fire caused the damage", e1=(2, 3), e2=(4, 5) ) logits = model(ids.unsqueeze(0), adj.unsqueeze(0)) pred = torch.argmax(logits, dim=-1).item() print(idx2rel[pred])

preprocess_sentence会复用训练时的vocab.py和tree.py，所以 GUI 与训练时的分词规则必须一致。同一个句子训练时拆成 5 个 token，GUI 里拆成 4 个 token，后面张量长度对不上，模型即使能跑，结果也完全不可复现。逻辑层里显式调用model.eval()和torch.no_grad()是为了关闭 dropout 和梯度缓存，这会让预测结果稳定下来，否则多次点击 GUI 可能出现概率差异。

6.3 部署时容易被忽略的 checkpoint 路径问题

在 Mac 或无 NVIDIA GPU 机器上，torch.load默认保留训练时的设备指针，所以加载时务必加上map_location="cpu"。如果 GUI 内部用了 MPS 设备，还需要把ids和adj同时.to(device)，只移 ids 不移动邻接矩阵是常见的 CPU/GPU 张量不匹配来源。把这些路径和参数对齐后，GUI 输出的关系类型就能和resoult.txt里的结果对应上。

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