open-dataset-workflow.md 15.4 KB

Raw Blame History Permalink



Open Dataset Workflow / 开放数据工作流


0. 本地真实数据就绪检查

在跑 smoke-local 前，先确认目录里真的有足够的音频：

/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


判定标准：


至少 2 个音频文件
至少 2 个时长 >= 8s 的可切 query 文件

ready_for_smoke=true 才进入完整 smoke


如果目录为空，状态快照脚本也会明确提示未就绪。


更新：2026-06-02


一页结论

如果你要把 FMA / MTG-Jamendo 这类开源音乐目录真正接进项目，推荐只记住这一条链路：


inspect-local / inspect-batch
prepare-local
validate-local
再进入训练与评估
生成 benchmark / model card / release artifacts
或直接使用一键 smoke-local


1. 工作流图

flowchart LR
    A[Local Open Audio Dir] --> B[inspect-local / inspect-batch]
    B --> C[prepare-local]
    C --> D[validate-local]
    D --> E[train.py]
    D --> F[evaluate.py]
    F --> G[artifact bundle]


2. 最短命令表


步骤
命令
作用


预检查

src/data/external_adapters.py inspect-local ...

看规模是否足够


批量比较

src/data/external_adapters.py inspect-batch ...

比较多个候选目录


生成清单

src/data/external_adapters.py prepare-local ...

产出 train/test/catalog


训练前校验

src/data/external_adapters.py validate-local ...

确认结构正确


训练 smoke

train.py --data ... --dry-run

验证 manifests 可直接进入训练


发布制品
scripts/generate_artifacts.py
生成 benchmark/model-card/release-checklist


一键 smoke

src/data/external_adapters.py smoke-local ...

自动跑完整链路


3. 推荐顺序


3.1 单目录

/usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-local fma data/raw/fma_small_audio --eval-ratio 0.2 --query-duration 8.0
/usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/raw/fma_small_audio --output-root data/external_ingested --eval-ratio 0.2 --query-duration 8.0
/usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/raw/fma_small_audio --output-root data/external_ingested --eval-ratio 0.2 --query-duration 8.0 --query-stride 4.0
/usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/fma/manifests
/usr/local/miniconda3/bin/python train.py --data data/external_ingested/fma/manifests --output data/models_fma_smoke --device cpu --epochs 1 --batch-size 2 --dry-run
/usr/local/miniconda3/bin/python run_demo.py build-index --data data/external_ingested/fma/manifests --model data/models_fma_smoke/best_model.pt --output data/index_fma_smoke --device cpu

# 如果长时间 CPU 建索引被中断，可从 partial checkpoint 续跑
/usr/local/miniconda3/bin/python run_demo.py build-index \
  --data data/external_ingested/fma/manifests \
  --model data/models_fma_smoke/best_model.pt \
  --output data/index_fma_smoke \
  --device cpu \
  --resume \
  --checkpoint-every-refs 100

说明：
- `smoke-local` 现在内部默认也会为 `build-index` 打开 `--resume`
- checkpoint 会记录 `model_signature`
- 如果这次训练出的 `best_model.pt` 与旧 partial checkpoint 不是同一个模型，恢复会被自动拒绝并从 0 重建，避免混入不同模型的 embedding

## 小规模策略 A/B smoke

如果你想快速比较不同 query / training 切片策略，可直接运行：

