Skip to main content

安装 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,请先按原安装方式卸载干净,再执行在线安装流程。更多详情,参见历史版本中的对应安装指导。

请按以下步骤,使用 DEB 配置包自动配置 APT 软件源:

  1. 下载配置包:

    wget https://dl.mthreads.com/repo/repository/ubuntu2204/pool/jammy/amd64/musa-repo-jammy_1.0.0.11-1_all.deb
  2. 安装配置包:

    sudo dpkg -i musa-repo-jammy_1.0.0.11-1_all.deb
  3. 更新本地缓存:

    sudo apt update

更新缓存后,可通过 APT 直接安装以下软件包:

组件软件包
Linux Drivermthreads-driver
MUSA Toolkitmusa-toolkit
muDNNlibmudnn3-musa-5
MCCL(S5000 系列)mccl-s5000
MCCL(S4000 系列)mccl-s4000

步骤 2:安装驱动

1. 确认资源需求

  • MT GPU 卡
  • 操作系统:Ubuntu 22.04
  • 内核版本:5.15.0-105-generic
注意

集群内部机器无法直接在宿主机上安装 deb 包,请卸载 operator 相关组件后安装。

2. 配置 BIOS

  1. S4000 显卡:如果使用的是内存 >=256G 的服务器,且显卡是 S4000,则必须 开启 IOMMU(VT-d) 选项

  2. 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 能看到图形界面。另外,请务必选择软重启,硬重启不能保证所有写入行为同步到文件。

  1. PC 配置:如果是 PC,需要将 BIOS 中的 resize bar 选项设置为 ON
    • 将显示器连接到主板上,并断开电源重新启动计算机。在启动过程中,按下 Delete 键 以进入 BIOS 设置界面
    • 在 BIOS 设置界面中,找到并开启 Above 4G 选项
    • 查找并将 Resize Bar 开关置为 ON。请注意,大部分主板在首次开机时此选项默认为 OFF,并且通常显示在 BIOS 菜单的右上角
    • 重启计算机,系统正常加载后,执行 lspci -nn | grep 1ed5 确认显卡已识别

3. 安装 MT 驱动

用于安装摩尔线程显卡的底层驱动程序。

  1. 选择安装方式

    完成 APT 配源后,可直接在线安装 Linux Driver。

    1. 安装驱动

      sudo apt install mthreads-driver
    2. 重启系统 强烈建议重启电脑来使驱动生效

      sudo reboot
    3. 如需在不重启的情况下重新加载驱动

      modprobe -rv mtgpu && modprobe -v mtgpu
  2. 设置用户组

    非 Root 用户如需获取设备使用权限,可参考以下方式设置:

    # 把普通用户账号,加进 render & video group
    sudo usermod -aG render,video ${USER}
    # 重新登入账户

4. 验证安装并查询版本

  1. 使用 mthreads-gmi 验证

    # 通过 mthreads-gmi 校验 Linux Driver 安装
    # 命令行执行 mthreads-gmi,能够展示 gmi 版本号、Driver 版本号、显卡相关主要信息等
    mthreads-gmi
  2. 查看版本信息

    # 可通过包管理器或者 mthreads-gmi 工具查看驱动的版本信息
    dpkg -s mthreads-driver
    # 或者
    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 驱动。

  1. 检查 MT GPU 驱动版本:

    mthreads-gmi
  2. 若未安装或未安装适配版本 MT GPU 驱动,请先完成上一节的驱动安装与验证。

2. 安装 MUSA Toolkit

MUSA Toolkit 包含了针对摩尔线程 GPU 进行通用计算开发的必要编译器和工具链,支持安装到主机(host)或 docker 环境中。

注意

运行环境在 docker 上,建议通过 container-toolkit 创建容器,否则需要手动映射 host 上的 /usr/lib/x86_64-linux-gnu/libmusa.so* 到容器中。

完成 APT 配源后,可直接在线安装 MUSA Toolkit。

sudo apt install musa-toolkit

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 配源后,直接安装软件包 libmudnn3-musa-5 即可。

sudo apt install libmudnn3-musa-5

安装完成后,您可以查看 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 配源后,根据显卡型号选择对应软件包:

# S5000 系列显卡
sudo apt install mccl-s5000

# S4000 系列显卡
sudo apt install mccl-s4000

步骤 6:验证安装

建议先完成基础开发环境验证,再根据实际安装的可选组件继续验证。

