PyTorch Geometric

新
许可证: MIT · 更新于 2026-11-11
我的评分

一、简介

PyTorch Geometric(通常简称 PyG)是构建在 PyTorch 之上的开源图神经网络库,采用 MIT 许可发布。它由多特蒙德工业大学的 Matthias Fey 与 Jan Eric Lenssen 创建,首篇论文《Fast Graph Representation Learning with PyTorch Geometric》提出一个核心主张:单一的消息传递抽象足以实现绝大大量图卷积,无需为每个算子单独编写内核。此后该项目成为 PyTorch 生态内默认的图学习工具箱,并成为大量面向物理的图网络工作的实现底座——基于网格的模拟器、蛋白质结构模型、材料性质预测器皆在其上构建。

这篇指南对物理 AI 的意义在于,物理数据的形态正日益脱离规则网格。结构化 CFD 网格、非结构有限元网格、粒子构型、分子图与点云都是不规则数据,各自带有稠密张量卷积难以高效表达的图结构。PyG 提供了层目录、采样机制与数据抽象,把这些结构变成可训练模型。物理仿真入门说明了规则网格假设在这些场景中失效的原因。

本文要支撑的判断不是”要不要用 PyG”,而是:给定一个不规则物理场,应该采用哪种图抽象、由此对应哪一类算子族、以及框架的性能天花板实际落在哪里。这三个选择都有站得住脚的答案,且彼此相互影响。基于网格的流水线与基于点云的流水线共用同一个库,却不共用方法论;适合前者的采样配置对后者可能并不合适。

文中所有版本与能力表述均于 2026 年 11 月 11 日对照项目仓库、发布说明与官方文档核实。第九节记录版本时间线、当前版本以及哪些说法属于项目自述。

二、原理与工作方式

核心抽象是消息传递层。一层为每个节点计算一次更新,其依据是从邻居到达的消息。PyG 在一个基类中实现该范式,拆成三个可覆写的部件:按边产生一条消息的消息函数、在节点处归约传入消息的聚合函数、以及变换聚合结果的更新函数。前向过程由基类处理边索引的记账工作,用户只覆写这三个语义部分。正因如此,同一个基类支撑起图卷积、图注意力、面向点云的边卷积以及其间大量专用算子。

边索引表示是第二个核心概念。图被存为一对索引张量,给出每条边的源节点与目标节点,另附节点特征与可选的边特征。由于图以索引对并非稠密邻接矩阵表达,内存开销随边数增长;同一表示也适用于异构图,异构图的边还要按关系类型再作划分。

异构图通过专门的数据类支持,按节点类型与边类型分别存储,消息按边类型计算,更新按节点类型应用。同构图模型可自动转换为异构图模型,异构算子则允许为每种关系使用不同卷积。在实践中,凡是物理系统存在真正不同种类的相互作用时这一点就很关键:例如分子图中的原子-键、键-原子与原子-原子关系,或有限体积离散中的单元-顶点、单元-单元关系。

第三层是采样。对于大到装不进内存的图,邻居加载器通过对每个节点采样有限个邻居、跨越有限跳数来构造小批量,使每步的子图规模与原图规模解耦。聚类式采样器则改为对图做分区。自 2.0 版本起,加载器接口取代了较早的采样器接口,采样配置以每跳邻居数列表表达。

外围则是实用组件:把多个图合并为一个不相连批次的加载器(通过偏移边索引实现)、把特征存储与图拓扑分离以便接入外部存储后端的 store 抽象、面向超大图的磁盘数据集格式、可解释性模块,以及 GraphSAGE、GCN、GAT、GIN 等组装完整架构的高层模型类。可选的编译扩展为受益于此的操作提供融合内核,缺少这些扩展时库会优雅降级到纯 PyTorch 实现。

三、适用边界与前提

PyG 假设问题可以表达为节点、边与特征。这是一个相当宽泛的假设,但它排除了若干人们有时会想要的东西:更适合在谱方法或连续卷积框架中处理的连续场、结构化网格上的场(此时候选卷积架构既更简单也更快)、以及未知量是场本身并非节点附带标签的逆问题。神经算子合集覆盖了处理结构化与谱情形的算子学习家族。

