test/docs/deployment.md

# Qwen3-ASR 部署指南

快速部署 Qwen3-ASR 语音识别服务，支持 CPU/macOS、NVIDIA GPU、沐曦 GPU、天数 GPU 与摩尔线程 GPU 运行形态。

如果你正在继续验证本轮 CUDA 官方 vLLM 迁移，请同时参考：

- [PENDING_CUDA_VLLM_HANDOFF.md](./TODO/PENDING_CUDA_VLLM_HANDOFF.md)

依赖安装现在改成根目录默认 NVIDIA GPU，CPU、沐曦、天数与摩尔线程为单独特化环境：

| 模式 | 命令 | 说明 |
|------|------|------|
| NVIDIA GPU | `uv sync` 或 `./scripts/sync_gpu_env.sh` | Linux/NVIDIA 运行时，默认锁定 CUDA 13.0/cu130 `torch 2.11.0` / `torchaudio 2.11.0` / `torchvision 0.26.0` + `vllm 0.20.0` |
| 沐曦 GPU | `./scripts/sync_metax_env.sh` | 同步公共依赖；可选 GPU 栈安装默认从沐曦 MACA PyPI 源按 `--no-deps` 安装 |
| 天数 GPU | `./scripts/sync_iluvatar_env.sh` | 同步公共依赖；GPU 栈使用天数官方 vLLM 镜像 |
| 摩尔线程 GPU | `./scripts/sync_mthreads_env.sh` | 同步公共依赖；GPU 栈使用摩尔线程官方 MUSA vLLM 镜像 |
| CPU | `./scripts/sync_cpu_env.sh` | Linux/CPU 运行时 |
| 自动 | `./scripts/sync_accel_env.sh` | 根据 `mx-smi` / `ixsmi` / `mthreads-gmi` / `nvidia-smi` 自动选择沐曦、天数、摩尔线程、NVIDIA 或 CPU 环境 |

## 快速部署

### NVIDIA GPU 版本部署（推荐）

适用于生产环境，提供更快的推理速度：

**前置要求：**
- NVIDIA GPU（默认镜像面向 CUDA 13.0+；CUDA 12.6 / 13.0 可通过构建参数覆盖）
- 已安装 NVIDIA Container Toolkit
- 显存 12GB+（推荐 16GB+ 以支持 Qwen3-ASR 1.7B）

```bash
# 使用 docker run（带模型挂载）
docker run -d --name qwen3-asr \
  --gpus all \
  -p 17003:8000 \
  -v /opt/dep/asr/models:/app/models \
  -v /opt/dep/asr/data:/app/data \
  -e ACCELERATOR=nvidia \
  -e DEVICE=auto \
  -e QWEN_GPU_MEMORY_UTILIZATION=0.3 \
  -e QWEN_VLLM_ENFORCE_EAGER=true \
  unis/qwen3-asr:gpu-latest

# 或使用 docker-compose（推荐）
docker-compose up -d
```

### 沐曦 GPU 版本部署

适用于已安装沐曦驱动与容器运行栈的机器：

```bash
docker run -d --name qwen3-asr-metax \
  --privileged \
  --network=host \
  --pid=host \
  --ipc=host \
  -v /dev:/dev \
  -v /opt/mxdriver:/opt/mxdriver:ro \
  -v /opt/dep/asr/models:/app/models \
  -v /opt/dep/asr/data:/app/data \
  -e ACCELERATOR=metax \
  -e PORT=17003 \
  -e METAX_VISIBLE_DEVICES=0 \
  unis/qwen3-asr:metax-latest

# 或使用 docker-compose-metax.yml
docker compose -f docker-compose-metax.yml up -d
```

构建沐曦镜像时，`Dockerfile.metax` 会基于沐曦官方 vLLM 镜像融合本项目代码与通用依赖：

```bash
./scripts/package_vendor_gpu_image.sh \
  --vendor metax \
  --base-image <沐曦官方vLLM镜像名> \
  -v n260-3.7.0.38
```

