Commit a549d1de a549d1de68fcc155b15a214b993157f3676db3b1 by cnb.bofCdSsphPA

Clarify the ACR evolution path and freeze a production-grade data model

Constraint: Phase-1 must support encoder-only open-source backbones without destabilizing future schema evolution
Rejected: extending the old flat song_id + fixed-vector schema | would couple model swaps to schema rewrites and weaken copyright lineage
Confidence: high
Scope-risk: moderate
Directive: treat canonical_song/work/recording/recording_asset/audio_window plus model/feature registries as the stable contract; evolve models and indexes around them
Tested: git diff --check on changed files; Python content/structure sanity check; architect review APPROVED; README link coverage and DDL object presence verified
Not-tested: live PostgreSQL apply not run because psql is unavailable in this environment
1 parent 2898ef26
## 2026-06-04
- 重构文档主阅读路径,新增按角色划分的文档入口:架构、开发、运维、模型底座。
- 新增 [SOTA 演进方案说明](./sota-evolution-guide.md),明确 Phase-1 encoder-only 路线、MERT/MuQ 角色与后续 version/cover 演进。
- 重写 [ACR 系统蓝图](./acr-architecture.md),补充角色视图、离线/在线职责分工与当前实现到目标实现的映射。
- 新增 [PostgreSQL 数据模型与 DDL 设计说明](./postgresql-data-model.md),补充设计意图、解决的问题、流程图与实施顺序。
- 新增 `acr-engine/sql/acr_pg_schema_v2.sql`,提供面向 `canonical_song/work/recording/asset/window + model_registry/feature_set_registry` 的推荐版 PostgreSQL DDL。
- 根据 architect 复核意见补充:`recording_asset` 术语统一、reference set 版本化对象、候选枚举约束、以及关键 lineage trigger 设计。
- 新增 `acr-engine/scripts/export_workspace_music20_embeddings_jsonl.py``acr-engine/scripts/evaluate_songid_pgvector_path.py`,补齐 song_id 级 pgvector 评测脚手架。
- 新增 `acr-engine/data/pgvector_eval/music20/` 评测产物,当前 `faiss-as-pgvector-standin` 结果:整体 `top1=0.9091``top3=0.9545`;其中 `query_type=1` 很强(`top1=1.0`),`query_type=7` 仍明显偏弱(`top1=0.0``top3=0.5`)。
- 新增 `acr-engine/data/local_eval/voice_workspace20_type7_eval.json`,对当前 `workspace_music20` 语义做了 20 条 `type_7` 批量验证:`top1=0.0``top3=0.05`,说明业务 song_id 正确性仍明显不足。
......
# ACR Docs Overview
> 保留最新架构与最短落地入口。历史细节仍在仓库中,但默认阅读只保留下面 6 份主文档
> 面向“版权保护 / 听歌识曲 / 版本归属”的音乐 ACR 文档入口。默认先看主路径,历史细节文档作为补充材料保留
## 最短阅读顺序
## 一页结论
1. [session-handoff.md](./session-handoff.md)
2. [CHANGELOG.md](./CHANGELOG.md)
当前项目已经从“原型是否能跑通”转向“**如何把 100w 音频 / 30w 歌曲做成可演进的版权检索系统**”。
默认阅读顺序不再按“训练脚本 -> demo”,而按:
1. **系统蓝图**:当前系统是什么、未来要演进成什么
2. **SOTA 演进**:Phase-1 不微调底座时怎么做,后面如何升级
3. **PostgreSQL 数据模型**:资产、窗口、特征、索引、匹配结果如何落盘
4. **现有实现对照**:当前仓库代码和文档分别在哪
---
## 主阅读路径(推荐)
### 1. 管理 / 架构 / 跨团队负责人
1. [acr-architecture.md](./acr-architecture.md)
2. [sota-evolution-guide.md](./sota-evolution-guide.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [session-handoff.md](./session-handoff.md)
### 2. 开发 / 数据 / 检索工程师
1. [postgresql-data-model.md](./postgresql-data-model.md)
2. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
3. [acr-architecture.md](./acr-architecture.md)
4. [dataset-spec.md](./dataset-spec.md)
5. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
6. [runbook.md](./runbook.md)
4. [runbook.md](./runbook.md)
### 3. 运维 / 平台 / 服务工程师
1. [acr-architecture.md](./acr-architecture.md)
2. [postgresql-data-model.md](./postgresql-data-model.md)
3. [service-api.md](./service-api.md)
4. [runbook.md](./runbook.md)
### 4. 模型 / 底座 / 研究工程师
1. [sota-research-2026.md](./sota-research-2026.md)
2. [sota-evolution-guide.md](./sota-evolution-guide.md)
3. [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
4. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
---
## 新的核心文档分工
| 文档 | 作用 | 适合谁先读 |
|---|---|---|
| [acr-architecture.md](./acr-architecture.md) | 当前系统蓝图、角色分工、在线/离线链路 | 架构、开发、运维 |
| [sota-evolution-guide.md](./sota-evolution-guide.md) | SOTA 演进路径、Phase-1 encoder-only 方案、后续升级路线 | 架构、模型、检索 |
| [postgresql-data-model.md](./postgresql-data-model.md) | PostgreSQL 数据字典、DDL 设计意图、流程图、查询路径 | 数据、后端、检索、平台 |
| [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md) | 当前训练/manifest/pgvector 原型链说明 | 开发、数据 |
| [session-handoff.md](./session-handoff.md) | 最新状态与续跑上下文 | 新 session 接手人 |
---
## 当前实现与未来目标的关系
```mermaid
flowchart LR
A[当前实现\nChromaprint + ECAPA + Melody Rerank] --> B[Phase-1\nEncoder-only Foundation Backbone]
B --> C[Phase-2\nVersion/Cover Lane + Better Aggregation]
C --> D[Phase-3\nIndustrial Retrieval + Reranker + Governance]
```
- **当前实现** 已验证基础链路可运行。
- **Phase-1** 目标是:不微调底座,直接上更强开源 encoder,并把 PostgreSQL 数据规范先落稳。
- **Phase-2** 目标是:增强 version / cover / hard-case 归属能力。
- **Phase-3** 目标是:多索引、多角色协作、数据治理、服务化上线。
---
## 当前推荐只看这几类
## 现有实现入口
### 1. 项目架构
- [acr-architecture.md](./acr-architecture.md)
- [session-handoff.md](./session-handoff.md)
### 代码入口
- `acr-engine/src/engines/chromaprint_matcher.py`
- `acr-engine/src/engines/ecapa_embedder.py`
- `acr-engine/src/engines/hybrid_engine.py`
- `acr-engine/src/service/app.py`
- `acr-engine/sql/pgvector_schema.sql`(原型版)
- `acr-engine/sql/acr_pg_schema_v2.sql`(本轮新增的推荐版)
### 2. 数据与评测
- [dataset-spec.md](./dataset-spec.md)
- [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
- [open-dataset-workflow.md](./open-dataset-workflow.md)
### 历史/补充文档
- [sota-research-2026.md](./sota-research-2026.md)
- [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
- [project-responsibility-map.md](./project-responsibility-map.md)
- [industrialization-roadmap.md](./industrialization-roadmap.md)
### 3. 运行与服务
- [runbook.md](./runbook.md)
- [service-api.md](./service-api.md)
---
### 4. 最新 hard-case 结论
- [acr-hard-case-analysis.md](../acr-engine/../docs/acr-hard-case-analysis.md)
## 如何理解当前文档体系
## 当前架构一句话
- **主文档**:优先保证“读完就知道怎么推进”
- **历史文档**:保留实验上下文、旧方案与补充解释
- **SQL 文件**:保证可以直接落地数据库原型
- `/workspace`:样本与素材来源
- `acr-engine/`:训练、索引、识别、服务主工程
- 本地小样本验证:优先 **FAISS**
- 生产向量检索:统一 **pgvector**
如果你只读 3 份:
1. [acr-architecture.md](./acr-architecture.md)
2. [sota-evolution-guide.md](./sota-evolution-guide.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
......
# ACR 系统架构图
# ACR 系统蓝图 / Architecture Blueprint
> 更新:2026-06-02
> 更新:2026-06-04
> 目标:把当前 ACR 原型、未来 SOTA 演进路径、以及不同角色的关注点统一到一份可读的系统蓝图里。
## 一页结论
- 识别链路已不是单一模型,而是 **指纹 + 向量 + melody-aware rerank** 的混合结构
- 数据与服务已经进入工业化演进阶段
- 当前主短板在:`humming_like``confused` 的 hard-case 精度
当前仓库已经验证了一个可运行的混合识别原型:
- `Chromaprint / fingerprint`:负责 exact / near-duplicate 快速召回
- `ECAPA-style embedding`:负责当前语义向量召回 baseline
- `melody-aware rerank`:负责弱旋律补强
但未来面向 **版权保护 + 100w 音频 / 30w 歌曲** 的目标,系统应演进为:
1. **数据规范稳定**`canonical_song -> work -> recording -> recording_asset -> audio_window`
2. **底座模型可替换**`model_registry -> feature_set_registry -> embedding/index`
3. **检索链分层**:exact lane + semantic lane + version/cover lane + aggregation
4. **服务与运维分离**:离线建库、在线召回、审核归一、监控治理分别有清晰职责
---
## 1. 总体架构
## 1. 总体系统
```mermaid
flowchart LR
Q[Query Audio] --> P[Preprocess]
P --> F1[Chromaprint Features]
P --> F2[128-Mel Features]
P --> F3[Melody Signature]
F1 --> M1[Fingerprint Matcher]
F2 --> M2[ECAPA + BandSplit Embedder]
F3 --> M3[Melody Similarity]
flowchart TD
A[Audio Sources\n官方母带 / 平台音频 / 抓取音频 / UGC / 录音] --> B[Asset Normalization]
B --> C[Canonical Data Model\nSong / Work / Recording / Asset / Window]
C[Catalog References] --> I1[Fingerprint Index]
C --> I2[Embedding Window Index]
C --> I3[Reference Melody Cache]
C --> D1[Exact Lane\nChromaprint / Neural AFP]
C --> D2[Semantic Lane\nFoundation Encoder]
C --> D3[Version/Cover Lane\nPhase-2+]
M1 --> H[Hybrid Fusion]
M2 --> H
M3 --> H
D1 --> E[Candidate Aggregation]
D2 --> E
D3 --> E
H --> O[Top-K + Reject]
E --> F[Canonical Song Decision]
F --> G[Service / Review / Audit]
```
---
## 2. 在线/离线分层图
## 2. 当前实现 vs 目标实现
| 维度 | 当前实现 | 目标实现 |
|---|---|---|
| 底座向量模型 | ECAPA-style baseline | MERT / MuQ 等 foundation encoder 为主 |
| 检索结构 | chromaprint + embedding + melody | exact + semantic + version/cover + rerank |
| 数据主键 | 以 `song_id` 为核心 | `canonical_song / work / recording / asset / window` 分层 |
| 存储形态 | 原型式 pgvector schema + 文件产物 | PostgreSQL 主数据 + 可替换向量/索引层 |
| 服务目标 | 验证闭环 | 版权保护 / 归属判断 / 工业化运维 |
---
## 3. 角色视图
## 3.1 产品 / 架构角色
关注:
- 版权保护是否能最终定位到 `canonical_song_id`
- `recording``work` 的区别是否明确
- 当前阶段是否坚持“先冻结规范、后迭代模型”
- 各团队之间接口是否清晰
最该读:
- 本文
- [sota-evolution-guide.md](./sota-evolution-guide.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
---
## 3.2 开发角色(后端 / 检索 / 数据)
关注:
- 如何把音频导入统一实体模型
- 如何切窗、建 feature_set、挂索引
- 如何从 query 走到候选,再归一到 `canonical_song_id`
- 如何支持未来切换 `model_name / model_version / feature_set`
最该读:
- 本文
- [postgresql-data-model.md](./postgresql-data-model.md)
- [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
---
## 3.3 运维 / 平台角色
关注:
- 离线任务:抽特征、建索引、重建索引
- 在线服务:召回、聚合、缓存、可观测性
- 存储分层:对象存储、PostgreSQL、索引后端
- 版本化:encoder 变更如何灰度、回滚、双写/双索引
最该读:
- 本文
- [service-api.md](./service-api.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
---
## 3.4 模型底座 / 研究角色
关注:
- Phase-1 先不用微调时,选哪个开源 encoder
- 如何定义 feature_set:窗长、hop、pooling、layer selection
- 未来如何从 encoder-only 升级到 version/cover lane
- 如何让新模型接入而不破坏数据层
最该读:
- [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)
---
## 4. 离线 / 在线职责拆分
```mermaid
flowchart TD
A[Offline Pipeline] --> A1[Dataset Prep]
A --> A2[Training]
A --> A3[Index Build]
A --> A4[Benchmark]
B[Online Service] --> B1[/health]
B --> B2[/recognize]
B --> B3[/index/build]
flowchart LR
A[Offline\n数据治理/切窗/特征抽取/建索引] --> B[Registered Artifacts\nfeature_set / index / metadata]
B --> C[Online\nquery encode / retrieve / aggregate / decide]
```
### 离线职责
- 资产标准化
- 元数据归一
- 切窗
- 模型特征抽取
- fingerprint / embedding 建索引
- 回填 PostgreSQL 元数据
### 在线职责
- 接收 query
- query 切块 / 编码
- exact / semantic / version lane 召回
- recording/work/song 聚合
- 输出 `canonical_song_id` + 证据
---
## 3. 关键模块表
## 5. 为什么必须把角色拆开
| 模块 | 输入 | 输出 | 作用 |
|---|---|---|---|
| Preprocess | wav | mel/chroma/f0 | 统一特征入口 |
| Fingerprint Matcher | query audio | chroma candidates | 快速召回 |
| ECAPA Embedder | mel | embeddings | 语义向量检索 |
| Melody Similarity | query/ref melody | melody score | 哼唱场景补强 |
| Hybrid Fusion | multi-scores | ranked candidates | 综合排序 |
| Service API | request | JSON result | 对外调用 |
因为这个项目已经不是单一模型脚本,而是:
1. **数据治理系统**:谁的音频、属于哪个 recording/work/song
2. **检索系统**:如何从 query 找到候选
3. **判定系统**:最终输出哪一个 `canonical_song_id`
4. **服务系统**:如何对外提供 API 与可观测性
5. **演进系统**:底座模型会变,但数据规范不能跟着乱变
---
## 4. 当前设计重点
## 6. 当前阶段建议
### 当前最重要的不是继续改训练,而是:
### 4.1 为什么是混合结构
纯指纹对哼唱弱,纯 embedding 对局部强匹配和解释性不足,因此使用混合结构更稳妥。
1. 先把 PostgreSQL 数据规范稳定下来
2. 先把 `model_registry / feature_set_registry` 结构打稳
3. Phase-1 用开源 encoder 直接做 semantic lane baseline
4. 保留当前 ECAPA 作为历史 baseline / 对照组
### 4.2 为什么加入 melody-aware
目前 hard-case 主要在哼唱/近旋律混淆,因此用 melody signature 做辅助排序。
### 当前系统中的保留项
- `Chromaprint`:保留
- `ECAPA baseline`:保留为对照组
- `melody rerank`:保留为补充 lane,不再作为主演进方向
### 4.3 为什么要 window-level index
整曲平均 embedding 会损失局部片段信息;window-level 更贴近 ACR 场景。
### 当前系统中的升级项
- semantic lane 主 encoder -> foundation model
- pgvector 原型 schema -> 可扩展 PostgreSQL 数据模型
- 扁平 song_id -> canonical/work/recording/recording_asset/audio_window
---
## 5. 细节附录
## 7. 与代码的映射
代码映射:
- `src/engines/chromaprint_matcher.py`
- `src/engines/ecapa_embedder.py`
- `src/engines/hybrid_engine.py`
- `src/service/app.py`
| 代码/文档 | 当前角色 |
|---|---|
| `acr-engine/src/engines/chromaprint_matcher.py` | exact lane 原型 |
| `acr-engine/src/engines/ecapa_embedder.py` | current embedding lane baseline |
| `acr-engine/src/engines/hybrid_engine.py` | current aggregation prototype |
| `acr-engine/sql/pgvector_schema.sql` | 早期 pgvector prototype |
| `acr-engine/sql/acr_pg_schema_v2.sql` | 推荐的 PostgreSQL V2 schema |
| [postgresql-data-model.md](./postgresql-data-model.md) | V2 schema 设计说明 |
---
## 8. 阅读建议
## Sources
- See `docs/references-and-sources.md` for the current source map.
如果你是:
- **架构负责人**:下一篇看 [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 演进方案说明 / SOTA Evolution Guide
> 更新:2026-06-04
> 目标:给出一个“先不上微调、先用开源 encoder”的 Phase-1 路线,并明确后续如何演进到更强的版权保护 / 版本归属系统。
## 一页结论
如果当前约束是:
- 先不微调底座
- 先要落数据规范
- 先解决 100w 音频 / 30w 歌曲的检索与归属基础问题
那么最合理的 Phase-1 路线不是“重训一套新模型”,而是:
1. **保留 exact lane**:Chromaprint / fingerprint
2. **semantic lane 主底座**:MERT-v1-95M
3. **semantic lane challenger**:MuQ
4. **数据库先稳住**`model_registry + feature_set_registry + audio_embedding + retrieval_index_registry`
5. **结果先按层聚合**:window -> recording -> work -> canonical_song
---
## 1. 为什么当前要走 encoder-only Phase-1
因为你当前最紧迫的问题不是“模型精度极限”,而是:
- 曲库很大:100w 音频 / 30w 歌曲
- 数据关系复杂:同曲可能有多录音、多版本、多来源资产
- 如果数据规范不稳,未来任何模型升级都会反复返工
所以 Phase-1 目标应该是:
```mermaid
flowchart LR
A[冻结数据规范] --> B[接入开源 encoder]
B --> C[建立 semantic baseline]
C --> D[做大规模索引与聚合验证]
D --> E[再决定是否进入微调 / version lane]
```
---
## 2. 推荐的阶段划分
## Phase-0:当前仓库阶段(已具备)
- `Chromaprint + ECAPA + melody rerank`
- 可跑通训练/建索引/评测/服务闭环
- 适合作为 baseline,而不是最终生产底座
## Phase-1:Encoder-only foundation baseline(当前推荐)
- exact lane:Chromaprint
- semantic lane:MERT-v1-95M
- challenger:MuQ
- 不微调底座
- 只做 feature extraction + index + aggregation
## Phase-2:Version / Cover lane
- 在 Phase-1 数据模型稳定后
- 引入 cover/version 专门分支
- 强化 work-level 归属
## Phase-3:Industrial retrieval stack
- ANN + reranker
- online/offline artifact registry
- 监控、回放、审计、人工复核
---
## 3. Phase-1 的推荐模型组合
## 3.1 Exact lane
### 选型
- Chromaprint / landmark hash
### 作用
- 原曲片段
- 平台转码
- near-duplicate
- 局部片段强匹配
### 为什么保留
版权保护不能只靠 semantic embedding。exact lane 在很多真实投诉/取证场景里仍然是最快且证据最强的第一条路径。
---
## 3.2 Semantic lane 主模型:MERT-v1-95M
### 推荐原因
- 是 music SSL foundation model
- 已有公开论文与实现
- 比自训小型 ECAPA 更符合音乐任务底座定位
- Phase-1 直接做 frozen encoder 成本与风险都更低
### Phase-1 中的角色
- 作为主 encoder 产出 window embedding
- 负责 noisy/BGM/一般跨域检索 baseline
- 后面可继续作为 teacher 或兼容旧索引版本
### 推荐 feature set
1. `mert_v1_95m__window_5s_hop_2.5s__meanpool__l2`
2. `mert_v1_95m__window_10s_hop_5s__meanpool__l2`
### 为什么先做两套
- `5s/2.5s`:更利于局部定位
- `10s/5s`:更利于整体语义稳定
---
## 3.3 Semantic lane Challenger:MuQ
### 推荐原因
- 更新、更接近下一代 music foundation model 路线
- 值得作为 challenger baseline
- 即使不开微调,也有希望在部分 MIR 任务上优于较早底座
### 当前建议
- Phase-1 先作为对照组,不立即替代 MERT
- 重点验证:向量分布稳定性、窗口级检索表现、内存/推理成本
---
## 3.4 为什么 Phase-1 不直接以 CoverHunter 为主线
因为 CoverHunter 的优势在:
- cover song identification
- alignment / refined attention / coarse-to-fine 训练
而你当前约束是:
- 先不用微调
- 先用开源 encoder
- 先把数据和检索规范落稳
所以它更适合作为 **Phase-2 的 version/cover lane 方向**,而不是 Phase-1 的主 baseline。
---
## 4. 角色关注点
## 4.1 模型底座角色
重点关注:
- 哪些 encoder 已注册到 `model_registry`
- 每个 encoder 的 input SR、window、pooling、embedding dim
- 哪些 feature set 是线上候选,哪些只是实验候选
## 4.2 检索角色
重点关注:
- 指纹 lane 与 semantic lane 如何组合
- `recording/work/song` 聚合规则
- top-k 候选如何稳定输出
## 4.3 数据角色
重点关注:
- 资产去重
- reference 资产选择
- window manifest
- 是否支持全量重建特征与索引
## 4.4 运维 / 平台角色
重点关注:
- encoder 版本切换是否可灰度
- 索引重建是否可并行
- 热/冷索引、历史索引是否可回滚
---
## 5. Phase-1 的实施顺序
```mermaid
flowchart TD
A[冻结 PostgreSQL 数据规范] --> B[导入 canonical/work/recording/asset/window]
B --> C[注册 model_registry / feature_set_registry]
C --> D[抽取 MERT 特征]
C --> E[抽取 MuQ 特征]
D --> F[构建 semantic index]
E --> F
F --> G[与 fingerprint lane 做聚合]
G --> H[输出 canonical_song_id / work_id / recording_id]
```
---
## 6. 每阶段解决的问题
| 阶段 | 解决的问题 | 暂不解决的问题 |
|---|---|---|
| Phase-1 | 数据规范、开源底座 baseline、索引可重建、song/work/recording 聚合 | 底座微调、cover 专项训练、melody tower |
| Phase-2 | version/cover 归属、work-level recall | 更复杂跨模态 humming |
| Phase-3 | 工业化服务、回放、监控、人工审核闭环 | 极致 research SOTA |
---
## 7. 与当前仓库的关系
### 当前保留
- `ECAPA baseline`:保留做对照,不作为长期主底座
- `Chromaprint`:保留,且在版权保护场景里非常重要
- `melody rerank`:保留为辅助 lane
### 当前新增
- `model_registry`
- `feature_set_registry`
- foundation encoder 特征抽取与注册
- 更清晰的 `canonical_song / work / recording` 数据结构
---
## 8. 当前推荐结论
如果今天就要给 Phase-1 定方案,我建议:
1. **先不改训练主线,不删 ECAPA**
2. **新增 MERT-v1-95M semantic lane**
3. **新增 MuQ challenger lane**
4. **只把 `is_reference=true` 的主参考窗口先做成热索引**
5. **先把 PostgreSQL 设计当成主交付**
换句话说:
> Phase-1 的核心不是“哪一个模型最终赢”,而是“数据规范 + 模型注册 + 特征注册 + 索引注册”这套长期结构先稳定下来。