执行摘要

• 一句话：重构 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