docs: README 分层重构 — 主页精简到 150 行 + 6 个子文档
原 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)。无内容丢失。
This commit is contained in:
audio2text dev
187
docs/CONFIG.md
Normal file
187
docs/CONFIG.md
Normal file
@@ -0,0 +1,187 @@
|
||||
← [返回主页](../README.md)
|
||||
|
||||
# 配置文件说明
|
||||
|
||||
项目预置两份配置文件，`setup.sh` 按 `AUDIO2TEXT_VARIANT` 自动复制对应文件为
|
||||
`config.yaml`（运行时实际读取的文件，不入库）：
|
||||
|
||||
| 文件 | 激活方式 | 说明 |
|
||||
|---|---|---|
|
||||
| `config.cpu.yaml` | `./setup.sh`（默认） | CPU 开发，最小模型 |
|
||||
| `config.gpu.yaml` | `AUDIO2TEXT_VARIANT=gpu ./setup.sh` | GPU 生产，质量优先 |
|
||||
| `config.example.yaml` | — | 带完整注释的字段参考模板 |
|
||||
|
||||
也可手动切换：`cp config.gpu.yaml config.yaml` 后重启容器即可，无需重建镜像（镜像不含配置）。
|
||||
运行时通过环境变量 `CONFIG_PATH` 指定路径（容器内默认 `/app/config.yaml`）。所有路径相对
|
||||
容器内文件系统。`config.py` 用 pydantic 做类型校验，缺字段时回退默认值。
|
||||
|
||||
部署流程见 [部署指南](./DEPLOYMENT.md)。
|
||||
|
||||
---
|
||||
|
||||
## CPU / GPU 两份配置的差异
|
||||
|
||||
其余字段（存储、断句、日志、docs）两份配置完全一致，仅以下 8 项不同：
|
||||
|
||||
| 字段 | `config.cpu.yaml` | `config.gpu.yaml` |
|
||||
|---|---|---|
|
||||
| `asr.model` | `tiny.en` | `large-v3-turbo` |
|
||||
| `asr.device` | `cpu` | `cuda` |
|
||||
| `asr.compute_type` | `int8` | `float16` |
|
||||
| `asr.batch_size` | `8` | `32` |
|
||||
| `asr.beam_size` | `5` | `2` |
|
||||
| `translation.model` | `Helsinki-NLP/opus-mt-en-zh` | `facebook/nllb-200-distilled-1.3B` |
|
||||
| `translation.device` | `cpu` | `cuda` |
|
||||
| `translation.batch_size` | `8` | `32` |
|
||||
|
||||
---
|
||||
|
||||
## 完整字段
|
||||
|
||||
### `server` — 服务监听
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `host` | str | `0.0.0.0` | 容器内监听地址（由 `docker -p` 映射到宿主） |
|
||||
| `port` | int | `8000` | 容器内监听端口 |
|
||||
| `workers` | int | `1` | uvicorn worker 数。ML 推理为重，固定单 worker 避免显存重复占用 |
|
||||
|
||||
### `storage` — 文件存储
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `upload_dir` | str | `/data/uploads` | 上传视频落盘根目录（按 `yyyy/mm` 分子目录） |
|
||||
| `work_dir` | str | `/data/.work` | 分片会话暂存 + 中间音频 + SQLite 数据库 |
|
||||
| `output_dir` | str | `/data/outputs` | 生成的 SRT 字幕输出目录 |
|
||||
| `chunk_bytes` | int | `1048576` | 流式分片大小（1 MiB）。注意：前端上传页固定 4 MiB，此项影响服务端缓冲 |
|
||||
| `chunk_session_ttl_seconds` | int | `300` | 被放弃的分片会话存活秒数，超时后后台 reaper 清理（短 TTL，与下方缓存清理不同） |
|
||||
| `cache_retention_days` | int | `7` | 任务产物（字幕 / 中间音频 / 保留的原始视频）保留天数；超期任务连同 DB 记录一并删除。`0` = 禁用清理 |
|
||||
| `cache_cleanup_interval_hours` | int | `24` | 定时清理间隔（小时）。容器启动时跑一次，之后按此间隔循环 |
|
||||
|
||||
### `processing` — 处理流程
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `delete_original_after_extract` | bool | `true` | 提取音频成功后删除原始视频，省空间。`false` 则保留视频 |
|
||||
| `keep_audio` | bool | `false` | 任务完成后是否保留中间 wav。`false` 则只留字幕、删 wav |
|
||||
|
||||
### `asr` — 语音识别（faster-whisper）
|
||||
|
||||
| 字段 | 类型 | 默认（CPU） | 说明 |
|
||||
|---|---|---|---|
|
||||
| `model` | str | `tiny.en` | Whisper 模型名。CPU dev 用 `tiny.en`（39M，英文专用，同系列最小）；GPU prod 用 `large-v3-turbo`（8x 速度，质量接近 large-v3） |
|
||||
| `device` | str | `cpu` | `cpu` 或 `cuda` |
|
||||
| `compute_type` | str | `int8` | CPU 用 `int8`；GPU 用 `float16` |
|
||||
| `language` | str | `en` | 识别语言，仅英语 |
|
||||
| `word_timestamps` | bool | `true` | 词级时间戳：让断句精确（取首末词时间戳）而非纯匀速估算。建议开 |
|
||||
| `vad_filter` | bool | `true` | 过滤静音段，提升识别质量与速度 |
|
||||
| `batch_size` | int | `8`（CPU）/ `32`（GPU） | `BatchedInferencePipeline` 批量解码的音频块数。GPU 拉大 batch 拉长单次 GPU 解码时间，掩盖 CPU 提取 Mel 特征的间隙，提升平均利用率 |
|
||||
| `beam_size` | int | `5`（CPU）/ `2`（GPU） | beam search 宽度。GPU turbo 模型鲁棒，降到 2 减少解码候选数与步数，加速明显、质量损失小；CPU 无加速诉求保持默认 5 |
|
||||
|
||||
### `translation` — 翻译（NLLB-200）
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `model` | str | `facebook/nllb-200-distilled-1.3B` | HuggingFace 模型名。GPU 生产用 1.3B（质量最好）；CPU dev 用 `Helsinki-NLP/opus-mt-en-zh`（~300MB，2GB 机可跑）。NLLB 同系列最小为 `distilled-600M`（~1.2GB，需 ≥4GB 内存） |
|
||||
| `device` | str | `cpu` | `cpu` 或 `cuda` |
|
||||
| `src_lang` | str | `eng_Latn` | NLLB 语言码：英语 |
|
||||
| `tgt_lang` | str | `zho_Hans` | NLLB 语言码：简体中文 |
|
||||
| `batch_size` | int | `8`（CPU）/ `32`（GPU） | 翻译批量大小。不与 ASR 共驻时显存独占，可用大 batch |
|
||||
| `max_length` | int | `256` | 单条翻译最大 token 数 |
|
||||
| `sort_by_length` | bool | `true` | 按句子长度排序后分批，减少批内 padding 浪费（GPU 收益大） |
|
||||
|
||||
### `segmentation` — 断句与字幕规范化
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `max_words_per_line` | int | `14` | 单行最多词数，超出按逗号拆分 |
|
||||
| `max_duration_seconds` | float | `7.0` | 单条字幕最长 7 秒 |
|
||||
| `min_duration_seconds` | float | `1.0` | 单条字幕最短 1 秒（太短则与下条合并） |
|
||||
| `max_chars_per_line` | int | `42` | SRT 规范：每行 ≤42 字符，超出按词折行（≤2 行） |
|
||||
|
||||
### `logging` — 日志
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `level` | str | `info` | 控制台输出的最低级别：`debug` / `info` / `warning` / `error`。不影响 `/logs` 页面（页面可自由切换级别查看） |
|
||||
| `buffer_size` | int | `2000` | `/logs` 页面内存缓冲条数（有界 deque，旧记录自动淘汰） |
|
||||
|
||||
日志分层语义：
|
||||
|
||||
| 级别 | 内容 | 示例 |
|
||||
|---|---|---|
|
||||
| **debug**（详细） | 子步骤：ffmpeg 命令、模型加载/卸载、转写逐段、翻译逐批进度 | `加载 ASR 模型 model=tiny.en device=cpu` / `ffmpeg 命令：ffmpeg -y ...` |
|
||||
| **info**（简略） | 仅任务阶段转换，看当前进行到哪一步 | `任务 1 [transcribing 55%] 识别出 3 段` |
|
||||
| **error**（详细） | 完整 traceback（文件名+行号+调用链），可点击展开 | `任务 1 失败：ffmpeg 失败 (code=183)...` + traceback |
|
||||
|
||||
> **注意**：`logging.level` 只控制控制台输出级别。`/logs` 页面始终全量缓冲（DEBUG 起），
|
||||
> 页面上的级别按钮是查询过滤，不受此配置限制——所以控制台设 `info` 保持简略，而 `/logs`
|
||||
> 页面切到 DEBUG 仍能看到所有详细子步骤。
|
||||
|
||||
### `docs` — API 文档保护
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `enabled` | bool | `true` | 是否开启 `/docs` `/redoc` `/openapi.json` |
|
||||
| `username` | str | `admin` | Basic Auth 用户名 |
|
||||
| `password` | str | `CHANGE_ME` | Basic Auth 明文密码（常量时间比较）。**部署前务必修改** |
|
||||
| `realm` | str | `audio2text docs` | WWW-Authenticate realm |
|
||||
|
||||
---
|
||||
|
||||
## 配置示例
|
||||
|
||||
```yaml
|
||||
server:
|
||||
host: 0.0.0.0
|
||||
port: 8000
|
||||
workers: 1
|
||||
|
||||
storage:
|
||||
upload_dir: /data/uploads
|
||||
work_dir: /data/.work
|
||||
output_dir: /data/outputs
|
||||
chunk_bytes: 1048576
|
||||
chunk_session_ttl_seconds: 300
|
||||
cache_retention_days: 7 # 任务产物保留天数，超期清理（0=禁用）
|
||||
cache_cleanup_interval_hours: 24 # 定时清理间隔（启动时跑一次，之后循环）
|
||||
|
||||
processing:
|
||||
delete_original_after_extract: true
|
||||
keep_audio: false
|
||||
|
||||
asr:
|
||||
model: tiny.en # GPU: large-v3-turbo
|
||||
device: cpu # GPU: cuda
|
||||
compute_type: int8 # GPU: float16
|
||||
language: en
|
||||
word_timestamps: true
|
||||
vad_filter: true
|
||||
batch_size: 8 # GPU: 32（拉长单次 GPU 解码，掩盖 CPU 特征提取间隙）
|
||||
beam_size: 5 # GPU: 2（turbo 鲁棒可降，候选数↓解码步数↓）
|
||||
|
||||
translation:
|
||||
model: facebook/nllb-200-distilled-1.3B
|
||||
device: cpu # GPU: cuda
|
||||
src_lang: eng_Latn
|
||||
tgt_lang: zho_Hans
|
||||
batch_size: 8 # GPU: 32（显存独占可用大 batch）
|
||||
max_length: 256
|
||||
sort_by_length: true # 按长度排序分批，减少 padding 浪费
|
||||
|
||||
segmentation:
|
||||
max_words_per_line: 14
|
||||
max_duration_seconds: 7.0
|
||||
min_duration_seconds: 1.0
|
||||
max_chars_per_line: 42
|
||||
|
||||
logging:
|
||||
level: info # debug | info | warning | error（控制台输出最低级别）
|
||||
buffer_size: 2000
|
||||
|
||||
docs:
|
||||
enabled: true
|
||||
username: admin
|
||||
password: "CHANGE_ME"
|
||||
realm: "audio2text docs"
|
||||
```
|
||||
Reference in New Issue
Block a user