本课说明（2026-11-14 新编）
适用范围：MUSA SDK 5.2.0（Driver 5.2.0、Toolkit 5.2.0、muDNN 3.4.0、MCCL 2.4.0）。请先完成第 2 课的环境准备。 本课依据官方文档与正式 Release 整理，未在真实 MUSA GPU 上实测；标注“官方”的命令与数值来自原文，标注“本站补充”的脚本由本站编写用于检查与教学，使用前请在自己的环境中验证。
一、先理解分层
| 层 | 组件（5.2.0 版本） | 作用 |
|---|---|---|
| 内核驱动 + 用户态驱动 | mthreads-driver（Driver 5.2.0）：内核模块 mtgpu、用户态库 libmusa | 让操作系统识别并调度 GPU |
| Toolkit | musa-toolkit 5.2.0：编译器 mcc、运行时 musart、工具 | 编译与运行 MUSA 程序 |
| 数学 / 通信库 | muDNN 3.4.0、MCCL 2.4.0 | 深度学习算子、多卡通信 |
| Python 生态 | torch / torch_musa、Triton-MUSA 3.6.0、TileLang-MUSA 0.1.8、MATE 0.2.3 | 框架与高层算子 |
版本号来自 MUSA SDK v5.2.0 发布版本信息。MUSA SDK 5.2.0 安装指南 明确写道“Linux Driver 版本与 MUSA Toolkit 版本独立”，因此升级时要分别记录两者版本。
二、配置 APT 源（仅 Ubuntu 22.04 x86_64 Server）
bash
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三、安装驱动
bash
# 在线方式
sudo apt install -y mthreads-driver
# 离线方式（其他系统或无外网）
sudo apt install ./musa_5.2.0-server_amd64.deb # 官方写法，apt 会自动处理依赖
# 安装后建议重启；不能重启时可重新加载模块
sudo modprobe -rv mtgpu && sudo modprobe -v mtgpu
# 让普通用户可以访问 GPU
sudo usermod -aG render,video $USER # 重新登录后生效提示 “mtgpu is in use”
说明仍有进程或依赖模块占用 GPU。先停止使用 GPU 的进程和容器，用
lsmod | grep mtgpu 查看依赖关系，再卸载模块；无法确认时直接重启更稳妥。四、验证驱动
bash
mthreads-gmi # 列出所有 GPU 及状态
dpkg -s mthreads-driver # APT 安装时查看版本
dpkg -s musa # 离线 deb 安装时查看版本五、安装 Toolkit
bash
# 在线方式
sudo apt install -y musa-toolkit
# 离线方式：解压 musa_toolkits_5.2.0.tar.gz 后在目录内执行
sudo ./install.sh -u # 先卸载旧版本（若有）
sudo ./install.sh
# 环境变量（写入 ~/.bashrc）
export MUSA_INSTALL_PATH=/usr/local/musa
export PATH=$MUSA_INSTALL_PATH/bin:$PATH
export LD_LIBRARY_PATH=$MUSA_INSTALL_PATH/lib:$LD_LIBRARY_PATH
musa_version_query # 期望显示 5.2.0
musaInfo # 查看设备属性官方文档给出的 S5000 musaInfo 示例中，计算能力为 3.1、多处理器数为 56、warpSize 为 32、显存约 79.91 GB。你的输出若差异很大，先确认卡型和驱动版本。
六、muDNN 与 MCCL
bash
# muDNN：二选一
sudo apt install -y mudnn # 跟随最新版本
sudo apt install -y libmudnn3-musa-5 # 固定到 MUSA 5 大版本（包名中的 3 对应 muDNN 3 系列，属本站推断）
# MCCL：按卡型选择
sudo apt install -y mccl-s5000 # MTT S5000
sudo apt install -y mccl-s4000 # MTT S4000七、Python 包源
官方 PyPI 源为 https://dl.mthreads.com/repo/api/pypi/pypi/simple，提供 x86_64、Python 3.10/3.12 的轮子。文档示例包括 torch==2.9.1 torch_musa==2.9.1、mate==0.2.3、triton==3.6.0。
bash
pip install torch==2.9.1 torch_musa==2.9.1 \
--index-url https://dl.mthreads.com/repo/api/pypi/pypi/simple不要混用源
官方提示不要在同一条 pip 命令里混用摩尔线程源与公共 PyPI。本站补充：混用时 pip 可能从公共源选中非 MUSA 版的 torch；公共依赖请单独用一条命令安装。
八、控制可见设备
bash
export MUSA_VISIBLE_DEVICES=0,1,2,3 # 只让进程看到 0-3 号卡
# 需要彻底禁止驱动加载时（如维护）：
echo "blacklist mtgpu" | sudo tee -a /etc/modprobe.d/blacklist.conf九、已知问题
MUSA SDK v5.2.0 发布版本信息 记录：当 mtbios 版本高于 4.3.43 时，EDC 计数需要 Driver 5.2.0、dcgm 1.1.6 与 mtml 2.4.2 配套使用。监控平台升级时请一并核对这三项版本。
十、卸载与回滚
bash
# 卸载顺序：先停所有 GPU 进程与容器
# APT 安装：按实际安装的包移除（libmudnn3-musa-5、mccl-s4000 等按需加入）
sudo apt remove -y mccl-s5000 mudnn musa-toolkit mthreads-driver
sudo apt autoremove -y
# 离线 deb 安装的驱动
sudo dpkg -P musa
# tar 包安装的 Toolkit（官方卸载方式）
sudo rm -rf /usr/local/musa
sudo modprobe -rv mtgpu; sudo reboot
# 回滚：重新安装记录过的旧版本离线包升级前请记录 dpkg -s 输出与 musa_version_query 结果，保留旧版本离线包，以便回滚。
十一、常见问题
| 现象 | 排查方向 |
|---|---|
mthreads-gmi 无设备 | lspci -nn | grep 1ed5；IOMMU 设置；dmesg | grep mtgpu |
| 普通用户报权限错误 | 是否已加入 render、video 组并重新登录 |
musa_version_query 找不到 | PATH / LD_LIBRARY_PATH 是否指向 /usr/local/musa |
| APT 安装失败 | 系统是否为全新 Ubuntu 22.04 Server；否则改用离线包 |