CHANGELOG.md 280 KB

Raw Blame History Permalink



2026-06-02 16:11 UTC / hum_guard fresh eval did not beat hum_focus


对 /tmp/dualaxis_sweep/hum_guard/eval.json 做了最新复核
fresh evidence：


num_queries=20
top1=0.6
topk=0.85
clean top1=0.875
augmented top1=0.75
humming_like top1=0.5
confused top1=0.0


对比结论：


hum_guard 没有超过 hum_focus

它在 topk 上与 hum_focus 持平，但 top1 更低
当前仍应以 hum_focus 作为下一轮小步搜索锚点


2026-06-02 16:12 UTC / delivery package frozen for handoff


当前任务切到“先交付、后续跑”的状态，暂停继续扩展实现，先把交接文件补齐
当前最重要的最新事实：


hum_focus 仍是当前 dual-axis 最佳候选
真实 FMA / 开放数据链路、数据规范、pgvector 说明、SOTA 研究文档都已补齐到可接续状态


交付目标：


让新 session 能直接从 docs/session-handoff.md、docs/delivery-handoff-2026-06-02.md 接上
让后续继续做数据集补充、切片策略、训练/评测优化时不需要重新梳理上下文


约束确认：


不提交 data/raw、data/external_smoke、checkpoint、__pycache__

文档链接继续使用相对路径


下一步（重启后）：


继续围绕 hum_focus 做小步搜索
继续补充开放数据集训练/评测组合
再做一轮可复现的训练 + 评测 + 提交


2026-06-02 16:03 UTC / hum_focus pinned as the current best dual-axis candidate


在 dual-axis 搜索中继续比较 hum_focus 与 hum_balanced，拿到更细粒度的 fresh evidence
fresh evidence（2026-06-02 16:03:13 UTC）：


hum_focus：top1=0.7, topk=0.85, humming_like=0.5, confused=0.25


hum_balanced：top1=0.65, topk=0.95, humming_like=0.25, confused=0.25


结论：


hum_focus 当前是这轮搜索的最佳候选
它把 humming_like 从 0.0 拉回到 0.5，同时保住 confused=0.25


hum_balanced 只回到 v6 水平，未超越 hum_focus


下一步最值得做的是围绕 hum_focus 微调，而不是退回到 v6 或继续盲搜


2026-06-02 15:56 UTC / dual-axis smoke completed first end-to-end eval


以新的 dual-axis 配置跑通了一轮端到端 smoke：train -> build-index -> evaluate

fresh evidence（2026-06-02 15:56:02 UTC）：


训练输出：/tmp/dualaxis_smoke/models/best_model.pt

索引输出：/tmp/dualaxis_smoke/index/

评测输出：/tmp/dualaxis_smoke/eval.json


结果：


num_queries=20
top1=0.5
topk=0.9
clean top1=0.875
humming_like top1=0.0
confused top1=0.25


对比当前基线：


比 v6 的 humming_like=0.25 更差
与 v6 的 confused=0.25 持平


结论：


双轴参数化已经能跑通完整链路
但这组权重并未改善 humming_like，后续应继续做更细粒度的双轴搜索，而不是直接接受当前组合


2026-06-02 15:47 UTC / dual-axis hard-case weighting is now configurable in code


已把 SongPairDataset 中的 hard-case 采样权重与 pair loss 权重从硬编码改为配置驱动
代码变更：


src/data/dataset.py：新增 sample_type_weights / pair_type_weights 参数

train.py：从 cfg["training"] 透传上述配置

configs/default.yaml：新增默认 dual-axis hard-case 权重配置


fresh verification：


python -m py_compile train.py src/data/dataset.py 通过

train.py --data data/synthetic_v2 --device cpu --epochs 1 --batch-size 4 --dry-run 通过
自定义权重实例化检查通过：
dataset_len=96
unique_songs=16
sample_multiplicity_minmax=6/6
示例 hard_weight=[5.0, 1.0]


结论：下一轮可直接在不改代码结构的前提下，实验 humming_like / confused 的双轴 weighting 组合


2026-06-02 15:46 UTC / v5-v6 hard-case difference is now causally explained


基于仓库内历史实验记录，补齐了 v5 与 v6 hard-case 表现差异的来源解释
fresh evidence：


docs/CHANGELOG.md:2954+ 明确记录：v6 是 sample-level confused-priority weighting


docs/CHANGELOG.md:6805+ 明确记录：v5 是 type-aware hard-case weighting


docs/sota-research-2026.md:113-114 已总结两者差异：

v5 改善 humming_like，但 confused 无突破

v6 提升 confused，但 humming_like 回落


当前可执行结论：


v5 的优势主要来自 type-aware weighting 对 humming_like 的更温和提升

v6 的优势主要来自 sample-level confused-priority weighting 对 confused 的定向拉升
下一轮不应重做盲目 sweep，而应设计 双轴 hard-case weighting / 分治策略


2026-06-02 15:45 UTC / hard-case baseline sweep pinned the next optimization baseline


对现有 v3~v6 基线在 data/synthetic_v2 上做了一轮统一 hard-case 评测 sweep
fresh evidence（2026-06-02 15:45:18 UTC）：


汇总文件：/tmp/synth_v2_baseline_sweep/summary.json

统一配置：evaluate.py --data data/synthetic_v2 --fast-eval --split test --top-k 5 --seed 42


关键结果：


v3: top1=0.6, topk=0.75, humming_like top1=0.0, confused top1=0.25


v4: top1=0.4, topk=0.8, humming_like top1=0.0, confused top1=0.0


v5: top1=0.6, topk=0.9, humming_like top1=0.5, confused top1=0.0


v6: top1=0.65, topk=0.95, humming_like top1=0.25, confused top1=0.25


结论：


若看总体与 clean/augmented 平衡：v6 当前最强
若专看 humming_like top1：v5 当前更强（0.5 vs 0.25）
因此下一轮优化建议以 v6 为总体基线，同时对比吸收 v5 在 humming_like 上更优的因素


2026-06-02 15:43 UTC / hard-case gap verified after the first real-path closure


在首个 real-path build-index -> evaluate 闭环之后，补跑了一轮现成 synthetic_v2 hard-case smoke，验证下一步优化重点
fresh evidence（2026-06-02 15:43:17 UTC）：


评测文件：/tmp/synthetic_v2_eval_v6_top16.json

组合：data/synthetic_v2 + data/models_v6/best_model.pt + data/index_v6/reference

结果：num_queries=16, top1=0.6875, topk=1.0

by_type：

clean: n=7, top1=1.0, topk=1.0


augmented: n=4, top1=0.75, topk=1.0


humming_like: n=4, top1=0.25, topk=1.0


confused: n=1, top1=0.0, topk=1.0


关键解释：


当前 real-path FMA external smoke manifest 只包含 clean query，没有 confused / humming_like

因此 real-path 评测只能证明 clean 闭环，不足以证明 hard-case 鲁棒性


结论：当前最明确的优化方向已收敛到 humming_like / confused 的 top1 提升，而不是继续重复 clean smoke


2026-06-02 15:40 UTC / real-path 200-ref rerun closed the first explicit evaluate loop


基于已完成的 200-ref real-path index，补了一轮显式 evaluate.py smoke
先定位并修复评测环境问题：


初次失败原因为 /tmp/fma_realpath_small_rerun_eval/audio/... 缺失
通过软链补齐：/tmp/fma_realpath_small_rerun_eval/audio -> /workspace/acr-engine/data/external_smoke/fma/audio


fresh evidence（2026-06-02 15:40:30 UTC）：


eval_top50.json 已落盘：/tmp/fma_realpath_small_rerun_eval/eval_top50.json

结果：num_queries=35, top1=0.8571, topk=1.0


by_type.clean: n=35, top1=0.8571, topk=1.0


验证补充：


overlap test items = 235

其中非 reference query = 35

因此即使 --max-queries 50，最终也只会评到 35 条 query


结论：当前已拿到第一份真实路径 build-index -> evaluate 闭环证据
下一关键里程碑：


扩到更大 query 数或更大 reference 集
引入 confused / humming_like 等 hard case 评测


2026-06-02 15:35 UTC / real-path 200-ref rerun finished reference index


fixed real-path 200 reference rerun：/tmp/fma_realpath_small_rerun_index2 已完成 reference/embedding 阶段
fresh evidence（2026-06-02 15:35:19 UTC）：


chromaprint_progress.json => status=complete, refs_done=200/200, skipped_refs=0


reference_progress.json => status=complete, refs_done=200/200, windows_done=2068, embedding_shape=[2068, 192], skipped_refs=0

最终产物已落盘：

reference_embs.npy（1588352 bytes）

reference_ids.npy（74576 bytes）


前台 stdout 明确可见：


[build-reference-index] progress: refs=200/200 ...
Built reference index: 2068 windows, embeddings shape (2068, 192)
[done] embedding index built: 2068 refs


结论：修复后的真实路径 rerun 已完整跨过 chromaprint -> reference 两个核心建索引阶段
下一关键里程碑：确认后续是否自动进入评测/识别链，或补一轮显式 evaluate smoke


2026-06-02 15:29 UTC / real-path 200-ref rerun crossed into reference stage


基于已修复代码继续跟进真实路径 200 reference rerun：/tmp/fma_realpath_small_rerun_index2

fresh evidence（2026-06-02 15:29:17 UTC）：


chromaprint_progress.json => status=complete, refs_done=200/200, skipped_refs=0

已落盘 chromaprint.pkl（2266212 bytes）

reference_progress.json 已出现，当前为 status=building

reference 阶段已完成首个 checkpoint：refs_done=25/200, windows_done=256, skipped_refs=0

partial 产物已出现：
reference_embs.partial.npy
reference_ids.partial.npy


结论：当前主流程已经明确跨过 chromaprint -> reference 边界，之前“只停在 chromaprint 无下游产物”的状态不再适用于这条 fixed rerun
下一关键里程碑：


reference_embs.npy / reference_ids.npy 完整产出
或捕获新的明确 traceback / failure evidence


2026-06-02 15:22 UTC / bad-mp3 skip tolerance verified


为 chromaprint_matcher.py 与 ecapa_embedder.py 的 reference 建索引循环增加单文件容错：


missing audio -> warning + skip
decode failure -> warning + skip


progress JSON 新增字段：skipped_refs

最小复现验证：/tmp/chroma_skip_repro


1 个正常 mp3 + 1 个损坏 mp3
RC=0
chromaprint 阶段：skipped_refs=1

reference 阶段：skipped_refs=1

成功产出：
reference_embs.npy
reference_ids.npy
reference_progress.json


结论：当前已修复“单个坏 MP3 拖垮整轮 build-index”的高概率故障模式


2026-06-02 15:18 UTC / build-index log flush hardening


为 run_demo.py、chromaprint_matcher.py、ecapa_embedder.py 的关键 print() 增加 flush=True

目的：避免 build-index 长时间运行时日志文件保持 0 bytes，导致“无声运行/无声退出”难排查
fresh evidence：极小样本复现 /tmp/chroma_repro_tiny12 已验证日志实时落盘


RC=1
日志中可见：[build-index] starting chromaprint index

日志中可见：[build-reference-index] start: refs=12 ...

日志中可见最终 traceback：ValueError: No reference embeddings were produced ...


结论：当前至少已修复“失败时日志完全不可见”的可观测性问题，下一步可继续针对真实路径复现 root cause


2026-06-02 15:09 UTC / build-index unexpected exit checkpoint


新鲜证据：observable 与 legacy 两个 build-index 进程都已退出

ps -p 431703 与 ps -p 424691 均无存活进程

pgrep -af 'run_demo.py build-index|evaluate.py ...' 未发现接续进程
observable 目录仍只有：


chromaprint.pkl
chromaprint_progress.json


chromaprint_progress.json 最后状态停在：


status=building
refs_done=4420/8000


当前仍未出现：


reference_*
evaluate.py


结论：当前已从“长时间线性推进”切换为“需要排查 build-index 异常退出”的新阶段


2026-06-02 14:25 UTC / restart-package handoff refresh


交付基线刷新为：bc6d07afbd1e31d3956d20e35c20c424bc21ba99

固化当前最重要运行证据：observable chromaprint smoke


PID=431703
status=building
refs_done=1740/8000
hashes=229127
postings=1510952


明确旧真实 FMA build-index 进程仅作背景运行态，不再作为新 observability 代码验证来源
重写交付/交接文档，便于新 session 直接从 chromaprint -> reference_* -> evaluate 阶段继续
约束保持不变：不提交 data/raw、data/external_smoke、/tmp、checkpoint、__pycache__


2026-06-02 chromaprint build-index observability checkpoint

完成项：


为 acr-engine/src/engines/chromaprint_matcher.py 的 index_songs_from_dir() 增加 chromaprint 阶段 progress JSON 与周期性 partial cache 落盘。
为 acr-engine/run_demo.py build-index 增加 --chromaprint-checkpoint-every-refs，让 chromaprint 阶段也能分段 checkpoint，而不是只能盲等最终 chromaprint.pkl。


验证结果：


小样本可观测 smoke：


命令：run_demo.py build-index --data data/external_smoke/fma/manifests --output /tmp/chroma_index_observable_smoke --chromaprint-checkpoint-every-refs 10 ...


已实际落盘：


/tmp/chroma_index_observable_smoke/chromaprint_progress.json
/tmp/chroma_index_observable_smoke/chromaprint.pkl


chromaprint_progress.json fresh evidence：


status=building
refs_done=50
refs_total=8000
elapsed_sec=36.93
eta_sec=5871.909
hashes=19509
postings=45626


chromaprint.pkl 当时文件大小：574K


python -m py_compile src/engines/chromaprint_matcher.py run_demo.py 通过


结论：


现在 chromaprint 阶段不再是黑盒长跑，可以直接看到 refs 进度、ETA、hash/posting 规模，并在运行中拿到 partial cache。
后续新进程可直接用这套证据判断 build-index 是否真正推进，而不必盲等最终产物。


2026-06-02 chromaprint peak scan exact-safe optimization checkpoint

完成项：


将 acr-engine/src/engines/chromaprint_matcher.py 的 _find_peaks() 从 Python 双层循环改为 sliding_window_view 向量化窗口最大值实现。
放弃了更激进但会改变 hash 结果的 maximum_filter 方案，改用严格保持旧语义的等价版本。


验证结果：


