verl 在 AMD ROCm 上的容器化部署指南：Dockerfile.rocm 镜像构建、配置与训练实战

verl 在 AMD ROCm 上的容器化部署指南：Dockerfile.rocm 镜像构建、配置与训练实战

【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl

本指南以 docker/rocm/README.md 为核心，系统讲解 verl（HybridFlow）如何在 AMD GPU 上借助 ROCm 软件栈完成容器化部署：包括支持的 GPU 架构与软件版本基线、镜像内预编译与源码构建的组件划分、BuildKit 本地构建方法与关键构建参数调优，并衔接 AMD 快速上手教程中的容器启动、环境校验与端到端 PPO/GRPO 训练流程。读完本文，你将能够独立完成 verl ROCm 镜像的构建与调优，并在 MI300 / MI350 系列 GPU 上跑通 vLLM 或 SGLang 驱动的强化学习训练。

背景：为什么 verl 需要单独的 ROCm 镜像

verl 的 NVIDIA 系列镜像（见 docker/README.md）依赖 CUDA 生态，无法直接运行在 AMD GPU 上。因此仓库在 docker/rocm 目录下维护了一套独立的容器配方（Docker recipe），用于在 AMD GPU + ROCm 软件栈上运行 verl。

• 主镜像配方为 docker/rocm/Dockerfile.rocm，面向当前与未来的 verl 版本；
• 目录下其余Dockerfile.rocm*/Apptainerfile.rocm文件（如Dockerfile.rocm702、Dockerfile.rocm6、Dockerfile.rocm_verl-0.4.1、Dockerfile.rocm.deepseek-v4）仅作为历史版本参考保留，对应 ROCm 6.x 与已锁定的 verl 0.3.x / 0.4.x 等旧版本，新工作应以Dockerfile.rocm为目标。

完整的分步走查（构建、运行与 PPO/GRPO 示例命令）可参见 AMD 教程 docs/amd_tutorial/amd_quick_start.rst。

支持的硬件：GPU 架构（GPU_ARCH）

镜像针对以下 GPU 架构（通过GPU_ARCH控制）进行了验证与内核编译：

其他架构（如gfx90a，对应 MI200/MI250）可以通过覆盖GPU_ARCH构建，但不在官方验证范围内。AMD 快速上手文档 docs/amd_tutorial/amd_quick_start.rst 进一步明确当前支持的 GPU 目标为 MI300X / MI325X（gfx942）与 MI350X / MI355X（gfx950）。

关键软件版本基线

Dockerfile.rocm当前锁定的软件栈如下（源自 docker/rocm/README.md）：

从 docker/rocm/Dockerfile.rocm 的源码可以看到，基础镜像为rocm/primus:v26.4，其中 vLLM 与 SGLang 的提交分别由构建参数VLLM_TAG（18d87a87dc39c1a50f452b218fdcc3aeec48d18e）与SGLANG_TAG（0801cc05ed202544e2e5c67d6b0a1d454de54fca）固定；verl 本身也固定到提交7b19203c52503760f92e0368067c7eb744236274，保证镜像可复现。

镜像内容构成：预编译与源码构建的分工

以rocm/primus:v26.4为基础镜像，Dockerfile.rocm按以下策略组装环境：

预编译（下载安装，不参与本地编译）：

• ROCm 7.14 运行时与开发包（通过repo.radeon.comapt 源安装）；
• torch、apex、torchaudio、torchvision、triton（基础镜像中已预编译）；
• Flash Attention 与 TransformerEngine（ROCm fork）。

源码构建（锁定提交后现场编译）：

• vLLM；
• SGLang。

其余安装项：cupy-rocm、mbridge、megatron-core、megatron-bridge、transformers以及 verl 包本身。

从 Dockerfile 看镜像内的关键处理

Dockerfile.rocm中几个值得注意的实现细节（可作为构建调试参考）：

1. vLLM 的 ROCm 专项补丁：通过sed直接修改源码，包括在csrc/cumem_allocator.cpp中对新映射 VRAM 执行hipMemset清零（避免残留数据，对应上游 PR #44972 的 sleep/wake 正确性回归），以及修复 MoE 未量化权重存储的_maybe_pad_weight就地赋值问题（PR #46009）。
2. verl 默认 rollout 配置注入：构建时通过sed修改 verl 的 verl/trainer/config/rollout/rollout.yaml，为vllm与sglang注入disable_custom_all_reduce: True，并为sglang额外设置attention_backend: triton。
3. SGLang 的 ROCm 兼容处理：包括修复fused_add_rms_norm六参数在非 AITER 路径上的崩溃（PR #32034）、禁用 rust gRPC 扩展模块、以及将sgl-kernel的编译目标强制写为gfx942/gfx950。
4. 运行时环境变量（来自 docker/rocm/Dockerfile.rocm 的ENV段）：
   • PYTORCH_ALLOC_CONF=expandable_segments:True：启用可扩展内存段，防止训练 OOM；
   • SGLANG_ATTENTION_BACKEND=triton、SGLANG_USE_AITER=0；
   • NVTE_USE_GROUPED_GEMM_TRITON=1；
   • HSA_ENABLE_IPC_MODE_LEGACY=1、NCCL_DEBUG=ERROR、ROCPROFILER_LOG_LEVEL=fatal；
   • MIOPEN_DEBUG_FORCE_IMMED_MODE_FALLBACK=1。