第二个假设是图构造正确。PyG 不决定什么是一个节点。把节点选为网格单元、网格顶点、粒子还是原子是一个建模决策,后果很大:它决定邻域结构、网络感受野以及采样成本。基于单元的网格图与基于顶点的网格图在精度与成本上都不同,且没有普遍正确的选择。

第三个假设关乎规模。库的扩展性叙事建立在采样之上,而采样成立的前提是底层物理相互作用确实具有局域性,因为存在长程耦合的场必须采样很大的邻域才能保证精度。采样还会引入偏差,因为被采样的子图并非完整邻域,在度分布本身影响结论的问题上,这会改变结果而不仅是拖慢速度。

第四个假设关于周边数值工作流。图网络预测场值,它不施加守恒。带约束或守恒性质的架构确实存在,但它们位于库之外,需要守恒硬性质的项目必须显式设计。代理模型与降阶模型合集综述了各建模家族及其保证的边界。

第五个假设关乎安装与版本耦合。PyG 与 PyTorch 版本紧密耦合,其编译扩展针对特定 PyTorch 构建编译。自 2.3 版本起安装路径大幅简化,但耦合依然存在;驱动版本混杂的异构集群需要锁定环境。近期版本还把原先独立的 cluster 包功能并入主库并标记弃用,围绕旧拆分搭建的现存环境需要一次迁移。

四、上手路径

自 2.3 版本起,基础功能不再要求单独安装 scatter 与 cluster 包;直接安装本库即可工作,可选编译扩展在需要某项具体能力时再补装。当前版本支持较新的 PyTorch 与多种 CUDA 构建,并要求较新的 Python。扩展本身提供 CPU 与 GPU 内核,库在导入时检测哪些可用并设置内部标志,因此缺少扩展只会降低性能,不会破坏导入。

第一个练习应是在一个小规模标准数据集上做节点分类,用现成模型之一。这同时确立三件事:安装是否可靠、批处理路径是否通畅、训练循环是否接通。随后再写自定义层;基类让这一步很短——继承消息传递基类、选定聚合模式、实现消息函数、调用传播入口。

处理异构数据时,先构造异构数据对象,分别添加各节点类型与各关系的边索引,再使用为每种关系分派独立卷积的异构算子。当各关系确实需要不同处理时,从同构图模型自动转换而来并不适用。

扩展到更大规模时,配置很关键:显式设定每跳采样的邻居数,让跳数与卷积层数对齐,并从小批量起步。显存紧张时,首选降批量并非降采样数,因为前者降低峰值显存更快;有研究报告批量从 1024 降到 512 时显存下降约 37%,而模型效果仅损失 0.8%。图能装下时预加载到 GPU 显存可让端到端时间大致减半,因为反复的主机到设备传输是流水线中相当可观的隐藏成本。

小图上跑通后,换到物理数据集,并检查图构造是否与物理一致:邻居数、边界处理,以及节点是否对应具有物理意义的逐节点标签。基于物理的深度学习条目说明此类模型相对求解器的位置,PhysicsNeMo覆盖把神经组件与物理求解器耦合的同类框架。

五、横向对比

与另一主流图框架 Deep Graph Library 相比,差别在实现策略以及时间花在哪里。一项系统性基准研究把流水线拆解后发现:小批量训练中采样可占总运行时间的高达九成,而两框架在这一环差异明显——DGL 用带 OpenMP 的 C++ 实现采样器,PyG 更依赖 Python,这使得 DGL 在大图采样上明显更快。同一研究发现 PyG 更易用、数据加载更快,并报告 PyG 在大图上对某些层因缺少融合内核而出现内存不足。该研究还指出,图能装下时预加载到显存可让整体速度翻倍,且能耗几乎完全随运行时间变化。

与神经算子相比,差别在于学习对象的性质。神经算子学习函数空间之间的映射,能直接表示连续场;图网络学习离散化上的映射。在规则网格与光滑场上,算子路线通常更合适;在非结构网格上,或离散方式在多次运行之间会变化时,图路线更自然,而算子路线需要适配。神经算子实践教程对该对比有详细展开。

与自写 scatter 实现相比,PyG 的价值在于广度与维护,并非峰值吞吐。手写流水线在某个特定算子上可以更快,但换下一个算子就得重写一遍,也无法受益于生态已有的基准、采样器与数据集工具链。