单曲样本 /tmp/fma_real_smoke_stopcheck/fma/audio/fma_00000.mp3：


old_sec=1.3305
new_sec=0.6579
speedup_x=2.02


等价性验证：


same_all200=true
same_hashes=true
old_hashes=609
new_hashes=609


python -m py_compile src/engines/chromaprint_matcher.py 通过
长跑中的真实 FMA smoke 在 2026-06-02 13:49:25 UTC 仍处于 build-index，尚未产出 chromaprint.pkl / reference_progress.json


结论：


这次提交安全降低了 chromaprint 峰值扫描热点成本，且不改变当前 fingerprint/hash 行为。
后续可继续观察真实 FMA 全量 smoke 是否更快进入 chromaprint.pkl 或 embedding checkpoint。


2026-06-02 真实 FMA smoke build-index 13:36 UTC delivery checkpoint

完成项：


复核真实 FMA 全量 smoke 的最新运行态，确认当前已越过训练阶段。
将最新可交付事实补充到 handoff / delivery / AGENT 记忆文档。
明确新 session 的唯一高价值续跑目标：监控 build-index -> evaluate 切换。


验证结果：


活跃进程仍为：


external_adapters.py smoke-local fma ...
run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests ...


模型产物已存在：


/tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt
/tmp/fma_real_smoke_stopcheck/fma_models_smoke/song_to_idx.json


validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true

当前仍未观测到 evaluate.py，fma_index_smoke/ 仍未看到索引产物文件


结论：


真实 FMA smoke 当前稳定停留在 CPU-only 建索引阶段。
本次交付重点已从“训练进行中”切换为“等待索引产物或评测切换”。


2026-06-02 真实 FMA smoke build-index 13:34 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:34 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 13:28 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:28 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 13:22 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:22 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 13:16 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:16 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 13:10 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:10 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 13:04 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 13:04 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 12:59 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 12:59 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 12:55 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 12:55 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 12:51 UTC checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 12:51 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录 evaluate.py 仍未启动、索引目录仍未出现索引产物文件。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 再延续 checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程到 12:43 UTC 仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录索引目录仍未出现索引产物文件，evaluate.py 仍未启动。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 仍稳定处于建索引阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 延续 checkpoint

完成项：


再次检查真实 FMA smoke 的下游阶段，确认流程仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录到 12:39 UTC 仍未出现索引产物文件或 evaluate.py。


验证结果：


当前仍存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前仍未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录存在，但尚未看到索引产物文件

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 已稳定停留在建索引阶段，但尚未进入评测阶段。
下一关键证据仍是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke build-index 持续阶段 checkpoint

完成项：


再次检查真实 FMA smoke 下游阶段，确认流程仍停留在 build-index。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录索引目录已创建但尚未出现索引产物文件。


验证结果：


当前存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...

当前未观测到 evaluate.py 进程

/tmp/fma_real_smoke_stopcheck/fma_index_smoke/ 目录已创建

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 已稳定进入建索引阶段，但还没有切换到评测阶段。
下一关键证据是索引产物出现或 evaluate.py 启动。


2026-06-02 真实 FMA smoke 跨过训练结束并进入 build-index checkpoint

完成项：


在更长观察窗口后确认真实 FMA smoke 已结束训练阶段。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录首个模型文件落盘与 build-index 转场。


验证结果：


原 train.py 进程已结束

/tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt 已出现

/tmp/fma_real_smoke_stopcheck/fma_models_smoke/song_to_idx.json 已出现
当前存在 run_demo.py build-index --data /tmp/fma_real_smoke_stopcheck/fma/manifests --model /tmp/fma_real_smoke_stopcheck/fma_models_smoke/best_model.pt ...


validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


结论：


真实 FMA 全量 smoke 已成功跨过“长时间 CPU 训练”这一最大不确定阶段。
当前流程已进入 build-index，下一关键证据是索引完成并切换到 evaluate。


2026-06-02 真实 FMA smoke fresh evidence 31:47 checkpoint

完成项：


在额外约 180 秒窗口后再次检查真实 FMA smoke，确认 train.py elapsed 已推进到 31:47。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更长观察窗口下的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=31:47

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 在更长观察窗口下仍持续推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 27:54 checkpoint

完成项：


在额外约 120 秒窗口后再次检查真实 FMA smoke，确认 train.py elapsed 已推进到 27:54。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更长观察窗口下的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=27:54

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 在更长观察窗口下仍持续推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 24:11 checkpoint

完成项：


在额外约 30 秒窗口后再次检查真实 FMA smoke，确认 train.py elapsed 已推进到 24:11。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更有间隔意义的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=24:11

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 在更长观察窗口下仍持续推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 22:58 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 22:58。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=22:58

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 22:10 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 22:10。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=22:10

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 20:08 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 20:08。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=20:08

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 19:12 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 19:12。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=19:12

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 18:22 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 18:22。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，同步更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=18:22

仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，没有中断迹象。
到该时点仍未产生首个模型文件或下游阶段切换证据。


2026-06-02 真实 FMA smoke fresh evidence 17:07 checkpoint

完成项：


再次刷新真实 FMA smoke 运行态，确认 train.py elapsed 已推进到 17:07。
更新 docs/session-handoff.md 与 docs/changelist-2026-06-02.md，记录更晚的 live evidence。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=17:07

当前仍未出现 build-index/evaluate 相关新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


fma_models_smoke/ 仍仅有目录本身


结论：


真实 FMA 全量 smoke 仍在 epoch 内推进，暂无流程中断证据。
到该时点仍未产生首个模型文件或后续评测阶段证据。


2026-06-02 真实 FMA smoke fresh evidence 15:12 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认 train.py 仍在前进而非悬挂。
更新 docs/session-handoff.md，补齐 12:12 UTC 的最新时间推进证据。
更新 docs/changelist-2026-06-02.md，把最新 elapsed 时间推进补入交付记录。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=15:12

仍仅存在 smoke-local 与 train.py 相关进程，未见 build-index/evaluate 新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


find /tmp/fma_real_smoke_stopcheck/fma_models_smoke ... 仍仅返回目录本身


结论：


当前真实 FMA smoke 还未结束第 1 个 epoch，但持续推进证据已再次更新。
到这一时点，仍没有流程卡死迹象，也还没有最终精度结果。


2026-06-02 真实 FMA smoke fresh evidence 再校验 checkpoint

完成项：


再次检查真实 FMA smoke 运行态，确认训练仍在持续推进。
更新 docs/session-handoff.md，补充 12:11 UTC 的 fresh evidence。
更新 docs/changelist-2026-06-02.md 与 docs/delivery-handoff-2026-06-02.md，强调当前尚未进入 build-index/evaluate。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd => ELAPSED=14:25

当前仅存在 smoke-local 与 train.py 相关进程，未见 build-index/evaluate 新进程

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


find /tmp/fma_real_smoke_stopcheck/fma_models_smoke ... 仅返回目录本身


结论：


真实 FMA smoke 仍在 epoch 内部推进，没有卡死证据。
截至本次 checkpoint，流程尚未进入建索引或评测阶段。


2026-06-02 交付包补齐最新真实 FMA 运行态与重启接力说明 checkpoint

完成项：


更新 docs/session-handoff.md，补齐真实 FMA smoke 的最新运行态、卡点与重启后第一优先级动作。
更新 docs/delivery-handoff-2026-06-02.md，把当前最关键卡点切换为“真实 FMA CPU 长训练仍在执行中”。
更新 docs/changelist-2026-06-02.md，记录本次交付包的新增证据与下一步。
更新 AGENT.md，写入最新真实 FMA smoke 运行态记忆。
修正 docs/README.md 中“4 组/5 组主文档”的表述不一致。


验证结果：


ps -p 311629 -o pid,etime,%cpu,%mem,cmd 显示 train.py 仍在运行。

validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


/tmp/fma_real_smoke_stopcheck/fma_models_smoke/ 当前为空目录，符合 Epoch 1 结束后首次保存的实现逻辑。


结论：


当前可交付的最新事实已经被沉淀进 handoff 包，新 session 重启后无需重复排查“是否卡死”。
现阶段最真实的 blocker 是 无 GPU 环境下真实 FMA 全量 smoke 训练耗时长，而不是流程错误。


2026-06-02 真实 FMA smoke 启动并进入 CPU 长训练 checkpoint

完成项：


已在真实本地 FMA 数据上启动端到端 smoke：


输入目录：acr-engine/data/raw/fma_small_audio

输出目录：/tmp/fma_real_smoke_stopcheck


已确认真实 FMA manifest 生成并通过校验：


catalog_references=8000
train_queries=6401
test_queries=1593
val_queries=0


已确认当前环境无可用 NVIDIA GPU：


nvidia-smi 返回 NO_NVIDIA_GPU

torch.cuda.is_available() = false


已确认真实 smoke 当前处于 CPU 训练阶段，且持续推进：


训练命令输出目录：/tmp/fma_real_smoke_stopcheck/fma_models_smoke

当前 checkpoint 时进度已推进到 Epoch 1 step 836/3201


验证结果：


check-local-ready fma ... => ready_for_smoke=true


validate-splits /tmp/fma_real_smoke_stopcheck/fma/manifests => ok=true


train.py 进程仍在运行，ELAPSED≈08:22


结论：


真实 FMA 数据已经不只是“可检查”，而是已进入真实端到端 smoke 执行。
当前慢的主因是“无 GPU + 真实 FMA 规模较大”，不是流程卡死。

fma_models_smoke 目录暂时无文件是正常现象；按当前 train.py 逻辑，best_model.pt 会在 Epoch 1 结束后首次落盘。


2026-06-02 Python 缓存噪音忽略规则补齐 checkpoint

完成项：


已把以下常见未跟踪缓存噪音加入 .gitignore：


acr-engine/__pycache__/
acr-engine/**/__pycache__/
acr-engine/**/*.pyc


结论：


下次续跑时，未跟踪的 Python 缓存噪音会进一步减少。
已跟踪的历史产物仍会显示，这次不改动其版本管理状态。


2026-06-02 本地噪音忽略规则补齐 checkpoint

完成项：


已把以下本地生成噪音加入 .gitignore：


acr-engine/.omx_wait_for_fma.log
acr-engine/.omx_wait_for_fma.pid
acr-engine/configs/manifests/examples/business_asset_export_real_smoke.csv


结论：


下次续跑时，git status 会少掉一批已知临时文件干扰。
这次只收敛已确认的本地生成噪音，不改变任何数据内容。


2026-06-02 delivery handoff 命令格式统一 checkpoint

完成项：


已把 docs/delivery-handoff-2026-06-02.md 中的最短可跑命令格式统一到与其他主入口一致。


结论：


AGENT.md / docs/README.md / docs/session-handoff.md / docs/delivery-handoff-2026-06-02.md 现在都包含同一条格式一致的第一验证命令。


2026-06-02 session handoff 补齐第一条可跑命令 checkpoint

完成项：


已把完整的最短可跑命令补入 docs/session-handoff.md。
四个主入口现在都包含同一条第一验证命令。


结论：


新 session 即使先打开 session-handoff.md，也能直接执行第一条验证命令，而不必再跳转查找。


2026-06-02 delivery handoff 同步最短可跑命令 checkpoint

完成项：


已把最短可跑命令同步到 docs/delivery-handoff-2026-06-02.md。
现在 AGENT / README / session-handoff / delivery-handoff 四处入口已一致。


结论：


新 session 无论先看哪个主要交接入口，都能立刻拿到第一条验证命令。


2026-06-02 AGENT 记忆同步最短可跑命令 checkpoint

完成项：


已把 business_export_offline_smoke.py 的最短可跑命令同步到 AGENT.md。
已让 README 与 AGENT 的重启入口保持一致。


结论：


下次新 session 启动时，不仅 docs 能找到最短验证命令，AGENT 记忆里也能直接看到。


2026-06-02 总览页补齐最短可跑命令 checkpoint

完成项：


已在 docs/README.md 补入“新 session 最短可跑命令”。
已再次重跑 business_export_offline_smoke.py，确认离线 smoke 仍可通过。


验证结果：


catalog_refs=2
train_queries=1
test_queries=1
val_queries=0
dry_run_passed=true


结论：


现在新 session 不仅知道先读什么，也知道先跑什么来验证环境与链路。


2026-06-02 总览页一致性与最短阅读顺序 checkpoint

完成项：


修正 docs/README.md 中“4 组/5 组”表述不一致问题。
新增“新 session 最短阅读顺序”，明确交接优先级。


结论：


现在总览页不仅能分组导航，也能直接告诉接手者先读什么。
文档入口自洽性进一步增强。


2026-06-02 总览页补齐业务导出链入口 checkpoint

完成项：


已更新 docs/README.md，把业务数据接入链提升为独立导航分组。
已在总览页直接给出业务导出最短链与离线 smoke 入口。


结论：


新 session 不需要再从大量文档中手动拼出业务接入顺序。
文档总览已能同时覆盖开放数据链与业务数据链。


2026-06-02 业务导出离线 smoke 实跑通过 checkpoint

完成项：


已实际运行 acr-engine/scripts/business_export_offline_smoke.py。
已确认链路从业务导出样例 -> manifest-ready JSONL -> 项目 manifest -> train.py --dry-run 全部跑通。


验证结果：


input_rows=5
output_rows=5
roles=reference/query/excluded

buckets=lossless_reference_core/short_video_hook/demo_variation_pool

catalog_refs=2
train_queries=1
test_queries=1
val_queries=0
dry_run_passed=true


结论：


业务导出离线适配链已经具备真实可运行证据，而不只是模板与脚本集合。
下个 session 可以直接替换成真实业务导出数据，沿同一链路继续推进。


2026-06-02 项目 manifest 适配脚本交付 checkpoint

完成项：


新增 acr-engine/scripts/build_business_project_manifests.py

新增 docs/business-project-manifest-adapter.md

已把业务导出链推进到可直接生成项目 catalog/train/test/val 的阶段。


结论：


下个 session 已基本不需要再手工拼项目 manifest。
从业务导出到项目 manifest 的离线适配链已经成型。


2026-06-02 manifest-ready 角色拆分脚本交付 checkpoint

完成项：


新增 acr-engine/scripts/split_business_manifest_ready.py

已把业务规范化输出继续推进为 reference/query/excluded 三类 JSON 清单。


结论：


