PyTorch Geometric（PyG）是构建在 PyTorch 之上的图神经网络（GNN）标准库。它提供图的数据结构、60 多种 GNN 层实现、可扩展的小批量训练，以及对异构图的支
安装
资料显示其测试版本为 torch-geometric 2.7.x（2025 年 10 月），要求 Python 3.10+ 与 PyTorch 2.6+。
先安装 PyTorch（需匹配你的 CUDA/CPU 环境）：
uv pip install torch
安装核心 PyG（基础使用无需扩展 wheel）：
uv pip install torch_geometric
可选的加速算子（pyg-lib、torch-scatter、torch-sparse、torch-cluster）自 PyG 2.3 起对基础使用并非必需。如需安装，先检查 PyTorch 与 CUDA 版本，再从 PyG wheel 索引安装版本匹配的 wheel：
python -c "import torch; print(torch.__version__, torch.version.cuda)"
uv pip install pyg-lib torch-scatter torch-sparse torch-cluster \
-f https://data.pyg.org/whl/torch-2.8.0+cu128.html
检查版本：
import torch_geometric
print(torch_geometric.__version__)
Conda：pyg conda 频道对 PyTorch >2.5 已不再维护，请改用 uv pip install 与上述 wheel 索引。
PyG 2.7 说明：该版本移除了 Python 3.9 与 PyTorch ≤2.5 支持；torch_geometric.distributed 已弃用，请使用标准 torch.distributed DDP。
核心概念
图数据：Data 与 HeteroData
图存放在 Data 对象中，关键属性包括 x（节点特征）、edge_index（[2, num_edges] 的 COO 格式，dtype=torch.long）、edge_attr（边特征）、y（标签）、pos（位置）。
edge_index 格式很关键：它是 [2, num_edges] 张量，edge_index[0] 为源节点，edge_index[1] 为目标节点，并非元组列表。若边以行形式给出，需转置并调用 .contiguous()。无向图需包含两个方向。异构图使用 HeteroData。
数据集
PyG 内置许多可自动下载与预处理的标准数据集，例如 Planetoid（Cora/Citeseer/Pubmed）、TUDataset（ENZYMES、MUTAG、IMDB-BINARY 等）、OGB、QM7/QM9、ShapeNet 等。常见任务对应：节点分类用 Planetoid、OGB；图分类用 TUDataset、OGB；链接预测用 OGB；分子用 QM7、QM9、MoleculeNet；点云/网格用 ShapeNet、ModelNet、FAUST。
变换
Transforms 用于预处理或增强图数据，类似 torchvision transforms，如 NormalizeFeatures、ToUndirected、AddSelfLoops、KNNGraph、RandomJitter、Compose 等，可作为 pre_transform（一次并保存到磁盘）或 transform（每次访问）应用。
构建 GNN 模型
快速开始：使用内置层
最快的方式是堆叠 torch_geometric.nn 中的卷积层，例如用 GCNConv 构建两层 GCN。注意：PyG 卷积层不包含激活函数，需自行在每层后应用。
选择卷积层
可按任务与图结构选择：GCNConv 适合同构半监督节点分类；GATConv/GATv2Conv 适合邻居重要性不同的场景；SAGEConv 适合大图与归纳设置；GINConv 适合图分类与最大化表达能力；TransformerConv 适合丰富边特征；EdgeConv 适合点云与动态图；RGCNConv 适合多关系类型异构图；HGTConv 适合异构图。所有卷积层至少接受 (x, edge_index)，许多还接受 edge_attr。
惰性初始化
输入通道用 -1 可让 PyG 自动推断维度，对异构模型尤其有用。
高层模型 API
PyG 为常见架构提供现成模型类，如 GraphSAGE、GCN、GAT、GIN。
通过 MessagePassing 自定义层
要实现新 GNN 层，可继承 MessagePassing：propagate() 编排消息传递，message() 定义每条边流动的信息，aggregate() 在节点处合并消息（sum/mean/max），update() 变换聚合结果。_i / _j 约定：传给 propagate() 的张量可在 message() 签名中加 _i（目标/中心节点）或 _j（源/邻居节点）自动索引。
任务特定模式
节点分类
单图全批量训练：前向传播、按 train_mask 计算交叉熵损失、反向与优化；评估时用 model.train(False) 进入推理模式。
图分类
多图使用 DataLoader 做小批量，并用全局池化得到图级表示。PyG 的 DataLoader 通过构造块对角邻接矩阵批量处理多图，batch 张量将每个节点映射到其图索引，池化操作（global_mean_pool、global_max_pool、global_add_pool）据此按图聚合。
链接预测
将边划分为 train/val/test，使用负采样，可用 RandomLinkSplit 变换。编码节点后对边打分。
扩展到大规模图
对于无法放入 GPU 显存的图，使用 NeighborLoader 进行邻居采样。要点：num_neighbors 列表长度应与 GNN 深度（消息传递层数）匹配；种子节点始终是输出中前 batch.batch_size 个节点；batch.n_id 将重标号索引映射回原始节点 ID；对 Data 与 HeteroData 均适用；链接预测用 LinkNeighborLoader；采样超过 2-3 跳通常不可行。其他可扩展选项包括 ClusterLoader（ClusterGCN）、GraphSAINTSampler、ShaDowKHopSampler。多 GPU 训练、DDP、PyTorch Lightning 集成与 torch.compile 支持见参考资料。
异构图
对于含多种节点与边类型的图（社交网络、知识图谱、推荐），使用 HeteroData：节点特征按节点类型字符串索引，边索引按 (src_type, edge_type, dst_type) 三元组索引，并提供 x_dict、edge_index_dict、metadata() 等便捷访问。
构建异构 GNN 有三种方式：1）用 to_hetero() 自动转换——写同构模型再自动转换，二部图输入通道用 (-1, -1)；2）HeteroConv 包装器——为每种边类型指定不同卷积；3）原生异构算子如 HGTConv。
异构图注意事项：用 T.ToUndirected() 添加反向边类型以支持双向消息流；二部图卷积层（源/目标类型不同）应禁用 add_self_loops，改用跳跃连接；对 HeteroData 使用 NeighborLoader 时，input_nodes 指定为 ('node_type', mask) 元组；num_neighbors 可按边类型用字典做细粒度控制。
自定义数据集
加载自有数据的方式：快速方式（无需类）直接创建 Data 对象并传列表给 DataLoader；可复用（适合内存）继承 InMemoryDataset，重写 raw_file_names、processed_file_names、download()、process()；大型（磁盘支持）继承 Dataset，还需重写 len() 与 get()；从 CSV 加载用 pandas 构建映射；从 NetworkX 用 from_networkx(G) 转换；从 scipy 稀疏矩阵用 from_scipy_sparse_matrix(adj) 提取 edge_index。
可解释性
PyG 提供 torch_geometric.explain 解释 GNN 预测，使用 Explainer 与 GNNExplainer 等算法，可设置 explanation_type、node_mask_type、edge_mask_type 与 model_config，并可视化重要子图与特征重要性。可用算法包括 GNNExplainer（基于优化）、PGExplainer（参数化、需训练）、CaptumExplainer（基于梯度）、AttentionExplainer（注意力权重），同构与异构图均适用。
常见陷阱
edge_index 形状必须为 [2, num_edges] 而非 [num_edges, 2]，必要时转置；卷积层不含激活函数，需手动添加；异构二部图注意自环问题。