与建在 PyG 之上的几何深度学习库相比,PyG 是底座并非竞品。面向分子性质预测、等变模型与图基础模型的各类库都假定 PyG 已存在。材料发现案例与机器学习原子间势案例都是这条栈在材料领域的实例。

与本目录其余条目相比,PyG 占据不规则结构这一格。PyVista负责网格与场的可视化,常常是生成几何进而构造图的上游步骤;FEniCS与OpenFOAM是产出训练数据的求解器;物理基础模型合集则覆盖预训练模型方向,它在部分场景下取代逐任务训练。

六、基准与数据

PyG 原始论文是项目自身的性能主张,报告相对另一图框架约十四到十五倍的加速优势。该数字距今已有多年,且早于两个项目当前的编译器融合工作;它应被读作”这一抽象设计良好”的证据,并非当下比值。

目前最有用的对比证据是上文提到的框架基准研究,它拆解流水线并非给出单一数字。所用数据集覆盖实际区间:PPI、Flickr 与一个引文图处于小到中等规模,大规模一侧则是含 1.14 亿条边的 Reddit、Yelp,以及含 240 万节点与 6100 万条边的商品图。其结论是:采样占主导;两框架在 Python 与 C++ 实现路径上的差别恰好体现在此处;GPU 加速采样在受支持处带来极大提速;卷积内核本身只占总时间的一小部分。

该研究中另有两个数字值得记住。CPU 与 GPU 之间的数据搬运是主要的隐藏成本,图能装下时整体预加载可让速度大约翻倍;能耗几乎完全随运行时间走,因此同一工作负载上更快的框架也是更省电的,框架选择本身并不存在额外的效率红利。

另一个内存数字来自一篇基于商品规模图的实际文章:整图加载时报告的峰值内存约 22 GB、单轮约 3.2 分钟;邻居采样把峰值内存降到约 3 GB,代价是单轮延长到约 4.7 分钟,精度差异很小。权衡的一般形态是采样以算力换内存,而兑换率取决于底层相互作用的局域性有多强。

领域内的结果通常引自建模论文并非库本身。图网络模拟器被报道在百万单元规模的地下流体仿真中相对求解器取得可观加速;多尺度图架构把全球天气预报的计算时间从小时量级降到分钟量级。全球天气预报案例记录了这一脉络。这些数字归属模型及其训练数据,库只是底座;把它们归给框架属于范畴错误。

七、物理 AI 场景中的用法

PyG 在物理 AI 工作流中的角色,是为不规则结构承担建模层。有三种情形反复出现。

第一种是基于网格的仿真学习。网格图网络表示非结构网格,模型预测下一步状态或相对求解器步的残差。由于网络学习的是局部相互作用规则并非离散方式,它可以在与训练时不同的分辨率或不同的网格上运行,这正是学习型模拟器在实践中真正有价值的地方。

第二种是分子与材料建模。分子天生就是图,图编码是精确的并非近似的,这正是该领域推进最快的原因。材料发现案例与机器学习原子间势案例都建立在这一底座上:在图网络上训练出的势函数随后被部署进经典分子动力学引擎内部。物理基础模型合集覆盖预训练方向。

第三种是图结构的检索与推理。近期版本新增了面向语言模型的子包,包括检索增强的图生成、把文本转成问答以合成多跳训练数据的路径,以及一批新的图基础模型。这是最新也最不确定的一项能力,图学习与以语言模型为中心的流水线之间的边界正在这里划定。

三种情形的实务流程相同:构造图、选择算子族、恰当采样或分批、训练,然后检查物理。最后一步并非可选。图网络能很好地复现观测到的训练数据,却依然可能违反守恒、产生非物理的梯度,或在分布外失效;能捕捉这些问题的检查方法在性能工程合集里有专门讨论。物理 AI 学习路径给出该库在更完整序列中的位置。

八、不适用场景与失效模式

第一种失效模式是采样瓶颈,这是结构性的。若采样占据大部分运行时间,那么加速卷积内核几乎不改变墙钟时间,而”把层做快”这个直觉应对并不有效。真正有效的缓解手段是:在物理允许时缩小采样邻域;在框架提供相应支持时把采样搬到 GPU;以及在数据装得下时预加载。

第二种失效模式是特定算子的内存压力。在没有对应融合内核时,内存行为较重的层在大图上被报道会出现内存不足,因此算子选择部分上是内存决策,精度决策只是其中一面。

