DGL HeteroGraphConv 模块详解:异构图上的关系级消息传递与结果聚合

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

DGL HeteroGraphConv 模块详解:异构图上的关系级消息传递与结果聚合

导读

HeteroGraphConv 是 DGL(Deep Graph Library)为异构(heterogeneous)图提供的一个模块级封装,它允许你将任意 DGL NN 模块(如 GraphConv、SAGEConv)分别应用到图中每一种关系(relation)上,再按目标节点类型聚合来自多条关系的更新结果。本文基于 docs/source/guide_ko/nn-heterograph.rst 展开,结合 python/dgl/nn/pytorch/hetero.py 的 PyTorch 实现、tests/python/pytorch/nn/test_nn.py 的单元测试以及 examples/pytorch/rgcn-hetero/model.py 的真实用法,讲解其数学形式、实现逻辑、forward 执行流程、聚合函数(sum/max/min/mean/stack)与自定义聚合,并给出可复制的完整代码示例。读完本文,你将能够用 HeteroGraphConv 快速构建 RGCN 等异构图 GNN 模型,并理解其与消息传递级 API multi_update_all 的对应关系。

1. 为什么需要 HeteroGraphConv

在 DGL 中,普通图卷积模块(如 GraphConv)默认作用于同构图。而现实中的图(如用户-商品-店铺网络、知识图谱)通常包含多种节点类型与多种关系,例如:

  • ('user', 'follows', 'user')
  • ('user', 'plays', 'game')
  • ('store', 'sells', 'game')

对于这类异构图,最直接的做法是:把每一种关系单独抽出来形成一张二分子图,对每条关系分别应用一个(可能共享或不共享权重的)NN 模块,最后把同一目标节点类型从多个关系收到的结果聚合起来。这正是 HeteroGraphConv 做的事。

该模块的逻辑与消息传递级 API multi_update_all 一致,核心包含两部分(见原文档):

  1. 每条关系 r 对应的 DGL NN 模块 f_r;
  2. 将同一节点类型从多条关系得到的结果合并的**归约(reduction)/ 聚合(aggregation)**操作。

用公式表示即为:

h_dst^(l+1) = AGG_{r ∈ R, r_dst = dst} ( f_r(g_r, h_r_src^l, h_r_dst^l) )

其中 f_r 是关系 r 的 NN 模块,AGG 是聚合函数。也就是说,目标节点类型 dst 的新特征,是对所有“以 dst 为目标”的关系各自卷积结果做聚合得到的。

2. 核心实现逻辑:从 __init__ 到 forward

2.1 构造:mods 关系映射字典与 aggregate 聚合函数

参考 python/dgl/nn/pytorch/hetero.py,HeteroGraphConv 的构造函数接收两个参数:

class HeteroGraphConv(nn.Module):
    def __init__(self, mods, aggregate='sum'):
        super(HeteroGraphConv, self).__init__()
        self.mods = nn.ModuleDict(mods)
        if isinstance(aggregate, str):
            # An internal function to get common aggregation functions
            self.agg_fn = get_aggregate_fn(aggregate)
        else:
            self.agg_fn = aggregate
  • mods:一个 dict[str, nn.Module],把每种**边类型(关系)**映射到对应的 NN 模块。注意,键既可以是简写的边类型字符串(如 'follows'),也可以是完整的规范边类型三元组 (stype, etype, dtype)(如 ('user', 'follows', 'user')),源码通过 _get_module 兼容两种键形式。
  • aggregate:聚合方式,可以是字符串('sum'、'max'、'min'、'mean'、'stack',默认 'sum'),也可以是自定义的可调用对象(callable)。

实际实现中还有两个值得注意的细节:

  1. mods 会被转成 nn.ModuleDict 注册为子模块,使参数能够被 PyTorch 优化器正常发现(源码注释说明了为何额外保存 mod_dict 以兼容 canonical edge type 索引)。
  2. 构造时会遍历所有子模块,若其具备 set_allow_zero_in_degree 方法,则统一调用 set_allow_zero_in_degree(True),避免异构图中存在入度为零的节点(0-in-degree)时触发断言错误——因为异构图没有通用的加自环规则,DGL 选择直接放行零入度节点。