下个 session 从业务导出到角色拆分已经形成连续脚本链路。
后续只需要补最终项目 manifest 适配，而不必再手工分角色。


2026-06-02 业务导出规范化脚本交付 checkpoint

完成项：


新增 acr-engine/scripts/normalize_business_export.py

已把业务导出 cookbook 从“样例说明”推进为“可运行转换脚本 + 样例输入”。


结论：


下个 session 可以直接把业务 CSV/JSONL 导出转成 manifest-ready JSONL。

type -> role -> bucket 默认规则现在不只是文档约定，也有可执行脚本承接。


2026-06-02 业务导出 cookbook 与样例交付 checkpoint

完成项：


新增 docs/business-export-cookbook.md

新增 CSV 样例：acr-engine/configs/manifests/examples/business_asset_export_example.csv

新增 JSONL 样例：acr-engine/configs/manifests/examples/business_asset_export_example.jsonl


结论：


下个 session 已有 SQL 字段映射参考，以及 CSV/JSONL 中间格式样例。
从业务库表到 manifest 的最后一段人工理解成本继续降低。


2026-06-02 业务 manifest 与 type-role 规范交付 checkpoint

完成项：


新增 docs/business-manifest-and-type-role-spec.md

新增 acr-engine/configs/manifests/business_asset_manifest_template.json

新增 acr-engine/configs/manifests/business_type_role_mapping.json

新增 acr-engine/scripts/print_business_type_mapping.py


结论：


下个 session 已可直接从业务库表导出 manifest 所需字段。

type -> role(reference/query/excluded) -> bucket 现在已经有 repo-native 默认规则，不需要再从聊天记录反推。


2026-06-02 业务素材 type→bucket 指南交付 checkpoint

完成项：


新增业务素材类型与 bucket 说明文档：docs/business-music-bucket-and-type-guide.md

新增业务素材 bucket 模板：acr-engine/configs/buckets/business_type_bucket_template.json

已把该入口接回 pgvector 指南、开放数据工作流和 session handoff。


首批业务 bucket：


lossless_reference_core
compressed_reference_realworld
short_video_hook
with_harmony_shift
demo_variation_pool
hard_negative_confusable


结论：


现在不仅有通用语义 bucket 模板，也有贴近你们素材 type 的业务 bucket 模板。
下个 session 可以直接按照素材 type 做训练/评测分层，而不必再从表结构重新推导。


2026-06-02 语义 bucket 模板交付 checkpoint

完成项：


新增语义 bucket 配置模板：acr-engine/configs/buckets/fma_semantic_bucket_template.json

已把模板入口与运行命令补入 workflow / benchmark / handoff 文档。


模板覆盖的首批 bucket：


energy_dominant
repeated_section_rich
steady_beat_regular_meter
hard_negative_confusable


结论：


现在下个 session 不需要从 0 设计 bucket 结构。
可以直接在模板里替换 glob，开始做更有业务意义的 bucket benchmark。


2026-06-02 bucket/style-aware benchmark 汇总完成 checkpoint

完成项：


已确认 bucket/style-aware benchmark 的完整 report.json 生成完成。
已确认两个最小 bucket 都已完成并各自产出 bucket_report.json。
已把“bucket 基线已可运行”推进为“bucket 基线已有完整汇总结果”。


最终结果（toy bucket smoke, seed=42）：


prefix_000_a：winner=hybrid


prefix_000_b：winner=high_energy

aggregate：


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


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


结论：


这个最小 bucket smoke 再次证明：当前不存在单一全局默认策略。
bucket winner 已经出现分化，后续必须转向更有语义的 bucket（风格 / 结构 / hard-case），而不是继续只看单一 cap 分数。
现阶段可稳定对外表述为：


high_energy 在 cap48 三 seed 聚合下更稳

hybrid 在 cap64 单 seed 下更强
bucket 基线已能解释“不同子集出现不同 winner”的现象，但当前 bucket 仍只是 toy prefix bucket


2026-06-02 bucket/style-aware benchmark 基线落地 checkpoint

完成项：


新增 acr-engine/scripts/ab_smoke_bucketed.py，用于按 bucket 配置批量驱动现有 ab_smoke_segmentation.py。
新脚本已通过 py_compile。
已完成最小 smoke 验证：首个 bucket prefix_000_a 已成功产出 bucket_report.json。


验证证据：


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

首个 bucket 结果：


prefix_000_a

hybrid: num_queries=4, top1=1.0, topk=1.0


high_energy: num_queries=3, top1=1.0, topk=1.0

winner: hybrid


当前第二个 bucket prefix_000_b 仍在运行中。


说明：


这次提交的重点是把 bucket/style-aware benchmark 从“待办”推进为“已存在可运行基线”。
完整 bucket 汇总 report.json 尚未生成，因此当前只把它视作基线工具完成与首桶 smoke 通过。


2026-06-02 cap64 完结 checkpoint

完成项：


cap64 真实 FMA 对照已完成。
已拿到 high_energy 与 hybrid 的最终评测结果与 winner。


最终结果（cap64, seed=42）：


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


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

winner：hybrid


结论：


cap64 与 cap48 给出了不同结论：


cap48 三 seed 下 high_energy 更稳且领先
cap64 当前单 seed 下 hybrid 明显领先


这说明默认策略判断已经进入“依赖子集规模 / 数据构成”的阶段。
下一步必须进入：


bucket/style-aware benchmark
更系统的 hard-case / genre bucket 评测


2026-06-02 cap64 hybrid 索引完成并进入评测 checkpoint

完成项：


已确认 cap64 的 hybrid reference index 构建完成。
已确认流程从 hybrid build-index 推进到 hybrid evaluate.py。


验证证据：


hybrid/fma_index_smoke/reference_progress.json：


status=complete
refs_done=64
windows_done=657
embedding_shape=[657, 192]
elapsed_sec=107.228


进程树显示：


evaluate.py --data /tmp/ab_smoke_seg_cap64_top2/hybrid/fma/manifests ... --seed 42 --max-queries 32


截至本 checkpoint：


hybrid eval.json 尚未生成
总 report.json 尚未生成


2026-06-02 cap64 hybrid 训练完成证据 checkpoint

完成项：


追加记录 cap64 的 hybrid 训练完成证据。
已从运行会话直接确认 hybrid 的 Epoch 1/1 从 0/32 推进到 32/32 完成。
当前进程仍处于 run_demo.py build-index 阶段。


验证证据：


运行会话输出显示：Epoch 1 完整跑完。
当前进程显示：run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/hybrid/fma/manifests ...


2026-06-02 cap64 hybrid 进入 build-index checkpoint

完成项：


已确认 cap64 的 hybrid 分支完成训练并进入 run_demo.py build-index。

hybrid/fma_models_smoke/best_model.pt 已写出。


验证证据：


当前进程显示：


run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/hybrid/fma/manifests ...


产物已存在：


/tmp/ab_smoke_seg_cap64_top2/hybrid/fma_models_smoke/best_model.pt


截至本 checkpoint：


hybrid 的 eval.json 尚未生成
总 report.json 尚未生成


2026-06-02 cap64 hybrid 训练启动 checkpoint

完成项：


追加记录 cap64 的第二个策略分支已经启动。
已确认主流程从 manifest_tools.py audio-dir-to-splits 进入 hybrid train.py。


验证证据：


当前进程显示：


external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/hybrid
train.py --data /tmp/ab_smoke_seg_cap64_top2/hybrid/fma/manifests ... --segment-strategy hybrid


截至本 checkpoint：


hybrid 的 eval.json 尚未生成
总 report.json 尚未生成


2026-06-02 cap64 high_energy 首个结果 checkpoint

完成项：


已拿到 cap64 中 high_energy 的首个评测结果。
主流程已从 high_energy 切换到 hybrid 分支，说明 cap64 仍在继续。


验证证据：


high_energy/fma_reports_smoke/eval.json：


num_queries=32
top1=0.625
topk=1.0


progress.json 已同步记录同一结果。
当前进程显示：


external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/hybrid
manifest_tools.py audio-dir-to-splits ... --query-strategy hybrid


说明：


截至本 checkpoint，hybrid 结果尚未生成，总 report.json 也尚未生成。


2026-06-02 cap64 索引完成并进入评测 checkpoint

完成项：


已确认 cap64 的 high_energy reference index 构建完成。
已确认流程从 build-index 推进到 evaluate.py。


验证证据：


reference_progress.json：


status=complete
refs_done=64
windows_done=657
embedding_shape=[657, 192]
elapsed_sec=108.986


进程树显示：


evaluate.py --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ... --seed 42 --max-queries 32


截至本 checkpoint：


report.json 仍未生成


2026-06-02 cap64 训练完成证据 checkpoint

完成项：


追加记录 cap64 的更强 fresh evidence。
已从运行会话直接确认 high_energy 的 Epoch 1/1 训练完整跑完。
当前主流程仍停留在 run_demo.py build-index，尚未进入 evaluate.py。


验证证据：


运行会话输出显示：Epoch 1 从 0/32 推进到 32/32 完成。
进程树仍显示：run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ...


2026-06-02 cap64 进入 build-index checkpoint

完成项：


追加记录 cap64 benchmark 的阶段推进。
已确认 high_energy 分支不再停留在训练，而是进入 run_demo.py build-index。


验证证据：


进程树显示：


scripts/ab_smoke_segmentation.py --work-root /tmp/ab_smoke_seg_cap64_top2
external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/high_energy
run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ...


截至本 checkpoint：


cap64 report.json 仍未生成


2026-06-02 cap64 benchmark 启动 checkpoint

完成项：


已启动新的真实 FMA cap64 对照 benchmark。
本轮配置：subset_size=64, max_test_queries=32, seed=42。
当前已确认流程进入 high_energy 训练阶段。


验证证据：


主进程：scripts/ab_smoke_segmentation.py --work-root /tmp/ab_smoke_seg_cap64_top2

子流程：external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/high_energy

当前训练：train.py --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ... --segment-strategy high_energy


说明：


截至本 checkpoint，cap64 结果尚未生成。
本次提交的目的是为下一 session 固化新一轮 benchmark 已正式启动的证据。


2026-06-02 cap48 seed999 完结与三 seed 聚合 checkpoint

完成项：


cap48 top2 seed=999 最终完成。
已拿到 high_energy 与 hybrid 的最终评测结果。
已完成 cap48 三个 seed 的 aggregate 汇总，并更新默认策略表述。


最终结果（seed=999）：


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


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

winner：high_energy


cap48 三 seed aggregate：


high_energy：


mean_top1=0.9167
min_top1=0.9167
max_top1=0.9167
stdev_top1=0.0


hybrid：


mean_top1=0.8750
min_top1=0.7917
max_top1=0.9583
stdev_top1=0.0680


结论：


在当前 cap48 真实 FMA smoke 条件下，high_energy 已展现出比 hybrid 更高且更稳定的 top1。
默认优先策略表述从“等待更多 seed”推进为：


cap48 条件下优先 high_energy


hybrid 继续作为优化与对照对象


2026-06-02 seed999 中间结果 checkpoint（hybrid 已落盘）

完成项：


记录 cap48 top2 seed=999 中 hybrid 的已完成评测结果。
确认 hybrid 结果已经写入 progress.json，而总 report.json 仍待 high_energy 完成后生成。


验证证据：


hybrid/fma_reports_smoke/eval.json：


num_queries=24
top1=0.875
topk=1.0


/tmp/ab_smoke_seg_cap48_top2_seed999/progress.json 已记录同一结果。
当前进程已切换到：


high_energy 的 run_demo.py build-index


说明：


截至本 checkpoint，三 seed aggregate 仍不能最终更新，因为 high_energy 的 seed=999 还未完成。


2026-06-02 运行中 benchmark 新证据 checkpoint

完成项：


追加记录 cap48 top2 seed=999 的新鲜运行证据。
已确认流程并未卡死在 hybrid build-index，而是继续推进到 evaluate.py。
已记录 reference index 完成指标：48 refs / 491 windows / 192-d embedding。


验证证据：


reference_progress.json 显示：


status=complete
refs_done=48
windows_done=491
embedding_shape=[491, 192]
elapsed_sec=80.26


进程树显示：


evaluate.py ... --seed 999 --max-queries 24 正在运行


说明：


截至本 checkpoint，/tmp/ab_smoke_seg_cap48_top2_seed999/report.json 仍未生成。
因此本次仍不更新 3-seed aggregate 结论。


2026-06-02 交付检查点：handoff / changelist / agent memory

完成项：


新增根目录 AGENT.md，固化当前开发偏好、提交习惯、续跑优先级与避坑约束。
新增 docs/changelist-2026-06-02.md，用于本次交付文件级变更说明。
新增 docs/delivery-handoff-2026-06-02.md，用于新 session 快速接管。
补充 docs/session-handoff.md：明确当前卡点、运行中的 benchmark、下一步命令与禁止误提交项。


当前卡点：


cap48 top2 seed=999 benchmark 仍在运行中，尚未产出最终 report.json。
仓库存在大量未跟踪数据与模型产物，当前阶段只适合提交文档。


交付说明：


本次提交以“可续跑交接”为目标，不等待长时 CPU benchmark 完成。
下一 session 进入后应优先检查：


/tmp/ab_smoke_seg_cap48_top2_seed999/report.json
相关 eval.json

进程是否仍在运行


Changelog


2026-06-02


Stage: 汇总 cap48 两次 seed 的聚合指标

完成项：


汇总：


/tmp/ab_smoke_seg_cap48_top2/report.json
/tmp/ab_smoke_seg_cap48_top2_seed123/report.json


计算 cap48 当前 2 次 seed 的聚合指标
更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


cap48 聚合结果（2 次 seed）：


high_energy:


mean_top1 = 0.9167
min_top1 = 0.9167
max_top1 = 0.9167
stdev_top1 = 0.0


hybrid:


mean_top1 = 0.8750
min_top1 = 0.7917
max_top1 = 0.9583
stdev_top1 = 0.0833


结论：


仅看 cap48 当前两次 seed，high_energy 的均值与稳定性更占优

hybrid 的表现波动更大，但峰值更高
当前最稳妥的策略判断应升级为：


单轮结果不可信
默认策略应参考多 seed 聚合

下一步继续扩展 seed 数或 style-aware bucket 比单纯再加单轮更有价值


Stage: 收尾 cap48 seed123 并确认 cap48 对 seed 敏感

完成项：


