audio2text/docs/DEPLOYMENT.md

← 返回主页

部署指南

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

构建 / 重建镜像的 Docker 操作细节见 Docker 说明； 配置字段含义见 配置文件说明。

---

部署：CPU 开发环境

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

前置要求

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

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

步骤

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，之后容器启动 即用、无需联网：

./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 内存）。

自定义端口

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 可用：

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

步骤

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 显式启动：

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 利用率优化。

CPU ↔ GPU 切换

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

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 差异。

启动后的入口

两种模式通用：

入口	地址
主页	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 配置生效

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