session-handoff.md 22 KB

Raw Blame History Permalink



Session Handoff / 持续开发交接文档


更新：2026-06-02

目的：让新 session / 新代理进入仓库后，能在最短时间内理解项目现状并继续开发。


一页结论

这是一个正在从原型向工业化推进的 音乐 ACR / music retrieval 项目。

当前已经完成：


原型可运行


synthetic 数据生成
训练
建索引
识别
评测


开放数据接入链路完整闭环


inspect-local / inspect-batch
prepare-local
validate-local
train
build-index
evaluate
generate_artifacts


文档已浓缩


docs 入口已分成 4 组
相对路径支持跳转
开放数据工作流有单页文档


当前最重要的下一步：


用真实本地 FMA / MTG-Jamendo 音频目录替换 synthetic stand-in
跑真实开放数据 smoke
继续优化准确率，尤其是 confused / humming_like


1. 项目是什么

这是一个面向音乐片段识别 / 音乐检索的 ACR 引擎，核心路线是：


指纹检索（Chromaprint-like）
embedding 检索（ECAPA-derived）
可选 melody-aware 融合
retrieval-first 评测与优化


它已经不是单纯的“分类模型训练脚本”，而是一个较完整的工程原型：


数据层
训练层
索引层
识别层
评测层
文档层
开放数据接入层
发布产物层


2. 你应该先看哪些文档


核心 4 组入口


docs/README.md
docs/open-dataset-workflow.md
docs/dataset-spec.md
docs/industrialization-roadmap.md


如果你是算法/模型方向


docs/dataset-spec.md
docs/sota-research-2026.md
docs/industrial-benchmark-spec.md


如果你是数据接入方向


docs/open-dataset-workflow.md
docs/dataset-sources-and-licensing.md
acr-engine/data/raw/README.md


如果你是工程/服务方向


docs/service-api.md
docs/CHANGELOG.md


3. 当前代码结构重点


训练与评测主入口


acr-engine/train.py
acr-engine/evaluate.py
acr-engine/run_demo.py


数据层


acr-engine/src/data/dataset.py
acr-engine/src/data/synthetic.py
acr-engine/src/data/manifest_tools.py
acr-engine/src/data/external_adapters.py


检索与模型层


acr-engine/src/engines/hybrid_engine.py
acr-engine/src/engines/ecapa_embedder.py
acr-engine/src/engines/chromaprint_matcher.py
acr-engine/src/models/ecapa_tdnn.py
acr-engine/src/models/losses.py


服务层


acr-engine/src/service/app.py


4. 已经完成的关键能力


4.1 原型与 synthetic 数据


synthetic dataset 可生成

train.py --dry-run 可通过
可训练出 checkpoint
可 build-index
可 recognize
可 evaluate


4.2 开放数据接入

已经具备以下命令：


inspect-local
inspect-batch
prepare-local
validate-local
smoke-local


这些都在：


acr-engine/src/data/external_adapters.py


4.3 文档与发布产物

开放数据 smoke 也能生成：


benchmark report
model card
release checklist
artifact manifest


5. 开放数据当前的实际工作方式


真实音频应该放到哪里


acr-engine/data/raw/fma_small_audio/
acr-engine/data/raw/mtg_jamendo_audio/


说明文件：


acr-engine/data/raw/README.md


当前最推荐的命令


FMA

/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2


MTG-Jamendo

/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local mtg_jamendo data/raw/mtg_jamendo_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2


当前 smoke-local 已验证能力

smoke-local 会自动跑：


inspect-local
prepare-local
validate-local
train
build-index
evaluate
generate_artifacts


6. 目前最重要的验证证据


6.1 synthetic-as-open-fixed（开放数据 stand-in）

已成功验证：


prepare-local
validate-local
train.py
build-index
evaluate.py
generate_artifacts.py


关键结果：


num_queries=8
top1=1.0
topk=1.0


