用途：指导在摩尔线程 MTT S5000 平台上编写、迁移、审查、调试和运行 Python/PyTorch 代码，尤其适合需要在 NVIDIA CUDA 与 MUSA 之间保持单一可维护代码库的 CUDA 项目。相关技能分工明确：musa-pytorch-python 管 Python 环境与 wheel 兼容，musa-local-server 管本机 Toolkit 路径与驱动诊断，musa-ubuntu2204-install 管其他 Ubuntu 22.04 主机的驱动/Toolkit 安装。实际操作前应优先阅读目标仓库的 AGENTS.md、环境文档与实验规则，不得借此绕过仓库对 GPU 运行、数据准备、产物路径、提交与推送的限制。
主要能力与要点：1）本地平台事实（2026-09-02 于 worker31069 验证）：8 张 MTT S5000，每张 81920 MiB；主机驱动 3.3.5-server；MUSA ToolKit / mcc 可选 4.3.5 与 5.2.0；muDNN/MCCL 为 3.1.5/2.1.5 与 3.4.0/2.4.0；Python 3.12.14；PyTorch 与 torch_musa 本机未安装；可见性变量为 MUSA_VISIBLE_DEVICES；torchada、Triton、bitsandbytes、flash-attn、MATE 未安装，不应生成依赖它们的代码。2）迁移策略优先级：后端中立 PyTorch 加少量设备抽象；行为不同时在一处平台边界内写显式 MUSA 实现；大型遗留 CUDA 代码库可用 torchada，但要求已安装、版本兼容、在入口先于 CUDA 相关模块导入并端到端测试；不支持的自定义 CUDA 扩展用原生 MUSA 扩展或纯 PyTorch 回退。不要机械替换所有 cuda 字符串，应逐处分类为设备选择、可见性/资源归属、AMP 或内存 API、分布式后端、仅 CUDA 的包或扩展、内核/架构假设、文档或产物元数据、必须保留的 NVIDIA 专用路径。3）编码前环境检查命令：mthreads-gmi、musaInfo、mcc --version、python --version，以及一段打印 torch、torch_musa 版本、torch.version.musa、musa 可用性、设备数与 mccl 可用性的 Python 代码。若 torch.musa.is_available() 为 false，先查驱动、ToolKit、匹配的 torch/torch_musa wheel、MUSA_HOME、PATH、LD_LIBRARY_PATH，再调试应用代码。不要在 MUSA 主机上原样安装 CUDA 锁定的 requirements.txt。4）设备检测与后端抽象：提供 accelerator_type/accelerator_device/set_accelerator_device 辅助函数；优先 tensor.to(device)、model.to(device)，避免 .cuda()/.musa()；MUSA 张量 device.type 为 musa；不要用 torch.cuda.is_available() 作通用 GPU 检查；不要按主机名选择 MUSA。附有 CUDA 到 MUSA 的 API 对照表，如 torch.device、torch.musa.set_device、synchronize、empty_cache、memory_allocated、Stream/Event、manual_seed，CUDA_VISIBLE_DEVICES 对应 MUSA_VISIBLE_DEVICES，backend nccl 对应 mccl，nvidia-smi 对应 mthreads-gmi。5）最小单卡程序示例展示 set_device、bfloat16、AdamW、autocast、梯度裁剪与同步。6）AMP 与数值稳定性：使用后端中立 API；fp16 需要 GradScaler；BF16 通常不需缩放；不要凭一次成功前向推断反向正确性，需分别验证前向输出、损失、梯度、裁剪前后梯度范数、参数与优化器状态有限。文中记录 Qwen3.5-2B 二进制代码 QAT 在 SDPA 下产生 NaN 梯度、改用 eager attention 可完成 20 步的局部限制，指出不可泛化为所有 MUSA SDPA 路径都损坏。7）Transformers 与 Accelerate：显式传 device 或 .to(device)；审计 device_map="auto"、dispatch、量化加载与 offload 中的 CUDA 分支；先使用原生 AdamW。8）多卡 MCCL：示例用 LOCAL_RANK 设置 musa 设备，init_process_group(backend="mccl")，DDP 包装，启动命令为 MUSA_VISIBLE_DEVICES=0,1 torchrun --standalone --nproc-per-node=2 train.py；注意可见性由启动器决定，避免 DataParallel，验证 is_backend_available("mccl")，保证集合通信顺序一致并销毁进程组。9）内存与性能：提供 synchronize 与 max_memory_allocated 辅助；计时前后同步；记录分配与保留峰值；不要把 empty_cache() 当 OOM 策略。10）CUDA 扩展：MUSAExtension 与 BuildExtension 示例使用 kernel.mu 和 mcc 编译参数；torchada 需在导入 CUDA 扩展辅助模块前导入。限制：性能与数值对齐需单独验证，高阶并行与第三方内核需自行预检。