PyG同构数据集构建全指南：从零搭建GNN可控实验数据

做图神经网络的实验，最难受的往往不是调模型，而是数据不听话。公开数据集像 TUDataset 里的 MUTAG、PROTEINS，图与图之间的节点数、边结构差异很大，你想做特征重要性分析或者模型消融实验时，结构变量根本控制不住。这时候就得自己造数据，而 PyG 里最容易上手、也最容易出问题的操作之一，就是构建同构数据集——所有图共享同一套拓扑模板，只改特征和标签。这篇文章我就把整套构建流程、踩坑记录和进阶玩法完整写出来，给正在折腾 GNN 实验的你一个可以照抄的答案。

1. 同构数据集到底解决什么问题

1.1 先搞清楚"同构"在图学习里的含义

我见过不少人把"同构数据集"和图论里的 graph isomorphism（图同构）混在一起，其实完全是两码事。图论里的同构判定，讨论的是两个拓扑结构能不能通过节点重排变得一模一样，这是个计算上不太好啃的问题。而我们在 PyG 里说"构建同构数据集"，指的是数据集内部所有样本图共享同一个拓扑模板：比如每个样本都是 10 个节点的环，或者都是 5×5 的网格，节点编号方式固定不变，变的只是节点特征和图标签。

这样的数据集在公开 benchmark 里反而不常见。MUTAG 里每个分子图的原子数从十几到几十都有，PROTEINS 里的蛋白质结构更是千差万别。研究者如果想让模型只靠特征做判断，就必须把结构变量按住不动，同构数据集就提供了最干净的控制变量实验环境。

这里还有个容易混淆的概念：PyG 文档里的 Heterogeneous Graph、Homogeneous Graph，讨论的是单张图内部节点和边是否分类型，前者是异质图，后者是同质图。而我们说的同构数据集，讲的是整个数据集的图样本之间拓扑是否一致。前者描述单张图的内部组成，后者描述样本之间的结构对齐关系。两者完全不同，推导实现时别搞岔了。

1.2 PyG 的数据结构决定了同构集很好造

PyG 的核心是torch_geometric.data.Data，它本质上是一个灵活的张量容器，你可以在里面塞各种命名的 tensor 字段。构建同构数据集，最关键的是两类字段：x（节点特征，shape 为[num_nodes, num_features]）和edge_index（边索引，COO 格式，shape 为[2, num_edges]）。当我们谈到"同构"时，落实到数据结构上就是每个 Data 对象的x.size(0)相同，edge_index的形状和内容一致——甚至绝大多数情况下可以直接复用同一份edge_index模板。

COO 格式很简单，就是两行矩阵，第一行是源节点编号，第二行是目标节点编号，每一列代表一条有向边。无向图通常把双向边都写进去。比如一条从节点 0 到节点 1 的边，就写成edge_index[:, 0] = tensor([0, 1])。PyG 的模型在消息传递时会同时处理源端和目标端的特征聚合，所以你把无向图写成双向边不会错。

批量训练时，DataLoader会把多个 Data 拼接成一个大 Batch，edge_index各列自动做偏移累加，形成一个分块对角结构，同时生成batch向量标记每个节点属于哪一个子图。同构数据集在这种拼接机制下有额外的好处：每个子图节点数、边数完全一样，batch 里的张量形状非常规整，调试时做 shape 对账特别省心。

1.3 使用场景与适用人群

具体来说，同构数据集在下面这些场景里特别能打：

• 图分类或图回归的模型验证。结构固定后，模型不能靠边连接方式偷懒区分样本，只能实实在在学特征，这样得到的准确率才有说服力。
• 特征鲁棒性测试。给节点特征增加不同强度的高斯噪声，看模型性能曲线，可以定量评估特征的重要性。
• 图生成模型评估。如果要评价一个生成模型输出图的质量，参考图和生成图结构一致时，对齐和比较都方便很多。
• 超参数对比实验。做学习率、网络深度、dropout 比例等对比时，数据集的噪声越小，实验结论越干净。