相关目录：


acr-engine/data/external_ingested/synthetic_as_open_fixed/
acr-engine/reports/open-smoke-fixed/fma/


6.2 一键 smoke-local

已验证：

/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/synthetic_v2/songs --output-root data/external_smoke --eval-ratio 0.2 --query-duration 5.0 --train-epochs 1 --batch-size 2


关键结果：


num_audio_files=24
catalog=24
train_queries=16
test_queries=8
top1=1.0
topk=1.0


相关目录：


acr-engine/data/external_smoke/


0. 当前交付状态（本次 checkpoint）


已可交付


文档体系、数据规范、切片策略、评测公平性控制已成型。
新 session 已可依据本文件和 AGENT.md 继续推进。


当前卡点


cap48 top2 seed=999 已完成，三 seed aggregate 已可计算。
工作区存在大量数据与模型产物，当前只建议精确提交文档文件。


0.5 当前 bucket/style-aware 基线结论

完整 bucket 汇总已完成：


汇总文件：/tmp/ab_smoke_bucketed_smoke/report.json


prefix_000_a：winner=hybrid


prefix_000_b：winner=high_energy

aggregate：


hybrid：mean_top1=1.0, mean_topk=1.0, mean_num_queries=4.0


high_energy：mean_top1=1.0, mean_topk=1.0, mean_num_queries=3.5


当前解释：


toy bucket 已经足够证明“不同子集可出现不同 winner”。
但它仍不是业务语义 bucket，因此只能作为方法学基线，不能当成最终产品结论。


最新验证证据（2026-06-02 18:21 UTC 左右）


hybrid 的 reference index 已完成：


refs_done=48 / refs_total=48
windows_done=491
embedding_shape=[491, 192]
elapsed_sec=80.26


对应文件已写出：


/tmp/ab_smoke_seg_cap48_top2_seed999/hybrid/fma_index_smoke/reference_embs.npy
/tmp/ab_smoke_seg_cap48_top2_seed999/hybrid/fma_index_smoke/reference_ids.npy
/tmp/ab_smoke_seg_cap48_top2_seed999/hybrid/fma_index_smoke/reference_progress.json


进程树已确认进入：


evaluate.py --data /tmp/ab_smoke_seg_cap48_top2_seed999/hybrid/fma/manifests ... --output-json /tmp/ab_smoke_seg_cap48_top2_seed999/hybrid/fma_reports_smoke/eval.json --seed 999 --max-queries 24


最终结果（seed=999）：


hybrid：num_queries=24, top1=0.875, topk=1.0


high_energy：num_queries=24, top1=0.9167, topk=1.0

winner：high_energy


三 seed aggregate（cap48）：


high_energy：mean_top1=0.9167, min=0.9167, max=0.9167, stdev=0.0


hybrid：mean_top1=0.8750, min=0.7917, max=0.9583, stdev=0.0680


最优先待办


把已完成的 toy bucket baseline 升级为语义 bucket（风格 / 结构 / hard-case）。
对比 cap48 与 cap64 的不一致现象，补充分规模结论。
继续补 cap64 multi-seed，而不是只保留单 seed。
继续优化 hybrid，重点降低波动并提升 hard case 稳定性。
在 bucket 基线下继续提交与推送。


续跑时不要做的事


不要 git add .

不要提交 data/raw、data/external_smoke、/tmp、__pycache__、模型与索引产物


7. 当前最重要的待办


优先级 A：真实开放数据替换

目标：


用真实本地 FMA / MTG-Jamendo 音频替换 synthetic stand-in


操作：


把真实音频放进：


acr-engine/data/raw/fma_small_audio/
或 acr-engine/data/raw/mtg_jamendo_audio/


直接运行 smoke-local

记录：


inspect 规模
train/test query 数
top1/topk
artifact bundle


优先级 B：hard-case 精度继续优化

当前历史结论：


