cat-shark
078170c12a
- tests/realdata_contract.py：数据契约底座（SRT 解析/清洗、时间对齐量化 指标 align_report、幻觉词/专名判定、提示词规则拼接） - tests/test_integration_alignment.py：流水线产物 vs 硬字幕参考的时间对齐 （真实数据复现"字幕过早/过晚"，红→绿闭环） - tests/test_integration_prompt_rules.py：寒暄幻觉/专名提示词规则测试 - scripts/extract_reference_srt.py：从烧录字幕视频自动提取参考时间轴 - testdata/REALDATA_README.md + alignment/*.reference.srt：真实参考字幕 （视频素材较大，gitignore 不入库）
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# 真实数据复现测试框架
|
||
|
||
本目录是"用**真实数据**复现问题并验证修复"的集成测试框架，**不 mock 任何
|
||
模型/音频/LLM**。测试只读取你按约定放好的真实数据文件；数据缺失时整体跳过，
|
||
不影响 100% 覆盖率门禁（`pytest --cov-fail-under=100`）。
|
||
|
||
## 你要做什么
|
||
|
||
把真实数据放到 `vrsub/testdata/` 下的两个子目录即可，测试自动发现并执行。
|
||
不需要改任何测试代码。
|
||
|
||
### 1）时间对齐（复现"字幕时间与说话时间不吻合"）
|
||
|
||
```
|
||
vrsub/testdata/alignment/
|
||
├── <name>.mp4|wav|... # 真实视频/音频素材（有说话内容）
|
||
└── <name>.reference.srt # 人工校对时间轴的参考字幕（说话真实发生的时间）
|
||
```
|
||
|
||
- 参考字幕用**标准 SRT**（序号/时间轴/文本/空行），时间戳格式
|
||
`HH:MM:SS,mmm -> HH:MM:SS,mmm`。
|
||
- 测试会对同一素材用生产 whisper 节点分别以 `vad_filter=True`（当前生产配置）
|
||
与 `vad_filter=False` 转写，各自与参考字幕做**最近邻时间对齐**，输出：
|
||
- `平均绝对偏差`（整体同步精度）
|
||
- `偏差中位数`（系统性偏早/偏晚方向与幅度）
|
||
- `偏早/偏晚累计`（问题严重程度）
|
||
- 复现判定：平均绝对偏差 > 0.5s，或中位偏差超出 ±0.7s，即判"过早/过晚"被
|
||
稳定捕获（红）；修复后回落到容差内（绿）。
|
||
- 建议先放一段**约 30s~2min、说话清晰、有参考时间轴**的素材做第一轮复现。
|
||
|
||
### 2）幻觉词 / 专有名词提示词规则（复现"谢谢观看/晚安"与"芒果"）
|
||
|
||
```
|
||
vrsub/testdata/prompt_rules/
|
||
├── <name>.ja.srt # 真实视频的日文 ASR 输出字幕（标准 SRT）
|
||
└── <name>.expected.txt # 期望清单（每行一个关键词）
|
||
```
|
||
|
||
- `<name>.ja.srt`：真实 ASR 输出，最好**包含**"谢谢观看 / 晚安 / 感谢收看"
|
||
等收尾寒暄，以及"マンゴー（芒果）"等专名。
|
||
- `<name>.expected.txt`：目前测试内置了寒暄词表与专名名单，期望文件内容可先
|
||
为空或写备注；断言规则已内置在 `tests/realdata_contract.py` 的
|
||
`HALLUCINATION_TOKENS` / `PROPER_NOUNS_NO_TRANSLATE` 中，需要扩充时改那里
|
||
并同步更新 `.expected.txt`。
|
||
- 该测试调用**真实 LLM API**（读取 `.env` 的 `LLM_API_BASE` / `LLM_API_KEY` /
|
||
`LLM_MODEL`，与生产 llm-translate 同一接口）。未配置 Key 时跳过；配置后
|
||
每次运行都会真实调用并断言"合入提示词规则后不再输出寒暄、专名不被直译"。
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
# 只跑这两类真实数据集成测试
|
||
uv run pytest tests/test_integration_alignment.py tests/test_integration_prompt_rules.py -v
|
||
|
||
# 跑全部（含覆盖率门禁）
|
||
uv run pytest
|
||
```
|
||
|
||
测试发现数据后自动成为回归门禁：**修复前红、修复后绿**，防止问题回潮。
|
||
|
||
## 文件说明
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `tests/realdata_contract.py` | 数据契约：目录/素材发现、SRT 解析、时间对齐指标、幻觉词/专名判定、提示词规则拼接（纯函数） |
|
||
| `tests/test_integration_alignment.py` | 时间对齐集成测试（真实 whisper 节点 + 参考字幕，vad 开/关对照） |
|
||
| `tests/test_integration_prompt_rules.py` | 提示词规则集成测试（真实 LLM API + 动态规则，不 mock） |
|
||
|
||
## 后续修复落点（供实现对账）
|
||
|
||
1. **时间对齐**：`nodes/whisper.py` 的 VAD / 分块偏移 / word_timestamps 策略。
|
||
测试用统一指标量化，修一处跑一次即可看到偏差回落。
|
||
2. **提示词规则**：`nodes/llm.py` 的 `translate_lines` 按
|
||
`build_translation_system_prompt` 的契约动态拼接规则（检测关键词 → 注入
|
||
对应规则），生产 `llm-translate` 走同一套 prompt。 |