企业官网建设流程全解析

1. 先搞清楚异构图到底“异”在哪里

从0到1用PyG创建异构图，最忌讳一上来就抄代码。你得先弄明白异构图和普通图有什么区别，不然写出来的模型大概率是“看起来在分类，实际上瞎猜”。

如果你接触过图神经网络，大概率用过PyG里的Data类：一个edge_index存边，一个x存节点特征，完事。这种图叫同构图，也就是整个图里只有一种节点、一种边。像社交网络的好友关系，节点都是用户，边都是“关注”，同构图够了。

但真实业务里几乎没有这么干净的数据。拿电商举例：有用户，有商品，有店铺。用户买商品，用户收藏商品，商品属于店铺。这里就有三种节点类型，三种边类型。你要是硬把三种节点揉成一个Data，特征维度都不一样，模型根本没法训。这就是异构图存在的意义——它允许图中同时存在多种类型的节点和多种类型的边。

PyG专门为这件事提供了HeteroData类，它的设计思路很简单：用字典的方式，按“类型”把不同节点和边分开存。比如data['user'].x存用户特征，data['item'].x存商品特征，data['user', 'buy', 'item'].edge_index存用户到商品的购买关系。每种类型各管各的，既清晰又不互相污染。

这篇文章我会从零开始，手把手带你建一个电商场景的异构图，然后把它喂给GNN模型做节点分类。整个过程不跳步骤，每段代码都会解释为什么这么写、背后是什么原理。适合刚入门GNN、被异构图各种报错折磨过、以及想系统搞懂PyG异构图写法的读者。

2. 为什么PyG要用HeteroData而不是Data

2.1 从同构图到异构图，数据结构发生了什么变化

同构图的Data对象里，edge_index是一个形状为[2, num_edges]的张量，第一行是源节点索引，第二行是目标节点索引。这个定义隐含了一个假设：所有边都是同一类关系，所有节点都在同一个特征空间里。

到了异构图，这个假设不成立了。不同类型的节点特征维度可能不同，比如用户有128维属性，商品有256维属性，店铺只有32维属性。如果硬放在同一个张量里，只能做padding，不仅浪费内存，还会给模型引入大量无意义的零值，训练效果奇差。

HeteroData的解决办法是：每个节点类型单独维护一个特征矩阵，每条边类型单独维护一个edge_index。它内部是这样组织的：

HeteroData( user={ x=[1000, 128] }, item={ x=[5000, 256] }, shop={ x=[100, 32] }, (user, buy, item)={ edge_index=[2, 20000] }, (user, collect, item)={ edge_index=[2, 5000] }, (item, belong, shop)={ edge_index=[2, 5000] } )

你可以把HeteroData理解成一个多层文件柜：每个节点类型是一个抽屉，每个边类型也是一个抽屉，各自装各自的东西，互不干扰。这种设计的最大好处是，模型在消息传递阶段可以分别对不同类型的关系做不同的变换，而不是把所有信息混在一起。

2.2 HeteroData底层的存储方式

PyG的HeteroData并不是一个黑盒，它内部有两个核心属性：_node_types和_edge_types，分别记录当前图里有哪些节点类型和边类型。当你执行data['user'].x = ...时，PyG会检查'user'是否在_node_types里，如果不在，会自动注册一个新的节点类型，并把x塞进去。

同理，data['user', 'buy', 'item'].edge_index = ...会注册一条新的边类型。这里有个容易踩坑的点：PyG要求边类型必须是三元组(source_node_type, edge_type, target_node_type)，不能是二元组。我见过有人写data['like'].edge_index = ...，结果直接报错KeyError: 'like'，就是因为少了source和target的声明。

还有一个细节：同一种关系如果方向相反，在PyG里是不同的边类型。比如“用户关注商品”和“商品被用户关注”，在语义上可能是一回事，但在PyG里一个写作('user', 'follow', 'item')，另一个写作('item', 'followed_by', 'user')。如果你需要模型同时利用两个方向的信息，就要把两条边都加上，或者用to_homogeneous()之后再自己做对称化。

2.3 版本差异：HeteroData的API进化

PyG的异构图API在2.0之后逐渐稳定下来，但不同版本之间还是有一些小差异。老版本里，创建节点类型要写data['user'] = NodeStore()或者data['user'].num_nodes = 1000，新版本直接data['user'].x = ...就可以了。