naive oversampling：失败
type-aware weighting：部分有效
sample-level weighting：提升 confused

retrieval fusion tuning：更稳定有效


下阶段重点：


confused
humming_like
真实开放数据上的 hard-case bucket


优先级 C：foundation model / SOTA baseline

已经在文档中记录：


MERT
MuQ
更强 retrieval-first 路线


后续可以做：


frozen backbone baseline
adapter fine-tune


8. 最新关键提交（便于新 session 快速定位）

近几次关键提交建议优先看：


6232787 Make segmentation strategy benchmarks comparable under fixed query budgets

f04a314 Benchmark real FMA segmentation strategies on a capped smoke subset

d7a0894 Favor beat-aligned candidate segments for music ACR training/query generation

b6cdf66 Add high-energy and onset-aware music segment selection

d221852 Add explicit drop zones for real open-music corpora

eee15ac Automate the full open-dataset smoke workflow behind one command

8795907 Generate release artifacts for the open-dataset smoke path

dc9ef1b Close the open-dataset smoke loop through evaluation


9. 最新真实数据切片 benchmark 状态（重启后优先续跑这里）


已完成的最新事实

当前项目已经不是“只有 random 切片”：


训练/外部 query 生成支持：


random
silence_aware
high_energy
onset_aware
beat_aware
repeated_section_aware
hybrid


已接入的 librosa 逻辑：


effects.split
onset.onset_detect
beat.beat_track
feature.chroma_cqt


已完成的小规模 capped 验证

命令：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_cap \
  --subset-size 6 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid \
  --max-test-queries 5 \
  --output-json /tmp/ab_smoke_cap/report.json


结果：


max_test_queries = 5
num_queries = 5
top1 = 1.0
topk = 1.0


正在进行的中规模 capped FMA benchmark

命令：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg_cap16 \
  --subset-size 16 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid beat_aware high_energy repeated_section_aware \
  --max-test-queries 12 \
  --output-json /tmp/ab_smoke_seg_cap16/report.json


在本次交接时，cap16 已完成，最终结果如下：


策略
num_queries
top1
topk
状态


hybrid
12
1.0
1.0
已完成


high_energy
12
1.0
1.0
已完成


beat_aware
12
0.9167
1.0
已完成


repeated_section_aware
12
0.8333
1.0
已完成


重启后第一优先动作


先检查：


pgrep -af 'ab_smoke_seg_cap16|external_adapters.py smoke-local fma /tmp/ab_smoke_seg_cap16|evaluate.py --data /tmp/ab_smoke_seg_cap16|run_demo.py build-index --data /tmp/ab_smoke_seg_cap16'


如果 report.json 已存在，优先读取并同步文档
如果中断：


