ACR Docs Overview

面向“版权保护 / 听歌识曲 / 版本归属”的音乐 ACR 文档入口。默认先看主路径，历史细节文档作为补充材料保留。

最短启动路径（推荐）

如果下次启动的目标是：先判断当前 host 能不能继续推进 Phase-1，不要先手工翻很多文档，先直接跑：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/run_planner_validation_commands_live.py   --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2'   --output data/pgvector_eval/music20/planner_validation_commands_runner_report.json

当前这条命令的 fresh evidence 已有：

• executed_count = 4
• all_passed = true

它会一次性执行：

1. prereq_audit
2. worker_contract_smoke
3. semantic_vector_negative_matrix
4. asset_level_upsert_validation

如果结果仍是：

• downloads_root_exists = false
• ready_jobs = 0
• exact = failed/unreadable_audio_assets
• semantic = 4/4 failed

那么说明当前优先级应该是：

1. 解决 /workspace/downloads 挂载
2. 安装语义模型 runtime 依赖

而不是继续怀疑 PostgreSQL contract。

一页结论

当前项目已经从“原型是否能跑通”转向“如何把 100w 音频 / 30w 歌曲做成可演进的版权检索系统”。 默认阅读顺序不再按“训练脚本 -> demo”，而按：

1. 系统蓝图：当前系统是什么、未来要演进成什么
2. SOTA 演进：Phase-1 不微调底座时怎么做，后面如何升级
3. PostgreSQL 数据模型：资产、窗口、特征、索引、匹配结果如何落盘
4. 现有实现对照：当前仓库代码和文档分别在哪

---

主阅读路径（推荐）

1. 管理 / 架构 / 跨团队负责人

1. acr-architecture.md
2. sota-evolution-guide.md
3. postgresql-data-model.md
4. phase1-implementation-checklist.md
5. session-handoff.md

2. 开发 / 数据 / 检索工程师

1. postgresql-data-model.md
2. phase1-implementation-checklist.md
3. model-feature-registry-bootstrap.md
4. training-data-and-pgvector-guide.md
5. acr-architecture.md
6. runbook.md

3. 运维 / 平台 / 服务工程师

1. acr-architecture.md
2. postgresql-data-model.md
3. phase1-implementation-checklist.md
4. service-api.md
5. runbook.md

4. 模型 / 底座 / 研究工程师

1. sota-research-2026.md
2. sota-evolution-guide.md
3. model-feature-registry-bootstrap.md
4. production-encoder-freeze-and-embedding-strategy.md
5. training-data-and-pgvector-guide.md

---

新的核心文档分工

文档	作用	适合谁先读
acr-architecture.md	当前系统蓝图、角色分工、在线/离线链路	架构、开发、运维
sota-evolution-guide.md	SOTA 演进路径、Phase-1 encoder-only 方案、后续升级路线	架构、模型、检索
postgresql-data-model.md	PostgreSQL 数据字典、DDL 设计意图、流程图、查询路径	数据、后端、检索、平台
postgres_db_schema_samples.md	PostgreSQL 实际落库样例、live pgvector 测试链路、召回/混淆结果	数据、后端、检索、平台
phase1-implementation-checklist.md	Phase-1 落地 checklist，按阶段拆执行项	架构、开发、平台
model-feature-registry-bootstrap.md	模型、feature set、reference set 初始化手册	模型、检索、数据
training-data-and-pgvector-guide.md	当前训练/manifest/pgvector 原型链说明	开发、数据
session-handoff.md	最新状态与续跑上下文	新 session 接手人

---

当前实现与未来目标的关系

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 目标是：多索引、多角色协作、数据治理、服务化上线。

---

现有实现入口

代码入口

• 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（本轮新增的推荐版）

历史/补充文档

• sota-research-2026.md
• production-encoder-freeze-and-embedding-strategy.md
• project-responsibility-map.md
• industrialization-roadmap.md

---

如何理解当前文档体系

• 主文档：优先保证“读完就知道怎么推进”
• 历史文档：保留实验上下文、旧方案与补充解释
• SQL 文件：保证可以直接落地数据库原型

如果你只读 3 份：

1. acr-architecture.md
2. sota-evolution-guide.md
3. postgresql-data-model.md