training-data-and-pgvector-guide.md 25.5 KB

Raw Blame History Permalink



Training Data, Input Format, and pgvector Guide / 训练数据、输入格式与 pgvector 指南


更新：2026-06-02

关联文档：数据规范 · 开放数据工作流 · 数据来源与接入 · 服务接口


一页结论

围绕你最新问的几个问题，可以压缩成 5 句话：


当前训练输入的最小单位是“带 song_id 的 query 样本 + reference 资产 + manifest”，不是直接把 3 分钟 mp3 整批扔进模型。
3 分钟 mp3 当前在训练端通常不是预切全量重叠窗口，而是运行时随机裁 5s；检索端才是重叠滑窗。
如果有 GPU，FMA 这类真实数据训练会明显加速；当前 train.py 支持 auto/cuda，smoke-local 也已支持 --device cpu|cuda|auto，其中 auto 会在 smoke 内部解析成实际设备。
FMA、MTG-Jamendo、自有 BGM/录音都应先变成统一 manifest，再做训练、评测和 pgvector 入库。
后续你们要扩自己的数据集时，最重要的不是文件后缀，而是 song_id / type / offset / source_dataset / split 这些结构化字段。


1. 总体结构图

flowchart LR
    A[原始素材\nBGM / 歌曲 / 录音 / FMA] --> B[标准化音频资产\n16k / mono]
    B --> C[Reference 全曲/长片段]
    B --> D[Query 短片段\n5s / 8s]
    C --> E[Manifest\ncatalog/train/val/test]
    D --> E
    E --> F[训练 / 评测 / 建索引]
    F --> G[Embedding / Fingerprint]
    G --> H[PostgreSQL + pgvector]


2. 当前训练数据到底是什么格式


2.1 不是“一个 mp3 文件”，而是三层对象


层
现在需要什么
作用


音频资产层
.wav/.mp3/.flac/.ogg
真正被读取的内容


标注层

song_id、type、offset、source_dataset

告诉系统“是谁、是哪种样本”


manifest 层

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

驱动训练、建库、评测


也就是说，最小可训练单元不是“一个文件”，而是：


一个 audio_path

一个 song_id

一个 type

一个 duration

如为 query，通常还应有 offset


2.2 当前推荐音频约束


项目
当前推荐值
说明


采样率
16000 Hz
读取时统一到 16k


声道
mono
当前管线按单声道


训练片段长度
5s
训练数据集代码事实


外部 query 默认长度
8s

prepare-local/smoke-local 默认


频谱输入
128 维 Mel
当前音乐任务输入层


模型配置
use_band_split=true
已集成频带分割模块


3. 3 分钟 mp3 怎么进入训练


3.1 当前切片策略图

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

    B --> B1[随机 offset]
    B1 --> B2[取 5s clip]

    C --> C1[5s window]
    C1 --> C2[2.5s stride]
    C2 --> C3[50% overlap windows]

    D --> D1[随机取 1 个 8s query]


3.2 直接回答“有没有重叠窗口”


链路
当前答案


训练

没有固定重叠滑窗集，而是随机裁剪


检索 / reference index

有，默认 50% overlap


开放数据 manifest 生成

没有，默认每首歌只生成 1 个 query


所以：


如果你担心 3 分钟内容只看一小段，担心是合理的；
当前训练覆盖靠多次 epoch 的随机采样累积，而不是一次性把整首歌切完；
如果后续要提高 recall/鲁棒性，可以继续加“多 query / overlap query manifest”这条增强线。


4. 如果有 BGM、音乐录音，应该怎么转成训练数据


4.1 推荐分工图

flowchart LR
    A[自有 BGM / 歌曲母带] --> B[reference]
    A --> C[clean query]
    A --> D[augmented query]
    A --> E[confused / humming_like]
    F[手机录音 / 环境录音] --> C
    F --> E


4.2 转换规则表


原始素材
转成什么
标记建议


完整 BGM / 完整歌曲
reference
type=reference


原曲直接截 5s/8s

clean query
type=clean


加噪/压缩/混响/EQ 后片段

augmented query
type=augmented


容易和别的歌混淆的片段
难例 query
type=confused


哼唱感、旋律弱、手机录音风格
难例 query
type=humming_like


4.3 你们自己扩数据集时的最小规则


一首歌必须有稳定 song_id。

完整版本或主版本优先做 reference。

