training-data-and-pgvector-guide.md
15.8 KB
Training Data, Input Format, and pgvector Guide / 训练数据、输入格式与 pgvector 指南
一页结论
你这次问的两个核心问题，可以先压缩成一句话：
-
当前训练输入的最小单位是“带
song_id标签的音频片段 + reference 全曲/长片段 + manifest”，不是只扔一堆音频文件进去。
- 如果后面要接入
pgvector，应先把音频转成标准资产和 manifest，再从 manifest 生成 embedding 与结构化元数据，不要直接把原始音频塞进数据库。
1. 总体结构图
flowchart LR
A[原始素材\nBGM / 歌曲 / 录音] --> B[标准化音频资产\n16k / mono / wav优先]
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. 先回答你的问题 1：当前训练数据和输入数据应该是什么格式
2.1 当前项目真正需要的输入，不只是音频文件
当前项目训练/评测链路需要 3 类输入：
| 层 | 现在需要什么 | 作用 |
|---|---|---|
| 音频资产层 | .wav/.mp3/.flac/.ogg |
真正被读取和切片的内容 |
| 标注层 |
song_id、type、offset 等 |
告诉系统“这是谁、是什么角色” |
| manifest 层 |
catalog.json / train.json / test.json / val.json
|
驱动训练、建库、评测 |
也就是说，最小可训练单元不是“一个文件”，而是：
- 一个音频文件路径
audio_path - 一个主标签
song_id - 一个角色标签
type - 一个时长
duration - 如为 query，通常还应有
offset
2.2 当前代码侧的默认音频读取约束
从当前仓库实现看，数据读取是按以下原则处理的：
| 项目 | 当前推荐值 | 说明 |
|---|---|---|
| 采样率 | 16000 Hz |
读取时会统一到 16k |
| 声道 | mono |
当前管线按单声道处理 |
| query 长度 |
5s 或 8s
|
训练常用 5s，开放数据 smoke 常用 8s |
| reference 长度 | 尽量完整曲目 | 用于建 reference 索引 |
| 频谱输入 | 128 维 Mel 频谱 |
你要求从 40 维 MFCC 切到音乐任务更合适的 128 Mel |
推荐的标准化目标
容器格式：WAV 优先（也可 MP3/FLAC/Ogg）
采样率：16k
声道：mono
响度：建议归一化到稳定区间
切片长度：5s / 8s
2.3 训练数据中的两种核心角色
A. Reference
Reference 是“曲库真身”，用于建索引、被检索、被匹配。
示例：
{
"song_id": "song_0001",
"audio_path": "audio/song_0001.wav",
"duration": 183.4,
"type": "reference",
"source_dataset": "internal_bgm"
}
要求：
- 一首歌至少 1 条 reference
- 最好是完整曲目或较长主版本
- 不建议把手机录音、环境录音直接当主 reference
B. Query
Query 是“未来线上用户会扔给你的东西”，用于训练和评测识别能力。
示例：
{
"song_id": "song_0001",
"audio_path": "audio/song_0001_query_03.wav",
"duration": 5.0,
"type": "clean",
"offset": 63.2,
"segment_type": "mid",
"source_dataset": "internal_bgm"
}
要求：
- 来自对应
song_id的 reference 曲目 - 时长稳定
- offset 可追溯
- query/reference 使用同一个
song_id
2.4 Query 里具体应该是什么内容
推荐内容类型
| type | 内容 | 用途 |
|---|---|---|
clean |
原曲直接切片 | 基础训练/评测 |
augmented |
加噪、混响、压缩、EQ 后切片 | 提升鲁棒性 |
confused |
容易与别的歌混淆的难例片段 | 拉开区分度 |
humming_like |
旋律近似、配器弱、手机录音风格片段 | 强化近旋律检索 |
reference |
全曲或长片段 | 建库索引 |
不推荐直接混进训练主集的内容
- 完全未知来源、无法映射
song_id的录音 - 严重截断、纯噪声、无有效音乐主体的片段
- 多首歌混在一起、没有主目标标签的片段
这些更适合先放到：
- 待清洗池
- 难例池
- 线上回流池
2.5 manifest 应该长什么样
最低字段要求
| 字段 | 必需 | 说明 |
|---|---|---|
song_id |
是 | 同一首歌的统一主标签 |
audio_path |
是 | 相对路径，建议相对 manifest 根 |
duration |
是 | 秒数 |
type |
是 | reference/clean/augmented/confused/... |
offset |
query 建议有 | query 在 reference 中的起始位置 |
segment_type |
建议 | intro/mid/outro/external_query |
source_dataset |
建议 | 数据来源，例如 fma_small
|
当前项目 manifest 文件
| 文件 | 含义 |
|---|---|
catalog.json |
全部样本总表，尤其包含 reference |
train.json |
训练 query 样本 |
val.json |
验证集 query 样本 |
test.json |
测试集 query 样本 |
3. 如果后面要保存到 pgvector，现在应该怎么处理
3.1 正确分层
不要：
- 原始音频直接进 PostgreSQL 大表
- 训练前再从数据库反向拼装所有资产
推荐：
| 内容 | 存储位置 |
|---|---|
| 原始音频 / 标准音频 | 文件系统 / NAS / 对象存储 |
| manifest / 结构化元数据 | PostgreSQL 普通表 |
| 向量 embedding |
pgvector 列 |
| 检索索引参数 | PostgreSQL 索引 / 服务配置 |
3.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
表职责说明
| 表 | 存什么 |
|---|---|
songs |
歌曲主实体 |
references |
reference 音频资产 |
segments |
query 片段 |
reference_embeddings |
reference 的 embedding |
query_embeddings |
query 的 embedding |
3.3 现在就应该为 pgvector 预留的字段
如果你们后面一定要落 PostgreSQL，建议从今天开始在 manifest / 数据处理中保留这些字段：
| 字段 | 作用 |
|---|---|
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 |
数据快照版本 |
最重要的原则
song_id要稳定，version_id要可扩展，audio_uri要可回溯，model_version/data_version要可审计。
3.4 一个推荐的数据库入库流程
flowchart LR
A[音频目录] --> B[prepare-local]
B --> C[manifests]
C --> D[导出 pgvector JSON]
D --> E[批量导入 PostgreSQL]
E --> F[计算 embedding]
F --> G[写入 pgvector]
推荐执行顺序：
- 音频标准化
- 生成 manifest
- 用 manifest 导出结构化 JSON
- 导入 PostgreSQL 元数据表
- 批量计算 embedding
- 写入
pgvector - 建 ANN 索引
4. 再回答你的问题 2：BGM、音乐录音怎么转成训练数据
4.1 场景 A：你有标准 BGM / 母带 / 完整成品
这是最适合做训练主集的情况。
转化规则
| 输入资产 | 转成什么 |
|---|---|
| 完整曲目 | reference |
| 从完整曲目切的 5s/8s 片段 |
clean query |
| 加噪/压缩/混响后的派生片段 |
augmented query |
| 易混淆段落 |
confused query |
最小流程
flowchart TD
A[完整 BGM] --> B[标准化]
B --> C[reference]
B --> D[切 query 片段]
D --> E[clean]
D --> F[augmented]
D --> G[confused]
C --> H[manifest]
E --> H
F --> H
G --> H
标注原则
- 一首歌一个稳定
song_id - query 与 reference 共用这个
song_id - 不同重编版不要强行共用同一个
song_id - 如果是“同一歌不同版本”，建议：
song_id=主作品IDversion_id=具体版本ID
4.2 场景 B：你有手机录音、环境录音、直播录屏
这类数据通常更适合作为 query / hard case，不适合作为主 reference。
推荐映射
| 原始录音类型 | 建议角色 |
|---|---|
| 手机外放录音 |
augmented 或 external_query
|
| 环境采集 | augmented |
| 直播录屏截取 | external_query |
| 强失真但可识别旋律 | humming_like |
转化步骤
- 先找到它对应哪首 reference
- 确认主要目标曲目是否单一
- 裁成 5s / 8s 片段
- 写入同一个
song_id - 标
type=augmented / humming_like / confused - 标
segment_type=external_query
示例：
{
"song_id": "song_0001",
"audio_path": "queries/phone/song_0001_live_01.wav",
"duration": 8.0,
"type": "augmented",
"segment_type": "external_query",
"source_dataset": "phone_recording"
}
4.3 场景 C：你只有一堆历史文件夹，还没有精标注
这种情况建议先做 弱监督标准化，不要卡死在一开始就完美标注。
先做 3 步
-
按文件夹/文件名生成候选
song_id
-
把完整长音频先当候选 reference
- 自动切若干 query 片段，后续再人工抽检修订
推荐策略
| 阶段 | 做法 |
|---|---|
| 第 1 阶段 | 先把数据“可训练化” |
| 第 2 阶段 | 对高价值样本做人工修标 |
| 第 3 阶段 | 根据误识别样本补 hard cases |
5. 标签应该怎么设计
5.1 最少标签集
对于当前项目，建议先保留以下标签层级：
| 维度 | 字段 | 例子 |
|---|---|---|
| 主标签 | song_id |
song_0001 |
| 版本标签 | version_id |
song_0001_mixA |
| 角色标签 | type |
reference/clean/augmented/confused |
| 结构标签 | segment_type |
intro/mid/outro/external_query |
| 来源标签 | source_dataset |
fma_small / internal_bgm
|
| 合规标签 | license |
cc-by / internal
|
5.2 什么情况下要拆 label
以下情况建议拆成不同 song_id 或 version_id：
| 情况 | 建议 |
|---|---|
| 主旋律相同但编曲大改 | 拆 version_id
|
| 纯伴奏版 vs 演唱版差异极大 | 拆 version_id
|
| mashup / 混剪 | 不进主训练集，单独 hard-case |
| 两首歌拼接 | 单独标记，避免污染主监督 |
6. BGM / 录音转训练集的工业化处理建议
6.1 推荐目录结构
project/
audio/
reference/
queries/
augmented/
manifests/
catalog.json
train.json
val.json
test.json
如果走当前仓库现成流程，也可以直接按：
然后通过：
生成标准化输出。
6.2 推荐的数据处理 checklist
| 阶段 | 必做项 |
|---|---|
| 音频清洗 | 去坏文件、去空文件、统一采样率 |
| 资产标准化 | mono、16k、稳定命名 |
| reference 建立 | 每首歌至少 1 条 reference |
| query 生成 | 每首歌切多个位置片段 |
| 标签治理 | song_id/version_id/type/source_dataset/license |
| 数据拆分 | train/val/test 按歌或按 query 控制泄漏 |
| 评测 | 看 top1/topk、混淆矩阵、难例集 |
| 入库 | manifest -> JSON -> PostgreSQL/pgvector |
7. 如果将来要把音频内容保存到 pgvector 检索系统，应该怎么转
7.1 不要直接存“音频”，要存“音频的表示”
pgvector 适合存：
- embedding 向量
- 指纹向量
- 结构化 metadata
不适合存：
- 大体积原始 WAV 本体
- 大批量训练中间缓存
建议保存的对象
| 对象 | 是否进 pgvector |
|---|---|
| 原始音频文件 | 否 |
| 标准化音频路径 | 是，存 URI/Path |
| reference embedding | 是 |
| query embedding | 可选 |
| song metadata | 是，普通表 |
| 标签/来源/license | 是，普通表 |
7.2 建议的线上检索链路
sequenceDiagram
participant U as User Query Audio
participant S as ACR Service
participant E as Embedder
participant P as pgvector
participant M as Metadata DB
U->>S: 上传5s/8s音频
S->>E: 提取128 Mel + embedding
E->>P: 向量检索TopK
P-->>S: 候选 song_id
S->>M: 读取歌曲元数据
M-->>S: title/artist/version/license
S-->>U: 返回识别结果
8. 你们现在就可以采用的落地规范
8.1 训练样本规范（建议定版）
输入规范
- 单条 query：
5s或8s - 音乐主体明确
- 16k mono
- 每条 query 必须映射到一个
song_id
reference 规范
- 每首歌至少一个完整 reference
- reference 不用强切成很多碎片保存
- 以全曲或长片段为主
标签规范
-
song_id：稳定主键 -
version_id：可扩展 -
type：固定枚举 -
source_dataset：必保留 -
license：商业化必须保留
8.2 面向 pgvector 的规范（建议定版）
- manifest 作为唯一数据交换层
- 音频在文件系统，对象路径写到
audio_uri - embedding 单独表，带
model_version - 每次重训后保留
data_version - 检索结果必须能追溯到原始 reference
9. 推荐执行路径
如果你们后面要把 BGM、录音、开放数据一起纳入训练，我建议按这个顺序推进：
- 先把所有音频资产标准化为
16k mono - 给每首歌建立稳定
song_id - 完整曲目作为 reference
- 自动切 5s/8s query
- 增加
augmented/confused/humming_like难例 - 生成 manifests
- 跑训练 / 评测 / 建索引
- 从 manifest 导出 pgvector JSON
- 再接 PostgreSQL + pgvector
10. 直接给你的结论
问题 1：当前训练数据和输入数据应该是什么样
答案：
- 输入不是单纯音频文件夹，而是“音频 +
song_id标签 + manifest” - reference 是完整曲目或长片段，query 是 5s/8s 片段
- 当前推荐统一成 16k mono，输入层采用 128 维 Mel 频谱
- 如果未来要接 pgvector，现在就要保留
song_id/version_id/audio_uri/source_dataset/license/model_version/data_version这些字段
问题 2：BGM、音乐录音怎么转成训练数据
答案：
- 完整 BGM/母带 -> reference
- 从 reference 切 5s/8s -> clean query
- 加噪/混响/压缩 -> augmented query
- 手机录音/环境录音/直播录屏 -> external query / hard case
- 所有派生片段都必须回挂到统一
song_id
11. 相关仓库内工具
文档
脚本 / SQL
- acr-engine/scripts/export_manifest_to_pgvector_json.py
- acr-engine/scripts/pgvector_bulk_load_template.py
- acr-engine/sql/pgvector_schema.sql
Sources
- This guide is grounded in the current repo’s manifest pipeline and pgvector schema templates: