open-dataset-workflow.md 10.7 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
/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