我建议你直接用最新的稳定版，并且锁定版本号。我自己项目里用的是torch-geometric>=2.3，下面的代码都是基于这个版本写的。如果你还在用老版本，遇到TypeError: 'HeteroData' object does not support item assignment这种报错，别慌，先升级版本再说：

pip install torch-geometric --upgrade

升级之后，老代码里data['user'].num_nodes = ...的写法可能会失效，因为新版不再显式要求你声明节点数，而是通过x的第一维自动推断。如果你的节点没有特征，只想知道节点数，就用data['user'].num_nodes = 1000，这个在新版里依然支持。

3. HeteroData的核心细节与实操要点

3.1 创建空HeteroData对象

一切从HeteroData()开始：

from torch_geometric.data import HeteroData data = HeteroData()

这时候data是完全空的。你执行print(data)，会看到输出只有一行HeteroData()，没有任何类型信息。不用担心，接下来每添加一个类型的节点或边，print(data)就会自动更新，把当前的节点类型、边类型、张量形状都列出来，这个功能非常实用，调试的时候多用它。

3.2 添加节点特征

给异构图添加节点类型，本质上就是给它赋一个属性。比如：

import torch data['user'].x = torch.randn(1000, 128) # 1000个用户，128维特征 data['item'].x = torch.randn(5000, 256) # 5000个商品，256维特征 data['shop'].x = torch.randn(100, 32) # 100个店铺，32维特征

这里有几个要点：

第一，x必须是torch.Tensor，不能是numpy数组，也不能是list。这个错误新手常犯，PyG底层的消息传递机制默认输入是Tensor，你传numpy数组进去，运行时才报错，排查起来比较费劲。

第二，不同节点类型的特征维度可以不一样。user是128维，item是256维，shop是32维，这在HeteroData里完全合法。真正训练的时候，模型的第一层会对每个类型单独做线性变换，把不同维度统一到一个隐藏层维度。

第三，如果你的某个节点类型没有特征，可以用torch.nn.Embedding生成可学习的嵌入向量，或者直接赋一个全零矩阵。但要注意，全零矩阵在梯度传播时会产生梯度，不过所有节点初始状态相同，可能导致训练初期模型很难区分节点，我一般建议至少用随机初始化。

3.3 添加边索引

边索引的格式和同构图一样，都是[2, num_edges]的张量，第一行是源节点索引，第二行是目标节点索引。在异构图里，这个索引是对应节点类型自己的索引，不是整个图的全局索引。

# 用户到商品的购买关系：1000个用户，5000个商品 user_buy_item_edge_index = torch.randint(0, 1000, (2, 20000)) user_buy_item_edge_index[1] = torch.randint(0, 5000, (1, 20000)) data['user', 'buy', 'item'].edge_index = user_buy_item_edge_index

上面这段代码有个小问题：第一行生成了[2, 20000]的随机张量，两行都是从0到999，然后第二行把目标节点索引重新赋值为0到4999。这样做虽然能跑通，但实际业务中边的关系不是随机的，你需要根据自己的数据来构造。

这里我重点想说的是索引的语义。edge_index[0]里的值，指的是'user'节点类型的节点编号，从0到999；edge_index[1]里的值，指的是'item'节点类型的节点编号，从0到4999。PyG不会像同构图那样要求全局节点ID连续，因为不同类型本来就该分开编号。

3.4 添加边特征

边特征是可选的，但很多场景下非常有用。比如购买关系可以带一个“购买时间”的权重，收藏关系可以带一个“收藏来源”的属性。

data['user', 'buy', 'item'].edge_attr = torch.randn(20000, 8) data['user', 'collect', 'item'].edge_attr = torch.randn(5000, 4)

因为不同边的特征维度也可以不同，所以edge_attr的维度设计比较灵活。需要注意的是，如果你的模型需要统一处理边特征，比如把所有边特征拼接后再过一层MLP，那不同边类型的特征维度最好保持一致，或者在模型里分别处理。

3.5 查看和修改已有数据

写代码的时候我最常干的事就是print(data)。它会输出类似这样的内容：

HeteroData( user={ x=[1000, 128] }, item={ x=[5000, 256] }, shop={ x=[100, 32] }, (user, buy, item)={ edge_index=[2, 20000], edge_attr=[20000, 8] }, (user, collect, item)={ edge_index=[2, 5000], edge_attr=[5000, 4] }, (item, belong, shop)={ edge_index=[2, 5000] }, num_nodes_list=[1000, 5000, 100], num_edges_list=[20000, 5000, 5000] )

