MUSA SDK 安装使用说明

版本 v4.x.x

1. 软件包准备

请从官方渠道获取 MUSA SDK 安装包。软件包中应包含以下文件（具体版本号以实际发布为准）：

基于 Debian/Ubuntu（.deb）的软件包：

├── mccl_rc2.1.x.tar.gz
├── mudnn_rc3.1.x.tar.gz
├── musa_3.3.x-server_amd64.deb
├── musa_toolkits_rc4.3.x.tar.gz

基于 RHEL/Alinux（.rpm）的软件包：

├── mccl_rc2.1.x.tar.gz
├── mudnn_rc3.1.x.tar.gz
├── musa_3.3.x-server_amd64.rpm
├── musa_toolkits_rc4.3.x.tar.gz

若在 Docker 中运行，可能还需：mtml、mt-container-toolkit 等组件（参见驱动安装中的可选步骤）。

2. 驱动安装

2.1 资源需求

GPU：MTT S80/MTT S3000/MTT S4000/MTT S5000 （以发布版本信息为准）。
操作系统与内核（示例，请以当前发布说明为准）：
- Ubuntu 22.04，内核 5.15.x
- Debian 12，内核 5.15.x
- Alibaba Cloud Linux 3，内核 5.10.x

请确保当前内核与所安装驱动版本兼容。

2.2 BIOS 配置

将显示器连接至主板，断电后重新上电。启动时按 Delete 进入 BIOS。
在 BIOS 中开启 Above 4G 选项。
将 Resize BAR 设置为 ON（多数主板默认 OFF，常见于 BIOS 右上角）。
IOMMU（VT-d）：
- 若使用 MTT S5000，请关闭 IOMMU。
- 若使用 MTT S4000 且内存 ≥256GB，请开启 IOMMU（Intel 平台为 intel_iommu=on，AMD 为 amd_iommu=on）。

配置完成后保存并重启。进入系统后执行 lspci -nn | grep 1ed5 确认显卡已被识别。

2.3 安装依赖（DKMS 等）

驱动通过 DKMS 编译内核模块，需先安装相应依赖。

2.3.1 Ubuntu

sudo apt update
sudo apt install -y dkms
sudo apt install -y clang libclang-dev libelf-dev gcc-multilib build-essential \
  libx11-dev libxi-dev libgl1-mesa-glx libglu1-mesa libglu1-mesa-dev libglew-dev \
  libglfw3 libglfw3-dev libnuma-dev ninja-build cmake libstdc++-12-dev
sudo apt install -y python3-pip
sudo apt -y install python-is-python3

2.3.2 Debian 12

sudo apt update
sudo apt install -y dkms

若安装 dkms 时自动安装了与当前驱动不兼容的内核（例如 6.1），需卸载该内核并确认当前运行内核与驱动兼容，再安装驱动。查看已安装内核示例：

dpkg --list | grep -E 'linux-image-[0-9]|linux-headers-[0-9]'

2.3.3 Alibaba Cloud Linux / RHEL 系

sudo dnf -y install dkms

2.4 环境检查与驱动卸载

检查 PCI 是否识别到显卡：

lspci -nn | grep 1ed5

若已安装旧版驱动，先卸载：

# Debian/Ubuntu：卸载旧 musa 包
sudo dpkg -P musa

# RHEL/Alinux：卸载旧 musa 包
sudo rpm -e musa

若提示 mtgpu is in use，可先重启再卸载，或尝试卸载模块后再次卸载包：

sudo rmmod mtgpu
# 再次执行上述 dpkg -P musa 或 rpm -e musa

确认无残留：

lsmod | grep mtgpu

2.5 安装驱动

2.5.1 Debian/Ubuntu（.deb）

# 安装驱动包（以 musa_3.3.x-server_amd64.deb 为例，请替换为实际文件名）
sudo dpkg -i musa_3.3.x-server_amd64.deb

# 强烈建议重启以加载新驱动
sudo reboot

若暂时不能重启，可尝试重新加载模块（不保证所有场景有效）：

sudo modprobe -rv mtgpu && sudo modprobe mtgpu

2.5.2 Alibaba Cloud Linux / RHEL（.rpm）

# 安装驱动包（以 musa_3.3.x-server_amd64.rpm 为例，请替换为实际文件名）
sudo rpm -ivh musa_3.3.x-server_amd64.rpm

# 强烈建议重启以加载新驱动
sudo reboot

若暂时不能重启，可尝试：

sudo modprobe -rv mtgpu && sudo modprobe mtgpu

2.6 可选：Docker 场景（mtml 与 container-toolkit）

若运行环境为 Docker，需在宿主机上安装 mtml 与 mt-container-toolkit（仅针对提供 .deb 的发行版，包名与版本以实际发布为准）：

sudo dpkg -i mtml_2.2.x-linux-R_amd64.deb
sudo dpkg -i mt-container-toolkit_2.1.x-1_amd64.deb

2.7 可选：非 root 用户设备权限

非 root 用户如需访问 GPU 设备，可将用户加入 render 和 video 组：

sudo usermod -aG render ${USER}
sudo usermod -aG video ${USER}

修改后需重新登录生效。