```bash
/usr/local/miniconda3/bin/python acr-engine/scripts/ab_smoke_segmentation.py \
  --dataset fma \
  --input-dir acr-engine/data/raw/fma_small_audio \
  --work-root /tmp/ab_smoke_seg \
  --subset-size 8 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --output-json /tmp/ab_smoke_seg/report.json


当前脚本会比较：


random
silence_aware
high_energy
beat_aware
repeated_section_aware
hybrid


排序规则：


先按 top1

再按 topk

最后按 num_queries


这样在 top1/top5 持平时，会优先保留覆盖 query 更多的策略，而不是误把 query 更少的策略排到第一。

如果你要做更公平的策略比较，建议再加 --max-test-queries，让每个策略在同样的 query 预算下评测：

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


已验证：


最终报告会显式记录 max_test_queries


evaluate.py 会按 --seed 复现抽样
端到端 smoke 报告中的 num_queries 已成功收敛到 5


这一步的意义是：


之前的 A/B 排名更偏“覆盖能力”
加上 cap 后，可以更公平地比较“同等 query 成本下的识别质量”


最新真实 FMA capped 结果（subset=16, max_test_queries=12）

已完成一轮更公平的真实 FMA A/B：


排名
策略
num_queries
top1
topk


1
hybrid
12
1.0
1.0


2
high_energy
12
1.0
1.0


3
beat_aware
12
0.9167
1.0


4
repeated_section_aware
12
0.8333
1.0


当前建议：


默认训练 / query 策略仍优先 hybrid

high_energy 是当前最强的并列次选，适合更偏主段/高能区的数据

beat_aware 更适合规则节拍较强的风格，但在这轮 FMA 子集上略弱

repeated_section_aware 单独使用不如混合策略稳


更新：更大 cap24 top2 对照（subset=24, max_test_queries=16）

在更大的真实 FMA 子集上，只保留前两名策略继续对照：


排名
策略
num_queries
top1
topk


1
hybrid
16
1.0
1.0


2
high_energy
16
0.8125
1.0


这轮结果比 cap16 更有区分度，说明：


hybrid 不只是“和 high_energy 打平”
在更大的真实子集上，hybrid 的稳定性更强
当前默认推荐应明确收敛到 hybrid


更新：cap32 top2 对照（subset=32, max_test_queries=20）

进一步扩大到 32 首真实 FMA 子集后，结论继续强化：


排名
策略
num_queries
top1
topk


1
hybrid
20
0.95
1.0


2
high_energy
20
0.5
1.0


这说明：


hybrid 在更大真实子集上仍明显领先

high_energy 虽然可作为高能区偏置策略，但稳定性不足以成为默认
当前默认策略已经可以稳定写死为 hybrid


更新：cap48 top2 对照（subset=48, max_test_queries=24）

继续扩大到 48 首真实 FMA 子集后，出现了结果反转：


排名
策略
num_queries
top1
topk


1
high_energy
24
0.9167
1.0


2
hybrid
24
0.7917
1.0


这轮结果说明：


前面 cap24 / cap32 支持 hybrid

但 cap48 上 high_energy 反超
因此当前结论应从“默认策略已完全固定”调整为：


hybrid 仍是当前保守默认
high_energy 已成为强竞争方案
下一步必须做更大样本或多随机种子复核，不能只靠单轮 cap48 就完全改默认


更新：cap48 第二个 seed 复核（subset=48, max_test_queries=24, seed=123）

对同一规模再跑第二个 seed 后，结果又回到 hybrid 领先：


排名
策略
num_queries
top1
topk


1
hybrid
24
0.9583
1.0


2
high_energy
24
0.9167
1.0


这说明：


cap48 的策略排名对 seed / 抽样子集 敏感

单次 cap48 不能作为“high_energy 已全面反超”的充分证据
当前最稳妥结论仍是：


hybrid 保留为保守默认

high_energy 保留为强竞争方案
后续需要 多 seed 聚合结论，而不是看单次跑分


cap48 多 seed 聚合摘要（当前 2 次）

把 cap48 的两次 seed 放到一起看：


策略
runs
mean_top1
min_top1
max_top1
stdev_top1
mean_topk


high_energy
2
0.9167
0.9167
0.9167
0.0
1.0


hybrid
2
0.8750
0.7917
0.9583
0.0833
1.0


当前可解释为：


high_energy 在这两次 cap48 上均值更高且更稳定


hybrid 在第二个 seed 上更强，但波动也更大
因此目前最准确的表述不是“谁绝对赢”，而是：


cap48 上 high_energy 的聚合均值暂时领先
hybrid 仍是更保守的默认候选
最终默认仍应等待更多 seed 或更大样本确认
/usr/local/miniconda3/bin/python evaluate.py --data data/external_ingested/fma/manifests --model data/models_fma_smoke/best_model.pt --index-prefix data/index_fma_smoke/reference --split test --device cpu --fast-eval --output-json reports/fma-smoke/eval.json
/usr/local/miniconda3/bin/python scripts/generate_artifacts.py --eval-json reports/fma-smoke/eval.json --config-json reports/fma-smoke/config.json --output-dir reports/fma-smoke --model-version fma-smoke --data-version fma_local
```


