DGL 节点分类/回归完整指南:从 GraphSAGE 到 Heterogeneous RGCN 的实战训练

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

DGL 节点分类/回归完整指南:从 GraphSAGE 到 Heterogeneous RGCN 的实战训练

导读:节点分类/回归是图神经网络(GNN)最经典、应用最广的下游任务。本文基于 DGL 官方指南 docs/source/guide/training-node.rst(含韩文版 guide_ko/training-node.rst 与中文版 guide_cn/training-node.rst)展开,完整覆盖两大实战路径:一是用 SAGEConv 堆叠多层网络,在全图(full graph)上训练同质图节点分类模型;二是用 HeteroGraphConv + GraphConv 构建 RGCN 式异构卷积网络,在含多种边类型(relation)的异构图上完成节点分类。读完本文,你将掌握:DGL 内置图卷积模块的选型与核心参数、基于掩码(mask)的训练/验证/测试划分用法、完整训练循环的写法,以及异构图上按边类型分路卷积、按目标节点类型聚合输出的底层原理。

任务背景:什么是节点分类与节点回归

对于图神经网络来说,最常见且被广泛采用的任务之一就是节点分类(Node Classification)。在训练、验证和测试集中,每个节点都被分配了一个来自预定义类别集合的 ground truth 类别;节点回归(Node Regression)任务则与之类似,区别仅在于每个节点被标注的是一个真实数值(ground truth number)而非离散类别。

无论是分类还是回归,核心思想一致:为了对节点做出预测,GNN 需要执行 消息传递机制(message passing),综合利用节点自身的特征、其邻居节点的特征以及边的特征,计算出节点的隐藏表示(hidden representation)。消息传递可以重复多轮,从而让每个节点逐渐聚合到更大范围邻居(更高阶邻域)的信息——这正是"多跳邻居信息"能够被编码进节点表示的根本原因。

同质图:用 SAGEConv 编写图神经网络模型

单轮消息传递与内置卷积模块

DGL 提供了一批内置的图卷积模块(built-in graph convolution modules),每个模块封装一轮消息传递计算。本文以 SAGEConv 为例——它是 GraphSAGE 模型使用的图卷积模块,在 PyTorch、MXNet 与 TensorFlow 后端中均可使用(本文代码基于 dgl.nn.pytorch)。

从源码看,SAGEConv 的数学定义位于 python/dgl/nn/pytorch/conv/sageconv.py:

h_N(i)^(l+1) = aggregate({ h_j^l, for all j in N(i) })
h_i^(l+1)    = sigma(W · concat(h_i^l, h_N(i)^(l+1)))
h_i^(l+1)    = norm(h_i^(l+1))

即:先聚合邻居特征,再将自身特征与聚合结果拼接后做线性变换,最后可选的归一化与激活。它支持的 aggregator_type 有四种:mean、gcn、pool、lstm(源码中通过 valid_aggre_types = {"mean", "gcn", "pool", "lstm"} 校验,非法取值会抛出 DGLError,见 sageconv.py)。

堆叠多层:两层的 GraphSAGE 模型

图上的深度学习模型通常需要多层结构,以执行多轮消息传递。实现方式很简单:像堆叠全连接层一样堆叠图卷积模块。指南给出了一个两层 GNN 模型的标准写法:

# Construct a two-layer GNN model
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__()
        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):
        # inputs are features of nodes
        h = self.conv1(graph, inputs)
        h = F.relu(h)
        h = self.conv2(graph, h)
        return h

要点解析:

  • 维度流转:in_feats → hid_feats → out_feats。其中 out_feats 通常等于类别数(分类)或 1(回归)。
  • 中间激活:两个卷积层之间插入 F.relu 引入非线性;最后一层不接激活,直接输出 logits,交由损失函数处理。
  • aggregator_type='mean':SAGEConv 默认的邻居聚合方式即 mean;也可换用 gcn、pool(带全连接 + 最大池化的聚合)或 lstm(LSTM 聚合器,源码中对应 self.lstm = nn.LSTM(...),见 sageconv.py)。
  • 更多超参数:SAGEConv 还支持 feat_drop(特征 dropout 率,默认 0)、bias(是否加可学习偏置,默认 True)、norm(对更新后特征的归一化层)、activation(层内激活函数,默认 None),完整签名见 sageconv.py。

值得注意的是,这个两层模型不仅限于节点分类,它产出的隐藏节点表示同样可以作为边分类(training-edge.rst)、链接预测(training-link.rst)或图分类(training-graph.rst)等下游任务的特征来源——也就是说,本文的模型骨架具有通用性。

