安装指南

版本配套表

MindSpeed RL支持Atlas 800T A2等昇腾训练硬件形态。软件版本配套表如下：

MindSpeed RL版本	Megatron版本	PyTorch版本	torch_npu版本	CANN版本	Python版本
master（主线）	Core 0.8.0	2.5.1	2.5.1	8.3.RC1	Python3.10
2.2.0（商分）	Core 0.8.0	2.5.1	2.5.1	8.3.RC1	Python3.10
2.1.0（商分）	Core 0.8.0	2.5.1	2.5.1	8.2.RC1	Python3.10
2.0.0（预览）	Core 0.8.0	2.5.1	2.5.1	8.1.RC1	Python3.10

昇腾辅助软件中有更多关于PyTorch和CANN的版本信息。

安装依赖的软件

在安装MindSpeed RL之前，请参考版本配套表，安装配套的昇腾软件栈，软件列表如下： （注：Ascend提供满足商用标准的稳定版本和具有新特性的社区体验版本供开发者选择）

依赖软件	版本
昇腾NPU驱动	25.3.0
昇腾NPU固件
Toolkit（开发套件）	8.3.RC1
Kernels（算子包）
NNAL神经网络加速库（Ascend Transformer Boost加速库）
Python	3.10
torch	2.5.1
torch_npu
apex	0.1
ray	2.42.1
vllm	main

驱动固件安装

（注：下载参考：商用稳定版固件与驱动和社区体验版固件与驱动）

bash Ascend-hdk-*-npu-firmware_*.run --full
bash Ascend-hdk-*-npu-driver_*.run --full

CANN安装

（注：下载参考：商用稳定版CANN和8.3.RC1 社区体验版CANN）

bash Ascend-cann-toolkit_*_linux-aarch64.run --install
bash Atlas-A3-cann-kernels_*_linux-aarch64.run --install
source /usr/local/Ascend/ascend-toolkit/set_env.sh
bash Ascend-cann-nnal_*_linux-aarch64.run --install
source /usr/local/Ascend/nnal/atb/set_env.sh

vllm及相关依赖安装：

（注：环境中需要安装git，因为vllm的安装过程依赖git）

# pydantic高版本包会产生冲突，指定版本安装
pip install pydantic==2.12.0
git clone -b releases/v0.9.1 https://github.com/vllm-project/vllm.git
cd vllm
git checkout b6553be1bc75f046b00046a4ad7576364d03c835
VLLM_TARGET_DEVICE=empty pip install .
cd ..

vllm_ascend安装

（注：若机器为x86架构，需要先进行PyTorch框架安装中的torch和torch_npu安装，安装vllm_ascend时，注释requirements.txt和pyproject.toml中torch和torch_npu的安装）

git clone -b v0.9.1-dev https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
git checkout 8c7bc45
pip install -r requirements.txt
pip install -e .

ray安装

pip install ray==2.42.1

PyTorch框架安装

（（注：PyTorch框架和torch_npu插件安装教程；可从PyTorch-Ascend官方代码仓获取PyTorch各个版本对应的torch_npu的whl包）

# 安装torch和torch_npu
pip install torch-2.5.1-cp310-cp310-*.whl
pip install torch_npu-2.5.1.*.manylinux2014_*.whl

# apex for Ascend 构建参考 https://gitcode.com/Ascend/apex
pip install apex-0.1.dev*.whl

高性能内存库 jemalloc 安装

为了确保 Ray 进程能够正常回收内存，需要安装并使能 jemalloc 库进行内存管理。

Ubuntu 操作系统

通过操作系统源安装jemalloc（注意： 要求Ubuntu版本>=20.04）。

sudo apt install libjemalloc2

在启动任务前执行如下命令通过环境变量导入jemalloc。

# arm64架构(可通过 find /usr -name libjemalloc.so.2 确认文件是否存在) 
export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2
# x86_64架构
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2

OpenEuler 操作系统

执行如下命令重操作系统源安装jemalloc。

yum install jemalloc

如果上述方法无法正常安装，可以通过源码编译安装 前往jemalloc官网下载最新稳定版本，官网地址:https://github.com/jemalloc/jemalloc/releases/

tar -xvf jemalloc-{version}.tar.bz2
cd jemalloc-{version}
./configure --prefix=/usr/local
make
make install

在启动任务前执行如下命令通过环境变量导入jemalloc。

根据实际安装路径设置环境变量，例如安装路径为：/usr/local/lib/libjemalloc.so.2，可通过以下命令来设置环境变量(通过 find /usr -name libjemalloc.so.2 确认文件是否存在)。

export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2

如以上安装过程出现错误，可以通过提出issue获得更多解决建议。

准备源码

git clone https://gitcode.com/Ascend/MindSpeed-RL.git -b 2.2.0

git clone https://gitcode.com/Ascend/MindSpeed.git 
cd MindSpeed
git checkout ca70c1338f1b3d1ce46a0ea426e5779ae1312e2e  # 参考MindSpeed-LLM依赖版本
pip install -r requirements.txt 
cp -r mindspeed ../MindSpeed-RL/
cd ..

# Megatron从github下载，请确保网络能访问
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout core_r0.8.0
cp -r megatron ../MindSpeed-RL/
cd ..

git clone https://gitcode.com/Ascend/MindSpeed-LLM.git -b 2.1.0
cd MindSpeed-LLM
git checkout bf1e61f
cp -r mindspeed_llm ../MindSpeed-RL/
cd ..

cd ./MindSpeed-RL
pip install -r requirements.txt
pip install antlr4-python3-runtime==4.9.3 --no-deps 

算子预编译

训练开始前进行算子预编译可以大大节省训练时的初次编译时间，在多机训练时可在每个节点上提前执行如下预编译命令。

python -c "import mindspeed; from mindspeed.op_builder import RotaryPositionEmbeddingOpBuilder; RotaryPositionEmbeddingOpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import MoeTokenPermuteOpBuilder; MoeTokenPermuteOpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import GMMOpBuilder; GMMOpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import GMMV2OpBuilder; GMMV2OpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import MoeTokenUnpermuteOpBuilder; MoeTokenUnpermuteOpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import MatmulAddOpBuilder; MatmulAddOpBuilder().load()" &
python -c "import mindspeed; from mindspeed.op_builder import GroupMatmulAddOpBuilder; GroupMatmulAddOpBuilder().load()"

FAQ

Q：安装过程中出现的软件依赖冲突，是否会影响正常运行？

A：建议软件安装顺序严格按照安装指南从上到下进行，此时遇到依赖冲突不会影响正常运行。