3.2 多目录比较

/usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-batch fma=data/raw/fma_small_audio mtg_jamendo=data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0


3.3 一键 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
/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 auto
/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 --query-stride 4.0 --train-epochs 1 --batch-size 2 --device auto


真实目录放置位置可参考：


acr-engine/data/raw/README.md
acr-engine/data/raw/fma_small_audio/
acr-engine/data/raw/mtg_jamendo_audio/


4. 输出物说明


catalog.json：建索引用 reference 清单

train.json：训练 queries + references

test.json：固定评估 queries + references

val.json：可选验证集


5. 当前验证证据

已在本地 data/synthetic_v2/songs 上按开放数据流程跑通：


inspect-local：


num_audio_files=24
recommended_train_queries=19
recommended_test_queries=5


prepare-local：


catalog=24
train_queries=16
test_queries=8


validate-local：


ok=true


train.py --dry-run：


Dry run passed! Pipeline is working.


build-index + evaluate：


top1=1.0
topk=1.0


generate_artifacts：


benchmark-report.md
model-card.md
release-checklist.md


smoke-local：


会一次性返回 inspect / prepare / validate / report 路径摘要
现在支持 --device cpu|cuda|auto


auto 会在 smoke 内部解析成实际设备，避免把字符串 auto 直接传给 embedding/eval 侧
现在支持 --query-stride

当设置 --query-stride < query-duration 时，会为单首歌生成多个重叠 query，而不是只采 1 个随机 query


FMA 下载完成后的单条准备命令

cd acr-engine
/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py


这个脚本会在归档完整时自动执行：


extract
check-local-ready
inspect-local


如果归档还没下完，会返回结构化 archive_not_complete。


FMA 完成前等待并自动切换

cd acr-engine
/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 120


作用：


周期性检查 fma_small.zip 是否完成
一旦完成，自动进入 scripts/fma_postdownload_ready.py

如果还没完成，则返回 waiting 和最近的进度快照


Sources


See dataset-spec.md

See dataset-sources-and-licensing.md


Bucket / style-aware benchmark 基线

为了避免只看单一子集规模，现在仓库里已经有可运行的 bucket benchmark 基线：


../acr-engine/scripts/ab_smoke_bucketed.py


它的作用是：


从同一大目录中按 pattern 划出多个 bucket
每个 bucket 各自运行 ab_smoke_segmentation.py

生成 bucket 级 winner 与 aggregate summary


最小 smoke 已验证：


bucket: prefix_000_a


hybrid: 4 / 1.0 / 1.0


high_energy: 3 / 1.0 / 1.0

winner: hybrid


完整 bucket 汇总现已完成：


prefix_000_a winner=hybrid


prefix_000_b winner=high_energy

aggregate：


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


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


当前结论：


bucket baseline 已经能稳定复现“不同子集会选出不同 winner”。
下一步不是继续做 prefix toy bucket，而是升级到更有业务意义的 bucket。


推荐直接从模板开始：


../acr-engine/configs/buckets/fma_semantic_bucket_template.json


建议先人工挑一批歌，再把 glob 替换成你自己的候选集合，优先覆盖：


energy_dominant
repeated_section_rich
steady_beat_regular_meter
hard_negative_confusable


对应命令：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/ab_smoke_bucketed.py \
  --dataset fma \
  --input-dir data/raw/fma_small_audio \
  --bucket-config configs/buckets/fma_semantic_bucket_template.json \
  --work-root /tmp/ab_smoke_bucketed_semantic \
  --default-subset-size 16 \
  --query-duration 8 \
  --train-epochs 1 \
  --batch-size 2 \
  --device cpu \
  --strategies high_energy hybrid \
  --max-test-queries 8 \
  --seed 42 \
  --output-json /tmp/ab_smoke_bucketed_semantic/report.json


业务素材 bucket 模板

如果下一步不是继续用 FMA，而是切到你们自己的歌曲/BGM 素材，优先看：


business-music-bucket-and-type-guide.md
../acr-engine/configs/buckets/business_type_bucket_template.json