企业官网建设流程全解析

verl 在昇腾 NPU 上的完整安装部署指南：vLLM/SGLang × FSDP/Megatron 双后端组合

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

本篇技术指南以 docs/ascend_tutorial/zh/get_start/install_guidance.rst 为核心骨架，系统讲解 verl 在昇腾（Ascend）NPU 平台上的环境安装与部署全流程：涵盖支持的硬件型号与训推后端组合、Docker 镜像获取与构建、vLLM 与 SGLang 两条自定义源码安装路径的完整依赖版本清单、HDK/CANN 前置准备、一键安装脚本的底层执行逻辑，以及 SGLang 后端的特殊环境变量配置。读者完成后可依据本文在 Atlas A2/A3 设备上从零搭建一套可运行的 verl 强化学习训练环境，并可结合 快速上手指南 直接跑通首个 GRPO 训练任务。

硬件支持范围

当前昇腾安装指南覆盖以下 Atlas 系列产品：

• Atlas 200T A2 Box16（910B 系列，单卡 1 die）
• Atlas 900 A2 PODc（910B 系列集群形态）
• Atlas 800T A3（A3 系列，每卡含 2 die，跑示例时n_gpus_per_node需设为 16）
• Ascend 950 系列产品：详见专门的 昇腾安装指南(A5)，该文档给出了 vLLM 0.23.0 + Megatron-LMcore_r0.12.0的独立安装步骤

需要特别说明的是：从 2025/12/11 起，verl 存量场景已支持自动识别 NPU 设备类型，GPU 脚本在昇腾上运行时原则上不再需要显式设置trainer.device=npu；但自动识别的前提是运行环境包含torch_npu软件包，若环境中没有安装torch_npu，仍需显式指定trainer.device=npu。新增特性仍可通过设置trainer.device优先指定设备类型。

框架后端支持说明

当前 NPU 上支持以下常见训推后端组合，每种组合均有完整的部署路径（Docker 镜像或自定义源码安装）：

即用户可以根据模型规模与并行策略偏好，自由组合「推理引擎」与「训练引擎」，形成四种常用组合：vLLM + FSDP2、vLLM + Megatron、SGLang + FSDP2、SGLang + Megatron。每种组合在 tests/special_npu/quick_start 下都有对应的可直接运行的最小验证脚本。

部署方式一：Docker 镜像获取、构建与使用

镜像获取

昇腾官方在 quay.io 的ascend/verl仓库中托管了每日构建的 A2/A3 镜像，镜像基于 docker/ascend 目录下的 Dockerfile 构建。镜像命名遵循两种格式：

• 每日构建镜像：latest-{推理后端}-{适用产品信息}-{操作系统}-{其他字段}
• verl release 版本镜像：{verl release版本号}-{CANN版本}-{TorchNPU版本}[-{适用产品信息}-{操作系统}]-{Python版本}[-{推理后端}-{其他字段}]

当前每日镜像内置的主要组件版本可参考 dockerfile_build_guidance.rst 中的版本清单（CANN 9.1.0、torch 2.10.0、vLLM 0.23.0、Megatron-LMcore_r0.18.0等）；完整的镜像 tag 列表参见 docker/ascend/supported_tags.md，其中按「Latest / verl Release / Model-Specific / History」四类归档了各 tag 对应的 Dockerfile 与设备类型（910b 对应 A2、A3）。

自行构建镜像

以 vLLM 后端的 A2 镜像为例，在仓库根目录执行：

cd docker/ascend # vLLM 后端 docker build -f Dockerfile.ascend_8.5.0_a2 -t verl-ascend:8.5.0-a2 . # SGLang 后端 docker build -f Dockerfile.ascend.sglang_8.5.0_a2 -t verl-ascend-sglang:8.5.0-a2 . # 构建后查询本地镜像 docker images

其中Dockerfile.ascend_8.5.0_a2是 Dockerfile 文件名，verl-ascend:8.5.0-a2中verl-ascend为自定义镜像名称、8.5.0-a2为自定义镜像标签。以 docker/ascend/Dockerfile.ascend_9.1.0_a3 为例，其构建逻辑清晰反映了整个安装链路：基础镜像为ascendhub/cann:9.1.0-a3-ubuntu22.04-py3.12；先安装 gcc/cmake 等系统依赖；x86_64 平台自动配置https://download.pytorch.org/whl/cpu/作为 pip 额外源；随后 clone vLLM（v0.23.0）、vLLM-Ascend、MindSpeed（core_r0.18.0）、Megatron-LM、MegatronAdaptor、TransformerEngineNPU、MindSpeed-Ops、MindSpeed-Bridge、Megatron-Bridge（v0.5.0）等源码仓库并以pip install -e方式安装；最后 clone verl 并安装requirements-npu.txt。

