PyTorch 仓库中的 functorch 安装指南：从独立包到内置模块的完整演进与实战

PyTorch 仓库中的 functorch 安装指南：从独立包到内置模块的完整演进与实战

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch

functorch 是 PyTorch 生态中提供 JAX 风格可组合函数变换（vmap、grad、vjp、jvp、jacrev、jacfwd、hessian等）的核心库。本文以 functorch/docs/source/install.rst 为骨架，完整讲解 functorch 的安装方式、版本演进、与 PyTorch 二进制的关系，并结合当前仓库源码给出验证、运行与迁移建议。读完本文，你将掌握：如何在新老 PyTorch 版本上正确安装与使用 functorch、如何从旧版独立包平滑升级、如何用官方测试与最小示例验证安装是否成功，以及 functorch API 在当前仓库中的实际实现位置。

核心结论：functorch 已并入 PyTorch，无需单独安装

install.rst开门见山给出了一个关键事实：自 PyTorch 1.13 起，functorch 已直接包含在 PyTorch 二进制中，不再需要单独安装独立的 functorch 包。也就是说，只要你按官方流程安装好 PyTorch，就可以直接在程序中执行：

import functorch

这一点在当前仓库的源码中得到了充分印证：仓库根目录下的 functorch/init.py 不再定义任何独立实现，而是通过薄封装把能力转发到torch._functorch子模块（详见下文"源码印证"一节）。functorch 已经从"独立第三方库"正式演变为 PyTorch 核心组件。

从旧版升级：先卸载旧版独立包

如果你的环境里安装的是早期版本的独立 functorch 包（functorch 0.1.x 或 0.2.x），在升级到 PyTorch 1.13+ 之前，可能需要先将其卸载，以避免两个版本的 functorch 并存导致符号冲突或版本混乱：

pip uninstall functorch

卸载完成后，再安装新版 PyTorch，即可使用随 PyTorch 自带的 functorch。

保持向后兼容：pip install functorch依然可用

官方明确承诺维持向后兼容性：pip install functorch这条命令在 PyTorch 1.13 及之后的相当一段时间内依然可用，直到官方正式宣布弃用。这一设计主要照顾的是"维护同时支持多个 PyTorch 与 functorch 版本库"的开发者——他们可以继续用pip install functorch来锁定特定版本组合，而不必立刻改写依赖声明。

需要注意的是，这条兼容路径是"渐进式弃用"策略的一部分。从当前仓库 torch/_functorch/deprecated.py 的源码可以看到，functorch.*顶层 API 自 PyTorch 2.0 起已标记为弃用（deprecated），官方建议迁移到torch.func.*或torch.vmap等新入口，并计划在 PyTorch >= 2.3 的某个未来版本中删除。因此：新项目请优先使用torch.func/torch.vmap命名空间，老项目应规划迁移。

Colab 环境：零安装快速体验

install.rst专门为 Google Colab 用户提供了快速上手路径：官方维护了一个包含完整安装与体验说明的 Colab Notebook，你只需在 Colab 中打开该 Notebook，按步骤安装 PyTorch 并导入 functorch，即可在云端免费环境里体验全部变换功能，无需配置本地 GPU 环境。这是评估 functorch 能力最快、门槛最低的方式。

Nightly 版本：抢先体验最新特性

如果你需要 functorch 的最前沿功能，官方建议直接安装 PyTorchnightly（每夜构建）二进制。根据install.rst的说明，自 2022 年 09 月 21 日起，import functorch已包含在 nightly PyTorch 二进制中，也就是说你不再需要为 nightly 单独拼装 functorch 包。nightly 构建可通过 PyTorch 官网的安装指引获取。

这一点与 functorch/README.md 中的"从源码安装"章节相互呼应：README 同样注明"截至 2022/09/21，functorch 随 nightly PyTorch 二进制一起安装"，并给出了开发环境下的验证方式（详见下文"验证安装"）。

历史版本（PyTorch 1.11.x / 1.12.x）：使用独立包

对于仍停留在 PyTorch 1.11.x 或 1.12.x 的用户，functorch 尚未并入主二进制，需要按以下两步操作：

1. 首先安装对应版本的 PyTorch；
2. 然后执行：

pip install functorch

该命令会拉取与目标 PyTorch 版本配套的独立 functorch 包。这是唯一需要"显式单独安装 functorch"的场景。

验证安装：官方最小示例与测试命令

无论通过哪种方式安装，安装完成后都建议立即运行验证。这里给出两个层面的验证手段。