内置卷积模块全景

DGL 的 dgl.nn 提供了丰富的内置图卷积模块,除 SAGEConv 外,还包括 GraphConv(GCN)、GATConv、GINConv、RelGraphConv、ChebConv 等数十种,完整清单可见 python/dgl/nn/pytorch/conv/ 目录(对应的文档 API 章节为 apinn)。关于 DGL 神经网络模块的通用工作机理,以及如何用消息传递 API(update_all、apply_edges 等)编写自定义 GNN 模块,可参考 guide/nn.rst 中的示例。

全图训练循环:Citeseer 数据集实战

数据准备:特征、标签与掩码

训练"全图"(full graph)上的节点分类模型,本质上就是:对上述模型做一次前向传播,把预测与训练节点上的 ground truth 标签比较,计算损失并反向传播。

本节使用 DGL 内置数据集 CiteseerGraphDataset 演示完整的训练循环。该数据集的节点特征与标签存储在图的 ndata 上,训练/验证/测试划分以**布尔掩码(boolean mask)**形式直接存在图上——这与 guide/data-pipeline.rst 中介绍的数据集约定一致。

从源码可以确认该数据集的规模与任务设定(见 python/dgl/data/citation_graph.py):

  • 节点数:3327
  • 边数:9228
  • 类别数:6
  • 标签划分:Train 120 / Valid 500 / Test 1000
  • 每个节点带有 3703 维的预定义特征

数据读取与划分的代码为:

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_features 由特征矩阵的列数直接推断,n_labels 通过"最大标签值 + 1"自动算出类别数——这样模型输出维度与任务类别数严格对齐。

评估函数:按掩码计算准确率

指南给出的评估函数以准确率(accuracy)为指标,只在指定掩码对应的节点上比较预测与标签:

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)

关键点:

  • model.eval() + torch.no_grad():关闭 dropout 等训练期行为与梯度追踪,保证评估结果稳定且节省显存。
  • torch.max(logits, dim=1):取每个节点 logits 中最大值的下标作为预测类别。
  • 掩码索引 logits[mask]:布尔张量直接用于过滤,只在目标集合(如验证集)上统计准确率。

训练循环本体

接下来是完整训练循环:

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()
    # forward propagation by using all nodes
    logits = model(graph, node_features)
    # compute loss
    loss = F.cross_entropy(logits[train_mask], node_labels[train_mask])
    # compute validation accuracy
    acc = evaluate(model, graph, node_features, node_labels, valid_mask)
    # backward propagation
    opt.zero_grad()
    loss.backward()
    opt.step()
    print(loss.item())

    # Save model if necessary.  Omitted in this example.

逐行拆解:

  1. 初始化:SAGE(in_feats=n_features, hid_feats=100, out_feats=n_labels),隐藏层维度取 100,输出维度为类别数;优化器选用 Adam。
  2. model.train():进入训练模式。
  3. 全图前向:logits = model(graph, node_features) 一次对整张图的所有节点做前向传播。
  4. 损失:F.cross_entropy(logits[train_mask], node_labels[train_mask])——交叉熵只在 train_mask 选中的节点上计算,这是全图监督学习的典型写法(与掩码过滤后的 logits、标签对齐)。
  5. 验证:每个 epoch 用 evaluate 在验证集上算一次准确率。
  6. 反向更新:opt.zero_grad() → loss.backward() → opt.step() 的标准三件套。
  7. 保存模型的代码在本示例中省略,实际项目中可在验证准确率提升时用 torch.save(model.state_dict(), path) 存档。

端到端完整示例

指南指向的 GraphSAGE 端到端同质图节点分类示例,其完整模型实现位于 examples/pytorch/graphsage/train_full.py,其中的 GraphSAGE 类展示了更贴近生产的写法:可调节的层数(num_layers)、dropout 概率、可自定义的聚合函数与非线性激活。当需要把本文的两层玩具模型升级为可配置的工业级实现时,可以直接参考该文件。

异构图:HeteroGraphConv 实现节点分类

为什么异构图需要特殊处理

如果图是异构的(heterogeneous,存在多种节点类型与多种边类型/relation),你通常希望从所有边类型的邻居那里收集消息。直观做法是:为每种边类型配备一个独立的图卷积模块,先在各关系子图上分别做消息传递,再把结果按目标节点类型合并。

