基于 DGL 的节点分类/回归实战:从同构图 GraphSAGE 到异构图 RGCN 的完整训练指南

原创2026-09-21 10:17:091,704 阅读
文章标签:深度学习机器学习人工智能图计算分布式训练高性能计算数据科学

基于 DGL 的节点分类/回归实战:从同构图 GraphSAGE 到异构图 RGCN 的完整训练指南

导读

节点分类(Node Classification)是图神经网络最经典的应用任务之一:给定一张图,训练集中的每个节点都带有从预定义类别集合中分配的正确标注,模型学习利用节点自身的特征以及邻居节点与边的特征,预测验证集与测试集中节点的类别;节点回归(Node Regression)与之类似,只是标注从离散类别变成了连续数值。本文以 DGL(Deep Graph Library)为实践框架,完整讲解同构图与异构图上节点分类模型的构建、训练与评估流程,涵盖 SAGEConv、HeteroGraphConv 等核心模块的源码级原理,并给出可直接运行验证的端到端示例。读完本文,你将掌握:如何堆叠图卷积层搭建多层 GNN、如何基于布尔掩码组织训练/验证/测试划分、如何计算交叉熵损失并完成反向传播,以及如何将同样的流程推广到多节点类型的异构图场景。

节点分类任务的核心思想:通过消息传递学习节点表示

在图神经网络中,节点分类依赖消息传递(Message Passing)机制:每一轮消息传递中,每个节点收集其邻居节点的特征(以及边的特征),经过聚合与变换后更新自身的隐藏表示。数学上,一轮更新可以概括为"消息生成 → 消息聚合 → 节点表示更新"三步,重复多轮即可利用越来越大的邻居范围(如两跳、三跳)的信息。

DGL 对这套机制提供了高度封装的图卷积模块,只需一次前向调用即可完成一轮消息传递,其底层由 update_all 等原语驱动(详见 python/dgl/nn/pytorch/conv/sageconv.py 中 graph.update_all(msg_fn, fn.mean("m", "neigh")) 的调用模式)。因此,编写节点分类模型的核心工作就是选择合适的卷积模块并按照层级堆叠它们。

编写神经网络模型:用 SAGEConv 搭建两层同构图 GNN

原文档选择 dgl.nn.pytorch.SAGEConv 作为演示模块(MXNet 与 TensorFlow 后端也有对应实现)。SAGEConv 源自 GraphSAGE 论文(Inductive Representation Learning on Large Graphs),其更新公式为:

h_neighbor = aggregate({h_j, for all j in N(i)})
h_i = sigma(W · concat(h_i, h_neighbor))

即:先聚合邻居表示,再将自身表示与聚合结果拼接后经过线性变换与激活。以下代码用两个 SAGEConv 堆叠出一个两层 GNN:

# 构建一个2层的GNN模型
import dgl.nn as dglnn
import torch.nn as nn
import torch.nn.functional as F

class SAGE(nn.Module):
    def __init__(self, in_feats, hid_feats, out_feats):
        super().__init__()
        # 实例化SAGEConv,in_feats是输入特征的维度,out_feats是输出特征的维度,aggregator_type是聚合函数的类型
        self.conv1 = dglnn.SAGEConv(
            in_feats=in_feats, out_feats=hid_feats, aggregator_type='mean')
        self.conv2 = dglnn.SAGEConv(
            in_feats=hid_feats, out_feats=out_feats, aggregator_type='mean')

    def forward(self, graph, inputs):
        # 输入是节点的特征
        h = self.conv1(graph, inputs)
        h = F.relu(h)
        h = self.conv2(graph, h)
        return h

SAGEConv 的聚合器与参数细节(源码级补充)

查看 SAGEConv 的构造函数 可以确认,aggregator_type 的合法取值为 mean、gcn、pool、lstm 四种,传入非法值会抛出 DGLError。各聚合器的底层实现(见 forward 方法)分别是:

  • mean:对邻居特征取均值,即 fn.mean("m", "neigh");
  • gcn:将自身特征与邻居求和结果除以 (入度 + 1),等价于带自环的 GCN 归一化,且该模式不构造 fc_self 线性层;
  • pool:先经过一个 fc_pool 线性层与 ReLU,再对邻居取最大值;
  • lstm:用一个 LSTM 作为聚合器(实现位于 _lstm_reducer),适合顺序敏感的邻居集合。

