# Qwen-Asr 国产化兼容适配汇报

## 一、适配目标

完成对 **沐曦(MetaX)** 和 **天数(Iluvatar)** 两款国产GPU的完整适配，实现语音识别服务在国产硬件平台的稳定运行。

---

## 二、适配历程与关键节点

| 时间 | 里程碑 | 关键动作 |
|------|--------|----------|
| 2026-06-02 | 架构设计 | 新增Accelerator抽象层，重构设备检测逻辑 |
| 2026-06-02 | 沐曦适配 | 新增沐曦GPU支持(MetaX MACA runtime) |
| 2026-06-02 | 天数适配 | 新增天数GPU支持(Iluvatar IX runtime) |
| 2026-06-03 | 部署完善 | 完善沐曦全流程部署支持，升级天数基础镜像 |
| 2026-06-04 | 问题修复 | 修复setuptools版本冲突，优化pip安装配置 |

---

## 三、遇到的主要"坑"与解决方案

### **坑1：设备检测适配问题**
- **问题**：不同厂商使用不同的设备查询命令（`mx-smi` vs `ixsmi`），输出格式差异大
- **解决方案**：
  - 抽象统一的`AcceleratorAdapter`接口
  - 支持多种SMI命令格式解析（JSON/表格/列表）
  - 自动检测优先级：国产厂商SMI → NVIDIA → CPU

### **坑2：vLLM/PyTorch版本不兼容**
- **问题**：国产GPU的vLLM、PyTorch、内核和运行时需要严格匹配厂商官方版本
- **解决方案**：
  - 采用"厂商官方vLLM镜像 + 项目代码叠加"策略
  - 不在Dockerfile中重新`pip install vllm`，避免解析到NVIDIA CUDA依赖
  - 提供专用环境配置文件（`environments/metax/`、`environments/iluvatar/`）

### **坑3：环境变量命名混乱**
- **问题**：各厂商使用不同的设备可见性变量名
- **解决方案**：
  - 沐曦：`METAX_VISIBLE_DEVICES` / `MACA_VISIBLE_DEVICES` / `MX_VISIBLE_DEVICES`
  - 天数：`ILUVATAR_VISIBLE_DEVICES` / `IX_VISIBLE_DEVICES` / `CUDA_VISIBLE_DEVICES`
  - 代码层统一处理，支持多种变量名自动识别

### **坑4：显存管理问题**
- **问题**：国产GPU显存分配策略与NVIDIA不同，默认配置易导致KV cache不足
- **解决方案**：
  - 引入`QWEN_GPU_MEMORY_UTILIZATION`配置项（默认0.25）
  - 强制启用`QWEN_VLLM_ENFORCE_EAGER=true`提升兼容性
  - 提供详细的显存配置指导文档

### **坑5：离线部署打包复杂**
- **问题**：目标机通常无法联网，需要完整的离线交付包
- **解决方案**：
  - 开发`export_offline_bundle.sh`一键打包脚本
  - 支持跳过模型打包（模型单独准备）
  - 生成厂商专用的docker-compose配置

### **坑6：Python环境依赖冲突**
- **问题**：沐曦官方镜像使用特定Python路径和setuptools版本
- **解决方案**：
  - 不使用uv虚拟环境，直接使用系统Python
  - 固定setuptools版本为69.5.1
  - 支持自定义Python路径配置

---

## 四、兼容性矩阵

| 平台 | 支持状态 | 基础镜像 | 设备命令 |
|------|----------|----------|----------|
| NVIDIA CUDA | ✅ 支持 | 自定义CUDA 13.0 | nvidia-smi |
| 沐曦 MetaX | ✅ 支持 | vLLM 0.17.0 + MACA AI3.5.3 | mx-smi |
| 天数 Iluvatar | ✅ 支持 | vLLM 0.17.0 + IX 4.4.0 | ixsmi |
| CPU (Rust) | ✅ 支持 | - | - |

---

## 五、交付成果

1. **代码层**：统一的加速器抽象层（`app/core/accelerator.py`）
2. **部署文档**：
   - 《沐曦GPU国产化离线部署指南》
   - 《天数GPU国产化离线部署指南》
3. **环境配置**：专用依赖配置文件（metax/iluvatar）
4. **打包脚本**：一键离线打包工具
5. **Docker镜像**：专用Dockerfile和docker-compose配置

---

## 六、关键经验总结

1. **厂商官方镜像优先**：不自行编译GPU运行时，直接使用厂商验证过的vLLM镜像
2. **统一抽象层**：通过Adapter模式屏蔽硬件差异，上层业务无感知
3. **配置化驱动**：设备可见性、显存比例等参数化配置，适应不同现场环境
4. **离线交付优先**：提前规划离线部署方案，避免现场网络限制问题