Reduce ACR docs to the current song-centric storage design

Constraint: Keep only documentation that directly serves the current Phase-1 song-centric + fused-table storage and retrieval design.
Rejected: Preserve broad historical, dataset, business-export, and template docs in the main docs root | They increase handoff cost and blur the active design surface.
Confidence: high
Scope-risk: moderate
Directive: Treat postgresql-data-model.md as the single source of truth for where slices, models, and features are stored until a concrete fused DDL supersedes it.
Tested: git diff --check on touched docs; /usr/local/miniconda3/bin/python scripts/check_markdown_links.py --root docs returned OK for 11 active markdown files; final docs root reduced to 12 files
Not-tested: external markdown renderers and downstream readers that may still expect removed auxiliary docs

 ## 2026-06-04
 
+- 在 `docs/postgresql-data-model.md` 新增“切片数据 / 模型 / feature 具体落哪张表”的表格与流程图，明确当前默认回溯链为 `feature_fact -> audio_object(window) -> audio_object(asset) -> media_entity(song)`。
+- 收敛 `docs/README.md` 为当前 song-centric 设计入口，并清理 docs 目录中与当前设计无关的模板、开放数据、业务导出、历史路线类文档。
+
 - 收敛文档入口链路，新增 `docs/start-here.md`，统一新同学接手路径为：`README -> start-here -> session-handoff`。
 - 重写 `docs/README.md`，按“接手 / 方案 / 实施 / 运行 / 角色”重组导航，降低首次阅读成本。
 - 重构 `docs/session-handoff.md`，把最新 Phase-1 runner、稳定结论、blocker 与下一步动作收口到单页文档。
@@ -12,6 +15,8 @@
 
 - 根据“尽量融合、用多 type 关联”的新约束，在 `docs/postgresql-data-model.md` 补充“融合优先”建模视图：推荐以 `media_entity`、`audio_object`、`feature_fact`、`set_membership` 这 4 类通用表承载 Phase-1 物理实现，同时保留 `song/recording/asset/window/feature` 的逻辑分层。
 
+- 根据“当前不关心版本，只需多个音频稳定归到同一个 song_id”的新约束，将 `docs/postgresql-data-model.md`、`docs/README.md` 与 `docs/start-here.md` 的默认 Phase-1 口径进一步收敛为 `song -> asset -> window -> feature`；`recording` 调整为未来扩展层，而非当前强主层。
+
 ## 2026-06-04
 
 - 更新 `docs/README.md` 顶部为与 `session-handoff` 一致的“最短启动路径”，并再次用该入口命令重跑 `run_planner_validation_commands_live.py`，确认 fresh 结果仍为 `executed_count=4`、`all_passed=true`。

 # ACR Docs Overview
 
-> 面向“版权保护 / 听歌识曲 / 版本归属”的音乐 ACR 文档总入口。
+> 当前仅保留与 **song-centric + 融合优先** ACR 设计直接相关的文档。
 
 ---
 
 ## 0. 新同学先做什么
 
-### 先跑，不要先读一堆文档
-
 ```bash
 cd /workspace/acr-engine
 /usr/local/miniconda3/bin/python scripts/run_planner_validation_commands_live.py \
@@ -21,105 +19,53 @@ cd /workspace/acr-engine
 - `executed_count = 4`
 - `all_passed = true`
 
-### 再按这条阅读链路走
-1. [start-here.md](./start-here.md)
-2. [session-handoff.md](./session-handoff.md)
-3. [acr-architecture.md](./acr-architecture.md)
-4. [postgresql-data-model.md](./postgresql-data-model.md)
-5. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
-
 ---
 
-## 1. 文档总导航
+## 1. 当前默认设计口径
 
-### A. 接手项目 / 恢复上下文
-- [start-here.md](./start-here.md) — 新同学 10 分钟接手入口
-- [session-handoff.md](./session-handoff.md) — 当前状态、阻塞、下一步
-- [CHANGELOG.md](./CHANGELOG.md) — 变更记录
+当前 Phase-1 默认按下面理解：
 
-### B. 系统方案 / 设计主线
-- [acr-architecture.md](./acr-architecture.md) — 总体架构与分层
-- [sota-evolution-guide.md](./sota-evolution-guide.md) — SOTA 演进路径
-- [postgresql-data-model.md](./postgresql-data-model.md) — PostgreSQL 主数据/特征模型
-- [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md) — encoder-only 冻结策略
+```text
+song -> asset -> window -> fingerprint / embedding
+```
 
-### C. 第一个阶段怎么落地
-- [phase1-implementation-checklist.md](./phase1-implementation-checklist.md) — Phase-1 执行清单
-- [postgresql-data-model.md](./postgresql-data-model.md) — 含 Phase-1 极简 schema 与融合优先视图
-- [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md) — model/feature/reference set 初始化
-- [phase1-worker-contract.md](./phase1-worker-contract.md) — worker、job、失败语义合同
-- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md) — PostgreSQL 存储样例
+对应融合优先物理表：
 
-### D. 运行 / 服务 / 数据治理
-- [runbook.md](./runbook.md) — 运维/运行手册
-- [service-api.md](./service-api.md) — 服务 API
-- [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md) — 训练/向量检索说明
-- [open-dataset-workflow.md](./open-dataset-workflow.md) — 开源数据接入流程
+```text
+media_entity -> audio_object -> feature_fact -> set_membership
+```
 
 ---
 
-## 2. 按角色阅读
+## 2. 必读文档
 
-### 产品 / 业务 / 版权策略
 1. [start-here.md](./start-here.md)
-2. [acr-architecture.md](./acr-architecture.md)
-3. [project-responsibility-map.md](./project-responsibility-map.md)
-4. [business-export-cookbook.md](./business-export-cookbook.md)
-
-### 数据 / 平台 / PostgreSQL
-1. [postgresql-data-model.md](./postgresql-data-model.md)
-2. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
-3. [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md)
-4. [runbook.md](./runbook.md)
-
-### 算法 / 检索 / 模型
-1. [sota-evolution-guide.md](./sota-evolution-guide.md)
-2. [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
-3. [phase1-worker-contract.md](./phase1-worker-contract.md)
-4. [sota-research-2026.md](./sota-research-2026.md)
-
-### 开发 / 实施 / 交付
-1. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
 2. [session-handoff.md](./session-handoff.md)
-3. [CHANGELOG.md](./CHANGELOG.md)
-4. [release-checklist.md](./release-checklist.md)
+3. [acr-architecture.md](./acr-architecture.md)
+4. [postgresql-data-model.md](./postgresql-data-model.md)
+5. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
 
 ---
 
-## 3. 当前最重要的稳定结论
+## 3. 实施相关文档
 
-- 目标场景不是普通歌曲推荐，而是 **版权保护 / 听歌识曲 / 版本归属**。
-- Phase-1 先走 **encoder-only** 路线，不先微调底座。
-- exact lane：`Chromaprint`。
-- semantic baseline：`MERT-v1-95M`。
-- semantic challenger：`MuQ`。
-- `ECAPA` 保留为 historical baseline，不再作为长期主底座。
-- 可演进完整版主链为：
-
-```text
-canonical_song -> work -> recording -> recording_asset -> audio_window
-```
-
-- 如果只看 Phase-1 最小骨架，可以先按下面理解：
-
-```text
-song -> recording -> asset -> window -> fingerprint / embedding
-```
-
-- 模型/特征主链固定为：
-
-```text
-model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint -> retrieval_index_registry
-```
+- [postgresql-data-model.md](./postgresql-data-model.md) — 当前唯一默认数据模型；含切片/模型/feature 落表说明与流程图
+- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md) — PostgreSQL 存储样例
+- [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md) — model/feature/reference set 初始化
+- [phase1-worker-contract.md](./phase1-worker-contract.md) — worker、job、失败语义合同
+- [phase1-implementation-checklist.md](./phase1-implementation-checklist.md) — Phase-1 实施清单
+- [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md) — encoder-only 冻结策略
+- [sota-evolution-guide.md](./sota-evolution-guide.md) — 当前 SOTA 演进主线
 
 ---
 
-## 4. 当前不要浪费时间的方向
+## 4. 当前稳定结论
 
-- 不要回退到只用一个 `song_id` 的扁平结构。
-- 不要把 embedding 存成固定列（如 `mert_embedding` / `muq_embedding`）。
-- 不要在 Phase-1 先讨论重新训练底座。
-- 不要把当前阻塞误判成 PostgreSQL schema 问题；当前主要 blocker 是音频挂载与 runtime 依赖。
+- 最终归属对象当前只要求稳定返回 `song_id`
+- 同一个 `song` 下允许有多个音频文件
+- 当前暂不把 `recording/version` 作为必须返回对象
+- `window` 仍然保留，因为它是 evidence / offset / 检索最小单元
+- `feature_fact` 统一承载 `fingerprint` 和 `embedding`
 
 ---
 
@@ -129,19 +75,4 @@ model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint ->
 /usr/local/miniconda3/bin/python scripts/check_markdown_links.py --root docs
 ```
 
-用途：在清理或重组文档后，快速发现 `docs/` 下的相对链接断链。默认会跳过 `CHANGELOG.md` 这类历史归档文档。
-
----
-
-## 6. 补充但不建议作为第一入口
-
-以下文档保留用于专题补充，不建议新同学第一轮就读：
-- [dataset-spec.md](./dataset-spec.md)
-- [dataset-sources-and-licensing.md](./dataset-sources-and-licensing.md)
-- [references-and-sources.md](./references-and-sources.md)
-- [current-capability-map.md](./current-capability-map.md)
-- [industrialization-roadmap.md](./industrialization-roadmap.md)
-- [industrial-benchmark-spec.md](./industrial-benchmark-spec.md)
-- [benchmark-report-template.md](./benchmark-report-template.md)
-- [model-card-template.md](./model-card-template.md)
-- [report-layout.md](./report-layout.md)
+默认会跳过 `CHANGELOG.md` 这类历史归档文档。

@@ -79,21 +79,22 @@ flowchart TD
 那 Phase-1 完全可以按下面这套最小骨架推进：
 
 ```text
-song -> recording -> asset -> window -> fingerprint / embedding
+song -> asset -> window -> fingerprint / embedding
 ```
 
 保留原因：
-- `recording` 不能删：同一首歌会有多个版本
 - `window` 不能删：它是 offset/evidence/多段投票的最小单元
-- `feature_set_registry` 不能删：否则未来换 MERT/MuQ 会把 schema 写死
+- `feature_set_registry` / `feature_fact` 不能删：否则未来换 MERT/MuQ 会把 schema 写死
+- `asset` 不能删：同一个 `song` 下会有多个真实音频文件
 
 可以延后：
+- `recording`
 - `work`
 - 更重的 `retrieval_index_registry`
 - 更细的全链路审计表
 
 因此推荐口径不是“把所有层都砍掉”，而是：
-> **Phase-1 先上最小可用层；未来版本归属/cover/work 治理再继续加层。**
+> **Phase-1 先上 song-centric 最小可用层；未来版本归属/cover/work 治理再继续加层。**
 
 ---
 
@@ -125,7 +126,6 @@ song -> recording -> asset -> window -> fingerprint / embedding
 最该读：
 - 本文
 - [postgresql-data-model.md](./postgresql-data-model.md)
