verl 昇腾（Ascend）镜像构建与容器使用指南：Dockerfile 清单、镜像版本命名与一键部署实战

verl 昇腾（Ascend）镜像构建与容器使用指南：Dockerfile 清单、镜像版本命名与一键部署实战

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

本文围绕 verl 开源仓库中docs/ascend_tutorial/zh/get_start/dockerfile_build_guidance.rst文档，系统讲解 verl 在昇腾 NPU（Atlas 系列）上的 Docker 镜像体系：公开镜像的获取渠道与命名规则、镜像内各组件版本清单、docker/ascend目录下全部 Dockerfile 的选型对照表、从零构建镜像的命令，以及容器启动、进入与目录挂载的完整操作模板。读完本文，你将能够在 Atlas 200T A2 Box16、Atlas 900 A2 PODc、Atlas 800T A3 等昇腾硬件上快速获取或自行构建 verl 训推环境，并正确启动容器完成后续的 GRPO 等 RL 训练验证。

一、镜像获取与公开镜像地址

verl 在昇腾平台上提供了托管于quay.io的ascend/verl镜像仓库（每日构建），镜像基于 docker/ascend 目录下的 Dockerfile 构建。用户有两种途径获得昇腾环境：

1. 直接拉取公开镜像（每日构建，随主分支持续更新）；
2. 根据docker/ascend下的 Dockerfile 自行构建（可锁定 CANN 版本、推理后端与 verl release 版本）。

镜像命名规则

公开镜像的命名遵循两套规则：

每日构建镜像名格式

latest-{推理后端}-{适用产品信息}-{操作系统}-{其他字段}

示例（见 supported_tags.md）：

• latest-vllm-910b-ubuntu：vLLM 推理后端 + 910b（A2）设备 + Ubuntu；
• latest-vllm-a3-ubuntu：vLLM 推理后端 + A3 设备 + Ubuntu；
• latest-sglang-910b-ubuntu、latest-sglang-a3-ubuntu：SGLang 推理后端对应设备。

verl release 版本镜像名格式

{verl release版本号}-{CANN版本}-{TorchNPU版本}[-{适用产品信息}-{操作系统}]-{Python版本}[-{推理后端}-{其他字段}]

示例（release/v0.8.0）：

• v0.8.0-cann9.0.0-torch_npu2.9.0.post2-910b-ubuntu22.04-py3.11-vllm
• v0.8.0-cann9.0.0-torch_npu2.9.0.post2-a3-ubuntu22.04-py3.11-vllm

历史版本示例：verl-8.5.0-910b-ubuntu22.04-py3.11-v0.7.1、verl-8.3.rc1-a3-ubuntu22.04-py3.11-v0.7.0。这套命名把 CANN 版本、torch_npu 版本、设备类型、操作系统、Python 版本与 verl 版本全部编码进标签中，方便在生产环境中精确对齐依赖。

二、镜像硬件支持范围

当前昇腾镜像与教程覆盖以下硬件平台：

• Atlas 200T A2 Box16（对应 Dockerfile 中的a2后缀，SOC 为ascend910b1，每卡 1 die）；
• Atlas 900 A2 PODc；
• Atlas 800T A3（对应 Dockerfile 中的a3后缀，每卡 2 die，因此 A3 机器上跑示例时需要将n_gpus_per_node设置为 16）。

从 Dockerfile 源码可以看到设备类型通过ARG SOC_VERSION="ascend910b1"与基础镜像cann:9.1.0-910b-ubuntu22.04-py3.12固定（Dockerfile.ascend_9.1.0_a2），构建脚本会依据uname -m自动区分aarch64与x86_64架构，分别导出对应的LD_LIBRARY_PATH（devlib 路径）以正确链接 CANN 运行库。

三、最新镜像内各组件版本信息清单

以下为最新镜像（基于 CANN 9.1.0）内置的组件版本，用户在规划环境时应以此为准对齐：

该清单与 昇腾安装指南 中的关键版本建议保持一致（vLLM 0.23.0 / torch 2.10.0 / torch_npu 2.10.0.post4 / MindSpeed 与 Megatron-LM 均为core_r0.18.0）。特别说明：2026/08 更新后，vLLM 后端镜像已弃用mbridge，改用Megatron-Bridge 0.5.0完成 DeepSeek 等模型的 Megatron 侧适配，这一点在 Dockerfile.ascend_9.1.0_a2 中可以看到git clone --branch v0.5.0 .../Megatron-Bridge.git并pip install -e Megatron-Bridge --no-build-isolation --no-deps的安装步骤。

四、Dockerfile 构建镜像脚本清单

所有 Dockerfile 均位于 docker/ascend 目录，按用途分为三类：通用镜像（跟随主分支每日构建）、verl release 版本镜像（锁定版本号）与模型定制镜像（针对特定模型调优）。

1. 通用镜像

2. verl release 版本镜像

3. 模型定制镜像

4. 源码安装说明

• vLLM 推理后端镜像：vLLM、vLLM-Ascend、MindSpeed、Megatron-LM、verl 均为源码安装，对应源码仓库位于镜像根目录/下（见 Dockerfile.ascend_9.1.0_a2 中的git clone与pip install -e步骤）。
• SGLang 推理后端镜像：SGLang、MindSpeed、verl 为源码安装，源码同样位于镜像根目录/下。

