← [返回主页](../README.md)

# 部署指南

CPU 开发 / GPU 生产同一份代码，仅靠 `AUDIO2TEXT_VARIANT` 切换镜像 + 配置。
本文档覆盖两种环境的完整部署流程、模型选型与切换方法。

构建 / 重建镜像的 Docker 操作细节见 [Docker 说明](./DOCKER.md)；
配置字段含义见 [配置文件说明](./CONFIG.md)。

---

## 部署：CPU 开发环境

CPU 模式用于本地开发与流程验证，模型选同系列最小尺寸，2GB 内存开发机即可跑通完整流程。

### 前置要求

- Docker（用于构建镜像 + 运行容器）
- 约 500 MB 磁盘（模型缓存）+ 上传视频空间

CPU 模式**不需要** NVIDIA 驱动，普通 Linux / macOS / WSL 均可。

### 步骤

```bash
cd /root/zikai/audio2text

# 1. 构建 CPU 镜像 + 复制 config.cpu.yaml → config.yaml
./setup.sh                         # 默认 AUDIO2TEXT_VARIANT=cpu

# 2. 启动容器（默认端口 8000）
./start.sh

# 3. 停止 / 重启
./stop.sh
./start.sh
```

`setup.sh` 做三件事：检查 docker → 构建 `audio2text:cpu` 镜像 → 把 `config.cpu.yaml`
复制为 `config.yaml`（运行时实际读取的文件）。可重复执行；改完配置后重新 `cp` 并重启即可，
无需重建镜像。

首次启动会下载模型（Whisper `tiny.en` ~39M + opus-mt ~300MB）到 `./models` volume，
之后秒起。启动后浏览器打开 `http://127.0.0.1:8000/`，拖入视频或音频文件即可。

### 预拉模型（避免首次启动卡在下载）

容器首次处理任务时会从 HuggingFace 下载模型，大模型（GPU 的 large-v3-turbo ~3GB +
NLLB-1.3B ~2.5GB）下载耗时较长。可用预拉脚本提前下好到 `./models` volume，之后容器启动
即用、无需联网：

```bash
./scripts/prefetch_models.sh                  # 读 config.yaml（当前激活配置）
./scripts/prefetch_models.sh config.gpu.yaml  # 读指定配置（如切换到 GPU 前预拉大模型）
```

脚本用已构建的镜像跑一次性容器，读配置里的 `asr.model` / `translation.model`，下载到
`./models/huggingface`（HF 标准缓存）。**幂等**：已下过的模型自动跳过。换 config 的模型
名后重跑即可补下新模型，无需重建镜像。

### CPU 模型选型

| 组件 | 模型 | 大小 | 说明 |
|---|---|---|---|
| ASR | `tiny.en` | ~39M | Whisper 同系列最小，英文专用版（比通用 `tiny` 在英语上更准） |
| 翻译 | `Helsinki-NLP/opus-mt-en-zh` | ~300MB | 最轻量英译中。NLLB 同系列最小 `distilled-600M` 需 ~2.4GB，2GB 机 OOM，故回退 |

> 翻译质量与 GPU 的 NLLB-1.3B 有差异，但**完整流程一致**（提取→识别→断句→翻译→双语 SRT），
> 足以验证端到端逻辑。如需在 CPU 上验证 NLLB 翻译质量，可把 `translation.model` 改为
> `nllb-200-distilled-600M`（需 ≥4GB 内存）或 `nllb-200-distilled-1.3B`（需 ~5GB 内存）。

### 自定义端口

```bash
AUDIO2TEXT_PORT=9000 ./start.sh
```

---

## 部署：GPU 生产环境

GPU 模式用于生产，模型质量优先，NVIDIA 3090 24G 上几 GB 视频几分钟出字幕。

### 前置要求

- Docker
- **NVIDIA GPU 驱动**（宿主机）
- **nvidia container runtime**（让容器能用 GPU；安装 `nvidia-container-toolkit`）
- 约 6 GB 磁盘（模型缓存：large-v3-turbo ~3GB + NLLB-1.3B ~2.5GB）

验证 GPU 可用：

```bash
nvidia-smi                            # 宿主能看到 GPU
docker run --rm --gpus all nvidia/cuda:12.1.0-runtime-ubuntu22.04 nvidia-smi
# 上面容器内也能列出 GPU 即说明 nvidia runtime 已就绪
```

### 步骤

```bash
cd /root/zikai/audio2text

# 1. 构建 GPU 镜像 + 复制 config.gpu.yaml → config.yaml
AUDIO2TEXT_VARIANT=gpu ./setup.sh

# 2. 启动容器（start.sh 检测到 gpu 镜像 + nvidia-smi 自动加 --gpus all）
./start.sh

# 3. 停止 / 重启
./stop.sh
./start.sh
```

`start.sh` 的镜像选择逻辑：若本机存在 `audio2text:gpu` 镜像**且**有 `nvidia-smi`，自动用
GPU 模式（`--gpus all`）；否则回退 CPU 镜像。也可用 docker compose 显式启动：

```bash
docker compose --profile gpu up -d --build   # GPU
docker compose --profile cpu up -d --build   # CPU
```

### GPU 模型选型

| 组件 | 模型 | 显存 | 说明 |
|---|---|---|---|
| ASR | `large-v3-turbo` | ~3GB（FP16） | 8x 速度，质量接近 large-v3 |
| 翻译 | `facebook/nllb-200-distilled-1.3B` | ~2.5GB（FP16） | 质量最好的蒸馏版 |

ASR 与翻译**不共驻**：翻译阶段先卸载 Whisper 释放显存，独占跑大 batch（`batch_size=32`），
两者峰值显存互不叠加，远低于 24G 上限。模型缓存（`./models` volume）跨容器复用，
CPU→GPU 切换时 NLLB/Whisper 大模型首次下载、之后秒起。

GPU 利用率调优（batch_size / beam_size 选择依据）见
[架构与原理 - GPU 利用率优化](./ARCHITECTURE.md#gpu-利用率优化)。

### CPU ↔ GPU 切换

同一份代码，仅靠 `AUDIO2TEXT_VARIANT` 切换镜像 + 配置：

```bash
AUDIO2TEXT_VARIANT=gpu ./setup.sh   # 切到 GPU（构建 gpu 镜像 + config.gpu.yaml）
AUDIO2TEXT_VARIANT=cpu ./setup.sh   # 切回 CPU（构建 cpu 镜像 + config.cpu.yaml）
./start.sh                          # 重新启动
```

两套配置的差异仅在 8 项（其余字段完全一致），完整对照见
[配置文件说明 - CPU/GPU 差异](./CONFIG.md#cpu--gpu-两份配置的差异)。

### 启动后的入口

两种模式通用：

| 入口 | 地址 |
|---|---|
| 主页 | `http://127.0.0.1:8000/`（上传入口 + 最近 10 任务进度卡片） |
| 历史任务 | `http://127.0.0.1:8000/history`（分页查看所有任务，可按文件名搜索、下载字幕） |
| 日志页 | `http://127.0.0.1:8000/logs`（按级别分层、自动刷新） |
| API 文档 | `http://127.0.0.1:8000/docs`（Basic Auth，凭据见 config.yaml `docs` 段） |
| 健康检查 | `http://127.0.0.1:8000/health` |
| 任务列表 | `http://127.0.0.1:8000/api/tasks` |

### 验证 GPU 配置生效

```bash
curl -s http://127.0.0.1:8001/health | python -m json.tool
# 应见 cuda_available=true, gpu="NVIDIA GeForce RTX 3090",
#      asr_batch_size=32, asr_beam_size=2, asr_model=large-v3-turbo
```