cat-shark
5b263171f2
- 待办：会话式长上下文方案标记为已技术评审且不实施；补记问题 A 的阶段性结论（暂缓） - 新增 docs/实验数据-字幕审校定位与修复实验.md：LLM 定位触发率/召回、合成正样本、逐条修复前后对照、成本与复现方式 - 新增 docs/实验数据-字幕重生成成本与耗时.md：单价口径、功率画像、全量推算 - decisions：补充两条决策（会话式长上下文否决、审校定位+定向修复暂缓） - scripts：归档一次性探测脚本 probe_subtitle_review_stage0.py（含 rebuild 子步骤） - AGENTS/README：补充实验与改动许可规则、文档索引
110 lines
6.1 KiB
Markdown
110 lines
6.1 KiB
Markdown
# VRSub
|
||
|
||
为视频生成 **VR 双眼字幕**的单体应用：API、调度器与全部节点在同一进程内运行，
|
||
单仓库、单环境、单命令启动。由原分布式 WOV 多仓库合并而来。
|
||
|
||
用户上传视频，选择工作流，即可得到中文 `.srt` 与 VR 双目 `.ass` 字幕；
|
||
也可以按文件夹批量处理整个媒体库，产物直接落在视频旁。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
uv sync
|
||
uv run uvicorn wov_app.main:app --reload
|
||
```
|
||
|
||
访问：
|
||
|
||
```
|
||
http://127.0.0.1:8000/ 应用中心（上传视频 → 字幕生成）
|
||
http://127.0.0.1:8000/tasks.html 任务管理
|
||
http://127.0.0.1:8000/batch.html 批量处理（按文件夹）
|
||
http://127.0.0.1:8000/admin.html 管理后台（工作流）
|
||
http://127.0.0.1:8000/workflow.html 工作流编排（DAG JSON）
|
||
http://127.0.0.1:8000/docs API 文档
|
||
```
|
||
|
||
- 模型权重本地优先：把 whisper 模型放在 `model/faster-whisper-large-v2`
|
||
（含 `model.bin`）即可完全离线运行。
|
||
- LLM 翻译默认使用 SiliconFlow，API Key 放在 gitignored 的 `.env`
|
||
（`LLM_API_KEY=sk-...`），启动时自动加载。
|
||
- 环境变量全表与依赖管理见 [docs/configuration.md](./docs/configuration.md)。
|
||
|
||
## 文档导航
|
||
|
||
| 文档 | 内容 |
|
||
| --- | --- |
|
||
| [docs/architecture.md](./docs/architecture.md) | 目录结构、核心机制（registry/scheduler/前端）、北极星不变式、单体化说明 |
|
||
| [docs/node-protocol.md](./docs/node-protocol.md) | 节点输入输出协议表、字幕样式统一、模型权重解析、长音频分块、VLM OCR 并发、暂停断点、前端框选 |
|
||
| [docs/workflows.md](./docs/workflows.md) | 内置工作流一览、`_note_` 参数标注约定、decode_full 与幻觉清洗、切换模型、产物命名 |
|
||
| [docs/configuration.md](./docs/configuration.md) | 环境变量全表、启动方式、Python/uv 管理 |
|
||
| [docs/operations.md](./docs/operations.md) | 孤儿数据清理、任务暂停/继续、进度日志、文件夹批量处理 |
|
||
| [docs/testing.md](./docs/testing.md) | 测试结构（按模块目录组织）、测试资产归属、真实模型集成测试 |
|
||
| [docs/decisions.md](./docs/decisions.md) | 设计决策与踩坑记录（模型选型、glm-ocr 循环、帧号排序等） |
|
||
| [docs/代码审查问题跟踪.md](./docs/代码审查问题跟踪.md) | 缺陷清单 R01–R08、修复记录与验收标准 |
|
||
| [docs/待办-翻译上下文复用与语义纠错.md](./docs/待办-翻译上下文复用与语义纠错.md) | 待办：翻译上下文复用需求、ASR 听岔成句、已知坑与数据现状 |
|
||
| [docs/实验数据-字幕重生成成本与耗时.md](./docs/实验数据-字幕重生成成本与耗时.md) | 字幕重生成的成本/耗时/功率实测口径与全量推算 |
|
||
| [docs/实验数据-字幕审校定位与修复实验.md](./docs/实验数据-字幕审校定位与修复实验.md) | 字幕审校（定位+定向修复）的实测结果、成本与暂缓结论 |
|
||
| [docs/VR双目字幕景深与遮挡调查报告.md](./docs/VR双目字幕景深与遮挡调查报告.md) | VR 字幕景深/遮挡方案的调研全文 |
|
||
| [docs/调研-whisper漏句与decode_full验证.md](./docs/调研-whisper漏句与decode_full验证.md) | whisper 漏句与 decode_full 的实验记录 |
|
||
| [docs/adaptive_vad.md](./docs/adaptive_vad.md) | 每视频自适应 VAD 调参方案 |
|
||
| [docs/proper_nouns.md](./docs/proper_nouns.md) | 专有名词处理表 |
|
||
|
||
代理协作规则（TDD、提交许可、测试与注释规范、执行环境）见
|
||
[AGENTS.md](./AGENTS.md)，该文件只写规则、不含项目信息。
|
||
|
||
## 目录
|
||
|
||
| 路径 | 说明 |
|
||
| --- | --- |
|
||
| `src/wov_sdk/` | 协议数据模型（与分布式版兼容） |
|
||
| `src/wov_app/` | 应用层：API、注册表、调度器、批量引擎、数据库 |
|
||
| `nodes/` | 进程内节点实现（echo/ffmpeg/whisper/llm/vlm/ass/ocr/filter） |
|
||
| `manifests/` | 节点清单 JSON |
|
||
| `workflows/` | 默认工作流定义 JSON（模型与链路均为数据） |
|
||
| `web/` | 静态前端 |
|
||
| `model/` | 本地模型权重（gitignored） |
|
||
| `data/` | SQLite 与存储（gitignored） |
|
||
| `docs/` | 设计与运维文档 |
|
||
| `tests/` | 按模块组织的测试（见 [docs/testing.md](./docs/testing.md)） |
|
||
|
||
## 内置工作流
|
||
|
||
| ID | 名称 | 链路 |
|
||
| --- | --- | --- |
|
||
| `zh-direct` | 中文直出字幕 | 提音 → 中文转写 → ASS |
|
||
| `ocr-subtitle` | 字幕OCR提取 | 抽帧 → 逐帧 OCR → 汇总 SRT → LLM 过滤 |
|
||
| `learn-translate` | 学习资料转译+翻译字幕 | 提音 → 转写(decode_full) → LLM 翻译 → ASS |
|
||
|
||
链路细节与参数约定见 [docs/workflows.md](./docs/workflows.md)。
|
||
|
||
## 模型与实验结论摘要
|
||
|
||
- 默认 LLM 为 `Qwen/Qwen3.5-35B-A3B`（2026-09 切换）：对同片 2 小时日语 ASR 做
|
||
8 个模型全量对比，质量与旧默认 `Qwen/Qwen3.6-35B-A3B` 持平，速度 0.232 s/行
|
||
（全评测最快），评测报告见 `data/experiments/translate_models/REPORT.md`。
|
||
- `subtitle-correction` 节点**不跟随**该默认值，有意保留
|
||
`Qwen/Qwen3.6-35B-A3B`：错听泛化实测新模型 0/4、旧模型 4/4。
|
||
- 通用转写模型为 `faster-whisper-large-v2`（2026-09 由 large-v3 切换），
|
||
依据见 [docs/decisions.md](./docs/decisions.md#whisper-large-v2-vs-large-v3-切换)。
|
||
- `llm-filter` 节点的 LLM 五类分类层**默认关闭**（`use_llm=0`）：
|
||
实测该层额外删除的 131 条中 56% 是真实对话，净收益为负；
|
||
现只跑确定性规则层，误删真对话从 73 条降为 0 条且无 LLM 调用。
|
||
详细依据见 [docs/decisions.md](./docs/decisions.md#llm-filter-的-llm-分类层默认关闭)。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
uv run pytest
|
||
```
|
||
|
||
测试资产与集成测试说明见 [docs/testing.md](./docs/testing.md)，
|
||
测试规则（TDD、真实数据要求）见 [AGENTS.md](./AGENTS.md#测试规则)。
|
||
|
||
## 与分布式版的关系
|
||
|
||
- 协议数据模型、工作流 DAG 数据化、调度拓扑执行保持不变。
|
||
- 已移除：子进程节点、节点 HTTP 协议、节点注册/实例管理、TTL 回收。
|
||
- 未来回退分布式时，只需为 `registry.invoke` 重新加上进程边界。
|
||
- 详见 [docs/architecture.md](./docs/architecture.md#单体化说明)。
|