# PR #6954 完整报告

- 仓库：`verl-project/verl`
- 标题：[trainer] fix: Add readme and CI test for Titan Engine
- 合并时间：2026-07-08 14:23
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6954

---

# 执行摘要

- 一句话：为 TorchTitan 引擎新增文档与 CI 测试
- 推荐动作：推荐阅读文档和 CI 配置以理解 TorchTitan 引擎的依赖和部署，CI 模板可用于其他引擎的测试集成。

# 功能与动机

TorchTitan 引擎需要 nightly 版本的 PyTorch 和 TorchTitan 支持 spmd_types，缺乏 CI 覆盖和文档。本 PR 添加端到端 CI 和文档，确保引擎的可测试性和可维护性。

# 实现拆解

1. **新增 CI 工作流 **（`.github/workflows/e2e_ppo_trainer_torchtitan_vllm.yml`）：配置触发条件为推送或 PR 到主分支且路径匹配或排除，定义 job 步骤安装 nightly 依赖（torch, torchvision, vllm, torchtitan）并运行测试脚本。
2. **修改测试脚本 **（`tests/special_e2e/run_ppo_trainer_torchtitan.sh`）：将默认激活检查点模式从 `none` 改为 `selective`（提升训练效率），将总训练步数从硬编码 100 改为环境变量 `TOTAL_TRAIN_STEPS` 并可配置（方便 CI 设置小步数），移除 wandb 日志（减少 CI 依赖）。
3. **新增文档 **（`docs/workers/torchtitan_workers.rst`）：详细说明 TorchTitan 引擎的需求（nightly 依赖、版本锁定关系）、安装步骤、支持的特性（N-D 并行、torch.compile、选择性激活检查点等）和限制（无流水线并行）。
4. **更新文档索引 **（`docs/index.rst`）：在入口中添加 TorchTitan 工作页面的链接，使其可被文档构建系统发现。

关键文件：
- `.github/workflows/e2e_ppo_trainer_torchtitan_vllm.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 新增的 CI 工作流是此 PR 的核心基础设施，确保 TorchTitan 引擎每次变更后都能通过 e2e 测试。
- `tests/special_e2e/run_ppo_trainer_torchtitan.sh`（模块 测试脚本；类别 test；类型 test-coverage）: 修改后的测试脚本是 CI 的直接执行者，其配置变更影响 CI 效率和稳定性。
- `docs/workers/torchtitan_workers.rst`（模块 文档说明；类别 docs；类型 documentation）: 新增的文档是开发者使用 TorchTitan 引擎的主要参考资料，包含依赖和配置细节。
- `docs/index.rst`（模块 文档索引；类别 docs；类型 documentation）: 更新文档索引以使 TorchTitan 页面可访问。

关键符号：未识别

## 关键源码片段

### `tests/special_e2e/run_ppo_trainer_torchtitan.sh`

修改后的测试脚本是 CI 的直接执行者，其配置变更影响 CI 效率和稳定性。

```bash
# 可配置参数
AC_MODE=${AC_MODE:-selective}   # 默认使用 selective 激活检查点
TOTAL_TRAIN_STEPS=${TOTAL_TRAIN_STEPS:-100}  # 可覆盖总训练步数

# 训练参数数组
common_params=(
    model_engine=torchtitan
    algorithm.adv_estimator=grpo
    actor_rollout_ref.actor.torchtitan.activation_checkpoint="${AC_MODE}"
    trainer.total_training_steps=${TOTAL_TRAIN_STEPS}
    trainer.logger=['console','file']  # 移除 wandb，降低 CI 依赖
)

```

# 评论区精华

除 CLA 自动检查外，无 reviewer 评论；PR 直接获得 wuxibin89 批准。

- 暂无高价值评论线程

# 风险与影响

- 风险：Nightly 依赖版本可能在 2 个月后从索引中移除导致 404（PR 中已说明）；CI 路径过滤较严格可能遗漏其余相关变更。
- 影响：降低 TorchTitan 引擎的使用门槛；CI 保证核心变更不破坏 TorchTitan 训练；团队可从文档中快速了解并行配置。
- 风险标记：nightly 依赖过期风险 , CI 路径过滤严格

# 关联脉络

- PR #6916 [trainer] fix: Update latest TorchtitanEngine: 此 PR 的 CI 和文档建立在 TorchTitan 引擎更新之上，为引擎提供测试和文档。
- PR #6950 [trainer] fix: spmd_types and activation checkpointing composability bug: 修复了 TorchTitan 引擎的兼容性问题，此 PR 的测试脚本避免了该问题。