7.1 KiB
7.1 KiB
audio2text
音频 / 视频转双语字幕服务。上传视频 → ffmpeg 提取音频 → faster-whisper 识别英语 → 断句 + 时间戳重算 → NLLB 翻译为中文 → 输出双语 SRT。全程跑在 Docker 容器里，自带 网页上传界面，支持大文件分片上传与断点续传。
仿照 zikai 的 server/ 风格分层（controllers → services），CPU 开发 / GPU 生产
同一份代码，仅靠 config.yaml 的 device + model + compute_type 三项切换。
快速开始
GPU 环境（需 NVIDIA GPU + nvidia runtime）
AUDIO2TEXT_VARIANT=gpu ./setup.sh
./start.sh # 端口 8001
启动后打开 http://127.0.0.1:8000/，拖入视频即可。详细部署流程、模型选型、CPU↔GPU 切换
见 部署指南。
功能特性
- 网页上传：拖拽 / 选择文件，多文件并发、4 MiB 分片、断点续传
- 双语字幕：英文在上、中文在下，亦可单独下载英文 / 中文字幕
- faster-whisper 转写：词级时间戳，断句精确（取首末词时间戳）
- NLLB-200 英译中：ASR 与翻译模型不共驻，翻译时独占显存跑大 batch
- 任务状态机：
queued → uploading → extracting → transcribing → segmenting → translating → done - 实时日志页：按级别分层（debug=详细子步骤 / info=阶段转换 / error=完整 traceback）
- 定时缓存清理：任务产物默认保留 7 天，超期连同 DB 记录一并删除
- SQLite 持久化（自包含，无需外部 DB）
/docs（Swagger UI）受 Basic Auth 保护
架构
Spring 风格分层，HTTP 边界（controllers）与业务逻辑（services）分离：
audio2text/
├── Dockerfile # 一份 Dockerfile，ARG VARIANT=cpu|gpu 出两个镜像
├── docker-compose.yml # cpu / gpu / dev 三个 profile
├── setup.sh / start.sh / stop.sh # 安装 / 启动 / 停止（包装 docker 命令）
├── scripts/
│ └── prefetch_models.{sh,py} # 预拉模型权重到 ./models volume（避免首次启动下载）
├── requirements.txt
├── config.example.yaml # 配置模板（复制为 config.yaml 后填值）
├── docs/ # 详细文档（见下方索引）
└── app/
├── main.py # FastAPI 应用工厂
├── config.py # 从 config.yaml 加载的类型化 Settings（pydantic）
├── database.py # SQLite 引擎 / Session / Base / get_db
├── security.py # /docs 的 Basic Auth（常量时间比较）
├── controllers/ # FastAPI 路由 —— HTTP 边界
│ ├── upload_router.py # 分片上传（建会话/查状态/传片/complete）
│ └── task_router.py # 任务列表 / 状态 / 下载字幕
├── services/ # 业务逻辑
│ ├── types.py # 共享 DTO（Word/Segment/Subtitle，纯 dataclass）
│ ├── upload_service.py # 分片上传会话 + 拼接 + 创建任务
│ ├── ffmpeg_service.py # 提取音频 16k mono pcm
│ ├── asr_service.py # faster-whisper 转写
│ ├── segmenter.py # 断句 + 时间戳重算（纯算法，零模型依赖）
│ ├── translate_service.py # NLLB 翻译
│ ├── model_manager.py # 模型加载/卸载（不共驻核心）
│ ├── scheduler.py # ffmpeg 串行队列 + GPU 调度线程
│ ├── pipeline.py # 编排：提取→识别→断句→翻译→写SRT
│ ├── srt_writer.py # SRT 写入 + 双语合并
│ ├── log_buffer.py # 内存日志缓冲（供 /logs 页面查询）
│ ├── reaper.py # 清理被放弃的上传会话（短 TTL）
│ └── cache_cleaner.py # 定时清理超期任务产物 + 孤儿目录（长保留期）
├── models/ # SQLAlchemy ORM
│ ├── task.py # Task（转写任务，状态机）
│ └── upload_session.py # UploadSession（分片会话，含 task_id FK）
├── schemas/ # pydantic 请求/响应 DTO
│ └── task.py
└── views/
├── _shared.py # 共享前端资产（BASE_CSS + SHARED_JS + 上传协议 + 页面骨架）
├── home_html.py # 主页（上传入口 + 最近任务卡片）
├── history_html.py # 历史任务分页表格（含搜索）
└── logs_html.py # 实时日志页
数据流
浏览器 /（主页）
│ 分片上传 (4 MiB/片, 可断点续传)
▼
upload_router ──► upload_service ──► UploadSession(SQLite) + 分片落盘
│ complete
▼
创建 Task(queued) ──► scheduler
│
├─ ffmpeg 串行队列（最多 1 个并发，其余排队）→ 16k mono wav
│ （按配置删原始视频）
├─ GPU 调度线程（单线程，模型复用）：
│ get_asr → asr_service.transcribe → segments(带词级时间戳)
│ unload_asr → get_translator
│ translate_service.translate → 中文译文（独占显存大 batch）
└─ srt_writer → en.srt / zh.srt / bilingual.srt
更新 Task(done) + 写 output_dir
入口
| 入口 | 地址 |
|---|---|
| 主页（上传 + 最近任务） | http://127.0.0.1:8000/ |
| 历史任务 | http://127.0.0.1:8000/history |
| 实时日志 | http://127.0.0.1:8000/logs |
| API 文档 | http://127.0.0.1:8000/docs（Basic Auth） |
| 健康检查 | http://127.0.0.1:8000/health |
文档索引
详细文档按主题拆分，主页只保留核心速览：
| 文档 | 内容 |
|---|---|
| 部署指南 | CPU / GPU 完整部署流程、前置要求、模型选型、CPU↔GPU 切换、自定义端口 |
| 配置文件说明 | CPU/GPU 配置差异表、全部字段说明（server/storage/asr/translation/...）、配置示例 |
| Docker 说明 | 镜像构建、新建/重建/改配置/改依赖四种场景、缓存分层与删除边界、⚠️ until filter 失效根因、Volume 挂载 |
| HTTP 接口 | 接口一览表、分片上传协议、请求/响应示例 |
| 架构与原理 | 断句算法、模型不共驻显存策略、GPU 利用率优化、缓存清理机制 |
| 常见问题 | CPU 跑 NLLB、模型下载、断点续传、保留原始视频、自动清理等 |
依赖
- Python：FastAPI + uvicorn + SQLAlchemy + faster-whisper + transformers（torch 按 VARIANT 分叉，CPU/GPU 装不同 wheel）。完整列表见
requirements.txt - 系统：ffmpeg（镜像内 apt 装）、patchelf（修复 ctranslate2 可执行栈）。GPU 需宿主 NVIDIA 驱动 + nvidia container runtime
镜像构建与依赖安装细节见 Docker 说明。