training-data-and-pgvector-guide.md 12.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，属于需要继续治理的实验产物一致性问题；
因此后续继续做工业级化时，应该把 “manifest query 时长 / train clip 时长 / eval query 时长 / report metadata” 统一纳入一个显式配置结构。


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


完整曲库先做 reference 池。

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

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


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