所以这篇文章适合谁？一类是做消融实验的研究生，一类是在公司需要自建 benchmark 数据的算法工程师，还有一类是刚学 GNN、想通过手写数据集彻底搞懂 PyG Dataset 机制的初学者。无论哪种身份，同构数据集都是绕不开的第一个台阶。

2. 构建方案怎么选：InMemoryDataset 是最合适的入口

2.1 为什么不能只靠 Data + DataLoader

如果你的实验只需要 50 个图，那确实没必要上 Dataset。直接data_list = [Data(...), ...]，然后DataLoader(data_list, batch_size=32)就完事。但实验规模一大，问题就来了：每次跑脚本都要重新生成数据；想给数据统一加预处理找不到合适的地方；缓存结果没法复用；在多进程 DataLoader 下容易重复消耗内存。这些痛点正是 PyG Dataset 体系要解决的。

PyG 提供了两个层级：InMemoryDataset（全量数据常驻内存）和Dataset（按需从磁盘加载）。同构数据集通常样本量在几千到几万，单图节点数也不会特别夸张，整体内存占用可控，用InMemoryDataset是性价比最高的选择。Dataset基类更适合图文件极其庞大、单图就要 MB 级别的场景，走 lazy 加载路线。你在开源项目里看到的大部分自定义 PyG 数据集，都是从InMemoryDataset继承的，学这个也不会踩到太多边角知识。

2.2 Dataset 生命周期：raw、process 与 processed 三个环节

InMemoryDataset的核心机制是三个目录概念：raw_dir、processed_dir和对应的文件。当你实例化一个数据集时，PyG 会自动做两件事：先看processed_file_names指定的文件是否存在于processed_dir，存在就直接加载；不存在就调用process()生成，再保存到processed_paths[0]。这意味着你的生成脚本天然带上了一层缓存，第二次运行不会被重复生成，但也意味着如果你改了结构定义，一定要手动删除旧的processed/data.pt，不然你用的还是旧数据。

process()里最关键的一步是self.collate(data_list)。这个方法会把一个 Data 列表合并成两个东西：一个巨型Data对象（所有子图拼接成的整体）和一个slices字典（记录每个子图在整体 tensor 里的偏移位置）。保存时把(data, slices)一起torch.save到 processed 路径，下次加载时就能快速恢复。你可能好奇：PyG 为什么不直接保存整个 data_list？因为按偏移量切分再合并的效率，比维护一堆 Python 对象高得多，这也是 DataLoader 能高效迭代的核心原因。

子类中还需要实现raw_file_names和processed_file_names两个属性。我们的数据完全是程序生成的，没有外部原始文件，所以raw_file_names直接返回空列表。processed_file_names则指定缓存文件名，比如['data.pt']，这个文件是判断数据是否已经处理过的唯一依据。

2.3 结构模板的生成策略

同构数据集的结构模板可以有很多种，常见的有环形图、网格图、完全图、随机图。选哪种取决于你的任务：想测局部信息聚合能力就选环形图；想测二维空间关系就选网格图；想测全局依赖就选完全图。我的建议是优先采用规则结构，因为规则结构容易在代码和文章里展示，也方便你手工验算edge_index是否正确。

生成侧建议把模板生成逻辑放在process()内部，并且用纯 PyTorch 操作完成。比如环形图可以一行torch.arange加取模生成，网格图用torch.arange和 reshape 也能搞定，没有必要引入 networkx 增加依赖。这里有个细节值得注意：同一个edge_index张量不要直接赋给所有 Data 对象，因为多个 Data 共享同一份内存引用后，一旦某个样本做结构变换，其他样本会被连带修改。务必用.clone()复制一份再放入每个 Data。

3. 手把手实现一个同构图分类数据集

3.1 完整代码实现