2.2 forward:额外参数 mod_args 与 mod_kwargs

forward 的完整签名如下(见 python/dgl/nn/pytorch/hetero.py):

def forward(self, g, inputs, mod_args=None, mod_kwargs=None):
    if mod_args is None:
        mod_args = {}
    if mod_kwargs is None:
        mod_kwargs = {}
    outputs = {nty: [] for nty in g.dsttypes}

除了输入图 g 和输入特征 inputs 之外,forward 还接收两个可选字典参数:

  • mod_args:dict[str, tuple],键为边类型,值为传给对应子模块的额外位置参数;
  • mod_kwargs:dict[str, dict],键为边类型,值为传给对应子模块的额外关键字参数。

这两个字典的键与 self.mods 一致,用于在不同关系上以定制化参数调用各自模块。例如在 tests/python/pytorch/nn/test_nn.py 的测试中:

mod_args = {"follows": (1,), "plays": (1,)}
mod_kwargs = {"sells": {"arg2": "abc"}}
h = conv(g, {"user": uf, "game": gf, "store": sf},
         mod_args=mod_args, mod_kwargs=mod_kwargs)

其中 mod1.carg1 == 1、mod3.carg2 == 1 的断言验证了这些额外参数确实被传到了对应关系的子模块中。

2.3 输出字典:一个节点类型对应一个结果列表

outputs 是一个以目标节点类型为键、以列表为值的字典:

outputs = {nty: [] for nty in g.dsttypes}

每个 nty 对应的值之所以是列表,是因为可能有多条关系以 nty 为目标节点类型。此时该节点类型会收到多个输出,HeteroGraphConv 会在最后对这些列表再做一次聚合。例如在 ('user','plays','game') 和 ('store','sells','game') 并存时,'game' 类型的输出列表就有两个元素。

2.4 图类型分派:普通异构图 vs. 子图块(block)

forward 需要区分输入图是普通异构图,还是由邻居采样得到的子图块(block,例如 dgl.to_block 或 dataloader 输出的块):

if g.is_block:
    src_inputs = inputs
    dst_inputs = {k: v[:g.number_of_dst_nodes(k)] for k, v in inputs.items()}
else:
    src_inputs = dst_inputs = inputs
  • 若 g 是 block:源节点特征直接用完整输入 inputs,而目标节点特征只取每个类型前 number_of_dst_nodes(k) 个节点对应的切片(因为 block 中目标节点排在节点列表的最前面);
  • 若 g 是普通异构图:源与目标特征相同,即 src_inputs = dst_inputs = inputs。

该逻辑对应采样式(stochastic training)训练中,HeteroGraphConv 可以直接接收 block 作为输入,从而支持大规模图上的邻居采样训练。

2.5 按 canonical etype 遍历并跳过无效关系

随后按规范边类型遍历图中的所有关系:

for stype, etype, dtype in g.canonical_etypes:
    rel_graph = g[stype, etype, dtype]
    if rel_graph.num_edges() == 0:
        continue
    if stype not in src_inputs or dtype not in dst_inputs:
        continue
    dstdata = self.modsetype,
        *mod_args.get(etype, ()),
        **mod_kwargs.get(etype, {}))
    outputs[dtype].append(dstdata)

关键点(原文档及源码均确认):

  • 每条关系用 canonical_etype,即 (stype, etype, dtype) 三元组表示;用它作为键可以抽取对应的二分子图 rel_graph(g[stype, etype, dtype]);
  • 对二分子图,输入特征以元组 (src_inputs[stype], dst_inputs[dtype]) 形式组织,分别对应源节点特征与目标节点特征;
  • 无边的关系被跳过(rel_graph.num_edges() == 0 时 continue),避免无谓调用;同样,源类型或目标类型不在输入特征字典中时也会跳过;
  • 每个关系对应的 NN 模块被调用后,输出 dstdata 追加到 outputs[dtype] 列表中。

2.6 最后的聚合:agg_fn

遍历完成后,对每个目标节点类型的结果列表执行聚合:

rsts = {}
for nty, alist in outputs.items():
    if len(alist) != 0:
        rsts[nty] = self.agg_fn(alist, nty)