看到这个输出，你就能快速确认每种类型的数据是否齐全、维度是否合理。

修改数据也很简单，直接重新赋值：

data['user'].x = torch.randn(1000, 256) # 把用户特征改成256维 del data['user', 'collect', 'item'] # 删除收藏关系

这里有个坑：当你删除一种边类型后，data.metadata()返回的edge_types列表会自动更新，但你如果有其他地方引用了这个边类型的名字，就会报错。所以删除操作要谨慎，最好在数据预处理阶段完成，不要在模型训练过程中做。

3.6 规范化：给异构图补全缺失属性

PyG提供了一个normalize()方法，主要作用是给边加上归一化系数。这个对GCN这类需要归一化邻接矩阵的模型特别重要：

data = data.normalize()

normalize()的运行逻辑是：遍历所有边类型，对每类边单独计算度的归一化系数，并把结果存在edge_norm里。注意，这个操作会修改原有数据，所以如果你需要保留原始图结构，建议先复制一份再调用。

4. 从零构建一个电商异构图：完整实操

4.1 定义场景

我以一个简化版电商场景为例：有1000个用户、5000个商品、100个店铺。三种关系：用户购买商品、用户收藏商品、商品属于店铺。目标是利用这些关系，对商品做类别预测（比如“电子产品”“服装”“食品”）。

这个场景覆盖了异构图里最典型的模式：既有用户和商品之间的交互边，也有商品和店铺之间的归属边，模型能同时学到用户兴趣和店铺属性对商品类别的影响。

4.2 构造节点数据

真实数据里，用户特征可能是年龄、性别、注册天数等；商品特征可能是价格、点击量、销量等；店铺特征可能是开店时长、评分等。这里我用随机张量代替，但维度设计尽量贴近真实场景：

import torch from torch_geometric.data import HeteroData data = HeteroData() # 用户：1000个，特征维度128 data['user'].x = torch.randn(1000, 128) # 商品：5000个，特征维度256 data['item'].x = torch.randn(5000, 256) # 店铺：100个，特征维度32 data['shop'].x = torch.randn(100, 32) # 商品类别标签：5个类别，用于训练和评估 data['item'].y = torch.randint(0, 5, (5000,))

这里多了一个y属性，这是节点标签。同构图里标签通常叫data.y，异构图里每个节点类型都可以有自己的标签。我这里只给商品加了标签，因为我们要做的是商品分类。如果你需要对用户做分类，就再给data['user'].y赋值。

4.3 构造边数据

边数据的构造需要一点技巧。现实中，用户购买商品、用户收藏商品的关系是从行为日志里统计出来的，不会像下面这么随机。这里为了示例能直接跑通，用随机生成的方式模拟：

# 用户购买商品：20000条边 buy_edge_index = torch.stack([ torch.randint(0, 1000, (20000,)), torch.randint(0, 5000, (20000,)) ], dim=0) # 用户收藏商品：5000条边 collect_edge_index = torch.stack([ torch.randint(0, 1000, (5000,)), torch.randint(0, 5000, (5000,)) ], dim=0) # 商品属于店铺：每个商品随机属于一个店铺 belong_edge_index = torch.stack([ torch.arange(5000), torch.randint(0, 100, (5000,)) ], dim=0) data['user', 'buy', 'item'].edge_index = buy_edge_index data['user', 'collect', 'item'].edge_index = collect_edge_index data['item', 'belong', 'shop'].edge_index = belong_edge_index

注意belong_edge_index的构造方式：源节点是商品索引torch.arange(5000)，目标节点是店铺索引。这保证每个商品恰好有一条归属边。实际业务中一个商品可能属于多个店铺（比如分销场景），那就需要有多条边，源节点索引会有重复。

4.4 加上边特征

为了让模型有更多信息可用，我给边加上权重：

# 购买时长权重：值越大表示购买行为越近 data['user', 'buy', 'item'].edge_attr = torch.rand(20000, 1) + 0.5 # 收藏来源权重：1表示APP内收藏，2表示网页端收藏 data['user', 'collect', 'item'].edge_attr = torch.randint(1, 3, (5000, 1)).float()

这里我特意让两种边特征的维度不同：购买边的edge_attr是1维，收藏边的是1维但语义不同。PyG不要求不同边类型的特征维度一致，但你在构建模型时得自己处理这种不一致。

