vrsub/testdata/REALDATA_README.md

真实数据复现测试框架

本目录是"用真实数据复现问题并验证修复"的集成测试框架，不 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 时跳过；配置后 每次运行都会真实调用并断言"合入提示词规则后不再输出寒暄、专名不被直译"。

运行

# 只跑这两类真实数据集成测试
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。