只有列表非空的目标类型才会出现在返回字典 rsts 中,即只返回被更新过的节点类型。例如只输入 'store' 特征时,只有 'game' 类型会被更新。

3. 聚合函数:五种内置策略与自定义聚合

聚合函数由 get_aggregate_fn(见 python/dgl/nn/pytorch/hetero.py)根据字符串生成,DGL 支持以下取值:

聚合方式 说明 输出形状(输入列表长度为 k、特征维度为 d 时)
'sum' 按元素求和 (N, d)
'max' 按元素取最大 (N, d)
'min' 按元素取最小 (N, d)
'mean' 按元素取平均 (N, d)
'stack' 沿第 2 维堆叠,顺序确定 (N, k, d)

内置实现通过 th.stack(inputs, dim=0) 后沿 dim=0 做归约(_sum_reduce_func、_max_reduce_func、_min_reduce_func、_mean_reduce_func),'stack' 则使用 _stack_agg_func 沿 dim=1 堆叠。若传入非法字符串,会抛出 DGLError 提示必须是 "sum", "max", "min", "mean" 或 "stack"。

除了字符串,aggregate 也可以传自定义可调用对象,其签名为 func(tensors, dsttype),其中 tensors 是待聚合的张量列表,dsttype 是目标节点类型名。例如求和聚合等价于:

def my_agg_func(tensors, dsttype):
    # tensors: 待聚合的张量列表
    # dsttype: 聚合针对的目标节点类型名
    stacked = torch.stack(tensors, dim=0)
    return torch.sum(stacked, dim=0)

test_nn.py 中同样定义了自定义聚合函数 myagg,并用 @pytest.mark.parametrize("agg", ["sum", "max", "min", "mean", "stack", myagg]) 对全部内置策略和自定义策略做了形状断言测试,覆盖普通图与 block 两种输入。

4. 完整可运行的实战示例

4.1 基本用法(来自模块 docstring)

创建一个包含三种关系的异构图并应用 HeteroGraphConv(参考 hetero.py 的官方示例):

import dgl
import torch as th
import dgl.nn.pytorch as dglnn

# 1) 创建异构图:('user','follows','user')、('user','plays','game')、('store','sells','game')
edges1 = ([0, 0, 2, 1], [1, 2, 1, 3])
edges2 = ([0, 0, 0, 1, 2], [0, 2, 3, 0, 2])
edges3 = ([0, 0, 1, 1], [0, 3, 1, 2])
g = dgl.heterograph({
    ('user', 'follows', 'user'): edges1,
    ('user', 'plays', 'game'): edges2,
    ('store', 'sells', 'game'): edges3,
})

# 2) 为每条关系指定各自的卷积模块('follows' 与 'plays' 不共享权重)
conv = dglnn.HeteroGraphConv({
    'follows': dglnn.GraphConv(5, 5, allow_zero_in_degree=True),
    'plays':   dglnn.GraphConv(5, 5, allow_zero_in_degree=True),
    'sells':   dglnn.SAGEConv(5, 5, 'gcn'),
}, aggregate='sum')

# 3) 只提供 'user' 特征 → 同时更新 'user' 与 'game'
h1 = {'user': th.randn((g.num_nodes('user'), 5))}
h2 = conv(g, h1)
print(h2.keys())          # dict_keys(['user', 'game'])

# 4) 同时提供 'user' 与 'store' 特征 → 'plays' 与 'sells' 都会更新 'game',结果按 sum 聚合
f1 = {'user': th.randn((g.num_nodes('user'), 5)),
      'store': th.randn((g.num_nodes('store'), 5))}
f2 = conv(g, f1)
print(f2.keys())          # dict_keys(['user', 'game'])

# 5) 只提供 'store' 特征 → 只更新 'game'
g1 = {'store': th.randn((g.num_nodes('store'), 5))}
g2 = conv(g, g1)
print(g2.keys())          # dict_keys(['game'])

# 6) 也支持 (src, dst) 成对输入,各子模块同样收到成对输入
x_src = {'user': ..., 'store': ...}
x_dst = {'user': ..., 'game': ...}
y_dst = conv(g, (x_src, x_dst))
print(y_dst.keys())       # dict_keys(['user', 'game'])

