MUSA SDK安装指南

SDK 5.2：先核对整套组件，不单独追新

截至本次核查，官方入口指向 MUSA SDK 5.2.0。发布说明未标注发布日期，因此这里称“当前文档基线”，不称“9月新发布”。其组件表列出 Linux Driver 5.2.0、MUSA Toolkit 5.2.0、muDNN 3.4.0、MCCL 2.4.0、Triton-MUSA 3.6.0、TileLang-MUSA 0.1.8、MATE 0.2.3。SDK 5.2 发布说明

本次发布说明中的已验证/推荐 CPU、OS 与内核表针对 S5000，不是所有摩尔线程 GPU 的通用升级矩阵。S80、M1000 或其他型号需另查对应硬件的支持说明；升级前先核对 GPU 型号及其官方支持矩阵。SDK 推荐平台范围

表中变化来自 官方版本说明；验证方式为教学建议，未提供实测性能承诺。

成熟度提示：发布说明仍将 Graph Management API support 列为实验特性。须按具体 API 和工作负载核验，不能把新增/验证数量理解为全部图能力已成为正式生产特性。SDK 实验特性

监控也有依赖：不要只升级驱动

发布说明限定：当 mtbios 为 4.3.43 时，EDC counter 变更须配合 Linux Driver 5.2.0、dcgm 1.1.6 和 mtml 2.4.2。升级前先清点这些版本；升级后检查指标存在性、单位、错误计数与告警，不要把“采集成功”当作“语义一致”。EDC 兼容约束

1. 备份现有版本清单、内核、BIOS、驱动包及可回滚的工作负载镜像。
2. 核对官方 OS / 内核支持表，先在独立测试节点升级，不直接批量变更生产集群。
3. 分别验证设备识别、单卡计算、多卡通信及监控采集；保存日志。
4. 应用容器依照自己的依赖矩阵锁版本，不将 SDK 总表的 Triton/MATE 版本强制覆盖到 vLLM 或 SGLang 镜像。

最后一条尤其重要：vLLM 0.24 正式发布栈列出的 Triton 3.2.0、MATE 0.2.4 与 SDK 组件表不同，这是不同交付物的锁定组合，不能按版本号大小自行拼装。vLLM 正式依赖表

历史教程与基础知识

一、概述

MUSA SDK（Software Development Kit）是摩尔线程提供的GPU开发工具集，包含驱动、运行时库、编译器、数学库以及各种开发工具。本课将指导你从零开始在Ubuntu系统上安装MUSA SDK，确保你的摩尔线程GPU可以正常用于AI开发和通用计算。

MUSA SDK的安装方式主要有两种：

• musa-deploy一键部署（推荐新手使用）：通过自动化脚本完成所有组件的安装
• 手动逐步安装：适合需要定制安装的高级用户

二、系统要求检查清单

在安装MUSA SDK之前，请逐项检查以下系统要求：

2.1 硬件要求

1. 摩尔线程GPU：MTT S80 / S3000 / S4000 / S5000 系列之一
   确认GPU已安装：打开终端，运行以下命令检查PCIe设备
   bash 复制代码

   # 检查系统是否识别到摩尔线程GPU
   lspci | grep -i "Moore"
   # 或者搜索MT关键词
   lspci | grep -i "MT"
   
   # 预期输出类似：
   # 03:00.0 Display controller: Moore Threads Technology Ltd. MTT S80 (rev 01)

2. CPU：x86_64架构，Intel或AMD处理器
3. 内存：建议至少16GB系统内存
4. 磁盘空间：至少20GB可用空间用于SDK安装

2.2 软件要求

1. 操作系统：Ubuntu 20.04 LTS 或 Ubuntu 22.04 LTS（推荐）
   bash 复制代码

   # 检查操作系统版本
   cat /etc/os-release
   # 确认NAME="Ubuntu"，VERSION_ID为"20.04"或"22.04"
   
   uname -r
   # 确认为x86_64架构内核

2. 内核版本：Linux Kernel 5.4+ （Ubuntu 20.04默认为5.4，Ubuntu 22.04默认为5.15）
3. GCC编译器：GCC 7.0+ （用于编译MUSA程序）
   bash 复制代码

   # 检查GCC版本
   gcc --version
   # 如果未安装：
   sudo apt update && sudo apt install build-essential -y

4. Python：Python 3.8+（用于torch_musa等Python工具）
   bash 复制代码

   # 检查Python版本
   python3 --version

三、使用musa-deploy一键部署（推荐）

musa-deploy是摩尔线程提供的自动化部署工具，它会自动检测你的系统环境，下载并安装所有必要的MUSA SDK组件。

3.1 安装步骤

1. 下载musa-deploy工具
   前往摩尔线程开发者网站下载最新版本的musa-deploy：
   bash 复制代码

   # 访问开发者网站获取最新版本链接
   # https://developer.mthreads.com
   
   # 下载musa-deploy安装包（示例版本号，请替换为最新版本）
   wget https://oss.mthreads.com/release-rc/cuda_compatible/musa-deploy_latest.tar.gz
   
   # 解压
   tar -xzf musa-deploy_latest.tar.gz
   cd musa-deploy

2. 运行自动部署脚本
   bash 复制代码

   # 查看帮助信息
   ./musa-deploy --help
   
   # 一键安装所有组件（需要sudo权限）
   sudo ./musa-deploy --install all
   
   # 安装过程将自动完成以下工作：
   # 1. 检测系统环境和GPU型号
   # 2. 安装MTGPU内核驱动
   # 3. 安装MUSA Runtime运行时库
   # 4. 安装mcc编译器（MUSA C/C++ Compiler）
   # 5. 安装muDNN深度学习库
   # 6. 安装MCCL集合通信库
   # 7. 配置环境变量