-- [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
 
 ---
 
@@ -139,8 +139,8 @@ song -> recording -> asset -> window -> fingerprint / embedding
 
 最该读：
 - 本文
-- [service-api.md](./service-api.md)
 - [postgresql-data-model.md](./postgresql-data-model.md)
+- [phase1-worker-contract.md](./phase1-worker-contract.md)
 
 ---
 
@@ -154,8 +154,8 @@ song -> recording -> asset -> window -> fingerprint / embedding
 
 最该读：
 - [sota-evolution-guide.md](./sota-evolution-guide.md)
-- [sota-research-2026.md](./sota-research-2026.md)
 - [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
+- [postgresql-data-model.md](./postgresql-data-model.md)
 
 ---
 
@@ -235,4 +235,4 @@ flowchart LR
 如果你是：
 - **架构负责人**：下一篇看 [sota-evolution-guide.md](./sota-evolution-guide.md)
 - **数据/后端负责人**：下一篇看 [postgresql-data-model.md](./postgresql-data-model.md)
-- **模型负责人**：先看 [sota-evolution-guide.md](./sota-evolution-guide.md) 再回到 [sota-research-2026.md](./sota-research-2026.md)
+- **模型负责人**：先看 [sota-evolution-guide.md](./sota-evolution-guide.md) 再看 [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)

-# Benchmark Report Template
-
-> 用于每次模型版本评测输出
-
-## 一页结论
-- 模型版本：
-- 数据版本：
-- 核心结论：
-- 是否通过上线门禁：
-
-## 1. 评测范围图
-
-```mermaid
-flowchart LR
-    A[Model Version] --> B[Datasets]
-    A --> C[Scenario Buckets]
-    A --> D[Latency / Ops]
-```
-
-## 2. 指标表
-
-| Bucket | top1 | top5 | MRR | FAR | Notes |
-|---|---:|---:|---:|---:|---|
-| clean |  |  |  |  |  |
-| humming_like |  |  |  |  |  |
-| confused |  |  |  |  |  |
-
-## 3. 文字分析
-- 最强项：
-- 最弱项：
-- 与上一版本对比：
-
-## 4. 细节附录
-- 评测命令
-- 数据清单
-- 原始 JSON 报告路径
-
-## Sources
-- `docs/industrial-benchmark-spec.md`

-# Business Export Cookbook / 业务库表导出 Cookbook
-
-> 更新：2026-06-02  
-> 关联文档：[业务 Manifest 与 Type-Role 规范](./business-manifest-and-type-role-spec.md) · [业务素材类型与 Bucket 指南](./business-music-bucket-and-type-guide.md)
-
-## 一页结论
-
-下个 session 如果要从你们的业务库表真正导出训练/评测清单，建议直接按这个顺序：
-
-1. 先从 SQL 导出音频资产基础字段
-2. 用 `type-role mapping` 补 `role` / `bucket`
-3. 落成 CSV 或 JSONL 中间文件
-4. 再转成项目 manifest
-5. 或直接先用仓库脚本转成 manifest-ready JSONL
-
-仓库里已经补好以下参考物：
-- [../acr-engine/configs/manifests/business_asset_manifest_template.json](../acr-engine/configs/manifests/business_asset_manifest_template.json)
-- [../acr-engine/configs/manifests/business_type_role_mapping.json](../acr-engine/configs/manifests/business_type_role_mapping.json)
-- [../acr-engine/configs/manifests/examples/business_asset_export_example.csv](../acr-engine/configs/manifests/examples/business_asset_export_example.csv)
-- [../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl](../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl)
-
----
-
-## 1. 推荐 SQL 导出字段
-
-```sql
-SELECT
-  s.id              AS song_id,
-  a.id              AS asset_id,
-  a.type            AS type,
-  a.file_path       AS audio_path,
-  s.title           AS title,
-  s.artist_name     AS artist,
-  s.album_id        AS album_id,
-  a.duration_sec    AS duration_sec,
-  a.sample_rate     AS sample_rate,
-  a.bitrate         AS bitrate,
-  a.license_code    AS license,
-  a.created_at      AS created_at
-FROM music_asset a
-JOIN song s ON s.id = a.song_id
-WHERE a.type IN (1,7,8,9,10,11,16,18,2,12);
-```
-
-说明：
-- 这不是强制 SQL，只是字段映射样例。
-- 关键不是表名，而是把字段凑齐到 manifest 规范里。
-
----
-
-## 2. 导出后要补什么字段
-
-| 字段 | 来源 | 说明 |
-|---|---|---|
-| `role` | `business_type_role_mapping.json` | 由 `type` 映射 |
-| `bucket` | `business_type_role_mapping.json` | 默认业务 bucket |
-| `split` | 导出脚本或后处理 | `train/val/test/holdout` |
-| `source_dataset` | 固定值 | 如 `internal_catalog` |
-| `offset_sec` | 片段类素材可填 | 非片段可先置 `0` |
-
----
-
-## 3. 推荐中间格式
-
-### CSV
-适合：
-- 业务同学先导数据
-- Excel / 表格工具核对
-
-样例：
-- [../acr-engine/configs/manifests/examples/business_asset_export_example.csv](../acr-engine/configs/manifests/examples/business_asset_export_example.csv)
-
-### JSONL
-适合：
-- 脚本流式处理
-- 后续直接转 manifest
-
-样例：
-- [../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl](../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl)
-
----
-
-## 4. 建议后处理规则
-
-1. `type=10/11` 默认补成 `reference`
-2. `type=1/9` 默认补成压缩域 `reference`
-3. `type=7/8/16` 默认补成 `query`
-4. `type=18/2/12` 默认先 `excluded`
-5. 非音频资产直接过滤掉
-
----
-
-## 5. 下个 session 最直接动作
-
-1. 按 SQL 样例从业务库导一次真实数据
-2. 存成 CSV 或 JSONL
-3. 用仓库里的 mapping 规则补齐 `role` / `bucket`
-4. 再转换成项目需要的 manifest
-
-## Sources
-- See [business-manifest-and-type-role-spec.md](./business-manifest-and-type-role-spec.md)
-- See [business-music-bucket-and-type-guide.md](./business-music-bucket-and-type-guide.md)
-
-
-## 6. 轻量规范化脚本
-
-仓库里已经补了一层可直接运行的转换脚本：
-- [../acr-engine/scripts/normalize_business_export.py](../acr-engine/scripts/normalize_business_export.py)
-
-示例：
-
-```bash
-cd /workspace/acr-engine
-/usr/local/miniconda3/bin/python scripts/normalize_business_export.py \
-  --input configs/manifests/examples/business_asset_export_example.csv \
-  --output /tmp/business_asset_manifest_ready.jsonl
-```
-
-这个脚本会：
-1. 读取 CSV 或 JSONL 导出
-2. 应用 `business_type_role_mapping.json`
-3. 自动补 `role / bucket / source_dataset / split` 默认值
-4. 输出 manifest-ready JSONL
-
-
-## 7. 拆分为角色清单
-
-如果你已经拿到了 manifest-ready JSONL，还可以继续用：
-- [../acr-engine/scripts/split_business_manifest_ready.py](../acr-engine/scripts/split_business_manifest_ready.py)
-
-示例：
-
-```bash
-cd /workspace/acr-engine
-/usr/local/miniconda3/bin/python scripts/split_business_manifest_ready.py \
-  --input /tmp/business_asset_manifest_ready.jsonl \
-  --output-dir /tmp/business_asset_manifest_split
-```
-
-它会输出：
-- `reference.json`
-- `query.json`
-- `excluded.json`
-
-这样下个 session 可以更快把业务素材继续整形成训练/评测所需清单。
-
-
-## 8. 生成项目 manifest
-
-如果你已经有 manifest-ready JSONL，可以直接继续生成项目当前需要的四个 manifest：
-- [../acr-engine/scripts/build_business_project_manifests.py](../acr-engine/scripts/build_business_project_manifests.py)
-- [business-project-manifest-adapter.md](./business-project-manifest-adapter.md)

-# Business Manifest and Type-Role Spec / 业务 Manifest 与 Type-Role 规范
-
-> 更新：2026-06-02  
-> 关联文档：[业务素材类型与 Bucket 指南](./business-music-bucket-and-type-guide.md) · [训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md)
-
-## 一页结论
-
-现在仓库里已经有两份可以直接复用的业务接入模板：
-- [../acr-engine/configs/manifests/business_asset_manifest_template.json](../acr-engine/configs/manifests/business_asset_manifest_template.json)
-- [../acr-engine/configs/manifests/business_type_role_mapping.json](../acr-engine/configs/manifests/business_type_role_mapping.json)
-
-它们解决两个问题：
-1. 业务库表里的字段，最少要映射成什么 manifest 字段。
-2. 你们的 `type` 应该默认落到 `reference / query / excluded` 哪一类。
-
----
-
-## 1. 映射图
-
-```mermaid
-flowchart LR
-    A[业务库表记录] --> B[type-role mapping]
-    B --> C[reference]
-    B --> D[query]
-    B --> E[excluded]
-    C --> F[manifest rows]
-    D --> F
-    F --> G[train / build-index / evaluate]
-```
-
----
-
-## 2. 最小 manifest 字段
-
-| 字段 | 必需 | 说明 |
-|---|---|---|
-| `song_id` | 是 | 歌曲主 ID |
-| `asset_id` | 是 | 具体素材 ID |
-| `type` | 是 | 你们现有的素材类型 |
-| `role` | 是 | `reference` / `query` / `excluded` |
-| `split` | 是 | `train` / `val` / `test` / `holdout` |
-| `audio_path` | 是 | 可访问的音频路径 |
-| `source_dataset` | 是 | 来源标识 |
-| `bucket` | 否 | 分桶评测标签 |
-| `offset_sec` | 否 | query 起点 |
-| `duration_sec` | 否 | 片段长度 |
-
----
-
-## 3. 默认 type-role 规则
-
-| type | 默认 role | 默认 bucket | 说明 |
-|---:|---|---|---|
-| `10` / `11` | `reference` | `lossless_reference_core` | 无损主库 |
-| `9` / `1` | `reference` | `compressed_reference_realworld` | 压缩真实分布 |
-| `8` / `7` / `16` | `query` | `short_video_hook` | 短视频/副歌入口 |
-| `18` | `excluded` | `demo_variation_pool` | 先人工筛 |
-| `2` / `12` | `excluded` | `with_harmony_shift` | 先做专项桶 |
-| 其余非音频 type | `excluded` | `non_audio` | 不入模 |
-
----
-
-## 4. 导出原则
-
-1. **reference 与 query 即使同曲，也不要混成同一条资产记录。**
-2. **如果无法确认是否同曲同版本，默认 `excluded`。**
-3. **`type=18 demo` 不要自动并入 train，先人工审。**
-4. **短视频片段优先导出为 `query`，不要直接当 reference。**
-
----
-
-## 5. 模板与脚本
-
-- Manifest 模板：
-  - [../acr-engine/configs/manifests/business_asset_manifest_template.json](../acr-engine/configs/manifests/business_asset_manifest_template.json)
-- Type-role 模板：
-  - [../acr-engine/configs/manifests/business_type_role_mapping.json](../acr-engine/configs/manifests/business_type_role_mapping.json)
-- 打印脚本：
-  - [../acr-engine/scripts/print_business_type_mapping.py](../acr-engine/scripts/print_business_type_mapping.py)
-- 规范化脚本：
-  - [../acr-engine/scripts/normalize_business_export.py](../acr-engine/scripts/normalize_business_export.py)
-- 角色拆分脚本：
-  - [../acr-engine/scripts/split_business_manifest_ready.py](../acr-engine/scripts/split_business_manifest_ready.py)
-
-示例命令：
-
-```bash
-cd /workspace/acr-engine
-/usr/local/miniconda3/bin/python scripts/print_business_type_mapping.py
-```
-
----
-
-## 6. 下个 session 直接动作
-
-1. 按这份规范把库表字段映射到 manifest 行。
-2. 用 `business_type_role_mapping.json` 给每条资产打默认 `role` / `bucket`。
-3. 先导出 `reference` 与 `query` 清单，再进入训练与 bucket benchmark。
-
-## 延伸阅读
-- [business-export-cookbook.md](./business-export-cookbook.md)
-
-## Sources
-- See [business-music-bucket-and-type-guide.md](./business-music-bucket-and-type-guide.md)
-- See [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)

-# Business Music Bucket and Type Guide / 业务音乐素材类型与 Bucket 指南
-
-> 更新：2026-06-02  
-> 关联文档：[训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md) · [开放数据工作流](./open-dataset-workflow.md) · [工业级 Benchmark 规范](./industrial-benchmark-spec.md)
-
-## 一页结论
-
-针对你们现有的素材 `type` 字段，**不要把所有文件都混进训练**。  
-更推荐按“reference 主资产 + query 派生资产 + hard-case 评测资产”三层来用。
-
-### 最推荐参与训练/建库的类型
-
-| 优先级 | type | 含义 | 训练用途 |
-|---|---:|---|---|
-| 高 | `10` | 伴奏无和声-无损 | 最干净的 reference 候选 |
-| 高 | `11` | 原曲-无损 | 主 reference / 主训练资产 |
-| 高 | `9` | 伴奏无和声-压缩 | reference 补充 / 压缩域适配 |
-| 高 | `1` | 原曲-压缩 | 训练域补充 / 真实线上分布 |
-| 中 | `18` | 音频 demo | 可作为弱监督补充，需人工筛 |
-| 中 | `8` | 片段(副歌) | 可用于 repeated-section / 高辨识度 query |
-| 中 | `7` | 抖音片段 | 可用于短视频域 query 评测 |
-| 中 | `16` | 快手片段 | 可用于短视频域 query 评测 |
-
-### 通常不直接参与主训练的类型
-
-| type | 含义 | 原因 |
-|---:|---|---|
-| `2` / `12` | 伴奏有和声 | 容易引入“同曲不同演唱层”的额外变异，适合后续单独实验 |
-| `3` / `13` / `20` | 歌词 / LRC / 译文滚动歌词 | 非音频资产 |
-| `4` / `14` / `19` | 封面 / PSD / 曲谱图片 | 非音频资产 |
-| `5` | 授权书 | 合规文件，不入模 |
-| `6` | 专辑信息 | 元数据，不入模 |
-| `17` | 词曲压缩包 | 需先拆解，不应直接入模 |
-
----
-
-## 1. 业务素材职责图
-
-```mermaid
-flowchart LR
-    A[无损主资产\n10 / 11] --> B[reference 主库]
-    C[压缩主资产\n1 / 9] --> D[训练域增强]
-    E[短视频片段\n7 / 16 / 8] --> F[query 评测集]
-    G[录音/demo\n18] --> H[弱监督补充池]
-    B --> I[训练 / 建索引]
-    D --> I
-    F --> J[短片段评测 / hard-case]
-    H --> K[人工筛选后再进入 I 或 J]
-```
-
----
-
-## 2. 你们的 type 应该怎么用
-
-## 2.1 主训练 / 主建库推荐
-
-### A. 第一优先：`10` + `11`
-
-原因：
-- 音质最好
-- 标签语义最稳定
-- 最适合作为“真值 reference”
-
-推荐用途：
-- `reference`
-- 主训练资产
-- pgvector 主 embedding 表
-
-### B. 第二优先：`9` + `1`
-
-原因：
-- 更接近线上真实压缩分布
-- 可以增强模型对编码损伤的适应性
-
-推荐用途：
-- 训练补充
-- 评测时做 clean/compressed query
-- reference 域扩展
-
-### C. 第三优先：`8` / `7` / `16`
-
-原因：
-- 更接近真实识别入口
-- 有利于短片段 / 副歌 / 短视频域评测
-
-推荐用途：
-- query 评测集
-- repeated-section-rich bucket
-- short-video bucket
-
-### D. 谨慎使用：`18`
-
-原因：
-- `demo` 的混音、编排、完整度差异很大
-- 很容易把“不是同一首最终版本”的样本混入同标签
-
-推荐用途：
-- 先放人工筛选池
-- 只在确认与正式版本同曲同主旋律时再纳入训练或 hard-case
-
----
-
-## 2.2 不建议一开始就并入主训练的类型
-
-### `2` / `12` 伴奏有和声
-
-风险：
-- 同一 `song_id` 下会多出人声/和声干扰
-- 如果当前系统目标是“音乐 ACR / BGM 识别”，这类素材更适合作为后续 domain robustness 对照
-
-建议：
-- 先单独放一个 `with_harmony_accompaniment` bucket
-- 不要一开始和 `10`/`9` 直接混训
-
----
-
-## 3. 建议的训练/评测分层
-
-```mermaid
-flowchart TD
-    A[主库 reference] --> A1[10 / 11]
-    B[训练补充] --> B1[1 / 9]
-    C[短片段评测] --> C1[7 / 16 / 8]
-    D[特殊对照] --> D1[2 / 12 / 18]
-    E[非音频元数据] --> E1[3 / 4 / 5 / 6 / 13 / 14 / 17 / 19 / 20]
-```
-
-### 推荐首版策略
-
-| 层 | 推荐 type |
-|---|---|
-| reference 主库 | `10`, `11` |
-| 训练补充 | `1`, `9` |
-| query 评测 | `7`, `8`, `16` |
-| 人工筛选后可补充 | `18` |
-| 后续鲁棒性专项实验 | `2`, `12` |
-
----
-
-## 4. 业务语义 bucket 建议
-
-## 4.1 第一批最值得做的 bucket
-
-| bucket 名称 | 推荐来源 type | 作用 |
-|---|---|---|
-| `lossless_reference_core` | `10`, `11` | 最干净真值库 |
-| `compressed_reference_realworld` | `1`, `9` | 线上压缩域 |
-| `short_video_hook` | `7`, `16`, `8` | 短视频 / 副歌识别 |
-| `with_harmony_shift` | `2`, `12` | 有和声伴奏干扰 |
-| `demo_variation_pool` | `18` | demo 与正式版差异风险 |
-| `hard_negative_confusable` | 人工精选 | 风格近似、编曲近似、旋律近似 |
-
----
-
-## 4.2 为什么这比通用 semantic bucket 更贴近业务
-
-因为你们的数据不是纯学术数据集，而是**带素材业务语义**的：
-- 有主资产 / 压缩版 / 无损版
-- 有短视频片段
-- 有副歌片段
-- 有带和声/不带和声伴奏
-
-因此你们最先应该做的不是抽象的 genre bucket，而是：
-1. **版本形态 bucket**
-2. **入口场景 bucket**
-3. **混淆风险 bucket**
-
----
-
-## 5. 推荐配置模板
-
-配套模板：
-- [../acr-engine/configs/buckets/fma_semantic_bucket_template.json](../acr-engine/configs/buckets/fma_semantic_bucket_template.json)
-- [../acr-engine/configs/buckets/business_type_bucket_template.json](../acr-engine/configs/buckets/business_type_bucket_template.json)
-
-其中：
-- `fma_semantic_bucket_template.json` 更偏通用方法学
-- `business_type_bucket_template.json` 更偏你们现有业务素材形态
-
----
-
-## 6. 和 pgvector 怎么配合
-
-如果后续落到 pgvector，建议至少保留这些字段：
-
-| 字段 | 说明 |
-|---|---|
-| `song_id` | 主歌曲 ID |
-| `asset_id` | 具体资产 ID |
-| `type` | 你们的素材类型 |
-| `bucket` | 当前评测/训练桶 |
-| `role` | `reference` / `query` |
-| `source_dataset` | 来源 |
-| `offset_sec` | query 起点 |
-| `duration_sec` | query 长度 |
-| `embedding` | pgvector 向量 |
-
-这样后面就能按：
-- `type` 过滤
-- `bucket` 出报表
-- `role` 区分 reference/query
-- `source_dataset` 做多源分析
-
----
-
-## 7. 下个 session 的直接动作
-
-1. 先按这个文档筛出首批可用 type：`10`, `11`, `9`, `1`, `8`, `7`, `16`
-2. 再把这些映射进：
-   - [../acr-engine/configs/buckets/business_type_bucket_template.json](../acr-engine/configs/buckets/business_type_bucket_template.json)
-3. 跑 bucket benchmark
-4. 对照 `hybrid` / `high_energy` 在不同业务 bucket 下是否分化
-
-## Sources
-- See [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
-- See [industrial-benchmark-spec.md](./industrial-benchmark-spec.md)

-# Business Project Manifest Adapter / 业务数据到项目 Manifest 适配说明
-
-> 更新：2026-06-02  
-> 关联文档：[业务导出 Cookbook](./business-export-cookbook.md) · [业务 Manifest 与 Type-Role 规范](./business-manifest-and-type-role-spec.md)
-
-## 一页结论
-
-现在仓库里已经有一条接近项目训练/评测 manifest 的离线脚本链：
-
-1. 业务库表导出 CSV / JSONL
-2. [../acr-engine/scripts/normalize_business_export.py](../acr-engine/scripts/normalize_business_export.py)
-3. [../acr-engine/scripts/split_business_manifest_ready.py](../acr-engine/scripts/split_business_manifest_ready.py)
-4. [../acr-engine/scripts/build_business_project_manifests.py](../acr-engine/scripts/build_business_project_manifests.py)
-
-最后一步会直接生成：
-- `catalog.json`
-- `train.json`
-- `test.json`
-- `val.json`
-
-格式对齐当前项目已有 manifest 结构。
-
----
-
-## 1. 对齐后的项目格式
-
-### `catalog.json`
-- 只放 reference
-- 字段：`song_id / audio_path / duration / type=reference / source_dataset`
-
-### `train.json` / `test.json`
-- 前半部分是 query
-- 后半部分拼接 reference
-- query 字段：
-  - `song_id`
-  - `audio_path`
-  - `duration`
-  - `type=clean`
-  - `offset`
-  - `segment_type=external_query`
-  - `source_dataset`
-
-### `val.json`
-- 当前默认只放 `split=val` 的 query
-- 可选把 `holdout` 合并进 `val`
-
----
-
-## 2. 示例命令
-
-```bash
-cd /workspace/acr-engine
-/usr/local/miniconda3/bin/python scripts/normalize_business_export.py \
-  --input configs/manifests/examples/business_asset_export_example.csv \
-  --output /tmp/business_asset_manifest_ready.jsonl
-
-/usr/local/miniconda3/bin/python scripts/build_business_project_manifests.py \
-  --input /tmp/business_asset_manifest_ready.jsonl \
-  --output-dir /tmp/business_project_manifests
-```
-
-如果你希望把 `holdout` 先并进 `val.json`：
-
-```bash
-/usr/local/miniconda3/bin/python scripts/build_business_project_manifests.py \
-  --input /tmp/business_asset_manifest_ready.jsonl \
-  --output-dir /tmp/business_project_manifests \
-  --include-holdout-in-val
-```
-
----
-
-## 3. 适配边界
-
-这一步还不是最终“真实业务生产接入”，但已经足够让下个 session：
-- 用真实业务导出样本跑通 manifest 结构
-- 对接 `train.py / evaluate.py / run_demo.py`
-- 再只针对最终字段细节做小修
-
-## Sources
-- See [business-export-cookbook.md](./business-export-cookbook.md)
-- See [business-manifest-and-type-role-spec.md](./business-manifest-and-type-role-spec.md)

-# Current Capability Map / 当前能力地图
-
-> 更新：2026-06-02
-
-## 一页结论
-
-当前项目有三类能力：
-
-1. **已完整闭环**
-2. **已打通但仍是 smoke 级**
-3. **仍待真实数据/更大规模验证**
-
----
-
-## 1. 能力状态表
-
-| 能力 | 当前状态 | 说明 |
-|---|---|---|
-| synthetic 数据生成 | 已完成 | 可稳定生成合成训练/评测数据 |
-| synthetic 训练 | 已完成 | `train.py` 可跑通 |
-| synthetic 建索引 | 已完成 | `run_demo.py build-index` 可跑通 |
-| synthetic 评测 | 已完成 | `evaluate.py` 可输出 JSON |
-| synthetic 发布制品 | 已完成 | 可生成 benchmark/model-card/checklist |
-| 开放数据 inspect | 已完成 | `inspect-local` / `inspect-batch` |
-| 开放数据 prepare | 已完成 | `prepare-local` |
-| 开放数据 validate | 已完成 | `validate-local` |
-| 开放数据训练 smoke | 已完成 | 已在 stand-in 数据上验证 |
-| 开放数据索引 smoke | 已完成 | 已在 stand-in 数据上验证 |
-| 开放数据评测 smoke | 已完成 | 已在 stand-in 数据上验证 |
-| 开放数据发布制品 smoke | 已完成 | 已在 stand-in 数据上验证 |
-| 一键 smoke-local | 已完成 | inspect→prepare→validate→train→index→eval→artifacts |
-| 真实 FMA 本地目录 smoke | 待外部数据 | 代码已就绪，缺真实音频目录 |
-| 真实 MTG-Jamendo 本地目录 smoke | 待外部数据 | 代码已就绪，缺真实音频目录 |
-| hard-case 精度优化 | 进行中 | confused / humming_like 仍需持续优化 |
-| foundation model baseline | 未完成 | 仅完成文档研究与路线规划 |
-| 工业级生产部署 | 未完成 | 服务骨架已在，生产治理未完成 |
-
----
-
-## 2. 最短路径图
-
-```mermaid
-flowchart LR
-    A[Local Audio Dir] --> B[inspect-local]
-    B --> C[prepare-local]
-    C --> D[validate-local]
-    D --> E[train]
-    E --> F[build-index]
-    F --> G[evaluate]
-    G --> H[generate_artifacts]
-```
-
----
-
-## 3. 当前最可靠入口
-
-- [docs/open-dataset-workflow.md](./open-dataset-workflow.md)
-- [docs/session-handoff.md](./session-handoff.md)
-- [acr-engine/FIRST_RUN_CHECKLIST.md](../acr-engine/FIRST_RUN_CHECKLIST.md)
-- [acr-engine/scripts/status_snapshot.py](../acr-engine/scripts/status_snapshot.py)
-
----
-
-## 4. 当前最重要缺口
-
-1. 真实 FMA 本地音频未落地
-2. 真实 MTG-Jamendo 本地音频未落地
-3. hard-case 在真实数据上的表现未知
-4. foundation model baseline 还未开始实现
-5. 服务与部署仍偏原型级
-
----
-
-## Sources
-- [session-handoff.md](./session-handoff.md)
-- [open-dataset-workflow.md](./open-dataset-workflow.md)
-- [CHANGELOG.md](./CHANGELOG.md)

-# Dataset Sources and Licensing
-
-> 更新：2026-06-02
-
-## 一页结论
-
-- 当前优先目标改为：**个人使用下充分利用开源数据集**
-- 外部数据集接入现在不仅要能 bootstrap，还要能真实切成 train/eval manifests
-- 当前建议优先级：
-  1. FMA
-  2. MTG-Jamendo
-  3. CCMusic（审批/核验后）
-  4. ModelScope music datasets（白名单后）
-- ModelScope 与 CCMusic 当前都不能默认直接进入商用训练
-
-对个人使用的直接建议：
-- FMA / MTG-Jamendo：优先转成训练与评估资产
-- CCMusic / ModelScope：优先当补充评估或探索来源
-- 保留 license 注记，但不再把“商用阻塞”作为个人实验主阻塞
-
-推荐先读：
-- [开放数据工作流](./open-dataset-workflow.md)
-
-建议接入顺序：
-1. 下载/准备 FMA 或 MTG-Jamendo 的本地音频目录
-2. 运行 [acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-local` 或 `inspect-batch`
-3. 再运行 [acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `prepare-local`
-4. 生成 [catalog.json / train.json / test.json / val.json](../acr-engine/data/external_ingested/README.md)
-5. 将 [train.json](../acr-engine/data/external_ingested/README.md) 用于训练，将 [test.json](../acr-engine/data/external_ingested/README.md) 用于固定评估
-
----
-
-## 1. 来源分层图
-
-```mermaid
-flowchart TD
-    A[Candidate Datasets] --> B[Open / MIR Baselines]
-    A --> C[Chinese / Regional Sources]
-    A --> D[Discovery Surfaces]
-
-    B --> B1[FMA]
-    B --> B2[MTG-Jamendo]
-    C --> C1[CCMusic]
-    D --> D1[ModelScope music datasets]
-```
-
----
-
-## 2. 数据源表
-
-| 数据源 | 角色 | 风险 | 当前策略 |
-|---|---|---|---|
-| FMA | 首批真实 baseline | track license 需核验 | review_required |
-| MTG-Jamendo | retrieval/tagging corpus | CC 细则需核验 | review_required |
-| CCMusic | 中文 MIR 资源 | 可能需申请/存在限制 | review_required |
-| ModelScope music | 数据发现入口 | license 分散 | deny_until_whitelisted |
-
----
-
-## 3. 白名单流程图
-
-```mermaid
-flowchart LR
-    A[发现数据集] --> B[收集 license / terms]
-    B --> C[法律/合规审查]
-    C --> D{可商用?}
-    D -- 是 --> E[加入 whitelist]
-    D -- 否 --> F[禁止进入训练]
-```
-
----
-
-## 4. 文字说明
-
-### 4.1 为什么 ModelScope 只能先当 discovery surface
-因为不同数据集来源和条款差异很大，不能因为“在 ModelScope 上”就默认可商用。
-
-### 4.2 为什么 CCMusic 要单独看
-它对中文音乐任务很有价值，但部分子集可能涉及申请、协议或非标准商业许可边界。
-
-### 4.3 为什么 license registry 要和模型版本绑定
-这样才能在未来追踪：
-- 某个模型到底用了哪些数据
-- 这些数据是否允许对应商用场景
-
----
-
-## 5. 细节附录
-
-入口链接：
-- FMA: https://github.com/mdeff/fma
-- MTG-Jamendo: https://github.com/MTG/mtg-jamendo-dataset
-- CCMusic: https://ccmusic-database.github.io/en/database/ccm.html
-- ModelScope search: https://modelscope.cn/search?page=1&search=music&type=dataset
-
-
-## Sources
-- See [references-and-sources.md](./references-and-sources.md) for the current source map.
-
-
-## Download / LFS governance
-
-### Preferred repository behavior
-
-```mermaid
-flowchart TD
-    A[Upstream dataset source] --> B[Local raw drop zone]
-    B --> C[Git LFS tracked large files]
-    C --> D[check-local-ready]
-    D --> E[prepare-local / smoke-local]
-```
-
-### Current repo policy
-
-| Item | Policy | Reason |
-|---|---|---|
-| `acr-engine/data/raw/**/*.zip` | Git LFS | avoid bloating normal git history |
-| `acr-engine/data/raw/**/*.wav` / `.mp3` / `.flac` / `.ogg` | Git LFS | allow local reproducibility without normal blob explosion |
-| FMA Small | acceptable as first real-data engineering baseline | easiest realistic open music smoke path |
-| MTG-Jamendo | default to research/eval lane | do not assume commercial-safe rights without subset-specific proof |
-
-### Operational note
-
-Even when a dataset is technically downloadable, this project should separate:
-
-- **engineering usability**
-- **benchmark suitability**
-- **commercial deployment suitability**
-
-These are not the same thing.

-# ACR Dataset / 输入输出规范
-
-> 更新：2026-06-02  
-> 关联文档：[训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md) · [开放数据工作流](./open-dataset-workflow.md) · [数据来源与接入](./dataset-sources-and-licensing.md)
-
-## 一页结论
-
-当前项目的数据规范，最重要的是 4 件事：
-
-1. **训练输入不是“整首 mp3 文件”本身，而是 manifest 驱动的 reference + query 样本体系**。
-2. **训练和检索的切窗策略不同**：训练端当前是**随机裁剪 5s**，检索/建索引端当前是**5s 窗口 + 2.5s stride 的 50% 重叠滑窗**。
-3. **外部开源数据集进入项目时，必须先转换成统一 manifest**，再做训练、评测、索引和 pgvector 入库。
-4. **当前音乐任务输入层已切换到 128 维 Mel 频谱**，并开启 band-split 方向；FMA 这类真实数据建议优先使用 GPU。
-
----
-
-## 1. 数据流图
-
-```mermaid
-flowchart LR
-    A[Raw Audio\nFMA / MTG / 自有 BGM / 录音] --> B[Manifest Conversion]
-    B --> C[Catalog Manifest\nreference]
-    B --> D[Train/Test Manifest\nquery]
-    C --> E[Reference Index Build\nsliding windows]
-    D --> F[Training / Evaluation]
-    E --> G[Hybrid Retrieval]
-    F --> G
-    G --> H[pgvector / report / service]
-```
-
----
-
-## 2. 数据对象表
-
-| 对象 | 作用 | 必要字段 | 说明 |
-|---|---|---|---|
-| Reference | 可检索曲库 | `song_id`, `audio_path`, `duration`, `type=reference` | 用于建索引 |
-| Query Segment | 待识别片段 | `song_id`, `audio_path`, `duration`, `type` | 用于训练/评测 |
-| Catalog Manifest | reference 总表 | JSON list | 用于离线索引 |
-| Query Manifest | query 总表 | JSON list | 用于训练与评测 |
-
----
-
-## 3. Manifest 结构图
-
-```mermaid
-flowchart TD
-    M[Manifest] --> R[Reference Records]
-    M --> Q[Query Records]
-    R --> R1[song_id]
-    R --> R2[audio_path]
-    R --> R3[duration]
-    R --> R4[type=reference]
-    Q --> Q1[song_id]
-    Q --> Q2[audio_path]
-    Q --> Q3[duration]
-    Q --> Q4[type=clean/augmented/confused/humming_like]
-    Q --> Q5[offset]
-```
-
----
-
-## 4. 输入输出总表
-
-| 环节 | 输入 | 输出 |
-|---|---|---|
-| 训练 | query segments + references | embeddings + logits |
-| 索引 | catalog references | chromaprint index + embedding index |
-| 识别 | query audio | ranked candidates |
-| 评测 | query manifest + catalog | top1/top5/hard-case report |
-| 入库 | manifest + embedding | pgvector-ready JSON / SQL rows |
-
----
-
-## 5. 3 分钟 mp3 到 5–8 秒片段：当前到底怎么切
-
-## 5.1 当前代码里有 **3 种不同切法**
-
-```mermaid
-flowchart TD
-    A[3min mp3] --> B[训练 Dataset]
-    A --> C[检索 / 建索引]
-    A --> D[外部数据集 manifest 生成]
-
-    B --> B1[随机裁 1 个 5s clip]
-    C --> C1[5s 窗 + 2.5s stride]\n50% overlap
-    D --> D1[每首歌随机采 1 个 query]\n默认 8s
-```
-
-| 场景 | 当前实现 | 是否重叠 | 代码位置 |
-|---|---|---:|---|
-| 训练 `SongPairDataset` | 每次采样按 `segment_strategy` 选 1 个 5s clip；默认可随机，也可走音乐感知候选 | 否，**不是固定滑窗全集展开** | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
-| 检索 / embedding / 建索引 | `window_sec=5.0`, `stride_sec=2.5` | 是，**50% overlap** | [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py), [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py) |
-| `audio-dir-to-splits` 默认 | 每首歌生成 query；可随机，也可按音乐感知策略产出 | 否 | [acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py) |
-| `audio-dir-to-splits --query-stride 4.0` 例 | 对单首歌生成多个滑窗 query | 是，可配置 | [acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py) |
-
-### 直接回答你的问题
-
-- **有重叠窗口，主要在检索/索引链路；训练端不是全量滑窗展开。**
-- **当前训练主链路不是“只会随机切”**，而是每次 batch 动态选 1 个 5s 片段；候选可以来自 `random / silence_aware / high_energy / onset_aware / beat_aware / repeated_section_aware / hybrid`。
-- **当前外部数据集 manifest 生成器也不再只有随机 query**，可通过 `--query-strategy` 走音乐感知切法，也可通过 `--query-stride` 开启多 query / overlap query 生成。**
-
----
-
-## 5.2 为什么这样设计
-
-| 设计点 | 当前好处 | 当前限制 |
-|---|---|---|
-| 训练随机裁剪 | 节省存储，不必预生成几万切片 | 同一 epoch 暴露到的时间区域有限 |
-| 检索重叠滑窗 | 更接近真实 ACR reference coverage | 索引体积更大 |
-| 音乐感知候选切片 | 更容易打到主段、起音、拍点、非静音区 | CPU 分析成本更高 |
-| 外部数据少量 query smoke | smoke 更轻、更快验证 | 训练/评测覆盖不充分 |
-
-推荐理解方式：
-- **训练端**更像“随机数据增强采样器”
-- **检索端**更像“为了召回覆盖做滑窗索引”
-
-### 5.3 我们到底有没有用 librosa 的分段逻辑
-
-有，而且已经进入主链路，但不是“把整套结构分段 API 全盘替代随机采样”。
-
-当前已用到的 `librosa` 音乐感知逻辑：
-
-| 逻辑 | 当前用途 | 代码位置 |
-|---|---|---|
-| `librosa.effects.split` | `silence_aware`，避开静音区 | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
-| `librosa.onset.onset_detect` | `onset_aware`，优先起音附近 | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
-| `librosa.beat.beat_track` | `beat_aware`，优先规则拍点 | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
-| `librosa.feature.chroma_cqt` | `repeated_section_aware`，近似找重复主段 / hook | [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) |
-
-还**没有**直接上整套更重的 `librosa.segment.*` 结构分段主流程，原因主要是：
-
-1. **训练 query 的真实来源并不总对齐段落边界**，完全结构分段会把训练分布拉得过“整齐”；
-2. **CPU 成本更高**，对 FMA / MTG 这类大目录 smoke 和批量 manifest 生成不够轻；
-3. **当前阶段先追求稳健可复现**，优先落地静音、起音、拍点、重复段这几类收益更直接的候选策略。
-
-所以现在的设计不是“没考虑 librosa 分段”，而是：
-- **已经用了 librosa 的轻量高收益部分**
-- **保留 random 作为泛化增强**
-- **把更重的结构分段留作后续增强，而不是一上来替代全部采样逻辑**
-
----
-
-## 6. 当前训练信号与 hard-case 规则
-
-## 6.1 Hard-case 训练信号图
-
-```mermaid
-flowchart LR
-    A[Query Segment] --> B{type}
-    B -->|clean| C[w=1.0]
-    B -->|augmented| D[w=1.4]
-    B -->|humming_like| E[w=2.5]
-    B -->|confused| F[w=4.0]
-    C --> G[Sample-level SupCon + CE]
-    D --> G
-    E --> G
-    F --> G
-```
-
-| 类型 | 当前训练权重 | 目标 |
-|---|---:|---|
-| clean | 1.0 | 保持基础识别稳定 |
-| augmented | 1.4 | 提高常规退化鲁棒性 |
-| humming_like | 2.5 | 提高旋律近似查询鲁棒性 |
-| confused | 4.0 | 强化最易混淆片段分离能力 |
-
----
-
-## 6.2 检索融合参数图
-
-```mermaid
-flowchart LR
-    A[Chromaprint Score] --> D[Fused Score]
-    B[ECAPA Score] --> D
-    C[Melody Score] --> D
-```
-
-| 参数 | 默认值 | 当前验证更优值（fast-eval） | 含义 |
-|---|---:|---:|---|
-| `chroma_weight` | 0.25 | 0.20 | 降低纯指纹主导 |
-| `ecapa_weight` | 0.50 | 0.55 | 提高 embedding 检索主导 |
-| `melody_weight` | 0.25 | 0.25 | 暂时保持不变 |
-
----
-
-## 7. 开源数据集 train/eval 切分图
-
-```mermaid
-flowchart LR
-    A[Open Audio Dir] --> B[audio-dir-to-splits]
-    B --> C[catalog.json]
-    B --> D[train.json]
-    B --> E[test.json]
-    B --> F[val.json]
-```
-
-| 产物 | 用途 | 说明 |
-|---|---|---|
-| [catalog.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/catalog.json) | 建索引 | 所有 reference 曲目 |
-| [train.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/train.json) | 训练查询 | query + references |
-| [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json) | 评估查询 | query + references |
-| [val.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/val.json) | 预留验证集 | 当前可为空 |
-
-推荐法则：
-- FMA / MTG-Jamendo 可优先用于真实 train/eval baseline
-- 至少固定一部分曲目只进 [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json)，不要同时参与训练
-- 小数据集也要保证至少 1 个 train query + 1 个 test query
-
-CLI 入口：
-- 低层工具：[acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py)
-- 高层统一入口：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `prepare-local <dataset> <input_dir>`
-- 导入前预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-local <dataset> <input_dir>`
-- 多目录批量预检查：[acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-batch fma=<dir> mtg_jamendo=<dir> ...`
-
----
-
-## 8. 当前项目输入层规范
-
-| 项目 | 当前值/建议 | 说明 |
-|---|---|---|
-| 采样率 | `16kHz` | 统一音频读取口径 |
-| 声道 | `mono` | 当前链路按单声道处理 |
-| 频谱 | `128 Mel` | 音乐任务输入层 |
-| 训练 clip | `5s` | 当前训练代码事实 |
-| 外部 query manifest 默认 | `8s` | 当前 `prepare-local/smoke-local` 默认 |
-| Band split | `enabled` | 已纳入当前模型配置 |
-
----
-
-## 9. 文字说明
-
-### 9.1 为什么必须分离 catalog 和 query
-工业化系统里，“可搜索曲库”和“训练/评测 query”必须分离，否则评测会和真实服务语义混在一起。
-
-### 9.2 为什么输入层是 128 Mel
-音乐任务需要更丰富的频带表达；128 Mel 比 40 维 MFCC 更适合 timbre/harmony/band-split 建模。
-
-### 9.3 为什么 query 类型必须显式标注
-`clean / augmented / confused / humming_like` 不只是标签名，而是训练权重、评测 bucket、难例治理的入口。
-
-### 9.4 关于 5s vs 8s 的一个当前注意点
-当前仓库有两组时长：
-- **训练 Dataset 与默认模型训练：5s**
-- **开放数据 manifest/query 默认：8s**
-
-这不是同一层配置，因此当前文档和实验报告里必须明确区分；不要把它们误认为一套统一参数。
-
-### 9.5 当前经验结论
-- 简单过采样会导致整体退化
-- type-aware weighting 能提升一部分 hard case
-- confused 类需要更高权重，但过强偏置会回伤 `humming_like`
-- residual confused failure 往往集中在 `intro` 片段，因此 `segment_type` 不只是元数据，还应参与后续难负例设计
-
----
-
-## 10. 细节附录
-
-### Reference 示例
-```json
-{
-  "song_id": "song_0001",
-  "audio_path": "songs/song_0001.wav",
-  "duration": 20.0,
-  "type": "reference"
-}
-```
-
-### Query 示例
-```json
-{
-  "song_id": "song_0001",
-  "audio_path": "segments/song_0001_seg_04_confused.wav",
-  "duration": 5.0,
-  "type": "confused",
-  "offset": 8.3,
-  "segment_type": "mid"
-}
-```
-
-## Sources
-- 当前代码事实来自 [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), [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py), [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py), [acr-engine/train.py](../acr-engine/train.py)

-# Industrial Benchmark Spec
-
-> 更新：2026-06-02
-
-## 一页结论
-
-- 工业级 ACR 不能只看总 top1
-- 必须同时看：
-  1. hard-case
-  2. rejection / false accept
-  3. latency / scale
-  4. license provenance completeness
-
----
-
-## 1. Benchmark 分层图
-
-```mermaid
-flowchart TD
-    A[Industrial Benchmark] --> B[Accuracy]
-    A --> C[Robustness]
-    A --> D[Operational]
-    A --> E[Compliance]
-
-    B --> B1[top1/top5/MRR]
-    C --> C1[humming/confused/noisy]
-    D --> D1[latency/indexing/throughput]
-    E --> E1[data provenance/license coverage]
-```
-
----
-
-## 2. 指标表
-
-| 维度 | 指标 | 目标 |
-|---|---|---|
-| Accuracy | top1 / top5 / MRR | 主识别质量 |
-| Robustness | humming/confused/noisy top1 | hard-case 质量 |
-| Operational | p50/p95 latency | 服务能力 |
-| Operational | index throughput | 建库能力 |
-| Safety | false accept rate | 误识别风险 |
-| Compliance | license coverage | 商业可用前提 |
-
----
-
-## 3. 场景图
-
-```mermaid
-flowchart LR
-    Q[Queries] --> Q1[clean]
-    Q --> Q2[augmented]
-    Q --> Q3[humming_like]
-    Q --> Q4[confused]
-    Q --> Q5[noisy/compressed]
-```
-
----
-
-## 4. 文字说明
-
-### 4.1 为什么 hard-case 要单独出报表
-因为总体 top1 很容易掩盖哼唱和混淆场景的失败，而这些正是用户最敏感的场景。
-
-### 4.2 为什么要加入 operational metrics
-工业级系统不是离线竞赛模型，需要考虑服务响应与增量索引成本。
-
-### 4.3 为什么要把 compliance 放进 benchmark
-对于商用系统，如果训练/评测数据来源不可追溯，再高精度也不能安全上线。
-
----
-
-## 5. 细节附录
-
-推荐 release gate：
-- clean top1 >= 0.95
-- noisy top1 >= 0.85
-- confused top1 >= 0.70
-- humming_like top1 >= 0.60
-- top5 >= 0.95 on production-relevant buckets
-
-
-## Sources
-- See [references-and-sources.md](./references-and-sources.md) for the current source map.
-
-
-## 6. Bucket / Style-aware 基线
-
-当前仓库已经新增可运行基线脚本：
-- [../acr-engine/scripts/ab_smoke_bucketed.py](../acr-engine/scripts/ab_smoke_bucketed.py)
-
-用途：
-- 按 bucket 配置文件拆分多个小子集
-- 对每个 bucket 分别运行现有 `ab_smoke_segmentation.py`
-- 输出 bucket 级 winner 与聚合均值
-
-推荐最小配置文件格式：
-
-```json
-{
-  "buckets": [
-    {"name": "prefix_000_a", "patterns": ["fma_small/000/00000?.mp3"], "subset_size": 4},
-    {"name": "prefix_000_b", "patterns": ["fma_small/000/00014?.mp3"], "subset_size": 4}
-  ]
-}
-```
-
-推荐命令：
-
-```bash
-/usr/local/miniconda3/bin/python acr-engine/scripts/ab_smoke_bucketed.py   --dataset fma   --input-dir data/raw/fma_small_audio   --bucket-config /tmp/cap64_bucket_test.json   --work-root /tmp/ab_smoke_bucketed_smoke   --default-subset-size 4   --query-duration 8   --train-epochs 1   --batch-size 2   --device cpu   --strategies high_energy hybrid   --max-test-queries 4   --seed 42   --output-json /tmp/ab_smoke_bucketed_smoke/report.json
-```
-
-
-当前已验证的最小结果：
-- `prefix_000_a` winner=`hybrid`
-- `prefix_000_b` winner=`high_energy`
-- aggregate 层面两者 `mean_top1` 都是 `1.0`
-
-因此 bucket benchmark 的当前意义不是“选出唯一赢家”，而是为后续语义 bucket / hard-case bucket 提供一个可复用执行框架。
-
-
-推荐模板：
-- [../acr-engine/configs/buckets/fma_semantic_bucket_template.json](../acr-engine/configs/buckets/fma_semantic_bucket_template.json)
-
-它不是自动标注器，而是一个“人工先分 bucket，再复用统一 benchmark 流程”的执行模板。

-# 工业化路线图
-
-> 更新：2026-06-02
-
-## 一页结论
-
-当前项目已完成：
-- 原型可运行
-- retrieval-first 初步改造
-- 服务骨架
-- 外部数据 adapter 雏形
-
-下一阶段必须聚焦三件事：
-1. **真实数据接入**
-2. **hard-case 精度**
-3. **商业化合规与服务稳定性**
-
----
-
-## 1. 路线图图示
-
-```mermaid
-flowchart LR
-    P0[P0 原型跑通] --> P1[P1 真实数据验证]
-    P1 --> P2[P2 工程化与服务化]
-    P2 --> P3[P3 大规模索引]
-    P3 --> P4[P4 商用上线]
-```
-
----
-
-## 2. 阶段表
-
-| 阶段 | 目标 | 当前状态 | 核心产物 |
-|---|---|---|---|
-| P0 | 端到端原型 | 已完成 | demo/train/index/eval |
-| P1 | 白名单真实数据接入 | 进行中 | adapters/manifests/benchmark |
-| P2 | API / benchmark / ops | 进行中 | FastAPI + spec |
-| P3 | ANN / 增量索引 | 未完成 | Faiss/HNSW |
-| P4 | 可商用平台 | 未完成 | license gate / SLA / release flow |
-
----
-
-## 3. 近期优先级
-
-### Priority A
-- FMA / Jamendo 小规模白名单子集接入
-- humming_like / confused 精度提升
-- service 配置化与真实部署 smoke
-
-### Priority B
-- ANN 向量索引
-- 拒识/误接收指标
-- 模型版本化
-
-### Priority C
-- foundation model baseline
-- 在线评估与监控
-- 商业部署流程
-
----
-
-## 4. 分层职责
-
-| 层 | 重点 |
-|---|---|
-| 数据层 | 只接入可审计白名单数据 |
-| 模型层 | 以 retrieval 指标为主，不迷信分类头 |
-| 检索层 | 强化 hard-case 与 rejection |
-| 服务层 | 稳定 API、可配置、可观测 |
-| 合规层 | 任何上线模型必须可追溯数据来源 |
-
----
-
-## 5. 细节附录
-
-关联文档：
-- [数据来源与接入](./dataset-sources-and-licensing.md)
-- [工业评测规范](./industrial-benchmark-spec.md)
-- [服务接口](./service-api.md)
-
-
-## Sources
-- See [references-and-sources.md](./references-and-sources.md) for the current source map.

-# Model Card Template
-
-## 一页结论
-- 模型名称：
-- 版本：
-- 适用场景：
-- 不适用场景：
-
-## 1. 模型结构图
-
-```mermaid
-flowchart LR
-    A[Input Audio] --> B[128 Mel + BandSplit]
-    B --> C[Encoder]
-    C --> D[Embedding]
-    D --> E[Hybrid Retrieval]
-```
-
-## 2. 关键信息表
-
-| 项 | 内容 |
-|---|---|
-| 训练数据 |  |
-| 评测数据 |  |
-| 主要指标 |  |
-| 已知风险 |  |
-| 许可证约束 |  |
-
-## 3. 文字说明
-- 训练方式：
-- 模型限制：
-- 风险提示：
-
-## 4. 细节附录
-- checkpoint 路径
-- config 路径
-- benchmark 报告路径
-
-## Sources
-- `docs/dataset-spec.md`
-- `docs/benchmark-report-template.md`

-# Open Dataset Workflow / 开放数据工作流
-
-## 0. 本地真实数据就绪检查
-
-在跑 `smoke-local` 前，先确认目录里真的有足够的音频：
-
-```bash
-/usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready fma data/raw/fma_small_audio --eval-ratio 0.2 --query-duration 8.0
-/usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready mtg_jamendo data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0
-```
-
-判定标准：
-
-- 至少 `2` 个音频文件
-- 至少 `2` 个时长 `>= 8s` 的可切 query 文件
-- `ready_for_smoke=true` 才进入完整 smoke
-
-如果目录为空，状态快照脚本也会明确提示未就绪。
-
-
-> 更新：2026-06-02
-
-## 一页结论
-
-如果你要把 FMA / MTG-Jamendo 这类开源音乐目录真正接进项目，推荐只记住这一条链路：
-
-1. **inspect-local / inspect-batch**
-2. **prepare-local**
-3. **validate-local**
-4. 再进入训练与评估
-5. 生成 benchmark / model card / release artifacts
-6. 或直接使用一键 `smoke-local`
-
----
-
-## 1. 工作流图
-
-```mermaid
-flowchart LR
-    A[Local Open Audio Dir] --> B[inspect-local / inspect-batch]
-    B --> C[prepare-local]
-    C --> D[validate-local]
-    D --> E[train.py]
-    D --> F[evaluate.py]
-    F --> G[artifact bundle]
-```
-
----
-
-## 2. 最短命令表
-
-| 步骤 | 命令 | 作用 |
-|---|---|---|
-| 预检查 | [`src/data/external_adapters.py`](../acr-engine/src/data/external_adapters.py) `inspect-local ...` | 看规模是否足够 |
-| 批量比较 | [`src/data/external_adapters.py`](../acr-engine/src/data/external_adapters.py) `inspect-batch ...` | 比较多个候选目录 |
-| 生成清单 | [`src/data/external_adapters.py`](../acr-engine/src/data/external_adapters.py) `prepare-local ...` | 产出 train/test/catalog |
-| 训练前校验 | [`src/data/external_adapters.py`](../acr-engine/src/data/external_adapters.py) `validate-local ...` | 确认结构正确 |
-| 训练 smoke | [`train.py`](../acr-engine/train.py) `--data ... --dry-run` | 验证 manifests 可直接进入训练 |
-| 发布制品 | [`scripts/generate_artifacts.py`](../acr-engine/scripts/generate_artifacts.py) | 生成 benchmark/model-card/release-checklist |
-| 一键 smoke | [`src/data/external_adapters.py`](../acr-engine/src/data/external_adapters.py) `smoke-local ...` | 自动跑完整链路 |
-
----
-
-## 3. 推荐顺序
-
-### 3.1 单目录
-
-```bash
-/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 prepare-local fma data/raw/fma_small_audio --output-root data/external_ingested --eval-ratio 0.2 --query-duration 8.0 --query-stride 4.0
-/usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/fma/manifests
-/usr/local/miniconda3/bin/python train.py --data data/external_ingested/fma/manifests --output data/models_fma_smoke --device cpu --epochs 1 --batch-size 2 --dry-run
-/usr/local/miniconda3/bin/python run_demo.py build-index --data data/external_ingested/fma/manifests --model data/models_fma_smoke/best_model.pt --output data/index_fma_smoke --device cpu
-
-# 如果长时间 CPU 建索引被中断，可从 partial checkpoint 续跑
-/usr/local/miniconda3/bin/python run_demo.py build-index \
-  --data data/external_ingested/fma/manifests \
-  --model data/models_fma_smoke/best_model.pt \
-  --output data/index_fma_smoke \
-  --device cpu \
-  --resume \
-  --checkpoint-every-refs 100
-
-说明：
-- `smoke-local` 现在内部默认也会为 `build-index` 打开 `--resume`
-- checkpoint 会记录 `model_signature`
-- 如果这次训练出的 `best_model.pt` 与旧 partial checkpoint 不是同一个模型，恢复会被自动拒绝并从 0 重建，避免混入不同模型的 embedding
-
-## 小规模策略 A/B smoke
-
-如果你想快速比较不同 query / training 切片策略，可直接运行：
-
-```bash
-/usr/local/miniconda3/bin/python acr-engine/scripts/ab_smoke_segmentation.py \
-  --dataset fma \
-  --input-dir acr-engine/data/raw/fma_small_audio \
-  --work-root /tmp/ab_smoke_seg \
-  --subset-size 8 \
-  --query-duration 8 \
-  --train-epochs 1 \
-  --batch-size 2 \
-  --device cpu \
-  --output-json /tmp/ab_smoke_seg/report.json
-```
-
-当前脚本会比较：
-- `random`
-- `silence_aware`
-- `high_energy`
-- `beat_aware`
-- `repeated_section_aware`
-- `hybrid`
-
-排序规则：
-- 先按 `top1`
-- 再按 `topk`
-- 最后按 `num_queries`
-
-这样在 top1/top5 持平时，会优先保留**覆盖 query 更多**的策略，而不是误把 query 更少的策略排到第一。
-
-如果你要做**更公平**的策略比较，建议再加 `--max-test-queries`，让每个策略在同样的 query 预算下评测：
-
-```bash
-/usr/local/miniconda3/bin/python acr-engine/scripts/ab_smoke_segmentation.py \
-  --dataset fma \
-  --input-dir acr-engine/data/raw/fma_small_audio \
-  --work-root /tmp/ab_smoke_seg_cap \
-  --subset-size 6 \
-  --query-duration 8 \
-  --train-epochs 1 \
-  --batch-size 2 \
-  --device cpu \
-  --strategies hybrid \
-  --max-test-queries 5 \
-  --output-json /tmp/ab_smoke_seg_cap/report.json
-```
-
-已验证：
-- 最终报告会显式记录 `max_test_queries`
-- `evaluate.py` 会按 `--seed` 复现抽样
-- 端到端 smoke 报告中的 `num_queries` 已成功收敛到 `5`
-
-这一步的意义是：
-- 之前的 A/B 排名更偏“覆盖能力”
-- 加上 cap 后，可以更公平地比较“同等 query 成本下的识别质量”
-
-### 最新真实 FMA capped 结果（subset=16, `max_test_queries=12`）
-
-已完成一轮更公平的真实 FMA A/B：
-
-| 排名 | 策略 | num_queries | top1 | topk |
-|---:|---|---:|---:|---:|
-| 1 | `hybrid` | 12 | 1.0 | 1.0 |
-| 2 | `high_energy` | 12 | 1.0 | 1.0 |
-| 3 | `beat_aware` | 12 | 0.9167 | 1.0 |
-| 4 | `repeated_section_aware` | 12 | 0.8333 | 1.0 |
-
-当前建议：
-- **默认训练 / query 策略仍优先 `hybrid`**
-- `high_energy` 是当前最强的并列次选，适合更偏主段/高能区的数据
-- `beat_aware` 更适合规则节拍较强的风格，但在这轮 FMA 子集上略弱
-- `repeated_section_aware` 单独使用不如混合策略稳
-
-### 更新：更大 cap24 top2 对照（subset=24, `max_test_queries=16`）
-
-在更大的真实 FMA 子集上，只保留前两名策略继续对照：
-
-| 排名 | 策略 | num_queries | top1 | topk |
-|---:|---|---:|---:|---:|
-| 1 | `hybrid` | 16 | 1.0 | 1.0 |
-| 2 | `high_energy` | 16 | 0.8125 | 1.0 |
-
-这轮结果比 cap16 更有区分度，说明：
-- `hybrid` 不只是“和 `high_energy` 打平”
-- 在更大的真实子集上，`hybrid` 的稳定性更强
-- 当前默认推荐应明确收敛到 **`hybrid`**
-
-### 更新：cap32 top2 对照（subset=32, `max_test_queries=20`）
-
-进一步扩大到 32 首真实 FMA 子集后，结论继续强化：
-
-| 排名 | 策略 | num_queries | top1 | topk |
-|---:|---|---:|---:|---:|
-| 1 | `hybrid` | 20 | 0.95 | 1.0 |
-| 2 | `high_energy` | 20 | 0.5 | 1.0 |
-
-这说明：
-- `hybrid` 在更大真实子集上仍明显领先
-- `high_energy` 虽然可作为高能区偏置策略，但稳定性不足以成为默认
-- 当前默认策略已经可以稳定写死为 **`hybrid`**
-
-### 更新：cap48 top2 对照（subset=48, `max_test_queries=24`）
-
-继续扩大到 48 首真实 FMA 子集后，出现了**结果反转**：
-
-| 排名 | 策略 | num_queries | top1 | topk |
-|---:|---|---:|---:|---:|
-| 1 | `high_energy` | 24 | 0.9167 | 1.0 |
-| 2 | `hybrid` | 24 | 0.7917 | 1.0 |
-
-这轮结果说明：
-- 前面 cap24 / cap32 支持 `hybrid`
-- 但 cap48 上 `high_energy` 反超
-- 因此当前结论应从“默认策略已完全固定”调整为：
-  - **`hybrid` 仍是当前保守默认**
-  - **`high_energy` 已成为强竞争方案**
-  - 下一步必须做更大样本或多随机种子复核，不能只靠单轮 cap48 就完全改默认
-
-### 更新：cap48 第二个 seed 复核（subset=48, `max_test_queries=24`, `seed=123`）
-
-对同一规模再跑第二个 seed 后，结果又回到 `hybrid` 领先：
-
-| 排名 | 策略 | num_queries | top1 | topk |
-|---:|---|---:|---:|---:|
-| 1 | `hybrid` | 24 | 0.9583 | 1.0 |
-| 2 | `high_energy` | 24 | 0.9167 | 1.0 |
-
-这说明：
-- cap48 的策略排名对 seed / 抽样子集 **敏感**
-- 单次 cap48 不能作为“high_energy 已全面反超”的充分证据
-- 当前最稳妥结论仍是：
-  - `hybrid` 保留为保守默认
-  - `high_energy` 保留为强竞争方案
-  - 后续需要 **多 seed 聚合结论**，而不是看单次跑分
-
-### cap48 多 seed 聚合摘要（当前 2 次）
-
-把 cap48 的两次 seed 放到一起看：
-
-| 策略 | runs | mean_top1 | min_top1 | max_top1 | stdev_top1 | mean_topk |
-|---|---:|---:|---:|---:|---:|---:|
-| `high_energy` | 2 | 0.9167 | 0.9167 | 0.9167 | 0.0 | 1.0 |
-| `hybrid` | 2 | 0.8750 | 0.7917 | 0.9583 | 0.0833 | 1.0 |
-
-当前可解释为：
-- `high_energy` 在这两次 cap48 上**均值更高且更稳定**
-- `hybrid` 在第二个 seed 上更强，但波动也更大
-- 因此目前最准确的表述不是“谁绝对赢”，而是：
-  - **cap48 上 `high_energy` 的聚合均值暂时领先**
-  - **`hybrid` 仍是更保守的默认候选**
-  - 最终默认仍应等待更多 seed 或更大样本确认
-/usr/local/miniconda3/bin/python evaluate.py --data data/external_ingested/fma/manifests --model data/models_fma_smoke/best_model.pt --index-prefix data/index_fma_smoke/reference --split test --device cpu --fast-eval --output-json reports/fma-smoke/eval.json
-/usr/local/miniconda3/bin/python scripts/generate_artifacts.py --eval-json reports/fma-smoke/eval.json --config-json reports/fma-smoke/config.json --output-dir reports/fma-smoke --model-version fma-smoke --data-version fma_local
-```
-
-### 3.2 多目录比较
-
-```bash
-/usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-batch fma=data/raw/fma_small_audio mtg_jamendo=data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0
-```
-
-### 3.3 一键 smoke
-
-```bash
-/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
-/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 --device auto
-/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 --query-stride 4.0 --train-epochs 1 --batch-size 2 --device auto
-```
-
-真实目录放置位置可参考：
-- [acr-engine/data/raw/README.md](../acr-engine/data/raw/README.md)
-- [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/)
-
----
-
-## 4. 输出物说明
-
-- [catalog.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/catalog.json)：建索引用 reference 清单
-- [train.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/train.json)：训练 queries + references
-- [test.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/test.json)：固定评估 queries + references
-- [val.json](../acr-engine/data/external_ingested/demo_via_adapter/fma/manifests/val.json)：可选验证集
-
----
-
-## 5. 当前验证证据
-
-已在本地 `data/synthetic_v2/songs` 上按开放数据流程跑通：
-
-- `inspect-local`：
-  - `num_audio_files=24`
-  - `recommended_train_queries=19`
-  - `recommended_test_queries=5`
-- `prepare-local`：
-  - `catalog=24`
-  - `train_queries=16`
-  - `test_queries=8`
-- `validate-local`：
-  - `ok=true`
-- `train.py --dry-run`：
-  - `Dry run passed! Pipeline is working.`
-- `build-index + evaluate`：
-  - `top1=1.0`
-  - `topk=1.0`
-- `generate_artifacts`：
-  - `benchmark-report.md`
-  - `model-card.md`
-  - `release-checklist.md`
-- `smoke-local`：
-  - 会一次性返回 inspect / prepare / validate / report 路径摘要
-  - 现在支持 `--device cpu|cuda|auto`
-  - `auto` 会在 smoke 内部解析成实际设备，避免把字符串 `auto` 直接传给 embedding/eval 侧
-  - 现在支持 `--query-stride`
-  - 当设置 `--query-stride < query-duration` 时，会为单首歌生成多个重叠 query，而不是只采 1 个随机 query
-
----
-
-
-### FMA 下载完成后的单条准备命令
-
-```bash
-cd acr-engine
-/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py
-```
-
-这个脚本会在归档完整时自动执行：
-
-1. `extract`
-2. `check-local-ready`
-3. `inspect-local`
-
-如果归档还没下完，会返回结构化 `archive_not_complete`。
-
-
-### FMA 完成前等待并自动切换
-
-```bash
-cd acr-engine
-/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 120
-```
-
-作用：
-
-- 周期性检查 `fma_small.zip` 是否完成
-- 一旦完成，自动进入 [scripts/fma_postdownload_ready.py](../acr-engine/scripts/fma_postdownload_ready.py)
-- 如果还没完成，则返回 `waiting` 和最近的进度快照
-
-## Sources
-- See [dataset-spec.md](./dataset-spec.md)
-- See [dataset-sources-and-licensing.md](./dataset-sources-and-licensing.md)
-
-
-### Bucket / style-aware benchmark 基线
-
-为了避免只看单一子集规模，现在仓库里已经有可运行的 bucket benchmark 基线：
-- [../acr-engine/scripts/ab_smoke_bucketed.py](../acr-engine/scripts/ab_smoke_bucketed.py)
-
-它的作用是：
-1. 从同一大目录中按 pattern 划出多个 bucket
-2. 每个 bucket 各自运行 `ab_smoke_segmentation.py`
-3. 生成 bucket 级 winner 与 aggregate summary
-
-最小 smoke 已验证：
-- bucket: `prefix_000_a`
-- `hybrid`: `4 / 1.0 / 1.0`
-- `high_energy`: `3 / 1.0 / 1.0`
-- winner: `hybrid`
-
-完整 bucket 汇总现已完成：
-- `prefix_000_a` winner=`hybrid`
-- `prefix_000_b` winner=`high_energy`
-- aggregate：
-  - `hybrid`：`mean_top1=1.0, mean_topk=1.0, mean_num_queries=4.0`
-  - `high_energy`：`mean_top1=1.0, mean_topk=1.0, mean_num_queries=3.5`
-
-当前结论：
-- bucket baseline 已经能稳定复现“不同子集会选出不同 winner”。
-- 下一步不是继续做 prefix toy bucket，而是升级到更有业务意义的 bucket。
-
-推荐直接从模板开始：
-- [../acr-engine/configs/buckets/fma_semantic_bucket_template.json](../acr-engine/configs/buckets/fma_semantic_bucket_template.json)
-
-建议先人工挑一批歌，再把 glob 替换成你自己的候选集合，优先覆盖：
-1. `energy_dominant`
-2. `repeated_section_rich`
-3. `steady_beat_regular_meter`
-4. `hard_negative_confusable`
-
-对应命令：
-
-```bash
-cd /workspace/acr-engine
-/usr/local/miniconda3/bin/python scripts/ab_smoke_bucketed.py \
-  --dataset fma \
-  --input-dir data/raw/fma_small_audio \
-  --bucket-config configs/buckets/fma_semantic_bucket_template.json \
-  --work-root /tmp/ab_smoke_bucketed_semantic \
-  --default-subset-size 16 \
-  --query-duration 8 \
-  --train-epochs 1 \
-  --batch-size 2 \
-  --device cpu \
-  --strategies high_energy hybrid \
-  --max-test-queries 8 \
-  --seed 42 \
-  --output-json /tmp/ab_smoke_bucketed_semantic/report.json
-```
-
-
-### 业务素材 bucket 模板
-
-如果下一步不是继续用 FMA，而是切到你们自己的歌曲/BGM 素材，优先看：
-- [business-music-bucket-and-type-guide.md](./business-music-bucket-and-type-guide.md)
-- [../acr-engine/configs/buckets/business_type_bucket_template.json](../acr-engine/configs/buckets/business_type_bucket_template.json)

@@ -256,6 +256,132 @@ window -> fingerprint / embedding -> candidate -> aggregate
 
 ---
 
+## 1.2 当前业务前提变化：版本暂不重要，先做 song-centric
+
+如果当前业务约束是：
+
+> **同一个歌曲下可以有多个录音或多个音频，但暂时不关心版本语义，只需要最终稳定归到同一个 `song_id`**
+
+那么当前 Phase-1 最推荐的默认口径应进一步收敛为：
+
+```text
+song -> asset -> window -> feature
+```
+
+也就是说：
+- `song` 是当前唯一必须稳定返回的归属对象
+- 同一个 `song` 下允许存在多个音频文件
+- 这些音频文件可以是官方、抓取、BGM、片段、query sample 等不同来源
+- 现阶段先不把“录音版本差异”提升成必须单独建模的核心层
+
+### 当前最推荐的物理实现
+
+在这个业务前提下，最推荐直接采用 **3+1 张融合表**：
+
+| 物理表 | 主要 type | 当前作用 |
+|---|---|---|
+| `media_entity` | `song` | 只承载最终业务归属对象 |
+| `audio_object` | `asset`, `window` | 承载音频文件与切片窗口 |
+| `feature_fact` | `fingerprint`, `embedding` | 承载检索特征事实 |
+| `set_membership` | `reference_set`, `hot_set`, `eval_set` | 承载 reference / eval 等集合关系 |
+
+对应逻辑主链：
+
+```text
+song -> asset -> window -> feature
+```
+
+### 切片数据、模型、feature 具体落在哪些表
+
+在当前 **song-centric + 融合优先** 设计下，可以直接按下面理解：
+
+| 你关心的对象 | 当前推荐表 | 关键 type / 字段 | 作用 |
+|---|---|---|---|
+| 歌曲主实体 | `media_entity` | `entity_type=song` | 最终归属到哪个 `song_id` |
+| 原始音频文件 | `audio_object` | `object_type=asset`, `song_id`, `storage_uri`, `checksum` | 保存同一 song 下的多个音频文件 |
+| 切片窗口 | `audio_object` | `object_type=window`, `parent_object_id=<asset_id>`, `start_ms`, `end_ms` | 保存由 asset 切出来的检索窗口 |
+| 模型信息 | `feature_fact` | `model_name`, `model_version`, `feature_set_name` | 记录这条特征是哪个模型、哪套参数算的 |
+| fingerprint 特征 | `feature_fact` | `feature_type=fingerprint`, `fingerprint_value` | 保存 exact lane 特征 |
+| embedding 特征 | `feature_fact` | `feature_type=embedding`, `embedding_dim`, `embedding_uri`, `vector_table_name` | 保存 semantic lane 特征 |
+| reference / eval 归属 | `set_membership` | `set_type`, `member_type`, `member_id` | 决定哪些 asset/window/song 进入 reference 集 |
+
+最关键的一点是：
+
+> **切片本身也落在 `audio_object`，只是 `object_type=window`；模型与特征统一落在 `feature_fact`。**
+
+### 对应流程图
+
+```mermaid
+flowchart TD
+    A[media_entity
+entity_type=song] --> B[audio_object
+object_type=asset]
+    B --> C[audio_object
+object_type=window]
+    C --> D1[feature_fact
+feature_type=fingerprint]
+    C --> D2[feature_fact
+feature_type=embedding]
+    D1 --> E[set_membership
+reference_set / eval_set]
+    D2 --> E
+```
+
+### 对应写入流程
+
+```mermaid
+sequenceDiagram
+    participant ING as Ingest Job
+    participant DB as PostgreSQL
+
+    ING->>DB: 写 media_entity(song)
+    ING->>DB: 写 audio_object(asset)
+    ING->>DB: 切窗后写 audio_object(window)
+    ING->>DB: 写 feature_fact(fingerprint)
+    ING->>DB: 写 feature_fact(embedding)
+    ING->>DB: 写 set_membership(reference/eval)
+```
+
+### 一个最实用的查询回溯口径
+
+如果 query 命中了一条 embedding/fingerprint，回溯路径就是：
+
+```text
+feature_fact -> audio_object(window) -> audio_object(asset) -> media_entity(song)
+```
+
+这条链已经足够支撑你当前最关心的问题：
+- 这个切片来自哪个音频文件
+- 这个音频文件归到哪个 `song_id`
+- 这条特征是哪个模型/feature set 算出来的
+
+---
+
+### 为什么现在可以先不把 `recording` 做成强实体
+
+因为你当前不关心：
+- official / live / remaster 的严格版本区分
+- cover/version lane 的独立归档
+- 返回结果必须精确到 recording_id
+
+你当前真正关心的是：
+
+> 这一批不同来源、不同形式的音频，最后是否都能被稳定归到同一个 `song_id`
+
+在这个目标下，把 `recording` 作为强主层，会增加理解成本，但对当前第一阶段收益有限。
+
+### 但这不代表未来永远不要 `recording`
+
+推荐的处理方式是：
+- **当前 schema 默认不强推 `recording`**
+- 如果未来开始关心版本归属，再把 `recording` 从 `media_entity(entity_type=recording)` 或 `audio_object.metadata_json` 中提升出来
+
+换句话说：
+- **当前先做 song-centric 检索归属**
+- **未来再演进到 recording-centric / work-centric 治理**
+
+---
+
 ## 1.2.1 融合优先：逻辑分层保留，物理表尽量收敛
 
 如果你的核心诉求是：
@@ -264,7 +390,7 @@ window -> fingerprint / embedding -> candidate -> aggregate
 
 那么推荐采用下面这个口径：
 
-- **逻辑层** 仍然保留 `song / recording / asset / window / feature`
+- **逻辑层** 当前默认保留 `song / asset / window / feature`；`recording` 仅保留为未来扩展语义
 - **物理层** 尽量融合成少数几张通用表
 
 也就是说：
@@ -275,7 +401,7 @@ window -> fingerprint / embedding -> candidate -> aggregate
 
 | 物理表 | 主要 type | 作用 |
 |---|---|---|
-| `media_entity` | `song`, `work`, `recording` | 承载业务归属对象 |
+| `media_entity` | `song`（当前默认）, `work`/`recording`（未来扩展） | 承载业务归属对象 |
 | `audio_object` | `asset`, `window` | 承载真实音频文件与切片对象 |
 | `feature_fact` | `fingerprint`, `embedding` | 承载检索特征事实 |
 | `set_membership` | `reference_set`, `hot_set`, `eval_set` | 承载集合归属关系 |
@@ -292,9 +418,9 @@ media_entity -> audio_object -> feature_fact -> set_membership
 
 #### `media_entity`
 用 `entity_type` 区分：
-- `song`
-- `work`
-- `recording`
+- `song`（当前默认必用）
+- `work`（可选）
+- `recording`（未来扩展）
 
 公共字段可统一为：
 - `entity_id`
@@ -354,7 +480,7 @@ media_entity -> audio_object -> feature_fact -> set_membership
 
 优点：
 1. **新同学更容易理解**：看到的是 3~4 张核心表，而不是十几张专用表
-2. **多 type 复用更自然**：`song/work/recording`、`asset/window` 都能用 type 统一表达
+2. **更符合当前业务前提**：多个音频直接挂到同一个 `song_id`，先不强区分 recording
 3. **模型演进更平滑**：`feature_fact` 可以同时容纳不同模型与不同特征
 4. **更符合当前目标**：先把识别闭环跑通，而不是先把治理模型拆到很细
 
@@ -395,7 +521,7 @@ song_everything
 
 | 层 | 融合优先推荐表 | 当前作用 |
 |---|---|---|
-| 实体层 | `media_entity` | 统一承载 `song/work/recording` |
+| 实体层 | `media_entity` | 当前默认只承载 `song` |
 | 音频对象层 | `audio_object` | 统一承载 `asset/window` |
 | 特征层 | `feature_fact` | 统一承载 `fingerprint/embedding` |
 | 集合层 | `set_membership` | 统一承载 `reference/hot/eval` 等集合关系 |
@@ -406,10 +532,10 @@ song_everything
 media_entity -> audio_object -> feature_fact -> set_membership
 ```
 
-如果按逻辑语义理解，则仍然对应：
+如果按逻辑语义理解，则当前默认对应：
 
 ```text
-song/work/recording -> asset/window -> fingerprint/embedding -> reference membership
+song -> asset/window -> fingerprint/embedding -> reference membership
 ```
 
 ### 这版极简 schema 明确不要求第一天就重投入的内容

 # Production Encoder Freeze & Embedding Strategy / 生产 Encoder 冻结与 Embedding 策略答疑
 
 > 更新：2026-06-03  
-> 关联文档：[持续开发交接文档](./session-handoff.md) · [训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md) · [开放数据工作流](./open-dataset-workflow.md) · [服务接口](./service-api.md)
+> 关联文档：[持续开发交接文档](./session-handoff.md) · [PostgreSQL 数据模型](./postgresql-data-model.md) · [Phase-1 实施清单](./phase1-implementation-checklist.md)
 
 ## 一页结论
 
@@ -623,9 +623,9 @@ prod_artifacts/
 
 ## Sources
 - [持续开发交接文档](./session-handoff.md)
-- [训练数据与 pgvector 指南](./training-data-and-pgvector-guide.md)
-- [开放数据工作流](./open-dataset-workflow.md)
-- [服务接口](./service-api.md)
+- [postgresql-data-model.md](./postgresql-data-model.md)
+- [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
+- [phase1-worker-contract.md](./phase1-worker-contract.md)
 - [acr-engine/train.py](../acr-engine/train.py)
 - [acr-engine/run_demo.py](../acr-engine/run_demo.py)
 - [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py)

-# ACR 项目职责图
-
-> 更新：2026-06-02
-
-## 一页结论
-
-- 本项目已经从“算法原型”升级为“**面向工业化的 ACR 平台雏形**”
-- 当前系统分为 **数据层、训练层、检索层、服务层、评测层、合规层**
-- 近期重点不是再堆功能，而是：
-  1. 提升 `humming_like` / `confused` 准确率
-  2. 接入真实白名单数据集
-  3. 完善服务、索引、benchmark 与合规闭环
-
----
-
-## 1. 分层图
-
-```mermaid
-flowchart TD
-    A[L1 业务目标层] --> B[L2 系统能力层]
-    B --> C[L3 核心模块层]
-    C --> D[L4 工程服务层]
-    C --> E[L5 数据与合规层]
-
-    A1[听歌识曲 / 哼唱识别 / 商业可用]:::goal --> A
-
-    B1[高准确率识别] --> B
-    B2[可扩展曲库] --> B
-    B3[可服务化调用] --> B
-    B4[可审计数据来源] --> B
-
-    C1[训练与表征学习] --> C
-    C2[指纹检索] --> C
-    C3[向量检索] --> C
-    C4[混合重排] --> C
-    C5[评测基准] --> C
-
-    D1[FastAPI] --> D
-    D2[Index Build] --> D
-    D3[Manifest Tools] --> D
-
-    E1[External Adapters] --> E
-    E2[Dataset Registry] --> E
-    E3[License Review] --> E
-
-    classDef goal fill:#e8f5e9,stroke:#2e7d32;
-```
-
----
-
-## 2. 职责总表
-
-| 层级 | 模块 | 负责内容 | 当前状态 |
-|---|---|---|---|
-| 数据层 | `src/data/*` | synthetic 数据、external adapters、manifest | 已有基础 |
-| 训练层 | `train.py` / `src/models/*` | 128 Mel、band-split、embedding 学习 | 可运行 |
-| 检索层 | `src/engines/*` | chromaprint、embedding、melody-aware hybrid | 可运行 |
-| 服务层 | `src/service/*` | health / recognize / index build | 骨架已通 |
-| 评测层 | `evaluate.py` | top1/top5/hard-case benchmark | 已建立 |
-| 合规层 | registry/docs | dataset source / licensing / whitelist | 雏形已建 |
-
----
-
-## 3. 分工图
-
-```mermaid
-flowchart LR
-    D[数据团队] --> D1[数据接入]
-    D --> D2[manifest 标准化]
-    D --> D3[license 审查]
-
-    M[模型团队] --> M1[特征与模型]
-    M --> M2[鲁棒训练]
-    M --> M3[hard-case 优化]
-
-    R[检索团队] --> R1[指纹索引]
-    R --> R2[向量索引]
-    R --> R3[融合与拒识]
-
-    S[平台团队] --> S1[API 服务]
-    S --> S2[部署]
-    S --> S3[监控]
-
-    Q[质量团队] --> Q1[benchmark]
-    Q --> Q2[回归验证]
-    Q --> Q3[上线门禁]
-```
-
----
-
-## 4. 文字说明
-
-### 4.1 数据层
-负责把不同来源的数据集（synthetic、FMA、Jamendo、CCMusic、ModelScope 白名单集）转成统一的 `catalog/query manifest`。
-
-### 4.2 训练层
-负责音乐任务特征建模，目前已经从低维说话人风格输入升级到：
-- 128 Mel
-- band-split
-- retrieval-first 训练方向
-
-### 4.3 检索层
-负责三路信息融合：
-- 指纹匹配
-- embedding 匹配
-- melody-aware 重排
-
-### 4.4 服务层
-负责把离线原型包装成可调用系统，目前已有 FastAPI 骨架。
-
-### 4.5 评测层
-负责质量门禁，不能只看总体 top1，要看 hard-case、拒识、误接收。
-
-### 4.6 合规层
-负责商用前提，任何外部数据集都必须进入 registry 和白名单流程。
-
----
-
-## 5. 细节附录
-
-关键文档：
-- `docs/dataset-spec.md`
-- `docs/industrial-benchmark-spec.md`
-- `docs/dataset-sources-and-licensing.md`
-- `docs/industrialization-roadmap.md`
-
-
-## Sources
-- See `docs/references-and-sources.md` for the current source map.

-# References and Sources Map
-
-> 更新：2026-06-02
-
-## 一页结论
-
-当前项目的引用分成四类：
-1. **开源数据集来源**
-2. **研究/SOTA 来源**
-3. **服务与工程规范来源**
-4. **项目内部文档来源**
-
----
-
-## 1. 引用分层图
-
-```mermaid
-flowchart TD
-    A[References] --> B[Datasets]
-    A --> C[Research]
-    A --> D[Engineering]
-    A --> E[Internal Docs]
-
-    B --> B1[FMA]
-    B --> B2[MTG-Jamendo]
-    B --> B3[CCMusic]
-    B --> B4[ModelScope]
-
-    C --> C1[Neural AFP]
-    C --> C2[Music Foundation Models]
-    C --> C3[Band-split]
-    C --> C4[Data Balancing]
-```
-
----
-
-## 2. 外部来源表
-
-| 类别 | 名称 | URL | 当前用途 |
-|---|---|---|---|
-| Dataset | FMA | https://github.com/mdeff/fma | 真实 retrieval baseline 候选 |
-| Dataset | MTG-Jamendo | https://github.com/MTG/mtg-jamendo-dataset | 真实音乐检索候选 |
-| Dataset | CCMusic | https://ccmusic-database.github.io/en/database/ccm.html | 中文 MIR 数据源候选 |
-| Dataset | ModelScope music search | https://modelscope.cn/search?page=1&search=music&type=dataset | 数据发现入口 |
-| Research | MERT | https://arxiv.org/abs/2306.00107 | foundation-model 方向参考 |
-| Research | MuQ | https://arxiv.org/abs/2501.01108 | music representation 方向参考 |
-| Research | Band-split RNN | https://arxiv.org/abs/2209.15174 | 频带建模参考 |
-| Research | BAGAN | https://arxiv.org/abs/1803.09655 | 数据平衡增强参考 |
-
----
-
-## 3. 内部文档依赖图
-
-```mermaid
-flowchart LR
-    A[references-and-sources.md] --> B[dataset-sources-and-licensing.md]
-    A --> C[sota-research-2026.md]
-    A --> D[industrialization-roadmap.md]
-```
-
----
-
-## 4. 文字说明
-
-### 4.1 为什么单独做 References Map
-因为后续文档会越来越多，如果不把“哪些结论来自哪里”系统整理出来，很快会失去可追溯性。
-
-### 4.2 目前引用质量说明
-- dataset 来源：优先官方 repo / 官方主页
-- research 来源：优先 arXiv / 论文主页
-- service/工程来源：当前主要以内生工程规范为主
-
-### 4.3 未来要加强的地方
-- 在每篇核心文档底部补“Sources”小节
-- benchmark 报告与 model card 显式引用训练数据与论文版本
-
----
-
-## 5. 细节附录
-
-建议补充：
-- 每份文档增加 `Sources` 节
-- 每次模型 release 输出引用快照
-
-## Sources
-- FMA: https://github.com/mdeff/fma
-- MTG-Jamendo: https://github.com/MTG/mtg-jamendo-dataset
-- CCMusic: https://ccmusic-database.github.io/en/database/ccm.html
-- ModelScope music search: https://modelscope.cn/search?page=1&search=music&type=dataset

-# Release Checklist
-
-## 一页结论
-发布前必须同时满足：
-- 质量通过
-- 合规通过
-- 服务通过
-- 文档齐全
-
-## 1. 发布门禁图
-
-```mermaid
-flowchart TD
-    A[Release Candidate] --> B[Benchmark Pass]
-    A --> C[License Review Pass]
-    A --> D[Service Smoke Pass]
-    A --> E[Docs Complete]
-```
-
-## 2. Checklist 表
-
-| 项目 | 状态 |
-|---|---|
-| benchmark report 已生成 |  |
-| model card 已生成 |  |
-| license registry 已更新 |  |
-| service smoke test 通过 | partial: `/health` OK, `/recognize/voice` payload returns against `workspace_music20`, but batch validation is currently poor (`type_7 top1=0.0/top3=0.05`, `type_8 top1=0.0/top3=0.0`, `type_16 top1=0.0/top3=0.0`) |
-| dataset whitelist 已确认 |  |
-| changelog 已更新 | yes |
-| architect review completed | yes (approved with watch) |
-
-## 3. 文字说明
-- 任何缺失项都不能视作商用可发布
-
-## 4. 细节附录
-- 发布 commit
-- benchmark 报告路径
-- model card 路径
-- license 审查记录路径
-
-## Sources
-- `docs/dataset-sources-and-licensing.md`
-- `docs/industrial-benchmark-spec.md`
-
-
-## 2026-06-03 voice-query service foundation
-
-- `/health` 已可用
-- `/recognize/voice` 路由已接入，但当前推理仍被 `torch` 缺失阻塞
-- 本地 FAISS 20-song 验证已完成
-- handoff / changelog / docs README 已同步
-
-- handoff 已刷新：yes（已指向 voice service runtime 当前状态与下一步排查路径）
-
-- business-corpus song_id baseline 已生成：yes（`data/pgvector_eval/music20/songid_eval_report.json`）

-# Report Layout Convention
-
-## 一页结论
-
-所有评测与发布产物统一放入：
-
-- `reports/<model-version>/<data-version>/eval.json`
-- `reports/<model-version>/<data-version>/benchmark-report.md`
-- `reports/<model-version>/<data-version>/model-card.md`
-- `reports/<model-version>/<data-version>/release-checklist.md`
-- `reports/<model-version>/<data-version>/artifact-manifest.json`
-
----
-
-## 1. 布局图
-
-```mermaid
-flowchart TD
-    A[reports/] --> B[model-version]
-    B --> C[data-version]
-    C --> D[eval.json]
-    C --> E[benchmark-report.md]
-    C --> F[model-card.md]
-    C --> G[release-checklist.md]
-    C --> H[artifact-manifest.json]
-```
-
----
-
-## 2. 约定表
-
-| 文件 | 用途 |
-|---|---|
-| eval.json | 机器可读评测输出 |
-| benchmark-report.md | 人类可读 benchmark 摘要 |
-| model-card.md | 模型说明 |
-| release-checklist.md | 发布门禁 |
-| artifact-manifest.json | 产物索引 |
-
----
-
-## 3. 文字说明
-- 所有 release 候选都应有独立目录
-- 不要把临时 smoke 文件与正式 release 报告混放
-
-## Sources
-- docs/benchmark-report-template.md
-- docs/model-card-template.md
-- docs/release-checklist.md

-# ACR 项目运行手册
-
-## 1. 环境
-
-```bash
-cd acr-engine
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-## 2. 生成数据
-
-```bash
-python run_demo.py generate-data --output data/synthetic --num-songs 24
-```
-
-## 3. 校验训练链路
-
-```bash
-python train.py --data data/synthetic --dry-run --device cpu
-```
-
-## 4. 最小训练
-
-```bash
-python train.py --data data/synthetic --output data/models --device cpu --epochs 1 --batch-size 8
-```
-
-## 5. 建索引
-
-```bash
-python run_demo.py build-index --data data/synthetic --model data/models/best_model.pt --output data/index --device cpu
-```
-
-## 6. 跑识别
-
-```bash
-python run_demo.py recognize \
-  --query data/synthetic/segments/song_0020_seg_00.wav \
-  --data data/synthetic \
-  --model data/models/best_model.pt \
-  --index-prefix data/index/reference \
-  --device cpu
-```
-
-## 7. 成功判定
-
-至少满足：
-
-- 能输出 JSON 结果
-- 返回 `candidates`
-- 结果中包含 `song_id` 和 `confidence`

-# ACR Service API
-
-> 更新：2026-06-02
-
-## 一页结论
-
-- 当前服务是工业化骨架，不是最终生产网关
-- 已提供最小可调用能力：
-  1. health
-  2. ready
-  3. config
-  4. cache
-  5. recognize
-  6. index build
-- 已补充：服务就绪探针、基础缓存可见性、索引/模型存在性检查
-- 下一阶段重点是：鉴权、异步任务、ANN 索引、监控、错误码规范化
-
----
-
-## 1. 服务结构图
-
-```mermaid
-flowchart LR
-    C[Client] --> H[/health]
-    C --> H2[/ready]
-    C --> G[/config]
-    C --> C2[/cache]
-    C --> R[/recognize]
-    C --> I[/index/build]
-
-    R --> E[Hybrid Engine Cache]
-    I --> B[Index Builders]
-```
-
----
-
-## 2. Endpoint 表
-
-| Endpoint | 方法 | 作用 |
-|---|---|---|
-| `/health` | GET | 健康检查 |
-| `/config` | GET | 查看默认配置 |
-| `/ready` | GET | 查看模型/索引/manifest 是否就绪 |
-| `/cache` | GET | 查看当前 engine cache 状态 |
-| `/recognize` | POST | 输入 query，输出候选 |
-| `/index/build` | POST | 触发离线索引构建 |
-
----
-
-## 3. 请求流程图
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant API
-    participant Engine
-
-    Client->>API: POST /recognize
-    API->>Engine: load matcher/index/model
-    Engine-->>API: top-k candidates
-    API-->>Client: JSON result
-```
-
----
-
-## 4. 文字说明
-
-### 4.1 为什么先暴露文件路径 API
-当前阶段优先验证系统闭环，不急于引入上传存储层与异步 job orchestration。
-
-### 4.2 `/config` 的作用
-帮助服务侧和调用侧快速确认当前默认数据目录、模型路径与索引前缀。
-
-### 4.3 后续生产化差距
-- 缺鉴权
-- 缺对象存储上传
-- 缺异步索引任务
-- 缺可观测性
-- 缺错误码与 SLA 规范
-
----
-
-## 5. 细节附录
-
-### `/health`
-返回：
-```json
-{"status":"ok","service":"acr","version":"0.2.0"}
-```
-
-### `/config`
-返回：
-```json
-{
-  "data_dir":"data/synthetic_v2",
-  "model_path":"data/models_v3/best_model.pt",
-  "index_prefix":"data/index_v3/reference",
-  "device":"cpu"
-}
-```
-
-
-### `/ready`
-返回：
-```json
-{
-  "service":"acr",
-  "version":"0.3.0",
-  "ready":true,
-  "files":{...},
-  "manifests":[...],
-  "engine_cache_size":0
-}
-```
-
-### `/cache`
-返回当前进程内 engine cache 统计。
-
-
-
-## 6. 本地运行与 smoke
-
-```bash
-cd acr-engine
-/usr/local/miniconda3/bin/python -m uvicorn src.service.app:app --host 127.0.0.1 --port 8000
-```
-
-另一个终端可直接执行：
-
-```bash
-cd acr-engine
-/usr/local/miniconda3/bin/python scripts/service_smoke.py
-```
-
-该 smoke 当前会校验：
-
-- `/health`
-- `/ready`
-- `/config`
-- `/cache`
-
-## Sources
-- See [references-and-sources.md](./references-and-sources.md) for the current source map.

-# ACR / Music Retrieval SOTA Research (截至 2026-06-02)
-
-## 结论摘要
-
-到 2025-2026，这个方向相比传统“从零训练一个小型 ECAPA embedding”已经明显前进了。
-
-当前更强的方向主要有三类：
-
-1. **Neural Audio Fingerprinting 的鲁棒训练增强**
-2. **Music Foundation Model 作为 backbone / teacher**
-3. **Band-split / band-aware 结构用于音乐频谱建模**
-
-对本项目当前阶段的直接结论：
-- **仅靠样本重复或统一加权不是 SOTA 思路**
-- 更接近 2026 工业最佳实践的是：**retrieval-first + hard negative mining + foundation model backbone + 任务专门支路**
-- 我们当前仓库已经走到其中两步：`128 Mel + band-split`、`retrieval-first eval`
-- 下一步最该补的是：`confusion-aware negatives` 与 `humming melody tower`
-
-
-## 1. 方向图
-
-```mermaid
-flowchart LR
-    A[2026 ACR / MIR SOTA] --> B[Neural AFP Robustness]
-    A --> C[Music Foundation Models]
-    A --> D[Band-aware Architectures]
-    A --> E[Data Balancing / Hard Negatives]
-```
-
-## 1. Neural AFP 的更强实践
-
-### Enhancing Neural Audio Fingerprint Robustness to Audio Degradation for Music Identification (2025)
-- arXiv: https://arxiv.org/abs/2506.22661
-
-关键信息：
-- 指出很多 neural AFP 工作对真实退化模拟不够真实
-- 系统比较 metric learning 方法
-- 发现自监督 triplet loss 变体在该任务中更优
-- 强调多个 positive samples 对不同 loss 的影响不同
-
-对本项目的启发：
-- 不应只依赖当前简单 SupCon + CE
-- 应增加更真实的退化增强
-- 应明确做 retrieval 指标选择，而非只看分类头
-
-## 2. Music Foundation Model Backbones
-
-### Robust Neural Audio Fingerprinting using Music Foundation Models (2025)
-- arXiv: https://arxiv.org/abs/2511.05399
-
-关键信息：
-- 使用预训练 music foundation model（例如 MuQ、MERT）作为 neural fingerprinting backbone
-- 在 distorted / compressed / manipulated 音频条件下优于从零训练模型
-- 还能更好做 segment-level localization
-
-### MERT (2023)
-- arXiv: https://arxiv.org/abs/2306.00107
-
-关键信息：
-- 大规模自监督 music understanding 模型
-- 在多个 music understanding 任务上达到强表现
-
-### MuQ (2025)
-- arXiv: https://arxiv.org/abs/2501.01108
-
-关键信息：
-- 面向音乐的自监督表征学习模型
-- 使用 Mel-RVQ 目标
-- 在多种下游任务上优于更早工作
-
-对本项目的启发：
-- 2026 继续只用小模型从零训，不太可能是最佳路线
-- 更合理路线：
-  - 当前仓库保留轻量自训 baseline
-  - 下一阶段增加 MERT / MuQ frozen encoder 或 adapter fine-tune 版本
-
-## 3. Band-split / band-aware 结构
-
-### Music Source Separation with Band-split RNN (2022)
-- arXiv: https://arxiv.org/abs/2209.15174
-
-关键信息：
-- 显式把频谱切成多个频带再建模
-- 对音乐任务优于直接照搬通用音频结构
-
-虽然该文主要做 source separation，不是 ACR，但它对“音乐频带先验”很有启发。
-
-对本项目的启发：
-- 输入层加入 band-split 是合理工程方向
-- 未来可继续发展成：
-  - band-aware attention
-  - multi-band retrieval heads
-  - harmonic/rhythm 双塔结构
-
-## 4. 数据平衡与生成增强
-
-### BAGAN: Data Augmentation with Balancing GAN (2018)
-- arXiv: https://arxiv.org/abs/1803.09655
-
-严格说你提到的 `pro-WGAN` 我这次没有找到一个明确、权威、在该任务里广泛标准化的同名主文献；当前更接近、且有明确权威来源的是 **BAGAN / balancing GAN** 这一类面向不平衡数据增强的方法。
-
-因此本次实现里我采用的是：
-- **pro-WGAN 风格的工程近似平衡策略**
-- 不是声称已经复现某篇明确的 `pro-WGAN` SOTA 论文
-
-如果你之后指定了准确论文或仓库，我可以按那一版精确对齐实现。
-
-### 对当前实验结果的解释
-
-| 策略 | overall top1 | humming_like top1 | confused top1 | 结论 |
-|---|---:|---:|---:|---|
-| naive oversampling (smoke-v4) | 0.40 | 0.00 | 0.00 | 明显退化 |
-| type-aware weighting (smoke-v5) | 0.60 | 0.50 | 0.00 | 改善 humming，但 confused 无突破 |
-| sample-level confused-priority weighting (smoke-v6) | 0.65 | 0.25 | 0.25 | confused 突破，但需要重新平衡 humming |
-
-这说明：
-1. 2026 年这个方向里，**“难例重要”是对的**
-2. 但 **单维度加权还不够**，需要把不同 hard case 分开建模
-3. 对音乐 ACR 来说，`confused` 与 `humming_like` 不是同一种难度来源：
-   - `confused` 更偏 timbre / arrangement / retrieval ambiguity
-   - `humming_like` 更偏 melody / pitch contour mismatch
-4. 当前仓库里的 residual confused failure 进一步显示：
-   - `intro` 片段是更高风险区域
-   - 下一步应引入 `segment_type-aware hard negatives`
-   - 这比继续全局调 sample ratio 更接近工业有效路径
-
-## 5. 2026 年是否已经有更好的方案？
-
-有，结论是：**有明显更好的路线**。
-
-最值得参考的是：
-1. 用 **music foundation model** 做 backbone
-2. 用 **更真实退化模拟 + retrieval-first metric learning**
-3. 用 **segment-level / window-level indexing**，而不是整曲平均 embedding
-4. 对哼唱任务增加 **melody/pitch contour 专门支路**
-
-## 6. 对本项目的建议排序
-
-### 当前阶段（已开始）
-- 128 Mel 替换低维说话人风格输入
-- band-split 输入层
-- 更强混淆增强
-- retrieval-first 评测
-
-### 下一阶段
-- MERT / MuQ frozen feature baseline
-- triplet / multi-positive metric learning 对比 SupCon
-- window-level index aggregation
-- FMA / Jamendo 小规模真实数据验证
-- confusion-aware negative mining
-- humming 专门旋律支路 / pitch contour rerank
-
-### 更后阶段
-- humming 专门 melody tower
-- foundation model + lightweight fingerprint head
-- ANN + reranker 两阶段工业化检索
-
-## Sources
-- Araz et al., 2025, Enhancing Neural Audio Fingerprint Robustness to Audio Degradation for Music Identification: https://arxiv.org/abs/2506.22661
-- Singh et al., 2025, Robust Neural Audio Fingerprinting using Music Foundation Models: https://arxiv.org/abs/2511.05399
-- Li et al., 2023, MERT: Acoustic Music Understanding Model with Large-Scale Self-supervised Training: https://arxiv.org/abs/2306.00107
-- Zhu et al., 2025, MuQ: Self-Supervised Music Representation Learning with Mel Residual Vector Quantization: https://arxiv.org/abs/2501.01108
-- Luo & Yu, 2022, Music Source Separation with Band-split RNN: https://arxiv.org/abs/2209.15174
-- Mariani et al., 2018, BAGAN: Data Augmentation with Balancing GAN: https://arxiv.org/abs/1803.09655

-# Training Data, Input Format, and pgvector Guide / 训练数据、输入格式与 pgvector 指南
-
-> 更新：2026-06-02  
-> 关联文档：[数据规范](./dataset-spec.md) · [开放数据工作流](./open-dataset-workflow.md) · [数据来源与接入](./dataset-sources-and-licensing.md) · [服务接口](./service-api.md) · [业务素材类型与 Bucket 指南](./business-music-bucket-and-type-guide.md) · [业务 Manifest 与 Type-Role 规范](./business-manifest-and-type-role-spec.md)
-
-## 一页结论
-
-围绕你最新问的几个问题，可以压缩成 5 句话：
-
-1. **当前训练输入的最小单位是“带 `song_id` 的 query 样本 + reference 资产 + manifest”**，不是直接把 3 分钟 mp3 整批扔进模型。
-2. **3 分钟 mp3 当前在训练端通常不是预切全量重叠窗口，而是运行时随机裁 5s；检索端才是重叠滑窗。**
-3. **如果有 GPU，FMA 这类真实数据训练会明显加速；当前 `train.py` 支持 `auto/cuda`，`smoke-local` 也已支持 `--device cpu|cuda|auto`，其中 `auto` 会在 smoke 内部解析成实际设备。**
-4. **FMA、MTG-Jamendo、自有 BGM/录音都应先变成统一 manifest，再做训练、评测和 pgvector 入库。**
-5. **后续你们要扩自己的数据集时，最重要的不是文件后缀，而是 `song_id / type / offset / source_dataset / split` 这些结构化字段。**
-
----
-
-## 1. 总体结构图
-
-```mermaid
-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 当前切片策略图
-
-```mermaid
-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 推荐分工图
-
-```mermaid
-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 你们自己扩数据集时的最小规则
-
-1. **一首歌必须有稳定 `song_id`**。
-2. **完整版本或主版本优先做 `reference`**。
-3. **query 一定要能回溯到 reference 的时间位置**，因此最好保留 `offset`。
-4. **不同来源必须保留 `source_dataset`**。
-5. **训练、验证、测试必须保留 `split` 语义**，不要后面再靠文件夹猜。
-
----
-
-## 5. FMA / MTG / 自有数据的目录规范
-
-## 5.1 推荐目录图
-
-```mermaid
-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](../acr-engine/src/data/external_adapters.py) `check-local-ready`
-- [acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) `inspect-local`
-
----
-
-## 6.2 FMA cookbook
-
-```bash
-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
-```
-
-如果只是验证全链路：
-
-```bash
-/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](../acr-engine/src/data/manifest_tools.py) | 音频目录 -> manifest |
-| [acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py) | inspect / prepare / validate / smoke 统一入口 |
-| [acr-engine/src/data/dataset.py](../acr-engine/src/data/dataset.py) | 训练/测试数据集读取与随机裁剪 |
-| [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py) | 通用音频处理与滑窗 |
-| [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py) | embedding 抽取与 reference 滑窗索引 |
-| [acr-engine/train.py](../acr-engine/train.py) | 训练主入口 |
-| [acr-engine/evaluate.py](../acr-engine/evaluate.py) | 评测主入口 |
-| [acr-engine/run_demo.py](../acr-engine/run_demo.py) | build-index / query demo |
-| [acr-engine/scripts/export_manifest_to_pgvector_json.py](../acr-engine/scripts/export_manifest_to_pgvector_json.py) | manifest 导出为 pgvector-ready JSON |
-| [acr-engine/scripts/pgvector_bulk_load_template.py](../acr-engine/scripts/pgvector_bulk_load_template.py) | PostgreSQL 批量导入模板 |
-| [acr-engine/sql/pgvector_schema.sql](../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|cuda|auto` |
-| `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 推荐数据模型
-
-```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)
-
----
-
-## 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. 给你们后续自建数据集的落地建议
-
-1. **完整曲库先做 reference 池**。
-2. **从 reference 池切出 clean query 作为第一层训练集**。
-3. **再做 augmented / confused / humming_like 三类增强 query**。
-4. **固定一部分永不训练，只做 test set。**
-5. **先把 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 | 是 |
-
-推荐理解：
-
-1. **训练不是全部随机切**  
-   当前训练集可用 `random / silence_aware / high_energy / onset_aware / beat_aware / repeated_section_aware / hybrid`
-2. **reference 建库不是随机切**  
-   建库仍然是固定滑窗
-3. **外部数据 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`
-- 先把非静音、起音、拍点、重复段这些高收益候选打通
-- 暂时没有把更重的结构分段作为默认主流程
-
-原因：
-
-1. **ACR 查询不总是结构化片段**  
-   用户截到的可能是副歌，也可能是过门、录屏残片、短视频二创片段。
-2. **重结构分段更耗 CPU**  
-   对 FMA 这类真实开放集批量 prepare/smoke 不够轻。
-3. **训练仍需要随机性**  
-   纯结构分段会降低截取点分布的多样性。
-
-当前更合理的策略是：
-- `hybrid` 作为默认训练切片推荐
-- `beat_aware / repeated_section_aware` 作为偏音乐主段的强化选项
-- `random` 保留为泛化基线
-
-为什么不直接完全依赖音乐结构分段？
-
-- ACR 真实 query 往往来自短视频、录屏、随手截取，不一定对齐节拍或段落边界
-- 先做 **静音感知分段**，收益最大、风险最小
-- 更复杂的 beat / chorus / onset 分段可以作为下一阶段增强，而不应替代现有随机增强
-
-### 训练侧推荐
-
-```bash
-/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 生成推荐
-
-```bash
-/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. 如果你的目标是“识别原曲”
-
-```text
-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`
-
-这样你后面可以做两种策略：
-
-1. **作品级识别**
-   - 原曲和伴奏共享 `canonical_song_id`
-   - 但保留不同 `version_id`
-2. **版本级识别**
-   - 原曲和伴奏完全分开标签
-
-如果你现在主目标只是 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](../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`
-
-最短示例：
-
-```bash
-/usr/local/miniconda3/bin/python acr-engine/scripts/internal_asset_type_mapper.py assets.csv --output-dir out/internal_asset_map
-```
-
-如果你希望直接产出可训练 manifest：
-
-```bash
-/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 里是相对路径，推荐加上音频根目录：
-
-```bash
-/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，可直接导出：
-
-```bash
-/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
-```
-
-自动扩窗示例：
-
-```bash
-/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`
-
-如果你想临时把伴奏类也纳入导出，可用：
-
-```bash
-/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/dataset.py), [acr-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py), [acr-engine/src/data/external_adapters.py](../acr-engine/src/data/external_adapters.py), [acr-engine/src/utils/audio.py](../acr-engine/src/utils/audio.py), [acr-engine/src/engines/ecapa_embedder.py](../acr-engine/src/engines/ecapa_embedder.py), [acr-engine/train.py](../acr-engine/train.py)