读取 /tmp/ab_smoke_seg_cap48_top2_seed123/report.json

读取：


/tmp/ab_smoke_seg_cap48_top2_seed123/hybrid/fma_reports_smoke/eval.json
/tmp/ab_smoke_seg_cap48_top2_seed123/high_energy/fma_reports_smoke/eval.json


更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


最终结果（subset=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


结论：


cap48 在不同 seed 下已经出现明显不同排序：


默认 seed：high_energy > hybrid


seed=123：hybrid > high_energy


这意味着 cap48 当前最可靠的结论不是“谁绝对赢”，而是：


该对比对 seed/抽样敏感
当前默认策略判断必须依赖多 seed 聚合结果

hybrid 仍可保留为保守默认，high_energy 仍是强竞争方案


Stage: 启动 cap48 第二个 seed 复核反转结果

完成项：


启动第二个 seed 的 cap48 top2 benchmark：


work_root = /tmp/ab_smoke_seg_cap48_top2_seed123
subset_size = 48
max_test_queries = 24
seed = 123
策略：hybrid vs high_energy


更新 session-handoff.md


当前 fresh evidence：


第二个 seed 已启动

hybrid 已完成首条评测：


num_queries = 24
top1 = 0.9583
topk = 1.0


high_energy 已进入：


run_demo.py build-index --resume --checkpoint-every-refs 100


结论：


已经从“单轮 cap48 反转”升级为“开始做多 seed 复核”
即使当前 session 结束，新 session 也可直接从 handoff 中的 cap48_top2_seed123 入口继续


Stage: 收尾 cap48 top2 真实 FMA 对照并发现 high_energy 反超

完成项：


读取 /tmp/ab_smoke_seg_cap48_top2/report.json

读取：


/tmp/ab_smoke_seg_cap48_top2/hybrid/fma_reports_smoke/eval.json
/tmp/ab_smoke_seg_cap48_top2/high_energy/fma_reports_smoke/eval.json


更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


最终结果（subset=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


结论：


cap48 与 cap24 / cap32 给出了不同方向的结果
这意味着“默认策略已经完全固定为 hybrid”的说法需要降级为暂时性结论

当前更稳妥的表述应是：


hybrid 仍可保留为保守默认

high_energy 已成为必须严肃对待的强竞争方案
下一步需要更大样本 / 多 seed / style-aware benchmark 再定最终默认


Stage: 启动 cap48 top2 真实 FMA 对照并记录运行阶段

完成项：


启动更大的真实 FMA top2 benchmark：


work_root = /tmp/ab_smoke_seg_cap48_top2
subset_size = 48
max_test_queries = 24
策略：hybrid vs high_energy


更新 session-handoff.md


当前 fresh evidence：


scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap48_top2 已启动

hybrid 已完成首条评测：


num_queries = 24
top1 = 0.7917
topk = 1.0


high_energy 已进入：


evaluate.py --data /tmp/ab_smoke_seg_cap48_top2/high_energy/fma/manifests ... --max-queries 24


report.json 尚未落盘


结论：


现在已经开始验证 cap24 / cap32 的结论在更大 subset=48 上是否继续成立
即使当前 session 结束，新 session 也可直接从 handoff 中的 cap48 入口继续盯结果


Stage: 收尾 cap32 top2 真实 FMA 对照并稳定默认策略结论

完成项：


读取 /tmp/ab_smoke_seg_cap32_top2/report.json

读取：


/tmp/ab_smoke_seg_cap32_top2/hybrid/fma_reports_smoke/eval.json
/tmp/ab_smoke_seg_cap32_top2/high_energy/fma_reports_smoke/eval.json


更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


最终结果（subset=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


结论：


cap32 继续强化 cap24 的结论：hybrid 明显优于 high_energy

当前默认训练 / query 策略可以稳定固定为 hybrid


high_energy 更适合作为专项对照策略，而非默认策略


Stage: 启动 cap32 top2 真实 FMA 对照并记录运行阶段

完成项：


启动更大的真实 FMA top2 benchmark：


work_root = /tmp/ab_smoke_seg_cap32_top2
subset_size = 32
max_test_queries = 20
策略：hybrid vs high_energy


更新 session-handoff.md


当前 fresh evidence：


scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap32_top2 已启动

hybrid 已完成首条评测：


num_queries = 20
top1 = 0.95
topk = 1.0


high_energy 已进入训练阶段

report.json 尚未落盘


结论：


现在已经开始验证 cap24 结论在更大 subset=32 上是否继续成立
当前至少可以确认：hybrid 在更大子集上仍保持较强表现
即使当前 session 结束，新 session 也可直接从 handoff 中的 cap32 入口继续盯结果


Stage: 收尾 cap24 top2 真实 FMA 对照并确认默认策略

完成项：


读取 /tmp/ab_smoke_seg_cap24_top2/report.json

读取 /tmp/ab_smoke_seg_cap24_top2/high_energy/fma_reports_smoke/eval.json

更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


最终结果（subset=24, max_test_queries=16）：


hybrid: num_queries=16, top1=1.0, topk=1.0


high_energy: num_queries=16, top1=0.8125, topk=1.0


结论：


cap24 比 cap16 更有区分度，hybrid 不再只是与 high_energy 打平
当前默认训练 / query 策略应明确固定为 hybrid


high_energy 更适合作为补充对照或偏高能区数据的次选策略


Stage: 启动更大 cap24 top2 真实 FMA 对照并记录首条结果

完成项：


启动：


/tmp/ab_smoke_seg_cap24_top2
策略仅保留 hybrid 与 high_energy

subset_size = 24
max_test_queries = 16


更新 session-handoff.md


当前 fresh evidence：


hybrid 已完成：


num_queries = 16
top1 = 1.0
topk = 1.0


high_energy 已进入训练阶段，整轮对照尚未完成


结论：


在比 cap16 更大的真实 FMA 子集上，hybrid 目前仍保持满分
下一步只需等待 high_energy 完成，就能判断两者在更大子集上是否继续打平或拉开


Stage: 收尾 cap16 真实 FMA capped segmentation benchmark

完成项：


读取 /tmp/ab_smoke_seg_cap16/report.json

确认 repeated_section_aware 最终评测结果
更新：


open-dataset-workflow.md
session-handoff.md
CHANGELOG.md


最终结果（subset=16, max_test_queries=12）：


hybrid: num_queries=12, top1=1.0, topk=1.0


high_energy: num_queries=12, top1=1.0, topk=1.0


beat_aware: num_queries=12, top1=0.9167, topk=1.0


repeated_section_aware: num_queries=12, top1=0.8333, topk=1.0


结论：


在固定 query 预算下，hybrid 仍是当前默认首选

high_energy 是最强次选，并且与 hybrid 在这轮 cap16 上打平

beat_aware 与 repeated_section_aware 单独使用时不如混合策略稳定


Stage: 交付当前切片 benchmark 续跑 handoff

完成项：


更新 session-handoff.md

记录最新关键提交：


6232787
f04a314
d7a0894
b6cdf66


记录中规模真实 FMA capped benchmark 的续跑入口
写入当前已拿到的 partial result：


hybrid: num_queries=12, top1=1.0, topk=1.0


beat_aware: num_queries=12, top1=0.9167, topk=1.0


high_energy: num_queries=12, top1=1.0, topk=1.0


验证结果：


当前进程确认：


scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap16

repeated_section_aware 策略仍在进行中


已落盘评测文件确认：


/tmp/ab_smoke_seg_cap16/hybrid/fma_reports_smoke/eval.json
/tmp/ab_smoke_seg_cap16/beat_aware/fma_reports_smoke/eval.json
/tmp/ab_smoke_seg_cap16/high_energy/fma_reports_smoke/eval.json


结论：


当前 session 即使立即中断，也已经具备可恢复的续跑交接材料
新 session 可以直接从 /tmp/ab_smoke_seg_cap16 和 docs/session-handoff.md 接手，而不需要重新梳理上下文


Stage: 为切片策略评测补齐公平 query cap，并澄清 librosa 分段现状

完成项：


修改 acr-engine/evaluate.py


新增 --max-queries

新增 --seed

允许评测前对 query 集进行可复现随机抽样


修改 acr-engine/src/data/external_adapters.py


smoke-local 新增 --max-test-queries

自动透传到 evaluate.py --max-queries

smoke 配置摘要同步记录 cap 信息


修改 acr-engine/scripts/ab_smoke_segmentation.py


新增 --max-test-queries

可在策略 A/B smoke 中统一限制 query 预算


更新文档：


open-dataset-workflow.md
dataset-spec.md
training-data-and-pgvector-guide.md


文档中额外澄清：


当前切片不是只有 random

已经接入 librosa.effects.split / onset_detect / beat_track / chroma_cqt

但尚未把更重的 librosa.segment.* 结构分段作为默认主流程


验证结果：


语法检查：


/usr/local/miniconda3/bin/python -m py_compile evaluate.py src/data/external_adapters.py scripts/ab_smoke_segmentation.py


单点评测验证：


evaluate.py --max-queries 5 --seed 123
输出 num_queries = 5

top1 = 1.0
topk = 1.0


端到端 smoke 验证：


scripts/ab_smoke_segmentation.py --strategies hybrid --max-test-queries 5
最终报告：
max_test_queries = 5
num_queries = 5
top1 = 1.0
topk = 1.0


结论：


现在策略 A/B 不再只能比较“谁生成的 query 更多”
已经可以在统一 query 成本预算下比较不同切片策略
当前项目也已明确进入“random + librosa 音乐感知候选”的混合切片阶段，而不是纯随机切片阶段


Stage: 为内部素材 query 自动补 duration / offset 规则

完成项：


扩展 acr-engine/scripts/internal_asset_type_mapper.py


新增 --duration-field

新增 --offset-field

新增 --default-query-duration

新增 --default-query-offset


规则更新：


query 优先使用 CSV 提供的 duration/offset

无 CSV duration 时，优先使用音频探测时长
无 CSV offset 时，使用默认 offset


pgvector payload 同步使用生成后的 duration/offset


验证结果：


用 3 行样例 CSV 验证：


song_a 短视频 query 使用 CSV 值：
duration = 5.0
offset = 12.5

song_c demo query 使用自动回填：
duration = 6.5
offset = 0.0


pgvector_payload.json 中的 segments 也已同步带上正确 offset_sec/duration_sec


结论：


现在内部素材 query 已经不再只能输出“空 offset”
对短视频片段、demo、后续回流片段的训练和入库更接近真实可用状态


Stage: 为内部素材映射脚本增加 pgvector-ready JSON 导出

完成项：


扩展 acr-engine/scripts/internal_asset_type_mapper.py


新增 --emit-pgvector-json

新增 --pgvector-split


可直接导出：


pgvector_payload.json


导出结构与现有 pgvector 导出工具兼容，包含：


songs
references
segments


同时额外保留：


audio_role
asset_type_code
audio_exists
validation_status


验证结果：


运行：


internal_asset_type_mapper.py ... --emit-pgvector-json --pgvector-split train


输出摘要：


pgvector_songs = 2
pgvector_references = 2
pgvector_segments = 2


抽样检查：


reference 行含 duration_sec/sample_rate/audio_role/asset_type_code

segment 行含 offset_sec/split/type/segment_type/audio_role


结论：


现在内部素材 CSV 已经可以直接桥接到 pgvector 入库准备阶段
后续再补 loader 或数据库直写时，不需要重新设计内部素材导出结构


Stage: 为内部素材映射脚本增加音频存在性与时长校验

完成项：


扩展 acr-engine/scripts/internal_asset_type_mapper.py


新增 --audio-root

自动探测 audio_exists

自动探测 duration_sec

自动写入 validation_status


在 summary 中新增：


missing_audio
trainable_audio_rows


更新 training-data-and-pgvector-guide.md


验证结果：


构造了 6 行样例 CSV，其中 4 个真实音频、2 个缺失路径
运行：


internal_asset_type_mapper.py ... --audio-root /tmp/internal_assets_audio --emit-manifests


输出摘要：


missing_audio = 2
trainable_audio_rows = 4


生成的 reference/query 记录已带：


audio_exists = true
validation_status = ok
正确的 duration


结论：


现在内部素材 CSV 到 manifest 的链路已经具备最基础的训练前质量校验
后续再补 offset / 更细粒度质量规则时，不需要推翻现有脚本结构


Stage: 让内部素材映射脚本直接输出 train/test manifests

完成项：


扩展 acr-engine/scripts/internal_asset_type_mapper.py


新增 --emit-manifests

新增 --eval-ratio

新增 --seed


在原有 references/queries/metadata_only/excluded 基础上，新增：


manifest_bundle/catalog.json
manifest_bundle/train.json
manifest_bundle/test.json
manifest_bundle/val.json


增加小样本保护：


即使 query 很少，也尽量保证 train/test 都有 query


更新 training-data-and-pgvector-guide.md


验证结果：


使用 6 行样例 CSV 执行：


internal_asset_type_mapper.py ... --emit-manifests --eval-ratio 0.5 --seed 42


输出摘要：


manifest_bundle 已生成
manifest_train_rows = 3
manifest_test_rows = 3
manifest_val_rows = 0


manifest 检查：


catalog：2 references

train：1 query + 2 references

test：1 query + 2 references


结论：


现在内部素材 CSV 已经可以一步变成接近可训练的 manifest bundle
后续如果再补充 duration/offset/audio existence 校验，就能更平滑接入正式训练链路


Stage: 将内部素材 type 策略落成可执行映射脚本

完成项：


新增 acr-engine/scripts/internal_asset_type_mapper.py

支持从内部素材 CSV 自动分流到：


references.json
queries.json
metadata_only.json
excluded.json


支持 --include-conditionals-as，可选把伴奏类临时导出成 query 或 reference

在 training-data-and-pgvector-guide.md 增加脚本入口说明


验证结果：


使用 6 行样例 CSV 验证：


11/1 -> references
7/18 -> queries
3 -> metadata_only
12 -> excluded


摘要输出：


references = 2
queries = 2
metadata_only = 1
excluded = 1


结论：


现在内部素材 type 策略已经不只在文档里，而是可以直接作为批量清洗入口使用
后续如果要从数据库导出 CSV 再转 manifest，已经有第一版可执行桥接脚本


Stage: 为内部素材 type 枚举补齐训练参与策略文档

完成项：


在 training-data-and-pgvector-guide.md 新增内部素材 type 映射章节
对用户给出的素材类型补齐：


