L2 歌词去重测试流程指南

本文档说明如何运行 L2 歌词召回测试、查看测试产物，并启动前端页面做人工复核。

0. 当前导入流程 2000 条 smoke 测试

先确认 .env 中有：

TARGET_TABLE_NAME_TMP=hk_songs_import_staging

第一次跑前，在目标库执行暂存表建表 SQL：

create_hk_songs_import_staging.sql

目标库已清空时，先跑第一阶段导入。这个阶段会边去重边导入：

• 判定为 new 的记录会按批次写入目标库。
• 判定为 merge 的记录不会插入新行，会写入暂存表和审核/记录清单。
• 判定为 review 的记录不会插入目标库，会进入暂存表等待业务人工审核。
• 所有 new / merge / review 结果都会写入 TARGET_TABLE_NAME_TMP。
• 输出 output/reports/review_decisions_*.csv，供复核页面展示 new / merge / review 全量结果。

0.1 第一阶段：跑 2000 条导入 smoke

uv run python import_hk_songs.py \
  --limit 2000 \
  --offset 0 \
  --batch-size 500 \
  --workers 8 \
  --load-existing-lyrics \
  --l2-recall topk \
  --l2-recall-top-k 20

如果想先不上传 OSS、只验证数据库写入和去重流程，可以加：

  --skip-oss

0.2 启动人工审核页面

uv run python serve_l2_dashboard.py --host 127.0.0.1 --port 8765

打开：

http://127.0.0.1:8765

页面会自动扫描 output/reports/review_decisions_*.csv。业务人员在页面里查看：

• 已经入库的 new 数据。
• 判定重复的 merge 样本。
• 需要人工审核的 review 样本。

对 review 样本，业务人员标注：

• 确认重复：不入库。
• 确认不重复：第二阶段入库。
• 待确认：暂不入库。

0.3 第二阶段：页面按钮入库审核通过项

业务人员完成所有 review 样本审核后，在页面点击：

入库审核通过

服务端会自动生成：

output/reports/review_import_approved_YYYYMMDD_HHMMSS.csv

并自动执行第二阶段导入：

uv run python import_hk_songs.py \
  --review-result-csv output/reports/review_import_approved_YYYYMMDD_HHMMSS.csv \
  --load-existing-lyrics

如果需要手动执行第二阶段，也可以使用上面的命令，把文件名替换成页面生成的实际 CSV。

0.4 smoke 后检查

第一阶段完成后，重点看日志里的：

插入: <new 入库数量>
L2合并命中=<merge 数量>
L2待审=<review 数量>
人工审核清单: output/reports/review_decisions_*.csv

第二阶段完成后，确认日志里的 插入 数量等于本次人工审核确认入库数量。

1. 运行 L2 测试脚本

在项目根目录执行：

RUN_L2_BENCHMARK=1 \
L2_BENCHMARK_LIMIT=20000000 \
L2_BENCHMARK_OFFSET=0 \
L2_BENCHMARK_LOAD_EXISTING=1 \
L2_BENCHMARK_EXISTING_LIMIT=50000 \
L2_BENCHMARK_DOWNLOAD_WORKERS=32 \
L2_BENCHMARK_TOPKS=20 \
L2_BENCHMARK_RETRIEVAL_TOP_N=10 \
python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s

这个测试只处理歌词：

• 从源库读取待导入歌词。
• 可选从目标测试库读取已有 lyrics_url 并下载歌词文件。
• 不下载或上传音频、封面、伴奏、曲谱等资源。
• 不写入数据库。
• 对不同 top_k 召回配置输出效率指标和人工复核材料。

2. 参数说明

