安装指南

版本配套表

MindSpeed MM支持Atlas 800T A2等昇腾训练硬件形态。软件版本配套表可查看版本说明的相关产品版本配套说明章节。

昇腾软件安装

模型开发时推荐使用配套的环境版本

依赖软件	版本
昇腾NPU驱动	在研版本
昇腾NPU固件	在研版本
Toolkit（开发套件）	在研版本
Ops（算子包）
NNAL（Ascend Transformer Boost加速库）
Python	3.10
PyTorch	2.6.0, 2.7.1
torch_npu插件	在研版本

驱动固件安装

下载驱动固件，请根据系统和硬件产品型号选择对应版本的driver和firmware。参考安装NPU驱动固件或执行以下命令安装：

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

CANN安装

下载CANN，请根据系统选择aarch64或x86_64对应版本的cann-toolkit、cann-kernel和cann-nnal。参考CANN安装或执行以下命令安装：

# 因为版本迭代，包名存在出入，根据实际修改
bash Ascend-cann-toolkit_8.5.0_linux-aarch64.run --install
bash Ascend-cann-*-ops_8.5.0_linux-aarch64.run --install
# 根据实际情况修改 ascend-toolkit 路径
source /usr/local/Ascend/cann/set_env.sh # 安装nnal包需要source环境变量
bash Ascend-cann-nnal_8.5.0_linux-aarch64.run --install
# 设置环境变量
# 根据实际情况修改 ascend-toolkit 路径
source /usr/local/Ascend/cann/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

Python依赖安装

Python依赖安装有一键安装和手动安装两种方式，一键安装可以快速安装所需要的所有三方库，手动安装可以灵活指定需要使用的各三方库版本，方便开发者进行调试，请按照自己的需求选择合适的安装方式。

一键安装

一键安装指令会依次安装pytorch、torch_npu、Megatron-LM、MindSpeed、MindSpeed-MM库。由于Megatron-LM对于pip install安装方式适配性待提升，采用源码拷贝方式进行使用。

以qwen3vl模型安装指令为例：

bash scripts/install.sh --msid 93c45456c7044bacddebc5072316c01006c938f9 && pip install -r examples/qwen3vl/requirements.txt

scripts/install.sh提供了如下选项供使用：

Options:
    -a, --arch ARCH         Target architecture (x86|arm) [required]
    -t, --torchversion VERSION   PyTorch version to install (default: 2.7.1)
    -m, --msid COMMIT_ID    MindSpeed commit ID [required]
    -h, --help              Display this help message and exit

-a, --arch：表示当前安装环境的机器的CPU架构，当前支持x86或arm。此选项为必选选项，会影响安装torch、torch_npu库时使用的版本。 -t, --torchversion：非必选项。表示当前使用的torch版本，默认值为2.7.1。 -m, --msid：必选选项。表示当前基于源码安装的MindSpeed加速库的commit id。 -h, --help：非必选选项，显示安装帮助。

若当前环境中已经安装了pytorch或torch_npu，安装时会在控制台打印如下信息，样例如下：

Version check results:
Currently installed torch version: 2.6.0, target version: 2.7.1
Currently installed torch_npu version: 2.6.0, target version: 2.7.1
Version mismatch detected. Continue installation? (y/n)

表示检测到环境中已经安装了2.6.0版本的pytorch和torch_npu。如果您希望安装新版本的torch和torch_npu，请输入y；如果希望保持已安装的pytorch和torch_npu，请输入n。

在安装完成之后，若控制台打印如下信息：

mindspeed mm successfully installed！

说明安装成功。

支持模型列表

目前qwen3vl、wan2.2等模型已支持一键安装，具体支持情况可以查看具体模型的README。

手动安装

该方法适用于单独安装PTA和其他三方库进行开发调试的用户使用。

1.安装pytorch和torch_npu

准备[torch_npu](https://www.hiascend.com/developer/download/community/result?module=pt)，参考[Ascend Extension for PyTorch 配置与安装](https://www.hiascend.com/document/detail/zh/Pytorch/730/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md)或执行以下命令安装：

安装torch和torch_npu，以下以python 3.10 + torch 2.7.1为例：

```shell
conda create -n test python=3.10
conda activate test
# 注：若需安装torch2.6.0版本需要修改列对应whl包，并且修改 MindSpeed-MM/pyproject.toml中的torch版本为2.6.0
pip install torch-2.7.1-cp310-cp310*.whl
pip install torch_npu-2.7.1*-cp310-cp310*.whl
```

2.仓库拉取及Megatron安装

拉取MindSpeed MM仓库并安装Megatron
```shell
git clone https://gitcode.com/Ascend/MindSpeed-MM.git
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout core_v0.12.1
cp -r megatron ../MindSpeed-MM/
cd ..
cd MindSpeed-MM
```

3.安装MindSpeed加速库

拉取并安装MindSpeed加速库
```shell
# 安装加速库
git clone https://gitcode.com/Ascend/MindSpeed.git
cd MindSpeed
# 根据需要切换到特定的分支或commit id
git checkout 93c45456c7044bacddebc5072316c01006c938f9
pip install -r requirements.txt
pip install -e .
cd ..
```

4.安装其它依赖

```shell
# 安装MindSpeed MM其它依赖
pip install -e .
```