企业官网建设流程全解析

verl 昇腾 A5 安装指南：Ascend 950 系列 NPU 上的 vLLM + Megatron 训推环境搭建

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

本文以 verl 昇腾教程中的《昇腾安装指南(A5)》为核心，系统梳理在 Ascend 950 系列产品（A5 硬件代次）上从零搭建 verl 强化学习训练环境的完整流程，涵盖 vLLM 推理后端、Megatron/MindSpeed 训练后端与 verl 本体三大部分的关键版本矩阵、源码安装命令与环境配置细节。读完本文，你将掌握 A5 硬件上各组件精确的版本对应关系、可复制的安装命令序列，以及 A5 平台特有的环境变量与设备识别机制，可直接照此在昇腾 NPU 上部署一套可运行的 verl 训推链路。

背景与适用场景

verl（HybridFlow）是一个灵活高效的 RL 后训练框架。在昇腾生态中，verl 已全面支持在华为昇腾芯片 NPU 上运行，官方文档将硬件支持划分为 A2、A3 与Ascend 950 系列产品（对应A5硬件代次）三类，详见 昇腾安装指南。

本文针对的A5 平台是昇腾硬件家族中的新一代产品。从源码可以确认，verl 已为 A5 代次建立了显式的识别与分支逻辑：

• 在 设备能力识别模块 中，AscendHardwareVersion枚举定义了A2 = 2、A3 = 3、A5 = 5三档硬件代次；get_npu_versions()通过torch_npu.npu.get_device_name()获取设备名，当设备名包含Ascend910_95或Ascend950时即判定为AscendHardwareVersion.A5。
• 在 NPU 平台插件 中，存在针对A5硬件版本的独立处理逻辑，说明框架已为 A5 的通信、IPC 等能力做了专门适配。
• checkpoint 引擎说明 中特别指出：在 Ascend 950 上启用 kimi-checkpoint-engine 需要配置 HCCL 白名单（HCCL_WHITELIST_DISABLE=0与HCCL_WHITELIST_FILE），这是 A5 平台独有的部署注意事项。
• 模型迁移至 NPU 指南 提到，A2、A3 机型暂不支持 FP8 精度训练，仅支持 BF16；Ascend 950 系列产品后续版本将开放 FP8 低精度训练能力，这也是 A5 平台值得关注的能力演进方向。

本文档（install_guidance_A5.rst）即针对 Ascend 950 系列（A5）给出了一套精确到版本号的安装方案，下面按依赖矩阵与三个安装阶段逐一展开。

关键版本支持与依赖

在动手安装之前，首先需要锁定一组互相兼容的版本组合。A5 安装方案要求的版本矩阵如下：

几点说明：

• 版本对应关系遵循推理引擎 vLLM 0.23.0 ↔ 基础框架 torch 2.10.0的配套原则，这一组合与通用昇腾安装指南（install_guidance.rst）中 vLLM 后端的版本主线保持一致；A5 方案在 transformers 上采用4.57.6（较通用 A2/A3 方案的5.10.4更保守），Python 固定为3.11。
• CANN 与 torch_npu 两个组件的正式商用版本尚待 Q2 发布，安装前需留意官方后续更新的链接与版本号。
• Megatron-LM 使用分支名core_r0.12.0，MindSpeed 使用精确的 commit-id0c6c0ceaa523a96032dee1539a52032155e6404e锁定版本，这保证了训练侧源码的可复现性。

环境安装步骤

A5 环境的安装分为三条主线：vLLM 推理后端、Megatron 训练后端、verl 本体依赖。建议严格按照以下顺序执行。

一、vLLM 推理后端支持

vLLM 负责 rollout 阶段的推理采样，其安装分为 vLLM 本体与 NPU 适配层 vLLM-Ascend 两部分，均采用源码安装方式：

# 安装 vllm git clone https://github.com/vllm-project/vllm.git cd vllm git checkout v0.23.0 VLLM_TARGET_DEVICE=empty pip install -v -e . cd .. # 安装 vllm-ascend # 安装之前要先 source cann 环境： source /usr/local/Ascend/cann/set_env.sh git clone https://github.com/vllm-project/vllm-ascend.git cd vllm-ascend git checkout releases/v0.23.0 pip install -v -e . --no-build-isolation --extra-index-url https://triton-ascend.osinfra.cn/pypi/simple/ --trusted-host triton-ascend.osinfra.cn cd ..

关键细节：

• VLLM_TARGET_DEVICE=empty：以 "empty" 设备目标构建 vLLM，即不编译特定 GPU 后端代码，适配层（vLLM-Ascend）会在运行时接管 NPU 执行，这是昇腾场景下 vLLM 源码安装的标准做法。
• 先 source CANN 环境：安装 vLLM-Ascend 之前必须激活 CANN 环境变量（source /usr/local/Ascend/cann/set_env.sh），否则编译期无法找到 NPU 相关头文件与库。若 CANN 安装路径被自定义，请相应调整 source 命令。
• --no-build-isolation：跳过构建隔离，直接在当前 Python 环境中解析依赖；--extra-index-url指向 triton-ascend 的官方 PyPI 源，--trusted-host用于信任该源的 HTTPS 证书。这两处参数与 NPU 安装脚本 中 triton-ascend 的安装方式一致。
• vLLM-Ascend 的releases/v0.23.0分支与 vLLM 的v0.23.0标签严格对应，二者必须配套。

