使用 DGL Sparse 与 GraphBolt 完成 GraphSAGE 小批量训练实战指南
使用 DGL Sparse 与 GraphBolt 完成 GraphSAGE 小批量训练实战指南
本文基于 DGL 官方指南 docs/source/guide/minibatch-sparse.rst 展开,系统讲解如何用 dgl.sparse 稀疏矩阵库替代传统的 FusedCSCSamplingGraph,配合 dgl.graphbolt 数据管道,实现基于子矩阵采样的 GraphSAGE 节点分类训练。读完本文,你将掌握 SparseMatrix.sample 与 SparseMatrix.compact 两个核心稀疏算子的语义与用法、如何编写自定义稀疏邻居采样器、如何将稀疏矩阵接入 GraphBolt DataLoader,并理解均值聚合(mean aggregator)在稀疏矩阵上的完整实现。
整体思路:与常规小批量训练有何不同
DGL 官方此前的小批量节点分类训练(见 minibatch-node.rst)依赖 dgl.graphbolt.FusedCSCSamplingGraph 完成邻居采样,图以 CSC 存储结构封装在采样图中。而本文介绍的方案有两大主要区别:
- 采样器不同:本文自定义了一个
SparseNeighborSampler采样器,它不再调用采样图内置的邻居采样内核,而是直接对稀疏矩阵执行sample与compact两个算子,从整张图的稀疏矩阵中"切出"所需的子矩阵。 - 图的表示不同:整张图被转换为
dgl.sparse.SparseMatrix,以标准的稀疏矩阵(内部为 COO/CSC 混合格式)表示邻接关系,采样、聚合全部以矩阵运算的形式完成。
其余部分(特征抓取、DataLoader 组装、前向传播、训练循环)与常规节点分类教程几乎完全一致,因此这篇教程可以看作"用稀疏矩阵重新实现一遍邻居采样"的完整范式。
官方文档对应的完整可运行示例位于 examples/graphbolt/sparse/graphsage.py,建议阅读本文时对照该文件。
第一步:自定义稀疏邻居采样器 SparseNeighborSampler
采样器继承自 dgl.graphbolt.subgraph_sampler.SubgraphSampler,并通过 torch.utils.data.functional_datapipe 注册为名为 sample_sparse_neighbor 的 DataPipe,这样后续可以用 datapipe.sample_sparse_neighbor(A, fanouts) 的方式直接链式调用(见 graphsage.py):
@functional_datapipe("sample_sparse_neighbor")
class SparseNeighborSampler(SubgraphSampler):
def __init__(self, datapipe, matrix, fanouts):
super().__init__(datapipe)
self.matrix = matrix
# Convert fanouts to a list of tensors.
self.fanouts = []
for fanout in fanouts:
if not isinstance(fanout, torch.Tensor):
fanout = torch.LongTensor([int(fanout)])
self.fanouts.insert(0, fanout)
def sample_subgraphs(self, seeds):
sampled_matrices = []
src = seeds
for fanout in self.fanouts:
# Sample neighbors.
sampled_matrix = self.matrix.sample(1, fanout, ids=src).coalesce()
# Compact the sampled matrix.
compacted_mat, row_ids = sampled_matrix.compact(0)
sampled_matrices.insert(0, compacted_mat)
src = row_ids
return src, sampled_matrices
构造参数语义
datapipe:上游 DataPipe,通常由gb.ItemSampler产出。matrix:表示整张图的SparseMatrix,形状为(N, N),N为节点数。fanouts:每层采样的邻居个数列表。注意这里用insert(0, ...)倒序存放,因为多层采样时从最深一层向第 1 层推进,循环里先取出的是第k跳的 fanout。每个 fanout 会被规范化为torch.LongTensor([int(fanout)])。
采样与压缩的核心循环
以三层采样(fanouts 长度为 3)为例,循环执行以下两步:
self.matrix.sample(1, fanout, ids=src):从矩阵的第 1 维(列维度)上,对src指定的每一列(即每个种子节点)随机抽取fanout个非零元素,得到一个与原始矩阵同形状、仅保留被采样非零元素的稀疏矩阵。随后的.coalesce()用于合并重复的索引项。sampled_matrix.compact(0):按行(第 0 维)压缩并重新编号:删除没有非零元素的行,将行索引重新映射为连续的0, 1, 2, ...,返回压缩后的子矩阵compacted_mat以及新行号到原始行号的映射row_ids。row_ids同时就是下一跳采样的种子节点。
每次迭代把 compacted_mat 通过 insert(0, ...) 压入列表头部,因此最终 sampled_matrices 中下标 0 对应第 1 跳(最靠近种子)的子矩阵,下标 k-1 对应第 k 跳的子矩阵——正好与多层 GNN 的前向顺序一致。src = row_ids 将压缩后的行号作为下一轮采样的种子,保证采样过程在"已采样子图"上层层外扩。
源码层面的算子语义
从源码 python/dgl/sparse/sparse_matrix.py 可以确认两个算子的完整参数:
SparseMatrix.sample(dim, fanout, ids=None, replace=False, bias=False)(sparse_matrix.py):
dim:采样维度,0表示按行采样,1表示按列采样。本教程中sample(1, ...)即"对每个种子节点(列)抽取其邻居"。fanout:每一行/每一列随机采样的元素个数。ids:可选的张量,指定参与采样的行/列 ID。当ids=None时从所有行/列采样;本教程每次传入src(上一轮压缩后的节点),实现逐步外扩。replace:是否允许同一元素被重复采样。replace=False时若非零元素少于fanout,则采样全部非零元素。bias:为True时以稀疏矩阵的值为采样权重进行带偏采样。- 该算子不支持自动求导,返回与原始矩阵同形状的子矩阵。
SparseMatrix.compact(dim, leading_indices=None)(sparse_matrix.py):
dim:要重新编号的维度,0为行、1为列。leading_indices:可选参数,指定要放到重编号维度最前面的行/列 ID。源码注释明确指出:该函数模仿dgl.to_block,leading_indices等价于dgl.to_block的include_dst_in_src——当按行重编号并把列 ID 作为leading_indices传入时,效果等同于"将目标节点包含进源节点",这在消息传递中用于保留种子节点信息。本教程中传None,重编号顺序保持原始顺序、仅删除空行。- 返回
(relabeled_matrix, original_ids)二元组:新矩阵 + 重编号维度"新索引 → 原始索引"的映射,即循环里的row_ids。
第二步:用 SparseMatrix 表示整张图
与常规教程不同,这里不构建 FusedCSCSamplingGraph,而是从数据集拿到 CSC 格式的邻接结构后直接构造稀疏矩阵(graphsage.py):
dataset = gb.BuiltinDataset("ogbn-products").load()
g = dataset.graph
# Create sparse.
N = g.num_nodes
A = dglsp.from_csc(g.csc_indptr, g.indices, shape=(N, N))
dglsp.from_csc(indptr, indices, val=None, shape=None)(sparse_matrix.py)从压缩稀疏列(CSC)格式构造矩阵:对第 i 列,非零元素的行索引存放在 indices[indptr[i]: indptr[i+1]] 中。要点:
indptr形状为(列数 + 1),indices形状为(nnz,);val缺省时自动填充全 1 张量;shape缺省时按(indices.max() + 1, len(indptr) - 1)推断;本教程显式指定(N, N)。
由于 from_csc 内部调用 torch.ops.dgl_sparse.from_csc(C++ 实现),构造出的矩阵可以直接在 CPU/GPU 上参与后续的 sample、compact 与矩阵乘法,而完整示例中还会将 indptr、indices 显式转为 long 类型以匹配算子的类型要求。
第三步:组装 GraphBolt DataLoader
有了采样器之后,其余管道与常规教程一致(graphsage.py):
datapipe = gb.ItemSampler(ids, batch_size=1024)
# Customize graphbolt sampler by sparse.
datapipe = datapipe.sample_sparse_neighbor(A, fanouts)
# Use grapbolt to fetch features.
datapipe = datapipe.fetch_feature(features, node_feature_keys=["feat"])
datapipe = datapipe.copy_to(device)
dataloader = gb.DataLoader(datapipe)
管道各环节作用:
gb.ItemSampler(ids, batch_size=1024):产出种子节点批次;sample_sparse_neighbor(A, fanouts):上一步自定义的稀疏采样器,产出sampled_subgraphs(子矩阵列表);fetch_feature(..., node_feature_keys=["feat"]):抓取子图中节点的特征;copy_to(device):将数据搬运到训练设备;gb.DataLoader(datapipe):包装为可迭代的数据加载器(支持多进程、异步预取)。
这样每个 batch 的数据结构包含 node_features["feat"]、labels 与 sampled_subgraphs 三部分,供模型使用。
第四步:基于稀疏矩阵的 GraphSAGE 模型
文档给出了 SAGEConv 与 SAGE 两层封装(graphsage.py):
class SAGEConv(nn.Module):
r"""GraphSAGE layer from `Inductive Representation Learning on
Large Graphs <https://arxiv.org/pdf/1706.02216.pdf>`__
"""
def __init__(self, in_feats, out_feats):
super(SAGEConv, self).__init__()
self._in_src_feats, self._in_dst_feats = in_feats, in_feats
self._out_feats = out_feats
self.fc_neigh = nn.Linear(self._in_src_feats, out_feats, bias=False)
self.fc_self = nn.Linear(self._in_dst_feats, out_feats, bias=True)
self.reset_parameters()
def reset_parameters(self):
gain = nn.init.calculate_gain("relu")
nn.init.xavier_uniform_(self.fc_self.weight, gain=gain)
nn.init.xavier_uniform_(self.fc_neigh.weight, gain=gain)
def forward(self, A, feat):
feat_src = feat
feat_dst = feat[: A.shape[1]]
# Aggregator type: mean.
srcdata = self.fc_neigh(feat_src)
# Divided by degree.
D_hat = dglsp.diag(A.sum(0)) ** -1
A_div = A @ D_hat
# Conv neighbors.
dstdata = A_div.T @ srcdata
rst = self.fc_self(feat_dst) + dstdata
return rst
关键实现解读
- 特征切分:
feat_dst = feat[: A.shape[1]]取前shape[1]行作为目标节点特征。由于compact(0)会删除空行,采样子矩阵的行数可能大于列数,但经过压缩重编号后,目标节点(种子节点)对应最靠前的若干行,因此通过截取前缀即可分离目标节点特征。 - 均值聚合的矩阵化表达:
D_hat = dglsp.diag(A.sum(0)) ** -1:A.sum(0)沿第 0 维求和得到每个节点的入度,dglsp.diag(sparse_matrix.py)将其构造为对角稀疏矩阵,再求负一次幂即得到度归一化因子;A_div = A @ D_hat:右乘度对角矩阵,等价于对每一列按入度做归一化;dstdata = A_div.T @ srcdata:转置后与邻居特征矩阵相乘,完成"求和并除以度数"的 mean 聚合。
- 自环与邻居聚合:
fc_self处理自身特征(对应 GCN 风格的 self-loop),fc_neigh处理邻居聚合结果,两者相加得到输出。模型名中的 "gcn" 聚合即指这种自环 + mean 邻居的合并方式。
SAGE 模型把三个 SAGEConv 层串起来,并在前两层之间插入 ReLU 与 Dropout(0.5);forward 中按层索引与 sampled_matrices 列表一一对应地取用对应跳数的子矩阵:
class SAGE(nn.Module):
def __init__(self, in_size, hid_size, out_size):
super().__init__()
self.layers = nn.ModuleList()
# Three-layer GraphSAGE-gcn.
self.layers.append(SAGEConv(in_size, hid_size))
self.layers.append(SAGEConv(hid_size, hid_size))
self.layers.append(SAGEConv(hid_size, out_size))
self.dropout = nn.Dropout(0.5)
self.hid_size = hid_size
self.out_size = out_size
def forward(self, sampled_matrices, x):
hidden_x = x
for layer_idx, (layer, sampled_matrix) in enumerate(
zip(self.layers, sampled_matrices)
):
hidden_x = layer(sampled_matrix, hidden_x)
if layer_idx != len(self.layers) - 1:
hidden_x = F.relu(hidden_x)
hidden_x = self.dropout(hidden_x)
return hidden_x
因为采样器已按"第 1 跳在最前"的顺序存放子矩阵,这里直接 zip(self.layers, sampled_matrices) 即可天然对齐:第 i 层使用第 i 跳的子矩阵。
第五步:训练与评估循环
文档给出了核心训练循环(graphsage.py):
features = dataset.feature
# Create GraphSAGE model.
in_size = features.size("node", None, "feat")[0]
num_classes = dataset.tasks[0].metadata["num_classes"]
out_size = num_classes
model = SAGE(in_size, 256, out_size).to(device)
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3, weight_decay=5e-4)
for epoch in range(10):
model.train()
total_loss = 0
for it, data in enumerate(dataloader):
node_feature = data.node_features["feat"].float()
blocks = data.sampled_subgraphs
y = data.labels
y_hat = model(blocks, node_feature)
loss = F.cross_entropy(y_hat, y)
optimizer.zero_grad()
loss.backward()
optimizer.step()
total_loss += loss.item()
要点:
- 输入特征维度由
dataset.feature.size("node", None, "feat")[0]动态获取,输出维度取自任务元数据num_classes; - 隐层维度 256、三层结构、
lr=1e-3、weight_decay=5e-4、训练 10 个 epoch,均为文档与示例中使用的默认配置; - 每个 batch 中
data.node_features["feat"]是特征,data.sampled_subgraphs是采样出的子矩阵列表(此处变量名沿用blocks,但内容为稀疏矩阵),data.labels是对应标签; - 损失采用
F.cross_entropy,评估指标为多分类准确率(完整示例中使用torchmetrics.functional.accuracy,见 graphsage.py)。
完整示例与运行方式
本文所有代码片段均来自仓库中的完整可运行示例 examples/graphbolt/sparse/graphsage.py,该脚本还额外包含:
argparse参数--mode(cpu/gpu,缺省gpu,无 CUDA 时自动回退 CPU);train/validate/evaluate分离的训练、验证、测试流程;- 训练/验证/测试均使用 fanouts
[10, 10, 10](每跳采样 10 个邻居); - 每轮打印 "Epoch / Loss / Accuracy",最后输出 Test accuracy。
运行方式(仓库内)大致为:
python examples/graphbolt/sparse/graphsage.py --mode gpu
首次运行会通过 gb.BuiltinDataset("ogbn-products") 自动下载 ogbn-products 数据集。该示例的整体流程是:加载整图 → 转换为稀疏矩阵 A → 对训练/验证/测试集分别用 SparseNeighborSampler 采样 1-hop、2-hop、3-hop 子矩阵 → 特征输入三层 SAGE 网络训练与评估。
小结
本篇教程的核心范式可以概括为:用稀疏矩阵的 sample + compact 算子替代传统邻居采样内核。sample 负责随机抽取邻居并产出子矩阵,compact 负责去冗余节点并重编号、同时返回新旧索引映射以驱动下一跳采样;图结构则以 from_csc 构造的 SparseMatrix 承载,模型聚合层全部通过矩阵乘法与 dglsp.diag 完成。这一方案与常规 GraphBolt 管道(ItemSampler → fetch_feature → copy_to → DataLoader)无缝衔接,适合希望以矩阵运算视角统一"采样—聚合"流程的开发者参考。若需要继续深入,可对照阅读 minibatch-custom-sampler.rst(自定义邻居采样器通用范式)与 minibatch-node.rst(常规 GraphBolt 小批量训练),并将 python/dgl/sparse/sparse_matrix.py 中 sample、compact、from_csc、diag 的完整文档作为算子速查手册。