使用 DGL Sparse 与 GraphBolt 完成 GraphSAGE 小批量训练实战指南

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

使用 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 存储结构封装在采样图中。而本文介绍的方案有两大主要区别:

  1. 采样器不同:本文自定义了一个 SparseNeighborSampler 采样器,它不再调用采样图内置的邻居采样内核,而是直接对稀疏矩阵执行 sample 与 compact 两个算子,从整张图的稀疏矩阵中"切出"所需的子矩阵。
  2. 图的表示不同:整张图被转换为 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)为例,循环执行以下两步:

  1. self.matrix.sample(1, fanout, ids=src):从矩阵的第 1 维(列维度)上,对 src 指定的每一列(即每个种子节点)随机抽取 fanout 个非零元素,得到一个与原始矩阵同形状、仅保留被采样非零元素的稀疏矩阵。随后的 .coalesce() 用于合并重复的索引项。
  2. 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)

管道各环节作用:

  1. gb.ItemSampler(ids, batch_size=1024):产出种子节点批次;
  2. sample_sparse_neighbor(A, fanouts):上一步自定义的稀疏采样器,产出 sampled_subgraphs(子矩阵列表);
  3. fetch_feature(..., node_feature_keys=["feat"]):抓取子图中节点的特征;
  4. copy_to(device):将数据搬运到训练设备;
  5. 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 的完整文档作为算子速查手册。

登录后查看全文
dgl