# PR #6388 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: update rocm doc
- 合并时间：2026-05-18 18:10
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6388

---

# 执行摘要

- 一句话：重构 ROCm Dockerfile 并新增快速入门文档
- 推荐动作：本 PR 适合所有使用 AMD ROCm 的团队精读，特别是 Docker 多阶段构建的实践值得学习。重点关注以下决策：
 - **拆分存档 vs 统一重构**：保留旧版本文件作为参考，但未对其应用相同改进，这是一种务实的做法，但需确保用户文档明确示意。
 - **Review 处理策略**：作者接受部分建议并修复，对设计决策（如 hardcode 版本号）坚持了自身理由，体现了权衡。
建议在合并后补充一个说明，指明 `Dockerfile.rocm6` 为存档，新用户应以 `Dockerfile.rocm` 为准。

# 功能与动机

PR Body 指出需要 'Update the ROCM support documentation to provide reproducible Docker and Dockerfile examples'。同时，为了跟上 AMD ROCm 最新软件栈（ROCm 7.0.2、Python 3.12）并采用多阶段构建最佳实践，以提供更高效、可复现的开发环境。

# 实现拆解

1. **重构 Dockerfile.rocm**：将原来单阶段、硬编码的构建方式替换为多阶段构建。基础镜像升级到 `rocm/pytorch:rocm7.0.2_ubuntu22.04_py3.12_pytorch_release_2.7`，并明确分为 `devel` 和 `runtime` 阶段，分离编译与运行时依赖，缩小最终镜像体积。
2. **归档旧版本为 Dockerfile.rocm6**：将原 Dockerfile.rocm（针对 ROCm 6.3.4）内容保存为新文件，作为向后兼容参考，但不纳入多阶段构建重构，以降低维护负担。
3. **新增 amd_quick_start.rst**：编写完整的 AMD ROCm 快速入门指南，涵盖硬件支持（MI300X/MI325X/MI355X）、容器启动、环境验证、特性支持矩阵以及训练示例（Colocate + FSDP GRPO 等）。
4. **更新文档索引**：在 `docs/index.rst` 中添加对 `amd_quick_start.rst` 的引用，使新指南可以被文档构建系统收录。
5. **根据 Review 修复问题**：包括修正 shell 变量引用语法（`$(MAX_JOBS)` → `${MAX_JOBS}`）、替换 Git 仓库引用从 fork 改为官方 `verl-project/verl` 并添加 commit 锁定，以及调整 sed 操作由行号改为模式匹配。部分修复针对 Dockerfile.rocm 主文件，Dockerfile.rocm6 作为存档未被全面修复。

关键文件：
- `docker/rocm/Dockerfile.rocm`（模块 Docker 构建；类别 infra；类型 infrastructure）: 核心变更文件。多阶段构建重构，升级 ROCm 版本，所有 Docker 构建逻辑重写。
- `docker/rocm/Dockerfile.rocm6`（模块 Docker 构建；类别 infra；类型 infrastructure）: 新增文件，保存旧的 Dockerfile.rocm 版本（ROCm 6.3.4）作为向后兼容参考。
- `docs/amd_tutorial/amd_quick_start.rst`（模块 AMD 教程；类别 docs；类型 documentation）: 新增教程文档，包含完整的 AMD ROCm 快速入门指南，包含环境设置、特性支持矩阵和训练示例。
- `docs/index.rst`（模块 文档主页；类别 docs；类型 documentation）: 在文档索引中添加对 amd_quick_start.rst 的链接，实现导航整合。

关键符号：未识别


# 评论区精华

Review 中 gemini-code-assist 提出了几点关键问题：
- **Shell 变量语法**：在 `Dockerfile.rocm6` 第 46 行，`$(MAX_JOBS)` 会被当做命令执行，应改为 `${MAX_JOBS}`。作者回应这是存档版本，建议参考最新的 `Dockerfile.rocm`，未直接修复。
- **sed 行号硬编码**：在 `Dockerfile.rocm` 第 139 行，使用 `121s` 行号定位替换 TransformerEngine 版本号，gemini 建议改用模式匹配。作者表示这是刻意为之，未来会手动同步版本。
- **Git 仓库引用**：克隆 `volcengine/verl` 分支且未固定 commit，gemini 建议切换到官方 `verl-project/verl` 并固定 commit。作者回复 fixed/resolved。
- **Dockerfile.rocm6 未优化**：gemini 指出新存档仍为单阶段大镜像，建议像 `Dockerfile.rocm` 一样应用多阶段构建。作者以存档为由未采纳。
整体上，作者接受并修复了关于仓库引用和环境变量的建议，对于硬编码版本文档和存档文件的改进持谨慎态度。

- Shell 变量语法错误 $(MAX_JOBS) 未修复 (correctness): 作者回应这是存档版本，建议用户参考最新的 Dockerfile.rocm，未直接修改 Dockerfile.rocm6。
- sed 行号硬编码的维护性讨论 (design): 作者表示这是 hardcode 版本号，未来会手动更新，但未改方案。
- Git 仓库引用和可复现性 (correctness): 作者回复 'fixed' 和 'resolved'，表明已修正（将仓库切换为官方 verl-project/verl 并添加 commit pinning）。

# 风险与影响

- 风险：
 1. **Dockerfile.rocm6 构建风险**：该文件保留旧结构，其中的 `$(MAX_JOBS)` 语法错误可能导致构建失败，且未应用多阶段构建，镜像体积较大。用户若直接使用该文件（如未注意其存档性质）可能遇到问题。
 2. **sed 行号硬编码**：若未来 TransformerEngine 版本更新，行号偏移将导致 patch 失败，目前依赖作者手动维护，存在可维护性风险。
 3. **依赖版本锁定**：部分 pip 包（如 `cupy-rocm-7-0`）及 git 库（如 `mbridge`）未指定精确版本，可能引入非确定性行为。虽作者声明 cupy 可正常安装，但仍需环境配合。
 4. **兼容性**：新 Dockerfile 明确基于 ROCm 7.0.2，可能与旧 ROCm 版本环境不兼容，需要用户更新驱动。
 - 影响：**影响范围**：中等。主要影响使用 AMD ROCm 进行训练的用户和开发者。
 - **用户**：现在有更清晰的快速入门指南（`amd_quick_start.rst`）和可直接使用的 Docker 镜像构建脚本，降低了上手成本。
 - **系统**：Docker 构建从单阶段改为多阶段，构建效率提升，镜像体积减小，利于 CI 和部署。
 - **团队**：代码仓库层面，旧 Dockerfile 归档为 `Dockerfile.rocm6` 避免了直接删除导致的历史丢失，但两个文件需分别维护可能带来额外负担。
 - 风险标记：旧 Dockerfile 语法未修复 , sed 行号依赖 , 部分依赖版本未锁定 , 多版本维护负担

# 关联脉络

- 暂无明显关联 PR