ACR Docs Overview

面向“版权保护 / 听歌识曲 / 版本归属”的音乐 ACR 文档总入口。

---

0. 新同学先做什么

先跑，不要先读一堆文档

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

也可以用包装脚本：acr-engine/scripts/start_phase1_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'

当前 fresh evidence：

• executed_count = 4
• all_passed = true

再按这条阅读链路走

1. start-here.md
2. session-handoff.md
3. acr-architecture.md
4. postgresql-data-model.md
5. phase1-implementation-checklist.md

---

1. 文档总导航

A. 接手项目 / 恢复上下文

• start-here.md — 新同学 10 分钟接手入口
• session-handoff.md — 当前状态、阻塞、下一步
• CHANGELOG.md — 变更记录

B. 系统方案 / 设计主线

• acr-architecture.md — 总体架构与分层
• sota-evolution-guide.md — SOTA 演进路径
• postgresql-data-model.md — PostgreSQL 主数据/特征模型
• production-encoder-freeze-and-embedding-strategy.md — encoder-only 冻结策略

C. 第一个阶段怎么落地

• phase1-implementation-checklist.md — Phase-1 执行清单
• model-feature-registry-bootstrap.md — model/feature/reference set 初始化
• phase1-worker-contract.md — worker、job、失败语义合同
• postgres_db_schema_samples.md — PostgreSQL 存储样例

D. 运行 / 服务 / 数据治理

• runbook.md — 运维/运行手册
• service-api.md — 服务 API
• training-data-and-pgvector-guide.md — 训练/向量检索说明
• open-dataset-workflow.md — 开源数据接入流程

---

2. 按角色阅读

产品 / 业务 / 版权策略

1. start-here.md
2. acr-architecture.md
3. project-responsibility-map.md
4. business-export-cookbook.md

数据 / 平台 / PostgreSQL

1. postgresql-data-model.md
2. postgres_db_schema_samples.md
3. model-feature-registry-bootstrap.md
4. runbook.md

算法 / 检索 / 模型

1. sota-evolution-guide.md
2. production-encoder-freeze-and-embedding-strategy.md
3. phase1-worker-contract.md
4. sota-research-2026.md

开发 / 实施 / 交付

1. phase1-implementation-checklist.md
2. session-handoff.md
3. CHANGELOG.md
4. release-checklist.md

---

3. 当前最重要的稳定结论

• 目标场景不是普通歌曲推荐，而是 版权保护 / 听歌识曲 / 版本归属。
• Phase-1 先走 encoder-only 路线，不先微调底座。
• exact lane：Chromaprint。
• semantic baseline：MERT-v1-95M。
• semantic challenger：MuQ。
• ECAPA 保留为 historical baseline，不再作为长期主底座。
• PostgreSQL 主链固定为：

canonical_song -> work -> recording -> recording_asset -> audio_window

• 模型/特征主链固定为：

model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint -> retrieval_index_registry

---

4. 当前不要浪费时间的方向

• 不要回退到只用一个 song_id 的扁平结构。
• 不要把 embedding 存成固定列（如 mert_embedding / muq_embedding）。
• 不要在 Phase-1 先讨论重新训练底座。
• 不要把当前阻塞误判成 PostgreSQL schema 问题；当前主要 blocker 是音频挂载与 runtime 依赖。

---

5. 补充但不建议作为第一入口

以下文档保留用于专题补充，不建议新同学第一轮就读：

• dataset-spec.md
• dataset-sources-and-licensing.md
• references-and-sources.md
• current-capability-map.md
• industrialization-roadmap.md
• industrial-benchmark-spec.md
• benchmark-report-template.md
• model-card-template.md
• report-layout.md