直接上一个能跑的完整例子。我构造的是 10 节点环形图数据集，500 个样本，每个图 8 维节点特征，二分类标签。代码已经注释了关键点，你可以直接复制到脚本里运行。

import torch import torch.nn.functional as F from torch_geometric.data import Data, InMemoryDataset, DataLoader from torch_geometric.nn import GCNConv, global_mean_pool class RingDataset(InMemoryDataset): """所有样本共享同一个环状拓扑，只改变节点特征和标签。""" def __init__(self, root, num_graphs=500, num_nodes=10, num_features=8, transform=None, pre_transform=None): self.num_graphs = num_graphs self.num_nodes = num_nodes self.num_features = num_features self.num_classes = 2 # 必须先把子类参数赋值，super().__init__ 内部才会执行 process() super().__init__(root, transform, pre_transform) @property def raw_file_names(self): # 没有外部原始文件，直接程序生成数据 return [] @property def processed_file_names(self): return ['data.pt'] def process(self): # 构建环形图模板：i -> (i+1) mod n，再补上反向边 row = torch.arange(self.num_nodes) col = (row + 1) % self.num_nodes edge_index = torch.cat([ torch.stack([row, col], dim=0), torch.stack([col, row], dim=0), ], dim=1) data_list = [] for i in range(self.num_graphs): x = torch.randn(self.num_nodes, self.num_features) # 让标签与第三个特征维度关联，保证任务可学 if x[:, 3].mean() > 0: y = torch.tensor([1], dtype=torch.long) else: y = torch.tensor([0], dtype=torch.long) data_list.append(Data(x=x, edge_index=edge_index.clone(), y=y)) if self.pre_filter is not None: data_list = [d for d in data_list if self.pre_filter(d)] if self.pre_transform is not None: data_list = [self.pre_transform(d) for d in data_list] data, slices = self.collate(data_list) torch.save((data, slices), self.processed_paths[0])

这套代码跑起来后，目录结构会自动建好：

data/ring/ ├── processed/ │ └── data.pt └── raw/

raw/目录会创建但不会放东西，因为我们没有原始文件。processed/data.pt是核心产物，下次实例化时直接加载它，不会再走一遍生成逻辑。

3.2 关键步骤拆解

先讲__init__里最容易出错的顺序问题。num_graphs、num_nodes、num_features这些子类属性必须在super().__init__()之前赋值，因为父类构造函数会检查 processed 文件是否存在，不存在就调用process()，而process()需要读取这些属性。如果你先调用super().__init__()再赋值，第一次运行时self.num_nodes还不存在，会直接抛 AttributeError。

然后是process()里的结构模板生成。我用了两行torch.stack生成环形图的单向边，再torch.cat把反向边也拼进去，最终每个节点有两个邻居，边数是 20。如果你把torch.cat去掉，只剩i -> (i+1) mod n的单向环，GCN 的邻居聚合范围就变小了，训练收敛也会变慢。无向图转成双向边是图神经网络里的常见习惯，不算冗余。

标签生成逻辑我故意设计成和第三个特征维度的均值挂钩，不是纯随机分桶。这样做的目的是保证下游的 GCN 模型能真实学到模式，让整个数据管线的验证有意义。如果你用纯随机标签，模型 loss 不下降，你会分不清是数据管道的问题还是任务本身不可学。用均值大于 0 作为正负样本的分界，两类占比大约各半，且特征和标签之间存在线性可分关系，适合快速自检。

最后是collate和torch.save。这个写法和新版本 PyG 一致：保存(data, slices)二元组。老版本教程里常见的是torch.save(self, self.processed_paths[0])，这种写法在新版本中会带来兼容性问题，建议直接用上面的方式。

3.3 验证数据管线与模型训练

数据生成完，不能光看代码不验证。先用最简单的打印确认数据规模正常：