除 in_feats / out_feats / aggregator_type 外,构造函数还支持 feat_drop(特征 dropout,默认 0)、bias(是否学习偏置,默认 True)、norm(归一化层)、activation(激活函数)等参数,参考 SAGEConv 参数文档。

需要说明的是:这个模型不仅适用于节点分类,学到的节点隐藏表示同样可以作为边分类、链接预测、图分类等其他下游任务的输入特征。

全图监督训练:数据准备、评估函数与训练循环

数据集与掩码划分

本节使用 DGL 内置数据集 dgl.data.CiteseerGraphDataset。从 CiteseerGraphDataset 的源码注释 可以看到:该数据集共 3327 个节点、9228 条边,特征维度 3703,类别数为 6,训练/验证/测试掩码分别覆盖 120 / 500 / 1000 个节点。节点特征与标签都存储在图的 ndata 上,训练/验证/测试的划分以布尔掩码的形式同样挂在 ndata 上:

node_features = graph.ndata['feat']
node_labels = graph.ndata['label']
train_mask = graph.ndata['train_mask']
valid_mask = graph.ndata['val_mask']
test_mask = graph.ndata['test_mask']
n_features = node_features.shape[1]
n_labels = int(node_labels.max().item() + 1)

这里 n_labels 通过标签最大值加一推导,避免了硬编码类别数。

准确率评估函数

下面的 evaluate 函数在验证/测试掩码上计算分类准确率:先让模型输出所有节点的 logits,再用掩码过滤出目标节点,取每行最大值对应的下标作为预测类别,最后统计预测与真实标签一致的样本比例:

def evaluate(model, graph, features, labels, mask):
    model.eval()
    with torch.no_grad():
        logits = model(graph, features)
        logits = logits[mask]
        labels = labels[mask]
        _, indices = torch.max(logits, dim=1)
        correct = torch.sum(indices == labels)
        return correct.item() * 1.0 / len(labels)

训练循环

全图(Full-batch)训练只需用全部节点特征做一次前向传播,在训练掩码对应的节点上比较预测 logits 与真实标签计算交叉熵损失,再反向传播即可:

model = SAGE(in_feats=n_features, hid_feats=100, out_feats=n_labels)
opt = torch.optim.Adam(model.parameters())

for epoch in range(10):
    model.train()
    # 使用所有节点(全图)进行前向传播计算
    logits = model(graph, node_features)
    # 计算损失值
    loss = F.cross_entropy(logits[train_mask], node_labels[train_mask])
    # 计算验证集的准确度
    acc = evaluate(model, graph, node_features, node_labels, valid_mask)
    # 进行反向传播计算
    opt.zero_grad()
    loss.backward()
    opt.step()
    print(loss.item())
    # 如果需要的话,保存训练好的模型。本例中省略。

注意标准的训练循环顺序:opt.zero_grad() 清空上一步梯度 → loss.backward() 计算梯度 → opt.step() 更新参数。F.cross_entropy 内部已包含 softmax 归一化,因此模型最后一层无需再显式接 softmax。

端到端示例:examples/pytorch/graphsage/train_full.py

原文档指出的 GraphSAGE 端到端样例 在仓库中可完整查看,它比上文的最小示例多了工程化细节,可作为生产级模板:

  • 可调层数与 dropout:SAGE 类用 nn.ModuleList 存放多个 SAGEConv 层,并通过 nn.Dropout(0.5) 对输入与中间层特征做 dropout(参考 train_full.py 第 13-29 行);
  • 多数据集支持:命令行 --dataset 参数支持 cora / citeseer / pubmed,并可通过 --dt 切换 float / bfloat16 数据类型(参考 train_full.py 第 65-93 行);
  • 自环处理:通过 AddSelfLoop() transform 在加载数据时添加自环,保证节点自身特征参与聚合;
  • 设备迁移:g = g.int().to(device) 将图与特征搬到 CUDA(若可用);
  • 更完整的训练配置:使用 nn.CrossEntropyLoss() 与 Adam 优化器,并设置 lr=1e-2, weight_decay=5e-4,训练 200 个 epoch,每个 epoch 打印验证集准确率(参考 train_full.py 第 43-62 行)。

