dataset-spec.md 11.4 KB

Raw Blame History Permalink



ACR Dataset / 输入输出规范


更新：2026-06-02

关联文档：训练数据与 pgvector 指南 · 开放数据工作流 · 数据来源与接入


一页结论

当前项目的数据规范，最重要的是 4 件事：


训练输入不是“整首 mp3 文件”本身，而是 manifest 驱动的 reference + query 样本体系。

训练和检索的切窗策略不同：训练端当前是随机裁剪 5s，检索/建索引端当前是5s 窗口 + 2.5s stride 的 50% 重叠滑窗。

外部开源数据集进入项目时，必须先转换成统一 manifest，再做训练、评测、索引和 pgvector 入库。

当前音乐任务输入层已切换到 128 维 Mel 频谱，并开启 band-split 方向；FMA 这类真实数据建议优先使用 GPU。


1. 数据流图

flowchart LR
    A[Raw Audio\nFMA / MTG / 自有 BGM / 录音] --> B[Manifest Conversion]
    B --> C[Catalog Manifest\nreference]
    B --> D[Train/Test Manifest\nquery]
    C --> E[Reference Index Build\nsliding windows]
    D --> F[Training / Evaluation]
    E --> G[Hybrid Retrieval]
    F --> G
    G --> H[pgvector / report / service]


2. 数据对象表


对象
作用
必要字段
说明


Reference
可检索曲库

song_id, audio_path, duration, type=reference

用于建索引


Query Segment
待识别片段

song_id, audio_path, duration, type

用于训练/评测


Catalog Manifest
reference 总表
JSON list
用于离线索引


Query Manifest
query 总表
JSON list
用于训练与评测


3. Manifest 结构图

flowchart TD
    M[Manifest] --> R[Reference Records]
    M --> Q[Query Records]
    R --> R1[song_id]
    R --> R2[audio_path]
    R --> R3[duration]
    R --> R4[type=reference]
    Q --> Q1[song_id]
    Q --> Q2[audio_path]
    Q --> Q3[duration]
    Q --> Q4[type=clean/augmented/confused/humming_like]
    Q --> Q5[offset]


4. 输入输出总表


环节
输入
输出


训练
query segments + references
embeddings + logits


索引
catalog references
chromaprint index + embedding index


识别
query audio
ranked candidates


评测
query manifest + catalog
top1/top5/hard-case report


入库
manifest + embedding
pgvector-ready JSON / SQL rows


5. 3 分钟 mp3 到 5–8 秒片段：当前到底怎么切


5.1 当前代码里有 3 种不同切法


flowchart TD
    A[3min mp3] --> B[训练 Dataset]
    A --> C[检索 / 建索引]
    A --> D[外部数据集 manifest 生成]

    B --> B1[随机裁 1 个 5s clip]
    C --> C1[5s 窗 + 2.5s stride]\n50% overlap
    D --> D1[每首歌随机采 1 个 query]\n默认 8s


场景
当前实现
是否重叠
代码位置


训练 SongPairDataset

每次采样按 segment_strategy 选 1 个 5s clip；默认可随机，也可走音乐感知候选
否，不是固定滑窗全集展开

acr-engine/src/data/dataset.py


检索 / embedding / 建索引

window_sec=5.0, stride_sec=2.5

是，50% overlap


acr-engine/src/utils/audio.py, acr-engine/src/engines/ecapa_embedder.py


audio-dir-to-splits 默认
每首歌生成 query；可随机，也可按音乐感知策略产出
否
acr-engine/src/data/manifest_tools.py


audio-dir-to-splits --query-stride 4.0 例
对单首歌生成多个滑窗 query
是，可配置
acr-engine/src/data/manifest_tools.py


直接回答你的问题


有重叠窗口，主要在检索/索引链路；训练端不是全量滑窗展开。

当前训练主链路不是“只会随机切”，而是每次 batch 动态选 1 个 5s 片段；候选可以来自 random / silence_aware / high_energy / onset_aware / beat_aware / repeated_section_aware / hybrid。

当前外部数据集 manifest 生成器也不再只有随机 query，可通过 --query-strategy 走音乐感知切法，也可通过 --query-stride 开启多 query / overlap query 生成。**


5.2 为什么这样设计


设计点
当前好处
当前限制


训练随机裁剪
节省存储，不必预生成几万切片
同一 epoch 暴露到的时间区域有限


检索重叠滑窗
更接近真实 ACR reference coverage
索引体积更大


音乐感知候选切片
更容易打到主段、起音、拍点、非静音区
CPU 分析成本更高


外部数据少量 query smoke
smoke 更轻、更快验证
训练/评测覆盖不充分


推荐理解方式：


训练端更像“随机数据增强采样器”

检索端更像“为了召回覆盖做滑窗索引”


5.3 我们到底有没有用 librosa 的分段逻辑

有，而且已经进入主链路，但不是“把整套结构分段 API 全盘替代随机采样”。

当前已用到的 librosa 音乐感知逻辑：


逻辑
当前用途
代码位置


librosa.effects.split

silence_aware，避开静音区
acr-engine/src/data/dataset.py


librosa.onset.onset_detect

onset_aware，优先起音附近
acr-engine/src/data/dataset.py