主 reference 推荐
主 query 推荐
伴奏类的条件式参与策略
文本/图片/授权/压缩包的 metadata-only 策略


增加 canonical_song_id / version_id / asset_type_code / audio_role 的落库建议


验证结果：


文档中已出现以下关键锚点：


12. 你这批内部素材 type，哪些推荐参与训练
12.3 最推荐的主任务训练组合
instrumental_variant
short_video_clip


当前建议与现有数据规范保持一致：


reference / query 分离
伴奏版本默认不无脑并入原曲主标签
非音频资产不进入音频模型训练


结论：


现在这批内部资产已经有一套明确的训练白名单 / 条件白名单 / 元数据白名单
后续做批量导入或 pgvector 入库时，可以直接按文档映射执行


Stage: 为外部数据集接入增加 overlap query manifest 能力

完成项：


修改 acr-engine/src/data/manifest_tools.py


为 audio-dir-to-splits 增加 --query-stride

支持按 stride 为单首歌生成多个 query
新 query 记录增加 query_index


修改 acr-engine/src/data/external_adapters.py


prepare-local / smoke-local 透传 --query-stride

smoke 配置摘要里记录 manifest_query_stride


更新 open-dataset-workflow.md 与 dataset-spec.md


验证结果：


CLI 验证：


manifest_tools.py audio-dir-to-splits --help 已出现 --query-stride


小数据验证：


执行：
prepare-local fma data/synthetic_v2/songs --query-duration 8.0 --query-stride 4.0
返回：
train_queries = 57
test_queries = 15
解析 manifest 后得到：
num_queries = 72
sample_query.offset = 0.0
query_index = 0
max_query_index = 2


结论：


现在外部开源数据接入已经不再局限于“每首歌只采一个随机 query”
当需要更高覆盖率时，可以直接生成多 query / overlap query manifests，用于更稳定的训练与评测


Stage: 显式拆分 smoke 配置里的 8s query 与 5s training segment 语义

完成项：


修改 acr-engine/src/data/external_adapters.py


新增 load_default_training_config()

新增 build_smoke_config_summary()

让 smoke-local 产出的 config.json 显式记录：
manifest_query_duration
train_segment_duration
sample_rate
n_fft
hop_length
query_duration_legacy


更新 training-data-and-pgvector-guide.md，说明新旧配置口径


验证结果：


通过直接调用 build_smoke_config_summary() 验证输出：


manifest_query_duration = 8.0
train_segment_duration = 5.0
requested_device = auto
resolved_device = cpu


默认训练配置读取自：


configs/default.yaml
其中 data.segment_dur = 5.0


结论：


现在 smoke 配置摘要已经能明确区分“manifest 的 query 时长”和“训练 clip 时长”
后续即使 report 产物跨实验对比，也更容易避免 5s/8s 语义混淆


Stage: 将连续开发偏好与当前进度固化到 AGENTS.md

完成项：


在根级 AGENTS.md 新增 Project Continuity Memory / 持续开发记忆

记录用户长期偏好：


自动继续执行
每阶段更新 changelog 并 commit/push
使用 /usr/local/miniconda3/bin/python

文档优先图表/表格/相对路径链接/浓缩结构


记录当前项目方向、真实 FMA 数据状态、smoke-local 设备能力、当前宿主机无 CUDA 的事实
记录最近完成的工程阶段与建议下一步，方便新 session 直接续做


验证结果：


AGENTS.md 已可检索到以下关键记忆锚点：


Project Continuity Memory
smoke-local
fma_small_audio
torch.cuda.is_available() == False
Highest-value next steps


新增内容与当前代码/文档状态一致：


smoke-local 已支持 --device cpu|cuda|auto

build-index 进度日志增强已完成
当前真实 FMA 长跑仍位于 CPU build-index 阶段


结论：


现在新 session 启动时，不需要重新摸索用户偏好、数据目录、当前瓶颈与下一步计划

AGENTS.md 已承担仓库级连续开发记忆入口


Stage: 增强 build-index 进度可见性，降低真实 FMA 长跑误判成本

完成项：


修改 acr-engine/src/engines/ecapa_embedder.py


在 build_reference_index 中输出 start/progress/finish 日志
日志包含 refs、windows、elapsed_sec、eta_sec


修改 acr-engine/run_demo.py


在 build-index 阶段显式打印 chromaprint 与 embedding 两个阶段的开始提示


复核当前宿主机设备条件，确认本机当前无 CUDA，只能走 CPU


验证结果：


宿主机设备：


torch.cuda.is_available() = False
device_count = 0


小数据验证：


使用 /tmp/acr_smoke_device_test/fma/manifests 运行 PYTHONUNBUFFERED=1 /usr/local/miniconda3/bin/python run_demo.py build-index ... --device cpu

看到新的阶段日志：
[build-index] starting chromaprint index ...
[build-index] starting embedding index ...
[build-reference-index] start: refs=24 ...
[build-reference-index] progress: refs=1/24 ...
[build-reference-index] progress: refs=24/24 ...
结束时成功输出：
Built reference index: 120 windows, embeddings shape (120, 192)


真实 FMA 状态复检：


真实长跑仍停留在 run_demo.py build-index ... --device cpu

但当前可以明确判断它是在 CPU 上长时间构建 embedding index，而不是“无输出的假卡死”


结论：


现在真实 FMA 长跑的主要瓶颈已被明确定位为 CPU embedding index 构建
即使当前宿主机无 GPU，也已经具备了更可观测的长跑诊断能力，方便后续迁移到 CUDA 机器或继续做索引阶段优化


Stage: 让 smoke-local 支持显式设备选择并验证 auto 设备解析

完成项：


修改 acr-engine/src/data/external_adapters.py，为 smoke-local 增加 --device

增加 auto -> cpu/cuda 的内部解析，避免把字符串 auto 直接传给 embedding / eval 侧
将训练、建索引、评测三个子命令统一改为透传解析后的设备
在 smoke 配置摘要中记录 requested_device 与 resolved_device

同步更新 open-dataset-workflow.md 与 training-data-and-pgvector-guide.md


验证结果：


CLI 验证：


/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local --help 已出现 --device DEVICE


最小链路验证：


使用 data/synthetic_v2/songs 运行 smoke-local ... --device auto

训练阶段输出 Device: cpu，说明 auto 已被正确解析
随后手动验证后半段命令可正常运行：
run_demo.py build-index --device cpu
evaluate.py --device cpu

evaluate.py 返回：
top1=1.0
topk=1.0


真实 FMA 状态复检：


真实 FMA smoke 主进程仍存活
当前子进程停留在 run_demo.py build-index ... --device cpu


结论：


现在 smoke-local 已具备 GPU/CPU/auto 设备入口，可直接用于后续真实数据 GPU smoke
同时也暴露出新的后续任务：真实 FMA smoke 的后半段索引/产物生成仍需继续观察与优化


Stage: 补齐训练数据、重叠窗口、GPU 与 FMA 数据处理文档

完成项：


重写并压缩 dataset-spec.md，补齐训练切片、检索重叠滑窗、manifest 生成差异
扩展 training-data-and-pgvector-guide.md，补齐 FMA / MTG / 自有数据接入、目录规范、脚本职责、GPU 加速说明
明确记录当前真实代码事实：训练端 5s 随机裁剪、检索端 5s/2.5s 重叠滑窗、外部 manifest 默认 8s query
记录当前 smoke 现状：smoke-local 仍固定 CPU，真实 FMA smoke 正在运行
记录当前实验产物一致性风险：旧的 fma_reports_smoke/config.json 与最新 manifests 时间戳不一致，需后续统一配置治理


验证结果：


源码复核：


src/data/dataset.py：训练端随机 5s crop

src/utils/audio.py / src/engines/ecapa_embedder.py：5s window + 2.5s stride

src/data/manifest_tools.py：每首歌 1 个随机 query，默认 8.0s


src/data/external_adapters.py：smoke-local 当前硬编码 --device cpu


train.py：支持 --device auto，CUDA 路径支持 mixed precision


真实运行状态：


FMA smoke 进程仍在运行
最新可见进度约 82% epoch 1


文档链接验证：主文档仍使用相对路径链接到仓库文件与同组文档


结论：


当前项目关于训练数据格式、3 分钟 mp3 切片、是否重叠窗口、GPU 是否可显著加速、FMA 与开放数据如何复用流程，已形成可交接文档
后续可继续沿两条线推进：


让 smoke-local 支持 GPU
增加 overlap query manifest 生成能力


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 文档浓缩与相对链接跳转

完成项：


重构 docs/README.md 为 4 组主文档入口
将多处相对路径从反引号文本改为 Markdown 可点击链接
收拢“数据接入”阅读入口，降低文档数量感知
修正文档内对脚本、manifest、关联文档的跳转方式


验证结果：


入口文档现在按：


项目与架构
数据与评测
服务与工程
研究与路线
进行分组


dataset-spec.md / dataset-sources-and-licensing.md / industrialization-roadmap.md / service-api.md / industrial-benchmark-spec.md
已使用相对链接替代部分反引号路径


结论：


文档入口已明显浓缩
读者不再需要先面对大量平铺文件名
相对路径现在更适合直接跳转


Stage: 开放数据单页工作流

完成项：


新增 docs/open-dataset-workflow.md

把开放数据接入流程浓缩为：


inspect-local / inspect-batch
prepare-local
validate-local


将该工作流挂到 docs/README.md 的“数据与评测”组下


验证结果：


/usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-local fma data/synthetic_v2/songs --eval-ratio 0.2 --query-duration 5.0 成功

/usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open --eval-ratio 0.2 --query-duration 5.0 成功

/usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open/fma/manifests 成功
当前结果：


num_audio_files=24
catalog=24
train_queries=16
test_queries=8
ok=true


结论：


现在开放数据接入路径已经浓缩成单页可执行工作流
后续接真实 FMA / MTG-Jamendo 本地目录时，上手成本更低


Stage: 开放数据 manifests 直连训练

完成项：


修复 src/data/manifest_tools.py 生成的开放数据 manifests 路径自洽性
让开放数据音频复制到输出根下的 audio/

修复 src/data/dataset.py 对 .../manifests 目录布局的路径解析
打通 prepare-local -> validate-local -> train.py --dry-run


验证结果：


/usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open_fixed --eval-ratio 0.2 --query-duration 5.0 成功

/usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open_fixed/fma/manifests 成功

/usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 --dry-run 成功
当前结果：


catalog=24
train_queries=16
test_queries=8
Dry run passed!


结论：


开放数据路径现在不仅能生成 manifests，还能真正进入训练
后续接入真实 FMA / MTG-Jamendo 时，可以直接走同一链路


Stage: 开放数据完整 smoke 闭环（train/index/eval）

完成项：


修复 run_demo.py 对开放数据自包含布局的索引入口假设
修复 src/engines/ecapa_embedder.py / src/engines/chromaprint_matcher.py 对 reference 路径的硬编码筛选
修复 evaluate.py 对开放数据 query 与 manifests 根路径的解析
打通开放数据 prepare-local -> validate-local -> train -> build-index -> evaluate


验证结果：


/usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 成功

/usr/local/miniconda3/bin/python run_demo.py build-index --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --output data/index_open_smoke_fixed --device cpu 成功

/usr/local/miniconda3/bin/python evaluate.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --index-prefix data/index_open_smoke_fixed/reference --split test --device cpu --fast-eval --output-json reports/open-smoke-fixed/fma/eval.json 成功
当前结果：


num_queries=8
top1=1.0
topk=1.0


结论：


开放数据接入链路现在已经完整闭环
真实 FMA / MTG-Jamendo 本地目录接入时，可直接复用同一流程


Stage: 开放数据 smoke 发布制品

完成项：


为 reports/open-smoke-fixed/fma/ 补充 config.json

用 scripts/generate_artifacts.py 生成开放数据 smoke 的：


benchmark report
model card
release checklist
artifact manifest


验证结果：


/usr/local/miniconda3/bin/python scripts/generate_artifacts.py --eval-json reports/open-smoke-fixed/fma/eval.json --config-json reports/open-smoke-fixed/fma/config.json --output-dir reports/open-smoke-fixed/fma --model-version open-smoke-fixed --data-version synthetic_as_open_fixed_fma 成功
产物存在：


reports/open-smoke-fixed/fma/benchmark-report.md
reports/open-smoke-fixed/fma/model-card.md
reports/open-smoke-fixed/fma/release-checklist.md
reports/open-smoke-fixed/fma/artifact-manifest.json


结论：


现在开放数据链路已经不只是“能跑”，还具备基础发布/汇报产物
下一步替换成真实 FMA / MTG-Jamendo 本地目录后，可直接复用同一 release 流程


Stage: 一键 open-dataset smoke

完成项：


扩展 src/data/external_adapters.py

新增 smoke-local

一条命令自动执行：


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


验证结果：


/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
产物目录：data/external_smoke/fma_reports_smoke


结论：


现在只要替换 input_dir，就能对真实 FMA / MTG-Jamendo 本地目录跑完整 smoke
这显著降低了真实开放数据集接入和验证成本


Stage: 真实开放数据落点目录模板

完成项：


新增 acr-engine/data/raw/README.md

新建本地开放数据落点目录：


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


将这些目录入口链接接入开放数据工作流与 docs 总入口


验证结果：


本地目录已创建：


data/raw/
data/raw/fma_small_audio/
data/raw/mtg_jamendo_audio/


data/raw/README.md 已包含可直接执行的下一条 smoke 命令模板


结论：


现在真实开放数据只需要放进明确目录即可
后续替换真实 FMA / MTG-Jamendo 本地音频时无需再猜目录结构


Stage: 新 session 首次启动清单

完成项：


新增 acr-engine/FIRST_RUN_CHECKLIST.md

把最常用启动检查命令与读文档顺序固化到 repo
将 checklist 接入 docs/README.md 与 docs/session-handoff.md


验证结果：


FIRST_RUN_CHECKLIST.md 已创建
docs 入口已挂接 checklist


结论：


新 session 现在可以更快进入有效开发状态
启动成本和漏看关键文档/命令的风险进一步下降


Stage: 状态快照脚本

完成项：


新增 acr-engine/scripts/status_snapshot.py

统一输出：


latest commit
核心 docs 路径
真实数据 drop zones
已验证 smoke 目录
下一步推荐命令