dataset = RingDataset(root='data/ring') print(f'样本数: {len(dataset)}') print(f'特征维度: {dataset.num_features} / 类别数: {dataset.num_classes}') sample = dataset[0] print(sample.x.shape, sample.edge_index.shape, sample.y) # 输出: torch.Size([10, 8]) torch.Size([2, 20]) tensor([0]) loader = DataLoader(dataset, batch_size=32, shuffle=True) batch = next(iter(loader)) print(batch.x.shape, batch.edge_index.shape, batch.batch.shape, batch.y.shape) # 输出: torch.Size([320, 8]) torch.Size([2, 640]) torch.Size([320]) torch.Size([32])

看到这个输出，说明collate的拼接逻辑是对的。320 是 32 个图乘以 10 个节点，640 是 32 个图乘以 20 条边，batch向量长度与节点总数一致，y的 batch 维度是 32。PyG 在拼edge_index时已经给每个子图的目标节点做了偏移，不需要你手动处理。

再写一个最简单的两层 GCN 跑 30 个 epoch，验证 loss 确实会下降：

class SimpleGNN(torch.nn.Module): def __init__(self, in_dim, hidden_dim, out_dim): super().__init__() self.conv1 = GCNConv(in_dim, hidden_dim) self.conv2 = GCNConv(hidden_dim, hidden_dim) self.classifier = torch.nn.Linear(hidden_dim, out_dim) def forward(self, x, edge_index, batch): x = F.relu(self.conv1(x, edge_index)) x = F.relu(self.conv2(x, edge_index)) x = global_mean_pool(x, batch) return self.classifier(x) model = SimpleGNN(dataset.num_features, 16, dataset.num_classes) optimizer = torch.optim.Adam(model.parameters(), lr=0.01) loss_fn = torch.nn.CrossEntropyLoss() model.train() for epoch in range(30): total_loss = 0.0 for batch in loader: optimizer.zero_grad() out = model(batch.x, batch.edge_index, batch.batch) loss = loss_fn(out, batch.y) loss.backward() optimizer.step() total_loss += loss.item() if epoch % 10 == 0 or epoch == 29: print(f'epoch {epoch:02d}, loss {total_loss / len(loader):.4f}')

你会看到 loss 从 0.7 左右一路下降到 0.45 以下，这说明数据生成、加载、拼接、模型前向传播整条链路没有断点。有些教程只讲数据构造不验证，结果读者后续训练时到处报错，所以这一步不要省略，至少跑 20 轮确认链路健康。

4. 踩坑记录：构建同构数据集的常见问题与排查方法

4.1 新老版本 PyG 的保存方式差异

先说说版本差异。PyG 2.3 之前的InMemoryDataset，官方示例里process()最后一行都是torch.save(self, self.processed_paths[0])，也就是把整个数据集对象序列化。新版本推荐保存(data, slices)二元组，因为父类的load()方法就是按这个格式读取的。如果你是从老教程复制代码，跑新版本时大概率遇到load() got an unexpected keyword argument 'data'这类错误，直接改成上面的写法即可。

如果你的项目还停留在老版本，那就得反过来：process()里保存torch.save(self, ...)，__init__里也不要手动torch.load，因为老版本父类会自动处理。最稳的排查方式，是先打印一下data, slices = torch.load(processed_path)看返回结构，别想当然。

4.2 排查清单与实测心得

同构数据集代码量不大，但真正跑起来，报错场景一个比一个经典，这里按我踩过的频率整理成速查表。

这里面最容易被忽视的是num_classes。PyG 的 Dataset 没有内置这个字段，它只知道你的y是什么类型，但不负责推断有几类。模型脚本里out = model(...)的最后一层Linear需要输出维度，如果你的num_classes不存在，训练代码会直接 AttributeError。所以我在代码里特意加上了self.num_classes = 2，这是从实际训练脚本反推出来的必需属性。