4.5 数据预处理与规范化

在喂给模型之前，我一般会做两件事：检查和规范化。

# 检查数据的metadata node_types, edge_types = data.metadata() print("Node types:", node_types) print("Edge types:", edge_types) # 规范化边权重 data = data.normalize()

metadata()返回两个元组，分别包含所有节点类型和边类型。这个信息非常重要，因为后面定义模型的时候，你需要知道模型需要处理哪些类型的边。

normalize()会把所有边类型的edge_norm计算出来并存储。这一步对于GCN来说很关键，因为GCN的卷积操作默认会使用归一化后的邻接矩阵。如果你用的是GAT或者GraphSAGE，归一化不是必须的，但做了也没坏处。

4.6 将异构图转为同构图

有些模型只支持同构图，比如普通的GCNConv、GraphSAGE。如果想把它们用在这个异构图上，得先把异构图“压扁”成同构图。PyG提供了to_homogeneous()方法：

from torch_geometric.transforms import ToUndirected # 先转成无向图，让消息能双向传播 data_undirected = ToUndirected()(data) # 再转成同构图 homogeneous_data = data_undirected.to_homogeneous()

to_homogeneous()的返回值里，x是所有节点特征拼接在一起的大矩阵，edge_index是所有边拼接后的全局索引。它会重新排列节点ID，让不同节点类型的节点在一个统一的ID空间里。同时，返回的node_type张量记录了每个节点原本属于哪个类型。

但这里有个大坑：如果不同节点类型的特征维度不一样，to_homogeneous()会直接报错，因为它没法把128维的向量和256维的向量拼成一个矩阵。解决办法有两种：

第一种，把所有节点的特征统一到相同维度：

from torch_geometric.nn import Linear user_x = data['user'].x item_x = data['item'].x shop_x = data['shop'].x # 都映射到64维 user_x = Linear(128, 64)(user_x) item_x = Linear(256, 64)(item_x) shop_x = Linear(32, 64)(shop_x) data['user'].x = user_x data['item'].x = item_x data['shop'].x = shop_x homogeneous_data = data.to_homogeneous()

第二种，直接用支持异构图的模型层，比如HGTConv、RGCNConv，这些模型内部会分别处理不同类型节点的特征维度，不需要你手动统一。我建议优先用第二种，因为第一种做线性变换时容易丢失信息，而且多了很多需要调的超参数。

4.7 完整可运行的构建代码

整合起来，整个构建过程就是下面这段代码。你可以直接复制运行：

import torch from torch_geometric.data import HeteroData def build_ecommerce_graph(): data = HeteroData() # 节点 data['user'].x = torch.randn(1000, 128) data['item'].x = torch.randn(5000, 256) data['shop'].x = torch.randn(100, 32) data['item'].y = torch.randint(0, 5, (5000,)) # 边 data['user', 'buy', 'item'].edge_index = torch.stack([ torch.randint(0, 1000, (20000,)), torch.randint(0, 5000, (20000,)) ], dim=0) data['user', 'collect', 'item'].edge_index = torch.stack([ torch.randint(0, 1000, (5000,)), torch.randint(0, 5000, (5000,)) ], dim=0) data['item', 'belong', 'shop'].edge_index = torch.stack([ torch.arange(5000), torch.randint(0, 100, (5000,)) ], dim=0) # 边特征 data['user', 'buy', 'item'].edge_attr = torch.rand(20000, 1) + 0.5 data['user', 'collect', 'item'].edge_attr = torch.randint(1, 3, (5000, 1)).float() return data data = build_ecommerce_graph() print(data)

运行这段代码，你会看到一个结构清晰的异构图数据对象。这就是我们后面所有步骤的基础。

5. 将异构图接入GNN模型：三种实战方案

5.1 最简单：用to_hetero包装同构GNN

PyG提供一个非常巧妙的装饰器方法to_hetero()，它能把一个同构GNN自动转换成异构图版本。它的原理是：将同一个GNN层复制多份，每一份处理一种边类型，边类型之间的参数不共享（或者可以配置共享策略）。

from torch_geometric.nn import GCNConv, to_hetero import torch.nn.functional as F class GCN(torch.nn.Module): def __init__(self, in_channels, hidden_channels, out_channels): super().__init__() self.conv1 = GCNConv(in_channels, hidden_channels) self.conv2 = GCNConv(hidden_channels, out_channels) def forward(self, x, edge_index): x = self.conv1(x, edge_index) x = F.relu(x) x = self.conv2(x, edge_index) return x model = to_hetero(GCN(128, 64, 5), data.metadata(), aggr='sum')