运行方式(在仓库根目录下):

python examples/pytorch/graphsage/train_full.py --dataset cora
python examples/pytorch/graphsage/train_full.py --dataset citeseer
python examples/pytorch/graphsage/train_full.py --dataset pubmed

异构图上的节点分类:用 HeteroGraphConv 与 RGCN 处理多边类型

当图为异构(包含多种节点类型与边类型)时,用户通常希望沿着所有边类型从邻居收集消息。原文档采用 dgl.nn.pytorch.HeteroGraphConv 模块:它为每种边类型指定一个图卷积子模块,先对每条关系子图分别做卷积,再将指向同一目标节点类型的结果按指定方式聚合,最后输出每种目标节点类型的新表示。

RGCN 模型定义

下面的代码定义了一个异构图卷积模型:HeteroGraphConv 接收一个"边类型 → 卷积模块"的字典,其中每个关系使用一个 GraphConv,并通过 aggregate='sum' 将多种关系的结果相加:

# Define a Heterograph Conv model

class RGCN(nn.Module):
    def __init__(self, in_feats, hid_feats, out_feats, rel_names):
        super().__init__()
        # 实例化HeteroGraphConv,in_feats是输入特征的维度,out_feats是输出特征的维度,aggregate是聚合函数的类型
        self.conv1 = dglnn.HeteroGraphConv({
            rel: dglnn.GraphConv(in_feats, hid_feats)
            for rel in rel_names}, aggregate='sum')
        self.conv2 = dglnn.HeteroGraphConv({
            rel: dglnn.GraphConv(hid_feats, out_feats)
            for rel in rel_names}, aggregate='sum')

    def forward(self, graph, inputs):
        # 输入是节点的特征字典
        h = self.conv1(graph, inputs)
        h = {k: F.relu(v) for k, v in h.items()}
        h = self.conv2(graph, h)
        return h

HeteroGraphConv 的输入/输出协议与聚合方式(源码级补充)

从 HeteroGraphConv 实现 可以看到其计算伪代码:

outputs = {nty : [] for nty in g.dsttypes}
# 对每条规范边类型 (stype, etype, dtype) 应用对应的子模块
dstdata = relation_submodule(g[relation], ...)
outputs[dtype].append(dstdata)
# 对每个目标节点类型聚合来自不同关系的结果
rsts[nty] = aggregate(outputs[nty])

据此可以明确以下要点:

  • dgl.nn.HeteroGraphConv 的输入是一个"节点类型 → 特征张量"的字典,输出是另一个"节点类型 → 特征张量"的字典,返回的字典只包含那些确实收到消息的目标节点类型;
  • mods 字典的 key 可以是非规范边类型名(如 'follows'),内部通过 _get_module 兼容规范三元组 (stype, etype, dtype) 的查询;
  • aggregate 参数(即原文档所说的聚合函数)支持字符串 'sum'、'max'、'min'、'mean'、'stack',也支持传入自定义可调用对象;其中 'stack' 沿第二维堆叠(参考 get_aggregate_fn 实现)。原文档示例使用的 aggregate='sum' 表示将多种关系产生的消息逐元素相加;
  • 该模块会自动对每个子模块调用 set_allow_zero_in_degree(True),从而允许图中存在零入度节点(异构图没有通用的加自环规则)。

异构图上获取特征并前向传播

在异构图示例中,user 和 item 两类节点各有其特征,按节点类型分别取出:

model = RGCN(n_hetero_features, 20, n_user_classes, hetero_graph.etypes)
user_feats = hetero_graph.nodes['user'].data['feature']
item_feats = hetero_graph.nodes['item'].data['feature']
labels = hetero_graph.nodes['user'].data['label']
train_mask = hetero_graph.nodes['user'].data['train_mask']