3. 等待安装完成
   安装过程通常需要5-15分钟，取决于网络速度。安装脚本会显示详细的进度信息。
4. 重启系统
   安装完成后，需要重启系统以加载GPU内核驱动：
   bash 复制代码

   sudo reboot

3.2 常用部署选项

# 仅安装驱动
sudo ./musa-deploy --install driver

# 安装驱动 + 运行时（不含开发工具）
sudo ./musa-deploy --install runtime

# 完整安装（驱动 + 运行时 + 开发工具 + 库）
sudo ./musa-deploy --install all

# 指定安装路径
sudo ./musa-deploy --install all --prefix /opt/musa

# 查看已安装的组件
./musa-deploy --list

# 卸载所有组件
sudo ./musa-deploy --uninstall all

四、手动安装步骤

如果你需要更精细的控制，可以手动逐一安装各个组件。

4.1 安装GPU驱动

# 下载MTGPU驱动包
wget https://oss.mthreads.com/release-rc/cuda_compatible/mtgpu-drv_latest.deb

# 安装驱动
sudo dpkg -i mtgpu-drv_latest.deb

# 如果有依赖问题，运行：
sudo apt --fix-broken install -y

# 加载驱动模块
sudo modprobe mtgpu

# 验证驱动加载
lsmod | grep mtgpu
# 应看到mtgpu模块已加载

4.2 安装MUSA SDK核心组件

# 安装MUSA Runtime
sudo dpkg -i musa-runtime_latest.deb

# 安装MUSA编译器(mcc)
sudo dpkg -i musa-compiler_latest.deb

# 安装muDNN深度学习库
sudo dpkg -i mudnn_latest.deb

# 安装MCCL通信库
sudo dpkg -i mccl_latest.deb

4.3 配置环境变量

# 编辑 ~/.bashrc 添加环境变量
echo '# MUSA SDK Environment' >> ~/.bashrc
echo 'export MUSA_HOME=/usr/local/musa' >> ~/.bashrc
echo 'export PATH=$MUSA_HOME/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$MUSA_HOME/lib:$LD_LIBRARY_PATH' >> ~/.bashrc

# 使环境变量生效
source ~/.bashrc

# 验证mcc编译器
mcc --version

五、Docker容器环境搭建

使用Docker容器是开发环境搭建的另一种推荐方式，可以避免系统环境冲突，实现环境的快速部署和一致性。

5.1 安装Docker和MT Container Toolkit

1. 安装Docker（如果尚未安装）：
   bash 复制代码

   # 安装Docker
   sudo apt update
   sudo apt install docker.io -y
   
   # 将当前用户加入docker组（避免每次都要sudo）
   sudo usermod -aG docker $USER
   
   # 启动Docker服务
   sudo systemctl start docker
   sudo systemctl enable docker

2. 安装MT Container Toolkit：
   bash 复制代码

   # 下载MT Container Toolkit
   wget https://oss.mthreads.com/release-rc/cuda_compatible/mt-container-toolkit_latest.deb
   
   # 安装
   sudo dpkg -i mt-container-toolkit_latest.deb
   
   # 重启Docker守护进程
   sudo systemctl restart docker

3. 运行MUSA开发容器：
   bash 复制代码

   # 拉取摩尔线程官方开发镜像
   docker pull registry.mthreads.com/musa-dev/musa-pytorch:latest
   
   # 启动容器，挂载GPU
   docker run -it --rm \
     --runtime=mt \
     --name musa-dev \
     -v $(pwd)/workspace:/workspace \
     registry.mthreads.com/musa-dev/musa-pytorch:latest \
     /bin/bash
   
   # 在容器内验证GPU
   musa-smi

六、安装验证

安装完成后，请按以下步骤验证所有组件是否正常工作：

6.1 检查GPU驱动和设备

# 使用musa-smi查看GPU状态
musa-smi

# 预期输出类似：
# +-----------------------+-------------------------------+
# | MUSA Version: 1.x.x  | Driver Version: x.x.x        |
# +-----------------------+-------------------------------+
# | GPU  Name             | Memory-Usage   | GPU-Util    |
# | 0    MTT S80          | 256MiB/16384MiB|   0%        |
# +-----------------------+-------------------------------+

6.2 验证编译器

# 检查mcc编译器版本
mcc --version

# 检查MUSA运行时版本
musaInfo
# 或
cat /usr/local/musa/version.txt

6.3 验证Python环境

# 测试torch_musa是否正常（如果已安装）
import torch
import torch_musa

# 检查MUSA是否可用
print("MUSA available:", torch.musa.is_available())
print("Device count:", torch.musa.device_count())
print("Device name:", torch.musa.get_device_name(0))

# 简单计算测试
a = torch.randn(3, 3, device='musa')
b = torch.randn(3, 3, device='musa')
c = a @ b  # 矩阵乘法
print("Result on MUSA:", c)

6.4 编译并运行Hello World

// hello_musa.mu — 保存为.mu文件
#include <musa_runtime.h>
#include <stdio.h>

__global__ void helloKernel() {
    printf("Hello from MUSA thread %d in block %d!\n",
           threadIdx.x, blockIdx.x);
}

int main() {
    // 启动1个Block，4个Thread
    helloKernel<<<1, 4>>>();
    musaDeviceSynchronize();
    printf("Hello MUSA World!\n");
    return 0;
}

# 编译
mcc hello_musa.mu -o hello_musa

# 运行
./hello_musa

# 预期输出：
# Hello from MUSA thread 0 in block 0!
# Hello from MUSA thread 1 in block 0!
# Hello from MUSA thread 2 in block 0!
# Hello from MUSA thread 3 in block 0!
# Hello MUSA World!