将脚本接入 handoff 文档与 first-run checklist


验证结果：


/usr/local/miniconda3/bin/python scripts/status_snapshot.py 成功
输出已正确指向：


/workspace/docs/README.md
/workspace/docs/session-handoff.md
/workspace/docs/open-dataset-workflow.md


结论：


新 session 现在不只靠静态文档，也可以直接读取当前仓库状态快照
持续开发交接更稳


Stage: 状态快照落盘

完成项：


扩展 acr-engine/scripts/status_snapshot.py

新增 --output

可直接写入 .omx/latest_status_snapshot.json


验证结果：


/usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
已验证：


文件存在
JSON 可解析
包含 latest_commit

包含 next_commands


结论：


新 session 现在可以直接读取最近一次状态快照文件
交接信息更适合自动化和长期持续开发


Stage: FMA 完成前等待并自动切换

完成项：


新增 acr-engine/scripts/wait_for_fma_and_prepare.py

支持：


周期性检查 FMA archive 是否已完整
完整后自动调用 fma_postdownload_ready.py

未完成时返回结构化 waiting 快照


将脚本接入 docs/open-dataset-workflow.md 与 docs/session-handoff.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/wait_for_fma_and_prepare.py 成功

/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 2 --max-cycles 2 成功
当前结果：


第 1 次快照 archive_size=2110291968

第 2 次快照 archive_size=2115256320

status=waiting
最新进度 27.5439%


结论：


现在仓库已经具备“等待完成 -> 自动切入解压/就绪检查”的衔接能力
后续 session 可以用单命令挂起等待，而不是反复手工轮询


Stage: FMA 下载完成后自动就绪

完成项：


新增 acr-engine/scripts/fma_postdownload_ready.py

在 FMA 整包完成后，可自动执行：


extract
check-local-ready
inspect-local


将该脚本挂接到 docs/open-dataset-workflow.md 与 docs/session-handoff.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/fma_postdownload_ready.py 成功

/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 成功返回结构化结果
当前结果：


status=blocked
reason=archive_not_complete
archive_size=1631584256
progress_percent=21.2457


结论：


真实 FMA 下载一旦完成，仓库已经具备单命令进入“解压 + 本地就绪检查”的能力
后续 session 不需要再手工串接这些步骤


Stage: pgvector bulk load plan 模板

完成项：


新增 acr-engine/scripts/pgvector_bulk_load_template.py

为 pgvector 导出结果补充 PostgreSQL bulk-load plan 模板
在 docs/training-data-and-pgvector-guide.md 中补充对应说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/pgvector_bulk_load_template.py 成功

/usr/local/miniconda3/bin/python scripts/pgvector_bulk_load_template.py --input reports/pgvector_manifest_export_test.json --output reports/pgvector_bulk_load_plan_test.json 成功
当前结果：


songs=24
references=24
segments=20


结论：


pgvector 方向现在已经具备：


schema 模板
manifest 导出模板
bulk-load plan 模板


后续接真实 PostgreSQL 时，只差 live loader，而不是从零设计数据入口


Stage: pgvector 落库模板

完成项：


新增 acr-engine/sql/pgvector_schema.sql

新增 acr-engine/scripts/export_manifest_to_pgvector_json.py

在 docs/training-data-and-pgvector-guide.md 中补充可执行模板说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/export_manifest_to_pgvector_json.py 成功

/usr/local/miniconda3/bin/python scripts/export_manifest_to_pgvector_json.py --data data/synthetic_v2 --split test --source-dataset synthetic_v2 --output reports/pgvector_manifest_export_test.json 成功
当前导出结果：


songs=24
references=24
segments=20


结论：


pgvector 方向现在不仅有概念文档，还有可直接复用的 schema 和 manifest 导出桥接脚本
后续接 PostgreSQL 时返工成本会显著降低


Stage: FMA 下载自动守护

完成项：


新增 acr-engine/scripts/watch_fma_download.py

支持周期性：


inspect 当前下载进度
检查 curl 进程是否存活
如果停滞或进程消失则自动重新触发 bg-download


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/watch_fma_download.py 成功

/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 2 --interval 2 成功
当前 watcher 观测到：


第 1 次 archive_size=513179648

第 2 次 archive_size=516587520

两次 live_curl=true

两次 restarted=null（说明下载健康推进，无需重启）


最新 inspect：


archive_size=522387456
archive_progress_percent=6.8023


结论：


现在真实 FMA 下载不只可手动恢复，也具备基础自动守护能力
长时间下载的持续性进一步增强


Stage: 训练数据与 pgvector 专项文档

完成项：


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

单独详细说明：


当前训练数据/输入数据应该是什么格式

reference / query 的角色区分
BGM / 手机录音 / 直播录屏如何转成训练数据

song_id / type / offset / segment_type 等标签建议
未来接 pgvector 时的推荐表结构与字段设计


将该文档挂接到 docs/README.md 与 docs/session-handoff.md


验证结果：


文档内容已对齐当前代码行为：


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


已补充从“原始音频 -> 标准化资产 -> manifest -> pgvector”的完整分层说明


结论：


现在项目对“训练数据应该长什么样”与“以后怎么接 pgvector”已经有独立、可交接、可执行的文档说明


Stage: FMA 后台续传恢复

完成项：


为 acr-engine/scripts/prepare_fma_archive.py 新增 bg-download

使用 nohup curl + 日志文件的方式增强大文件后台续传稳定性
在发现下载停滞后，切换到新的后台恢复路径并重新托管 ModelScope 下载


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py bg-download 成功
当前返回：


returncode=0
pid=47175
log_path=/tmp/fma_modelscope_download.log


重新 inspect 后结果：


archive_size 从 61550592 增长到 71835648

archive_progress_percent=0.9354


日志验证：


Resuming transfer from byte position 61550592
当前吞吐已达到 MB/s 级别


结论：


FMA 真实数据下载不再依赖脆弱的一次性前台命令
当前已恢复到可持续的后台续传状态，后续 session 更容易接力


Stage: FMA 下载进度可视化

完成项：


增强 acr-engine/scripts/prepare_fma_archive.py 的 inspect 输出
新增：


archive_bytes_expected
archive_progress_ratio
archive_progress_percent


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_size=61550592
archive_progress_percent=0.8015


结论：


新 session 现在不需要手工换算大包下载进度
长时间 FMA 下载的交接成本进一步降低


Stage: FMA 源切换到 ModelScope

完成项：


将 acr-engine/scripts/prepare_fma_archive.py 的默认 FMA 整包源切换到用户提供的 ModelScope 地址
同步更新：


acr-engine/data/raw/README.md
docs/open-dataset-workflow.md
docs/session-handoff.md


通过 repo 内脚本重新启动托管下载流程


验证结果：


curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
当前响应关键信息：


200
content-length=7679594875
accept-ranges: bytes


curl -L --range 0-1023 ... 成功获取 1024 bytes

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_url=https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
archive_size=53620736
托管下载进程存在：prepare_fma_archive.py download


结论：


真实 FMA 下载现在已切换到用户指定的 ModelScope 通道
下载控制面也已统一回 repo 内脚本，后续 session 更容易续传与接力


Stage: 服务 HTTP smoke

完成项：


新增 acr-engine/scripts/service_smoke.py

用 uvicorn 真正拉起 FastAPI 服务，而不是只做函数级调用
更新 acr-engine/README.md 与 docs/service-api.md 的服务运行说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/service_smoke.py 成功

/usr/local/miniconda3/bin/python scripts/service_smoke.py 成功
当前 smoke 已验证：


/health
/ready
/config
/cache


当前结果：


health.ready=true
ready.ready=true

engine_cache_size=0（未执行 recognize 前）


结论：


服务现在已经具备最小 HTTP 级 smoke 验证
后续继续做鉴权、异步任务、监控时，有了更真实的回归入口


Stage: 服务就绪探针与缓存可见性

完成项：


增强 acr-engine/src/service/app.py

新增：


/ready
/cache


为服务默认模型/索引/manifest 增加 readiness 快照
为 HybridEngine 增加进程内缓存，避免同配置重复重载
更新 docs/service-api.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile src/service/app.py 成功
直接调用 health() / ready() / cache_status() 成功
直接调用 _load_engine() 两次成功
当前结果：


默认 service ready=true

首次加载 cache_hit=false

第二次加载 cache_hit=true

same_object=true


结论：


服务层现在不再只是“能调接口”的骨架
已具备最基本的就绪探针与缓存可见性，更接近工业级内网服务原型


Stage: FMA 整包下载/解压脚手架

完成项：


新增 acr-engine/scripts/prepare_fma_archive.py

支持：


inspect

download（支持 resume）
extract


将 FMA 官方整包路径接入：


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


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_exists=true
archive_size=9404416
extract_exists=true
num_audio_files=0


结论：


真实 FMA 整包路径现在不仅在下载，而且已经有标准化的 inspect/download/extract 工具链
即使下载耗时较长，后续 session 也能直接续传与接力


Stage: FMA 官方整包下载路径确认

完成项：


进一步验证 FMA Small 的稳定 archive 下载路径
确认 fma_small.zip 可通过官方归档地址直接访问
将该路径补充到开放数据工作流与交接文档


验证结果：


curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
当前响应头关键信息：


200 OK
Content-Type: application/zip
Content-Length: 7679594875
Accept-Ranges: bytes


curl -L --range 0-1023 ... 成功获取前 1024 bytes


结论：


FMA 真实数据已经不再缺下载地址
当前剩余问题从“找不到稳定 URL”转为“是否开始实际拉取 7.68 GB 归档并落盘”


Stage: FMA 下载器模块调用修复

完成项：


修复 acr-engine/scripts/fetch_fma_subset.py 的 yt-dlp 检测方式
从 shell 可执行查找改为优先支持：


yt-dlp 可执行文件

/usr/local/miniconda3/bin/python -m yt_dlp 模块调用


重新执行真实 FMA bounded 下载验证


验证结果：


which yt-dlp 仍为空

/usr/local/miniconda3/bin/python -m yt_dlp --version 成功，版本 2026.03.17


/usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 成功执行
当前结果：


ytdlp_cmd=["/usr/local/miniconda3/bin/python", "-m", "yt_dlp"]
8/8 请求均失败
失败原因已从“工具缺失”收敛为 freemusicarchive.org/music/track/<id> 返回 HTTP 404


结论：


下载脚本的模块调用问题已经修复
当前真实阻塞不再是本地环境，而是 FMA 历史页面 URL 路径已不可用
下一步应转向官方整包或稳定镜像，而不是继续重试旧页面 URL


Stage: FMA 真实下载脚手架

完成项：


新增 acr-engine/scripts/fetch_fma_subset.py

先验证了旧版 FMA 文件直链抓取路径
再切换为页面级抓取脚手架，并显式输出阻塞原因
将当前真实 FMA 下载状态记录进：


docs/open-dataset-workflow.md
docs/session-handoff.md


验证结果：


/usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 已执行两轮验证
第一轮结果：8 个 track id 全部 HTTP 403

第二轮结果：yt-dlp not found，脚本返回结构化 blocked JSON


结论：


真实 FMA 下载自动化入口已具备
但当前环境下仍缺稳定可用下载通道，尚不能宣称真实 FMA 已成功落地
该阻塞已经被显式固化到交接文档中，避免新 session 重复踩坑


Stage: 原始开放数据 LFS 治理

完成项：


新增根目录 /.gitattributes

为 acr-engine/data/raw/ 下的大文件与音频配置 Git LFS 跟踪策略
重写 acr-engine/data/raw/README.md，补充：


数据落点职责表

check-local-ready -> smoke-local 最短路径
原始数据下载 / LFS 治理策略


补充 docs/dataset-sources-and-licensing.md 的下载 / LFS 治理说明


验证结果：


git lfs version 成功

git check-attr filter -- acr-engine/data/raw/fma_small_audio/example.wav 返回 filter: lfs


git check-attr filter -- acr-engine/data/raw/archive.zip 返回 filter: lfs

文档已明确区分：


工程可用性
benchmark 适用性
商用可部署性


结论：


仓库现在具备承接真实开放音频和压缩包的 LFS 基础设施
后续下载真实数据时，不会直接把大文件塞进普通 git 历史


Stage: 真实数据就绪度守门

完成项：


为 acr-engine/src/data/external_adapters.py 新增 check-local-ready

为 smoke-local 增加前置就绪度守门，避免对空目录直接进入训练链路
增强 acr-engine/scripts/status_snapshot.py，输出：


dataset_readiness

capability_map 文档入口

check-local-ready 下一步命令


补充 docs/open-dataset-workflow.md 与 docs/session-handoff.md 的真实数据检查说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile src/data/external_adapters.py scripts/status_snapshot.py 成功

/usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready fma data/raw/fma_small_audio --eval-ratio 0.2 --query-duration 8.0 成功

/usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready mtg_jamendo data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0 成功

/usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
当前结果：


fma.ready_for_smoke=false
mtg_jamendo.ready_for_smoke=false
原因均为音频文件数与可切 query 文件数不足


结论：


真实开放数据现在有了明确的“进入 smoke 前门槛”
新 session 和自动化脚本可以立刻识别空目录，而不是误以为真实数据已经准备完成


Stage: 当前能力地图

完成项：


新增 docs/current-capability-map.md

明确区分：


已完整闭环
已打通但仍是 smoke 级
仍待真实数据/更大规模验证


将能力地图接入 docs 总入口与交接文档


验证结果：


docs/current-capability-map.md 已创建

docs/README.md 已挂接

docs/session-handoff.md 已挂接


结论：


新 session 现在更容易快速判断“什么是真的完成了，什么还只是 smoke 级能力”
能显著减少误判项目状态的风险


Stage: confused 定向优化 v6（sample-level weighting）

完成项：


将 hard-case loss 从 batch 级平均权重改为 sample-level weighting


SongPairDataset 改为对 confused / humming_like 区分采样强度

confused 样本权重提高到更高优先级
重训 models_v6、重建 index_v6、重跑 smoke-v6 评测
生成 reports/smoke-v6/synthetic_v2/ 发布制品
补充 docs/dataset-spec.md 中的 hard-case 输入规范说明
补充 docs/sota-research-2026.md 中的 v4/v5/v6 对比结论


验证结果：


train.py --dry-run 成功

py_compile 成功

run_demo.py build-index 成功