librosa.beat.beat_track

beat_aware，优先规则拍点
acr-engine/src/data/dataset.py


librosa.feature.chroma_cqt

repeated_section_aware，近似找重复主段 / hook
acr-engine/src/data/dataset.py


还没有直接上整套更重的 librosa.segment.* 结构分段主流程，原因主要是：


训练 query 的真实来源并不总对齐段落边界，完全结构分段会把训练分布拉得过“整齐”；

CPU 成本更高，对 FMA / MTG 这类大目录 smoke 和批量 manifest 生成不够轻；

当前阶段先追求稳健可复现，优先落地静音、起音、拍点、重复段这几类收益更直接的候选策略。


所以现在的设计不是“没考虑 librosa 分段”，而是：


已经用了 librosa 的轻量高收益部分
保留 random 作为泛化增强
把更重的结构分段留作后续增强，而不是一上来替代全部采样逻辑


6. 当前训练信号与 hard-case 规则


6.1 Hard-case 训练信号图

flowchart LR
    A[Query Segment] --> B{type}
    B -->|clean| C[w=1.0]
    B -->|augmented| D[w=1.4]
    B -->|humming_like| E[w=2.5]
    B -->|confused| F[w=4.0]
    C --> G[Sample-level SupCon + CE]
    D --> G
    E --> G
    F --> G


类型
当前训练权重
目标


clean
1.0
保持基础识别稳定


augmented
1.4
提高常规退化鲁棒性


humming_like
2.5
提高旋律近似查询鲁棒性


confused
4.0
强化最易混淆片段分离能力


6.2 检索融合参数图

flowchart LR
    A[Chromaprint Score] --> D[Fused Score]
    B[ECAPA Score] --> D
    C[Melody Score] --> D


参数
默认值
当前验证更优值（fast-eval）
含义


chroma_weight
0.25
0.20
降低纯指纹主导


ecapa_weight
0.50
0.55
提高 embedding 检索主导


melody_weight
0.25
0.25
暂时保持不变


7. 开源数据集 train/eval 切分图

flowchart LR
    A[Open Audio Dir] --> B[audio-dir-to-splits]
    B --> C[catalog.json]
    B --> D[train.json]
    B --> E[test.json]
    B --> F[val.json]


产物
用途
说明


catalog.json
建索引
所有 reference 曲目


train.json
训练查询
query + references


test.json
评估查询
query + references


val.json
预留验证集
当前可为空


推荐法则：


FMA / MTG-Jamendo 可优先用于真实 train/eval baseline
至少固定一部分曲目只进 test.json，不要同时参与训练
小数据集也要保证至少 1 个 train query + 1 个 test query


CLI 入口：


低层工具：acr-engine/src/data/manifest_tools.py

高层统一入口：acr-engine/src/data/external_adapters.py prepare-local <dataset> <input_dir>

导入前预检查：acr-engine/src/data/external_adapters.py inspect-local <dataset> <input_dir>

多目录批量预检查：acr-engine/src/data/external_adapters.py inspect-batch fma=<dir> mtg_jamendo=<dir> ...


8. 当前项目输入层规范


项目
当前值/建议
说明


采样率
16kHz
统一音频读取口径


声道
mono
当前链路按单声道处理


频谱
128 Mel
音乐任务输入层


训练 clip
5s
当前训练代码事实


外部 query manifest 默认
8s
当前 prepare-local/smoke-local 默认


Band split
enabled
已纳入当前模型配置


9. 文字说明


9.1 为什么必须分离 catalog 和 query

工业化系统里，“可搜索曲库”和“训练/评测 query”必须分离，否则评测会和真实服务语义混在一起。


9.2 为什么输入层是 128 Mel

音乐任务需要更丰富的频带表达；128 Mel 比 40 维 MFCC 更适合 timbre/harmony/band-split 建模。


9.3 为什么 query 类型必须显式标注

clean / augmented / confused / humming_like 不只是标签名，而是训练权重、评测 bucket、难例治理的入口。


9.4 关于 5s vs 8s 的一个当前注意点

当前仓库有两组时长：


训练 Dataset 与默认模型训练：5s
开放数据 manifest/query 默认：8s


这不是同一层配置，因此当前文档和实验报告里必须明确区分；不要把它们误认为一套统一参数。


9.5 当前经验结论


简单过采样会导致整体退化
type-aware weighting 能提升一部分 hard case
confused 类需要更高权重，但过强偏置会回伤 humming_like

residual confused failure 往往集中在 intro 片段，因此 segment_type 不只是元数据，还应参与后续难负例设计


10. 细节附录


Reference 示例

{
  "song_id": "song_0001",
  "audio_path": "songs/song_0001.wav",
  "duration": 20.0,
  "type": "reference"
}


Query 示例

{
  "song_id": "song_0001",
  "audio_path": "segments/song_0001_seg_04_confused.wav",
  "duration": 5.0,
  "type": "confused",
  "offset": 8.3,
  "segment_type": "mid"
}


Sources


当前代码事实来自 acr-engine/src/data/dataset.py, acr-engine/src/data/manifest_tools.py, acr-engine/src/utils/audio.py, acr-engine/src/engines/ecapa_embedder.py, acr-engine/train.py