query 一定要能回溯到 reference 的时间位置，因此最好保留 offset。

不同来源必须保留 source_dataset。

训练、验证、测试必须保留 split 语义，不要后面再靠文件夹猜。


5. FMA / MTG / 自有数据的目录规范


5.1 推荐目录图

flowchart TD
    A[acr-engine/data/raw] --> B[fma_small_audio]
    A --> C[mtg_jamendo_audio]
    A --> D[my_bgm_audio]

    E[acr-engine/data/external_ingested] --> F[fma/manifests]
    E --> G[mtg_jamendo/manifests]
    E --> H[my_bgm/manifests]

    I[acr-engine/data/external_smoke] --> J[fma_*]


5.2 目录职责表


目录
作用


acr-engine/data/raw/fma_small_audio/
FMA 原始音频目录


acr-engine/data/raw/mtg_jamendo_audio/
MTG-Jamendo 原始音频目录


acr-engine/data/external_ingested/<dataset>/manifests/
统一转换后的 manifest


acr-engine/data/external_smoke/
smoke 训练/索引/评测产物


6. FMA 的具体说明


6.1 当前已验证的 FMA 事实


项
当前状态


数据源
用户指定 ModelScope FMA Small 链接


本地目录
acr-engine/data/raw/fma_small_audio


音频文件数
8000


可切 query 文件
7994


中位时长
29.977s


真实 smoke
正在运行 / 已产生中间产物


真实检查入口：


acr-engine/src/data/external_adapters.py check-local-ready


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


6.2 FMA cookbook

cd /workspace/acr-engine

/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 validate-local \
  fma data/external_ingested/fma/manifests


如果只是验证全链路：

/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


7. 当前脚本与职责索引


脚本/文件
作用


acr-engine/src/data/manifest_tools.py
音频目录 -> manifest


acr-engine/src/data/external_adapters.py
inspect / prepare / validate / smoke 统一入口


acr-engine/src/data/dataset.py
训练/测试数据集读取与随机裁剪


acr-engine/src/utils/audio.py
通用音频处理与滑窗


acr-engine/src/engines/ecapa_embedder.py
embedding 抽取与 reference 滑窗索引


acr-engine/train.py
训练主入口


acr-engine/evaluate.py
评测主入口


acr-engine/run_demo.py
build-index / query demo


acr-engine/scripts/export_manifest_to_pgvector_json.py
manifest 导出为 pgvector-ready JSON


acr-engine/scripts/pgvector_bulk_load_template.py
PostgreSQL 批量导入模板


acr-engine/sql/pgvector_schema.sql
pgvector 表结构模板


8. GPU 是否会快很多


8.1 结论先说

会。对于 FMA 这种 8000 首规模的真实数据，GPU 通常会比 CPU 快很多。

原因：


Mel 特征后面的 ECAPA 前向/反向传播主要是张量计算；
当前 train.py 已支持 --device auto，且 CUDA 路径已启用 mixed precision；
真实 FMA smoke 当前跑在 CPU，上千 batch 训练明显慢。


8.2 当前代码现状


链路
当前状态


train.py
支持 --device auto/cuda/cpu


CUDA mixed precision
已支持


