DGL HeteroGraphConv 模块详解:异构图上的关系级消息传递与结果聚合
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 一致,核心包含两部分(见原文档):
- 每条关系
r对应的 DGL NN 模块f_r; - 将同一节点类型从多条关系得到的结果合并的**归约(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)。
实际实现中还有两个值得注意的细节:
mods会被转成nn.ModuleDict注册为子模块,使参数能够被 PyTorch 优化器正常发现(源码注释说明了为何额外保存mod_dict以兼容 canonical edge type 索引)。- 构造时会遍历所有子模块,若其具备
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. 行为要点与注意事项
结合源码与测试,使用时有几点需要注意:
- 关系键形式:
mods的键既可以用边类型字符串,也可以用(stype, etype, dtype)规范三元组;内部_get_module会先按原键查找,找不到且键是三元组时退回用其中etype查找(见 hetero.py)。 - 零入度节点:
HeteroGraphConv构造时会自动对所有支持set_allow_zero_in_degree的子模块开启零入度放行,因此异构图节点入度为零不会报错。 - 空关系 / 空图:无边的关系会被跳过;测试 test_nn.py 验证了将所有边移除后(
g.num_edges() == 0)调用依然安全,返回空的目标类型集合。 - 返回键只含被更新的类型:只有结果列表非空的节点类型才会出现在返回值中。
stack聚合:沿第 2 维(dim=1)堆叠,形状从(N, d)变为(N, k, d),其中k是更新该类型的有效关系数(测试中断言h["game"].shape == (4, 2, 4),即两条关系更新'game')。- 三种后端实现:除 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 节点分类流水线 中查看其在端到端管线中的完整用法。