5. 环境清单生成：构建末尾将env、pip list、dpkg -l分别导出到/workspace/.manifest/下的env.txt、requirements.txt、dpkg-list.txt，并写入training_docker_version，便于复现与排障。

本地构建：BuildKit 要求与构建参数

Dockerfile.rocm使用了 BuildKit 缓存挂载（RUN --mount=...），因此构建必须使用 BuildKit（含buildx插件）。若报错the --mount option requires BuildKit，需要先安装 buildx（sudo apt-get install -y docker-buildx），并在构建命令前加DOCKER_BUILDKIT=1。

默认构建命令：

DOCKER_BUILDKIT=1 docker build \ -f docker/rocm/Dockerfile.rocm \ -t verl-rocm:local .

常用构建参数

示例——只为 MI300 构建并使用内存安全的任务数：

DOCKER_BUILDKIT=1 docker build \ -f docker/rocm/Dockerfile.rocm \ --build-arg GPU_ARCH=gfx942 \ --build-arg MAX_JOBS=64 \ -t verl-rocm:mi300 .

说明：MAX_JOBS在Dockerfile.rocm中用于 vLLM 构建阶段（MAX_JOBS=64 python3 setup.py develop --no-deps），而 Flash Attention 与 TransformerEngine 采用预编译 wheel 或基础镜像自带版本，因此该参数主要影响 vLLM 的源码编译。

历史配方中的构建技巧（参考）

在旧版配方 docker/rocm/Dockerfile.rocm702 中可以看到更完整的构建手法，部分技巧在新配方中仍有借鉴价值：

• 通过ccache（CCACHE_MAXSIZE=50G）加速 FA / TE / vLLM / aiter 的重复构建，缓存存放在 BuildKit cache mount 中、不固化进镜像；
• 安装 ROCm deb 包后主动删除非目标GFX_ARCH的库文件（hipblaslt、rocblas、miopen等），显著减小镜像体积；
• 从repo.radeon.com的manylinux目录直接 pip 安装锁定 ROCm 版本、cp312ABI 的torch/apex/torchaudio/torchvision/tritonwheel。

发布历史：版本演进脉络

docker/rocm/README.md 记录了镜像的版本演进：

• 2026/07/20：ROCm 7.14 软件栈 —— torch==2.12.0，triton==3.7.0，vLLM @18d87a87d，SGLang @0801cc05ed，Flash Attention（CK）@v2.8.3，TransformerEngine @e6ede467，aiter @b5e03ed19，megatron-core==0.18.0；目标gfx942/gfx950。
• 2026/06/03：ROCm 7.0.2 软件栈 —— torch==2.9.1，triton==3.5.1，vLLM @1ff9d3353，Flash Attention（CK）@83f9e450，TransformerEngine @386bd316，aiter @45c428e54，megatron-core==0.16.0；目标gfx942/gfx950。

两个版本均以gfx942/gfx950为编译目标，可据此判断当前Dockerfile.rocm对应的是 2026/07/20 的 ROCm 7.14 基线。

容器启动与环境校验

官方推荐的预构建镜像为amdagi/verl-dev:rocm7.14_torch2.12_release_0724（见 docs/amd_tutorial/amd_quick_start.rst）。启动容器前需满足宿主机前置条件：

1. 宿主机已安装并正常运行的 AMD ROCm 7.14 驱动栈；
2. Docker 可访问/dev/kfd与/dev/dri；
3. 数据集与模型存储路径已就绪。

启动命令

NAME=verl_release DOCKER=amdagi/verl-dev:rocm7.14_torch2.12_release_0724 docker pull $DOCKER docker run -it --name $NAME --device /dev/kfd --device /dev/dri \ --privileged --network=host \ --group-add video --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ --shm-size=2048g \ --ulimit memlock=-1 --ulimit stack=67108864 \ -w /workspace \ $DOCKER \ /bin/bash

容器内环境校验