to_hetero接收三个参数：第一个是模型实例，第二个是metadata()的返回值，第三个是不同边类型消息聚合的方式，默认是'sum'，也可以选'mean'、'max'。它会根据metadata自动把所有边类型和节点类型对应到模型里。

这个方案的优点是省事，你只需要写一个普通的GCN模型，剩下的交给PyG处理。缺点是它假设每种边类型用的是同一个GCN层结构，只是参数不同，这限制了模型的表达能力。

5.2 进阶：使用异构图专用卷积层

如果数据关系比较复杂，我推荐直接用RGCNConv（关系图卷积网络）。它是专门为多关系图设计的，每条边带一个关系类型，模型会根据关系类型选择不同的变换矩阵。

from torch_geometric.nn import RGCNConv class RGCN(torch.nn.Module): def __init__(self, in_channels, hidden_channels, out_channels, num_relations): super().__init__() self.conv1 = RGCNConv(in_channels, hidden_channels, num_relations) self.conv2 = RGCNConv(hidden_channels, out_channels, num_relations) def forward(self, x, edge_index, edge_type): x = self.conv1(x, edge_index, edge_type) x = F.relu(x) x = self.conv2(x, edge_index, edge_type) return x

但要注意，RGCNConv要求所有节点的特征维度一致。所以你要把user、item、shop的特征统一到相同维度，比如都映射到128维，然后拼接成一个大的x矩阵，同时构造一个global_edge_index，把所有边类型合并成一个大边索引，再用edge_type来区分每个边属于哪类关系。

这个方法的好处是关系建模更精细，缺点是数据预处理比较繁琐。你需要自己写一个合并函数：

def merge_to_rgcn(data): # 统一节点特征维度 user_x = torch.nn.Linear(128, 128)(data['user'].x) item_x = torch.nn.Linear(256, 128)(data['item'].x) shop_x = torch.nn.Linear(32, 128)(data['shop'].x) # 节点编号偏移 offset = { 'user': 0, 'item': 1000, 'shop': 6000 } x = torch.cat([user_x, item_x, shop_x], dim=0) edge_indexes = [] edge_types = [] for i, edge_type in enumerate(data.edge_types): src, rel, dst = edge_type ei = data[edge_type].edge_index.clone() ei[0] += offset[src] ei[1] += offset[dst] edge_indexes.append(ei) edge_types.append(torch.full((ei.size(1),), i, dtype=torch.long)) global_edge_index = torch.cat(edge_indexes, dim=1) global_edge_type = torch.cat(edge_types, dim=0) return x, global_edge_index, global_edge_type

这种方案适合那种关系类型不多、但每种关系都很重要的场景。像我们的电商例子里三种关系，用RGCN就很合适。

5.3 实战：基于HGTConv的异构图节点分类

HGT（Heterogeneous Graph Transformer）是目前公认效果非常好的异构图神经网络模型，PyG里有现成的HGTConv。它的核心思想是：对不同节点类型用不同的线性变换，对不同边类型用不同的attention权重，让模型能自主判断哪种关系更重要。

下面写一个完整的商品分类训练脚本：

import torch.nn.functional as F from torch_geometric.nn import HGTConv class HGT(torch.nn.Module): def __init__(self, hidden_channels, out_channels, num_heads, num_layers, metadata): super().__init__() self.lin_dict = torch.nn.ModuleDict() for node_type in metadata[0]: # 每种节点类型先各自映射到hidden_channels if node_type == 'user': in_channels = 128 elif node_type == 'item': in_channels = 256 elif node_type == 'shop': in_channels = 32 else: in_channels = hidden_channels self.lin_dict[node_type] = torch.nn.Linear(in_channels, hidden_channels) self.convs = torch.nn.ModuleList() for _ in range(num_layers): conv = HGTConv(hidden_channels, hidden_channels, metadata, num_heads) self.convs.append(conv) self.out_lin = torch.nn.Linear(hidden_channels, out_channels) def forward(self, x_dict, edge_index_dict): # 第一步：不同节点类型映射到同一维度 x_dict = { node_type: self.lin_dict[node_type](x) for node_type, x in x_dict.items() } # 第二步：多层HGT卷积 for conv in self.convs: x_dict = conv(x_dict, edge_index_dict) # 第三步：只对商品类型做分类 return self.out_lin(x_dict['item'])

训练的时候，要注意x_dict是每种节点类型的特征字典，edge_index_dict是每种边类型的edge_index字典。PyG的HGTConv内部会处理不同节点类型之间的信息传播。

训练循环和普通PyTorch差不多：

model = HGT(hidden_channels=64, out_channels=5, num_heads=4, num_layers=2, metadata=data.metadata()) optimizer = torch.optim.Adam(model.parameters(), lr=0.001) loss_fn = torch.nn.CrossEntropyLoss() def train(): model.train() optimizer.zero_grad() # x_dict: {'user': ..., 'item': ..., 'shop': ...} x_dict = {node_type: data[node_type].x for node_type in data.node_types} edge_index_dict = {edge_type: data[edge_type].edge_index for edge_type in data.edge_types} logits = model(x_dict, edge_index_dict) # 只有商品有标签 loss = loss_fn(logits, data['item'].y) loss.backward() optimizer.step() return loss.item() for epoch in range(200): loss = train() if epoch % 20 == 0: print(f'Epoch {epoch:03d}, Loss: {loss:.4f}')

现有数据集里面商品标签是全部存在的，但实际运用中一般只有一部分节点有标签，另一部分用来做验证和测试。这时候你需要自己划分训练集和测试集，只对训练集部分计算loss。具体做法就是用一个train_mask掩码，只取logits[train_mask]和labels[train_mask]进行计算。

5.4 模型训练时最容易被忽略的两个细节

第一个细节是特征的类型。data['item'].y如果是torch.long类型，交叉熵损失函数才能正确处理。如果你构建数据时用了浮点数，比如torch.randn生成后再四舍五入，就会在计算损失时得到RuntimeError，提示“Expected long but got float”。解决办法很简单：

data['item'].y = data['item'].y.long()

第二个细节是特征归一化。GNN对特征尺度很敏感，尤其是HGT这种带attention的模型。我习惯在构造数据时，对每个节点类型的特征单独做一次标准化：

data['user'].x = (data['user'].x - data['user'].x.mean(dim=0)) / data['user'].x.std(dim=0) data['item'].x = (data['item'].x - data['item'].x.mean(dim=0)) / data['item'].x.std(dim=0) data['shop'].x = (data['shop'].x - data['shop'].x.mean(dim=0)) / data['shop'].x.std(dim=0)

如果不做标准化，数值范围差异大的特征会在梯度下降中占主导位置，模型训练容易不稳。

6. 常见问题与排查技巧实录

6.1 报错KeyError: 'user'，明明我赋值了

这个报错通常发生在你创建了HeteroData()之后，还没赋值就想访问对应类型的数据。比如：

data = HeteroData() print(data['user'].x) # KeyError: 'user'

原因很简单：HeteroData刚开始是空的，你只有先赋值data['user'].x = ...，PyG才会注册'user'这个节点类型。如果你想预声明一个空类型，可以用data['user'].num_nodes = 1000来注册。但这个需求比较少，因为大多数场景下你都会有节点特征。

6.2 边索引越界但不报错

这是最坑的一个问题。PyG在构造HeteroData时不会自动检查edge_index的索引是否在合法范围内，也就是说edge_index[0]的最大值可以大于对应节点类型的节点数。这时候前向传播时通常不会报错，因为PyG在消息传递时会做索引查找，如果索引超出范围，可能会返回nan，也可能把内存里的脏数据读进来，导致训练结果完全不可信。

排查方法是加一个简单的断言：

for edge_type in data.edge_types: src, _, dst = edge_type num_src = data[src].num_nodes num_dst = data[dst].num_nodes ei = data[edge_type].edge_index assert ei[0].max() < num_src, f"Source index out of range for {edge_type}" assert ei[1].max() < num_dst, f"Target index out of range for {edge_type}"

把这个检查放到构建数据后、训练前，能省去很多排查时间。

6.3 to_homogeneous()时特征维度不一致

前面提过这个问题。to_homogeneous()要求所有节点类型的特征维度一致，否则直接抛RuntimeError。如果你确实需要转同构图，又不想做特征映射，可以考虑只保留一部分特征，或者用无特征的图：

# 只保留结构信息，不保留特征 no_feat_data = data.clone() for node_type in no_feat_data.node_types: del no_feat_data[node_type].x homogeneous = no_feat_data.to_homogeneous()

