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.

@@ -2,6 +2,33 @@
 
 
 ## 2026-06-02
 ## 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: 文档浓缩与相对链接跳转
 ### Stage: 文档浓缩与相对链接跳转
 
 
 完成项：
 完成项：
@@ -814,6 +841,33 @@
 
 
 ## 2026-06-02
 ## 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 最小可运行链路
 ### Stage: 文档补全 + ACR 最小可运行链路
 
 
 完成项：
 完成项：
@@ -836,6 +890,33 @@
 
 
 ## 2026-06-02
 ## 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 调研）
 ### Stage: 准确率优化 v2（128 Mel / band-split / retrieval 评测 / dataset 规范 / SOTA 调研）
 
 
 完成项：
 完成项：
@@ -868,6 +949,33 @@
 
 
 ## 2026-06-02
 ## 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 转换模板
 ### Stage: 工业化服务骨架 + 外部 manifest 转换模板
 
 
 完成项：
 完成项：
@@ -890,6 +998,33 @@
 
 
 ## 2026-06-02
 ## 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: 文档治理闭环（导航 / 引用 / 模板）
 ### Stage: 文档治理闭环（导航 / 引用 / 模板）
 
 
 完成项：
 完成项：
@@ -910,6 +1045,33 @@
 
 
 ## 2026-06-02
 ## 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: 真实评测到发布产物链路打通
 ### Stage: 真实评测到发布产物链路打通
 
 
 完成项：
 完成项：
@@ -928,6 +1090,33 @@
 
 
 ## 2026-06-02
 ## 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 过采样试验
 ### Stage: 外部数据集 bootstrap + hard-case 过采样试验
 
 
 完成项：
 完成项：
@@ -951,6 +1140,33 @@
 
 
 ## 2026-06-02
 ## 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
 ### Stage: MTG-Jamendo / ModelScope bootstrap + type-aware hard-case weighting
 
 
 完成项：
 完成项：

@@ -60,6 +60,7 @@ flowchart TD
 ### B. 数据与评测
 ### B. 数据与评测
 - [数据规范](./dataset-spec.md)
 - [数据规范](./dataset-spec.md)
 - [开放数据工作流](./open-dataset-workflow.md)
 - [开放数据工作流](./open-dataset-workflow.md)
+- [训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md)
 - [数据来源与接入](./dataset-sources-and-licensing.md)
 - [数据来源与接入](./dataset-sources-and-licensing.md)
 - [工业评测规范](./industrial-benchmark-spec.md)
 - [工业评测规范](./industrial-benchmark-spec.md)
 
 

 # Training Data, Input Format, and pgvector Guide / 训练数据、输入格式与 pgvector 指南
 # 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
 ```mermaid
 flowchart LR
 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
     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
 - 一首歌至少 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
 ```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
 ## 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)