前向传播时把所有节点类型的特征打包成字典一次传入:

node_features = {'user': user_feats, 'item': item_feats}
h_dict = model(hetero_graph, {'user': user_feats, 'item': item_feats})
h_user = h_dict['user']
h_item = h_dict['item']

异构图的训练循环

异构图的训练与同构图完全一致,区别仅在于:前向输出是一个字典,需要按目标节点类型提取预测。例如只预测 user 节点的类别时,从返回字典中取 'user' 的嵌入:

opt = torch.optim.Adam(model.parameters())

for epoch in range(5):
    model.train()
    # 使用所有节点的特征进行前向传播计算,并提取输出的user节点嵌入
    logits = model(hetero_graph, node_features)['user']
    # 计算损失值
    loss = F.cross_entropy(logits[train_mask], labels[train_mask])
    # 计算验证集的准确度。在本例中省略。
    # 进行反向传播计算
    opt.zero_grad()
    loss.backward()
    opt.step()
    print(loss.item())
    # 如果需要的话,保存训练好的模型。本例中省略。

端到端示例:examples/pytorch/rgcn-hetero/

原文档提到的 RGCN 端到端节点分类示例位于 examples/pytorch/rgcn-hetero/,其中:

  • entity_classify_heteroAPI.py 是基于 HeteroGraphConv 高层 API 的训练入口:它从 dgl.data.rdf 加载 AIFB、MUTAG、BGS、AM 等 RDF 数据集,通过 dataset.predict_category 确定待预测的节点类型,取出该类型的 train_mask / test_mask / labels 后执行标准的"前向 → 交叉熵 → 反向传播"循环(参考 entity_classify_heteroAPI.py 第 78-108 行);
  • 命令行参数覆盖了工程化所需的关键超参:--n-hidden(隐藏单元数,默认 16)、--n-layers(传播轮数,默认 2)、--n-bases(基分解个数,-1 表示不分解)、--dropout(默认 0)、--lr(默认 1e-2)、--l2norm、--use-self-loop(是否把自身特征作为特殊关系)以及 --gpu(参考 entity_classify_heteroAPI.py 第 127-171 行);
  • 训练结束后会输出测试集上的准确率与损失,并可通过 --model_path 保存模型权重(参考 entity_classify_heteroAPI.py 第 109-123 行)。

典型运行命令(在仓库根目录下):

python examples/pytorch/rgcn-hetero/entity_classify_heteroAPI.py --dataset aifb
python examples/pytorch/rgcn-hetero/entity_classify_heteroAPI.py --dataset mutag

此外,仓库还提供了 entity_classify.py(基于低层消息传递 API 的实现)与 entity_classify_mb.py(小批量训练版本),模型层定义 RelGraphConvLayer 在 model.py 中,便于对比不同 API 风格的实现差异。

总结与进一步阅读

本文以 DGL 为框架,走通了节点分类任务的完整链路:

  1. 任务定义:节点分类/回归利用消息传递机制,以节点自身特征与邻居特征学习可泛化的节点表示;
  2. 模型构建:同构图用 SAGEConv(支持 mean/gcn/pool/lstm 四种聚合器)堆叠多层;异构图用 HeteroGraphConv 为每种边类型指定子模块并聚合结果;
  3. 训练范式:全图前向 + 掩码选样本 + 交叉熵损失 + Adam 反向传播,训练/验证/测试掩码均挂在图的 ndata 上;
  4. 工程落地:examples/pytorch/graphsage/train_full.py 与 examples/pytorch/rgcn-hetero/ 分别提供了同构与异构场景的端到端模板,可直接运行、替换数据集与调参。

想继续深入,可以进一步阅读:

  • 消息传递机制的基础:guide_cn 消息传递章节;
  • DGL 内置图卷积模块的完整列表:API 参考;
  • 自定义带消息传递的 GNN 模块:guide_cn nn 章节;
  • 边分类、链接预测与图分类等其他下游任务:guide_cn 训练章节、链接预测、图分类;
  • 数据管道与数据集处理:guide_cn data-pipeline 章节。
登录后查看全文
dgl