Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 5e373f5b 5e373f5b1bfcec928a9f91714da75c31da25685e by cnb.bofCdSsphPA
Options

Capture the current ACR delivery state so the next engineer can resume immediately 

Constraint: Keep the live song-centric mainline and selected20 regression baseline aligned in docs and artifacts
Rejected: Deferring README/handoff consolidation | Would force the next session to reconstruct context again
Confidence: high
Scope-risk: narrow
Directive: Update CHANGELOG, roadmap checklist, and handoff docs together whenever onboarding or delivery facts change
Tested: /usr/local/miniconda3/bin/python /workspace/scripts/check_markdown_links.py --root /workspace/docs; selected20 baseline vs fresh report equality check; git diff --check; architect review APPROVED
Not-tested: No new runtime pipeline execution in this commit; relies on already-generated selected20 artifacts
1 parent e7f2029f
Expand all
Inline Side-by-side
Showing 14 changed files with 953 additions and 12 deletions
# ACR Workspace Handoff / 快速接手入口
> 这份 README 面向新接手的开发人员：先告诉你**项目现在是什么、先看什么、先跑什么**，避免从零重新梳理。
---
## 1. 这个仓库现在在做什么
当前主线是一个 **song-centric 音乐 ACR 系统**，重点有两条：
1. **live PostgreSQL 主链**
- 把歌曲目录转换为 `song -> asset -> window -> fingerprint / embedding`
- 落到当前 4 表 schema：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
2. **selected20 小样本实战评测链**
- 用 20 首歌的专题数据评估当前方案在真实 query 条件下的 `song_id` 命中率
- 当前专题重点关注：
- `type_7`
- `type_16`
一句话理解：
> **数据库宿主链已经打通，当前要在不破坏主链的前提下继续优化 semantic lane，并用 selected20 做回归基线。**
---
## 2. 新同学先看哪些文档
建议按这个顺序读：
1. [docs/start-here.md](./docs/start-here.md)
2. [docs/delivery-onepager.md](./docs/delivery-onepager.md)
3. [docs/session-handoff.md](./docs/session-handoff.md)
4. [docs/song-ingest-query-delivery.md](./docs/song-ingest-query-delivery.md)
5. [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
6. [docs/selected20_songid_eval.md](./docs/selected20_songid_eval.md)
7. [docs/postgresql-data-model.md](./docs/postgresql-data-model.md)
8. [docs/postgres_db_schema_samples.md](./docs/postgres_db_schema_samples.md)
9. [docs/CHANGELOG.md](./docs/CHANGELOG.md)
如果只想快速进入状态，至少看这 4 份：
- [docs/start-here.md](./docs/start-here.md)
- [docs/session-handoff.md](./docs/session-handoff.md)
- [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
- [docs/selected20_songid_eval.md](./docs/selected20_songid_eval.md)
---
## 3. 先跑什么
### 3.1 live PostgreSQL 主链验证
```bash
cd /workspace
/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_songcentric_test \
--input-root acr-engine/data/songcentric_builder_smoke \
--output-dir acr-engine/data/pgvector_eval/music20
```
或：
```bash
acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
```
### 3.2 selected20 回归评测
```bash
cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/evaluate_selected20_songid_retrieval.py \
--downloads-dir /root/hikoon_song_files/output/selected_20_songs/downloads \
--reference-type 11 \
--query-types 1 7 12 16 \
--duration 8.0 \
--topk 3 \
--exact-weight 0.6 \
--semantic-weight 0.4 \
--output-json /workspace/acr-engine/data/local_eval/selected20_songid_eval_report.json \
--output-md /workspace/docs/selected20_songid_eval.md
```
---
## 4. 当前你需要知道的核心事实
### 主链事实
- 4 表 song-centric schema 已作为当前默认口径
- exact lane 已接入 `chromaprint_matcher`
- semantic lane 已接入 `mert-v1-95m`
- 当前 live 主链已有 fresh evidence
### selected20 事实
- baseline 报告已存在
- fresh 重跑报告已存在
- baseline 与 fresh 结果一致，当前专题已可作为回归基线
当前 overall：
| lane | count | top1 | top3 |
|---|---:|---:|---:|
| exact | 123 | 0.6016 | 0.8130 |
| semantic | 123 | 0.4715 | 0.6016 |
| fused | 123 | 0.6341 | 0.8537 |
当前关键结论：
- `type_1` 不是主要问题
- `type_12` 表现已经较好
- `type_7 / type_16` 仍是主要短板
### 当前 blocker
- MuQ 还没接通
- 当前已知 blocker：
- `RuntimeError: operator torchvision::nms does not exist`
---
## 5. 建议下一步怎么做
优先顺序：
1. **守住当前主链与 selected20 基线**
2. **先整理 hard-case 白名单**
3. **再解锁 MuQ runtime**
4. **最后把有效策略回灌到 PostgreSQL 在线主链**
详细 roadmap 和 checklist 见：
- [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
---
## 6. 代码和文档主要位置
- 主代码：
- [acr-engine/](./acr-engine/)
- 核心文档：
- [docs/](./docs/)
- 运行脚本：
- [acr-engine/scripts/](./acr-engine/scripts/)
- 会话/交付状态：
- [.omx/](./.omx/)
---
## 7. 如果你是新接手开发，最短路径
只做这几步：
1. 读 [docs/start-here.md](./docs/start-here.md)
2. 读 [docs/session-handoff.md](./docs/session-handoff.md)
3. 读 [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
4. 跑一次主链验证
5. 跑一次 selected20 回归
这样基本就能在 10~20 分钟内进入当前上下文。
This diff could not be displayed because it is too large.
This diff could not be displayed because it is too large.
# Selected 20 Songs 实战检索评测
- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
- reference：`type_11`
- queries：`type_1, type_7, type_12, type_16`
- 当前方案：`chromaprint_matcher + mert-v1-95m`
- 语义截断时长：`8.0s`
- reference 文件数：`24`
- query 文件数：`123`
## 1. 总体结果
| lane | count | top1 | top3 |
|---|---:|---:|---:|
| exact | 123 | 0.6016 | 0.8130 |
| semantic | 123 | 0.4715 | 0.6016 |
| fused | 123 | 0.6341 | 0.8537 |
## 2. 分 query type 结果
| query_type | lane | count | top1 | top3 |
|---|---|---:|---:|---:|
| type_1 | exact | 21 | 1.0000 | 1.0000 |
| type_1 | semantic | 21 | 1.0000 | 1.0000 |
| type_1 | fused | 21 | 1.0000 | 1.0000 |
| type_7 | exact | 41 | 0.4146 | 0.7073 |
| type_7 | semantic | 41 | 0.1707 | 0.3902 |
| type_7 | fused | 41 | 0.4390 | 0.7561 |
| type_12 | exact | 23 | 0.8261 | 0.9130 |
| type_12 | semantic | 23 | 1.0000 | 1.0000 |
| type_12 | fused | 23 | 0.9130 | 1.0000 |
| type_16 | exact | 38 | 0.4474 | 0.7632 |
| type_16 | semantic | 38 | 0.1842 | 0.3684 |
| type_16 | fused | 38 | 0.4737 | 0.7895 |
## 3. 失败样例（fused rank != 1）
- `type_7` / true=`572816` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/572816/type_7/三军令（副歌版）.mp3` / top1=`614397`
- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版2）-吉鹏泽.wav` / top1=`614397`
- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版3）-吉鹏泽.wav` / top1=`614397`
- `type_7` / true=`643015` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/643015/type_7/置念 抖音推广音频.wav` / top1=`637559`
- `type_7` / true=`656394` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/656394/type_7/把你宠坏-推广片段.wav` / top1=`614740`
- `type_7` / true=`657848` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/657848/type_7/小神仙 主歌剪-1.mp3` / top1=`614397`
- `type_7` / true=`659300` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/659300/type_7/推广片段2.WAV` / top1=`614397`
- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段1.1x.wav` / top1=`614397`
- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段_2.wav` / top1=`614397`
- `type_7` / true=`675406` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675406/type_7/2.mp3` / top1=`614397`
## 4. 结论
- `exact` 代表当前指纹链路单独表现。
- `semantic` 代表当前 MERT 单独表现。
- `fused` 代表当前版权保护场景里更接近实战的合并结果。
# Changelog
## 2026-06-04
- 继续收紧 `docs/README.md` 的默认接手路径表达：除了保留 `delivery-onepager.md` 在阅读顺序中的位置外，又显式增加 `start-here -> delivery-onepager -> session-handoff -> song-ingest-query-delivery` 的主路径说明，避免入口顺序仍被误读。
- 新增 `docs/delivery-onepager.md`，把当前 PostgreSQL 主链、selected20 基线、最短启动命令、fresh evidence 与下一步动作再压缩成一页交付摘要，方便外部同事或新 session 先快速接手。
- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md`，把 one-pager 接入默认阅读顺序，形成 “one-pager -> handoff -> runbook” 的精炼阅读路径。
## 2026-06-04
- 新增 `docs/song-ingest-query-delivery.md`，把当前仓库里“歌曲目录 -> manifest -> window/features -> PostgreSQL import -> selected20 查询评测 -> 交付产物”的完整链路、操作命令、产物位置、验证点收敛成一份端到端操作手册。
- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md`，把这份端到端手册接入默认阅读路径，方便新 session 或交付接手时直接定位完整链路说明。
## 2026-06-04
- 新增仓库根 `README.md`，作为新接手开发人员的快速入口：集中说明“项目当前在做什么、先看哪些核心文档、先跑哪些命令、当前已知事实与 blocker、下一步建议顺序”，并把核心文档链路全部串起来。
- 根据后续 architect 复核继续修正 `docs/start-here.md` 的入口计数错误：当前实际列出 `8` 份文档，因此把“只读这 7 份文档”更正为“只读这 8 份文档”，避免交付入口文案继续误导。
- 更新 `docs/research-delivery-roadmap.md` 的 checklist 表述，把“docs 已形成可唤起交付链路”明确扩展到 `root README + docs README + handoff/roadmap/selected20` 整体入口链。
- 根据 architect 复核修正 `docs/start-here.md` 的入口计数错误：文中实际列出 `7` 份文档，因此把“只读这 6 份文档”更正为“只读这 7 份文档”，避免交付入口文案与真实列表不一致。
- 在 `docs/research-delivery-roadmap.md` 增加“当前进度快照（2026-06-04）”，把 Phase A~E 当前状态显式化，避免后续 session 只看到 roadmap 而不知道已经推进到哪里。
- 更新 roadmap checklist：把“docs 已形成可唤起交付链路”和 selected20 的固定入口 / `json+markdown` 输出 / 结果解读文档化标记为已完成，同时保留 hard-case 白名单、MuQ 接入、在线主链回灌为后续待办。
- 新增 [research-delivery-roadmap.md](./research-delivery-roadmap.md)，把当前研究成果、后续 roadmap、阶段 checklist 和建议任务包集中固化成一份可直接唤起的交付文档。
- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md` 的入口链路，加入 `research-delivery-roadmap.md` 与 `selected20_songid_eval.md`，让后续 session 能从“当前成果 + 后续任务构想”直接接续。
- 在 `docs/session-handoff.md` 补充 `selected20_songid_eval_report_fresh.json` 与 fresh 重跑一致性的事实，明确 selected20 当前已具备可重复的小样本回归基线属性。
- 基于现有 `.omx` 记录与产物，补齐 `selected20` 实战评测交付：确认 `acr-engine/data/local_eval/selected20_songid_eval_report.json` 与 `docs/selected20_songid_eval.md` 对应同一轮 20 首歌 song-level 评测，口径为 `type_11` 作为 reference、`type_1/7/12/16` 作为 query、`chromaprint_matcher + mert-v1-95m` 双 lane 融合。
- 固化 `selected20` 当前实测结论：总计 `123` 条 query，`fused top1=0.6341 / top3=0.8537`，优于单独 `exact top1=0.6016 / top3=0.8130` 与 `semantic top1=0.4715 / top3=0.6016`；说明当前版权保护小样本场景下，融合优于单 lane。
- 固化 `selected20` 的分类型判断：`type_1` 已满分；`type_12` 由 MERT 单 lane 最强（`top1=1.0`），但融合后更稳；当前主要短板仍集中在 `type_7` 与 `type_16`，其中 `type_7 fused top1=0.4390 / top3=0.7561`、`type_16 fused top1=0.4737 / top3=0.7895`。
- 补充交付物说明：`docs/selected20_songid_eval_repro.md` 已给出复现命令与输出物位置，当前 20 首歌专题可作为后续接入 MuQ 或迁移 PostgreSQL song-centric 主链前的小样本回归基线。
## 2026-06-04
- 继续收敛文档到当前 live 主链口径：补齐 `feature_fact.object_id -> audio_object(window)`、`window.parent_object_id -> asset`、`feature_fact.song_id -> media_entity(song)` 的绑定说明，并新增 manifest/SQL 双样例，专门回答 Phase-1 开源模型集合应该如何落地存储以及 feature 与 audio object 如何关联。
- 修正 `docs/session-handoff.md` 中关于 semantic lane 的旧状态残留，统一到当前真实事实：live 默认已落 `chromaprint_matcher + mert-v1-95m`，MuQ 仍是下一阶段 challenger。
- 继续补充可复核的 live 样例：把 `feature_id = 34 -> window_id = 22 -> asset_id = 20 -> song_beta` 的真实 PostgreSQL 回溯结果写入 handoff 与 schema sample 文档，方便下次 session 直接人工复核绑定链路。
......
......@@ -9,10 +9,20 @@
新同学接手顺序：
1. [start-here.md](./start-here.md)
2. [session-handoff.md](./session-handoff.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
5. [CHANGELOG.md](./CHANGELOG.md)
2. [delivery-onepager.md](./delivery-onepager.md)
3. [session-handoff.md](./session-handoff.md)
4. [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
5. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
6. [selected20_songid_eval.md](./selected20_songid_eval.md)
7. [postgresql-data-model.md](./postgresql-data-model.md)
8. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
9. [CHANGELOG.md](./CHANGELOG.md)
推荐把前 4 份当作默认接手主路径：
```text
start-here -> delivery-onepager -> session-handoff -> song-ingest-query-delivery
```
---
......@@ -65,14 +75,18 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
- `semantic_runtime_available = true`
- `semantic_runtime_ready_count = 5`
- `semantic_fallback_count = 0`
- `import_counts.feature_fact = 29
- `import_counts.feature_fact = 34`
---
## 4. 当前保留文档分别解决什么
- [start-here.md](./start-here.md)：新同学 10 分钟接手入口
- [delivery-onepager.md](./delivery-onepager.md)：对外/跨团队交付时先发这一页
- [session-handoff.md](./session-handoff.md)：下次启动从哪里继续
- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)：歌曲从目录入库到查询/评测/交付的完整操作手册
- [research-delivery-roadmap.md](./research-delivery-roadmap.md)：当前研究交付、roadmap、checklist
- [selected20_songid_eval.md](./selected20_songid_eval.md)：20 首专题评测摘要
- [postgresql-data-model.md](./postgresql-data-model.md)：表设计、字段语义、feature 与 audio_object 的绑定关系、Phase-1 模型落库口径
- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)：DDL、manifest/SQL 样例、典型查询链路、真实存储示例
- [CHANGELOG.md](./CHANGELOG.md)：变更历史
......
# ACR 交付一页纸
> 给新接手同事的最短摘要：先看这页，再决定要不要展开到完整 runbook。
---
## 1. 现在已经交付了什么
当前已经有两条可用主线：
1. **PostgreSQL song-centric 主链**
- 歌曲目录 -> manifest -> window -> fingerprint/embedding -> PostgreSQL
2. **selected20 小样本评测主线**
- 20 首歌专题 -> exact / semantic / fused song-level 命中率评测
一句话：
> **数据库宿主链已经打通，20 首歌回归基线已经固定；下一步重点不是重做方案，而是在当前基线上继续补 semantic challenger。**
---
## 2. 当前默认模型
逻辑语义：
```text
song -> asset -> window -> fingerprint / embedding
```
物理落表：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
---
## 3. 最短启动命令
```bash
cd /workspace
/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_songcentric_test \
--input-root acr-engine/data/songcentric_builder_smoke \
--output-dir acr-engine/data/pgvector_eval/music20
```
---
## 4. 当前 fresh evidence
主链当前结果：
- `song_count = 2`
- `asset_count = 2`
- `window_count = 5`
- `matcher_fingerprint_count = 5`
- `semantic_runtime_ready_count = 5`
- `import_counts = media_entity:9 / audio_object:22 / feature_fact:34 / set_membership:9`
说明：
- exact lane 已接 `chromaprint_matcher`
- semantic lane 已接 `mert-v1-95m`
- 当前 5 个 window 没走 fallback
---
## 5. selected20 当前结论
- query 总数：`123`
- exact：`top1=0.6016 / top3=0.8130`
- semantic：`top1=0.4715 / top3=0.6016`
- fused：`top1=0.6341 / top3=0.8537`
关键判断：
- `type_1` 已打满
- `type_12` 很强
- 主要短板仍是 `type_7 / type_16`
---
## 6. 你应该先看哪份文档
### 如果你只想快速接手
1. [start-here.md](./start-here.md)
2. [delivery-onepager.md](./delivery-onepager.md)
3. [session-handoff.md](./session-handoff.md)
### 如果你要看完整操作链路
- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
### 如果你要看专题评测
- [selected20_songid_eval.md](./selected20_songid_eval.md)
- [selected20_songid_eval_repro.md](./selected20_songid_eval_repro.md)
---
## 7. 现在最重要的下一步
1. 保住当前 4 表主链不回退
2. 接入 MuQ challenger
3. 每次变更后复跑 selected20
4. 重点盯 `type_7 / type_16`
---
## 8. 相关文档
- [README.md](./README.md)
- [start-here.md](./start-here.md)
- [session-handoff.md](./session-handoff.md)
- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
- [research-delivery-roadmap.md](./research-delivery-roadmap.md)
- [CHANGELOG.md](./CHANGELOG.md)
# Research Delivery / 当前研究交付与 Roadmap
> 目标：把当前已经验证过的研究成果、下一阶段待办、以及可执行 checklist 固化成一份可直接唤起的交付文档。
---
## 1. 当前交付了什么
当前已经形成两条可复用主线：
1. **song-centric + 4 表 PostgreSQL 主链**
- 完整操作手册：[song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
2. **selected20（20 首歌）文件级小样本实战评测主线**
一句话总结：
> **数据库宿主链已经打通，20 首专题评测基线也已经建立；下一阶段不是重新争论总方案，而是在当前基线上做 challenger 扩展与 hard-case 改善。**
---
## 2. 当前研究成果摘要
### 2.1 主数据 / 宿主链成果
当前默认物理模型：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
当前默认逻辑语义：
```text
song -> asset -> window -> fingerprint / embedding
```
已真实验证：
- live PostgreSQL schema 可建表
- 真实目录 -> manifest -> import 可跑通
- `windows[].features[]` 可直接导入 `feature_fact`
- exact lane 已接 `chromaprint_matcher`
- semantic lane 已接 `mert-v1-95m`
- 当前主链在 live PostgreSQL 上已有 fresh evidence
### 2.2 selected20（20 首歌）专题成果
专题数据目录：
- `/root/hikoon_song_files/output/selected_20_songs/downloads`
当前专题方案：
- exact：`chromaprint_matcher`
- semantic：`mert-v1-95m`
- fused：`0.6 * exact + 0.4 * semantic`
当前 fresh 结果：
| lane | count | top1 | top3 |
|---|---:|---:|---:|
| exact | 123 | 0.6016 | 0.8130 |
| semantic | 123 | 0.4715 | 0.6016 |
| fused | 123 | 0.6341 | 0.8537 |
分类型结论：
| query_type | count | 当前判断 |
|---|---:|---|
| `type_1` | 21 | 已打满，当前不是主要矛盾 |
| `type_7` | 41 | 主要短板之一，混淆明显 |
| `type_12` | 23 | 当前表现很好，semantic 单 lane 已打满 |
| `type_16` | 38 | 另一主要短板，仍需重点优化 |
一句话判断：
> **当前融合结果优于单独 semantic，也略优于单独 exact；实战瓶颈主要在 `type_7 / type_16`。**
---
## 3. 当前 blocker
### 3.1 语义 challenger blocker
MuQ 当前还没接入成功。
已确认事实：
- 候选：`OpenMuQ/MuQ-large-msd-iter`
- `muq` 包已安装
- 当前 host 上 `import muq` 仍被 `RuntimeError: operator torchvision::nms does not exist` 阻塞
所以当前 blocker 不是“还没想到做什么”，而是：
> **MERT baseline 已可用，但 MuQ challenger 受 `torchvision` 兼容问题阻塞。**
### 3.2 效果 blocker
从 selected20 看，当前真正的效果短板不是：
- `type_1`
- `type_12`
而是：
- `type_7`
- `type_16`
这意味着下一阶段不能只盯 overall，必须盯 hard-case 的分类型提升。
---
## 4. 后续 Roadmap（建议版）
### 当前进度快照（2026-06-04）
| Phase | 状态 | 当前判断 |
|---|---|---|
| Phase A：冻结当前基线 | 进行中 | 主链与 selected20 基线都已形成，fresh 重跑一致性也已确认 |
| Phase B：接入 MuQ challenger | 未开始 | 仍被 `torchvision::nms` runtime blocker 卡住 |
| Phase C：selected20 回归闸门 | 进行中 | 已有脚本、JSON、Markdown 摘要，但还未完全制度化成固定门禁 |
| Phase D：专题策略回灌在线主链 | 未开始 | 还没有把 selected20 的 hard-case 分析映射回 PostgreSQL 查询侧 |
| Phase E：更大规模评测与工程化 | 未开始 | 当前仍以 selected20 为核心小样本基线 |
### Phase A：冻结当前基线
目标：
- 守住当前 song-centric 4 表主链
- 守住 selected20 小样本回归基线
完成标准：
- `run_songcentric_directory_pipeline_live.py` 继续稳定可跑
- `selected20_songid_eval_report.json` 继续作为对照基线
### Phase B：接入 MuQ challenger
目标：
- 在不破坏现有 MERT baseline 的前提下，加一条 MuQ semantic challenger lane
完成标准：
- `import muq` / `from muq import MuQ` 可成功
- runner/评测脚本能产出 MuQ embedding
- PostgreSQL 或文件级评测里能看到独立 MuQ 指标
关键评估：
- MuQ 单 lane 是否优于 MERT
- MuQ + exact 的 fused 是否改善 `type_7 / type_16`
### Phase C：以 selected20 作为回归闸门
目标：
- 把 selected20 固化成每次 encoder / fusion 变更后的回归集
完成标准：
- 每次变更后都能直接复跑 selected20
- 报告中必须比较：
- overall
- per-type
- 失败样例
### Phase D：把小样本专题映射回在线主链
目标：
- 把 selected20 的有效策略回灌到 PostgreSQL / song-centric 主链
- 交付/接手时优先参考 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
完成标准：
- `feature_fact` 中能区分不同 semantic challenger
- 可以对同一批 query 比较 exact / MERT / MuQ / fused
### Phase E：进入更大规模评测与工程化
目标：
- 从 selected20 扩展到更大的 reference / query 集
- 明确生产级回归、巡检、落库与索引策略
完成标准：
- 有更大评测集
- 有固定报表结构
- 有稳定的主链/专题双回归机制
---
## 5. Checklist（下一阶段执行清单）
### 5.1 基线保护 checklist
- [x] 4 表 song-centric schema 已作为当前默认口径
- [x] `chromaprint_matcher` 已接入 exact lane
- [x] `mert-v1-95m` 已接入 semantic baseline
- [x] selected20 已形成基线报告
- [x] selected20 fresh 重跑结果与当前基线一致
- [x] docs 已形成可唤起交付链路（root README / docs README / start-here / handoff / roadmap / selected20）
- [ ] 把 selected20 失败样例沉淀成 hard-case 白名单
### 5.2 MuQ 接入 checklist
- [ ] 审计 `torch / torchvision / muq` 兼容矩阵
- [ ] 解决 `torchvision::nms does not exist`
- [ ] 在本机成功 `from muq import MuQ`
- [ ] 在评测脚本中增加 MuQ lane
- [ ] 产出 `MERT vs MuQ vs fused` 对比报告
### 5.3 效果优化 checklist
- [ ] 按 `type_7 / type_16` 汇总失败歌曲对
- [ ] 统计最常见误判 top1 歌曲
- [ ] 评估 fusion 权重是否仍应固定在 `0.6 / 0.4`
- [ ] 尝试基于 hard-case 调整融合策略
- [ ] 验证优化是否真正改善 `type_7 / type_16`
### 5.4 工程化 checklist
- [x] 让 selected20 评测成为固定入口命令
- [x] 报告输出统一到 `json + markdown`
- [x] 在 docs 里固定“怎么读结果 / 怎么继续”
- [ ] 后续如果切 online path，保留该文件级评测作为快速回归集
---
## 6. 推荐下次启动顺序
1. 先看 [session-handoff.md](./session-handoff.md)
2. 再看 [selected20_songid_eval.md](./selected20_songid_eval.md)
3. 再看本文件的 roadmap + checklist
4. 决定是走：
- **MuQ 接入线**
- **selected20 hard-case 优化线**
- **PostgreSQL 在线回灌线**
### 当前建议的下一步（按收益排序）
1. **先做 hard-case 白名单**
- 把 `type_7 / type_16` 的失败样例整理成固定榜单
2. **再做 MuQ runtime 解锁**
- 先解决 `torchvision::nms`，再做 challenger 对比
3. **最后做主链回灌**
- 把 selected20 上确认有效的策略映射回 PostgreSQL 查询路径
---
## 7. 当前建议任务构想
### 任务包 A：MuQ 解锁
目标：
- 打通 MuQ runtime
产出：
- 环境兼容记录
- 可运行 MuQ smoke
- 可落盘 MuQ embedding
### 任务包 B：selected20 hard-case 分析
目标：
- 只盯 `type_7 / type_16`
产出：
- 失败歌曲对榜单
- 常见误判榜单
- 是否需要调整 fusion 的结论
### 任务包 C：回归制度化
目标：
- 让 selected20 成为固定回归门禁
产出：
- 固定命令
- 固定报告路径
- 固定结果解读模板
### 任务包 D：在线主链映射
目标：
- 把有效的专题结论映射回 PostgreSQL 主链
产出：
- 主链中的 challenger 标识
- 可对比的落库数据
- 在线/离线一致的评估视图
---
## 一句话交付结论
> 当前最值得保护的研究资产不是“某个临时实验数字”，而是 **已经跑通的 4 表 song-centric 主链 + 已经成型的 selected20 小样本回归基线 + 明确的 MuQ / hard-case 后续路线图**。
# Selected 20 Songs 实战检索评测
> 完整入库/查询主链操作手册见 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)；本页只负责 `selected20` 文件级实战评测摘要。
- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
- reference：`type_11`
- queries：`type_1, type_7, type_12, type_16`
- 当前方案：`chromaprint_matcher + mert-v1-95m`
- 语义截断时长：`8.0s`
- reference 文件数：`24`
- query 文件数：`123`
## 1. 总体结果
| lane | count | top1 | top3 |
|---|---:|---:|---:|
| exact | 123 | 0.6016 | 0.8130 |
| semantic | 123 | 0.4715 | 0.6016 |
| fused | 123 | 0.6341 | 0.8537 |
## 2. 分 query type 结果
| query_type | lane | count | top1 | top3 |
|---|---|---:|---:|---:|
| type_1 | exact | 21 | 1.0000 | 1.0000 |
| type_1 | semantic | 21 | 1.0000 | 1.0000 |
| type_1 | fused | 21 | 1.0000 | 1.0000 |
| type_7 | exact | 41 | 0.4146 | 0.7073 |
| type_7 | semantic | 41 | 0.1707 | 0.3902 |
| type_7 | fused | 41 | 0.4390 | 0.7561 |
| type_12 | exact | 23 | 0.8261 | 0.9130 |
| type_12 | semantic | 23 | 1.0000 | 1.0000 |
| type_12 | fused | 23 | 0.9130 | 1.0000 |
| type_16 | exact | 38 | 0.4474 | 0.7632 |
| type_16 | semantic | 38 | 0.1842 | 0.3684 |
| type_16 | fused | 38 | 0.4737 | 0.7895 |
## 3. 失败样例（fused rank != 1）
- `type_7` / true=`572816` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/572816/type_7/三军令（副歌版）.mp3` / top1=`614397`
- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版2）-吉鹏泽.wav` / top1=`614397`
- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版3）-吉鹏泽.wav` / top1=`614397`
- `type_7` / true=`643015` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/643015/type_7/置念 抖音推广音频.wav` / top1=`637559`
- `type_7` / true=`656394` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/656394/type_7/把你宠坏-推广片段.wav` / top1=`614740`
- `type_7` / true=`657848` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/657848/type_7/小神仙 主歌剪-1.mp3` / top1=`614397`
- `type_7` / true=`659300` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/659300/type_7/推广片段2.WAV` / top1=`614397`
- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段1.1x.wav` / top1=`614397`
- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段_2.wav` / top1=`614397`
- `type_7` / true=`675406` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675406/type_7/2.mp3` / top1=`614397`
## 4. 结论
- `exact` 代表当前指纹链路单独表现。
- `semantic` 代表当前 MERT 单独表现。
- `fused` 代表当前版权保护场景里更接近实战的合并结果。
# Selected20 SongID 检索评测复现手册
> 这份文档只覆盖 `selected20` 文件级回归评测；完整数据库主链与“歌曲入库 -> 查询 -> 交付”见 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)。
## 1. 目标
验证目录：
- `/root/hikoon_song_files/output/selected_20_songs/downloads`
在当前方案下：
- `reference = type_11`
- `query = type_1 / type_7 / type_12 / type_16`
- 目录名即 `song_id`
检查实战里是否能够正确识别回对应 `song_id`。
---
## 2. 当前方案口径
本专题默认评测的方案是：
- exact lane：`chromaprint_matcher`
- semantic lane：`mert-v1-95m`
- fused：`0.6 * exact + 0.4 * semantic`
说明：
- `type_11` 视为无损 reference
- `type_1/7/12/16` 视为 query
- 最终评测目标是 song-level `song_id` 命中率
---
## 3. 目录结构假设
每首歌结构类似：
```text
<downloads>/<song_id>/type_1/*
<downloads>/<song_id>/type_7/*
<downloads>/<song_id>/type_11/*
<downloads>/<song_id>/type_12/*
<downloads>/<song_id>/type_16/*
```
其中：
- 目录名 `<song_id>` 就是 ground truth
- `type_11` 至少 1 个文件
- query type 可以多文件
---
## 4. 复现命令
```bash
cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/evaluate_selected20_songid_retrieval.py \
--downloads-dir /root/hikoon_song_files/output/selected_20_songs/downloads \
--reference-type 11 \
--query-types 1 7 12 16 \
--duration 8.0 \
--topk 3 \
--exact-weight 0.6 \
--semantic-weight 0.4 \
--output-json /workspace/acr-engine/data/local_eval/selected20_songid_eval_report.json \
--output-md /workspace/docs/selected20_songid_eval.md
```
---
## 5. 输出物
### JSON 报告
- `acr-engine/data/local_eval/selected20_songid_eval_report.json`
包含：
- overall top1/top3
- per-type top1/top3
- 每条 query 的 exact / semantic / fused 排名
- 失败样例
### Markdown 摘要
- `docs/selected20_songid_eval.md`
适合给研发、产品、算法同学直接阅读。
---
## 6. 评测逻辑
### 6.1 reference 构建
- 遍历每个 `song_id`
- 读取 `type_11` 文件作为 reference
- 同时建立：
- `chromaprint_matcher` 指纹索引
- `mert-v1-95m` song embedding
### 6.2 query 评估
对每个 query 文件：
1. 走 exact：`chromaprint_matcher.match(...)`
2. 走 semantic：MERT embedding 和 reference song embedding 相似度
3. 融合：
```text
fused_score = 0.6 * exact_norm + 0.4 * semantic_norm
```
4. 输出 topk 候选
5. 检查 true `song_id` 的 rank
### 6.3 指标
- `top1`：正确 song_id 是否排第 1
- `top3`：正确 song_id 是否排前 3
---
## 7. 如何看结果
优先看：
1. overall
2. per query type
3. failed_fused_examples
建议解释顺序：
- exact 单独效果
- semantic 单独效果
- fused 是否优于单 lane
- 哪些 type 是当前主要短板
---
## 8. 后续扩展
如果后续接入 MuQ：
- 可以在该脚本里增加 `muq` lane
- 输出：`exact / mert / muq / fused`
- 比较 `type_7 / type_12 / type_16` 是否改善
如果后续切到 PostgreSQL：
- 可以把当前文件级 query/reference 逻辑迁移为 `song -> asset -> window -> feature_fact`
- 但这个专题脚本仍然保留，作为**小样本回归评测**基线
......@@ -2,6 +2,8 @@
> 目标：让下次启动的新 session 在 **3~10 分钟内** 知道从哪里开始。
快速对外转交时，先发： [delivery-onepager.md](./delivery-onepager.md)
---
## 1. 下次启动先做什么
......@@ -140,9 +142,11 @@ flowchart TD
1. [README.md](./README.md)
2. [start-here.md](./start-here.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
5. [CHANGELOG.md](./CHANGELOG.md)
3. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
4. [selected20_songid_eval.md](./selected20_songid_eval.md)
5. [postgresql-data-model.md](./postgresql-data-model.md)
6. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
7. [CHANGELOG.md](./CHANGELOG.md)
关键代码：
- `acr-engine/sql/acr_pg_schema_songcentric_v1.sql`
......@@ -152,6 +156,9 @@ flowchart TD
- `acr-engine/scripts/import_songcentric_manifest_live.py`
- `acr-engine/scripts/start_songcentric_shortest_path.sh`
如果要完整看“歌曲怎么入库、怎么查询/评测、交付时要带哪些产物”，直接读：
- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
---
## 9. 下一步优先顺序
......@@ -161,6 +168,58 @@ flowchart TD
3. 保留 fallback 分支，不破坏当前 host 的可运行性
4. 重新跑主链 runner，确认 semantic lane 有 fresh 证据
## 9.1 Selected20（20 首歌）当前评估结论
当前 `.omx` 记录对应的 20 首歌专题产物已经落在：
- `acr-engine/data/local_eval/selected20_songid_eval_report.json`
- `acr-engine/data/local_eval/selected20_songid_eval_report_fresh.json`
- `docs/selected20_songid_eval.md`
- `docs/selected20_songid_eval_repro.md`
- `docs/research-delivery-roadmap.md`
评测口径：
- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
- reference：`type_11`
- query：`type_1 / type_7 / type_12 / type_16`
- 评测目标：song-level `song_id` 命中率
- 当前方案：`chromaprint_matcher + mert-v1-95m`
- 融合口径：`0.6 * exact + 0.4 * semantic`
当前实测汇总：
| lane | count | top1 | top3 |
|---|---:|---:|---:|
| exact | 123 | 0.6016 | 0.8130 |
| semantic | 123 | 0.4715 | 0.6016 |
| fused | 123 | 0.6341 | 0.8537 |
补充说明：
- 2026-06-04 已做 fresh 重跑
- `selected20_songid_eval_report_fresh.json` 与当前基线结果一致
- 说明这份 20 首专题基线已具备可重复性，可直接作为后续 MuQ / fusion 变更的回归对照
按 query type 看：
| query_type | count | 结论 |
|---|---:|---|
| `type_1` | 21 | exact / semantic / fused 全部 `top1=1.0`，当前已打满 |
| `type_7` | 41 | 当前最弱短板之一；`fused top1=0.4390 / top3=0.7561`，比单 semantic 好，但仍不够稳 |
| `type_12` | 23 | 当前最好的一类之一；semantic 单 lane 已 `top1=1.0`，融合后 `top1=0.9130 / top3=1.0` |
| `type_16` | 38 | 当前另一主要短板；`fused top1=0.4737 / top3=0.7895`，仅小幅优于 exact |
一句话判断：
> **这 20 首歌专题里，当前融合链路已经明显优于单独 semantic，也略优于单独 exact；但真正限制实战效果的仍是 `type_7 / type_16` 这类混淆/改写 query，而不是 `type_1` 或 `type_12`。**
因此下次如果继续推进这个专题，优先顺序应是：
1. 先把 `selected20_songid_eval_report.json` 当作小样本回归基线
2. 接入 MuQ challenger 后直接复跑这份专题
3. 重点比较 `type_7 / type_16` 是否提升，而不是只看 overall
4. 如果后续切 PostgreSQL online path，也保留这份文件级评测作为快速回归基线
5. 继续按 [research-delivery-roadmap.md](./research-delivery-roadmap.md) 的 roadmap + checklist 拆下一阶段任务
---
## 一句话 handoff
......
......@@ -35,12 +35,16 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
---
## 2. 只读这 4 份文档
## 2. 只读这 8 份文档
1. [README.md](./README.md)
2. [session-handoff.md](./session-handoff.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
2. [delivery-onepager.md](./delivery-onepager.md)
3. [session-handoff.md](./session-handoff.md)
4. [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
5. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
6. [selected20_songid_eval.md](./selected20_songid_eval.md)
7. [postgresql-data-model.md](./postgresql-data-model.md)
8. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
---
......@@ -117,6 +121,9 @@ flowchart TD
### 第一优先级
把 semantic lane 从 `mert-v1-95m` baseline 扩展到 `MuQ` challenger，且不破坏现有宿主链。
### 并行专题优先级
把 `selected20`（20 首歌）作为小样本回归基线固定下来，后续任何 semantic challenger 或 fusion 调整都先复跑这份专题，重点看 `type_7 / type_16` 是否真的改善。
### 当前 host 事实
- `torch` 已可导入
- `torchaudio` 已可导入
......