沐曦等国产 GPU 的生产推荐路径是“厂商官方 vLLM 镜像 + 本项目代码/通用依赖”。不要在项目 Dockerfile 中重新 `pip install vllm`，避免解析到 PyPI/NVIDIA CUDA 依赖。

沐曦 GPU 的完整编译、模型准备和离线交付流程见 [沐曦 GPU 国产化离线部署指南](./metax_offline_deployment.md)。

### 天数 GPU 版本部署

适用于已安装天数驱动与容器运行栈的机器。按天数官方镜像运行建议，本 compose 使用 host network、host pid/ipc、privileged、`/dev`、`/usr/src`、`/lib/modules` 等挂载，并额外挂载本项目模型与数据目录：

```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

ASR_IMAGE=unis/qwen3-asr:iluvatar-vllm0.17.0-4.4.0-v5 \
docker compose -f docker-compose-iluvatar.yml up -d
```

天数 GPU 的完整编译、模型准备和离线交付流程见 [天数 GPU 国产化离线部署指南](./iluvatar_offline_deployment.md)。

### 摩尔线程 GPU 版本部署

适用于已安装摩尔线程驱动与 MUSA 容器运行栈的机器：

```bash
docker pull registry.mthreads.com/presale/devtech/vllm_musa:s4000_4.3.5_d0519

./scripts/package_vendor_gpu_image.sh \
  --vendor mthreads \
  --base-image registry.mthreads.com/presale/devtech/vllm_musa:s4000_4.3.5_d0519 \
  -v s4000_4.3.5_d0519

ASR_IMAGE=unis/qwen3-asr:mthreads-s4000_4.3.5_d0519 \
docker compose -f docker-compose-mthreads.yml up -d
```

摩尔线程 GPU 的完整编译、模型准备和离线交付流程见 [摩尔线程 GPU 国产化离线部署指南](./mthreads_offline_deployment.md)。

默认推荐将宿主机目录统一挂载到 `/opt/dep/asr` 下，目录结构如下：

```text
/opt/dep/asr/models/
  Qwen/
  iic/
  damo/
```

如果你希望挂载到自定义目录，可统一设置：

```bash
export MODEL_STORAGE_DIR=/data/qwen3-asr-models
export DATA_STORAGE_DIR=/data/qwen3-asr-data
mkdir -p "$MODEL_STORAGE_DIR" "$DATA_STORAGE_DIR"
docker-compose up -d
```

### 多 GPU 拓扑模式

项目现在支持统一的多 GPU 拓扑开关：

- `ASR_DEPLOY_TOPOLOGY=isolated`
  - 默认模式
  - 每张卡启动 1 个 backend 实例
  - 容器内使用 Nginx 负载均衡到多个实例
- `ASR_DEPLOY_TOPOLOGY=sharded`
  - 单个 backend 进程占用多张卡
  - 由 vLLM 在进程内部做多卡分片
- `ASR_DEPLOY_TOPOLOGY=auto`
  - 优先尝试 `sharded`
  - 如果当前平台、可见设备或 shard 数不满足条件，则自动回退到 `isolated`

### NVIDIA 多 GPU 自动并行部署（推荐）

适用于并发量较高场景。该方案通过容器 entrypoint 自动完成：
- 根据 `ASR_VISIBLE_DEVICES` 拉起多个 ASR 实例（每张卡 1 个实例）
- 容器内自动生成 Nginx upstream 并负载均衡到各实例
- 对外仍只暴露一个服务端口（默认 `8000`）

你不需要手工维护多个 `docker-compose` 服务块或手工维护 nginx upstream。

```bash
# 4 卡示例：GPU0,1,2,3 各启动 1 个实例
ASR_VISIBLE_DEVICES=0,1,2,3 docker-compose up -d
```

