PyTorch Geometric 2.8 版本演进全解析：从 2.1 到 2.8 的新特性、破坏性变更与升级指南

PyTorch Geometric 2.8 版本演进全解析从 2.1 到 2.8 的新特性、破坏性变更与升级指南【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric本文以仓库根目录 CHANGELOG.md 为绝对主体系统梳理 PyTorch GeometricPyG自 2.1.0 至 2.8.0 及 Unreleased 阶段的全部版本演进新增能力、行为变更、弃用与移除项、关键修复并结合 torch_geometric 源码与 test 测试用例给出实现级佐证。读完本文你将能够掌握 PyG 各版本的完整特性清单与破坏性变更点、理解 GNNLLM、图采样、可解释性、链接预测指标等核心模块的底层实现脉络、并依据版本兼容性矩阵安全规划升级路径。一、版本总览与升级速览表CHANGELOG 记录了 PyG 从 2.1.02022-08-17到 2.8.02026-06-05共 8 个正式版本外加一个 [Unreleased] 待发布区块。所有版本均遵循 Keep a Changelog 规范按 Added / Changed / Deprecated / Removed / Fixed / Security 六类组织。版本发布日期标志性新增兼容性变化2.1.02022-08-17torch_geometric.nn.aggr聚合包、FeatureStore/GraphStore抽象、LinkNeighborLoader、推理基准套件PyTorch 1.12 支持2.2.02022-12-01torch_geometric.explain模块、LRGBDataset、to_smiles、HydroNetPyTorch 1.13 支持2.3.02023-03-23torch_geometric.contrib子包、CaptumExplainer、GPS 图 Transformer、可解释性指标体系PyTorch 2.0 / Lightning 2.0 支持2.4.02023-10-12OnDiskDataset、Database接口、torch_geometric.distributed包、Kùzu 远程后端PyTorch 2.1 支持2.5.02024-02-16fsspec文件系统后端、ViSNet、分布式训练增强、mypy类型检查PyTorch 2.2 支持2.6.02024-09-13torch_geometric.Index/EdgeIndex、GRetriever、WebQSPDataset、LLM 包起步PyTorch 2.3/2.4 支持2.7.02025-10-14torch_geometric.llm、TAGDataset、GPSE、链接预测指标族PyTorch 2.5/2.6/2.8 支持移除 Python 3.8/3.92.8.02026-06-05from_relbench、txt2qa.py、GraphLand 基准、MGNANPyTorch 2.11/2.12 支持移除 PyTorch 2.8从版本节奏看PyG 的演进主线清晰数据抽象FeatureStore/GraphStore→ 可扩展采样NeighborLoader 系→ 大规模图存储OnDiskDataset/Database→ 可解释性框架explain→ 图基础模型与 GNNLLM 融合GRetriever/TAGDataset/llm 包。二、数据核心层的演进从 FeatureStore 到 OnDiskDataset2.1 FeatureStore / GraphStore 抽象2.1.02.1.0 引入的FeatureStore与GraphStore抽象是 PyG 数据层走向解耦的基石。源码中两者的实现分别位于 torch_geometric/data/feature_store.py 与 torch_geometric/data/graph_store.py将“节点/边特征存储”与“图拓扑结构存储”从Data/HeteroData对象中剥离出来从而支持NeighborLoader直接消费外部存储后端如分布式环境下的分片图。2.1.0 同时为Data/HeteroData增加了对这两类存储的内建支持。2.2 OnDiskDataset 与 Database 接口2.4.02.4.0 是数据层的大版本新增OnDiskDataset接口torch_geometric/data/on_disk_dataset.py、Database接口及其SQLiteDatabase/RocksDatabase实现torch_geometric/data/database.py并提供to_on_disk_dataset()将内存数据集转换为磁盘数据集。PCQM4Mv2数据集被作为OnDiskDataset的参考实现。2.5.0 进一步保证OnDiskDataset在多线程get调用下的并行性并修复了OnDiskDataset未应用 transforms 的 bug#8663。三、采样与加载器体系的持续强化3.1 采样器统一与 pyg-lib 集成2.1.0 – 2.3.02.1.0新增LinkNeighborLoader可扩展链接预测训练、filter_per_worker参数、FeatureStore/GraphStore后端采样支持。2.2.0LinkNeighborLoader支持三元组采样、disjoint模式、input_time时序采样RandomNodeLoader支持HeteroData。2.3.0采样逻辑统一收敛到torch_geometric.sampler包torch_geometric/sampler并接入pyg-lib的高性能 neighbor sampling。2.7.0 新增BidirectionalSampler定义于 torch_geometric/sampler/base_sampler.py 相关实现中支持沿边的正向与反向双向采样并允许合并SamplerOutput对象、获取全局 row/col 节点 ID。3.2 链接预测采样细节2.6.0 – 2.7.02.6.0LinkLoader支持按源/目标节点权重进行负采样NeighborLoader/LinkNeighborLoader支持边级时序采样。2.7.0LinkNeighborLoader支持加权负采样链接预测指标体系随之丰富见第六节。四、GNNLLMPyG 2.6 以来的核心增长极4.1 GRetriever 与 WebQSP2.6.02.6.0 引入GRetriever模型与WebQSPDataset数据集torch_geometric/datasets/web_qsp_dataset.py后者在 2.7.0 增加了use_pcst选项以优化证据子图抽取。2.7.0 补充了大量GRetriever架构基准示例并保护num_gnn_layers 0时的模型实例化2.8.0 修复了GRetriever.inference中的 dtype 不匹配问题#10681。4.2 torch_geometric.llm 包2.7.02.7.0 正式新增torch_geometric.llm子包仓库中对应 torch_geometric/llm包含LargeGraphIndexer大图索引器torch_geometric/llm/large_graph_indexer.py 中的class LargeGraphIndexerRagQueryLoaderRAG 查询加载器TAGDataset文本属性图数据集支持 LLM 生成的解释GLEM图-语言嵌入模型。配套示例覆盖GIT-Mol、MoleculeGPT、txt2qa合成多跳 QA 生成支持 vLLM 与 NVIDIA NIM 后端、g_retriever.py、relbench_gretriever.py等见 examples/llm。4.3 数据集与基准2.7.0 – 2.8.02.7.0MedShapeNet、CityNetwork、InstructMol、ComplexWebQuestions (CWQ)、Teeth3DS口内 3D 扫描分析扩展基准、HashTensortorch_geometric/hash_tensor.py。2.8.0from_relbench工具torch_geometric/contrib/utils/_relbench.py 中的def from_relbench可将 RelBench 数据库直接转换为HeteroDataGraphLand 基准经GraphLandDatasettorch_geometric/datasets/graphland.py接入contrib.nn.models.MGNAN模型torch_geometric/contrib/nn/models/mgnan.pyGNAN 到多元形状函数的扩展及配套示例见 examples/contrib。五、可解释性与模型家族扩展5.1 explain 框架2.2.0 – 2.7.02.2.0新增torch_geometric.explain基础框架torch_geometric/explainGNNExplainer从nn迁移至explain.algorithm。2.3.0新增CaptumExplainer、AttentionExplainer、PGExplainer、GraphMaskExplainer后者随后迁移到 torch_geometric/explain/algorithm、BA2MotifDataset、InfectionDataset及 fidelity/faithfulness/characterization_score 等指标。2.7.0GNNExplainer、PGExplainer、AttentionExplainer均支持异质图visualize_graph进入HeteroExplanation。5.2 新增模型层2.3.0 – 2.7.02.3.0DenseGATConv、AntiSymmetricConv、GPSConvGraph Transformer、SimpleConv、HeteroDictLinear、TemporalEncoding、KGE 系列TransE/ComplEx/DistMult。2.4.0MixHopConv、LCMAggregation可学习交换幺半群、NeuralFingerprint、DirGNN、GraphMixer、PMLP、PatchTransformerAggregation、ClusterPooling、VariancePreservingAggregation。2.5.0ViSNet等变模型、RCDD数据集、to_hetero_with_bases静态图支持。2.7.0LPFormer链接预测图 Transformer、Polynormer、ProteinMPNN、SGFormer、ARLinkPredictorAttract-Repel 链接预测嵌入、total_influencetorch_geometric/utils/influence.py量化长程依赖、GPSE 图位置/结构编码器。六、链接预测指标族2.6.0 – 2.7.02.6.0 引入LinkPredMRRtorch_geometric/metrics/link_pred.py 中的class LinkPredMRRLinkPredMetric子类计算 Top-k 预测的平均倒数排名。2.7.0 系统性补齐推荐系统/链接预测评估指标HitRatio、Coverage、Diversity、Personalization、AveragePopularity并支持加权的LinkPredNDCG、LinkPredRecall与LinkPredMetricCollection集合容器。这些指标实现均位于 torch_geometric/metrics/link_pred.py配套示例见 examples/ar_link_pred.py 及 examples 下的 Attract-Repel 链接预测脚本。七、PyTorch / Python 版本兼容矩阵与依赖演进版本新增 PyTorch 支持移除支持Python 变化2.1.01.12——2.2.01.13——2.3.02.0、Lightning 2.0——2.4.02.1—移除 Python 3.72.5.02.2——2.6.02.3、2.4PyTorch 1.12—2.7.02.5、2.6、2.8PyTorch 1.11移除 Python 3.82.8.02.11、2.12PyTorch 1.13–2.5、PyTorch 2.8移除 Python 3.9依赖层关键变化2.3.0 起torch-sparse成为可选依赖大部分torch-scatter依赖被移除2.7.0 起torch_geometric.distributed被弃用2.8.0 起弃用torch-cluster与torch-spline-conv统一迁移至pyg-lib0.6.02.6.0 起torch.load(weights_onlyTrue)成为默认行为。八、性能优化与编译支持PyG 持续将性能优化与torch.compile深度绑定2.3.0 引入torch.compile支持与基准研究2.5.0 扩展至HeteroConv、MultiAggregation、ModuleDict/ParameterDict2.4.0 增加torch_geometric.backend.use_segment_matmul标志torch_geometric/backend.py以覆盖默认的segment_matmul/grouped_matmul启发式策略2.5.0 将推断模式默认值改为基于基准测试的结果2.5.0 起 GNN 层默认可 jittable同时弃用MessagePassing.jittable与torch_geometric.compile改用torch.compile2.8.0 优化to_dense_batch在 eager 与torch.compile两种模式下的运行时并在 test/nn 中通过test_compile_basic.py、test_compile_conv.py、test_compile_dynamic.py等测试保障编译路径正确性。九、破坏性变更与升级注意点清单升级到 2.8.0 前需重点核对以下行为变更API 迁移GNNExplainer由nn迁至explain.algorithmExplainerConfig参数并入Explainer类Data.keys由属性改为方法2.4.0NeighborSampler中的num_neighbors不再是 loader 属性2.2.0RandomTranslate更名为RandomJitter。默认行为变化2.4.0 起所有 transform 均为不可变浅拷贝不再原地修改数据2.5.0 起GCNConv(normalizeFalse)禁止add_self_loopsTrue时序采样默认包含与种子时间戳相等的节点要求pyg-lib0.1.0。计算语义修正PointTransformerConv修正为sum聚合GATConv根据二分/非二分输入正确初始化模块nn.models.GAT保证输出out_channels维to_hetero在MessagePassing.add_self_loops未禁用时报错。已知修复GATConv/GATv2Conv的return_attention_weights修复2.8.0与其 TorchScript 支持移除为正确性考虑MetaPath2Vec末端孤立节点、k_hop_subgraph有向图、to_dgl空图处理等均有对应修复记录。十、如何基于 CHANGELOG 规划版本升级建议按以下步骤使用本仓库的 CHANGELOG.md 规划升级比对当前版本与目标版本逐段阅读两者之间的 Added/Removed/Deprecated 章节标记涉及自己使用 API 的条目。核对兼容性矩阵确认目标版本要求的 PyTorch 版本如 2.8.0 要求 PyTorch 2.9 且不再支持 2.8与 Python 版本2.8.0 移除 Python 3.9并同步升级pyg-lib0.6.0。检查弃用警告Deprecated 章节列出的 API如torch_geometric.distributed、torch-cluster应提前替换避免在下一版本被移除。回归验证关键路径运行 test 目录下与受影响模块对应的测试如升级采样相关则关注 test/loader、test/sampler升级数据层则关注 test/data确认行为变更符合预期。关注 Unreleased 区块该区块预示下一版本的动向如 MGNAN 模型、txt2kg多进程错误处理改进与 Python 3.14 下config_store的修复可提前评估对自身代码的影响。【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考