torchforge

一个原生基于 PyTorch 的智能体强化学习库，让你专注于算法而非基础设施。

概述

torchforge 生态系统的主要目的是将基础设施相关的关注点与模型相关的关注点分离，从而简化强化学习实验。torchforge 通过提供清晰的强化学习抽象以及这些抽象的一个可扩展实现来实现这一点。当你需要对资源分配、运行期间的故障处理或训练负载重定向、通信模式等进行细粒度控制时，相应的基础工具都已就位。而当你不需要这些复杂控制时，你就可以纯粹专注于你的强化学习算法。

关键特性：

• 易用性，便于快速研究（将强化学习循环与基础设施解耦）
• 可扩展性，适合高级用户（强化学习循环的各个部分都可以轻松修改，而无需接触基础设施）
• 可扩展性（能够在异步和同步训练之间切换，并支持数千张 GPU 卡）

⚠️ 早期开发警告 torchforge 目前仍处于实验阶段。你可能会遇到一些 bug、功能不完整的情况，以及未来版本中可能发生变化的 API。项目欢迎提交 bug 修复，但为了确保协调一致，在开始工作之前，请先讨论任何重大更改。建议你在问题跟踪器中表明你的贡献意向，可以通过新建问题或认领现有问题来实现。

📖 文档

查看 torchforge 的托管文档：https://meta-pytorch.org/torchforge。

教程

我们还准备了笔记本教程（即将发布）。

安装

torchforge 需要 PyTorch 2.9.0，并依赖 Monarch、vLLM 和 torchtitan。

Conda

使用以下命令安装 torchforge：

conda create -n forge python=3.12
conda activate forge
./scripts/install.sh

ROCm 安装

ROCm 用户可以使用专用脚本来安装：

conda create -n forge python=3.12
conda activate forge
./scripts/install_rocm.sh

注意事项：

• 在可能的情况下会自动检测 PYTORCH_ROCM_ARCH；如果检测失败，请手动设置（例如：PYTORCH_ROCM_ARCH=gfx942）。
• 在可能的情况下会自动检测 ROCM_VERSION；如果检测失败，请手动设置（例如：ROCM_VERSION=6.4）。
• 对于 ROCm 7.x，PyTorch 稳定版 2.9.0 尚不可用。脚本默认使用 nightly 轮子。你可以通过设置 PYTORCH_CHANNEL=stable|nightly 来覆盖默认行为。
• ROCm 构建会以 USE_TENSOR_ENGINE=0 的方式安装 Monarch，因此 RDMA 和分布式张量功能目前已被禁用。
• 可选标志：--use-sudo（系统包）和 --skip-amdsmi（跳过 amdsmi 安装）。

安装脚本会同时安装系统依赖和 torchforge。请注意，此安装脚本使用 DNF，但可以轻松扩展到其他 Linux 发行版。

可选：默认情况下，软件包安装使用 conda。如果你想在目标机器上直接安装系统包而不是通过 conda，可以在安装脚本中添加 --use-sudo 标志：./scripts/install.sh --use-sudo。

Pixi

Pixi 结合了 uv 的优势，并可通过 conda forge 获取系统依赖。pixi.toml 提供了一个清单文件，其中包含构建任务，install 是一个组合安装任务。

安装 pixi：

curl -fsSL https://pixi.sh/install.sh | bash

使用 pixi 安装 torchforge：

pixi run install

注意： 我们正在积极努力实现纯 uv 安装。目前，推荐使用 Conda。uv 支持尚未完全实现，相关进展可在 issue #494 中跟踪。

安装完成后，你可以运行以下命令，应该会看到 GRPO 训练正在运行的输出（至少需要 2 张 GPU 设备）：

python -m apps.grpo.main --config apps/grpo/qwen3_1_7b.yaml

快速入门

要在 Llama3 8B 模型上运行 SFT，运行以下命令：

python -m apps.sft.main --config apps/sft/llama3_8b.yaml

引用

许可证

源代码根据 BSD 3 许可证 提供，然而，您可能还需遵守其他法律义务，这些义务适用于本仓库中链接的其他内容，例如第三方数据和模型的许可或服务条款。

torchforge 快速上手指南

torchforge 是一个原生的 PyTorch 智能体强化学习（Agentic RL）库，旨在将基础设施与模型算法解耦，让开发者专注于 RL 算法本身。它支持从异步到同步的训练模式，并可扩展至数千张 GPU。

⚠️ 注意：本项目目前处于早期实验阶段，API 可能发生变化，且可能存在 Bug。生产环境使用请谨慎。

1. 环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Linux (脚本默认使用 DNF 包管理器，适用于 Fedora/CentOS/RHEL 等，其他发行版需手动安装系统依赖)。
• Python 版本：3.12。
• PyTorch 版本：2.9.0 (需配合 Monarch, vLLM, 和 torchtitan)。
• 硬件要求：
  • GPU：运行示例至少需要 2 块 GPU。
  • ROCm 用户：需确认架构版本（如 gfx942）和 ROCm 版本（如 6.4）。ROCm 7.x 用户需注意 PyTorch 稳定版尚未适配，脚本将默认使用 nightly 版本。

2. 安装步骤

推荐使用 Conda 进行安装。国内用户若遇到网络问题，建议配置 Conda 国内镜像源（如清华源或中科大源）以加速依赖下载。

方法一：标准安装 (CUDA/NVIDIA)

# 创建并激活 conda 环境
conda create -n forge python=3.12
conda activate forge

# 运行安装脚本
./scripts/install.sh

可选：若希望直接安装系统级包而非 conda 包，可添加 --use-sudo 参数：

./scripts/install.sh --use-sudo

方法二：ROCm 安装 (AMD GPU)

# 创建并激活 conda 环境
conda create -n forge python=3.12
conda activate forge

# 运行 ROCm 专用安装脚本
./scripts/install_rocm.sh

ROCm 特殊配置说明：

• 若自动检测失败，可手动指定架构和版本：

  PYTORCH_ROCM_ARCH=gfx942 ROCM_VERSION=6.4 ./scripts/install_rocm.sh
  

• 若需强制使用稳定版或 nightly 版 PyTorch：

  PYTORCH_CHANNEL=stable ./scripts/install_rocm.sh
  

• 当前 ROCm 构建默认禁用 RDMA 和分布式张量功能 (USE_TENSOR_ENGINE=0)。

方法三：使用 Pixi (替代方案)

Pixi 结合了 uv 的速度和 conda-forge 的系统依赖管理能力。

# 安装 pixi
curl -fsSL https://pixi.sh/install.sh | bash

# 使用 pixi 安装 torchforge
pixi run install

3. 基本使用

安装完成后，即可运行内置的示例应用。以下是最简单的快速启动示例。

示例：运行 GRPO 训练

确保机器至少有 2 块可用 GPU，运行以下命令启动 GRPO 训练示例：

python -m apps.grpo.main --config apps/grpo/qwen3_1_7b.yaml

示例：运行 SFT (监督微调)

若要对 Llama3 8B 模型进行 SFT 训练，运行：

python -m apps.sft.main --config apps/sft/llama3_8b.yaml

运行成功后，终端将输出训练日志，表明 RL 循环已正常启动。更多高级用法和自定义算法请参考官方文档：https://meta-pytorch.org/torchforge/