安装 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%)