## 一、核心概述
### 1. **MUSA (Metaverse Unified System Architecture)**
* 摩尔线程GPU的通用并行计算平台和编程模型
* 提供GPU编程简易接口，利用GPU并行计算引擎解决复杂计算问题
* 包含MUSAToolkits：GPU加速库、运行时库、编译器、调试和优化工具
### 2. **torch\_musa**
* 基于PyTorch v2.0.0的插件形式，支持摩尔线程GPU
* 最大程度与PyTorch代码解耦，便于维护与升级
* 利用PyTorch第三方后端扩展接口，将摩尔线程高性能计算库动态注册到PyTorch
* 支持CUDA兼容特性，CUDA kernels经过porting后可运行在摩尔线程显卡上
## 二、编译安装
### 1. **依赖环境**
* Python 3.8/3.9/3.10
* MUSA软件包：驱动、Toolkits、MUDNN、MCCL、muAlg、mutlass、muThrust等
* 推荐版本：MUSA驱动2.7.0-rc4-0822，MUSAToolkits rc3.1.0
### 2. **编译流程**
1. 向PyTorch源码打patch
2. 编译PyTorch
3. 编译torch\_musa
### 3. **推荐编译方式**
1cd torch_musa
2bash build.sh # 一键编译
3
### 4. **Docker开发环境**
* 提供开发用docker image
* 启动时需要添加`--env MTHREADS_VISIBLE_DEVICES=all`
## 三、快速入门
### 1. **常用环境变量**
* `TORCH_SHOW_CPP_STACKTRACES=1`：显示C++调用栈
* `MUDNN_LOG_LEVEL=INFO`：使能MUDNN算子库log
* `MUSA_VISIBLE_DEVICES=0,1,2,3`：控制可见显卡序号
* `MUSA_LAUNCH_BLOCKING=1`：同步模式下发MUSA kernel
### 2. **基本API使用**
1import torch
2import torch_musa
3
4torch.musa.is_available()
5torch.musa.device_count()
6a = torch.tensor([1.2, 2.3], device='musa')
7
### 3. **支持的功能**
* **推理**：支持常见模型如ResNet50
* **训练**：完整训练流程支持
* **混合精度训练**：支持AMP自动混合精度
* **分布式训练**：支持DDP分布式训练
* **TensorCore优化**：支持TensorFloat32加速
* **C++部署**：支持模型部署
## 四、算子开发
### 1. **算子实现分类**
* **Structured算子**：多种调用规则（functional、inplace、out）
* **UnStructured算子**：单一调用规则
### 2. **算子适配方法**
* **复用meta/impl函数（Legacy）**：复用CUDA实现
* **只复用meta函数（LegacyMeta）**：仅复用meta函数
* **自定义meta/impl函数（Customized）**：完全自定义实现
* **接入MUDNN（Customized）**：使用MUDNN库实现
* **CPU计算（Customized）**：回退到CPU计算
### 3. **CUDA-Porting机制**
* 自动将CUDA kernels转换为MUSA kernels
* 编译时自动进行，降低算子适配成本
## 五、第三方库扩展
### 1. **MUSAExtension API**
* 用于构建第三方库的MUSA扩展
* 支持CUDA代码迁移到MUSA
### 2. **扩展流程**
1. 分析构建脚本setup.py
2. 修改构建配置
3. 尝试构建并测试
## 六、性能优化
### 1. **Profiler工具**
* 适配PyTorch官方性能分析工具
* 支持单机多卡性能分析
* 可生成chrome trace文件
### 2. **TensorCore优化**
* 支持TensorFloat32加速
* 在S4000上可显著提升计算性能
## 七、调试工具
### 1. **异常算子对比和追踪工具**
* 检测算子执行异常
* 对比CPU和MUSA计算结果
* 支持分布式训练调试
### 2. **基本用法**
* 设置环境变量启用调试
* 分析日志结构和异常信息
* 处理检测到的异常
## 八、模型迁移示例（YOLOv5）
### 1. **手动迁移**
* device设置：将'cuda'改为'musa'
* DDP通信后端设置：使用'mccl'后端
* 混合精度训练设置
* 随机数种子设置
### 2. **自动迁移工具**
* **musa\_converter工具**：自动转换CUDA代码到MUSA
* 支持批量代码迁移
## 九、常见问题（FAQ）
### 1. **设备查看问题**
* 普通用户需添加至render group
* 使用`sudo usermod -aG render $(whoami)`
### 2. **计算库无法找到**
* 检查`/usr/local/musa/lib/`目录
* 设置`LD_LIBRARY_PATH`环境变量
### 3. **编译安装问题**
* 清理后重新编译：`python setup.py clean && bash build.sh`
* 可能需要更新MUSA软件栈
### 4. **Docker容器问题**
* 安装mt-container-toolkit
* 启动时添加`--env MTHREADS_VISIBLE_DEVICES=all`
### 5. **适配算子问题**
* 使用c++filt查看符号名称
* 在PyTorch源码中搜索符号