smoke-local
现已支持 `--device cpu


evaluate.py
当前 CLI 默认 cpu


run_demo.py build-index
当前 smoke 里也走 cpu


当前要注意的一点

smoke-local 现在已经支持显式设备选择，但有一个实现细节必须明确：


train.py 可以直接理解 auto


run_demo.py / evaluate.py 的 embedding 侧不能直接吃字符串 auto


所以当前 smoke-local 的做法是：


对外允许传 --device auto

对内先解析成真实设备，再分发给训练 / 建索引 / 评测


这让真实数据 smoke 可以直接复用 GPU，而不需要手工拆成多段命令。


9. 如果后面要保存到 pgvector，现在应该怎么处理


9.1 正确分层


内容
存储位置


原始音频 / 标准音频
文件系统 / NAS / 对象存储


manifest / 元数据
PostgreSQL 普通表


向量 embedding

pgvector 列


检索参数与版本
PostgreSQL / 配置中心


原则：


不要把原始 mp3 直接塞进 pgvector 表；
先标准化音频和 manifest；
再从 manifest 产出 embedding 与结构化记录。


9.2 pgvector 推荐数据模型

flowchart TD
    A[songs] --> B[references]
    A --> C[segments]
    B --> D[reference_embeddings]
    C --> E[query_embeddings]


当前仓库模板：


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


9.3 从今天开始就该保留的字段


字段
作用


song_id
主连接键


version_id
多版本扩展


audio_path / audio_uri

回溯音频资产


duration
切片合法性校验


offset
query 对应 reference 的时间位置


type
训练/检索角色


segment_type
intro/mid/outro/external


source_dataset
数据来源治理


license
合规治理


split
train/val/test


model_version
向量版本控制


data_version
数据快照版本


10. 当前一个真实注意点：5s / 8s 配置差异

当前仓库里有一个必须写进交接文档的现实问题：


项
当前事实


smoke-local 命令
常用 --query-duration 8.0


训练 dataset
仍按 segment_dur=5.0 读取


现有 FMA smoke 报告 config.json

出现过 query_duration=5.0 的旧产物


解释：


manifest query 时长、训练 crop 时长、报告里记录的 query_duration 当前不是完全同一个配置源；
旧的 fma_reports_smoke/config.json 时间戳早于最新 manifests，属于历史实验产物一致性问题；
当前代码侧已经开始把 smoke 配置摘要显式拆成：


manifest_query_duration
train_segment_duration
query_duration_legacy


因此后续继续做工业级化时，应该把 “manifest query 时长 / train clip 时长 / eval query 时长 / report metadata” 统一纳入一个显式配置结构。


11. 给你们后续自建数据集的落地建议


完整曲库先做 reference 池。

从 reference 池切出 clean query 作为第一层训练集。

再做 augmented / confused / humming_like 三类增强 query。
固定一部分永不训练，只做 test set。
先把 manifest 字段做全，再谈 pgvector 和工业服务。


11.5 切片策略：不要只用随机切

当前项目现在已经支持多类切片思路，但职责不同：


策略
适用位置
作用
是否已接入


random
训练 query
增强泛化，模拟未知用户截取点
是


sliding
建库 / query 生成
保证覆盖率，减少漏召回
是


silence_aware
训练 query / 外部 query 生成
优先避开静音，落到真正有音乐内容的片段
是


high_energy
训练 query / 外部 query 生成
优先抽取 RMS 高能区，更接近副歌/主唱/强节奏段
是


onset_aware
训练 query / 外部 query 生成
优先靠近起音事件，减少截到拖尾/空拍
是


beat_aware
训练 query / 外部 query 生成
优先靠近节拍点，适合强节奏流行/电子/舞曲等
是


repeated_section_aware
训练 query / 外部 query 生成
优先抽取与其它窗口最相似的重复主段，近似副歌/重复 hook
是


hybrid
训练 query / 外部 query 生成
混合 repeated-section / beat / energy / onset / silence / random
是


推荐理解：


训练不是全部随机切

当前训练集可用 random / silence_aware / high_energy / onset_aware / beat_aware / repeated_section_aware / hybrid


reference 建库不是随机切

建库仍然是固定滑窗

外部数据 query 生成也不是只能随机切

现在可选 --query-strategy random|silence_aware|high_energy|onset_aware|beat_aware|repeated_section_aware|hybrid


11.6 为什么没有直接全量切到 librosa.segment.*


这不是没考虑，而是当前做了更保守的工程取舍：


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

先把非静音、起音、拍点、重复段这些高收益候选打通
暂时没有把更重的结构分段作为默认主流程


原因：


ACR 查询不总是结构化片段

用户截到的可能是副歌，也可能是过门、录屏残片、短视频二创片段。

重结构分段更耗 CPU

对 FMA 这类真实开放集批量 prepare/smoke 不够轻。

训练仍需要随机性

纯结构分段会降低截取点分布的多样性。


当前更合理的策略是：


hybrid 作为默认训练切片推荐

beat_aware / repeated_section_aware 作为偏音乐主段的强化选项

random 保留为泛化基线


为什么不直接完全依赖音乐结构分段？


ACR 真实 query 往往来自短视频、录屏、随手截取，不一定对齐节拍或段落边界
先做 静音感知分段，收益最大、风险最小
更复杂的 beat / chorus / onset 分段可以作为下一阶段增强，而不应替代现有随机增强


训练侧推荐

/usr/local/miniconda3/bin/python acr-engine/train.py \
  --data data/your_manifests \
  --segment-strategy hybrid \
  --silence-top-db 30


建议：


baseline：random

更稳的音乐任务：hybrid

已知原始音频静音很多：silence_aware

更想贴近副歌/强节奏：high_energy

更想贴近短音起点/打点：onset_aware

更想贴近稳定节拍网格：beat_aware

更想贴近副歌/重复 hook：repeated_section_aware


外部数据 query 生成推荐

/usr/local/miniconda3/bin/python acr-engine/src/data/external_adapters.py prepare-local fma data/raw/fma_small_audio \
  --output-root data/external_ingested \
  --query-duration 8 \
  --query-stride 4 \
  --query-strategy high_energy \
  --silence-top-db 30


这会优先从高能区生成 query，而不是从长静音头尾或低能过门里随机采样。

补充建议：


场景
推荐策略


录音静音头尾很多
silence_aware


更想贴近副歌/主段
high_energy


更想贴近打点/起唱点
onset_aware


更想贴近规则拍点/律动骨架
beat_aware


更想贴近重复主段/副歌 hook
repeated_section_aware


既要音乐感知，又要保留泛化
hybrid


12. 你这批内部素材 type，哪些推荐参与训练


12.1 一页结论

如果目标是做 音乐 ACR / 歌曲识别，推荐按下面的优先级：


主 reference 首选：11 原曲-无损


次级 reference / 兼容增强：1 原曲-压缩


主 query 来源：7 抖音片段、8 片段(副歌)、16 快手片段、18 音频demo


伴奏类：2/9/10/12 不建议直接无脑混进“原曲主任务”同标签训练，除非你们的业务明确要识别伴奏版本

纯文本/图片/授权/压缩包：不进音频训练，只进元数据治理


12.2 推荐映射表


type
内容
建议角色
是否进主训练
建议说明


1
原曲-压缩(mp3)
secondary reference / clean query 来源
是
当 11 缺失时可做主 reference；有 11 时更适合做压缩退化增强


2
伴奏有和声-压缩(mp3)
可选单独版本库 / hard negative
条件式
不建议直接和原曲共用同一训练语义


3
TXT歌词
metadata
否
可入库做检索增强，不进音频模型


4
封面
metadata
否
不进音频训练


5
授权书
compliance metadata
否
只做合规治理


6
专辑信息(txt)
metadata
否
只做元数据


7
抖音片段
query
是
很适合真实 query 训练/评测


8
片段(副歌)
query
是
高价值 query，建议重点保留


9
伴奏无和声-压缩(mp3)
可选单独版本库 / hard negative
条件式
不建议默认并入原曲主标签


10
伴奏无和声-无损
可选 reference / hard negative
条件式
仅在“识别伴奏版本”任务里进入主训练


11
原曲-无损(wav/flac)
primary reference
强烈推荐
最适合作为标准 reference 真值


12
伴奏有和声-无损
可选单独版本库 / hard negative
条件式
与原曲声学差异大，默认不要并到原曲主任务


13
滚动歌词(lrc)
metadata
否
可做歌词侧检索，不进音频模型


14
封面源文件(psd)
metadata
否
不进训练


16
快手片段
query
是
与 7 类似，适合真实短视频场景评测


17
词曲压缩包
archive metadata
否
先解包治理，不直接训练


18
音频demo(mp3/wav)
query / weak reference
条件式
先按质量分层；可做 query，必要时做辅 reference


19
曲谱(png)
metadata
否
不进音频训练


20
译文滚动歌词
metadata
否
只做文本侧扩展


12.3 最推荐的主任务训练组合


A. 如果你的目标是“识别原曲”

reference:
- 11 原曲无损（主）
- 1 原曲压缩（辅）

query:
- 从 11 / 1 切 5s / 8s clean query
- 7 抖音片段
- 8 副歌片段
- 16 快手片段
- 18 音频demo（筛质后）


B. 如果你的目标是“原曲 + 伴奏版本都要识别”

建议不要直接把原曲和伴奏粗暴合并成同一个训练标签，而是至少保留：


canonical_song_id：作品级 ID

version_id：版本级 ID

audio_role：original / inst_with_harmony / inst_no_harmony / short_clip / demo


这样你后面可以做两种策略：


作品级识别


原曲和伴奏共享 canonical_song_id

但保留不同 version_id


版本级识别


原曲和伴奏完全分开标签


如果你现在主目标只是 ACR 识别“这首歌是谁”，而不是区分伴奏版本，建议先走策略 1，但训练时不要让伴奏版本无脑占太高比例，否则会把主模型拉偏。


12.4 我给你的实际建议


第一批一定要进的数据


11 原曲无损
1 原曲压缩
7 抖音片段
8 副歌片段
16 快手片段


第二批可控加入的数据


18 音频demo


先按质量筛选
干净 demo 可做 query
明显截断/噪声重的 demo 进 hard-case pool


不建议第一阶段直接并入主训练标签的数据


2 伴奏有和声
9 伴奏无和声-压缩
10 伴奏无和声-无损
12 伴奏有和声-无损


更稳妥的做法：


先单独入库
先做评测集 / hard negative
等主模型稳定后，再决定是否做多版本任务


12.5 对应 manifest / pgvector 字段建议

如果你们要把这些 type 真正落到训练和数据库，建议至少补这几个字段：


字段
示例
作用


canonical_song_id
song_123
作品主键


version_id
song_123_orig_lossless
版本主键


asset_type_code
11
原始 type 枚举


audio_role
original_lossless
训练与检索语义


type
reference / clean / augmented / confused
模型训练角色


source_platform
douyin / kuaishou / internal
来源治理


一个实用映射例子


原始 type
推荐 audio_role

推荐训练 type


11
original_lossless
reference


1
original_lossy

reference 或 clean


7
short_video_clip

clean / confused


8
chorus_clip
clean


16
short_video_clip

clean / confused


18
demo_audio

clean / augmented


2/9/10/12
instrumental_variant
先不进主训练，或做 hard negative


12.6 现在仓库里已经有可执行映射脚本

脚本：


acr-engine/scripts/internal_asset_type_mapper.py


作用：


读取内部素材 CSV
按 type 枚举自动分流成：


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


可选直接生成：


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


可选直接生成：


pgvector_payload.json


可选做音频校验：


audio_exists
duration_sec
validation_status


最短示例：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --output-dir out/internal_asset_map


如果你希望直接产出可训练 manifest：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --output-dir out/internal_asset_map --emit-manifests --eval-ratio 0.2


如果你们的 CSV 里是相对路径，推荐加上音频根目录：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --audio-root data/internal_audio --output-dir out/internal_asset_map --emit-manifests


这样脚本会自动补：


audio_exists
duration

missing_audio 汇总


同时脚本现在还支持：


--duration-field
--offset-field
--default-query-duration
--default-query-offset
--query-stride


规则是：


query 优先使用 CSV 自带的 duration/offset

duration 没有时，回落到默认 query duration（例如 8.0s），而不是整首音频时长
音频总时长会单独保留为 source_audio_duration，供 query 滑窗展开使用
offset 有 CSV 显式值时，保持单条 query，不做自动扩窗
offset 没有显式值且设置了 --query-stride 时，会按滑窗方式自动展开成多条 query
若未设置 --query-stride，offset 没有显式值时回落到默认值（通常 0.0）


推荐参数：


场景
推荐参数
说明


内部短视频片段已人工标好起点
--offset-field offset_sec
保留人工时间戳，避免自动扩窗覆盖人工标注


只有整首原始音频，没有 query 起点
--default-query-duration 8 --query-stride 4
自动产出 50% overlap 的多窗口 query


只想先做最小可用集
--default-query-duration 8
每条 query 只导出 1 个片段，默认 offset=0


如果你们下一步就是要进 PostgreSQL / pgvector，可直接导出：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --audio-root data/internal_audio --output-dir out/internal_asset_map --emit-pgvector-json --pgvector-split train


自动扩窗示例：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv \
  --audio-root data/internal_audio \
  --output-dir out/internal_asset_map \
  --default-query-duration 8 \
  --query-stride 4 \
  --emit-manifests \
  --emit-pgvector-json


例如 30s 音频在 8s query、4s stride 下会导出 offset：


0, 4, 8, 12, 16, 20, 22


导出的 queries.json 与 pgvector_payload.json 中都会保留 query_index，方便后续追踪窗口来源。

输出会包含：


songs
references
segments


并额外带上：


audio_role
asset_type_code
audio_exists
validation_status


如果你想临时把伴奏类也纳入导出，可用：

/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --output-dir out/internal_asset_map --include-conditionals-as query


但默认仍建议：


--include-conditionals-as skip


这样更符合当前主任务“先把原曲识别打稳，再逐步纳入伴奏版本”的策略。


Sources


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