例如 SGLang 镜像（Dockerfile.ascend.sglang_8.5.0_a2）会先将python/pyproject_npu.toml替换为python/pyproject.toml再执行pip install -e python[all_npu]，随后安装sgl-kernel-npu提供的torch_memory_saver、sgl_kernel_npu、deep_ep三个 wheel 包；而 8.3.RC1 时代的 SGLang 镜像则通过bash build.sh与bash build.sh -a deepep2从源码编译 NPU 算子与 A2 专用的 deep_ep 包（Dockerfile.ascend.sglang_8.3.rc1_a2）。理解这些差异有助于排障：例如在 A2 上使用 SGLang 推理 EP 时，需要确认 deep_ep 是否按 deepep2 模式重新编译。

五、镜像构建命令示例

进入仓库中的 Dockerfile 所在目录，使用docker build指定-f构建对应的镜像：

# 进入包含 Dockerfile 的目录 cd {verl-root-path}/docker/ascend # 构建 vLLM 推理后端镜像（A2 / CANN 8.5.0） docker build -f Dockerfile.ascend_8.5.0_a2 -t verl-ascend:8.5.0-a2 . # 构建 SGLang 推理后端镜像（A2 / CANN 8.5.0） docker build -f Dockerfile.ascend.sglang_8.5.0_a2 -t verl-ascend-sglang:8.5.0-a2 . # 构建完成后查询本地镜像 docker images

参数说明：

• -f Dockerfile.ascend_8.5.0_a2指定 Dockerfile 文件名；
• -t verl-ascend:8.5.0-a2中，verl-ascend为自定义镜像名称，8.5.0-a2为自定义镜像标签；
• 构建上下文.为当前目录，Dockerfile 内的git clone均发生在容器内，宿主机无需预装任何依赖。

构建耗时提示：由于构建过程包含 vLLM/vLLM-Ascend 的源码安装（VLLM_TARGET_DEVICE=empty pip install -v -e .与COMPILE_CUSTOM_KERNELS=1的算子编译）以及 verl 源码安装，整体构建耗时较长。若机器内存或 CPU 核数有限，可参考模型定制镜像中的做法设置ENV MAX_JOBS=1、MAKEFLAGS="-j1"、CMAKE_BUILD_PARALLEL_LEVEL=1降低并行编译压力（Dockerfile.ascend_8.5.2_a2_qwen3-5）。

六、容器启动命令模板

镜像构建完成后，通过以下模板启动容器。该模板已包含昇腾 NPU 容器运行所需的关键挂载与权限参数：

docker run -dit \ --ipc=host \ --network host \ --name {your_docker_name} \ --privileged \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \ -v /usr/local/sbin:/usr/local/sbin \ -v /usr/sbin:/usr/sbin \ -v /home:/home \ -v /data:/data \ {image_name}:{tag} \ /bin/bash

参数含义与注意事项：

• --ipc=host：共享宿主机 IPC 命名空间，避免多进程/多卡场景下的共享内存问题；
• --network host：使用宿主机网络，保证容器内 Ray 集群、推理服务端口可直接对外暴露；
• --name {your_docker_name}：建议替换为具有实际意义的容器名称（如verl-ascend-a2）；
• --privileged：授予容器扩展权限（昇腾设备访问通常需要），请根据实际安全需求评估是否必要；
• -v /usr/local/Ascend/driver:/usr/local/Ascend/driver与-v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware：将宿主机 NPU 驱动与固件挂载进容器，是容器识别昇腾设备的前提；
• -v /usr/local/sbin:/usr/local/sbin、-v /usr/sbin:/usr/sbin：挂载系统级工具与驱动相关可执行文件；
• -v /home:/home、-v /data:/data：挂载用户目录与数据目录（模型权重、数据集通常存放在这里）；
• {image_name}:{tag}：替换为镜像构建时对应的名称与标签；
• 如需挂载其他本地路径，自行追加-v <宿主机路径>:<容器内路径>即可。

七、启动与进入容器

容器创建后，后续使用只需两步：

# 启动容器 docker start {your_docker_name} # 进入正在运行的容器 docker exec -it {your_docker_name} bash

进入容器后，建议依次执行以下验证与初始化（与 昇腾快速上手说明 保持一致）：

# 使能 CANN 环境（若自定义了 CANN 路径，请按实际路径修改） source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh # 验证 NPU 设备可被识别 python3 -c "import acl;print(acl.get_soc_name())"

验证通过后即可进入 verl 主目录运行 GRPO 等训练脚本（例如tests/special_npu/quick_start/下的run_qwen3_0_6b_fsdp2_vllm_ascend.sh等四种训推后端组合脚本）。

八、使用建议与声明

• 推荐路径：追求最新特性用每日构建镜像（latest-*标签）；追求稳定性与可复现性，使用 verl release 版本镜像（如v0.8.0-*）；有特殊模型需求（如 Qwen3.5）再选用模型定制镜像或自行构建。
• 与安装指南的关系：若不想使用 Docker，也可以参考 昇腾安装指南 通过scripts/install_vllm_mcore_npu.sh、scripts/install_sglang_mcore_npu.sh在 conda 环境中完成自定义安装（vLLM 后端对应 torch 2.10.0 / torch_npu 2.10.0.post4，SGLang 后端对应 torch 2.8.0 / torch_npu 2.8.0.post2），两种方式的核心依赖版本与本文镜像清单对齐。
• 声明：verl 中提供的 ascend 相关 Dockerfile、镜像皆为参考样例，可用于尝鲜体验；如在生产环境中使用，请通过官方正式途径沟通确认。

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