evaluate.py --fast-eval --output-json reports/smoke-v6/synthetic_v2/eval.json 成功
当前结果：


overall top1=0.65, top5=0.95
humming_like top1=0.25
confused top1=0.25


结论：


相比 smoke-v5，overall top1 从 0.60 提升到 0.65

confused top1 从 0.00 提升到 0.25，说明 sample-level 权重有效

humming_like top1 从 0.50 回落到 0.25，说明两类 hard case 需要分治，而不能只靠单轴加权


Stage: v7 平衡采样试验（未保留）

完成项：


尝试降低 confused 偏置并提高 humming_like 采样强度
重跑 smoke-v7 全链路验证
基于失败样本回查 residual hard case 的 segment 分布


验证结果：


smoke-v7 结果退化为：


overall top1=0.55, top5=0.80
humming_like top1=0.00
confused top1=0.00


因结果明显回退，已回滚该试验，不作为主线版本保留


结论：


单纯重调全局采样比率不稳定
当前最优保留点仍是 smoke-v6

residual confused failure 主要落在 intro 片段，下一轮应改做 segment_type-aware hard negatives


Stage: 检索融合权重参数化 + fast-eval 调优

完成项：


evaluate.py 新增融合参数：


--chroma-weight
--ecapa-weight
--melody-weight


在稳定的 models_v6 + index_v6 资产上做 fresh fast-eval 对比
验证 retrieval-time fusion 调优是否比继续改训练权重更有效


验证结果：


默认 fast-eval：


overall top1=0.65
humming_like top1=0.25
confused top1=0.25


调整为 chroma=0.2 / ecapa=0.55 / melody=0.25 后：


overall top1=0.70
humming_like top1=0.50
confused top1=0.25


结论：


在当前阶段，检索融合调优 比继续调训练侧权重更稳定、更划算

ecapa 权重略升、chroma 略降能恢复 humming_like，同时保持 confused

下一阶段应继续把外部开源数据集真正接成 train/eval manifests，而不是只停在 bootstrap


Stage: 开源数据集 ingestion（train/eval manifests）

完成项：


扩展 src/data/manifest_tools.py

新增 audio-dir-to-splits CLI
支持从本地开放音频目录自动生成：


catalog.json
train.json
test.json
val.json


新增小数据集保护，确保个人使用场景下也能同时有 train/test queries


验证结果：


python -m py_compile src/data/manifest_tools.py 成功
使用本地 demo 音频目录成功生成真实 manifests
修正后小样本结果：


catalog=2
train_queries=1
test_queries=1


结论：


项目现在不再只停留在 external bootstrap
已经具备把开源音乐数据目录直接切成训练/评估输入的能力
下一阶段可以继续对接真实 FMA / MTG-Jamendo 下载目录


Stage: adapter-level 本地开源目录接入

完成项：


扩展 src/data/external_adapters.py

新增 prepare-local 命令
支持通过 adapter 入口直接把本地开源音频目录转成：


catalog.json
train.json
test.json
val.json


验证结果：


python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功

python src/data/external_adapters.py prepare-local fma tmp/open_music_demo --output-root data/external_ingested/demo_via_adapter --eval-ratio 0.5 --query-duration 5.0 成功
输出结果：


catalog=2
train_queries=1
test_queries=1


结论：


现在接入真实 FMA / MTG-Jamendo 目录时，不需要再手动拼 manifests
adapter 已经能作为统一入口管理开放数据集的训练/评估切分


Stage: 开源目录规模扫描（inspect-local）

完成项：


扩展 src/data/manifest_tools.py

新增 inspect-audio-dir

扩展 src/data/external_adapters.py

新增 inspect-local

在真正生成 manifests 之前，可以先报告：


音频文件数量
可切 query 的文件数
推荐 train/test query 数
基础时长统计


验证结果：


python -m py_compile src/data/manifest_tools.py src/data/external_adapters.py 成功

python src/data/manifest_tools.py inspect-audio-dir tmp/open_music_demo --query-duration 5.0 --eval-ratio 0.5 成功

python src/data/external_adapters.py inspect-local fma tmp/open_music_demo --eval-ratio 0.5 --query-duration 5.0 成功
返回结果：


num_audio_files=2
eligible_query_files=2
recommended_train_queries=1
recommended_test_queries=1


结论：


现在真实 FMA / MTG-Jamendo 目录在导入前就能先做规模预估
这对个人使用下的快速数据准备非常有帮助


Stage: 多目录批量 inventory（inspect-batch）

完成项：


扩展 src/data/external_adapters.py

新增 inspect-batch

支持一次性检查多个开放数据目录，例如：


fma=<dir>
mtg_jamendo=<dir>


验证结果：


python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功

python src/data/external_adapters.py inspect-batch fma=tmp/open_music_demo_fma mtg_jamendo=tmp/open_music_demo_jamendo --eval-ratio 0.5 --query-duration 5.0 成功
返回：


count=2
每个数据源均给出 num_audio_files / eligible_query_files / recommended_train_queries / recommended_test_queries


结论：


现在可以批量对比多个候选开放数据目录的可用规模
这让后续接入真实 FMA / MTG-Jamendo / 其他音乐集更高效


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 文档补全 + ACR 最小可运行链路

完成项：


补充项目职责图：docs/project-responsibility-map.md

补充系统架构图：docs/acr-architecture.md

补充阶段路线图：docs/roadmap.md

补充运行手册：docs/runbook.md

补充引擎说明：acr-engine/README.md

新增依赖清单：acr-engine/requirements.txt

新增 demo CLI：acr-engine/run_demo.py

修复数据集读取路径问题：acr-engine/src/data/dataset.py

修复首次训练不落 best checkpoint 的问题：acr-engine/train.py


验证结果：


已生成 synthetic dataset
已通过 train.py --dry-run

已完成 1 epoch CPU 训练并生成 best_model.pt

已完成指纹索引与 embedding 索引构建
已完成识别命令并输出 JSON 候选结果


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 准确率优化 v2（128 Mel / band-split / retrieval 评测 / dataset 规范 / SOTA 调研）

完成项：


补充 dataset / 输入输出规范：docs/dataset-spec.md

补充开源数据集接入计划：docs/open-dataset-plan.md

补充 2026 SOTA 研究说明：docs/sota-research-2026.md

输入特征从低维说话人风格配置改为 128 Mel

新增频带分割模块 BandSplitBlock

引入 pro-WGAN 风格工程近似平衡策略（针对困难样本的更强增广）
合成数据新增 confused / humming_like 样本类型
引入 catalog.json 作为可搜索 reference 清单
索引从整曲单向量改为 window-level embedding index
新增 evaluate.py 做 retrieval 评测
训练逻辑改为更 retrieval-oriented 的 song-pair 训练输入


验证结果：


synthetic_v2 端到端重新跑通
build-index 成功
evaluate 成功
test split 指标：top1=0.65, top5=0.95
分类型指标：


clean top1=1.00
augmented top1=0.75
humming_like top1=0.25
confused top1=0.25


结论：


结构性错误（catalog/index/fusion/评测缺失）已明显改善
当前主要剩余短板是 humming_like / confused 的鲁棒识别


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 工业化服务骨架 + 外部 manifest 转换模板

完成项：


新增 FastAPI 服务骨架：acr-engine/src/service/app.py

新增 manifest 转换工具：acr-engine/src/data/manifest_tools.py

新增工业 benchmark 文档：docs/industrial-benchmark-spec.md

扩展外部 dataset adapter CLI：acr-engine/src/data/external_adapters.py

新增服务 API 文档：docs/service-api.md

requirements 增加 FastAPI / uvicorn / pydantic


验证结果：


external_adapters.py registry 成功

external_adapters.py describe ccmusic 成功

external_adapters.py init modelscope_music 成功

manifest_tools.py csv-to-catalog 成功生成 catalog

service.app health() 返回 {"status":"ok"}

API build_index(...) 成功返回 reference window 数量
API recognize(...) 成功返回候选结果

train.py --dry-run 成功


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 文档治理闭环（导航 / 引用 / 模板）

完成项：


新增 docs/README.md 作为文档总入口
新增 docs/references-and-sources.md 作为引用来源总图
新增 docs/benchmark-report-template.md

新增 docs/model-card-template.md

新增 docs/release-checklist.md

核心文档统一补充 Sources 小节
核心文档统一补齐 executive summary / mermaid / table / appendix 风格


验证结果：


docs 总入口结构检查通过
references map 结构检查通过
核心 docs 存在性检查通过
benchmark/model/release 模板结构检查通过
所有核心文档均具备 Sources；SOTA 文档已补齐 Mermaid 图


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 真实评测到发布产物链路打通

完成项：


evaluate.py 支持 --output-json

新增 docs/report-layout.md

新增 scripts/generate_artifacts.py

打通 eval.json -> benchmark-report.md / model-card.md / release-checklist.md / artifact-manifest.json

为快速发布链路新增 --fast-eval（关闭 melody 重排以加快报告生成）


验证结果：


synthetic_v2 重建、训练、建索引成功

evaluate.py --fast-eval --output-json ... 成功输出 JSON
artifact generator 成功输出 4 类发布产物

reports/smoke-v2/synthetic_v2/ 目录产物存在性检查通过
当前 fast-eval 指标：top1=0.60, top5=0.75，hard-case 仍需继续优化


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: 外部数据集 bootstrap + hard-case 过采样试验

完成项：


新增 src/data/bootstrap_external.py

可自动为 fma / ccmusic 生成 bootstrap catalog manifest
在 SongPairDataset 中加入困难样本过采样试验（confused / humming_like）
重新训练 models_v4、重建 index_v4、重跑 smoke-v4 评测


验证结果：


data/external_bootstrap/fma/manifests/catalog.bootstrap.json 成功生成

data/external_bootstrap/ccmusic/manifests/catalog.bootstrap.json 成功生成

reports/smoke-v4/synthetic_v2/eval.json 成功生成
当前试验结果：top1=0.40, top5=0.80
hard-case 结果未改善：


humming_like top1=0.00
confused top1=0.00


结论：


该轮简单过采样策略无效，且整体精度下降
下一轮应改用更细粒度 hard-negative / melody-aware 正则，而不是继续放大样本重复权重


2026-06-02


Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：


复检归档下载状态，确认 fma_small.zip 已达完整字节数
验证本地 FMA 音频目录已可用于真实 smoke
直接启动真实 FMA smoke-local，进入训练/索引/评测主链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=7679594875
archive_progress_percent=100.0

num_audio_files=3025（inspect 阶段）


本地解压目录复检：


find data/raw/fma_small_audio ... | wc -l 返回 5827


check-local-ready / inspect-local 返回：
ready_for_smoke=true
num_audio_files=8000
eligible_query_files=7994
recommended_train_queries=6395
recommended_test_queries=1599


真实 smoke 已启动：


/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


当前训练侧实时证据：


Device: cpu
Classes: 6381
Train songs: 6381

Epoch 1 已启动
当前 epoch 总 batch 数：3191


结论：


真实 FMA 数据下载门槛已正式打开
项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段


Stage: 真实 FMA 下载超过八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 09:28


守护日志已增长到至少 19 轮：


cycle=18, 83.937%


cycle=19, 85.7155%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6724517888
archive_progress_percent=87.5634


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=87.5649


结论：


detached guard 已在九分钟级别继续稳定驻留
真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近八成半

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 08:25


守护日志已增长到至少 17 轮：


cycle=16, 81.1776%


cycle=17, 82.7758%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6432636928
archive_progress_percent=83.7627


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=83.764


结论：


detached guard 已在八分钟级别继续稳定驻留
真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过八成

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
复检后处理门槛是否仍未打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 07:15


守护日志已增长到至少 15 轮：


cycle=14, 78.2606%


cycle=15, 79.6962%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=6173982720
archive_progress_percent=80.3946


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=80.3946


结论：


detached guard 已在七分钟级别继续稳定驻留
真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载超过四分之三

完成项：


再次复检 detached guard 的更长时段稳定性
采集新的多轮日志增长证据
再次验证后处理门槛仍由未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 06:12


守护日志已增长到至少 13 轮：


cycle=12, 75.3734%


cycle=13, 76.9423%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5953486848
archive_progress_percent=77.5234


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=77.5247


结论：


detached guard 已在六分钟级别继续稳定驻留
真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载


Stage: 真实 FMA 下载逼近四分之三

完成项：


再次复检 detached guard 的更长时段存活情况
采集新的多轮日志增长证据
再次确认后处理门槛是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 05:19


守护日志已增长到至少 11 轮：


cycle=10, 72.2831%


cycle=11, 73.8305%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5748047872
archive_progress_percent=74.8483


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=74.8485


结论：


detached guard 已在五分钟级别继续稳定驻留
真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛


Stage: 真实 FMA 下载超过七成

完成项：


再次复检 detached guard 长时运行状态
采集新一轮日志增长证据
复检后处理门槛是否已经打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 04:16


守护日志已增长到至少 9 轮：


cycle=8, 68.0898%


cycle=9, 70.2949%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5479727104
archive_progress_percent=71.3544


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=71.3559


结论：


detached guard 在更长时间窗口内继续稳定工作
真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛


Stage: 真实 FMA 下载进度过三分之二

完成项：


再次复检 detached guard 的持续运行情况
采集新的多轮日志增长证据
复检后处理门槛是否已打开


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 03:19


守护日志已增长到至少 7 轮：


cycle=6, 63.9577%


cycle=7, 65.6775%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=5160501248
archive_progress_percent=67.1976


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=67.1995


结论：


detached guard 在更长时段内继续稳定工作
真实 FMA 下载已超过三分之二，但后处理门槛仍未打开


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


Stage: MTG-Jamendo / ModelScope bootstrap + type-aware hard-case weighting

完成项：


补充 mtg_jamendo 与 modelscope_music 的 bootstrap manifest 生成
在训练链路中加入 type-aware hard-case weighting（针对 confused / humming_like）
重训 models_v5、重建 index_v5、重跑 smoke-v5 评测


验证结果：


data/external_bootstrap/mtg_jamendo/manifests/catalog.bootstrap.json 成功生成

data/external_bootstrap/modelscope_music/manifests/catalog.bootstrap.json 成功生成

reports/smoke-v5/synthetic_v2/eval.json 成功生成
当前结果：top1=0.60, top5=0.90
hard-case 结果：


humming_like top1=0.50（较 v4 有提升）
confused top1=0.00（仍未解决）


结论：