二、Megatron 训练后端支持

训练后端由 MindSpeed 与 Megatron-LM 及其相关依赖组成，全部通过源码安装：

# MindSpeed git clone https://gitcode.com/Ascend/MindSpeed.git cd MindSpeed git checkout 0c6c0ceaa523a96032dee1539a52032155e6404e pip install -e . cd .. # Megatron git clone https://github.com/NVIDIA/Megatron-LM.git cd Megatron-LM git checkout core_r0.12.0 pip install -e . cd .. # 配置环境变量 export PYTHONPATH=$PYTHONPATH:your_path/Megatron-LM export PYTHONPATH=$PYTHONPATH:your_path/MindSpeed # 安装 mbridge pip install mbridge

关键细节：

• MindSpeed是 Megatron-LM 在昇腾 NPU 上的适配与优化组件，通过gitcode.com/Ascend/MindSpeed.git获取，并用精确 commit-id 锁定；Megatron-LM从 NVIDIA 官方仓库拉取core_r0.12.0分支。
• PYTHONPATH必须同时包含 Megatron-LM 与 MindSpeed 的源码路径（请将your_path替换为实际克隆目录），因为 MindSpeed 与 verl 的 Megatron 训练链路在运行时需要直接 import 这两个包；建议将这两行export写入~/.bashrc或每次训练启动脚本的开头，避免新会话丢失环境。
• mbridge（Megatron Bridge）承担 MindSpeed 与 Megatron-LM 之间的桥接适配，pip install mbridge安装。需要注意的是，该桥接组件在后续版本演进中已发生变化——较新的通用安装方案（如 install_vllm_mcore_npu.sh）已改为安装 Megatron-Bridge 与 MindSpeed-Bridge 等组件，A5 方案当前仍以mbridge为准，两者不可混用。

三、verl 依赖安装

最后安装 verl 框架本体及其 NPU 专属依赖：

git clone https://github.com/verl-project/verl.git cd verl pip install -e . pip install -r requirements-npu.txt

• pip install -e .以可编辑模式安装 verl 主包（依赖定义见 pyproject.toml）。
• requirements-npu.txt是昇腾 NPU 环境的补充依赖清单，其内容见 requirements-npu.txt，重点包括：triton-ascend==3.2.2（与上表版本矩阵一致）、TransferQueue @ git+https://github.com/Ascend/TransferQueue.git@main（昇腾侧高性能传输队列，为 checkpooint 引擎等 P2P 场景提供底层传输能力）、ray[default]（verl 分布式调度依赖）、tensordict、torchdata、qwen_vl_utils等。安装时需确保网络可访问这些源码与索引源。

安装后的验证与 A5 平台注意事项

环境安装完成后，建议按以下顺序做最小化验证：

1. CANN 可用性：source /usr/local/Ascend/cann/set_env.sh后执行npu-smi info，确认 NPU 设备可被系统识别。
2. 框架版本核对：在 Python 中逐一检查import torch; torch.__version__、import torch_npu、import vllm; vllm.__version__、import megatron、import mindspeed，确认与版本矩阵一致。
3. verl 入口可用性：参考 昇腾快速上手说明 运行 Qwen3-0.6B GSM8K GRPO 快速验证脚本（位于 tests/special_npu/quick_start），检查 actor、rollout、reference worker 初始化与首个 step 的训练链路。

针对 A5 平台，还有以下几点需要特别关注：

• 设备自动识别：verl 支持自动识别 NPU 设备类型，包括 A5。运行训练任务时原则上无需显式设置trainer.device=npu；前提是环境中安装了torch_npu软件包，否则仍需显式指定。A5 设备（设备名包含Ascend910_95/Ascend950）会被 get_npu_versions() 正确归类。
• HCCL 白名单配置（kimi-checkpoint-engine 场景）：在 Ascend 950 上使用 kimi checkpoint 引擎时，需通过环境变量启用 HCCL 通信白名单，并在 JSON 文件中登记设备 IP：

export HCCL_WHITELIST_DISABLE=0 export HCCL_WHITELIST_FILE=/path/to/whitelist.json

whitelist.json 内容格式：

{ "host_ip": ["ip1"], ["ip2"] }

• 精度能力边界：A5 平台当前以 BF16 为默认混合精度训练基准；FP8 低精度训练能力将在后续版本开放，规划 FP8 相关实验时需关注官方后续版本公告。
• 日志过滤（可选）：若训练过程中 transformers 出现大量别名废弃告警干扰日志，可设置export TRANSFORMERS_VERBOSITY=error过滤冗余输出。

延伸阅读

• 通用昇腾安装指南（覆盖 A2/A3 的 vLLM + FSDP/Megatron、SGLang + FSDP/Megatron 组合）：昇腾安装指南
• 镜像获取与构建方式：若希望跳过源码安装，可直接使用昇腾每日构建镜像或自行构建 Dockerfile，详见 昇腾镜像说明 与 docker/ascend 目录
• 快速上手（含四种训推后端组合的最小 GRPO 验证流程）：昇腾快速上手说明
• NPU 平台插件与设备识别实现：platform_npu.py、device.py

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