保留已有 /tmp/ab_smoke_seg_cap16/* 结果作人工记录
重新跑缺失策略，或单独跑：


cd /workspace/acr-engine
/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local \
  fma /tmp/ab_smoke_seg_cap16/subset_audio \
  --output-root /tmp/ab_smoke_seg_cap16/high_energy \
  --eval-ratio 0.2 \
  --query-duration 8.0 \
  --query-strategy high_energy \
  --segment-strategy high_energy \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --max-test-queries 12 \
  --seed 42


当前这轮 cap16 的最终建议已经形成：


默认优先：hybrid

强次选：high_energy


beat_aware / repeated_section_aware 更适合作为补充对照，而不是默认策略


10. cap24 top2 对照实验（进行中）

为进一步判断 hybrid 与 high_energy 的并列关系，已经启动更大的真实 FMA 对照：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg_cap24_top2 \
  --subset-size 24 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid high_energy \
  --max-test-queries 16 \
  --output-json /tmp/ab_smoke_seg_cap24_top2/report.json


当前 fresh evidence：


策略
subset
max_test_queries
top1
topk
状态


hybrid
24
16
1.0
1.0
已完成


high_energy
24
16
0.8125
1.0
已完成


恢复检查命令：

pgrep -af 'ab_smoke_seg_cap24_top2|external_adapters.py smoke-local fma /tmp/ab_smoke_seg_cap24_top2|evaluate.py --data /tmp/ab_smoke_seg_cap24_top2|run_demo.py build-index --data /tmp/ab_smoke_seg_cap24_top2'


cap24 top2 最终结论：


hybrid：16 / 1.0 / 1.0


high_energy：16 / 0.8125 / 1.0

这个结果比 cap16 更能说明问题：当前默认策略应明确固定为 hybrid


11. cap32 top2 对照实验（已完成）

为了确认 cap24 的结论不是偶然，已继续启动更大的真实 FMA top2 对照：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg_cap32_top2 \
  --subset-size 32 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid high_energy \
  --max-test-queries 20 \
  --output-json /tmp/ab_smoke_seg_cap32_top2/report.json


最终结果：


项目
状态


subset_size
32


max_test_queries
20


hybrid

num_queries=20, top1=0.95, topk=1.0


high_energy

num_queries=20, top1=0.5, topk=1.0


report.json
已生成


恢复检查命令：

pgrep -af 'ab_smoke_seg_cap32_top2|external_adapters.py smoke-local fma /tmp/ab_smoke_seg_cap32_top2|evaluate.py --data /tmp/ab_smoke_seg_cap32_top2|run_demo.py build-index --data /tmp/ab_smoke_seg_cap32_top2|train.py --data /tmp/ab_smoke_seg_cap32_top2'


cap32 top2 最终结论：


hybrid：20 / 0.95 / 1.0


high_energy：20 / 0.5 / 1.0

cap24 与 cap32 两轮更大真实子集都指向同一结论：默认策略固定为 hybrid


12. cap48 top2 对照实验（已完成）

为继续扩展真实数据证据链，已启动更大的 FMA top2 对照：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg_cap48_top2 \
  --subset-size 48 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid high_energy \
  --max-test-queries 24 \
  --output-json /tmp/ab_smoke_seg_cap48_top2/report.json


最终结果：


项目
状态


subset_size
48


max_test_queries
24


high_energy

num_queries=24, top1=0.9167, topk=1.0


hybrid

num_queries=24, top1=0.7917, topk=1.0


report.json
已生成


恢复检查命令：

pgrep -af 'ab_smoke_seg_cap48_top2|external_adapters.py smoke-local fma /tmp/ab_smoke_seg_cap48_top2|evaluate.py --data /tmp/ab_smoke_seg_cap48_top2|run_demo.py build-index --data /tmp/ab_smoke_seg_cap48_top2|train.py --data /tmp/ab_smoke_seg_cap48_top2'


cap48 top2 最终结论：


high_energy：24 / 0.9167 / 1.0


hybrid：24 / 0.7917 / 1.0

这轮结果与 cap24 / cap32 不一致，说明当前默认策略结论还不能视为彻底封板

下一步应优先做：


更大 subset（如 64+）
多 seed 复跑
style-aware bucket benchmark


13. cap48 top2 第二个 seed（已完成）

为验证 cap48 的“high_energy 反超”是否稳定，已启动第二个 seed：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg_cap48_top2_seed123 \
  --subset-size 48 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies hybrid high_energy \
  --max-test-queries 24 \
  --seed 123 \
  --output-json /tmp/ab_smoke_seg_cap48_top2_seed123/report.json


最终结果：


项目
状态


subset_size
48


max_test_queries
24


seed
123


hybrid

num_queries=24, top1=0.9583, topk=1.0


high_energy

num_queries=24, top1=0.9167, topk=1.0


report.json
已生成


seed123 最终结论：


hybrid：24 / 0.9583 / 1.0


high_energy：24 / 0.9167 / 1.0

cap48 至少已经表现出明显的 seed 敏感性

因此当前默认策略的判断应基于 多 seed 聚合，而不是单次 cap48 反转


cap48 两次 seed 的当前聚合结论


策略
runs
mean_top1
min_top1
max_top1
stdev_top1


high_energy
2
0.9167
0.9167
0.9167
0.0


hybrid
2
0.8750
0.7917
0.9583
0.0833


当前最稳妥的解释：


high_energy 在 cap48 两次 seed 上的均值暂时领先


hybrid 结果波动更大，但单轮峰值更高
后续默认策略不应只看某一次单跑，而应继续累计 seed / style bucket 的聚合结果

b766c74 Make open-dataset manifests trainable end to end

fa23144 Add a single-page open dataset workflow for training prep

af33be3 Condense docs and add manifest validation before training


这些 commit 基本覆盖了当前开放数据与文档演进主线。


9. 新 session 接手时的推荐动作

如果你是新的 session，建议顺序：


读：


docs/README.md
docs/open-dataset-workflow.md
docs/session-handoff.md
docs/current-capability-map.md


docs/training-data-and-pgvector-guide.md


acr-engine/FIRST_RUN_CHECKLIST.md


FMA 真实子集下载脚手架已存在：acr-engine/scripts/fetch_fma_subset.py；最近验证结果是旧直链 403、页面级历史 URL 404；但 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 已验证 200 OK 且支持 range


运行 acr-engine/scripts/status_snapshot.py

或直接查看最新落盘快照：acr-engine/.omx/latest_status_snapshot.json


检查真实数据是否已落位：


acr-engine/data/raw/fma_small_audio/
acr-engine/data/raw/mtg_jamendo_audio/


如果已有真实音频：


直接跑 smoke-local


如果还没有真实音频：


继续优化 synthetic-as-open-fixed
或继续补开放数据下载/清洗自动化


每完成一个阶段：


更新 docs/CHANGELOG.md

git commit
git push


10. 注意事项


这个仓库里存在已跟踪的 __pycache__ 文件；提交时要小心不要让它们污染变更。
当前最稳定的改进方向不是盲目调训练权重，而是：


retrieval-time fusion
更真实开放数据
更真实评测


开放数据布局现在依赖“自包含输出根”：


audio/

manifests/
这一点后续不要破坏。


Sources


README.md
open-dataset-workflow.md
CHANGELOG.md
FMA 下载完成后可直接执行：acr-engine/scripts/fma_postdownload_ready.py
若需要等待下载完成并自动切到解压/就绪检查，可直接执行：acr-engine/scripts/wait_for_fma_and_prepare.py


99. 本次 checkpoint 的明确结论


hybrid 的 seed=999 评测结果已先行落盘：top1=0.875, topk=1.0, num_queries=24。
本次已经完成“交接可续跑化”交付。
本次没有等待 seed=999 长时 CPU benchmark 完成，因此算法默认策略不做新结论跳变。
当前最新稳妥表述仍然是：


high_energy 在已知两轮 cap48 aggregate 中更稳

hybrid 上限更高但波动更大
最终默认策略要看更多 seed 聚合结果


100. 新一轮验证已启动：cap64


已启动：/tmp/ab_smoke_seg_cap64_top2

配置：subset_size=64, max_test_queries=32, seed=42

当前最新证据：


cap64 已完成：

hybrid：num_queries=32, top1=0.875, topk=1.0


high_energy：num_queries=32, top1=0.625, topk=1.0

cap64 winner：hybrid

当前结论已进入“分子集规模不一致”阶段，必须继续做 bucket/style-aware benchmark


101. bucket/style-aware benchmark 基线已落地


新脚本：acr-engine/scripts/ab_smoke_bucketed.py

已通过：py_compile

已验证首个 bucket：prefix_000_a


hybrid: 4 / 1.0 / 1.0


high_energy: 3 / 1.0 / 1.0

winner: hybrid


当前第二个 bucket prefix_000_b 仍在继续执行