type-aware weighting 比 naive oversampling 更有效
下一轮应专门针对 confused 类设计更强的 negative mining / confusion-aware 信号


Stage: internal asset query stride fix + type policy hardening

完成项：


修复 acr-engine/scripts/internal_asset_type_mapper.py 中内部素材 query 的自动扩窗逻辑
新增 source_audio_duration 透传，使长音频可基于真实总时长按 --query-stride 展开
修复 “默认 offset=0 被误判为显式 offset” 的问题，确保只有 CSV 明确给了 offset 才禁用扩窗
为 pgvector_payload.json 的 segments 补充 query_index

在 docs/training-data-and-pgvector-guide.md 补充内部素材滑窗规则、推荐参数表与自动扩窗示例


验证结果：


使用本地 30s songA.wav 验证：


--default-query-duration 8 --query-stride 4

queries.json 成功导出 7 条 query
offset 为 0, 4, 8, 12, 16, 20, 22


query_index 为 0..6


使用本地 40s songB.wav + CSV 显式 offset=12 验证：


仍只导出 1 条 query
未被自动扩窗覆盖


manifest_bundle/*.json 与 pgvector_payload.json 均已同步反映扩窗结果


结论：


现在内部素材可以稳定支持两种模式：


人工标 offset 的短视频片段：保持单条 query

只有整首音频、没有 query 起点的素材：自动生成多窗口 query


这让 7/8/16/18 这类 query 型素材可以更直接进入训练与评测流水线，同时保留对 pgvector 入库的可追踪性


Stage: silence-aware segmentation for training and open-dataset query generation

完成项：


在 acr-engine/src/data/dataset.py 为训练切片新增：


segment_strategy=random|silence_aware|hybrid
silence_top_db


接入 librosa.effects.split，用于优先选择非静音区作为训练片段来源
在 acr-engine/src/data/manifest_tools.py 为外部数据 query 生成新增：


--query-strategy random|sliding|silence_aware|hybrid
--silence-top-db


在 acr-engine/train.py 暴露训练 CLI 参数：


--segment-strategy
--silence-top-db


在 acr-engine/src/data/external_adapters.py 接通 prepare-local / smoke-local 的策略透传与配置落盘
在 docs/training-data-and-pgvector-guide.md 补充“切片策略”章节


验证结果：


代码编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py


人造音频验证：


构造 4s silence + 10s tone + 4s silence

manifest_tools.py --query-strategy silence_aware --query-duration 5 --query-stride 2.5
导出 query offset：3.968, 8.968, 9.08

说明 query 已明显偏向非静音主体区


训练侧偏移验证：


random offset 样本：0.325, 1.13, 2.902, 3.575, 8.313, 8.797, 9.574, 11.598


silence_aware offset 样本：4.173, 4.228, 4.736, 5.111, 5.874, 5.974, 8.436, 8.805

说明 silence-aware 显著减少落入头尾静音区的概率


dry-run 验证：


train.py --data data/synthetic_v2 --dry-run --segment-strategy silence_aware
forward/backward 成功，Embedding shape: torch.Size([64, 192])


adapter 验证：


external_adapters.py prepare-local ... --query-strategy silence_aware
summary 已记录 query_strategy: silence_aware


结论：


当前项目不再只有“随机切”
已形成：


训练侧：random / silence_aware / hybrid


建库侧：固定滑窗

开源集 query 生成侧：random / sliding / silence_aware / hybrid


下一阶段可继续叠加 beat/onset/chorus-aware 切片，而无需推翻现有流程


Stage: build-index checkpoint resume + path compatibility hardening

完成项：


在 acr-engine/src/engines/ecapa_embedder.py 完成 embedding index 的 checkpoint / resume 逻辑


支持读取 reference_progress.json

支持复用 reference_embs.partial.npy / reference_ids.partial.npy

若 final index 已存在，--resume 直接命中完成态


在 acr-engine/run_demo.py build-index 暴露：


--resume
--checkpoint-every-refs


修复 synthetic / 根目录型数据集的音频路径解析兼容问题：


acr-engine/src/engines/ecapa_embedder.py
acr-engine/src/engines/chromaprint_matcher.py


为 “没有任何 reference 被成功解析” 的场景补充显式报错，避免 np.vstack([]) 这类低可读错误
在 docs/open-dataset-workflow.md 补充 build-index --resume 用法


验证结果：


代码编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/engines/ecapa_embedder.py src/engines/chromaprint_matcher.py run_demo.py


兼容性验证：


run_demo.py build-index --data data/synthetic_v2 --model data/models_v6/best_model.pt --output /tmp/index_resume_fresh --device cpu
synthetic 根目录型 audio_path=songs/... 已可正常建索引


resume 一致性验证：


用 data/synthetic_v2/catalog.json 的前 2 首 reference 生成 partial checkpoint
人工保留 reference_embs.partial.npy / reference_ids.partial.npy + reference_progress.json

执行：


run_demo.py build-index ... --resume --checkpoint-every-refs 1


与 fresh full rebuild 对比结果：


resume_shape == fresh_shape == (120, 192)
ids_equal == True
embs_allclose == True
progress_status == complete
progress_refs_done == progress_refs_total == 24


resume 日志证据：


[build-reference-index] resuming from checkpoint: refs_done=2/24 windows_done=10


结论：


现在 CPU 长时间 build-index 任务即使中断，也可以从 partial checkpoint 续跑
该恢复逻辑已经拿到“恢复结果与 fresh rebuild 完全一致”的新鲜证据
下一步可以把这套 resume 能力进一步接到 smoke-local 的自动恢复策略里


Stage: smoke-local auto resume + model-signature safety gate

完成项：


在 acr-engine/src/engines/ecapa_embedder.py 为 index checkpoint 增加 model_signature


path
size_bytes
mtime_ns


恢复时如果 checkpoint 的 model_signature 与当前 best_model.pt 不一致：


自动拒绝旧 checkpoint
清理旧 partial 文件
从 0 重建 embedding index


在 acr-engine/src/data/external_adapters.py 的 smoke-local 中默认启用：


run_demo.py build-index --resume
--checkpoint-every-refs


在 docs/open-dataset-workflow.md 补充模型签名护栏说明


验证结果：


编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/engines/ecapa_embedder.py src/data/external_adapters.py run_demo.py


同模型恢复验证（models_v6 -> models_v6）：


人工构造前 2 首 reference 的 partial checkpoint
日志出现：
[build-reference-index] resuming from checkpoint: refs_done=2/24 windows_done=10
与 fresh rebuild 对比：
same_final_ids_equal == True
same_final_embs_equal == True
same_progress_status == complete


异模型拒绝恢复验证（models_v6 partial -> models_v5 current）：


日志出现：
resume checkpoint ignored due to load failure: model signature mismatch
随后从 0 重建：
start: refs=24 ... resume=True refs_done=0
与 models_v5 fresh rebuild 对比：
mismatch_final_ids_equal == True
mismatch_final_embs_equal == True


结论：


smoke-local 现在已经具备“可恢复，但不会错误复用旧模型 embedding”的安全自动恢复能力
这对真实 FMA 这类 CPU 长时任务尤其重要：重启可续跑，换模型不会串污染 index


Stage: high-energy / onset-aware music segmentation

完成项：


在 acr-engine/src/data/dataset.py 新增训练切片候选策略：


high_energy
onset_aware


在 acr-engine/src/data/manifest_tools.py 新增外部 query 生成策略：


--query-strategy high_energy
--query-strategy onset_aware


将 hybrid 升级为可复用：


high_energy
onset_aware

silence_aware
三类音乐感知候选，再补随机 fallback


在 train.py 与 external_adapters.py 暴露新策略选项
在 docs/training-data-and-pgvector-guide.md 增补策略说明与使用建议


验证结果：


编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py


人造音频验证：


构造 20s 音频：

4-6s 低能 tone

8/10/12s 强起音脉冲

14-19s 高能 tone


query 生成结果：


high_energy offsets：
2.5, 7.5, 10.0, 12.5, 15.0

onset_aware offsets：
4.032, 6.048, 8.032, 10.016, 10.048, 12.032


训练侧偏移验证：


TRAIN_HIGH_ENERGY_OFFSETS：
2.5, 15.0, 15.0, 2.5, 10.0, 12.5

TRAIN_ONSET_OFFSETS：
4.064, 4.032, 10.016, 8.032, 8.032, 6.048
说明新策略已明显偏向强能量区或起音邻域，而不是纯随机


dry-run 验证：


train.py --data data/synthetic_v2 --dry-run --segment-strategy high_energy
forward/backward 成功，Embedding shape: torch.Size([64, 192])


结论：


当前项目的音乐感知切片已经从“避静音”扩展到了“偏主段 / 偏起音”
下一步若继续增强，可在此基础上叠加：


beat-aware
chorus-aware
repeated-section-aware


Stage: beat-aware music segmentation

完成项：


在 acr-engine/src/data/dataset.py 新增：


beat_aware 候选切片策略


在 acr-engine/src/data/manifest_tools.py 新增：


--query-strategy beat_aware


在 train.py 与 external_adapters.py 暴露：


beat_aware 选项


为 beat_aware 增加容错：


优先使用 librosa.beat.beat_track

若 beat 检测失败，则回退到 onset 间隔估计生成近似节拍点


将 hybrid 扩展为优先复用：


beat_aware
high_energy
onset_aware
silence_aware


验证结果：


编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py


人造节拍音频验证：


构造 20s 音频

4s-18s 区间每 0.5s 注入一次脉冲（约 120 BPM）
再叠加轻微 tonal bed


直接 beat 候选结果：


DIRECT_BEAT_CANDIDATES_SEC：
4.032, 5.952, 7.872, 9.792, 11.712, 13.632, 15.0


query 生成结果：


BEAT_QUERY_OFFSETS：
4.032, 7.872, 9.792, 11.712, 13.632, 15.0

HYBRID_QUERY_OFFSETS：
3.968, 4.032, 4.064, 4.544, 5.0, 5.536, 6.016, 6.048, 7.872, 9.591, 9.792, 10.0


训练侧偏移验证：


TRAIN_BEAT_AWARE_OFFSETS：
13.632, 4.032, 4.032, 13.632, 7.872, 5.952

TRAIN_HYBRID_OFFSETS：
2.5, 5.536, 4.064, 12.5, 7.872, 4.032
说明 beat-aware 已明显偏向规则拍点，hybrid 也已吸收 beat-aware 候选


dry-run 验证：


train.py --data data/synthetic_v2 --dry-run --segment-strategy beat_aware
forward/backward 成功，Embedding shape: torch.Size([64, 192])


结论：


当前项目的音乐感知切片已经进一步从“高能/起音”扩展到“规则拍点”
下一步可继续叠加：


repeated-section-aware
chorus-like candidate mining


Stage: repeated-section-aware / chorus-like candidate sampling

完成项：


在 acr-engine/src/data/dataset.py 新增：


repeated_section_aware


在 acr-engine/src/data/manifest_tools.py 新增：


--query-strategy repeated_section_aware


在 train.py 与 external_adapters.py 暴露：


repeated_section_aware


实现方式：


对滑窗片段提取 chroma_cqt

取窗口级平均 chroma 向量
计算窗口间相似度
优先选择“与其它窗口最相似”的片段，作为重复主段 / 副歌 hook 的轻量近似


将 hybrid 扩展为优先复用：


repeated_section_aware
beat_aware
high_energy
onset_aware
silence_aware


验证结果：


编译验证：


/usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py


人造“重复副歌”音频验证：


构造 24s 音频

8-12s 与 16-20s 放置两段重复 motif


直接重复候选结果：


DIRECT_REPEAT_CANDIDATES_SEC：
6.0, 8.0, 10.0, 14.0, 16.0, 18.0


query 生成结果：


REPEAT_QUERY_OFFSETS：
6.0, 10.0, 14.0, 16.0, 18.0

HYBRID_QUERY_OFFSETS：
2.016, 2.048, 2.08, 6.0, 6.048, 8.0, 8.064, 10.0, 12.789, 14.0, 15.968, 16.0


训练侧偏移验证：


TRAIN_REPEAT_OFFSETS：
17.5, 0.0, 0.0, 17.5, 7.5, 2.5

TRAIN_HYBRID_OFFSETS：
0.0, 8.032, 2.5, 2.048, 2.016, 7.5
说明 repeated-section-aware 已能明显偏向重复主段周边，而 hybrid 也已吸收这类候选


dry-run 验证：


train.py --data data/synthetic_v2 --dry-run --segment-strategy repeated_section_aware
forward/backward 成功，Embedding shape: torch.Size([64, 192])


结论：


当前项目的音乐感知切片已经从：


避静音
高能区
起音点
拍点
进一步扩展到：
重复主段 / 近似副歌


下一步可继续做更强的：


chorus-like multi-feature ranking
小规模真实数据策略 A/B 对比


Stage: real FMA mini-subset segmentation A/B smoke benchmark

完成项：


新增脚本：


acr-engine/scripts/ab_smoke_segmentation.py


能力：


从本地真实数据目录抽取固定数量子集
依次运行 smoke-local

自动比较多种切片策略的 smoke 结果
汇总 top1 / topk / num_queries


修正排序规则：


不再只按 top1/topk

改为 top1 -> topk -> num_queries

避免在分数持平时把 query 更少的策略误判为 winner


验证结果：


真实数据来源：


data/raw/fma_small_audio


smoke 子集：


8 首 FMA 音频
query_duration=8
train_epochs=1
batch_size=2


比较策略：


random
silence_aware
high_energy
beat_aware
repeated_section_aware
hybrid


报告路径：


/tmp/ab_smoke_seg/report.json


排序修正后的结果：


hybrid：num_queries=37, top1=1.0, topk=1.0


beat_aware：num_queries=13, top1=1.0, topk=1.0


high_energy：num_queries=12, top1=1.0, topk=1.0


repeated_section_aware：num_queries=12, top1=1.0, topk=1.0


random：num_queries=4, top1=1.0, topk=1.0


silence_aware：num_queries=2, top1=1.0, topk=1.0


结论：


在这个极小真实子集 smoke 上，所有策略都能达到 top1/top5 = 1.0

但从 query 覆盖率 看：


hybrid 当前最优

beat_aware / high_energy / repeated_section_aware 是更强的次优候选


下一步应扩大真实子集规模，并引入更难的 query 类型，进一步拉开策略差异