这样得到的同构图只有edge_index，x为None。你可以后续用torch.nn.Embedding为所有节点生成统一的嵌入特征。但注意，这时候模型不知道节点的原始类型，完全靠图结构来区分，效果通常会打折扣。

6.4 大数据集上内存爆炸

异构图因为节点类型多，消息传递时往往比同构图更消耗内存。如果你要在大规模数据上训练，建议使用NeighborLoader进行邻居采样：

from torch_geometric.loader import NeighborLoader loader = NeighborLoader( data, num_neighbors=[10, 5], # 每层采样10个和5个邻居 input_nodes=('item', data['item'].train_mask), batch_size=128, shuffle=True, )

NeighborLoader是PyG专门为异构图设计的采样器，支持按节点类型采样。常用的参数是num_neighbors，列表长度等于GNN层数，每一层的值表示该层每个节点采样多少邻居。这样每个batch只包含采样出来的子图，内存占用可以控制在一个稳定的水平。

6.5 模型加了边特征却没用上

很多人在异构图里加了edge_attr，但模型里没有使用它。PyG的HGTConv默认不支持边特征，它只使用edge_index。如果你想利用边特征，要么选择支持边特征的层，比如GATConv搭配edge_dim参数，要么自己在消息传递前手动拼接：

# 手动使用边特征示例：简单拼接 class EdgeAwareConv(torch.nn.Module): def __init__(self, in_channels, edge_channels, out_channels): super().__init__() self.lin = torch.nn.Linear(in_channels + edge_channels, out_channels) def forward(self, x, edge_index, edge_attr): row, col = edge_index # 拼接源节点特征和边特征 msg = torch.cat([x[row], edge_attr], dim=-1) msg = self.lin(msg) return torch.zeros_like(x).index_add_(0, col, msg)

当然，这只是演示，实际项目中直接用现成的TransformerConv更省事。

6.6 训练loss正常但准确率很低

如果你发现模型loss在下降，但验证集准确率迟迟上不去，先别怀疑模型结构，大概率是图数据构造有问题。我踩过的坑是：边索引是随机生成的，导致图中没有真正的社区结构，模型学不到有用信息。另一个常见问题是标签和边关系完全没关联，比如商品类别和用户购买行为没有语义关系，模型当然学不好。

解决办法：先做一个简单的启发式baseline，比如直接用商品特征训练一个MLP，看效果如何。如果MLP的效果比GNN还好，说明图结构没有提供额外信息，问题多半出在数据构造上。

7. 给新手的几条实操建议

7.1 从打印HeteroData开始

我每次拿到一个新的异构图数据，第一件事就是print(data)，把节点类型、边类型、张量形状全部列出来。这不是浪费时间，而是帮你建立对数据的整体感知。很多报错本质上是因为你没有搞清楚自己的数据里到底有哪些类型、哪些关系，盲目套模型导致的。

7.2 先小规模跑通，再放大数据

构建异构图时，先用小数据集把整个流程走通，比如100个用户、500个商品、10个店铺。小数据跑起来快，调试方便，等你确信代码逻辑没问题了，再换成全量数据。这一步能帮你节省大量调试时间。

7.3 构图时就想清楚预测任务

构建异构图之前，先明确你的预测目标是什么。是预测节点标签？还是预测边是否存在？还是预测图的某个全局属性？目标不同，图结构、训练方式、模型选择都不一样。比如你要做边预测，就得准备负样本边；你要做节点分类，就需要保证每个有标签的节点类型有足够的监督信号。想清楚再动手，远比写代码更重要。

7.4 善用PyG的Transform

PyG提供了很多内置的Transform，比如ToUndirected、RandomLinkSplit、NormalizeFeatures。这些Transform能帮你省去不少手写代码的麻烦。使用时注意顺序：一般先做RandomLinkSplit划分训练集和测试集，再对子图做ToUndirected，最后才做特征标准化。顺序反了，容易造成数据泄露，测试集的信息跑到训练集里去。

7.5 版本锁定和环境管理

最后再啰嗦一句：做异构图项目，环境一致性很关键。PyG依赖的torch-sparse、torch-scatter这些扩展库，版本必须跟torch版本严格匹配。我自己遇到过无数次“安装成功但导入报错”的情况，最后都是用conda创建独立环境解决的。建议每个项目单独建一个conda env，把torch、torch-geometric的版本固定下来，不要轻易升级。