常用组合：
- 单卡（保持默认）：`ASR_VISIBLE_DEVICES=0`
- 双卡：`ASR_VISIBLE_DEVICES=0,1`
- 四卡：`ASR_VISIBLE_DEVICES=0,1,2,3`

强制单实例多卡分片：

```bash
ASR_DEPLOY_TOPOLOGY=sharded \
ASR_VISIBLE_DEVICES=0,1 \
docker-compose up -d
```

自动选择模式：

```bash
ASR_DEPLOY_TOPOLOGY=auto \
ASR_VISIBLE_DEVICES=0,1 \
docker-compose up -d
```

**服务访问地址：**
- API 服务: `http://localhost:17003`
- API 文档: `http://localhost:17003/docs`

### 沐曦多 GPU 自动并行部署

```bash
ASR_VISIBLE_DEVICES=0,1 docker compose -f docker-compose-metax.yml up -d
```

### 摩尔线程多 GPU 自动并行部署

```bash
ASR_VISIBLE_DEVICES=0,1 docker compose -f docker-compose-mthreads.yml up -d
```

### CPU 版本部署

适用于开发测试或无 GPU 环境：

```bash
docker run -d --name qwen3-asr \
  -p 17003:8000 \
  -v /opt/dep/asr/models:/app/models \
  -v /opt/dep/asr/data:/app/data \
  -e DEVICE=cpu \
  unis/qwen3-asr:cpu-latest
```

**注意：** CPU 版本不使用 GPU/vLLM 路径。
当前 CPU 镜像已集成 QwenASR Rust backend，会自动选择 `qwen3-asr-0.6b`。
CPU 镜像默认使用可分发的 `x86-64-v2` Rust 构建目标，避免把构建机的 native CPU 指令带入通用镜像。
如果你确认构建机与部署机 CPU 指令集一致，可在自建镜像时设置 `QWENASR_RUST_TARGET_CPU=native` 换取更激进优化。
当前 Rust backend 的 x86 kernel 需要 `avx2` 与 `fma`，不满足时启动会给出明确错误。镜像默认限制
`OPENBLAS_NUM_THREADS=1` / `OMP_NUM_THREADS=1` / `GOTO_NUM_THREADS=1`，以减少多 runtime 并发时的线程争抢。
CUDA vLLM 与 CPU Rust 路径下，`word_timestamps=true` 会自动调用 forced aligner 返回字词级时间戳。

### 离线交付目录导出

如果你需要把镜像交付到不能联网的机器，推荐直接生成一个完整的离线交付目录。该脚本使用普通 `docker build` + `docker save`，不依赖 `buildx`：

```bash
# 生成 GPU 离线交付目录
./export_offline_bundle.sh --type gpu

# 或生成 CPU 离线交付目录
./export_offline_bundle.sh --type cpu

# 或生成沐曦 GPU 离线交付目录
./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 \
  --skip-models
./export_offline_bundle.sh --type iluvatar --iluvatar-base registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5
./export_offline_bundle.sh --type mthreads --mthreads-base registry.mthreads.com/presale/devtech/vllm_musa:s4000_4.3.5_d0519

# 或一次同时生成 GPU + CPU 离线交付目录
./export_offline_bundle.sh --type all
```

生成后的目录形如：

```text
build-file/
  20260520_153000-all/
    qwen3-asr-cpu-20260520_153000-amd64.tar.gz
    qwen3-asr-gpu-20260520_153000-amd64.tar.gz
    docker-compose.yml
    docker-compose-cpu.yml
    docker-compose-metax.yml
    .env.example
    init_host_dirs.sh
    README.md
    DEPLOYMENT.md
```

其中会自动包含：

- 对应类型的一份或两份镜像压缩包
- 对应类型的 compose 文件；天数包只包含 `docker-compose-iluvatar.yml`
- 摩尔线程包只包含 `docker-compose-mthreads.yml`
- `.env` 模板
- 宿主机目录初始化脚本
- 离线部署说明文档

