243 lines
5.8 KiB
Markdown
243 lines
5.8 KiB
Markdown
# 天数 GPU 国产化离线部署指南
|
||
|
||
本文档用于天数/Iluvatar GPU 环境的编译、模型准备、离线包导出与目标机部署。
|
||
|
||
## 推荐基础镜像
|
||
|
||
天数默认推荐使用以下官方 vLLM 镜像作为基础镜像：
|
||
|
||
```bash
|
||
registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5
|
||
```
|
||
|
||
该镜像负责提供天数 IX 运行时、PyTorch、vLLM 与相关内核。本项目的 `Dockerfile.iluvatar` 只叠加通用 Python 依赖和业务代码，不在 Dockerfile 内重新安装 vLLM，也不使用 uv 虚拟环境。
|
||
|
||
## 目录约定
|
||
|
||
目标机推荐统一使用以下宿主机目录：
|
||
|
||
```text
|
||
/opt/dep/asr/
|
||
models/
|
||
data/
|
||
logs/
|
||
temp/
|
||
tasks/
|
||
```
|
||
|
||
容器内默认挂载为：
|
||
|
||
```text
|
||
/app/models
|
||
/app/data
|
||
```
|
||
|
||
## 在线编译融合镜像
|
||
|
||
在可访问天数镜像仓库和 Python 包源的构建机上执行：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
脚本会生成融合镜像：
|
||
|
||
```text
|
||
unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5
|
||
```
|
||
|
||
并导出镜像归档到：
|
||
|
||
```text
|
||
build-file/qwen3-asr-iluvatar-vllm0.17.0-4.4.0-v5-amd64.tar.gz
|
||
```
|
||
|
||
如果只需要本机镜像，不需要导出 tar 包，可增加 `--no-export`。
|
||
|
||
## 单独准备模型
|
||
|
||
模型下载建议独立于业务服务执行。`download-models.sh` 是增量下载脚本，不会删除已有模型目录，也不依赖 uv。
|
||
|
||
在项目根目录或离线包目录执行：
|
||
|
||
```bash
|
||
./scripts/download-models.sh --models-dir /opt/dep/asr/models
|
||
```
|
||
|
||
如果本机没有 Python 依赖，但已经有融合镜像，可以用镜像内环境下载：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
模型目录最终应至少包含：
|
||
|
||
```text
|
||
/opt/dep/asr/models/
|
||
Qwen/
|
||
Qwen3-ASR-0.6B/
|
||
Qwen3-ForcedAligner-0.6B/
|
||
damo/
|
||
iic/
|
||
```
|
||
|
||
## 导出完整离线交付包
|
||
|
||
如果要交付给不能联网的目标机，推荐直接导出天数专用离线包：
|
||
|
||
```bash
|
||
./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
|
||
```
|
||
|
||
如果模型要单独准备，不希望离线包包含模型压缩包：
|
||
|
||
```bash
|
||
./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
|
||
```
|
||
|
||
天数离线包只会包含天数专用启动文件：
|
||
|
||
```text
|
||
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`。
|
||
|
||
## 目标机离线部署
|
||
|
||
将整个离线包复制到目标机后，进入离线包目录：
|
||
|
||
```bash
|
||
chmod +x init_host_dirs.sh download-models.sh
|
||
./init_host_dirs.sh
|
||
```
|
||
|
||
导入镜像：
|
||
|
||
```bash
|
||
gunzip -c qwen3-asr-iluvatar-vllm0.17.0-4.4.0-v5-amd64.tar.gz | docker load
|
||
```
|
||
|
||
确认 `.env` 中的镜像名与导入镜像一致：
|
||
|
||
```env
|
||
ASR_IMAGE=unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5
|
||
```
|
||
|
||
按需设置显卡与 vLLM 显存比例：
|
||
|
||
```env
|
||
ILUVATAR_VISIBLE_DEVICES=0
|
||
IX_VISIBLE_DEVICES=0
|
||
CUDA_VISIBLE_DEVICES=0
|
||
QWEN_GPU_MEMORY_UTILIZATION=0.25
|
||
QWEN_VLLM_ENFORCE_EAGER=true
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
docker compose -f docker-compose-iluvatar.yml up -d
|
||
```
|
||
|
||
查看状态与日志：
|
||
|
||
```bash
|
||
docker compose -f docker-compose-iluvatar.yml ps
|
||
docker compose -f docker-compose-iluvatar.yml logs -f
|
||
```
|
||
|
||
服务默认监听 host 网络端口：
|
||
|
||
```text
|
||
http://<目标机IP>:17003
|
||
```
|
||
|
||
## 已导出的旧离线包处理
|
||
|
||
如果旧离线包里的镜像已经能识别 `Qwen3ASRForConditionalGeneration`，但启动时报 KV cache 不足，例如：
|
||
|
||
```text
|
||
Try increasing gpu_memory_utilization or decreasing max_model_len
|
||
```
|
||
|
||
不需要重新打镜像。只需要在旧离线包的 `docker-compose-iluvatar.yml` 的 `QWEN3_ASR_MODEL` 附近补充：
|
||
|
||
```yaml
|
||
QWEN_GPU_MEMORY_UTILIZATION: ${QWEN_GPU_MEMORY_UTILIZATION:-0.25}
|
||
QWEN_VLLM_ENFORCE_EAGER: ${QWEN_VLLM_ENFORCE_EAGER:-true}
|
||
```
|
||
|
||
然后重新创建容器：
|
||
|
||
```bash
|
||
docker compose -f docker-compose-iluvatar.yml down
|
||
docker compose -f docker-compose-iluvatar.yml up -d
|
||
```
|
||
|
||
只执行 `restart` 不会重新注入环境变量。
|
||
|
||
## 常见问题
|
||
|
||
### 为什么不用 uv？
|
||
|
||
天数 Docker 镜像内推荐直接使用系统 Python 环境。`Dockerfile.iluvatar` 使用：
|
||
|
||
```bash
|
||
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 中需要有：
|
||
|
||
```yaml
|
||
QWEN_GPU_MEMORY_UTILIZATION: ${QWEN_GPU_MEMORY_UTILIZATION:-}
|
||
QWEN_VLLM_ENFORCE_EAGER: ${QWEN_VLLM_ENFORCE_EAGER:-true}
|
||
```
|
||
|
||
然后在 `.env` 设置：
|
||
|
||
```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 不足、模型文件缺失等。
|