6.0 KiB

Raw Blame History

沐曦 GPU 国产化离线部署指南

本文档用于沐曦/MetaX GPU 环境的编译、模型准备、离线包导出与目标机部署。

基础镜像原则

沐曦部署应使用沐曦官方或现场确认的 vLLM/MACA 基础镜像：

cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64

该镜像负责提供 MACA 运行时、PyTorch、vLLM 与相关内核。本项目的 Dockerfile.metax 只叠加通用 Python 依赖和业务代码，不在 Dockerfile 内重新安装 vLLM，也不使用 uv 虚拟环境。

目录约定

目标机推荐统一使用以下宿主机目录：

/opt/dep/asr/
  models/
  data/
    logs/
    temp/
    tasks/

容器内默认挂载为：

/app/models
/app/data

在线编译融合镜像

先按沐曦官网复制的命令登录并拉取基础镜像。账号、密码和 token 不要写入项目文件、.env 或离线包。

官网命令通常形如：

docker login --username=<沐曦账号> --password=<沐曦token> cr.metax-tech.com && \
docker pull cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64

如果沐曦基础镜像是 tar 包，则改为先导入：

docker load -i metax-vllm-official.tar
docker images | grep -i -E 'metax|maca|vllm'

然后用完整官方镜像名构建融合镜像：

./scripts/package_vendor_gpu_image.sh \
  --vendor metax \
  --base-image cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64 \
  -v 0.17.0-maca.ai3.5.3.307

脚本会生成融合镜像：

unis/qwen3-asr:metax-0.17.0-maca.ai3.5.3.307

并导出镜像归档到：

build-file/qwen3-asr-metax-0.17.0-maca.ai3.5.3.307-amd64.tar.gz

单独准备模型

模型下载建议独立于业务服务执行。download-models.sh 是增量下载脚本，不会删除已有模型目录，也不依赖 uv。

./scripts/download-models.sh --models-dir /opt/dep/asr/models

如果本机没有 Python 依赖，但已经有融合镜像，可以用镜像内环境下载：

ASR_IMAGE=unis/qwen3-asr:metax-0.17.0-maca.ai3.5.3.307 \
./scripts/download-models.sh \
  --mode docker \
  --models-dir /opt/dep/asr/models

导出完整离线交付包

./export_offline_bundle.sh \
  --type metax \
  --metax-base cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64 \
  -v 0.17.0-maca.ai3.5.3.307

如果模型要单独准备，不希望离线包包含模型压缩包：

./export_offline_bundle.sh \
  --type metax \
  --metax-base cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64 \
  -v 0.17.0-maca.ai3.5.3.307 \
  --skip-models

如果不指定 -v，脚本会使用当前时间戳作为版本号。

沐曦官方镜像内的 Python 默认使用 /opt/conda/bin/python。如果现场镜像路径不同，可额外指定：

./export_offline_bundle.sh \
  --type metax \
  --metax-base cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.17.0-maca.ai3.5.3.307-torch2.8-py312-ubuntu22.04-amd64 \
  --metax-python /path/to/python \
  --skip-models

也可以先给官方长镜像名打一个本地短标签，再把短标签传给 --metax-base；这只是为了少复制长镜像名，不是必需步骤。

沐曦离线包只会包含沐曦专用启动文件：

docker-compose-metax.yml
.env
.env.example
init_host_dirs.sh
download-models.sh
download_models_standalone.py
README.md
DEPLOYMENT.md
METAX_DEPLOYMENT.md
BUNDLE_INFO.txt
qwen3-asr-metax-*-amd64.tar.gz

不会要求使用通用 docker-compose.yml。

目标机离线部署

将整个离线包复制到目标机后，进入离线包目录：

chmod +x init_host_dirs.sh download-models.sh
./init_host_dirs.sh

导入镜像：

gunzip -c qwen3-asr-metax-0.17.0-maca.ai3.5.3.307-amd64.tar.gz | docker load

确认 .env 中的镜像名与导入镜像一致：

ASR_IMAGE=unis/qwen3-asr:metax-0.17.0-maca.ai3.5.3.307

按需设置显卡与 vLLM 显存比例：

METAX_VISIBLE_DEVICES=0
MACA_VISIBLE_DEVICES=0
MX_VISIBLE_DEVICES=0
QWEN_GPU_MEMORY_UTILIZATION=0.25
QWEN_VLLM_ENFORCE_EAGER=true

启动服务：

docker compose -f docker-compose-metax.yml up -d

查看状态与日志：

docker compose -f docker-compose-metax.yml ps
docker compose -f docker-compose-metax.yml logs -f

服务默认端口：

http://<目标机IP>:17003

沐曦与天数的差异

沐曦使用 Dockerfile.metax 和 docker-compose-metax.yml
天数使用 Dockerfile.iluvatar 和 docker-compose-iluvatar.yml
沐曦目标机需要可访问宿主 /dev 与 /opt/mxdriver
沐曦 compose 使用 host network、host pid/ipc、privileged，并挂载 /dev 与 /opt/mxdriver
天数 compose 同样使用 host network、host pid/ipc、privileged 和宿主机设备/驱动目录挂载

常见问题

为什么不用 uv？

沐曦 Docker 镜像内推荐直接使用系统 Python 环境。Dockerfile.metax 使用：

python3 -m pip install --no-cache-dir -r environments/metax/requirements.txt

不创建 uv 虚拟环境，也不在镜像内运行 uv pip install。

为什么不重新安装 vLLM？

国产 GPU 的 vLLM、PyTorch、内核和运行时通常需要严格匹配厂商镜像。项目层重新 pip install vllm 容易解析到 PyPI/NVIDIA CUDA 依赖，破坏沐曦官方镜像里的匹配关系。

`QWEN_GPU_MEMORY_UTILIZATION` 为什么没生效？

变量必须进入容器才会生效。沐曦 compose 中需要有：

      QWEN_GPU_MEMORY_UTILIZATION: ${QWEN_GPU_MEMORY_UTILIZATION:-}
      QWEN_VLLM_ENFORCE_EAGER: ${QWEN_VLLM_ENFORCE_EAGER:-true}

然后在 .env 设置：

QWEN_GPU_MEMORY_UTILIZATION=0.25
QWEN_VLLM_ENFORCE_EAGER=true

修改 .env 后必须 down 再 up -d。

6.0 KiB Raw Blame History Unescape Escape