PyTorch Geometric 示例库实战指南从入门 GCN 到万亿边图规模扩展【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric本指南以 PyTorch GeometricPyG官方仓库中的 examples 目录 为核心系统梳理该示例库覆盖的各类 GNN 应用场景——从最基础的节点分类GCN、链接预测含 Attract-Repel 与 LPFormer 等进阶方法到大图基准OGB、关系深度学习Relational Deep Learning、异构图、LLM 与 GNN 协同、可解释性以及基于 cuGraph 的万亿边图扩展方案。读者读完后将掌握如何在当前仓库中快速定位并运行对应示例理解每个示例背后的关键实现细节数据加载、模型结构、训练/评估流程并知道如何将单卡示例平滑迁移到torch.compile、多 GPU 与分布式场景。示例库的整体布局与定位examples/目录examples/README.md汇集了覆盖不同 GNN 使用场景的示例脚本每个脚本都是小而完整的可运行程序包含数据加载、模型定义、训练循环与评估逻辑。该 README 本身扮演导航地图角色重点标出若干代表性示例并划分为以下主题簇入门与基础任务gcn.py节点分类、link_pred.py链接预测进阶链接预测ar_link_pred.pyAttract-Repel 嵌入、lpformer.pyGraph Transformer 链接预测大规模基准OGBogbn_train.py、ogbn_proteins_deepgcn.py关系深度学习rdl.pyRelBench 数据集节点属性预测新数据集graphland.py工程化主题子目录examples/compiletorch.compile、examples/multi_gpu多 GPU/分布式、examples/hetero异构图、examples/llmLLM 与 GNN 协同、examples/explain可解释性极致扩展通过 cuGraph 将 PyG 扩展到万亿级边的图数据运行环境方面README 特别建议 NVIDIA GPU 用户优先使用官方推荐的 NVIDIA PyG Container 中的设备选择逻辑。入门第一课用 GCN 做节点分类README 明确指出gcn.py是最适合入门的示例——它演示了如何在小型同构图数据Cora 等 Planetoid 数据集上训练 GCN 模型做节点级预测。该脚本堪称 PyG 最小工作流的完整范本核心链路如下。数据加载与特征归一化parser.add_argument(--dataset, typestr, defaultCora) parser.add_argument(--hidden_channels, typeint, default16) parser.add_argument(--lr, typefloat, default0.01) parser.add_argument(--epochs, typeint, default200) parser.add_argument(--use_gdc, actionstore_true, helpUse GDC) parser.add_argument(--wandb, actionstore_true, helpTrack experiment)数据部分gcn.py通过Planetoid数据集类下载 Cora并套用T.NormalizeFeatures()变换做行归一化。设备选择使用torch_geometric.device(auto)自动探测可用硬件训练指标可通过 torch_geometric.logging 的init_wandb/log接口输出——加--wandb即可接入 Weights Biases 追踪实验。模型与训练细节class GCN(torch.nn.Module): def __init__(self, in_channels, hidden_channels, out_channels): super().__init__() self.conv1 GCNConv(in_channels, hidden_channels, normalizenot args.use_gdc) self.conv2 GCNConv(hidden_channels, out_channels, normalizenot args.use_gdc)注意两个细节其一GCNConv默认在层内做归一化当启用--use_gdcGraph Diffusion Convolution时归一化被提前到数据预处理阶段完成因此卷积层需显式关闭normalize。其二优化器gcn.py对conv1施加weight_decay5e-4、对conv2不施加注释明确说明只在第一个卷积层做权重衰减——这是复现经典 GCN 论文超参的关键。训练循环train/test函数用data.train_mask/val_mask/test_mask分别计算交叉熵损失与三组准确率并按验证集最优保存测试结果--use_gdc对应的T.GDC变换配置为 PPR 扩散alpha0.05 TopK 稀疏化k128这是将 GCN 升级为 GDC 版本的完整实操样例。运行方式python examples/gcn.py --dataset Cora python examples/gcn.py --dataset CiteSeer --use_gdc --wandb链接预测三连从基础版到 Graph Transformer基础版link_pred.pylink_pred.py展示了一个最小化的 GNN 链接预测管线核心创新点在于用RandomLinkSplit变换把数据切分成 train/val/test 三份transform T.Compose([ T.NormalizeFeatures(), T.ToDevice(device), T.RandomLinkSplit(num_val0.05, num_test0.1, is_undirectedTrue, add_negative_train_samplesFalse), ])应用该变换后数据对象会转变成(train_data, val_data, test_data)三元组。模型采用编码器-解码器结构encode用两层 GCN 生成节点嵌入decode对候选边两端嵌入做点积得到边分数训练时每个 epoch 都重新做一次负采样link_pred.py把negative_sampling采样出的负边与正边拼接后交给BCEWithLogitsLoss监督评估用roc_auc_score。脚本末尾的decode_all还能对整个图预测所有可能存在边的概率邻接矩阵。进阶版ar_link_pred.py 与 Attract-Repel 嵌入ar_link_pred.py实现了基于论文《Pseudo-Euclidean Attract-Repel Embeddings for Undirected Graphs》的改进链接预测方法README 指出该方案可显著提升 AUC在对应论文报告中最多提升 23%。其思想是把嵌入维度显式拆成吸引与排斥两部分class ARLinkPredictor(torch.nn.Module): def __init__(self, in_channels): super().__init__() self.attract_dim in_channels // 2 self.repel_dim in_channels - self.attract_dim def forward(self, z_i, z_j): z_i_attr, z_i_repel z_i[:, :self.attract_dim], z_i[:, self.attract_dim:] z_j_attr, z_j_repel z_j[:, :self.attract_dim], z_j[:, self.attract_dim:] attract_score (z_i_attr * z_j_attr).sum(dim1) repel_score (z_i_repel * z_j_repel).sum(dim1) return attract_score - repel_score脚本通过--use_ar开关在传统 MLP 打分器LinkPredictor与 AR 打分器之间切换并支持 Cora/CiteSeer/PubMed 三个数据集训练采用train_test_split_edges切分正负边损失为正负样本二分类损失之和。更实用的是脚本在训练结束后会输出R-fraction排斥部分能量占比用于量化吸引/排斥空间的分离程度——这是理解 AR 方法可解释性的关键指标python examples/ar_link_pred.py --use_ar --dataset Cora进阶版lpformer.py 与 LPFormerlpformer.py演示了用 Graph Transformer 家族成员LPFormer论文《Empowering GNNs with Edge-based Flexible Graph Transformer》在ogbl-ppa数据集上做链接预测。它展示了 PyG 与 OGB 生态协作的完整流程用PygLinkPropPredDataset加载数据、dataset.get_edge_split()取得正负边划分模型初始化时传入ppr_thresholds控制 CN/1-hop/多跳 PPR 的截断阈值列表与gcn_cacheTrue等关键参数通过model.calc_sparse_ppr(...)预计算稀疏 PPR 矩阵作为 Transformer 的结构先验训练时对当前 batch 的正边做 mask 处理避免信息泄漏支持--runs多随机种子运行并汇总均值 ± 标准差评估用 OGB 官方的Evaluator计算hitsK。README 同时提醒ogbl-citation2的评估方式与其他 OGB 链接预测数据集不同见脚本内注释及 LPFormer 原仓库说明直接套用本脚本需要额外适配。大图基准在 OGB 数据集上训练 GNNogbn_train.py多模型 邻居采样ogbn_train.py是面向大规模 OGB 节点分类的通用训练脚本支持ogbn-arxiv默认、ogbn-products约 6200 万条边与ogbn-papers100M约 16 亿条边三个数据集README 以此为例说明 PyG 如何在大图上训练。它的工程化要点极具参考价值模型可切换通过--model在sage、gat、sgformer、polynormer之间选择其中 SGFormer默认Graph Transformer 类与 Polynormer 是 README 特别提及的代表性方法邻居采样用NeighborLoader做多跳子图采样--fan_out控制每层邻居数、--batch_size控制 batch 大小、--num_workers并行加载对 Transformer 类模型启用disjointTrue子图不共享节点图预处理开关--use_directed_graph控制是否保留有向图默认转为无向图并reducemean--add_self_loop控制是否添加自环内存预警当选择ogbn-papers100M且系统内存不足约 390GB 时脚本会打印显式警告——这直观说明了该数据集对硬件的要求Polynormer 特殊处理论文推荐 7 层结构脚本在层数不符时会提示训练时先做--local_epochs轮局部local训练作为 warmup再通过设置model._global True切换为全局注意力训练基建seed_everything(123)固定随机种子ReduceLROnPlateau依据验证集准确率调度学习率最终输出训练/推理/总体的平均与中位 epoch 耗时、最佳验证准确率与测试准确率。python examples/ogbn_train.py --dataset ogbn-arxiv --model sgformer python examples/ogbn_train.py --dataset ogbn-products --model sage -b 1024 --fan_out 15ogbn_proteins_deepgcn.py训练深度 GNNogbn_proteins_deepgcn.py演示如何在ogbn-proteins数据集上训练深层 GNNREADME 将其定位为深度 GNN 训练范本。几个实现亮点特征工程用scatter(..., reducesum)把边特征聚合到节点上作为初始节点特征该数据集原始节点无特征模型结构28 层DeepGCNLayer每层由GENConvsoftmax 聚合、可学习温度t、LayerNorm与ReLU构成使用blockres残差连接并通过ckpt_gradi % 3每三层做一次梯度检查点以节省显存数据划分RandomNodeLoader将图随机切分为 40 份用于训练、5 份用于测试多标签评估任务是 112 类多标签二元分类用BCEWithLogitsLoss训练并用 OGBEvaluator计算 ROC-AUC。关系深度学习rdl.py 与 RelBenchrdl.py展示了如何基于RelBench数据集论文见 README 引用做关系深度学习Relational Deep LearningRDL。RDL 的核心思路是把关系型数据库中的多张表建模为异构时序图然后在图上做端到端预测。该示例是 PyG 与 torch_frame 之外两个生态RelBench、PyTorch Frame协同的完整样板架构层次分明文本嵌入GloveTextEmbedding基于 SentenceTransformer 的 GloVe 平均词向量模型把文本列编码为张量异构特征编码器HeteroEncoder为每种节点类型维护一个 PyTorch FrameResNet按列语义类型categorical/numerical/multicategorical/embedding/timestamp选择对应的stype_encoder如EmbeddingEncoder、LinearEncoder、TimestampEncoder时序编码器HeteroTemporalEncoder用PositionalEncoding编码种子时间与节点时间戳的相对差换算为天数消息传递HeteroGraphSAGE用HeteroConv对每种边类型实例化SAGEConv层间配LayerNorm(modenode)预测头目标节点类型经过MLP输出预测。数据侧make_pkey_fkey_graph把数据库按主外键关系物化为HeteroData图对象NeighborLoader支持input_time/time_attr/temporal_strategy做时序邻居采样AttachTargetTransform负责在 batch 生成后把标签挂到对应节点上因为时序采样中同一节点可能多次出现、对应不同标签。任务类型通过get_task_type_params自动适配回归用L1LossMAE二分类用BCEWithLogitsLossROC-AUC。训练结束后按验证指标保存best_model.pt并加载测试python examples/rdl.py --dataset rel-f1 --task task_name --epochs 10--task的可选值以 RelBench 官网 发布的任务为准脚本启动时会校验。节点属性预测新基准graphland.pygraphland.py对应 README 提到的GraphLand 数据集论文《GraphLand: A Scientific Discovery Dataset for Graph Neural Networks》用于节点属性预测。它反映了 PyG 示例库持续跟进学术界新基准的节奏用法与其他数据集脚本一致加载数据集 → 构建模型 → 训练评估。工程化进阶编译、多 GPU、异构图、LLM 与可解释性torch.compileexamples/compileexamples/compile 目录提供了使用torch.compile加速 PyG 模型的示例。以 compile/gcn.py 为例与入门版相比有两处关键工程改动数据预处理阶段用T.GCNNorm()提前完成归一化卷积层设置normalizeFalse避免编译过程中出现图中断与 CPU 通信模型定义后直接model torch.compile(model, dynamicFalse)即可获得优化后的执行图训练循环保持不变。这是把 PyG 模型接入 PyTorch 2.x 编译器的标准姿势。多 GPU 与分布式examples/multi_gpuexamples/multi_gpu/README.md 对分布式示例做了系统分类详见该文档的示例表格可归纳为三条主线NVIDIA GPU cuGraph官方推荐方案单节点、多节点、链接预测等负载均有现成脚本位于 cuGraph-PyG 示例仓库安装方式见官方文档的 cuGraph 加速章节纯 PyTorch 分布式distributed_batching.py单节点多小图图级预测DataLoaderDistributedSampler、distributed_sampling.py单节点Reddit 大图节点分类NeighborLoader子图采样、distributed_sampling_multinode.py与配套的.sbatch多节点 Slurm 提交、papers100m_gcn.py/papers100m_gcn_multinode.py约 16 亿边图、pcqm4m_ogb.py图级回归、mag240m_graphsage.py大规模异构图、taobao.py异构图链接预测、model_parallel.py手动把不同层放到不同 GPU 的模型并行Intel GPUXPUdistributed_sampling_xpu.py支持单节点多卡的同构图邻居采样训练。异构图examples/heteroexamples/hetero 覆盖了异构图的典型任务二部图 GraphSAGEbipartite_sage.py、带标签传播的 HANhan_imdb.py、异构卷积hetero_conv_dblp.py、异构链接预测hetero_link_pred.py、HGThgt_dblp.py、CSV 数据加载load_csv.py、元路径随机游走metapath2vec.py、推荐系统recommender_system.py、时序链接预测temporal_link_pred.py以及to_hetero_mag.py等适合作为异构建模的起点合集。LLM 与 GNN 协同examples/llmexamples/llm 集中了将大语言模型与 GNN 联合训练的示例覆盖文本到知识图谱的 RAGtxt2kg_rag.py、文本问答txt2qa.py、分子与大分子场景git_mol.py、glem.py、molecule_gpt.py、protein_mpnn.py、图检索g_retriever.py、relbench_gretriever.py等方向。README 引用的 GNNLLM 研讨与演讲资料可帮助理解这一交叉方向的研究动机。可解释性examples/explainexamples/explain 提供 GNN 可解释性示例包括基于 Captum 的解释器captum_explainer.py及异构链接预测版、GNNExplainer 系列图分类、链接预测、GraphMask 与 MGNAN 图分类等对应 PyG 官方 explain 模块的实践入口。终极扩展cuGraph 把 PyG 带到万亿边README 最后专门用一节介绍如何借助 cuGraph 把 PyG 扩展到万亿级边的图。背景信息如下cuGraph是 RAPIDS 框架下专注于 GPU 加速图分析的包集合支持属性图与数千 GPU 规模扩展cuGraph GNNcugraph-gnn通过cuGraph-PyG与WholeGraph两个子项目为 PyTorch/PyG 提供原生 GPU 加速插件底层基于pylibcugraph/libcugraph的高性能 C 采样原语并配套libwholegraph/pylibwholegraph实现分布式边列表与嵌入存储用户既可以直接使用这些底层库也可以走 cuGraph-PyG 的高层 API——它直接实现了 PyG 的GraphStore、FeatureStore、NodeLoader与LinkLoader接口因此上层训练代码几乎无需改动即可无缝获得 GPU 加速的图存储与采样能力。README 给出的落地路径是参照官方安装指南完成 cuGraph 加速配置后直接使用 cuGraph-PyG 示例仓库中现成的单节点/多节点/链接预测训练脚本位于cugraph-pyg/cugraph_pyg/examples目录覆盖完整可扩展工作流。这与 examples/multi_gpu 中的建议一脉相承追求 NVIDIA GPU 上极致性能时优先采用 cuGraph 生态。如何快速上手推荐路径总结结合 README 的导览顺序建议按如下路径探索示例库入门先跑 examples/gcn.py理解数据加载 → 模型 → 训练/评估的最小闭环任务扩展依次阅读 examples/link_pred.py链接预测、examples/ar_link_pred.pyAR 改进版、examples/lpformer.pyGraph Transformer 版规模升级用 examples/ogbn_train.py 在多模型/多数据集上做邻居采样训练对照 examples/ogbn_proteins_deepgcn.py 学习深层 GNN 技巧场景拓展按需进入 examples/hetero、examples/llm、examples/explain 等主题目录性能优化参考 examples/compile 接入torch.compile参考 examples/multi_gpu 扩展到多 GPU最后按官方 cuGraph 指南迈向万亿边规模。所有示例脚本均位于仓库examples/目录下可直接以python examples/name.py运行OGB 相关脚本需先安装ogb包RDL 示例需安装relbench、torch_frame、sentence-transformers等依赖每个脚本都尽量保持自包含是理解 PyG 各模块 API 用法的最直接教材。【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
