DGL 节点分类/回归完整指南:从 GraphSAGE 到 Heterogeneous RGCN 的实战训练
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.
逐行拆解:
- 初始化:
SAGE(in_feats=n_features, hid_feats=100, out_feats=n_labels),隐藏层维度取 100,输出维度为类别数;优化器选用Adam。 model.train():进入训练模式。- 全图前向:
logits = model(graph, node_features)一次对整张图的所有节点做前向传播。 - 损失:
F.cross_entropy(logits[train_mask], node_labels[train_mask])——交叉熵只在train_mask选中的节点上计算,这是全图监督学习的典型写法(与掩码过滤后的 logits、标签对齐)。 - 验证:每个 epoch 用
evaluate在验证集上算一次准确率。 - 反向更新:
opt.zero_grad()→loss.backward()→opt.step()的标准三件套。 - 保存模型的代码在本示例中省略,实际项目中可在验证准确率提升时用
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。