5.8 KiB

Raw Blame History

天数 GPU 国产化离线部署指南

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

目录约定

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

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

容器内默认挂载为：

/app/models
/app/data

在线编译融合镜像

在可访问天数镜像仓库和 Python 包源的构建机上执行：

docker pull registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5

./scripts/package_vendor_gpu_image.sh \
  --vendor iluvatar \
  --base-image registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5 \
  -v vllm0.17.0-4.4.0-v5

脚本会生成融合镜像：

unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5

并导出镜像归档到：

build-file/qwen3-asr-iluvatar-vllm0.17.0-4.4.0-v5-amd64.tar.gz

如果只需要本机镜像，不需要导出 tar 包，可增加 --no-export。

单独准备模型

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

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

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

ASR_IMAGE=unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5 \
./scripts/download-models.sh \
  --mode docker \
  --models-dir /opt/dep/asr/models

模型目录最终应至少包含：

/opt/dep/asr/models/
  Qwen/
    Qwen3-ASR-0.6B/
    Qwen3-ForcedAligner-0.6B/
  damo/
  iic/

导出完整离线交付包

如果要交付给不能联网的目标机，推荐直接导出天数专用离线包：

./export_offline_bundle.sh \
  --type iluvatar \
  --iluvatar-base registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5 \
  -v vllm0.17.0-4.4.0-v5

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

./export_offline_bundle.sh \
  --type iluvatar \
  --iluvatar-base registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5 \
  -v vllm0.17.0-4.4.0-v5 \
  --skip-models

天数离线包只会包含天数专用启动文件：

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

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

目标机离线部署

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

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

导入镜像：

gunzip -c qwen3-asr-iluvatar-vllm0.17.0-4.4.0-v5-amd64.tar.gz | docker load

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

ASR_IMAGE=unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5

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

ILUVATAR_VISIBLE_DEVICES=0
IX_VISIBLE_DEVICES=0
CUDA_VISIBLE_DEVICES=0
QWEN_GPU_MEMORY_UTILIZATION=0.25
QWEN_VLLM_ENFORCE_EAGER=true

启动服务：

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

查看状态与日志：

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

服务默认监听 host 网络端口：

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

已导出的旧离线包处理

如果旧离线包里的镜像已经能识别 Qwen3ASRForConditionalGeneration，但启动时报 KV cache 不足，例如：

Try increasing gpu_memory_utilization or decreasing max_model_len

不需要重新打镜像。只需要在旧离线包的 docker-compose-iluvatar.yml 的 QWEN3_ASR_MODEL 附近补充：

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

然后重新创建容器：

docker compose -f docker-compose-iluvatar.yml down
docker compose -f docker-compose-iluvatar.yml up -d

只执行 restart 不会重新注入环境变量。

常见问题

为什么不用 uv？

天数 Docker 镜像内推荐直接使用系统 Python 环境。Dockerfile.iluvatar 使用：

python3 -m pip install --no-cache-dir -r environments/iluvatar/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。

日志中的本地模型 repo id warning 是否致命？

vLLM 可能会先尝试按远端 repo 方式读取 safetensors，遇到本地路径时打印 warning。如果后续出现 Loading safetensors checkpoint shards 并继续加载权重，通常不是致命错误。

真正需要处理的是最后的异常，例如模型架构不识别、KV cache 不足、模型文件缺失等。

5.8 KiB Raw Blame History Unescape Escape