参数	默认值	说明
RUN_L2_BENCHMARK	未开启	必须设为 1 才会运行联网 benchmark；否则 pytest 会跳过该测试。
L2_BENCHMARK_LIMIT	200	从源库查询多少条待评测歌曲。
L2_BENCHMARK_OFFSET	0	源库查询偏移量，用于分段抽样。
L2_BENCHMARK_LOAD_EXISTING	1	是否加载目标测试库已有歌词作为历史候选。设为 0 时只测试本批新歌之间的召回。
L2_BENCHMARK_EXISTING_LIMIT	500	从目标测试库加载多少条已有歌词候选；设为 0 表示不加 SQL LIMIT。
L2_BENCHMARK_TOPKS	20,50,100,200,500	要对比的 topK 召回候选规模，逗号分隔。
L2_BENCHMARK_RETRIEVAL_TOP_N	10	每条新歌在结果表中保留前多少个候选。前端当前按 top10 展示。
L2_BENCHMARK_DOWNLOAD_TIMEOUT	10	下载已有歌词文件的超时时间，单位秒。

3. 输出结果

测试完成后会在 output/reports/ 下生成：

l2_topk_benchmark_summary_YYYYMMDD_HHMMSS.csv
l2_topk_retrieval_top10_YYYYMMDD_HHMMSS.csv
l2_topk_duplicate_hits_YYYYMMDD_HHMMSS.csv
l2_topk_benchmark_assets_YYYYMMDD_HHMMSS/lyrics/

各文件含义：

文件	说明
l2_topk_benchmark_summary_*.csv	每个 topK 的效率汇总，包括耗时、吞吐、平均召回候选数、duplicate/review/new/hit 数量。
l2_topk_retrieval_top10_*.csv	每条新歌的 topN 召回候选明细，包含新歌和候选的歌名、歌手、词曲作者、歌词文件路径、相似度指标、判定原因。
l2_topk_duplicate_hits_*.csv	只保留命中 duplicate 或 review 的样本，适合人工重点复核。
l2_topk_benchmark_assets_*/lyrics/	新歌和候选歌词正文文件。CSV 中只保留路径，不直接塞歌词全文。

l2_topk_retrieval_top10_*.csv 还包含：

• l1_metadata_match：新歌与候选按 L1 元数据规则（歌名、作词人、作曲人）是否命中。
• l1_l2_conflict：L1 与 L2 结论是否冲突。比如 L2 判新歌但召回候选中有 L1 命中，或 L2 判重复但命中候选 L1 未命中。

4. 启动前端页面

运行：

python serve_l2_dashboard.py --host 127.0.0.1 --port 8765

然后打开：

http://127.0.0.1:8765

前端会自动扫描 output/reports/ 下成套的 benchmark 结果文件。

5. 前端使用方式

页面主要功能：

• 选择不同测试 run。
• 切换不同 top_k。
• 查看效率指标：耗时、吞吐、平均召回候选数、duplicate/review/new/hit 数量。
• 在“召回样本”中查看每条新歌的 topN 候选。
• 在“命中样本”中只查看 duplicate / review 样本。
• 左右并排查看新歌歌词和候选歌词。
• 高亮 L1/L2 冲突样本。
• 对样本做人工标注：确认重复、确认不重复、待确认。
• 点击“导出标注”导出当前 run、topK 和当前视图下的人工标注 CSV。
• 按歌名、歌手、ID 搜索样本。

如果刚跑完新测试但页面没有更新，点击页面右上角“刷新”。

6. 推荐测试方式

先用小样本确认流程：

RUN_L2_BENCHMARK=1 \
L2_BENCHMARK_LIMIT=20 \
L2_BENCHMARK_EXISTING_LIMIT=50 \
L2_BENCHMARK_TOPKS=20,100 \
python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s

再扩大样本：

RUN_L2_BENCHMARK=1 \
L2_BENCHMARK_LIMIT=1000 \
L2_BENCHMARK_EXISTING_LIMIT=5000 \
L2_BENCHMARK_TOPKS=20,50,100,200,500 \
python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s

如果目标库已有歌词很多，L2_BENCHMARK_EXISTING_LIMIT=0 会加载全部候选，运行时间和歌词下载时间会明显增加。

7. 普通单元测试

运行全部普通测试：

python -m pytest test_dedup.py -q

默认情况下，L2 benchmark 会被跳过，不会联网。