Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Commit a4c891da a4c891dad1af312917720d031a600ae8b30ac53d by cnb.bofCdSsphPA
Options

Clarify how audio becomes trainable and queryable data 

Constraint: The guidance had to align with the repo's existing manifest and pgvector templates while staying usable for later industrial ingestion.
Rejected: A purely conceptual note | It would not be actionable for future sessions or data engineering work.
Confidence: high
Scope-risk: narrow
Directive: Keep future dataset onboarding and pgvector ingestion changes anchored on manifest-first contracts and stable song identifiers.
Tested: Relative markdown links for the updated docs were validated locally and repository anchor files were confirmed present.
Not-tested: No model retraining or database ingestion was run in this documentation-only stage.
1 parent d1e1a2b7
Inline Side-by-side
Showing 3 changed files with 605 additions and 381 deletions
......@@ -2,6 +2,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 文档浓缩与相对链接跳转
完成项：
......@@ -814,6 +841,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 文档补全 + ACR 最小可运行链路
完成项：
......@@ -836,6 +890,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 准确率优化 v2（128 Mel / band-split / retrieval 评测 / dataset 规范 / SOTA 调研）
完成项：
......@@ -868,6 +949,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 工业化服务骨架 + 外部 manifest 转换模板
完成项：
......@@ -890,6 +998,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 文档治理闭环（导航 / 引用 / 模板）
完成项：
......@@ -910,6 +1045,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 真实评测到发布产物链路打通
完成项：
......@@ -928,6 +1090,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: 外部数据集 bootstrap + hard-case 过采样试验
完成项：
......@@ -951,6 +1140,33 @@
## 2026-06-02
### Stage: 训练数据与 pgvector 专项说明补强
完成项：
- 重写并补强 [docs/training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- 单独详细说明：
- 当前训练输入应由音频资产 + `song_id` 标签 + manifest 组成
- reference 与 query 的角色区分
- BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
- 面向 PostgreSQL + `pgvector` 的字段保留与入库分层
- 将该专项文档挂接到 [docs/README.md](./README.md) 的“数据与评测”主入口
验证结果：
- 已校验文档内新增相对链接全部可达
- 文档已覆盖：
- 输入格式
- 切片时长建议
- label 设计
- `song_id/version_id` 规范
- `pgvector` 数据模型与入库流程
- 当前引用的仓库内实现锚点：
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
结论：
- 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
- 新 session 与后续数据工程实现可直接按该文档落地
### Stage: MTG-Jamendo / ModelScope bootstrap + type-aware hard-case weighting
完成项：
......
......@@ -60,6 +60,7 @@ flowchart TD
### B. 数据与评测
- [数据规范](./dataset-spec.md)
- [开放数据工作流](./open-dataset-workflow.md)
- [训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md)
- [数据来源与接入](./dataset-sources-and-licensing.md)
- [工业评测规范](./industrial-benchmark-spec.md)
......
# Training Data, Input Format, and pgvector Guide / 训练数据、输入格式与 pgvector 指南
> 更新：2026-06-02
> 更新：2026-06-02
> 关联文档：[数据规范](./dataset-spec.md) · [开放数据工作流](./open-dataset-workflow.md) · [数据来源与接入](./dataset-sources-and-licensing.md) · [服务接口](./service-api.md)
## 一页结论
如果后面要把这个 ACR 项目做成稳定可持续的数据工程，建议把数据分成 4 层：
你这次问的两个核心问题，可以先压缩成一句话：
1. **原始音频层**：BGM、歌曲母带、录音、直播切片、手机录音
2. **标准音频资产层**：统一采样率、声道、文件命名后的可训练音频
3. **manifest 层**：`catalog.json` / `train.json` / `test.json` / `val.json`
4. **向量索引层**：embedding、metadata、pgvector/ANN 检索库
当前项目真正训练时吃进去的，不是“任意音频文件夹”，而是：
- 音频文件
- 配套 manifest
- `song_id` 级别标签
- query/reference 角色划分
如果未来要接 `pgvector`，推荐做法不是直接把原始音频塞进数据库，而是：
- 音频留文件系统/对象存储
- metadata 落 PostgreSQL
- embedding 向量落 `pgvector`
- `song_id` / `segment_id` / `type` / `offset` 做结构化列
1. **当前训练输入的最小单位是“带 `song_id` 标签的音频片段 + reference 全曲/长片段 + manifest”**，不是只扔一堆音频文件进去。
2. **如果后面要接入 `pgvector`，应先把音频转成标准资产和 manifest，再从 manifest 生成 embedding 与结构化元数据，不要直接把原始音频塞进数据库。**
---
## 1. 分层结构图
## 1. 总体结构图
```mermaid
flowchart LR
A[原始 BGM / 录音 / 歌曲] --> B[标准化音频资产]
B --> C[Reference Catalog]
B --> D[Query Segments]
C --> E[Manifest JSON]
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[训练 / 评测]
C --> G[Embedding / Fingerprint 索引]
G --> H[pgvector / 检索服务]
E --> F[训练 / 评测 / 建索引]
F --> G[Embedding / Fingerprint]
G --> H[PostgreSQL + pgvector]
```
---
## 2. 当前代码实际接受什么数据
## 2. 先回答你的问题 1：当前训练数据和输入数据应该是什么格式
### 2.1 音频层要求
## 2.1 当前项目真正需要的输入，不只是音频文件
从当前代码看，核心读取逻辑是：
当前项目训练/评测链路需要 3 类输入：
- `librosa.load(..., sr=16000, mono=True)`
- 默认训练片段长度：`5s`
- 外部数据 query 推荐长度：`8s`
- 频谱输入：Mel spectrogram
- 当前文档目标输入层：**128 Mel**
| 层 | 现在需要什么 | 作用 |
|---|---|---|
| 音频资产层 | `.wav/.mp3/.flac/.ogg` | 真正被读取和切片的内容 |
| 标注层 | `song_id`、`type`、`offset` 等 | 告诉系统“这是谁、是什么角色” |
| manifest 层 | `catalog.json` / `train.json` / `test.json` / `val.json` | 驱动训练、建库、评测 |
所以推荐原始资产先标准化为：
也就是说，**最小可训练单元**不是“一个文件”，而是：
| 项目 | 推荐值 | 说明 |
|---|---|---|
| 文件类型 | `.wav` / `.mp3` / `.flac` / `.ogg` | 当前转换工具支持这些后缀 |
| 采样率 | `16k` | 训练/评测读取时会统一到 16k |
| 声道 | mono | 当前 pipeline 按 mono 读取 |
| reference 时长 | 尽量完整曲目 | 用于建索引 |
| query 时长 | `5s` 或 `8s` | 训练常用 5s，开放数据切 query 常用 8s |
- 一个音频文件路径 `audio_path`
- 一个主标签 `song_id`
- 一个角色标签 `type`
- 一个时长 `duration`
- 如为 query，通常还应有 `offset`
---
### 2.2 manifest 层要求
## 2.2 当前代码侧的默认音频读取约束
当前项目的实际关键字段：
从当前仓库实现看，数据读取是按以下原则处理的：
| 字段 | 必需 | 用途 |
| 项目 | 当前推荐值 | 说明 |
|---|---|---|
| `song_id` | 是 | 主标签，同一首歌所有 query/reference 共享 |
| `audio_path` | 是 | 音频相对路径 |
| `duration` | 是 | 时长，控制切片与合法性 |
| `type` | 是 | `reference` / `clean` / `augmented` / `confused` / `humming_like` |
| `offset` | 建议 | query 在原曲中的起始偏移 |
| `segment_type` | 建议 | `intro` / `mid` / `outro` / `external_query` |
| `source_dataset` | 建议 | 数据来源标记 |
| 采样率 | `16000 Hz` | 读取时会统一到 16k |
| 声道 | `mono` | 当前管线按单声道处理 |
| query 长度 | `5s` 或 `8s` | 训练常用 5s，开放数据 smoke 常用 8s |
| reference 长度 | 尽量完整曲目 | 用于建 reference 索引 |
| 频谱输入 | `128 维 Mel 频谱` | 你要求从 40 维 MFCC 切到音乐任务更合适的 128 Mel |
### 推荐的标准化目标
```text
容器格式：WAV 优先（也可 MP3/FLAC/Ogg）
采样率：16k
声道：mono
响度：建议归一化到稳定区间
切片长度：5s / 8s
```
---
## 3. 训练数据到底应该长什么样
## 2.3 训练数据中的两种核心角色
## 3.1 Reference 数据
### A. Reference
Reference 表示“曲库真身”，用于建索引。
Reference 是“曲库真身”，用于建索引、被检索、被匹配。
示例：
......@@ -102,14 +95,12 @@ Reference 表示“曲库真身”，用于建索引。
要求：
- 一首歌至少 1 条 reference
- reference 通常是整首歌或较长主版本
- 不建议把噪音重、混响重、环境录音直接当 reference 主资产
---
- 最好是完整曲目或较长主版本
- 不建议把手机录音、环境录音直接当主 reference
## 3.2 Query 数据
### B. Query
Query 表示“我要识别的输入样本”。
Query 是“未来线上用户会扔给你的东西”，用于训练和评测识别能力。
示例：
......@@ -125,459 +116,475 @@ Query 表示“我要识别的输入样本”。
}
```
Query 的内容应该是：
- 原曲中的 5s/8s 切片
- 或人工合成退化片段
- 或真实世界录音片段
### Query 常见类型
要求：
| type | 含义 | 适合来源 |
|---|---|---|
| `clean` | 原曲直接切片 | 标准训练/评测主力 |
| `augmented` | 加噪、混响、压缩、EQ 后的切片 | 提升鲁棒性 |
| `confused` | 与其他音乐更相似、容易误判的片段 | 难例强化 |
| `humming_like` | 旋律近似、弱配器、手机录音风格 | 旋律/哼唱类近似查询 |
- 来自对应 `song_id` 的 reference 曲目
- 时长稳定
- offset 可追溯
- query/reference 使用同一个 `song_id`
---
## 4. 如果我们有 BGM、音乐录音，怎么转成训练数据
## 2.4 Query 里具体应该是什么内容
## 4.1 场景 A：你有一批“标准 BGM 母带/成品曲目”
### 推荐内容类型
这是最容易的情况。
### 推荐做法
1. 每首完整 BGM 作为 `reference`
2. 从同一首 BGM 中随机切出多个 query 片段
3. 给这些片段打上同一个 `song_id`
4. query 再按用途分到 `train/test/val`
| type | 内容 | 用途 |
|---|---|---|
| `clean` | 原曲直接切片 | 基础训练/评测 |
| `augmented` | 加噪、混响、压缩、EQ 后切片 | 提升鲁棒性 |
| `confused` | 容易与别的歌混淆的难例片段 | 拉开区分度 |
| `humming_like` | 旋律近似、配器弱、手机录音风格片段 | 强化近旋律检索 |
| `reference` | 全曲或长片段 | 建库索引 |
### 结果结构
### 不推荐直接混进训练主集的内容
```mermaid
flowchart TD
A[完整 BGM] --> B[reference]
A --> C1[query 1]
A --> C2[query 2]
A --> C3[query 3]
C1 --> D[train/test]
C2 --> D
C3 --> D
```
- 完全未知来源、无法映射 `song_id` 的录音
- 严重截断、纯噪声、无有效音乐主体的片段
- 多首歌混在一起、没有主目标标签的片段
### 关键点
这些更适合先放到：
- `song_id` 必须稳定
- 曲目版本要分清：主版本、纯伴奏版、短版、重编版不要误当同一首
- 如果版本差异大，建议拆成不同 `song_id`
- 待清洗池
- 难例池
- 线上回流池
---
## 4.2 场景 B：你有“手机录音/环境录音/直播录屏”
## 2.5 manifest 应该长什么样
这类数据不应直接全部当 reference 主资产，而更适合作为 query 或 hard-case 样本。
### 最低字段要求
### 推荐角色
| 字段 | 必需 | 说明 |
|---|---|---|
| `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 文件
| 文件 | 含义 |
|---|---|
| 清晰母带 / 官方音源 | reference |
| 手机录音 / 环境录音 | query |
| 直播采集片段 | query |
| 背景噪声下的短片段 | query |
| `catalog.json` | 全部样本总表，尤其包含 reference |
| `train.json` | 训练 query 样本 |
| `val.json` | 验证集 query 样本 |
| `test.json` | 测试集 query 样本 |
### 标注建议
---
如果录音可以明确对应某首 reference：
## 3. 如果后面要保存到 pgvector，现在应该怎么处理
```json
{
"song_id": "song_0001",
"audio_path": "queries/phone/song_0001_live_01.wav",
"duration": 5.0,
"type": "augmented",
"segment_type": "external_query",
"source_dataset": "phone_recording"
}
```
## 3.1 正确分层
如果录音非常嘈杂、很接近旋律轮廓但音色严重失真：
**不要**：
- 原始音频直接进 PostgreSQL 大表
- 训练前再从数据库反向拼装所有资产
- 可标 `type=humming_like`
- 或单独增加你们自己的扩展类型，如 `field_recording`
**推荐**：
但要注意：
- 训练前最好先映射回当前系统已有类型，避免代码完全不认识
| 内容 | 存储位置 |
|---|---|
| 原始音频 / 标准音频 | 文件系统 / NAS / 对象存储 |
| manifest / 结构化元数据 | PostgreSQL 普通表 |
| 向量 embedding | `pgvector` 列 |
| 检索索引参数 | PostgreSQL 索引 / 服务配置 |
---
## 4.3 场景 C：你只有一堆音频文件夹，还没做精标注
## 3.2 pgvector 推荐数据模型
```mermaid
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/sql/pgvector_schema.sql)
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/scripts/pgvector_bulk_load_template.py](../acr-engine/scripts/pgvector_bulk_load_template.py)
- 一首文件 = 一个 `song_id`
- 整首文件 = `reference`
- 从整首里随机切 query = `clean`
- 后续再人工修正错标/重名/版本冲突
### 表职责说明
这也是当前：
| 表 | 存什么 |
|---|---|
| `songs` | 歌曲主实体 |
| `references` | reference 音频资产 |
| `segments` | query 片段 |
| `reference_embeddings` | reference 的 embedding |
| `query_embeddings` | query 的 embedding |
- `manifest_tools.py audio-dir-to-splits`
- `external_adapters.py prepare-local`
---
在做的事情。
## 3.3 现在就应该为 pgvector 预留的字段
### 适用场景
如果你们后面一定要落 PostgreSQL，建议从今天开始在 manifest / 数据处理中保留这些字段：
- FMA
- MTG-Jamendo
- 你本地一批 BGM 文件夹
- 一批已知 song-level 但未做 segment 级标注的数据
| 字段 | 作用 |
|---|---|
| `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` 要可审计。
---
## 5. label 应该怎么设计
## 3.4 一个推荐的数据库入库流程
## 5.1 主标签：`song_id`
```mermaid
flowchart LR
A[音频目录] --> B[prepare-local]
B --> C[manifests]
C --> D[导出 pgvector JSON]
D --> E[批量导入 PostgreSQL]
E --> F[计算 embedding]
F --> G[写入 pgvector]
```
这是最重要的标签。
推荐执行顺序：
同一首歌的：
1. 音频标准化
2. 生成 manifest
3. 用 manifest 导出结构化 JSON
4. 导入 PostgreSQL 元数据表
5. 批量计算 embedding
6. 写入 `pgvector`
7. 建 ANN 索引
- reference
- clean query
- 手机录音 query
- 混响/噪声 query
---
都应该共享同一个 `song_id`。
## 4. 再回答你的问题 2：BGM、音乐录音怎么转成训练数据
### 推荐命名
## 4.1 场景 A：你有标准 BGM / 母带 / 完整成品
| 场景 | 推荐形式 |
|---|---|
| 内部 BGM | `bgm_000001` |
| 商业曲库 | `catalog_000001` |
| 开源数据 | `fma_012345` |
| 多版本项目 | `song_0001_vocal` / `song_0001_inst` |
这是最适合做训练主集的情况。
---
### 转化规则
## 5.2 辅助标签
| 输入资产 | 转成什么 |
|---|---|
| 完整曲目 | `reference` |
| 从完整曲目切的 5s/8s 片段 | `clean` query |
| 加噪/压缩/混响后的派生片段 | `augmented` query |
| 易混淆段落 | `confused` query |
建议额外保留：
### 最小流程
| 字段 | 作用 |
|---|---|
| `version_id` | 区分原版 / 伴奏版 / 重编版 |
| `segment_type` | 区分 intro / mid / outro |
| `recording_type` | 区分 studio / phone / live / screen_capture |
| `noise_level` | 区分 clean / mild / heavy |
| `source_dataset` | 保留来源审计 |
```mermaid
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
```
当前代码最少已经建议保留：
### 标注原则
- `type`
- `offset`
- `segment_type`
- `source_dataset`
- 一首歌一个稳定 `song_id`
- query 与 reference 共用这个 `song_id`
- 不同重编版不要强行共用同一个 `song_id`
- 如果是“同一歌不同版本”，建议：
- `song_id=主作品ID`
- `version_id=具体版本ID`
---
## 6. 如果以后接 pgvector，当前应该怎么处理
## 4.2 场景 B：你有手机录音、环境录音、直播录屏
## 6.1 不要直接把原始音频塞进 pgvector
这类数据通常更适合作为 **query / hard case**，不适合作为主 reference。
推荐分工：
### 推荐映射
| 层 | 存放位置 |
| 原始录音类型 | 建议角色 |
|---|---|
| 原始音频文件 | 对象存储 / 文件系统 |
| manifest / metadata | PostgreSQL 普通表 |
| embedding 向量 | `pgvector` 列 |
| 音频指纹 | PostgreSQL JSON / 独立索引 / 文件 |
| 手机外放录音 | `augmented` 或 `external_query` |
| 环境采集 | `augmented` |
| 直播录屏截取 | `external_query` |
| 强失真但可识别旋律 | `humming_like` |
---
### 转化步骤
## 6.2 推荐表结构
1. 先找到它对应哪首 reference
2. 确认主要目标曲目是否单一
3. 裁成 5s / 8s 片段
4. 写入同一个 `song_id`
5. 标 `type=augmented / humming_like / confused`
6. 标 `segment_type=external_query`
```mermaid
flowchart TD
A[songs] --> B[segments]
A --> C[references]
C --> D[reference_embeddings]
B --> E[query_embeddings]
示例：
```json
{
"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"
}
```
### songs
---
| 列 | 说明 |
|---|---|
| `song_id` | 主键/唯一业务键 |
| `title` | 曲名 |
| `artist` | 作者/演出者 |
| `version_id` | 版本标识 |
| `source_dataset` | 来源 |
| `license` | 许可证 |
## 4.3 场景 C：你只有一堆历史文件夹，还没有精标注
### references
这种情况建议先做 **弱监督标准化**，不要卡死在一开始就完美标注。
| 列 | 说明 |
|---|---|
| `reference_id` | 主键 |
| `song_id` | 外键 |
| `audio_uri` | 文件路径/对象存储地址 |
| `duration_sec` | 时长 |
| `sample_rate` | 采样率 |
### 先做 3 步
### segments
1. **按文件夹/文件名生成候选 `song_id`**
2. **把完整长音频先当候选 reference**
3. **自动切若干 query 片段，后续再人工抽检修订**
| 列 | 说明 |
|---|---|
| `segment_id` | 主键 |
| `song_id` | 外键 |
| `audio_uri` | query 文件路径 |
| `offset_sec` | 起始偏移 |
| `duration_sec` | 片段长度 |
| `type` | clean/augmented/confused/humming_like |
| `segment_type` | intro/mid/outro/external_query |
| `split` | train/test/val |
### reference_embeddings / query_embeddings
| 列 | 说明 |
### 推荐策略
| 阶段 | 做法 |
|---|---|
| `id` | 主键 |
| `song_id` | 外键 |
| `segment_id` / `reference_id` | 外键 |
| `embedding` | `vector(n)` |
| `model_version` | 模型版本 |
| `created_at` | 生成时间 |
| 第 1 阶段 | 先把数据“可训练化” |
| 第 2 阶段 | 对高价值样本做人工修标 |
| 第 3 阶段 | 根据误识别样本补 hard cases |
---
## 6.3 pgvector 推荐实践
## 5. 标签应该怎么设计
如果当前 embedding 维度是 192，那么可以设计：
## 5.1 最少标签集
```sql
embedding vector(192)
```
### 推荐额外保留字段
- `model_version`
- `data_version`
- `index_version`
- `source_dataset`
- `type`
- `offset_sec`
- `segment_type`
这样以后你能做：
对于当前项目，建议先保留以下标签层级：
- 按模型版本重建 embedding
- 按数据集来源筛选候选
- 按 query 类型分析误判
- 按 `segment_type` 做 intro/outro 针对性策略
| 维度 | 字段 | 例子 |
|---|---|---|
| 主标签 | `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` |
---
## 6.4 当前项目要为 pgvector 提前准备什么
现在就该做的，不是先建数据库，而是先保证这些字段规范：
1. `song_id` 稳定且唯一
2. `audio_path` 可追踪
3. `type` 明确
4. `offset` 可回溯
5. `source_dataset` 清晰
6. 模型产出的 embedding 可以和 metadata 一一对应
## 5.2 什么情况下要拆 label
换句话说：
以下情况建议拆成不同 `song_id` 或 `version_id`：
> 先把 manifest 设计好，未来接 pgvector 才不会返工。
| 情况 | 建议 |
|---|---|
| 主旋律相同但编曲大改 | 拆 `version_id` |
| 纯伴奏版 vs 演唱版差异极大 | 拆 `version_id` |
| mashup / 混剪 | 不进主训练集，单独 hard-case |
| 两首歌拼接 | 单独标记，避免污染主监督 |
---
## 7. 推荐的落地目录与数据加工流程
## 6. BGM / 录音转训练集的工业化处理建议
## 7.1 原始层
## 6.1 推荐目录结构
```text
acr-engine/data/raw/
bgm_master/
phone_recordings/
live_captures/
fma_small_audio/
project/
audio/
reference/
queries/
augmented/
manifests/
catalog.json
train.json
val.json
test.json
```
## 7.2 标准化层
如果走当前仓库现成流程，也可以直接按：
```text
acr-engine/data/curated/
my_bgm_v1/
audio/
manifests/
```
- [acr-engine/data/raw/fma_small_audio/](../acr-engine/data/raw/fma_small_audio/)
- [acr-engine/data/raw/mtg_jamendo_audio/](../acr-engine/data/raw/mtg_jamendo_audio/)
## 7.3 训练/评测层
然后通过：
```text
catalog.json
train.json
test.json
val.json
```
- [开放数据工作流](./open-dataset-workflow.md)
---
生成标准化输出。
## 8. 针对你当前项目的推荐操作方式
---
## 8.1 如果你现在手上有 BGM
## 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 |
1. 每首完整 BGM 先放入一个目录
2. 用统一命名整理
3. 运行：
---
```bash
/usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-local fma <你的目录>
/usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma <你的目录> --output-root data/external_ingested
/usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/fma/manifests
```
## 7. 如果将来要把音频内容保存到 pgvector 检索系统，应该怎么转
如果只是你自有 BGM，不一定非要叫 `fma`，后面可以再做一个内部 adapter。
## 7.1 不要直接存“音频”，要存“音频的表示”
---
`pgvector` 适合存：
## 8.2 如果你现在手上有录音/采集片段
- embedding 向量
- 指纹向量
- 结构化 metadata
建议：
不适合存：
- 不要把这批录音直接当 reference 主库
- 先把它们映射到已有 reference 的 `song_id`
- 作为 query / hard-case 数据进入训练或评测
- 大体积原始 WAV 本体
- 大批量训练中间缓存
如果当前无法人工全标：
### 建议保存的对象
- 先放到单独目录
- 先做 song-level 或 file-level 对齐
- 后续逐步补 segment-level 标注
| 对象 | 是否进 pgvector |
|---|---|
| 原始音频文件 | 否 |
| 标准化音频路径 | 是，存 URI/Path |
| reference embedding | 是 |
| query embedding | 可选 |
| song metadata | 是，普通表 |
| 标签/来源/license | 是，普通表 |
---
## 9. 一张总表
## 7.2 建议的线上检索链路
| 你手上的数据 | 推荐转化方式 | 在系统里的角色 |
|---|---|---|
| 完整 BGM 母带 | 整首保留 + 随机切 query | reference + clean query |
| 官方歌曲文件 | 整首保留 + 切片 | reference + clean query |
| 手机录音 | 对齐到已有 `song_id` | augmented / humming_like query |
| 直播录屏 | 截出音乐段并对齐 `song_id` | external query |
| 背景噪声录音 | 作为 hard case | confused / augmented |
| 开源整包数据集 | 先 `inspect-local`/`prepare-local` | baseline train/eval corpus |
```mermaid
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: 返回识别结果
```
---
## 10. 你现在最值得立刻固化的字段
## 8. 你们现在就可以采用的落地规范
如果后面确定要上 `pgvector`，现在最少要保证每条样本都能追踪：
## 8.1 训练样本规范（建议定版）
- `song_id`
- `audio_path`
- `duration`
- `type`
- `offset`
- `segment_type`
- `source_dataset`
- `split`
- `model_version`（生成 embedding 时记录）
### 输入规范
---
- 单条 query：`5s` 或 `8s`
- 音乐主体明确
- 16k mono
- 每条 query 必须映射到一个 `song_id`
## 11. 推荐文档跳转
### reference 规范
- [dataset-spec.md](./dataset-spec.md)
- [open-dataset-workflow.md](./open-dataset-workflow.md)
- [dataset-sources-and-licensing.md](./dataset-sources-and-licensing.md)
- [session-handoff.md](./session-handoff.md)
- 每首歌至少一个完整 reference
- reference 不用强切成很多碎片保存
- 以全曲或长片段为主
### 标签规范
## 12. 可直接落地的 pgvector 模板
- `song_id`：稳定主键
- `version_id`：可扩展
- `type`：固定枚举
- `source_dataset`：必保留
- `license`：商业化必须保留
仓库里现在已经补了两个可直接参考的模板：
---
- SQL schema: [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
- manifest 导出桥接脚本: [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
## 8.2 面向 pgvector 的规范（建议定版）
### 导出示例
- manifest 作为唯一数据交换层
- 音频在文件系统，对象路径写到 `audio_uri`
- embedding 单独表，带 `model_version`
- 每次重训后保留 `data_version`
- 检索结果必须能追溯到原始 reference
```bash
cd acr-engine
/usr/local/miniconda3/bin/python scripts/export_manifest_to_pgvector_json.py \
--data data/synthetic_v2 \
--split test \
--source-dataset synthetic_v2 \
--output reports/pgvector_manifest_export_test.json
```
---
### 当前已验证结果
## 9. 推荐执行路径
- `songs=24`
- `references=24`
- `segments=20`
如果你们后面要把 BGM、录音、开放数据一起纳入训练，我建议按这个顺序推进：
这一步还不会直接写 PostgreSQL，作用是：
1. 先把所有音频资产标准化为 `16k mono`
2. 给每首歌建立稳定 `song_id`
3. 完整曲目作为 reference
4. 自动切 5s/8s query
5. 增加 `augmented/confused/humming_like` 难例
6. 生成 manifests
7. 跑训练 / 评测 / 建索引
8. 从 manifest 导出 pgvector JSON
9. 再接 PostgreSQL + pgvector
1. 先把项目现有 manifest 规范转换成 pgvector-friendly 结构化 JSON
2. 后续你们可以再用 bulk insert / COPY / ETL 把这些行落到 PostgreSQL
3. embedding 生成后再写入 `vector(192)` 列
---
## 10. 直接给你的结论
### Bulk load plan 模板
### 问题 1：当前训练数据和输入数据应该是什么样
仓库里现在还新增了：
答案：
- [acr-engine/scripts/pgvector_bulk_load_template.py](../acr-engine/scripts/pgvector_bulk_load_template.py)
- **输入不是单纯音频文件夹，而是“音频 + `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` 这些字段**
它会把前一步导出的 manifest-friendly JSON，进一步整理成：
### 问题 2：BGM、音乐录音怎么转成训练数据
- SQL 语句模板
- songs / references / segments 行数据
- 导入顺序说明
答案：
示例：
```bash
cd acr-engine
/usr/local/miniconda3/bin/python scripts/pgvector_bulk_load_template.py \
--input reports/pgvector_manifest_export_test.json \
--output reports/pgvector_bulk_load_plan_test.json
```
- **完整 BGM/母带 -> reference**
- **从 reference 切 5s/8s -> clean query**
- **加噪/混响/压缩 -> augmented query**
- **手机录音/环境录音/直播录屏 -> external query / hard case**
- **所有派生片段都必须回挂到统一 `song_id`**
当前已验证结果：
---
- `songs=24`
- `references=24`
- `segments=20`
## 11. 相关仓库内工具
这样后续如果你们接真实 PostgreSQL，可以分三步走：
### 文档
- [数据规范](./dataset-spec.md)
- [开放数据工作流](./open-dataset-workflow.md)
- [数据来源与接入](./dataset-sources-and-licensing.md)
1. manifest -> pgvector-friendly JSON
2. JSON -> bulk load plan
3. bulk load plan -> PostgreSQL / pgvector 实际写入
### 脚本 / SQL
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/scripts/pgvector_bulk_load_template.py](../acr-engine/scripts/pgvector_bulk_load_template.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
## Sources
- Current code behavior from:
- [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)
- Existing project docs:
- [dataset-spec.md](./dataset-spec.md)
- [open-dataset-workflow.md](./open-dataset-workflow.md)
- This guide is grounded in the current repo’s manifest pipeline and pgvector schema templates:
- [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py)
- [acr-engine/sql/pgvector_schema.sql](../acr-engine/sql/pgvector_schema.sql)
- [数据规范](./dataset-spec.md)
......