容器启动命令模板

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

要点说明：

• 如需挂载其他本地路径到容器，自行追加-v <宿主机路径>:<容器内路径>；
• {your_docker_name}建议替换为有实际意义的容器名；
• --privileged授予容器扩展权限，请按实际安全需求评估是否必要；
• 启动后通过docker start {your_docker_name}启动容器，用docker exec -it {your_docker_name} bash进入容器。
• 注意：verl 提供的 ascend 相关 Dockerfile 与镜像均属参考样例，可用于尝鲜体验；生产环境使用请通过官方正式途径沟通确认。

部署方式二：自定义安装 vLLM + FSDP/Megatron

如果希望精确控制环境中每个组件的版本，或在已有昇腾系统上增量部署，可以选择源码自定义安装。verl 仓库提供了基于 conda 的一键部署脚本 scripts/install_vllm_mcore_npu.sh，脚本分步骤安装环境，若中途报错可根据当前步骤的报错信息排查，或通过 issue 反馈。

关键版本支持与依赖

版本演进说明（该文档的关键更新记录）：vLLM / vLLM-Ascend 曾先后从0.13.0更新至0.18.0（torch2.9.0、torch_npu2.9.0.post2），再更新至0.23.0（torch2.10.0、torch_npu2.10.0.post2）；MindSpeed / Megatron-LM 从core_r0.16.0更新为core_r0.18.0，同时弃用 mbridge、改用 Megatron-Bridge（版本0.5.0）。

安装前准备（HDK & CANN）

CANN 是 NPU 上的异构计算架构。以下为arm 平台 A3的安装指令，也可根据系统硬件型号从 CANN 社区下载安装。整个准备过程分为四步：配置用户属组 → 安装依赖并配置 yum 源 → 安装 NPU 驱动与 CANN 软件 → 安装后验证。

# 配置用户属组 sudo groupadd HwHiAiUser sudo useradd -g HwHiAiUser -d /home/HwHiAiUser -m HwHiAiUser -s /bin/bash # 安装依赖&配源 sudo yum makecache sudo yum install -y gcc python3 python3-pip kernel-headers-$(uname -r) kernel-devel-$(uname -r) sudo curl https://repo.oepkgs.net/ascend/cann/ascend.repo -o /etc/yum.repos.d/ascend.repo && yum makecache # 安装 NPU 驱动 sudo yum install -y Atlas-A3-hdk-npu-driver-26.0.rc1 # 安装 Toolkit，可指定 --install-path 自定义路径 sudo yum install -y Ascend-cann-toolkit-9.1.0 sudo yum install -y Ascend-cann-A3-ops-9.1.0 # 安装后验证 source /usr/local/Ascend/ascend-toolkit/set_env.sh python3 -c "import acl;print(acl.get_soc_name())"

最后一条验证命令能正确打印出 SoC 名称，说明驱动与 CANN 环境已就绪，可以进入源码安装阶段。

源码安装（一键脚本）

# 注意：在 x86 平台安装时，pip 需要配置额外的源，指令如下： # pip config set global.extra-index-url "https://download.pytorch.org/whl/cpu/" # 使能 CANN 环境，如果自定义了 CANN 路径，请按自定义路径修改以下命令 source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh conda create -n verl-vllm-npu python=3.12 -y conda activate verl-vllm-npu git clone --recursive https://github.com/verl-project/verl.git bash verl/scripts/install_vllm_mcore_npu.sh # 如果仅需要使用 FSDP 后端（不安装 Megatron 组件） # USE_MEGATRON=0 bash verl/scripts/install_vllm_mcore_npu.sh

脚本内部执行逻辑拆解（对应 scripts/install_vllm_mcore_npu.sh 的五个阶段）：