2.8 验证驱动安装

使用 mthreads-gmi 校验：

mthreads-gmi

查看内核态驱动版本：

dmesg | grep "Driver Version"
# 或
cat /var/log/dmesg | grep "Driver Version"

Debian/Ubuntu 也可通过包信息查看：

dpkg -s musa

3. MUSA Toolkit 安装

3.1 前提条件

已安装兼容版本的 MT GPU 驱动（参见上一节）。
安装前请执行 mthreads-gmi 确认驱动可用。

3.2 安装步骤

MUSA Toolkit 可安装在宿主机或 Docker 容器内。若在 Docker 中运行，建议在容器内安装 Toolkit，或通过 container-toolkit 正确映射设备与库。

以 musa_toolkits_rc4.3.x.tar.gz 为例（请替换为实际包名）：

tar -zxvf musa_toolkits_rc4.3.x.tar.gz
cd musa_toolkits_install
bash ./install.sh -u    # 先卸载环境中已安装的 MUSA（若有）
bash ./install.sh      # 非 root 用户请使用 sudo

安装成功后终端会提示将 bin 和 lib 加入环境变量。

3.3 设置环境变量

编辑 shell 配置文件（如 ~/.bashrc）：

vim ~/.bashrc

在末尾添加（若已通过安装脚本提示配置，可跳过）：

export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH

使配置生效：

source ~/.bashrc

3.4 验证

查看 Toolkit 及各组件版本：

musa_version_query

验证运行时能否正常识别设备：

musaInfo

输出中应能看到 GPU 型号、驱动版本、显存等信息。请确认子模块版本与数学库架构符合预期。

4. muDNN 安装

4.1 前提条件

已安装兼容版本的 MT GPU 驱动及 MUSA Toolkit。

4.2 安装步骤

以 mudnn_rc3.1.x.tar.gz 为例（请替换为实际包名）：

tar -zxvf mudnn_rc3.1.x.tar.gz
cd mudnn
./install_mudnn.sh -i    # 非 root 用户请使用 sudo

卸载（如需要）：

./install_mudnn.sh -u

4.3 环境变量

若已按上文配置 MUSA Toolkit 环境变量，一般无需额外设置。否则请确保：

export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH

安装完成后即可使用 muDNN API，详见 muDNN API 文档。

5. MCCL 安装

5.1 前提条件

已安装兼容版本的 MT GPU 驱动、MUSA Toolkit 及 muDNN。
多机场景需多张 MT GPU、InfiniBand 或 RoCE 网络，以及 MPI（如 MPICH 或 Open MPI）。

5.2 单机安装

以 mccl_rc2.1.x.tar.gz 为例（请替换为实际包名）：

tar -zxvf mccl_rc2.1.x.tar.gz
cd mccl
./install.sh -i    # 非 root 用户请使用 sudo

卸载（如需要）：

./install.sh -u

5.3 环境变量

确保已设置：

export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH

5.4 多机场景（可选）

网络：若使用 RoCE（如 PH1 架构），需通过环境变量指定 RoCE v2，例如 MCCL_IB_GID_INDEX=3。若仅有以太网无 IB，则无需配置 IB。
MPI：多机需安装 MPICH 或 Open MPI。可从 MPICH 官网或 Open MPI 官网获取安装包，按官方文档安装并验证 mpirun --version。
验证：在 MCCL 安装目录下的测试目录中，可运行单机/多机测试（具体命令与 hostfile 格式见 MCCL 文档）。多机时需在 hostfile 中配置各节点 IP 与进程数，并传递 LD_LIBRARY_PATH、MCCL_IB_GID_INDEX 等环境变量。

安装完成后即可使用 MCCL API，详见 MCCL API 文档。

附录：常用说明

多卡可见设备：通过环境变量限制可见 GPU，例如 export MUSA_VISIBLE_DEVICES=0,1,2,3 表示仅使用前 4 张卡。
版本与兼容性：各组件版本号请以实际发布包为准，安装前请阅读该版本发布说明，确认与当前 OS、内核及驱动兼容。

目录​

1. 软件包准备​

2. 驱动安装​

2.1 资源需求​

2.2 BIOS 配置​

2.3 安装依赖（DKMS 等）​

2.3.1 Ubuntu​

2.3.2 Debian 12​

2.3.3 Alibaba Cloud Linux / RHEL 系​

2.4 环境检查与驱动卸载​

2.5 安装驱动​

2.5.1 Debian/Ubuntu（.deb）​

2.5.2 Alibaba Cloud Linux / RHEL（.rpm）​

2.6 可选：Docker 场景（mtml 与 container-toolkit）​

2.7 可选：非 root 用户设备权限​

2.8 验证驱动安装​

3. MUSA Toolkit 安装​

3.1 前提条件​

3.2 安装步骤​

3.3 设置环境变量​

3.4 验证​

4. muDNN 安装​

4.1 前提条件​

4.2 安装步骤​

4.3 环境变量​

5. MCCL 安装​

5.1 前提条件​

5.2 单机安装​

5.3 环境变量​

5.4 多机场景（可选）​

附录：常用说明​

这篇文章对您有帮助吗？

目录