如果您只安装了 Linux Driver 和 MUSA Toolkit,确认 mthreads-gmimusa_version_querymusaInfo 输出正常即可;以下多机配置和通信验证仅在安装 MCCL 时需要。

  1. 确认版本

    export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH
    /usr/local/musa/bin/mccl_version
  2. 多机 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
  3. 功能验证

    # 单机验证
    ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

    # 多机验证(openmpi)
    mpirun --allow-run-as-root --mca btl_tcp_if_include bond0 -hostfile ./hostfile_with_openmpi \
    -x LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/lib \
    -x MCCL_PROTOS=2 -x MCCL_NET_SHARED_BUFFERS=0 \
    -x MCCL_ALGOS=1 -x MCCL_IB_GID_INDEX=3 \
    ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

    # 多机验证(mpich)
    mpirun -hostfile ./hostfile_with_mpich \
    -env LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/lib \
    -env MCCL_PROTOS=2 -env MCCL_NET_SHARED_BUFFERS=0 \
    -env MCCL_ALGOS=1 -env MCCL_IB_GID_INDEX=3 \
    ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

卸载 MUSA

如需卸载 MUSA SDK 及相关组件,请根据实际安装方式执行对应操作。

# 按需移除已安装的可选组件
# 根据显卡型号选择其一
# S5000 系列显卡
sudo apt remove mccl-s5000

# S4000 系列显卡
sudo apt remove mccl-s4000

# muDNN
sudo apt remove libmudnn3-musa-5

# 基础组件
sudo apt remove musa-toolkit
sudo apt remove mthreads-driver

# 清理 APT 自动安装的依赖
sudo apt autoremove

# 如需立即完成驱动卸载,建议重启系统
sudo reboot
注意
  • 如果报错 mtgpu is inuse,请重启系统后再次执行
  • 对于在线安装(APT),apt remove 不会自动清理所有依赖,建议继续执行 sudo apt autoremove
  • 如需清理 MUSA Toolkit,删除 /usr/local/musa 目录即可:sudo rm -rf /usr/local/musa
  • 请手动编辑 ~/.bashrc 文件,移除 MUSA 相关的环境变量设置

常见问题

Q1: 配置 APT 软件源后,执行 sudo apt update 失败怎么办?
  • 确认当前环境为全新 Ubuntu 22.04 x86_64 Server。
  • 确认系统可以正常访问软件源地址 https://dl.mthreads.com/
  • 确认 DEB 配置包已安装成功后,再重新执行 sudo apt update
dpkg -l | grep musa-repo-jammy
sudo apt update
Q2: 已完成配源,但 apt install 提示找不到软件包怎么办?
  • 先执行 sudo apt update 更新本地缓存。
  • 确认当前环境在 APT 方式支持范围内。
  • 可使用以下命令检查软件包是否已出现在 APT 缓存中:
apt search mthreads-driver
apt search musa-toolkit
apt search libmudnn3-musa-5
Q3: 系统中已安装旧版 Linux Driver 或 MUSA Toolkit,在线安装报冲突怎么办?

如果系统中已经通过旧版 DEB、tar 包或其他方式安装过 Linux Driver 或 MUSA Toolkit,请先按原安装方式卸载干净,再重新执行在线安装流程。更多详情,参见历史版本中的对应安装指导。

Q4: 为什么执行 apt remove 后仍有依赖包残留?

apt remove 默认只移除指定软件包,不会自动清理所有依赖。对于在线安装(APT),建议继续执行以下命令清理自动安装的依赖:

sudo apt autoremove
Q5: 驱动安装后无法识别设备
# 检查 PCI 识别
lspci -nn | grep 1ed5

# 检查驱动加载
lsmod | grep mtgpu

# 重新加载驱动
sudo modprobe -rv mtgpu && sudo modprobe -v mtgpu
Q6: IOMMU 配置问题
  • S4000 显卡:必须开启 IOMMU。Intel CPU 使用 intel_iommu=on iommu.passthrough=0,AMD/HG CPU 使用 amd_iommu=on
  • S5000 显卡:必须关闭 IOMMU。Intel CPU 可参考前文的关闭 IOMMU 步骤
Q7: 权限不足
# 将用户添加到 render 和 video 组
sudo usermod -aG render,video ${USER}
# 重新登录
Q8: Docker 环境中使用 MUSA
  • 使用 container-toolkit 创建容器(推荐)
  • 或手动映射 /usr/lib/x86_64-linux-gnu/libmusa.so* 到容器中