# ROCm 与可见 GPU 目标 rocminfo | grep -E "gfx942|gfx950" || true # PyTorch + ROCm 健康检查 python - <<'PY' import torch print("torch:", torch.__version__) print("rocm :", torch.version.hip) print("cuda_available:", torch.cuda.is_available()) if torch.cuda.is_available(): print("gpu_count:", torch.cuda.device_count()) print("device_0:", torch.cuda.get_device_name(0)) PY

支持矩阵与端到端训练示例

根据 docs/amd_tutorial/amd_quick_start.rst，当前软件与硬件范围如下：

各组合对应的示例脚本

以 examples/grpo_trainer/run_qwen3_8b_fsdp.sh 为例，该脚本为 GRPO / Qwen3-8B / FSDP 训练，支持通过环境变量切换推理后端：

• INFER_BACKEND：rollout 后端，可选vllm/sglang/trtllm（默认vllm）；
• 关键超参数通过环境变量覆盖，如MODEL_PATH、TRAIN_BATCH_SIZE（默认 1024）、PPO_MINI_BATCH_SIZE（默认 256）、MAX_PROMPT_LENGTH/MAX_RESPONSE_LENGTH、ROLLOUT_TP、ROLLOUT_GPU_MEM_UTIL（默认 0.6）、ROLLOUT_N（默认 5）、ACTOR_LR（默认 1e-6）等；
• 底层调用python3 -m verl.trainer.main_ppo，以 Hydra 风格参数数组（DATA/MODEL/ACTOR/ROLLOUT/REF/TRAINER）逐项覆盖默认配置。

将推理引擎切到 SGLang 时，只需设置INFER_BACKEND=sglang；镜像内已为 sglang 注入attention_backend: triton，无需手工修改配置。

已知问题与规避方案

AMD 快速上手文档 docs/amd_tutorial/amd_quick_start.rst 明确列出了以下已知问题：

1. qwen2.5-math-7b：模型下载后需在config.json中将max_position_embeddings更新为 32768。
2. PYTORCH_ALLOC_CONF=expandable_segments:True与 vLLM 自定义 AllReduce 冲突：该环境变量由Dockerfile.rocm默认设置以防止 OOM，但可能与vllm_custom_all_reduce冲突，因此默认在 rollout 配置中设置vllm.disable_custom_all_reduce=True（构建时通过sed注入 verl/trainer/config/rollout/rollout.yaml），待 ROCm 解决冲突后移除。
3. SGLang 的attention_backend必须设为triton：镜像构建时已默认注入。
4. 上游补丁依赖：vLLM 与 SGLang 的多个 ROCm 专项 PR 仍在等待上游合入，目前由 Dockerfile 在构建时直接打补丁（见 docker/rocm/Dockerfile.rocm 中的多处sed修改），未来将迁移到稳定的官方发布版本。

AMD 平台性能调优要点

启用 vLLM Sleep Mode

verl 默认要求 vLLM 开启 sleep mode，使 vLLM 在 rollout 结束后将 GPU 内存卸载到 CPU 内存。该特性已合入 vLLM 主分支（0.11.0 之后的版本）。在 AMD 上，可以通过源码构建 vLLM 或使用较新版本的预编译 ROCm wheel 获得该能力；同时建议 ROCm 版本不低于 7.0。开启 sleep mode 后，长上下文训练或多节点强化学习训练中的显存占用会显著下降（详见 docs/amd_tutorial/amd_vllm_page.rst）。

CUDA Graph 与 ROCm 兼容处理

在 AMD 平台 + vLLM V1 模式下，CUDA graph 在多节点场景中可能无法正常捕获，导致 rollout 性能明显下降；ROCm 在捕获大批量时可能触发意外崩溃。规避方式是：

• 将actor_rollout_ref.rollout.cudagraph_capture_sizes设为[1, 2, 4, 8, 16, 32, 64]（按显存大小调整）；
• 再将actor_rollout_ref.rollout.enforce_eager设为False以启用 CUDA graph。

参考资源

• 镜像配方与构建说明：docker/rocm/README.md、docker/rocm/Dockerfile.rocm
• AMD 快速上手教程：docs/amd_tutorial/amd_quick_start.rst
• AMD 性能调优：docs/amd_tutorial/amd_vllm_page.rst
• 历史参考配方：docker/rocm/Dockerfile.rocm702、docker/rocm/Dockerfile.rocm6、docker/rocm/Apptainerfile.rocm、docker/rocm/Dockerfile.rocm.deepseek-v4
• 训练示例：examples/grpo_trainer/run_qwen3_8b_fsdp.sh、examples/grpo_trainer/run_qwen3_5_35b_megatron.sh

【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl