← 返回主页
配置文件说明
项目预置两份配置文件，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 做类型校验，缺字段时回退默认值。
部署流程见 部署指南。
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 |
配置示例
5f6a242114