缓存问题则是改了代码却发现结果不变的经典场景。PyG 判断 processed 文件是否有效的标准只有一个：文件是否存在。它根本不会去比较你的process()函数内容有没有变化。所以每次改动数据生成逻辑，第一件事就是删掉processed/data.pt。我后来习惯直接把缓存文件名带版本号，比如data_v2.pt，逻辑发生任何变化就换名字，能省下不少和缓存斗智斗勇的时间。

5. 进阶思路：让同构数据集变得更灵活

5.1 用 transform 动态扰动结构

基础版的数据集是静态同构，每个图的结构完全相同。实际实验中，我们往往要在这个同构基底上做结构扰动，模拟真实场景中"结构基本一致但略有变化"的情况。PyG 的transform参数可以实现在每次访问样本时动态处理，非常适合做这类增强。

def drop_edges(data, p=0.2): num_edges = data.edge_index.size(1) keep = torch.rand(num_edges) > p data.edge_index = data.edge_index[:, keep] return data aug_dataset = RingDataset(root='data/ring', transform=drop_edges) sample1 = aug_dataset[0] sample2 = aug_dataset[0] print(sample1.edge_index.size(1), sample2.edge_index.size(1))

每次访问dataset[i]时，transform都会对样本执行，所以sample1和sample2的边数可能不同。关键是这个操作不会污染缓存：transform是在process()完成之后，每次取样本时对副本执行的，原始数据始终是完整的同构图。这种机制天然适合随机增强，不用你额外维护一份原始数据副本。

5.2 添加自定义图级特征

同构数据集还可以横向扩展字段。比如你想给每个图加一个全局统计量，作为额外的图级特征，直接在构造Data时传进去就行：

data_list.append(Data( x=x, edge_index=edge_index.clone(), y=y, glob_feat=torch.randn(4), ))

PyG 对未知字段的默认处理规则是沿第 0 维拼接，所以collate之后，glob_feat的形状会从(4,)变成(batch_size, 4)，正好可以作为图级特征输入分类器。同理，边特征edge_attr也可以直接加，collate时默认沿第 0 维拼接成(total_edges, dim)，符合预期。

真正需要小心的只有特殊字段，比如edge_index在拼 batch 时要偏移目标节点，所以Data.__inc__和__cat_dim__对它有特殊逻辑。你自己新增的普通字段基本不需要重写这两个方法，只要记得在训练脚本里同步消费新字段就行。

5.3 从同构到弱异构的迁移实验

有了同构数据集，还能做一件很有意思的事：把模型在同构数据上预训练，再迁移到弱异构数据上微调。同构数据让模型被迫学习特征层面的语义差异，不会依赖结构巧合，学到的表征往往更稳健。你可以用同样的代码生成一个节点数范围在 8 到 12 的弱异构数据集，先在RingDataset上预训练，再在弱异构集上微调，对比直接训练的效果。这类实验在论文里经常被用来验证模型的结构泛化能力，而构建起点就是本文这套同构数据集代码。

另外，同构数据在自监督对比学习里也很好用。同一张图做两次特征扰动，构成正样本对，不同图之间是负样本对。因为所有图的结构都一样，模型不可能靠结构捷径区分正负样本，只能真正学会特征级别的表示。这种干净的正负样本设计，在异质图数据上反而不容易做到。

最后再分享两个小习惯

从我第一次搭同构数据集到现在，卡得最久的不是生成逻辑，而是缓存。改了标签规则，跑出来的结果还是老样子，一度以为代码写错了。后来把 processed 目录删掉重跑，一切正常。从那以后我凡是改了数据定义，第一件事就是删缓存。这个习惯从一个小细节变成我跑所有 GNN 实验的固定动作。

还有一个建议：如果你只是快速验证一个想法，不一定要先写 Dataset 类。构造一个data_list，用Batch.from_data_list(data_list)直接喂给模型，能在十分钟内验证思路。等确认可行了，再迁移到InMemoryDataset做缓存和规范化管理也不迟。先跑通再封装，这个顺序能帮你省掉很多调试 Dataset 生命周期的时间。