Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Commit fa7f5f57 fa7f5f576d81902b8b307b47f4452244423b9657 by cnb.bofCdSsphPA
Options

Clarify the real data contract before scaling external datasets 

Constraint: Must document code-true behavior for training crops, retrieval windows, GPU support, and FMA reuse before more dataset automation lands
Rejected: Leave docs at high-level abstractions only | Would hide 5s-vs-8s and CPU-vs-GPU operational realities
Confidence: high
Scope-risk: narrow
Directive: Keep future dataset docs aligned with actual code paths and artifact timestamps, not intended architecture alone
Tested: Source review of dataset.py manifest_tools.py external_adapters.py utils/audio.py ecapa_embedder.py train.py; live FMA smoke progress observed through epoch completion
Not-tested: Markdown renderer-specific Mermaid rendering and every relative link target in external viewers
1 parent 713425f5
Expand all
Inline Side-by-side
Showing 3 changed files with 124 additions and 48 deletions
...@@ -2,6 +2,34 @@ ...@@ -2,6 +2,34 @@
2 2
3 ## 2026-06-02 3 ## 2026-06-02
4 4
5
6 ### Stage: 补齐训练数据、重叠窗口、GPU 与 FMA 数据处理文档
7
8 完成项：
9 - 重写并压缩 `dataset-spec.md`，补齐训练切片、检索重叠滑窗、manifest 生成差异
10 - 扩展 `training-data-and-pgvector-guide.md`，补齐 FMA / MTG / 自有数据接入、目录规范、脚本职责、GPU 加速说明
11 - 明确记录当前真实代码事实：训练端 5s 随机裁剪、检索端 5s/2.5s 重叠滑窗、外部 manifest 默认 8s query
12 - 记录当前 smoke 现状：`smoke-local` 仍固定 CPU，真实 FMA smoke 正在运行
13 - 记录当前实验产物一致性风险：旧的 `fma_reports_smoke/config.json` 与最新 manifests 时间戳不一致，需后续统一配置治理
14
15 验证结果：
16 - 源码复核：
17 - `src/data/dataset.py`：训练端随机 5s crop
18 - `src/utils/audio.py` / `src/engines/ecapa_embedder.py`：5s window + 2.5s stride
19 - `src/data/manifest_tools.py`：每首歌 1 个随机 query，默认 `8.0s`
20 - `src/data/external_adapters.py`：`smoke-local` 当前硬编码 `--device cpu`
21 - `train.py`：支持 `--device auto`，CUDA 路径支持 mixed precision
22 - 真实运行状态：
23 - FMA smoke 进程仍在运行
24 - 最新可见进度约 `82%` epoch 1
25 - 文档链接验证：主文档仍使用相对路径链接到仓库文件与同组文档
26
27 结论：
28 - 当前项目关于训练数据格式、3 分钟 mp3 切片、是否重叠窗口、GPU 是否可显著加速、FMA 与开放数据如何复用流程，已形成可交接文档
29 - 后续可继续沿两条线推进：
30 1. 让 `smoke-local` 支持 GPU
31 2. 增加 overlap query manifest 生成能力
32
5 ### Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练 33 ### Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练
6 34
7 完成项： 35 完成项：
......
1 # ACR Dataset / 输入输出规范 1 # ACR Dataset / 输入输出规范
2 2
3 > 更新：2026-06-02 3 > 更新：2026-06-02
4 > 关联文档：[训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md) · [开放数据工作流](./open-dataset-workflow.md) · [数据来源与接入](./dataset-sources-and-licensing.md)
4 5
5 ## 一页结论 6 ## 一页结论
6 7
7 - 数据规范的核心不是文件格式，而是**分离 catalog 与 query** 8 当前项目的数据规范，最重要的是 4 件事：
8 - 外部数据集进入系统前必须先转换成统一 manifest 9
9 - 当前系统的标准输入是： 10 1. **训练输入不是“整首 mp3 文件”本身，而是 manifest 驱动的 reference + query 样本体系**。
10 - **16k mono audio** 11 2. **训练和检索的切窗策略不同**：训练端当前是**随机裁剪 5s**，检索/建索引端当前是**5s 窗口 + 2.5s stride 的 50% 重叠滑窗**。
11 - **128 Mel** 12 3. **外部开源数据集进入项目时，必须先转换成统一 manifest**，再做训练、评测、索引和 pgvector 入库。
12 - **window-level retrieval** 13 4. **当前音乐任务输入层已切换到 128 维 Mel 频谱**，并开启 band-split 方向；FMA 这类真实数据建议优先使用 GPU。
13 - 当前系统的标准输出是：
14 - top-k candidates
15 - confidence
16 - reject/accept
17 - metadata
18 14
19 --- 15 ---
20 16
...@@ -22,13 +18,14 @@ ...@@ -22,13 +18,14 @@
22 18
23 ```mermaid 19 ```mermaid
24 flowchart LR 20 flowchart LR
25 A[External / Synthetic Audio] --> B[Manifest Conversion] 21 A[Raw Audio\nFMA / MTG / 自有 BGM / 录音] --> B[Manifest Conversion]
26 B --> C[Catalog Manifest] 22 B --> C[Catalog Manifest\nreference]
27 B --> D[Query Manifest] 23 B --> D[Train/Test Manifest\nquery]
28 C --> E[Reference Index Build] 24 C --> E[Reference Index Build\nsliding windows]
29 D --> F[Training / Evaluation Queries] 25 D --> F[Training / Evaluation]
30 E --> G[Hybrid Retrieval] 26 E --> G[Hybrid Retrieval]
31 F --> G 27 F --> G
28 G --> H[pgvector / report / service]
32 ``` 29 ```
33 30
34 --- 31 ---
...@@ -58,6 +55,7 @@ flowchart TD ...@@ -58,6 +55,7 @@ flowchart TD
58 Q --> Q2[audio_path] 55 Q --> Q2[audio_path]
59 Q --> Q3[duration] 56 Q --> Q3[duration]
60 Q --> Q4[type=clean/augmented/confused/humming_like] 57 Q --> Q4[type=clean/augmented/confused/humming_like]
58 Q --> Q5[offset]
61 ``` 59 ```
62 60
63 --- 61 ---
...@@ -66,14 +64,60 @@ flowchart TD ...@@ -66,14 +64,60 @@ flowchart TD
66 64
67 | 环节 | 输入 | 输出 | 65 | 环节 | 输入 | 输出 |
68 |---|---|---| 66 |---|---|---|
69 | 训练 | query segments | embeddings + logits | 67 | 训练 | query segments + references | embeddings + logits |
70 | 索引 | catalog references | chromaprint index + embedding index | 68 | 索引 | catalog references | chromaprint index + embedding index |
71 | 识别 | query audio | ranked candidates | 69 | 识别 | query audio | ranked candidates |
72 | 评测 | query manifest + catalog | top1/top5/hard-case report | 70 | 评测 | query manifest + catalog | top1/top5/hard-case report |
71 | 入库 | manifest + embedding | pgvector-ready JSON / SQL rows |
73 72
74 --- 73 ---
75 74
76 ## 4.1 Hard-case 训练信号图 75 ## 5. 3 分钟 mp3 到 5–8 秒片段：当前到底怎么切
76
77 ## 5.1 当前代码里有 **3 种不同切法**
78
79 ```mermaid
80 flowchart TD
81 A[3min mp3] --> B[训练 Dataset]
82 A --> C[检索 / 建索引]
83 A --> D[外部数据集 manifest 生成]
84
85 B --> B1[随机裁 1 个 5s clip]
86 C --> C1[5s 窗 + 2.5s stride]\n50% overlap
87 D --> D1[每首歌随机采 1 个 query]\n默认 8s
88 ```
89
90 | 场景 | 当前实现 | 是否重叠 | 代码位置 |
91 |---|---|---:|---|
92 | 训练 `SongPairDataset` | 每次采样随机取一个 5s clip | 否，**不是固定滑窗** | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
93 | 检索 / embedding / 建索引 | `window_sec=5.0`, `stride_sec=2.5` | 是，**50% overlap** | [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py), [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py) |
94 | `audio-dir-to-splits` | 每首歌只生成 1 个随机 query | 否 | [acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py) |
95
96 ### 直接回答你的问题
97
98 - **有重叠窗口，但只在检索/索引链路里有。**
99 - **当前训练主链路没有对 3 分钟 mp3 预展开成“全量重叠切片集”**，而是每次 batch 动态随机裁一个 5s 片段。
100 - **当前外部数据集 manifest 生成器也没有自动为每首歌生成多个重叠 query。**
101
102 ---
103
104 ## 5.2 为什么这样设计
105
106 | 设计点 | 当前好处 | 当前限制 |
107 |---|---|---|
108 | 训练随机裁剪 | 节省存储，不必预生成几万切片 | 同一 epoch 暴露到的时间区域有限 |
109 | 检索重叠滑窗 | 更接近真实 ACR reference coverage | 索引体积更大 |
110 | 外部数据一首歌一个 query | smoke 更轻、更快验证 | 训练/评测覆盖不充分 |
111
112 推荐理解方式：
113 - **训练端**更像“随机数据增强采样器”
114 - **检索端**更像“为了召回覆盖做滑窗索引”
115
116 ---
117
118 ## 6. 当前训练信号与 hard-case 规则
119
120 ## 6.1 Hard-case 训练信号图
77 121
78 ```mermaid 122 ```mermaid
79 flowchart LR 123 flowchart LR
...@@ -97,7 +141,7 @@ flowchart LR ...@@ -97,7 +141,7 @@ flowchart LR
97 141
98 --- 142 ---
99 143
100 ## 4.2 检索融合参数图 144 ## 6.2 检索融合参数图
101 145
102 ```mermaid 146 ```mermaid
103 flowchart LR 147 flowchart LR
...@@ -112,14 +156,9 @@ flowchart LR ...@@ -112,14 +156,9 @@ flowchart LR
112 | `ecapa_weight` | 0.50 | 0.55 | 提高 embedding 检索主导 | 156 | `ecapa_weight` | 0.50 | 0.55 | 提高 embedding 检索主导 |
113 | `melody_weight` | 0.25 | 0.25 | 暂时保持不变 | 157 | `melody_weight` | 0.25 | 0.25 | 暂时保持不变 |
114 158
115 说明：
116 - 当前仓库已经支持在 `evaluate.py` 中直接传入融合参数
117 - 对个人使用场景，推荐把一部分开源数据集固定成 **fusion tuning eval set**
118 - 这样训练、检索、调参可以分离，而不是每次都重训
119
120 --- 159 ---
121 160
122 ## 4.3 开源数据集 train/eval 切分图 161 ## 7. 开源数据集 train/eval 切分图
123 162
124 ```mermaid 163 ```mermaid
125 flowchart LR 164 flowchart LR
...@@ -137,7 +176,7 @@ flowchart LR ...@@ -137,7 +176,7 @@ flowchart LR
137 | [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json) | 评估查询 | query + references | 176 | [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json) | 评估查询 | query + references |
138 | [val.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/val.json) | 预留验证集 | 当前可为空 | 177 | [val.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/val.json) | 预留验证集 | 当前可为空 |
139 178
140 推荐法则（个人使用）： 179 推荐法则：
141 - FMA / MTG-Jamendo 可优先用于真实 train/eval baseline 180 - FMA / MTG-Jamendo 可优先用于真实 train/eval baseline
142 - 至少固定一部分曲目只进 [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json)，不要同时参与训练 181 - 至少固定一部分曲目只进 [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json)，不要同时参与训练
143 - 小数据集也要保证至少 1 个 train query + 1 个 test query 182 - 小数据集也要保证至少 1 个 train query + 1 个 test query
...@@ -148,38 +187,48 @@ CLI 入口： ...@@ -148,38 +187,48 @@ CLI 入口：
148 - 导入前预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-local <dataset> <input_dir>` 187 - 导入前预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-local <dataset> <input_dir>`
149 - 多目录批量预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-batch fma=<dir> mtg_jamendo=<dir> ...` 188 - 多目录批量预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-batch fma=<dir> mtg_jamendo=<dir> ...`
150 189
151 ## 5. 文字说明 190 ---
191
192 ## 8. 当前项目输入层规范
193
194 | 项目 | 当前值/建议 | 说明 |
195 |---|---|---|
196 | 采样率 | `16kHz` | 统一音频读取口径 |
197 | 声道 | `mono` | 当前链路按单声道处理 |
198 | 频谱 | `128 Mel` | 音乐任务输入层 |
199 | 训练 clip | `5s` | 当前训练代码事实 |
200 | 外部 query manifest 默认 | `8s` | 当前 `prepare-local/smoke-local` 默认 |
201 | Band split | `enabled` | 已纳入当前模型配置 |
152 202
153 ### 5.1 为什么必须分离 catalog 和 query 203 ---
154 早期原型容易把 train split 直接当搜索库，这会让评测和真实服务语义混乱。工业化系统必须把：
155 - “可搜索曲库”
156 - “训练/评测 query”
157 204
158 明确分离。 205 ## 9. 文字说明
159 206
160 ### 5.2 为什么输入层是 128 Mel 207 ### 9.1 为什么必须分离 catalog 和 query
161 音乐任务需要更丰富的频带表达，128 Mel 更适合 band-split 和音乐 timbre/harmony 建模。 208 工业化系统里，“可搜索曲库”和“训练/评测 query”必须分离，否则评测会和真实服务语义混在一起。
162 209
163 ### 5.3 query 类型为什么要显式标注 210 ### 9.2 为什么输入层是 128 Mel
164 `clean / augmented / confused / humming_like` 是评测与训练策略的重要条件，不应只放在隐式文件名里。 211 音乐任务需要更丰富的频带表达；128 Mel 比 40 维 MFCC 更适合 timbre/harmony/band-split 建模。
165 212
166 ### 5.4 为什么 hard-case 权重必须做到 sample-level 213 ### 9.3 为什么 query 类型必须显式标注
167 如果只在 batch 级取平均权重，`confused` 这种少量但高风险样本会被正常样本稀释。当前版本已经改成 **sample-level weighted SupCon + sample-level weighted CE**，从而让单个困难片段在损失中真实“被看见”。 214 `clean / augmented / confused / humming_like` 不只是标签名，而是训练权重、评测 bucket、难例治理的入口。
168 215
169 ### 5.5 当前经验结论 216 ### 9.4 关于 5s vs 8s 的一个当前注意点
217 当前仓库有两组时长：
218 - **训练 Dataset 与默认模型训练：5s**
219 - **开放数据 manifest/query 默认：8s**
220
221 这不是同一层配置，因此当前文档和实验报告里必须明确区分；不要把它们误认为一套统一参数。
222
223 ### 9.5 当前经验结论
170 - 简单过采样会导致整体退化 224 - 简单过采样会导致整体退化
171 - type-aware weighting 能提升一部分 hard case 225 - type-aware weighting 能提升一部分 hard case
172 - confused 类需要更高权重，但过强偏置会回伤 `humming_like` 226 - confused 类需要更高权重，但过强偏置会回伤 `humming_like`
173 - residual confused failure 往往集中在 `intro` 片段，因此 `segment_type` 不只是元数据，还应参与后续难负例设计 227 - residual confused failure 往往集中在 `intro` 片段，因此 `segment_type` 不只是元数据，还应参与后续难负例设计
174 - 因此 dataset 规范中必须保留 `type` 字段，后续才能继续做：
175 - confusion-aware negative mining
176 - melody-aware reranking
177 - 双支路 hard-case curriculum
178 - segment-type-aware hard negatives
179 228
180 --- 229 ---
181 230
182 ## 6. 细节附录 231 ## 10. 细节附录
183 232
184 ### Reference 示例 233 ### Reference 示例
185 ```json 234 ```json
...@@ -203,6 +252,5 @@ CLI 入口： ...@@ -203,6 +252,5 @@ CLI 入口：
203 } 252 }
204 ``` 253 ```
205 254
206
207 ## Sources 255 ## Sources
208 - See [references-and-sources.md](./references-and-sources.md) for the current source map. 256 - 当前代码事实来自 [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py), [acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py), [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py), [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py), [acr-engine/train.py](../acr-engine/train.py)
......