第三种是版本耦合。PyG 限定 PyTorch 版本区间,编译扩展限定具体 PyTorch 构建,近期又把原先独立的 cluster 包并入主库,围着旧拆分搭的环境需要显式迁移。在并行运行多个驱动版本集群的研究组里,环境矩阵是一笔真实成本。

第四种是图构造错误,这是”训练很好、预测很糟”最常见的根源。节点粒度选错、邻居半径设错、周期边界被当作开边界而错误连边、采样后域分解未正确重建,都会产出”学到了看似合理的错误相互作用规则”的模型。

第五种是缺乏物理保证。库只计算架构所计算的东西,标准消息传递不守恒质量、动量或能量。施加这些性质的架构作为独立工作存在,采用它们意味着自行编写自定义层并接受额外成本。

第六种是分布外外推。图网络在图结构的训练分布内插值,而训练分布之外的网格或构型是另一个问题。这一局限同样适用于学习型势函数,也正因如此,经典求解器成本边界的讨论才重要:经典求解器仍是评判学习结果的基准。

九、版本与口径核对

当前发布版本为 2.8.1,发布于 2026 年 10 月 6 日,属于维护版本,修复了 Python 3.14 下配置存储对只读参数的处理问题。其前依次为 2026 年 7 月 20 日的 2.8.0.post1 与 2026 年 6 月 5 日的 2.8.0。2.8.0 把 PyTorch 支持扩展到 2.9 至 2.12、Python 扩展到 3.10 至 3.14,把可选加速依赖整合进单一库包,新增面向图检索增强生成的合成多跳问答生成路径,并补充了数据集与基准支持。2.7.0 发布于 2025 年 10 月 14 日,新增语言模型子包、若干图基础模型与组件、双向采样支持以及一族链接预测指标;它移除了更旧的 Python 与 PyTorch 版本支持,并把 distributed 子包标记为弃用。2024 年 9 月 26 日的 2.6.1 与 9 月 17 日的 2.6.0 加入了图与语言模型结合的能力、带稀疏转换缓存的高效索引表示、新的池化与聚合算子、异构图可解释性支持,以及多个分布式示例。

包元数据声明最低 Python 版本为 3.10,许可为 MIT。项目由最初的作者们主导,并有学术顾问角色由斯坦福研究者担任,自 2019 年起持续开发。

关于出处:本节的版本事实来自项目发布列表、发布说明与包元数据。消息传递抽象、边索引表示、异构数据模型与采样设计均为项目自有文档化的设计。十四到十五倍数字出自项目首篇论文,应作为关于该抽象的历史性证据来读,并非当前比值。流水线拆解结果、采样开销占比、内存与单轮数字以及内存不足现象来自框架基准研究与一篇实用文章,并在第六节中如此标注。关于学习型模拟器与天气预报的性能主张,在原始论文中归属模型及其训练数据,并非框架。

十、参考资料

  1. PyTorch Geometric 项目文档,pytorch-geometric.readthedocs.io,消息传递基类、异构数据、加载器与采样器。

  2. PyTorch Geometric 发布说明,GitHub,2.6.0 至 2.8.1 各版本,PyTorch 与 Python 支持区间、依赖整合与图-语言模型能力。

  3. Fey 与 Lenssen 等,Fast Graph Representation Learning with PyTorch Geometric,原始论文,统一消息传递抽象与早期性能主张。

  4. Characterizing the Efficiency of Graph Neural Network Frameworks with a Magnifying Glass,IISWC 2022,流水线拆解、采样开销占比与 CPU/GPU 采样对比。

  5. PyTorch Geometric 安装指南,项目文档,可选编译扩展、优雅降级与版本要求。

  6. PyTorch Geometric 编译优化指南,项目教程,torch.compile 兼容性与已弃用的编译入口。

  7. MeshGraphNets,Learning Mesh-Based Simulation with Graph Networks,基于网格学习的参考架构。

  8. GraphCast,Learning Skillful Medium-Range Global Weather Forecasting,应用于全球预报的多尺度图架构。

  9. 材料发现案例,基于图的性质预测规模化方法,材料规模的图网络。

  10. 机器学习原子间势案例,图基势函数的训练及其在分子动力学引擎内的部署。

标签: