← [返回主页](../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"
```