最小 Python 冒烟测试

来自 functorch/README.md 的官方冒烟测试，适用于所有安装方式：

import torch from functorch import vmap x = torch.randn(3) y = vmap(torch.sin)(x) assert torch.allclose(y, x.sin())

这段代码验证了核心变换vmap是否可用：vmap(torch.sin)将sin沿 batch 维度向量化，其结果应与逐元素x.sin()完全一致。

官方单元测试

在从源码安装（functorch 开发环境）的场景下，README 建议运行以下测试确认一切正常：

pytest test/test_vmap.py -v pytest test/test_eager_transforms.py -v

此外还有两项依赖补充说明：

• AOTAutograd 有额外的可选依赖，可通过pip install networkx安装；
• 运行 functorch 测试前，需要安装测试依赖expecttest与pyyaml。

当前仓库中对应的测试文件位于 test 目录下，包括test/test_vmap.py、test/test_eager_transforms.py等，测试覆盖了各变换的正确性、组合性与异常路径。

源码印证：functorch 在当前仓库中的真实结构

深入仓库源码，可以更清楚地理解"并入 PyTorch"的具体形态。当前仓库对 functorch 采用了分层封装的架构：

1. 顶层命名空间：functorch/init.py 负责导出vmap、grad、hessian、jacfwd、jacrev、jvp、vjp、make_functional、make_functional_with_buffers、combine_state_for_ensemble、functionalize等 API，其__version__直接取torch.__version__，进一步证明 functorch 与 PyTorch 版本完全绑定。

2. 弃用适配层：torch/_functorch/deprecated.py 是functorch.*API 的薄封装，每个函数都通过warn_deprecated(...)发出FutureWarning，并转发到对应的新实现：

   • vmap→torch.vmap/torch.func.vmap（见 torch/_functorch/apis.py）
   • grad、grad_and_value→torch.func.grad
   • vjp、jvp、jacrev、jacfwd、hessian、functionalize→torch.func.*对应实现
   • make_functional、make_functional_with_buffers→torch.func.functional_call
   • combine_state_for_ensemble→torch.func.stack_module_state

3. 核心实现层：

   • vmap的完整语义、参数解析与批处理规则定义在 torch/_functorch/vmap.py 与 torch/_functorch/apis.py；
   • grad、vjp、jvp、jacrev、jacfwd、hessian的 eager 模式实现在 torch/_functorch/eager_transforms.py；
   • make_functional、make_functional_with_buffers、combine_state_for_ensemble的模块处理逻辑在 torch/_functorch/make_functional.py。

从 torch/_functorch/apis.py 的vmap文档字符串，可以提炼出vmap各参数的实际语义，方便你按需使用：

同理，grad(func, argnums=0, has_aux=False)假设func返回单元素 Tensor，计算输出关于第argnums个输入的梯度；jacrev/jacfwd分别用反向与正向自动微分计算雅可比矩阵，可相互嵌套或自嵌套生成 Hessian。

迁移路线与使用建议

综合install.rst的安装语义与当前仓库的源码状态，可以给出如下落地建议：

1. 新项目：直接安装 PyTorch 1.13+（推荐使用最新稳定版或 nightly），使用torch.func.vmap、torch.func.grad等新命名空间，避免依赖functorch.*的弃用警告。
2. 老项目 / 多版本库维护者：可继续使用pip install functorch的兼容路径，但应尽快规划迁移；迁移目标 API 对照表见上文"弃用适配层"一节。
3. PyTorch 1.11/1.12 用户：先装 PyTorch，再pip install functorch；升级到 1.13+ 前先pip uninstall functorch。
4. 尝鲜最新特性：安装 nightly 构建的 PyTorch，functorch 随附其中，无需单独安装。
5. 云端快速体验：优先使用官方 Colab Notebook，零配置即可完整体验。
6. 安装后必做验证：运行上述冒烟测试；若为源码开发环境，再运行pytest test/test_vmap.py -v与pytest test/test_eager_transforms.py -v。

总结

functorch 的安装史，本质上就是它与 PyTorch 逐步深度融合的历史：从 PyTorch 1.13 起并入主二进制，到 nightly 随附、pip install functorch保持兼容，再到 PyTorch 2.0 起以torch.func为最终形态。无论你处于哪个版本阶段，只要遵循 install.rst 的安装路径并对照本文的源码与验证指引，就能快速、正确地搭建起可组合函数变换的完整工作环境。

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch