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)。无内容丢失。
2.1 KiB
← 返回主页
常见问题
Q: CPU 开发机能跑 NLLB 吗？
config.cpu.yaml 默认用 opus-mt-en-zh（~300MB），2GB 内存开发机即可跑通完整流程。
若想在 CPU 上验证 NLLB 翻译质量，可手动改 translation.model：
facebook/nllb-200-distilled-600M（~1.2GB，同系列最小）——需 ≥4GB 内存，2GB 机会 OOM。facebook/nllb-200-distilled-1.3B（~2.5GB，GPU 生产同款）——需 ~5GB 内存。
生产环境（3090 24G）用 NLLB-1.3B 质量最好。
Q: 模型下载到哪里？每次启动都重下吗？
模型缓存到 /models volume（HF_HOME=/models/huggingface、CT2_CACHE=/models/ctranslate2）。
首次启动下载，之后跨容器复用秒起。删除 ./models 目录会强制重下。
Q: 上传大视频中断了怎么办？
分片上传支持断点续传。重新上传同一文件时，前端先调 status 接口查已传分片，只补传缺失的。
分片可乱序、可重传覆盖。
Q: 怎么保留原始视频不删？
把 config.yaml 的 processing.delete_original_after_extract 改为 false。
注意：保留的视频仍受缓存清理策略约束——任务超期（默认 7 天）后会被 cache_cleaner
连同字幕一起删除。想永久保留请把 storage.cache_retention_days 设为 0（禁用清理）。
Q: 字幕 / 任务记录多久会被自动清理？能禁用吗？
默认保留 7 天（storage.cache_retention_days）。超期任务的字幕、中间音频、保留的原始
视频连同 DB 记录一并删除，启动时跑一次 + 每 cache_cleanup_interval_hours（默认 24h）
循环一次。设 cache_retention_days: 0 可禁用自动清理（产物永久保留，需自行管理磁盘）。
手动触发：docker exec audio2text python -m app.services.cache_cleaner。
Q: GPU 镜像构建好了但 start.sh 还是用 CPU？
start.sh 检测到 audio2text:gpu 镜像且本机有 nvidia-smi 才用 GPU。确认宿主装了
NVIDIA 驱动 + nvidia container runtime。也可用 docker compose --profile gpu up -d 显式启动。