模型文件建议使用 `./scripts/download-models.sh --models-dir /opt/dep/asr/models` 单独准备；该脚本增量补齐缺失模型，不删除已有目录，也不依赖 uv。

当前运行时 / 设备默认值以主 README 为准：

- `README.md`
- `docs/README_zh.md`
设计背景与实现思路可参考：

- 当前 Qwen3 后端：`NVIDIA/沐曦 GPU -> vLLM`、`CPU/macOS -> vendored QwenASR Rust`
- 引用项目 [QwenASR](https://github.com/huanglizhuo/QwenASR)

### macOS / Apple Silicon 本地部署

适用于 M1/M2/M3/M4 机器上的本地 Qwen3-ASR 推理。当前 macOS 已统一走 vendored QwenASR Rust CPU backend。

```bash
./scripts/sync_cpu_env.sh
source .venv/bin/activate
python start.py
```

### 验证部署

```bash
# 健康检查
curl http://localhost:17003/stream/v1/asr/health

# 查看可用模型
curl http://localhost:17003/stream/v1/asr/models

# 测试语音识别（阿里云协议）
curl -X POST "http://localhost:17003/stream/v1/asr" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @test.wav

# 测试 OpenAI 兼容接口
curl -X POST "http://localhost:17003/v1/audio/transcriptions" \
  -H "Authorization: Bearer any" \
  -F "file=@test.wav" \
  -F "model=qwen3-asr-1.7b"
```

## 从源码构建镜像

### 使用构建脚本

项目提供了一个更薄的 `scripts/build_docker.sh` 包装层，用于统一 `docker buildx` 参数：

```bash
# 构建所有版本（CPU + GPU）
./scripts/build_docker.sh

# 仅构建 GPU 版本
./scripts/build_docker.sh -t gpu

# 构建指定版本并推送
./scripts/build_docker.sh -t all -v 1.0.1 -p

# 查看帮助
./scripts/build_docker.sh -h
```

**构建脚本参数：**

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-a, --arch` | 目标架构: `amd64`, `arm64`, `multi` | `amd64` |
| `-t, --type` | 构建类型: `cpu`, `gpu`, `all` | `all` |
| `-v, --version` | 版本标签 | `latest` |
| `-p, --push` | 构建后推送到 Docker Hub | 否 |
| `-e, --export` | 导出单架构镜像为 tar.gz | 否 |
| `-o, --output` | 导出目录 | `.` |
| `-r, --registry` | 镜像仓库 | `unis` |
| `-n, --no-cache` | 禁用 Docker 构建缓存 | 否 |

### 手动构建

```bash
# 构建 CPU 版本
docker build -t qwen3-asr:cpu-latest -f Dockerfile.cpu .

# 构建绑定当前机器指令集的 CPU 版本（仅适合同构部署）
docker build -t qwen3-asr:cpu-native -f Dockerfile.cpu \
  --build-arg QWENASR_RUST_TARGET_CPU=native \
  .

# 构建默认 GPU 版本（CUDA 13.0 / PyTorch cu130）
docker build -t qwen3-asr:gpu-cu130 -f Dockerfile.gpu .

# 构建 CUDA 12.6 版本
docker build -t qwen3-asr:gpu-cu126 -f Dockerfile.gpu \
  --build-arg PYTORCH_BASE_IMAGE=pytorch/pytorch:2.11.0-cuda12.6-cudnn9-runtime \
  --build-arg PYTORCH_CUDA_INDEX=https://download.pytorch.org/whl/cu126 \
  --build-arg CUDA_NVCC_PACKAGE=cuda-nvcc-12-6 \
  --build-arg TORCH_CUDA_ARCH_LIST="8.0;8.6;8.9" \
  .

# 构建 CUDA 13.0 版本
docker build -t qwen3-asr:gpu-cu130 -f Dockerfile.gpu \
  --build-arg PYTORCH_BASE_IMAGE=pytorch/pytorch:2.11.0-cuda13.0-cudnn9-runtime \
  --build-arg PYTORCH_CUDA_INDEX=https://download.pytorch.org/whl/cu130 \
  --build-arg CUDA_NVCC_PACKAGE=cuda-nvcc-13-0 \
  --build-arg TORCH_CUDA_ARCH_LIST="12.0+PTX" \
  .
```

`Dockerfile.cpu` 可覆盖的 CPU 构建参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `QWENASR_RUST_TARGET_CPU` | `x86-64-v2` | amd64 Rust backend 编译目标；可设为 `native` 构建绑定当前 CPU 的镜像 |

`Dockerfile.gpu` 可覆盖的 GPU 构建参数：

| 参数 | 默认值 | 用途 |
|------|--------|------|
| `PYTORCH_BASE_IMAGE` | `pytorch/pytorch:2.11.0-cuda13.0-cudnn9-runtime` | 选择 PyTorch/CUDA 基础镜像 |
| `PYTORCH_CUDA_INDEX` | `https://download.pytorch.org/whl/cu130` | 选择 PyTorch wheel CUDA 后端 |
| `CUDA_NVCC_PACKAGE` | `cuda-nvcc-13-0` | 安装匹配的 nvcc，用于 vLLM/FlashInfer JIT |
| `TORCH_CUDA_ARCH_LIST` | `12.0+PTX` | 指定 JIT 编译目标架构 |
| `VLLM_PACKAGE` | `vllm==0.20.0` | 覆盖 vLLM 包版本或来源 |

### 模型说明

服务支持以下 ASR 模型：

| 模型 | 说明 | 适用场景 |
|------|------|----------|
| Qwen3-ASR-1.7B ⭐ | 多语言 ASR（52种语言+方言，字级时间戳） | CUDA |
| Qwen3-ASR-0.6B | 轻量版多语言 ASR | CUDA / CPU Rust / macOS |

**运行时模型选择：**

系统根据机器资源自动选择合适的 Qwen3-ASR 模型：
- **显存 >= 32GB**: 自动加载 `qwen3-asr-1.7b`
- **显存 < 32GB**: 自动加载 `qwen3-asr-0.6b`
- **无 CUDA**: 自动加载基于 vendored Rust 的 `qwen3-asr-0.6b`
- **macOS / Apple Silicon**: 无论内存大小多少，默认都加载 `qwen3-asr-0.6b`
- **环境变量覆盖**: 设置 `QWEN3_ASR_MODEL=qwen3-asr-1.7b` 或 `QWEN3_ASR_MODEL=qwen3-asr-0.6b` 可硬覆盖自动选择

### 模型下载

启动时会先检测当前运行计划所需模型；如果本地缓存缺失，会自动从 ModelScope 下载。离线部署请提前准备模型缓存。
手动准备方式：

```bash
# 增量补齐离线部署所需模型，不删除已有文件
./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
```

离线部署时，推荐目录结构：

```text
/opt/dep/asr/models/
  Qwen/
  iic/
  damo/
```

然后保持与 compose 文件一致的挂载：

```yaml
volumes:
  - ${MODEL_STORAGE_DIR:-/opt/dep/asr/models}:/app/models
  - ${DATA_STORAGE_DIR:-/opt/dep/asr/data}:/app/data
```

## 环境变量配置

### 基础配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `HOST` | `0.0.0.0` | 服务绑定地址 |
| `PORT` | `8000` | 服务端口 |
| `DEBUG` | `false` | 调试模式（启用后可访问 /docs） |
| `LOG_LEVEL` | `INFO` | 日志级别：DEBUG, INFO, WARNING, ERROR |
| `WORKERS` | `1` | 工作进程数（多进程会复制模型，显存成倍增加） |
| `MAX_AUDIO_SIZE` | `2048` | 最大音频文件大小（MB，支持单位如 2GB） |
| `API_KEY` | - | 服务端统一鉴权密钥 |

### 设备配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `DEVICE` | `auto` | 设备选择：`auto`, `cpu`, `cuda:0` |
| `ASR_VISIBLE_DEVICES` | `0` | 统一可见 GPU 设备配置，程序会按当前 accelerator 自动映射到底层变量 |
| `ASR_DEPLOY_TOPOLOGY` | `isolated` | 部署拓扑：`isolated`, `sharded`, `auto` |

### 内置 Nginx 与限流配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `NGINX_RATE_LIMIT_RPS` | `0` | 全局每秒请求上限，`0` 表示关闭 |
| `NGINX_RATE_LIMIT_BURST` | `0` | 全局突发请求数，`0` 时自动取 `NGINX_RATE_LIMIT_RPS` |

### ASR 模型配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `ASR_ENABLE_REALTIME_PUNC` | `true` | 是否启用实时标点模型 |

### 性能优化配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `ASR_BATCH_SIZE` | `4` | 长音频分段后的 ASR 批处理大小 |
| `INFERENCE_THREAD_POOL_SIZE` | 自动 | 推理线程池大小；默认按 CPU 核数自动设置 |
| `MAX_SEGMENT_SEC` | `60` | 音频分段最大时长（秒） |
| `QWEN_GPU_MEMORY_UTILIZATION` | `0.9` | vLLM 可保留的 GPU 显存上限，KV cache 不足时可适当调高 |
| `QWEN_VLLM_ENFORCE_EAGER` | `true` | 强制 vLLM eager 执行以提高兼容性；NVIDIA 性能测试可设为 `false` 允许 CUDA Graph 优化 |
| `WS_MAX_BUFFER_SIZE` | `160000` | WebSocket 音频缓冲区大小（样本数） |
| `QWEN_RUST_CPU_WORKERS` | `4` | CPU Rust backend worker 数；Rust ASR / forced align 默认按该数量并行 |
| `QWEN_RUST_ASR_CONCURRENCY` | `0` | Rust ASR 阶段批内并行度；`0` 表示跟随 `QWEN_RUST_CPU_WORKERS` |
| `QWEN_RUST_ALIGN_CONCURRENCY` | `0` | Rust forced align 阶段批内并行度；`0` 表示跟随 `QWEN_RUST_CPU_WORKERS` |
| `QWENASR_LIBRARY_PATH` | 自动探测 | 覆盖 vendored Rust 动态库路径 |

### 远场过滤配置

流式 ASR 远场声音过滤功能，自动过滤远场声音和环境音：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `ASR_ENABLE_NEARFIELD_FILTER` | `true` | 启用远场声音过滤 |
| `ASR_NEARFIELD_RMS_THRESHOLD` | `0.01` | RMS 能量阈值 |
| `LOG_LEVEL=DEBUG` | - | 需要观察过滤细节时打开调试日志 |

调优建议：

- `ASR_NEARFIELD_RMS_THRESHOLD=0.01` 是当前默认值，也是推荐起点
- 嘈杂环境可以适当调高，增强背景语音过滤
- 安静环境如果出现小声说话漏识别，可以适当调低
- 需要观察过滤行为时，可临时设置 `LOG_LEVEL=DEBUG`

### 鉴权配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `API_KEY` | - | 服务端统一鉴权密钥；同时兼容 `Authorization: Bearer` 和 `X-NLS-Token` |

**使用示例：**

```bash
# 使用 Token
curl -H "X-NLS-Token: your_token" http://localhost:8000/stream/v1/asr/health

# 使用 Bearer Token（OpenAI 兼容）
curl -H "Authorization: Bearer your_token" http://localhost:8000/v1/models
```

### 日志配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `LOG_LEVEL` | `INFO` | 日志级别：`DEBUG`, `INFO`, `WARNING` |
| `LOG_FILE` | `data/logs/qwen3-asr.log` | 日志文件路径 |
| `LOG_MAX_BYTES` | `20971520` | 单个日志文件最大大小（20MB） |
| `LOG_BACKUP_COUNT` | `50` | 日志备份文件数量 |

## Docker Compose 配置

### 基础配置（GPU）

```yaml
services:
  qwen3-asr:
    image: unis/qwen3-asr:gpu-latest
    container_name: qwen3-asr
    ports:
      - "17003:8000"
    volumes:
      - /opt/dep/asr/models:/app/models
      - /opt/dep/asr/data:/app/data
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO
      - DEVICE=auto
      - QWEN_GPU_MEMORY_UTILIZATION=0.3
      - QWEN_VLLM_ENFORCE_EAGER=true
      - ASR_BATCH_SIZE=4
      - WORKERS=1
      - INFERENCE_THREAD_POOL_SIZE=4
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
```

### CPU 版本配置

```yaml
services:
  qwen3-asr:
    image: unis/qwen3-asr:cpu-latest
    container_name: qwen3-asr
    ports:
      - "17003:8000"
    volumes:
      - /opt/dep/asr/models:/app/models
      - /opt/dep/asr/data:/app/data
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO
      - DEVICE=cpu
      - WORKERS=1
      - INFERENCE_THREAD_POOL_SIZE=1
    restart: unless-stopped
```

### 生产环境配置（内置 Nginx，推荐）

```yaml
services:
  qwen3-asr:
    image: unis/qwen3-asr:gpu-latest
    container_name: qwen3-asr
    ports:
      - "17003:8000"
    volumes:
      - /opt/dep/asr/models:/app/models
      - /opt/dep/asr/data:/app/data
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO
      - DEVICE=auto
      - CUDA_VISIBLE_DEVICES=0,1
      - QWEN_GPU_MEMORY_UTILIZATION=0.3
      - QWEN_VLLM_ENFORCE_EAGER=true
      - NGINX_RATE_LIMIT_RPS=20
      - NGINX_RATE_LIMIT_BURST=40
      - WORKERS=1
      - INFERENCE_THREAD_POOL_SIZE=4
      - ASR_BATCH_SIZE=4
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
```

## 服务监控

### 健康检查

```bash
curl http://localhost:17003/stream/v1/asr/health
```

### 日志监控

```bash
# 实时查看日志
docker logs -f qwen3-asr

# 查看错误日志
docker logs qwen3-asr 2>&1 | grep -i error
```

### 资源监控

```bash
# 容器资源使用
docker stats qwen3-asr

# GPU 使用情况
docker exec -it qwen3-asr nvidia-smi
```

## 资源需求

### 最小配置（CPU 版本）

- CPU: 4 核
- 内存: 8GB
- 磁盘: 10GB

### 推荐配置（GPU 版本）

- CPU: 8 核
- 内存: 16GB
- GPU: NVIDIA GPU (12GB+ 显存，含说话人分离模型)
- 磁盘: 25GB

## 故障排除

### 常见问题

| 问题 | 症状 | 解决方案 |
|------|------|----------|
| GPU 内存不足 | CUDA OOM 错误 | 设置 `DEVICE=cpu` 或使用更大显存的 GPU |
| 模型加载失败 / 缓慢 | 本地模型缓存缺失 | 先运行 `./scripts/download-models.sh --models-dir /opt/dep/asr/models` 预准备模型 |
| 端口被占用 | 端口冲突错误 | 修改端口映射：`"8080:8000"` |
| 说话人分离失败 | CAM++ 模型错误 | 检查模型是否完整下载，显存是否充足 |

### 调试模式

```bash
# 启用调试模式
docker run -e DEBUG=true -e LOG_LEVEL=DEBUG ...

# 进入容器调试
docker exec -it qwen3-asr /bin/bash
```

## 更新服务

```bash
# 拉取最新镜像（GPU 版本）
docker pull unis/qwen3-asr:gpu-latest

# 拉取最新镜像（CPU 版本）
docker pull unis/qwen3-asr:cpu-latest

# 重启服务
docker-compose down && docker-compose up -d
```