RGCN 式两层异构卷积模型

指南使用 dgl.nn.HeteroGraphConv(PyTorch、MXNet、TensorFlow 后端均提供)实现这一点,配合 GraphConv 构成 RGCN 风格的两层模型:

# Define a Heterograph Conv model

class RGCN(nn.Module):
    def __init__(self, in_feats, hid_feats, out_feats, rel_names):
        super().__init__()

        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):
        # inputs are features of nodes
        h = self.conv1(graph, inputs)
        h = {k: F.relu(v) for k, v in h.items()}
        h = self.conv2(graph, h)
        return h

这里的两个关键设计:

  • 按关系分路的模块字典:{rel: dglnn.GraphConv(...) for rel in rel_names} 为每一种边类型(relation)实例化一个独立的 GraphConv,不同边类型之间不共享权重。
  • aggregate='sum' 聚合:对同一目标节点类型,把来自不同关系子图的消息聚合结果求和,作为该节点类型的最终输出。HeteroGraphConv 支持的聚合方式还包括 max、min、mean、stack,也允许传入自定义的聚合 callable(def my_agg_func(tensors, dsttype): ...),详见 python/dgl/nn/pytorch/hetero.py。

HeteroGraphConv 的底层执行逻辑

从源码看,HeteroGraphConv.forward 的核心流程是(伪代码见 python/dgl/nn/pytorch/hetero.py,实现见同文件 L184-L220):

outputs = {dsttype: [] for dsttype in g.dsttypes}
for (stype, etype, dtype) in g.canonical_etypes:
    rel_graph = g[stype, etype, dtype]
    dstdata = relation_submodule(rel_graph, (src_features[stype], dst_features[dtype]))
    outputs[dtype].append(dstdata)

rsts = {}
for ntype, ntype_outputs in outputs.items():
    if len(ntype_outputs) != 0:
        rsts[ntype] = aggregate(ntype_outputs)
return rsts

即:输入一个「节点类型 → 特征张量」的字典,输出另一个「节点类型 → 更新后特征」的字典;遍历每条规范边类型(canonical etype)调用对应的子模块,并把到达同一目标节点类型的结果用 aggregate 合并。此外,构造时 HeteroGraphConv 会自动对子模块调用 set_allow_zero_in_degree_fn(True),避免 0 入度节点在消息传递时报错(见 hetero.py)。

在异构数据上实例化模型与前向传播

指南中的示例数据来自异构图示例,其中 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']

注意两点:hetero_graph.etypes 提供了全部边类型名列表,供模型按关系分路;hetero_graph.nodes['user'].data[...] 是按节点类型索引 ndata 的标准 API。

前向传播同样简单——把每种节点类型的特征放进字典传入即可:

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()
    # forward propagation by using all nodes and extracting the user embeddings
    logits = model(hetero_graph, node_features)['user']
    # compute loss
    loss = F.cross_entropy(logits[train_mask], labels[train_mask])
    # Compute validation accuracy.  Omitted in this example.
    # backward propagation
    opt.zero_grad()
    loss.backward()
    opt.step()
    print(loss.item())

    # Save model if necessary.  Omitted in the example.

这一模式可以推广到任意目标节点类型:想要预测 item,只需把 ['user'] 换成 ['item'],并相应替换标签与掩码。

端到端完整示例

DGL 为异构图的节点分类提供了端到端示例:入口脚本为 examples/pytorch/rgcn-hetero/entity_classify.py,其中异构图卷积的详细定义位于模型实现文件 examples/pytorch/rgcn-hetero/model.py 的 RelGraphConvLayer 类中——该实现正是本文所述"按关系分路卷积 + 聚合"思想的完整落地,适合进一步研读与改造。

小结与进阶路线

本文围绕 DGL 节点分类/回归任务,走完了两条完整路线:

场景 核心模块 关键点
同质图节点分类/回归 SAGEConv(叠加多层) 掩码划分训练/验证/测试集;全图前向 + 掩码交叉熵;Adam 优化
异构图节点分类 HeteroGraphConv + GraphConv(RGCN 式) 按边类型分路卷积、不共享权重;aggregate='sum' 合并;输出为节点类型字典

在此基础上,若需处理更大规模的图(无法全图训练),可进一步学习基于邻居采样的小批量训练方法,参见 guide/minibatch-node.rst;消息传递 API 与自定义 GNN 模块的底层原理见 guide/message-passing.rst 与 guide/nn.rst。

登录后查看全文
dgl