1. 基础包安装：卸载旧版 triton/triton-ascend，安装 torchvision0.25.0、torchaudio2.10.0，从triton-ascend.osinfra.cn私有源安装 triton-ascend3.2.2，随后安装 transformers5.10.4与 setuptools-scm。
2. vLLM 与 vLLM-Ascend 安装：clone vLLMv0.23.0分支后以VLLM_TARGET_DEVICE=empty pip install -v -e .方式安装（empty 模式跳过 CUDA 相关编译）；再 clonereleases/v0.23.0分支的 vLLM-Ascend，更新子模块并执行COMPILE_CUSTOM_KERNELS=1 pip install --no-build-isolation --no-deps -v -e .编译 NPU 自定义 kernel。
3. Megatron 与 MindSpeed 安装（受USE_MEGATRON环境变量控制，默认开启）：clone MindSpeed 并 checkoutcore_r0.18.0，clone Megatron-LMcore_r0.18.0，随后安装 MegatronAdaptor、TransformerEngineNPU、MindSpeed-Ops、MindSpeed-Bridge 与 Megatron-Bridge（v0.5.0）等 Ascend 适配组件——这正是文档中「弃用 mbridge，改用 Megatron-Bridge」的落地体现。
4. verl 安装：pip install -v -e .安装 verl 本体，再安装requirements-npu.txt（该文件锁定了 triton-ascend3.2.2、TransferQueue 等 NPU 侧关键依赖）；脚本还建议将recipe子模块更新至 main 分支以获得更佳体验。
5. 收尾检查：补充安装 transformers5.10.4与 xgrammar0.1.33。

日志过滤

transformers 升级到5.10.4后可能出现大量别名废弃（deprecation）告警，可通过环境变量过滤冗余日志：

export TRANSFORMERS_VERBOSITY=error

部署方式三：自定义安装 SGLang + FSDP/Megatron

SGLang 路径与 vLLM 路径结构对称，但组件版本与前置依赖不同，且 SGLang 后端有额外的环境变量要求，建议严格按下文执行。

关键版本支持与依赖

注意与 vLLM 路径的差异：SGLang 路径 Python 推荐3.11、CANN 要求>=8.5.0、Megatron 组件停留在core_r0.16.0且仍使用 mbridge 方案。

安装前准备（HDK & CANN）

同样是 arm 平台 A3 的指令模板：

# 配置用户属组 sudo groupadd HwHiAiUser sudo useradd -g HwHiAiUser -d /home/HwHiAiUser -m HwHiAiUser -s /bin/bash # 安装依赖&配源 sudo yum makecache sudo yum install -y gcc python3 python3-pip kernel-headers-$(uname -r) kernel-devel-$(uname -r) sudo curl https://repo.oepkgs.net/ascend/cann/ascend.repo -o /etc/yum.repos.d/ascend.repo && yum makecache # 安装 NPU 驱动 sudo yum install -y Atlas-A3-hdk-npu-driver-25.5.0 # 安装 Toolkit，可指定 --install-path 自定义路径 sudo yum install -y Ascend-cann-toolkit-8.5.0 sudo yum install -y Ascend-cann-A3-ops-8.5.0 # 安装后验证 source /usr/local/Ascend/ascend-toolkit/set_env.sh python3 -c "import acl;print(acl.get_soc_name())"

源码安装（一键脚本）

# 注意：在 x86 平台安装时，pip 需要配置额外的源，指令如下： # pip config set global.extra-index-url "https://download.pytorch.org/whl/cpu/" # 使能 CANN 环境，如果自定义了 CANN 路径，请按自定义路径修改以下命令 source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh conda create -n verl-sgl-npu python=3.11 -y conda activate verl-sgl-npu git clone --recursive https://github.com/verl-project/verl.git bash verl/scripts/install_sglang_mcore_npu.sh # 如果仅需要使用 FSDP 后端 # USE_MEGATRON=0 bash verl/scripts/install_sglang_mcore_npu.sh

脚本内部执行逻辑拆解（对应 scripts/install_sglang_mcore_npu.sh 的六个阶段）：

