安装 MUSA SDK 5.1.0
本文档介绍如何在 Linux 平台安装 MUSA SDK 5.1.0,包括驱动程序 (Linux Driver)、MUSA 开发工具包 (MUSA Toolkit) 以及加速库 (muDNN 和 MCCL)。文档提供在线安装(APT)和离线安装两种方式,其中在线安装包括配置 Mthreads APT 软件源和安装软件包。按照本文档完成操作后,您可以快速搭建可用的 MUSA 开发环境。
执行以下所有操作需要具备系统管理员 root 权限或使用 sudo 命令。
安装流程概览
建议按以下顺序完成安装。下表列出了各步骤的作用及是否必需:
| 步骤 | 操作 | 说明 | 是否必需 |
|---|---|---|---|
| 1 | 下载安装包 | 选择在线或离线安装方式,并准备对应安装资源 | 是 |
| 2 | 安装驱动 | 安装 Linux Driver,提供 GPU 驱动和设备管理能力 | 是 |
| 3 | 安装 MUSA Toolkit | 安装编译器、运行时和基础开发工具链 | 是 |
| 4 | 安装 muDNN | 安装深度学习训练和推理所需的加速库 | 按需 |
| 5 | 安装 MCCL | 安装单机多卡和多机多卡通信组件 | 按需 |
| 6 | 验证安装 | 验证基础开发环境和按需安装的组件是否生效 | 建议 |
根据您的开发目标,可按以下方式继续:
- 如果您只是进行 MUSA 程序开发,完成 步骤 2 和 步骤 3 后即可开始编译和运行示例程序。
- 如果您涉及深度学习或多卡通信,请继续安装 muDNN 或 MCCL。
步骤 1:下载安装包
MUSA SDK 提供在线安装和离线安装两种方式。您可以按照自己的习惯和环境条件进行选择,推荐优先使用在线安装(APT)。 下表概述了两种安装方式的适用场景和说明:
| 安装方式 | 适用场景 | 说明 |
|---|---|---|
| 在线安装(APT) | 全新 Ubuntu 22.04 x86_64 Server 环境 | 通过 DEB 配置包自动配置 APT 软件源后直接安装 |
| 离线安装 | 受控环境、需要明确安装包版本 | 手动下载软件包并执行安装 |
使用在线安装(APT)前,建议先确认以下事项:
- APT 方式仅适用于上述全新环境。
- 如果系统中已经通过旧版 DEB、tar 包或其他方式安装过 Linux Driver 或 MUSA Toolkit,请先按原安装方式卸载干净,再执行在线安装流程。更多详情,参见历史版本中的对应安装指导。
- 在线安装(APT)
- 离线安装
请按以下步骤,使用 DEB 配置包自动配置 APT 软件源:
-
下载配置包:
wget https://dl.mthreads.com/repo/repository/ubuntu2204/pool/jammy/amd64/musa-repo-jammy_1.0.0.11-1_all.deb -
安装配置包:
sudo dpkg -i musa-repo-jammy_1.0.0.11-1_all.deb -
更新本地缓存:
sudo apt update
更新缓存后,可通过 APT 直接安装以下软件包:
| 组件 | 软件包 |
|---|---|
| Linux Driver | mthreads-driver |
| MUSA Toolkit | musa-toolkit |
| muDNN | libmudnn3-musa-5 |
| MCCL(S5000 系列) | mccl-s5000 |
| MCCL(S4000 系列) | mccl-s4000 |
离线安装包应包含以下文件:
├── Installation_guide_for_MUSA_SDK_rc5.1.0.pdf
├── MUSA SDK rc5.1.0 发布说明.pdf
├── MUSA_Programming_Guide_v0.9.4.pdf
├── MCCL_rc2.3.0
│ ├── MCCL_API_Reference_rc2.3.0.pdf
│ └── mccl.2.3.0.PH1.tar.gz
├── MT_Linux_Driver_5.1.0
│ └── musa_5.1.0-server_amd64.deb
├── muTriton_rc1.6.0
│ └── triton_1.6.0.py310.tar.gz
├── muDNN_rc3.3.0
│ └── mudnn.3.3.0.PH1.tar.gz
├── MUSA_Toolkits_rc5.1.0
│ ├── docs
│ │ ├── muBLAS_API_Reference_rc1.6.0.pdf
│ │ ├── muDNN_API_Reference_rc2.7.0.pdf
│ │ ├── muFFT_API_Reference_rc1.6.0.pdf
│ │ ├── muSOLVER_API_rc1.0.0.pdf
│ │ ├── muSPARSE_API_Reference_rc1.1.0.pdf
│ │ ├── muPP_API_Reference_rc1.7.0.pdf
│ │ ├── muRAND_API_Reference_rtm1.0.1.pdf
│ │ ├── MUSA_Compiler_Collection_User_Manual_rc3.1.0.pdf
│ │ ├── MUSA_Driver_API_Reference_rc3.1.0.pdf
│ │ ├── MUSA_Runtime_API_Reference_rc3.1.0.pdf
│ │ └── MCCL_API_Reference_rc2.3.0.pdf
│ └── musa_toolkits_5.1.0.tar.gz
└── SmartIO_1.2
└── mt-peermem_1.2_amd64.deb
步骤 2:安装驱动
1. 确认资源需求
- MT GPU 卡
- 操作系统:Ubuntu 22.04
- 内核版本:5.15.0-105-generic
集群内部机器无法直接在宿主机上安装 deb 包,请卸载 operator 相关组件后安装。
2. 配置 BIOS
-
S4000 显卡:如果使用的是内存 >=256G 的服务器,且显卡是 S4000,则必须 开启 IOMMU(VT-d) 选项
-
S5000 显卡:如果使用的显卡是 S5000,则必须 关闭 IOMMU (VT-d) 选项
开启 IOMMU(Intel CPU)
# 如果 IOMMU 是关闭的,可通过如下步骤开启
sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=on iommu.passthrough=0"/' /etc/default/grub
# 如果你的 CPU 是 AMD/HG,请改为 amd_iommu=on,而不是 intel_iommu=on
sudo update-grub
sudo reboot
关闭 IOMMU(Intel CPU)
# 如果 IOMMU 是开启的,可通过如下步骤关闭
sudo sed -i 's/^GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=off iommu=off iommu.passthrough=1 crashkernel=512M-:768M"/' /etc/default/grub
sudo update-grub
sudo reboot
判断 IOMMU 当前状态
sudo dmesg | grep -Ei "DMAR|IOMMU|VT-d|remapping"
上述 sed 命令会清除系统上原有的 quiet,以保证重启后 BMC 能看到图形界面。另外,请务必选择软重启,硬重启不能保证所有写入行为同步到文件。
- PC 配置:如果是 PC,需要将 BIOS 中的
resize bar选项设置为 ON- 将显示器连接到主板上,并断开电源重新启动计算机。在启动过程中,按下 Delete 键 以进入 BIOS 设置界面
- 在 BIOS 设置界面中,找到并开启 Above 4G 选项
- 查找并将 Resize Bar 开关置为 ON。请注意,大部分主板在首次开机时此选项默认为 OFF,并且通常显示在 BIOS 菜单的右上角
- 重启计算机,系统正常加载后,执行
lspci -nn | grep 1ed5确认显卡已识别
3. 安装 MT 驱动
用于安装摩尔线程显卡的底层驱动程序。
-
选择安装方式
- 在线安装(APT)
- 离线安装
完成 APT 配源后,可直接在线安装 Linux Driver。
-
安装驱动
sudo apt install mthreads-driver -
重启系统 强烈建议重启电脑来使驱动生效
sudo reboot -
如需在不重启的情况下重新加载驱动
modprobe -rv mtgpu && modprobe -v mtgpu
-
确认环境依赖
# 查看 PCI 是否识别到显卡lspci -nn | grep 1ed5# 安装依赖包(若已安装请忽略)sudo apt install linux-headers-$(uname -r)sudo apt install linux-modules-$(uname -r)sudo apt install linux-modules-extra-$(uname -r)sudo apt install dkms -
卸载驱动
# 卸载 old musa debsudo dpkg -P musa# 如果报错 mtgpu is inuse,直接重启即可sudo modprobe -rv mtgpu# 查询是否仍有 mtgpu ko 残留lsmod | grep mtgpu -
安装驱动
安装 MT Linux Driver,以
musa_5.1.0-server_amd64.deb包为例:注意:Linux Driver 版本与 MUSA Toolkit 版本独立,请根据硬件兼容性选择合适的 Linux Driver 版本。
sudo apt install ./musa_5.1.0-server_amd64.deb重启电脑来使驱动生效(强烈建议):
sudo reboot如需在不重启的情况下重新加载驱动:
modprobe -rv mtgpu && modprobe -v mtgpu
-
设置用户组
非 Root 用户如需获取设备使用权限,可参考以下方式设置:
# 把普通用户账号,加进 render & video groupsudo usermod -aG render,video ${USER}# 重新登入账户
4. 验证安装并查询版本
-
使用 mthreads-gmi 验证
# 通过 mthreads-gmi 校验 Linux Driver 安装# 命令行执行 mthreads-gmi,能够展示 gmi 版本号、Driver 版本号、显卡相关主要信息等mthreads-gmi -
查看版本信息
- 在线安装(APT)
- 离线安装
# 可通过包管理器或者 mthreads-gmi 工具查看驱动的版本信息dpkg -s mthreads-driver# 或者mthreads-gmi# 可通过包管理器或者 mthreads-gmi 工具查看驱动的版本信息dpkg -s musa# 或者mthreads-gmi
5. 配置其他选项
多卡环境,配置用户可见设备
通过设置 MUSA_VISIBLE_DEVICES 环境变量来指定使用的显卡,如:
export MUSA_VISIBLE_DEVICES=0,1,2,3
指定前 4 张显卡可见。
关闭开机自动加载 mtgpu.ko
# 在 /etc/modprobe.d/blacklist.conf 中设置
echo "blacklist mtgpu" >> /etc/modprobe.d/blacklist.conf
步骤 3:安装 MUSA Toolkit
1. 确认前提条件
已安装兼容版本 MT GPU 驱动。
-
检查 MT GPU 驱动版本:
mthreads-gmi -
若未安装或未安装适配版本 MT GPU 驱动,请先完成上一节的驱动安装与验证。
2. 安装 MUSA Toolkit
MUSA Toolkit 包含了针对摩尔线程 GPU 进行通用计算开发的必要编译器和工具链,支持安装到主机(host)或 docker 环境中。
运行环境在 docker 上,建议通过 container-toolkit 创建容器,否则需要手动映射 host 上的 /usr/lib/x86_64-linux-gnu/libmusa.so* 到容器中。
- 在线安装(APT)
- 离线安装
完成 APT 配源后,可直接在线安装 MUSA Toolkit。
sudo apt install musa-toolkit
-
执行安装
先进入到安装包的下载目录下,然后依次执行:
# 以 musa_toolkits_5.1.0.tar.gz 为例tar -zxvf musa_toolkits_5.1.0.tar.gzcd musa_toolkits_installbash ./install.sh -u # 先卸载环境已安装的 musabash ./install.sh # 以上两条命令非 root 用户需要 sudo 提权执行正常安装完毕后,终端会输出如下提示:
Successfully installed MUSA in /usr/local/musaPlease export /usr/local/musa/bin to PATH in ~/.bashrcexport PATH=/usr/local/musa/bin:${PATH}Please export /usr/local/musa/lib to LD_LIBRARY_PATH in ~/.bashrcexport LD_LIBRARY_PATH=/usr/local/musa/lib:${LD_LIBRARY_PATH} -
配置环境变量
-
文本编辑器打开用户终端配置文件:
vim ~/.bashrc -
在打开的配置文件末 尾追加如下命令:
export MUSA_INSTALL_PATH=/usr/local/musaexport PATH=$MUSA_INSTALL_PATH/bin:$PATHexport LD_LIBRARY_PATH=$MUSA_INSTALL_PATH/lib:$LD_LIBRARY_PATH -
配置文件会在下次启动终端时生效。如果想立即在当前终端生效,请执行:
source ~/.bashrc
-
3. 验证安装
验证 MUSA Toolkit 是否安装成功,运行以下命令:
musa_version_query
将输出如下结果(示例):
musa_toolkits:
{
"version": "5.1.0",
"git branch": "release_musa_5.1.0",
"git tag": "No tag",
"commit id": "e1481406739bd545c45c4b852450a81ac5feee6c",
"commit date": "2026-03-06 20:38:51 +0800"
}
CUB:
{
"version": "1.17.2",
"git branch": "develop-1.17",
"git tag": "No tag",
"commit id": "90657f2acd3286bc29ab50396996a00fa3c31c7d",
"commit date": "2026-03-27 16:57:00 +0800"
}
mcc:
{
"version": "5.1.0",
"git branch": "release_musa_5.1.0",
"git tag": "No tag",
"commit id": "390af73c488fe895e8b042ee5354a69b542ac6c1",
"commit date": "2026-03-27 18:10:29 +0800"
}
...
musa_runtime:
{
"version": "5.1.0",
"git branch": "release_musa_5.1.0",
"git tag": "No tag",
"commit id": "e9d9b3d98a944f5b03f582e4505dfb452f5d5faf",
"commit date": "2026-03-25 10:02:03 +0800"
}
检查子模块是否正确包含以及数学库的架构是否正确。
验证 musaInfo:
$ musaInfo
compiler: mcc
--------------------------------------------------------------------------------
device# 0
Name: MTT S5000
Driver Version: 5.1
Runtime Version: 5.1
compute capability: 3.1
pciBusID: 0x2a
pciDeviceID: 0x0
pciDomainID: 0x0
multiProcessorCount: 56
maxThreadsPerMultiProcessor: 3072
isMultiGpuBoard: 1
clockRate: 1500 Mhz
memoryClockRate: 20000 Mhz
memoryBusWidth: 640
totalGlobalMem: 79.91 GB
sharedMemPerMultiprocessor: 192.00 KB
totalConstMem: 8192
sharedMemPerBlock: 192.00 KB
canMapHostMemory: 1
regsPerBlock: 131072
warpSize: 32
l2CacheSize: 62914560
computeMode: 0
maxThreadsPerBlock: 1024
maxThreadsDim.x: 1024
maxThreadsDim.y: 1024
maxThreadsDim.z: 1024
maxGridSize.x: 2147483647
maxGridSize.y: 2147483647
maxGridSize.z: 2147483647
concurrentKernels: 1
cooperativeLaunch: 1
cooperativeMultiDeviceLaunch: 0
isIntegrated: 0
maxTexture1D: 32768
maxTexture2D.width: 32768
maxTexture2D.height: 32768
maxTexture3D.width: 16384
maxTexture3D.height: 16384
maxTexture3D.depth: 2048
peers: device#1 device#2 device#3 device#4 device#5 device#6 device#7
non-peers: device#0
memInfo.total: 79.91 GB
memInfo.free: 79.32 GB (99%)
步骤 4:安装 muDNN
1. 确认前提条件
已安装兼容版本 MT GPU 驱动及 MUSA Toolkit。
2. 安装 muDNN
- 在线安装(APT)
- 离线安装
完成 APT 配源后,直接安装软件包 libmudnn3-musa-5 即可。
sudo apt install libmudnn3-musa-5
-
执行安装
# 以 mudnn.3.3.0.PH1.tar.gz 为例tar -zxvf mudnn.3.3.0.PH1.tar.gzcd mudnn && ./install_mudnn.sh -i -
配置环境变量
DNN_PATH=$(realpath mudnn)export LD_LIBRARY_PATH=${DNN_PATH}/lib:$LD_LIBRARY_PATH
安装完成后,您可以查看 muDNN 的所有 API。
更多接口说明和使用示例,可参考 muDNN 文档。
步骤 5:安装 MCCL
1. 确认前置条件
- 多张 MT GPU 卡(单节点/多节点)
- 一块或多块 InfiniBand 网卡
- 已安装 MUSA 驱动
- 已安装 MUSA Toolkit
- 已安装 mtml(容器内部直接安装 mtml 或者通过 host 端映射,若是通过 container-toolkit 方式起的容器,会直接映射进去)
2. 配置网络
如果没有 IB 网卡,只有以太网,则无需配置 IB。PH1 架构走的 RoCE 网络,需要使用环境变量指定 RoCE v2 协议(MCCL_IB_GID_INDEX=3)
2.1 安装 IB 驱动
如果有 IB 网卡,但是 IB 驱动未安装,请先安装 IB 驱动。
2.2 验证 IB 驱动
$ ibstat
CA 'mlx5_0'
CA type: MT4123
Number of ports: 1
Firmware version: 20.31.1014
Hardware version: 0
Node GUID: 0xb83fd203005682a2
System image GUID: 0xb83fd203005682a2
Port 1:
State: Active
Physical state: LinkUp
Rate: 200
Base lid: 12
LMC: 0
SM lid: 5
Capability mask: 0x2651e848
Port GUID: 0xb83fd203005682a2
Link layer: InfiniBand
如果其中一个 network port 的 physical state 是 LinkUp,而且 Link layer 标明为 InfiniBand,就说明已经使能了 IB 网络。
3. 安装 MPI 工具
MPI 工具为 MCCL 提供跨节点的进程管理和通信基础,协调不同机器间的初始连接。多机场景下需要安装 MPI 工具。
选项 1:mpich 工具安装(mpich-4.2.0rc3 版本)
wget https://www.mpich.org/static/downloads/4.2.0rc3/mpich-4.2.0rc3.tar.gz
tar -xzf mpich-4.2.0rc3.tar.gz
cd mpich-4.2.0rc3
# 若已经执行过 ./configure,需要执行 make clean 清除
make clean
./configure --with-device=ch3:sock
make -j64
sudo make install
# 验证,mpich 工具默认装在/usr/local/bin 路径
export PATH=/usr/local/bin:$PATH
mpirun --version
选项 2:openMPI 工具安装
# 查看可用 openmpi 版本
apt list -a openmpi-bin
# 安装 openMPI(Ubuntu 22.04 + Linux 5.15.0-105-generic 环境建议安装 5.0.6 版本,方便问题排查)
wget https://oss.mthreads.com/tmp/torch_musa_build/openmpi-5.0.6.tar.bz2
tar -jxf openmpi-5.0.6.tar.bz2
cd openmpi-5.0.6
./configure --prefix=/usr/local/openmpi --without-hcoll --without-ucx
make -j4 all
make install
# 验证,openmpi 工具手动安装统一装在/usr/local/openmpi 路径
export PATH=/usr/local/openmpi/bin/:$PATH
mpirun --version
4. 安装 MCCL
- 在线安装(APT)
- 离线安装
完成 APT 配源后,根据显卡 型号选择对应软件包:
# S5000 系列显卡
sudo apt install mccl-s5000
# S4000 系列显卡
sudo apt install mccl-s4000
安装 MCCL 包,以 mccl.2.3.0.PH1.tar.gz 为例:
sudo tar -zxvf mccl.2.3.0.PH1.tar.gz
cd ./mccl
sudo bash ./install.sh
步骤 6:验证安装
建议先完成基础开发环境验证,再根据实际安装的可选组件继续验证。
如果您只安装了 Linux Driver 和 MUSA Toolkit,确认 mthreads-gmi、musa_version_query 和 musaInfo 输出正常即可;以下多机配置和通信验证仅在安装 MCCL 时需要。
-
确认版本
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH/usr/local/musa/bin/mccl_version -
多机 config 文件配置(2 节点为例)
-
mpich 配置文件:
hostfile_with_mpich<node1_ip>:<process_num><node2_ip>:<process_num> -
openmpi 配置文件:
hostfile_with_openmpi<node1_ip> slots=process_num<node2_ip> slots=process_num
-
-