5f6a242114
原 883 行单体 README 信息密度过高且重复（配置差异表出现 2 次、缓存说明 散落多处）。按主题拆分： 主页 README.md (150行): - 一句话简介 + 功能特性(精简) + 架构(目录树+数据流) + 快速开始 - 文档索引表(链接到 6 个子文档,每行一句话说明) - 入口地址表 + 依赖(精简) docs/ 子文档(原样搬运,不重写): - DEPLOYMENT.md (170行) CPU/GPU 部署、模型选型、CPU↔GPU 切换 - CONFIG.md (187行) 配置差异表、完整字段表、配置示例 - DOCKER.md (185行) 构建/重建/缓存分层/until根因/Volume - API.md (70行) HTTP接口表、分片上传协议、示例 - ARCHITECTURE.md(140行) 断句算法、显存策略、GPU优化、缓存清理 - FAQ.md (42行) 6 条常见问题 每个子文档顶部加「← 返回主页」链接,相关处加交叉引用 (如 DEPLOYMENT 提到缓存时链接 DOCKER.md)。无内容丢失。
171 lines
6.1 KiB
Markdown
171 lines
6.1 KiB
Markdown
← [返回主页](../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
|
||
```
|