1. SGLang 源码安装：clonev0.5.10分支，将python/pyproject.toml替换为 NPU 专用配置pyproject_npu.toml，再执行pip install -e python[srt_npu]安装带 NPU 运行时扩展的 SGLang。
2. 基础包安装：安装 torch2.8.0、torch_npu2.8.0.post2、torchvision0.23.0、pyyaml，以及 pybind11、click、mbridge、numpy<2.0.0、cachetools。
3. sgl-kernel-npu 安装：从 sgl-kernel-npu 的 release 下载对应torch2.8.0-py311-cann8.5.0-a3-${ARCH}的 zip 包（ARCH 通过uname -m自动识别），解压后依次安装torch_memory_saver、sgl_kernel_npu、deep_ep三个 whl，并对deep_ep的共享库建立符号链接后验证其可导入——这是 NPU 上 MoE 推理（DeepEP 通信）的关键底层组件。
4. Megatron 与 MindSpeed 安装（受USE_MEGATRON控制）：clone MindSpeed 并 checkoutcore_r0.16.0、clone Megatron-LMcore_r0.16.0，pip install -e安装两者并pip install mbridge。
5. verl 安装：先切到recipe子模块 main 分支，安装requirements-npu.txt，再pip install -v -e .。
6. 收尾：卸载 timm（避免与部分 NPU 推理链路冲突），补充安装 pyyaml、uvicorn、fastapi、pybase64、openai、partial_json_parser、python-multipart 等服务端依赖。

SGLang 使用注意事项（必读）

当前 NPU 上使用 SGLang 后端，必须添加以下环境变量：

# 支持 NPU 单卡多进程 export HCCL_HOST_SOCKET_PORT_RANGE=60000-60050 export HCCL_NPU_SOCKET_PORT_RANGE=61000-61050 # 规避 Ray 在 device 侧调用无法根据 is_npu_available 接口识别设备可用性 export RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES=1 # 根据当前设备和需要卡数定义 export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 # in A3（16 卡） # export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15 # 使能推理 EP 时需要 export SGLANG_DEEPEP_BF16_DISPATCH=1

这几组变量的作用分别是：前两组为 HCCL 通信预留 host/NPU 侧 socket 端口段，支撑 NPU 单卡多进程场景；RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES=1规避 Ray 无法通过is_npu_available识别设备的问题；ASCEND_RT_VISIBLE_DEVICES显式指定参与计算的 NPU 设备列表（A2 为 8 卡、A3 为 16 卡）；SGLANG_DEEPEP_BF16_DISPATCH=1在启用推理 Expert Parallel（EP）时开启 DeepEP 的 BF16 分发。

这些环境变量的用法在 tests/special_npu/quick_start 下的四个快速开始脚本中均有完整呈现，例如 run_qwen3_0_6b_megatron_sglang_ascend.sh 同时导出了HCCL_CONNECT_TIMEOUT=1500与上述三组 HCCL/Ray 变量，并在启动参数中通过+actor_rollout_ref.rollout.engine_kwargs.sglang.attention_backend="ascend"指定 SGLang 的 NPU 注意力后端。

安装后的验证与快速上手

环境安装完成后，可按 快速上手指南 进行最小链路验证。该指南以 Qwen3-0.6B + GSM8K 数据集为基础，提供四种训推后端组合的验证脚本：

四个脚本主要用来检查：verl 入口是否可用、数据是否可读取、actor/rollout/reference worker 是否能初始化、vLLM-Ascend/SGLang rollout 是否能生成、训练链路能否完成首个 step。运行时需先下载 Qwen3-0.6B 权重（默认路径~/models/Qwen/Qwen3-0.6B），并用python3 examples/data_preprocess/gsm8k.py --local_dataset_path /download/path/hf_data/gsm8k/预处理 GSM8K 数据，生成~/data/gsm8k/train.parquet与test.parquet；执行前同样需要 source CANN 环境并配置ASCEND_RT_VISIBLE_DEVICES。此外，SGLang 后端的 vLLM 脚本转换要点（rollout.name=sglang、attention_backend="ascend"、deepep_mode、enable_dp_attention、chunked_prefill_size等参数）也记录在该指南的「SGLang 后端使能说明」一节。

附录：昇腾暂不支持的生态库说明

verl 中昇腾暂不支持以下生态库：

即在昇腾 NPU 上不应单独安装flash_attn包来开启 flash attention 加速；相关加速能力需借助 transformers 框架本身的路径（以及上文中安装的 sgl-kernel-npu / vLLM-Ascend 自定义 kernel）获得。理解这一限制有助于在昇腾环境迁移 GPU 脚本时提前排查依赖冲突。

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