test/docs/国产化兼容适配汇报.md

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. 离线交付优先：提前规划离线部署方案，避免现场网络限制问题