alterlab-torch-geometric

PyTorch Geometric (PyG)

概述

PyTorch Geometric 是一个基于 PyTorch 构建的库，用于开发和训练图神经网络（GNN）。在图和不规则结构上进行深度学习时使用此技能，包括小批量处理、多 GPU 训练和几何深度学习应用。

何时使用此技能

在以下场景中应使用此技能：

• 基于图的机器学习：节点分类、图分类、链接预测
• 分子属性预测：药物发现、化学属性预测
• 社交网络分析：社区检测、影响力预测
• 引文网络：论文分类、推荐系统
• 3D 几何数据：点云、网格、分子结构
• 异构图：多类型节点和边（例如知识图谱）
• 大规模图学习：邻居采样、分布式训练

不适用场景

场景	改用
不涉及学习的经典图算法、中心性、最短路径或网络可视化	alterlab-networkx
用于提出实质性社会科学论断的社交网络分析设计（中心性、社区检测、ERGMs）	alterlab-sna
使用 MoleculeNet 特征提取器和预训练化学模型进行端到端分子属性预测	alterlab-deepchem
基于 TorchDrug 数据集和任务（GearNet、逆合成、分子生成）构建的项目	alterlab-torchdrug

快速入门

uv pip install torch_geometric
# Optional compiled ops (neighbor sampling, knn/radius graphs, fps): pick TORCH/CUDA to match your install
uv pip install pyg-lib -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html

PyG 2.8 将 torch-cluster 和 torch-spline-conv 并入了 pyg-lib（>= 0.7），因此不再需要这两个包。除非安装了 pyg-lib（或 torch-sparse），否则 NeighborLoader 会引发 ImportError；对于当前版本的 PyTorch（2.13/2.14），data.pyg.org 仅发布 pyg-lib wheel，不发布 torch-scatter/torch-sparse。

图是 torch_geometric.data.Data 对象：包括 x（节点特征 [N, F]）、edge_index（COO 格式的连接关系 [2, E]）、可选的 edge_attr、y、pos，以及任何自定义属性（train_mask 等）。DataLoader 会将多个图批处理为一个块对角图（不进行填充）；batch 向量将节点映射回其所属的源图。

完整的安装/稀疏依赖、基础图创建、基准数据集加载、边索引格式和小批量处理详情：references/getting_started.md。

核心工作流

1. 加载或构建数据 — 基准数据集、自定义 InMemoryDataset，或从 CSV 加载（references/datasets_and_loading.md；完整目录见 references/datasets_reference.md）。
2. 定义 GNN — 堆叠预构建的卷积层（GCNConv、GATConv、SAGEConv），或继承 MessagePassing 实现自定义层（references/building_gnns.md；完整层列表见 references/layers_reference.md）。
3. 训练 — 节点分类（单张图、训练/测试掩码）、图分类（DataLoader + 全局池化），或通过 NeighborLoader 邻居采样进行大规模训练（references/training_workflows.md）。
4. 按需使用高级功能 — 使用 HeteroData/to_hetero 处理异构图、变换、GNNExplainer 可解释性分析、分层池化、GPU、保存/加载（references/advanced_features.md；变换目录见 references/transforms_reference.md）。

构建 GNN（概览）

GNN 遵循邻域聚合流程：变换节点特征 → 沿边传播消息 → 从邻居聚合 → 更新表示。PyG 提供 40 多种卷积层。选择时请检查其功能：是否支持 SparseTensor、edge_weight、edge_attr、二分图，以及延迟（-1 通道）初始化。GCN/GAT/GraphSAGE 和自定义 MessagePassing 层的代码（包括 _i/_j 目标/源命名约定）见 references/building_gnns.md。

资源

捆绑参考资料

此技能包含详细的参考文档：

• references/getting_started.md：安装、图的基本创建、Data 结构、边索引格式、小批量处理
• references/building_gnns.md：消息传递、GCN/GAT/GraphSAGE 代码、自定义 MessagePassing 层、层功能
• references/datasets_and_loading.md：内置数据集、自定义 InMemoryDataset、从 CSV 加载图
• references/training_workflows.md：节点分类、图分类、大规模邻居采样
• references/advanced_features.md：异构图、变换、可解释性、池化、GPU、保存/加载
• references/layers_reference.md：所有 40 多种 GNN 层的完整列表及其说明和功能
• references/datasets_reference.md：按类别整理的全面数据集目录
• references/transforms_reference.md：所有可用变换及其使用场景

脚本

scripts/ 中提供了实用脚本：

• scripts/visualize_graph.py：使用 networkx 和 matplotlib 可视化图结构
• scripts/create_gnn_template.py：为常见 GNN 架构生成样板代码
• scripts/benchmark_model.py：在标准数据集上测试模型性能

可直接运行脚本，也可阅读脚本以了解实现模式。

官方资源

• 文档：https://pytorch-geometric.readthedocs.io/
• GitHub：https://github.com/pyg-team/pytorch_geometric
• 教程：https://pytorch-geometric.readthedocs.io/en/latest/get_started/introduction.html
• 示例：https://github.com/pyg-team/pytorch_geometric/tree/master/examples

属于 AlterLab Academic Skills 套件。