HeteroGraphConv 中每个子模块的 forward 必须满足:第一个参数是 DGLGraph 对象,第二个参数是一个张量(节点特征)或一对张量(源/目标节点特征)。这正是 GraphConv、SAGEConv 等内置模块的约定。

4.2 与 block(子图块)配合:支持邻居采样训练

将图转为 block 后同样可以直接传入 HeteroGraphConv(与测试 test_nn.py 的用法一致):

block = dgl.to_block(g, {'user': [0, 1, 2, 3], 'game': [0, 1, 2, 3], 'store': []})
h = conv(block, (
    {'user': uf, 'game': gf, 'store': sf},      # 源节点特征
    {'user': uf, 'game': gf, 'store': sf[0:0]}, # 目标节点特征(block 会自行切片)
))

该能力使 HeteroGraphConv 可以无缝嵌入 DGL 的邻居采样 dataloader 训练管线中。

4.3 实战:用 HeteroGraphConv 构建 RGCN 层

真实项目中,examples/pytorch/rgcn-hetero/model.py(model.py)用字典推导式为每种关系创建一个 GraphConv,再包进 HeteroGraphConv,构成 RGCN 的一层:

self.conv = dglnn.HeteroGraphConv(
    {
        rel: dglnn.GraphConv(
            in_feat, out_feat, norm="right", weight=False, bias=False
        )
        for rel in rel_names
    }
)

随后通过 WeightBasis 或逐关系权重矩阵实现共享/基底分解(basis decomposition),即经典 RGCN 的权重共享策略。这种“逐关系子模块 + 全局聚合”的组合正是 HeteroGraphConv 最典型的应用场景。同样的模式也出现在 examples/pytorch/rgat、examples/pytorch/ogb/ogbn-mag/hetero_rgcn.py 等异构图示例中。

5. 行为要点与注意事项

结合源码与测试,使用时有几点需要注意:

  1. 关系键形式:mods 的键既可以用边类型字符串,也可以用 (stype, etype, dtype) 规范三元组;内部 _get_module 会先按原键查找,找不到且键是三元组时退回用其中 etype 查找(见 hetero.py)。
  2. 零入度节点:HeteroGraphConv 构造时会自动对所有支持 set_allow_zero_in_degree 的子模块开启零入度放行,因此异构图节点入度为零不会报错。
  3. 空关系 / 空图:无边的关系会被跳过;测试 test_nn.py 验证了将所有边移除后(g.num_edges() == 0)调用依然安全,返回空的目标类型集合。
  4. 返回键只含被更新的类型:只有结果列表非空的节点类型才会出现在返回值中。
  5. stack 聚合:沿第 2 维(dim=1)堆叠,形状从 (N, d) 变为 (N, k, d),其中 k 是更新该类型的有效关系数(测试中断言 h["game"].shape == (4, 2, 4),即两条关系更新 'game')。
  6. 三种后端实现:除 PyTorch 外,DGL 还提供了 MXNet 与 TensorFlow 后端版本,分别位于 python/dgl/nn/mxnet/hetero.py 和 python/dgl/nn/tensorflow/hetero.py,接口保持一致;本文以 PyTorch 版为准。

6. 小结

HeteroGraphConv 是 DGL 异构 GNN 建模的核心模块:它把“对每条关系独立做图卷积、再按目标节点类型聚合”这一通用范式封装为模块,与消息传递级 API multi_update_all 逻辑一致,但以 nn.Module 的形式融入深度学习框架的建模与训练流程。通过 mods 字典定制各关系的子模块、通过 aggregate 参数(sum/max/min/mean/stack 或自定义函数)控制跨关系聚合、通过 mod_args/mod_kwargs 传递关系级定制参数,并天然兼容邻居采样产出的 block 输入,HeteroGraphConv 可支撑从 RGCN 到各类异构图模型的快速搭建。更多 API 细节可查阅 nn-heterograph 英文版 与模块文档字符串,也可在 dglgo 节点分类流水线 中查看其在端到端管线中的完整用法。

登录后查看全文
dgl