【起因：为什么"驱动"成了高频问题】

torch_musa 和驱动其实是两条线：版本号跟着 PyTorch 走，驱动跟着 MUSA SDK 走。两边各更各的，团队里就很容易出现这样的局面：

· 有人跑 2026 年的新模型，需要新驱动；

· 更多人在跑 2025 年及以前的老模型，那套代码或算子只认老驱动。

用错的结果：轻则 torch.musa.is_available() 返回 False，重则算子跑飞、精度对不上、训练莫名崩溃。

【torch_musa 是什么】

torch_musa 是摩尔线程出的 PyTorch 扩展包，让 PyTorch 脚本直接跑在 MUSA GPU 上。API 和 PyTorch 完全对齐，迁移基本就是换个后端字符串：

import torch

torch.musa.is_available() # True

a = torch.tensor([1.2, 2.3], device="musa")

torch.backends.mudnn.allow_tf32 = True

import torch.distributed as dist

dist.init_process_group("mccl", rank=rank, world_size=world_size)

两个小彩蛋：2.1.0 起 import torch 就会自动加载 torch_musa，不用手动 import；要写 C/C++ 层可以用 MUSAExtension，纯 CUDA 脚本想直接跑还能再配 torchada。仓库：github.com/MooreThreads/torch_musa

【版本节奏：命名规则】

torch_musa 版本号跟 PyTorch 对齐，各版本能力对照如下：

· 版本 2.1.x，基于 PyTorch 2.5.0：AOTInductor、FSDP2、Triton-MUSA

· 版本 2.5.0，基于 PyTorch 2.5.0：集成 muSolver/muFFT；UMM

· 版本 2.7.0 / 2.7.1，基于 PyTorch 2.7.1：Dynamic Double Casting、分布式 Checkpoint、FSDP2 overlap

· 版本 2.9.0，基于 PyTorch 2.9.0：默认 FP32 算 GEMM（要 TF32 得显式开）；FSDP2 Context Parallel

· 版本 2.9.1，基于 PyTorch 2.9.1：正式并 Release SDK 5.1.0；算子覆盖 dense/quantized/sparse/sparsecsr/nested

· 版本 2.9.1.post1，基于 PyTorch 2.9.1：启用 2.9.1.postN 命名；新增 SDK 5.2.0 支持

· 版本 2.11.0.post1，基于 PyTorch 2.11：最新；兼容 SDK 5.1 / 5.2；LibTorch Stable ABI 覆盖 2.9–2.11

注意，从 2.9.1.post1 起命名改成了 {major}.{minor}.{patch}.post{N}（对齐 PyPI）。看到 .postN 不用慌，那是同基线的增量补丁。

【核心：驱动配套矩阵】

· 版本 2.9.1 及更新 → 驱动 5.2.0（新一代栈，SDK 5.x）

· 版本 2.7.1 → 驱动 4.x（老模型栈，只能用 4 开头，不兼容 5.x）

记法就一句：新的配 5.2.0，老的配 4.x。

【为什么环境里要同时备两版驱动】

因为用哪个 torch_musa，看的是模型代际，不是机器新旧：

· 新模型 → torch_musa 2.9.1+ → 5.2.0 驱动；

· 2025 年及以前的老模型 → torch_musa 2.7.1 → 4.x 驱动。

两拨人常在同一个集群里跑，所以驱动得备两版，按人、按任务分。别想着"统一升到最新"一劳永逸——老模型换到新栈上不一定跑得起来，反而把本来能跑的环境搞坏。

【命名坑：deb 文件名 ≠ SDK 版本】

先说目录：sw-release/musa/external/{SDK版本}/deb/musa_{驱动版本}-server_amd64.deb。这里有个大坑——deb 文件名跟 SDK 版本根本对不上：

· SDK 目录 4.3.5 → deb 文件名 musa_3.3.5-server_amd64.deb

· SDK 目录 4.3.9 → deb 文件名 musa_3.3.9-server_amd64.deb

· SDK 目录 5.2.0 → deb 文件名 musa_5.2.0-server_amd64.deb

也就是说，4.x 的 SDK 包名是 musa_3.3.x，只有 5.x 才叫 musa_5.x。挑包一定认 SDK 目录，别只看文件名。MOSS 现有版本：4.3.0 … 4.3.9、5.0.0、5.1.0、5.2.0、5.3.0。

【包从哪拿】

· 驱动 deb：MOSS 目录 sh-moss/sw-release/musa/external/{SDK}/deb/

· torch_musa/torchwheel：GitHub Release 页（github.com/MooreThreads/torch_musa）

· 容器镜像：registry.mthreads.com/mcconline/musa-pytorch-release-public:latest（首启自带环境自检）

【动手验证（三步）】

mthreads-gmi # 驱动装好没

musaInfo # 环境自检

python3 -c "import torch, torch_musa;

print('torch', torch.version);

print('torch_musa', torch_musa.version);

print('musa available', torch.musa.is_available())" # 认不认设备

出现 musa available True，就能开跑。

【一句话总结】

· torch_musa 版本跟 PyTorch 走，驱动跟 SDK 走；

· 2.9.1+ 配 5.2.0，2.7.1 配 4.x；

· 环境里备两版驱动，按模型代际发；

· deb 文件名会骗人，认 SDK 目录。

你踩过哪些版本配套的坑？评论区补一下机型 / torch_musa / 驱动组合，一起把对照表攒全。

基于 torch_musa 官方 Release Note 和内部环境实践整理，具体版本以官方 Release 页为准。