Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 38b37e08 38b37e086d340ade289d9b15fd828001e1f346d9 by cnb.bofCdSsphPA
Options

Why the schema docs need one song-centric story, not parallel histories 

Constraint: New teammates must understand where slice/model/feature data lands without reading deprecated v2/planner-worker material
Rejected: Keep old docs with disclaimers | still leaves two competing mental models in the default docs path
Confidence: high
Scope-risk: narrow
Directive: Keep future docs anchored on the 4-table song-centric path unless the physical schema default truly changes
Tested: markdown link check on /workspace/docs; staged diff review; verified referenced wrapper script is present
Not-tested: No database or pipeline rerun was needed for this docs-only consolidation
1 parent 020702cc
Inline Side-by-side
Showing 13 changed files with 610 additions and 3715 deletions
#!/usr/bin/env bash
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PYTHON_BIN="${PYTHON_BIN:-/usr/local/miniconda3/bin/python}"
DSN="${1:-${PG_DSN:-}}"
SCHEMA="${2:-${PG_SCHEMA:-acr_songcentric_test}}"
INPUT_ROOT="${3:-$ROOT_DIR/data/songcentric_builder_smoke}"
OUTPUT_DIR="${4:-$ROOT_DIR/data/pgvector_eval/music20}"
if [[ -z "$DSN" ]]; then
echo "usage: $0 <postgres-dsn> [schema] [input-root] [output-dir]" >&2
echo "or set PG_DSN before running this script" >&2
exit 1
fi
cd "$ROOT_DIR/.."
"$PYTHON_BIN" acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
--dsn "$DSN" \
--schema "$SCHEMA" \
--input-root "${INPUT_ROOT#$ROOT_DIR/..\/}" \
--output-dir "${OUTPUT_DIR#$ROOT_DIR/..\/}"
# Changelog
## 2026-06-04
- 收敛 `docs/` 到当前 song-centric 主线，只保留 `README / start-here / session-handoff / postgresql-data-model / postgres_db_schema_samples / CHANGELOG` 六份核心文档，删除旧的 v2 / planner-worker / registry 扩展文档，避免新同学误入已退居次线的设计。
- 重写 `docs/postgresql-data-model.md`，明确 `保存切片的数据 + 模型 + feature` 的落表方案：`window` 落 `audio_object`，模型身份落 `feature_fact.model_name/model_version/feature_set_name`，具体 `fingerprint/embedding` 也统一落 `feature_fact`。
- 重写 `docs/postgres_db_schema_samples.md` 与入口文档，补充当前 4 表主链的流程图、典型 SQL 样例、查询回溯路径与写入顺序，统一文档口径到 `media_entity -> audio_object -> feature_fact -> set_membership`。
## 2026-06-04
- 新增 `acr-engine/scripts/start_songcentric_shortest_path.sh`，把当前默认主线再收敛成一条可直接复制执行的 shell 入口，并已用 fresh runner 结果再次验证。
- 将 `run_songcentric_directory_pipeline_live.py` 提升为当前默认主线入口，并把 fresh runner 结果同步到 `docs/README.md`、`docs/start-here.md`、`docs/session-handoff.md`，降低下次 session 的恢复成本。
......
# ACR Docs Overview
> 当前仅保留与 **song-centric + 融合优先** ACR 设计直接相关的文档。
> 当前 docs 只保留与 **song-centric + 4 表融合 schema** 直接相关的文档。
---
## 0. 新同学先做什么
## 1. 先看什么
如果当前要继续 song-centric 主线，先跑：
新同学接手顺序：
```bash
cd /workspace
/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_songcentric_test \
--input-root acr-engine/data/songcentric_builder_smoke \
--output-dir acr-engine/data/pgvector_eval/music20
```
如果要回归旧的 planner/worker 合同，再跑：
```bash
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](./start-here.md)
2. [session-handoff.md](./session-handoff.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
5. [CHANGELOG.md](./CHANGELOG.md)
---
## 1. 当前默认设计口径
## 2. 当前默认设计口径
当前 Phase-1 默认按下面理解：
逻辑语义：
```text
song -> asset -> window -> fingerprint / embedding
```
对应融合优先物理表：
物理落表：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
核心目标：
- 最终稳定返回 `song_id`
- 同一个 `song` 下允许多个音频文件
- `window` 是切片/evidence/召回最小单元
- `feature_fact` 同时承载 exact lane 与 semantic lane
- Phase-1 直接复用开源 encoder，不先训练/微调
---
## 2. 必读文档
## 3. 一键验证主链
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)
```bash
cd /workspace
/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_songcentric_test \
--input-root acr-engine/data/songcentric_builder_smoke \
--output-dir acr-engine/data/pgvector_eval/music20
```
---
包装脚本：
## 3. 实施相关文档
```bash
acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
```
- [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 演进主线
当前 fresh evidence：
- `song_count = 2`
- `asset_count = 2`
- `window_count = 5`
- `matcher_fingerprint_count = 5`
- `fallback_fingerprint_count = 0`
- `semantic_runtime_available = false`
- `import_counts.feature_fact = 24`
---
## 4. 当前稳定结论
## 4. 当前保留文档分别解决什么
- 最终归属对象当前只要求稳定返回 `song_id`
- 同一个 `song` 下允许有多个音频文件
- 当前暂不把 `recording/version` 作为必须返回对象
- `window` 仍然保留，因为它是 evidence / offset / 检索最小单元
- `feature_fact` 统一承载 `fingerprint` 和 `embedding`
- [start-here.md](./start-here.md)：新同学 10 分钟接手入口
- [session-handoff.md](./session-handoff.md)：下次启动从哪里继续
- [postgresql-data-model.md](./postgresql-data-model.md)：表设计、字段语义、流程图、设计取舍
- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)：DDL、样例数据、典型 SQL、导入查询链路
- [CHANGELOG.md](./CHANGELOG.md)：变更历史
---
## 5. 文档维护命令
```bash
/usr/local/miniconda3/bin/python scripts/check_markdown_links.py --root docs
/usr/local/miniconda3/bin/python /workspace/scripts/check_markdown_links.py --root /workspace/docs
```
默认会跳过 `CHANGELOG.md` 这类历史归档文档。
......
# ACR 系统蓝图 / Architecture Blueprint
> 更新：2026-06-04
> 目标：把当前 ACR 原型、未来 SOTA 演进路径、以及不同角色的关注点统一到一份可读的系统蓝图里。
## 一页结论
当前仓库已经验证了一个可运行的混合识别原型：
- `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. 总体系统图
```mermaid
flowchart TD
A[Audio Sources\n官方母带 / 平台音频 / 抓取音频 / UGC / 录音] --> B[Asset Normalization]
B --> C[Canonical Data Model\nSong / Work / Recording / Asset / Window]
C --> D1[Exact Lane\nChromaprint / Neural AFP]
C --> D2[Semantic Lane\nFoundation Encoder]
C --> D3[Version/Cover Lane\nPhase-2+]
D1 --> E[Candidate Aggregation]
D2 --> E
D3 --> E
E --> F[Canonical Song Decision]
F --> G[Service / Review / Audit]
```
---
## 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 主数据 + 可替换向量/索引层 |
| 服务目标 | 验证闭环 | 版权保护 / 归属判断 / 工业化运维 |
---
## 2.1 为什么现在会显得“层很多”
因为当前蓝图同时覆盖了 3 个维度：
1. **业务归属**：`song/work/recording`
2. **音频实体**：`asset/window`
3. **检索计算**：`feature/index/candidate/decision`
把这三类问题放在一张总图中，会看起来像一条很长的链。
但在工程上，它们其实是不同职责：
- 业务归属层回答：**最后该归谁**
- 音频实体层回答：**命中的是哪段音频**
- 检索计算层回答：**这段音频是怎么被召回出来的**
---
## 2.2 当前最小可用架构可以收敛到什么程度
如果当前阶段只追求：
> 快速稳定地把 query 命中到正确 `song_id`
那 Phase-1 完全可以按下面这套最小骨架推进：
```text
song -> asset -> window -> fingerprint / embedding
```
保留原因：
- `window` 不能删：它是 offset/evidence/多段投票的最小单元
- `feature_set_registry` / `feature_fact` 不能删：否则未来换 MERT/MuQ 会把 schema 写死
- `asset` 不能删：同一个 `song` 下会有多个真实音频文件
可以延后：
- `recording`
- `work`
- 更重的 `retrieval_index_registry`
- 更细的全链路审计表
因此推荐口径不是“把所有层都砍掉”，而是：
> **Phase-1 先上 song-centric 最小可用层；未来版本归属/cover/work 治理再继续加层。**
---
## 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)
---
## 3.3 运维 / 平台角色
关注：
- 离线任务：抽特征、建索引、重建索引
- 在线服务：召回、聚合、缓存、可观测性
- 存储分层：对象存储、PostgreSQL、索引后端
- 版本化：encoder 变更如何灰度、回滚、双写/双索引
最该读：
- 本文
- [postgresql-data-model.md](./postgresql-data-model.md)
- [phase1-worker-contract.md](./phase1-worker-contract.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)
- [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
---
## 4. 离线 / 在线职责拆分
```mermaid
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` + 证据
---
## 5. 为什么必须把角色拆开
因为这个项目已经不是单一模型脚本，而是：
1. **数据治理系统**：谁的音频、属于哪个 recording/work/song
2. **检索系统**：如何从 query 找到候选
3. **判定系统**：最终输出哪一个 `canonical_song_id`
4. **服务系统**：如何对外提供 API 与可观测性
5. **演进系统**：底座模型会变，但数据规范不能跟着乱变
---
## 6. 当前阶段建议
### 当前最重要的不是继续改训练，而是：
1. 先把 PostgreSQL 数据规范稳定下来
2. 先把 `model_registry / feature_set_registry` 结构打稳
3. Phase-1 用开源 encoder 直接做 semantic lane baseline
4. 保留当前 ECAPA 作为历史 baseline / 对照组
### 当前系统中的保留项
- `Chromaprint`：保留
- `ECAPA baseline`：保留为对照组
- `melody rerank`：保留为补充 lane，不再作为主演进方向
### 当前系统中的升级项
- semantic lane 主 encoder -> foundation model
- pgvector 原型 schema -> 可扩展 PostgreSQL 数据模型
- 扁平 song_id -> canonical/work/recording/recording_asset/audio_window
---
## 7. 与代码的映射
| 代码/文档 | 当前角色 |
|---|---|
| `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. 阅读建议
如果你是：
- **架构负责人**：下一篇看 [sota-evolution-guide.md](./sota-evolution-guide.md)
- **数据/后端负责人**：下一篇看 [postgresql-data-model.md](./postgresql-data-model.md)
- **模型负责人**：先看 [sota-evolution-guide.md](./sota-evolution-guide.md) 再看 [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
# 模型与 Feature Set 初始化手册 / Model & Feature Registry Bootstrap
> 更新：2026-06-04
> 目标：给出 Phase-1 里 `model_registry`、`feature_set_registry`、`reference_set_registry` 的初始化约定，避免每次接入新 encoder 时重新设计。
## 一页结论
Phase-1 不微调底座时，真正需要初始化的不是“训练任务”，而是三类对象：
1. **模型定义**：`model_registry`
2. **特征定义**：`feature_set_registry`
3. **reference 集定义**：`reference_set_registry`
也就是说，先把“你要怎么用模型”写清楚，再开始抽特征。
---
## 1. 推荐命名约定
## 1.1 model_name
推荐固定小写：
- `chromaprint`
- `mert`
- `muq`
- `ecapa`
- `coverhunter_encoder`（Phase-2+）
## 1.2 model_version
推荐表达清楚来源和规模：
- `v1-95m`
- `v1-330m`
- `large-msd-iter`
- `acr-baseline-v1`
## 1.3 feature set 命名
推荐格式：
```text
<model_name>__<feature_name>__<window>x<hop>__<pooling>__<metric>
```
示例：
- `mert__semantic_embedding__5s_2.5s__mean__cosine`
- `mert__semantic_embedding__10s_5s__mean__cosine`
- `muq__semantic_embedding__5s_2.5s__mean__cosine`
---
## 2. Phase-1 推荐初始化对象
## 2.1 模型清单
| model_name | model_version | 角色 |
|---|---|---|
| `chromaprint` | `v1` | exact lane |
| `mert` | `v1-95m` | semantic 主 baseline |
| `muq` | `large-msd-iter` | semantic challenger |
| `ecapa` | `acr-baseline-v1` | 历史 baseline / 对照 |
---
## 2.2 Feature set 清单
| feature_set | 目的 |
|---|---|
| `chromaprint asset-level` | exact 匹配 |
| `mert 5s/2.5s mean` | 主 semantic baseline |
| `mert 10s/5s mean` | 较长上下文验证 |
| `muq 5s/2.5s mean` | challenger baseline |
| `ecapa 5s/2.5s` | 历史对照 |
---
## 3. 推荐初始化 SQL
## 3.1 注册模型
```sql
insert into model_registry (
model_name, model_family, model_version, model_source, model_uri,
license_name, input_modality, input_sample_rate, input_channel_mode,
default_window_sec, default_hop_sec, output_embedding_dim,
pooling_supported, layer_selection_supported, is_trainable
) values
('chromaprint', 'fingerprint', 'v1', 'local', null,
null, 'audio', 16000, 'mono',
5.0, 2.5, null,
array['none'], false, false),
('mert', 'music_ssl', 'v1-95m', 'github', 'https://github.com/yizhilll/MERT',
null, 'audio', 24000, 'mono',
5.0, 2.5, 768,
array['mean','cls'], true, false),
('muq', 'music_ssl', 'large-msd-iter', 'github', 'https://github.com/tencent-ailab/MuQ',
null, 'audio', 24000, 'mono',
5.0, 2.5, 768,
array['mean','cls'], true, false),
('ecapa', 'speech_derived', 'acr-baseline-v1', 'local', null,
null, 'audio', 16000, 'mono',
5.0, 2.5, 192,
array['mean'], false, true);
```
---
## 3.2 注册 feature set
```sql
insert into feature_set_registry (
model_id, feature_name, feature_level, extraction_granularity,
window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
5.0, 2.5, 768, 'mean', 'final',
true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'mert' and model_version = 'v1-95m';
insert into feature_set_registry (
model_id, feature_name, feature_level, extraction_granularity,
window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
10.0, 5.0, 768, 'mean', 'final',
true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'mert' and model_version = 'v1-95m';
insert into feature_set_registry (
model_id, feature_name, feature_level, extraction_granularity,
window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
5.0, 2.5, 768, 'mean', 'final',
true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'muq' and model_version = 'large-msd-iter';
```
---
## 3.3 注册 reference set
```sql
insert into reference_set_registry (
set_name, description, encoder_scope, status
) values (
'phase1_hot_reference_v1',
'Phase-1 主 reference 集，仅包含当前线上热参考 recording',
'mert-v1-95m / muq-large-msd-iter',
'active'
);
```
---
## 4. reference set 的运营原则
### 当前建议
- 一个时间点只允许一个主 `active` hot reference set
- 新 encoder / 新聚合策略上线时，新建 set，不覆盖旧 set
- A/B 或 shadow 期间，允许多个 set 并存，但只有一个主线上标记
### 为什么
这样可以支持：
- 线上回滚
- encoder 升级
- 索引热切换
- 离线重放
---
## 5. 维度扩展规则
当前 DDL 只演示了：
- `audio_embedding_vector_192`
- `audio_embedding_vector_768`
后续如果接入新 encoder 维度，如 `1024`：
1. 新增 `audio_embedding_vector_1024`
2. 对应 feature_set 的 `embedding_dim=1024`
3. 独立建索引
4. 通过 `retrieval_index_registry` 切换
### 原则
- 维度变化是 feature set 升级，不是主数据模型升级
- 主数据层不该因 encoder 升级而改表
---
## 6. 当前推荐顺序
```mermaid
flowchart TD
A[注册 model_registry] --> B[注册 feature_set_registry]
B --> C[注册 reference_set_registry]
C --> D[抽取 embeddings/fingerprint]
D --> E[写 audio_embedding/audio_fingerprint]
E --> F[建 retrieval_index_registry]
```
---
## 7. 最后建议
如果你今天就开始做 Phase-1 初始化，建议最少先注册：
1. `chromaprint v1`
2. `mert v1-95m`
3. `muq large-msd-iter`
4. `mert 5s/2.5s mean`
5. `muq 5s/2.5s mean`
6. `phase1_hot_reference_v1`
这样数据、模型、索引三条线就都有了稳定入口。
---
## 10. Phase-1 worker contract（新增执行层）
当前已经不只是 registry/bootstrap 了，还补上了最小真实 worker 执行面：
- `acr-engine/scripts/bootstrap_phase1_reference_members_live.py`
- `acr-engine/workers/mark_job_status.py`
- `acr-engine/workers/run_chromaprint_job.py`
- `acr-engine/workers/run_embedding_job.py`
这层的作用不是立即跑完真实抽特征，而是先把下面这条链打通：
```text
planner -> feature_extraction_job -> worker -> PostgreSQL status update
```
### 当前能力
1. 读取 `feature_extraction_job`
2. 联表解析 `feature_set_registry + model_registry`
3. 解析 `target_scope`
4. 回写 `pending -> running -> completed`
5. 为后续真模型推理保留稳定契约
### 推荐阅读
详细契约与流程图见：
- [docs/phase1-worker-contract.md](./phase1-worker-contract.md)
---
## 8. live PostgreSQL bootstrap 脚本
为了避免每次手工执行 SQL，本仓库现在提供了一个可直接连 PostgreSQL 的 live bootstrap 脚本：
- `acr-engine/scripts/bootstrap_phase1_model_registry_live.py`
用途：
- 向目标 schema 写入 `model_registry`
- 写入 `feature_set_registry`
- 写入 `reference_set_registry`
- 采用 **幂等式 upsert / ensure** 方式，适合重复执行
### 8.1 执行命令
```bash
cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/bootstrap_phase1_model_registry_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_test \
--output data/pgvector_eval/music20/phase1_registry_bootstrap_report.json
```
### 8.2 当前已验证结果（acr_test）
本轮已在 `acr_test` schema 上真实执行，写入结果如下：
| 对象 | 数量 |
|---|---:|
| `model_registry` | `5` |
| `feature_set_registry` | `6` |
| `reference_set_registry` | `2` |
其中新增的 Phase-1 对象包含：
#### models
- `chromaprint v1`
- `mert v1-95m`
- `muq large-msd-iter`
- `ecapa acr-baseline-v1`
#### feature sets
- `chromaprint fingerprint_asset`
- `mert semantic_embedding 5s/2.5s`
- `mert semantic_embedding 10s/5s`
- `muq semantic_embedding 5s/2.5s`
- `ecapa semantic_embedding 5s/2.5s`
#### reference set
- `phase1_hot_reference_v1`
### 8.3 当前产物
- `acr-engine/data/pgvector_eval/music20/phase1_registry_bootstrap_report.json`
- `acr-engine/data/pgvector_eval/music20/phase1_registry_bootstrap_idempotency_report.json`
这个文件已经记录了：
- model_id
- feature_set_id
- reference_set_id
- 最终表计数
因此，下次 session 不需要再从 SQL 片段手工执行开始，而可以直接从 live bootstrap 脚本接上。
### 8.4 幂等性验证（已做）
同一套命令在 `acr_test` schema 上连续执行两次后，已经拿到真实幂等性证据：
| 项目 | 第 1 次 | 第 2 次 |
|---|---:|---:|
| `model_registry` | `5` | `5` |
| `feature_set_registry` | `6` | `6` |
| `reference_set_registry` | `2` | `2` |
第二次执行时：
- `models` 全部表现为 `updated`
- `feature_sets` 全部表现为 `reused`
- `reference_set` 表现为 `updated`
结论：
> 当前 bootstrap 脚本可重复执行，不会把 Phase-1 registry 数据重复灌爆。
---
## 9. Phase-1 extraction job bootstrap
当 `model_registry / feature_set_registry / reference_set_registry` 都已经存在后，下一步不是立刻手工跑抽特征，而是先把 **待执行 job** 写到 `feature_extraction_job`。
本仓库现在已经提供：
- `acr-engine/scripts/bootstrap_phase1_extraction_jobs_live.py`
用途：
- 根据已存在的 `feature_set_registry`
- 为 `phase1_hot_reference_v1` 生成待执行 extraction jobs
- 把 Phase-1 的 exact / semantic lanes 统一放进 PostgreSQL job 表
### 9.1 执行命令
```bash
cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/bootstrap_phase1_extraction_jobs_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_test \
--output data/pgvector_eval/music20/phase1_extraction_jobs_report.json
```
### 9.2 当前已验证结果（acr_test）
本轮已真实创建 5 条待执行 job：
| lane | model | feature | target_scope | status |
|---|---|---|---|---|
| exact | `chromaprint` | `fingerprint_asset` | `reference_set:phase1_hot_reference_v1` | `pending` |
| semantic | `mert` | `semantic_embedding` 5s/2.5s | `reference_set:phase1_hot_reference_v1` | `pending` |
| semantic | `mert` | `semantic_embedding` 10s/5s | `reference_set:phase1_hot_reference_v1` | `pending` |
| semantic | `muq` | `semantic_embedding` 5s/2.5s | `reference_set:phase1_hot_reference_v1` | `pending` |
| semantic | `ecapa` | `semantic_embedding` 5s/2.5s | `reference_set:phase1_hot_reference_v1` | `pending` |
对应 live 报告：
- `acr-engine/data/pgvector_eval/music20/phase1_extraction_jobs_report.json`
这意味着：
> 现在 PostgreSQL 里已经不只是“模型定义”和“特征定义”，而是连 **下一步该跑哪些抽特征任务** 都已经具备结构化入口了。
---
## 10. Phase-1 extraction plan（从 pending jobs 生成）
当 `feature_extraction_job` 已经存在后，下一步通常不是马上手敲命令，而是先从 PostgreSQL 生成一个**统一执行计划**。
本仓库现在已经提供：
- `acr-engine/scripts/plan_phase1_extraction_jobs_live.py`
用途：
- 读取 `feature_extraction_job`
- 过滤 `job_status=pending`
- 联表 `feature_set_registry + model_registry`
- 生成按 lane / priority 排序的 execution plan
### 10.1 执行命令
```bash
cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/plan_phase1_extraction_jobs_live.py \
--dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
--schema acr_test \
--job-status pending \
--output data/pgvector_eval/music20/phase1_extraction_plan_report.json
```
### 10.2 当前已验证结果（acr_test）
本轮已真实生成一份 ordered execution plan：
| order | lane | model | feature | physical_target |
|---|---|---|---|---|
| 1 | `exact` | `chromaprint` | `fingerprint_asset` | `audio_fingerprint` |
| 2 | `semantic` | `mert` | `semantic_embedding 5s/2.5s` | `audio_embedding` |
| 3 | `semantic` | `mert` | `semantic_embedding 10s/5s` | `audio_embedding` |
| 4 | `semantic` | `muq` | `semantic_embedding 5s/2.5s` | `audio_embedding` |
| 5 | `semantic` | `ecapa` | `semantic_embedding 5s/2.5s` | `audio_embedding` |
其中 planner 还会自动给出：
- `vector_table`
- `audio_embedding_vector_768`
- `audio_embedding_vector_192`
- `target_scope`
- `execution_notes`
当前产物：
- `acr-engine/data/pgvector_eval/music20/phase1_extraction_plan_report.json`
结论：
> 现在 PostgreSQL 里已经不仅能描述“有哪些 job”，还可以直接生成**按执行顺序排好的抽特征计划**。
### 10.3 ready-to-run command suggestions（已补齐）
本轮又进一步把 planner 升级为：**每条 job 都生成 command suggestion**。
示例：
#### exact lane
```bash
cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" EXTRACTION_JOB_ID=1 FEATURE_SET_ID=2 TARGET_SCOPE='reference_set:phase1_hot_reference_v1' PG_SCHEMA=acr_test OUTPUT_TARGET=audio_fingerprint \
/usr/local/miniconda3/bin/python workers/run_chromaprint_job.py --complete-dry-run
```
#### semantic lane
```bash
cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" EXTRACTION_JOB_ID=2 FEATURE_SET_ID=3 TARGET_SCOPE='reference_set:phase1_hot_reference_v1' PG_SCHEMA=acr_test MODEL_NAME=mert MODEL_VERSION=v1-95m VECTOR_TABLE=audio_embedding_vector_768 OUTPUT_TARGET=audio_embedding \
/usr/local/miniconda3/bin/python workers/run_embedding_job.py --complete-dry-run
```
这意味着下个 session 不需要先手工拼环境变量和 job 绑定关系，而可以直接从 planner 报告里复制命令模板。
### 10.4 planner 现在也会附带 validation commands
除了 per-job command suggestion，当前 planner 还会输出一组全局验证入口：
- `prereq_audit`
- `worker_contract_smoke`
- `semantic_vector_negative_matrix`
- `asset_level_upsert_validation`
也就是：
1. 先审计 host 前置条件
2. 再跑 exact+semantic 的 contract smoke
3. 再检查 semantic vector-table 负例是否稳定
4. 再验证 asset-level upsert contract
这让 planner 从“只会排任务”升级成“同时给出执行前检查入口”的交付物。
### 10.5 planner validation_commands 已做直接消费验证
本轮继续补了一层 fresh evidence：不是只看 planner JSON 里有命令，而是**直接从 `phase1_extraction_plan_report.json` 读取命令后执行**。
对应产物：
- `acr-engine/data/pgvector_eval/music20/phase1_validation_commands_execution_report.json`
当前已验证：
- `validation_commands.prereq_audit` -> `returncode = 0`
- `validation_commands.worker_contract_smoke` -> `returncode = 0`
- `validation_commands.semantic_vector_negative_matrix` -> `returncode = 0`
- `validation_commands.asset_level_upsert_validation` -> `returncode = 0`
当前 `phase1_validation_commands_execution_report.json` 已经达到：
- `executed_commands = 4`
- `all_passed = true`
这说明 planner 报告现在不仅能“展示命令”，还可以被脚本化消费为真正的执行入口。
# Phase-1 实施清单 / Encoder-only Implementation Checklist
> 更新：2026-06-04
> 目标：把“先不上微调、先用开源 encoder”的 Phase-1 方案拆成可执行步骤，方便数据、检索、平台、运维团队并行推进。
## 一页结论
Phase-1 的交付目标不是“证明某个新模型绝对最优”，而是：
1. 把 **PostgreSQL 主数据模型** 落稳
2. 把 **reference 资产 / window / feature_set** 跑通
3. 用 **MERT + MuQ** 建立 encoder-only baseline
4. 把 **fingerprint lane + semantic lane** 的聚合链先跑通
5. 给 Phase-2 的 version/cover lane 留好接口
---
## 1. 交付范围
### 本阶段必须完成
- `canonical_song / work / recording / recording_asset / audio_window` 入库
- `model_registry / feature_set_registry` 初始化
- MERT/MuQ encoder-only 特征抽取
- hot reference set 建设
- semantic index 建设
- query -> candidate -> canonical_song 的基础闭环
### 本阶段不强求完成
- 底座微调
- cover 专项训练
- humming 专项 melody tower
- 全量冷数据统一进热索引
---
## 2. 角色分工
| 角色 | 主要交付 |
|---|---|
| 数据工程 | 资产清洗、去重、实体映射、切窗清单 |
| 后端/DBA | PostgreSQL DDL、索引、写入链、校验约束 |
| 检索工程 | fingerprint lane、semantic lane、聚合逻辑 |
| 模型工程 | MERT/MuQ 接入、feature_set 设计、抽特征脚本 |
| 平台/运维 | 离线任务编排、对象存储、热/冷索引治理 |
---
## 3. 分阶段 checklist
## Stage 1：主数据落库
### 目标
把业务事实层稳定下来，不依赖具体 encoder。
### Checklist
- [ ] 建库执行 `acr-engine/sql/acr_pg_schema_v2.sql`
- [ ] 初始化 `canonical_song`
- [ ] 初始化 `work`
- [ ] 初始化 `recording`
- [ ] 初始化 `recording_asset`
- [ ] 校验 lineage trigger 可用
- [ ] 用一小批 reference 数据做插入烟测
### 输出物
- PostgreSQL schema v2
- 初始实体数据
- 可复用的数据导入脚本
---
## Stage 2：reference 资产与切窗
### 目标
把“可被检索”的 reference 集合建出来。
### Checklist
- [ ] 选出 `is_reference=true` 的 recording
- [ ] 创建 `reference_set_registry`
- [ ] 回填 `reference_set_member`
- [ ] 统一标准化音频路径
- [ ] 生成 `audio_window`
- [ ] 标记 `active_for_index`
### 推荐规则
- 先只放主 reference 版本
- 默认先做 `5s / 2.5s hop`
- intro/outro 可先保留，后续再做 quality pruning
---
## Stage 3：模型与 feature_set 初始化
### 目标
把模型注册和特征版本定义稳定下来。
### Checklist
- [ ] 注册 `chromaprint`
- [ ] 注册 `mert v1-95m`
- [ ] 注册 `muq`
- [ ] 注册 `mert 5s/2.5s mean pool`
- [ ] 注册 `mert 10s/5s mean pool`
- [ ] 注册 `muq 5s/2.5s mean pool`
- [ ] 明确每个 feature_set 的 metric / quantization / dim
### 输出物
- `model_registry` 初始化数据
- `feature_set_registry` 初始化数据
- feature set 命名约定
---
## Stage 4：encoder-only 抽特征
### 目标
先不上训练，直接把 reference 集变成可检索 embedding。
### Checklist
- [ ] 抽取 MERT window embeddings
- [ ] 抽取 MuQ window embeddings
- [ ] 写入 `audio_embedding`
- [ ] 热数据写入 `audio_embedding_vector_768` 或对应物理表
- [ ] 冷数据落对象存储/parquet
- [ ] 回填 `is_indexed`
### 验证
- [ ] 随机抽样检查 `window -> embedding -> feature_set` 回链可用
- [ ] 检查向量 norm/缺失率/重复率
---
## Stage 5：索引与召回
### 目标
跑通 semantic lane 与 exact lane 的双路召回。
### Checklist
- [ ] 建 fingerprint index
- [ ] 建 semantic index
- [ ] 回填 `retrieval_index_registry`
- [ ] 做 query encode
- [ ] 返回 `retrieval_candidate`
- [ ] 聚合到 `recording / work / canonical_song`
- [ ] 跑 `phase1_prereq_audit`
- [ ] 跑 `phase1_worker_contract_smoke`
- [ ] 跑 `semantic_vector_negative_matrix`
- [ ] 跑 `asset_level_upsert_validation`
### 第一版聚合建议
- max score
- top-k average
- hit windows count
- exact lane / semantic lane agreement bonus
---
## Stage 6：基础评测与上线门禁
### 目标
先证明 Phase-1 结构可用。
### Checklist
- [ ] exact query bucket
- [ ] noisy/BGM bucket
- [ ] version-like bucket（即便暂时不训练 cover lane）
- [ ] Top1/Top3/MRR
- [ ] canonical_song recall
- [ ] work-level recall
- [ ] reference set 版本记录
---
## 4. 推荐时间顺序
```mermaid
flowchart TD
A[Schema v2 落库] --> B[实体导入]
B --> C[reference set 初始化]
C --> D[audio_window 生成]
D --> E[model/feature_set 初始化]
E --> F[MERT/MuQ 抽特征]
F --> G[semantic index]
C --> H[fingerprint index]
G --> I[candidate aggregation]
H --> I
I --> J[Phase-1 benchmark]
```
---
## 5. 第一版验收标准
### 数据层
- 能稳定插入 `canonical_song -> work -> recording -> recording_asset -> audio_window`
- 能支撑至少一套 `reference_set`
### 模型/特征层
- 能并行存在多个 `model_registry / feature_set_registry`
- 能跑通 MERT/MuQ encoder-only 抽特征
### 检索层
- 能同时返回 fingerprint lane 与 semantic lane 候选
- 能聚合输出 `canonical_song_id`
### 运维层
- 能重建 reference set
- 能重建 semantic index
- 能记录 feature_set 与 index version
---
## 6. 本阶段容易踩的坑
1. 先把 embedding 存储设计死到某个模型维度
2. 只保留 song_id，不保留 work/recording
3. reference set 没有版本化
4. query 结果无法回查具体 evidence window
5. exact lane 被过早删除
---
## 7. 当前建议结论
如果你要马上排计划，建议按这个优先级：
1. Schema v2 与主数据导入
2. reference set + audio_window
3. MERT/MuQ feature_set 初始化
4. encoder-only 抽特征
5. 双路召回与聚合
6. benchmark 与门禁
## 6.1 当前 planner 已提供的 validation entrypoints
`acr-engine/scripts/plan_phase1_extraction_jobs_live.py` 现在除了 job 级 `command_suggestions`，还会在 `phase1_extraction_plan_report.json` 里附带：
- `validation_commands.prereq_audit`
- `validation_commands.worker_contract_smoke`
- `validation_commands.semantic_vector_negative_matrix`
- `validation_commands.asset_level_upsert_validation`
这意味着下次启动时可以先跑“全局验证入口”，再决定是否执行具体 job，而不必手工拼测试命令。
## 6.2 当前推荐的一键验证入口
如果只是想先确认当前 host 是否具备继续推进 Phase-1 的条件，推荐优先执行：
```bash
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
```
它会直接读取 `phase1_extraction_plan_report.json` 的 `validation_commands`，并批量执行：
- `prereq_audit`
- `worker_contract_smoke`
- `semantic_vector_negative_matrix`
- `asset_level_upsert_validation`
当前 live 结果：
- `executed_count = 4`
- `all_passed = true`
# Phase-1 Worker Contract / 作业执行器契约
> 更新：2026-06-04
> 目标：把 Phase-1 从“只有 registry / plan”推进到“worker 可以真实消费 PostgreSQL 作业并更新状态”。
---
## 一页结论
当前 Phase-1 已经具备一条最小真实执行链：
1. planner 从 `feature_extraction_job` 读 pending jobs
2. worker 读取 `extraction_job_id`
3. worker 联表解析 `feature_set_registry + model_registry`
4. worker 解析 `target_scope`
5. worker 回写 `feature_extraction_job.job_status / input_count / output_count / metadata_json`
也就是说，现在 PostgreSQL 不只是“数据字典”，已经开始承担：
- 作业编排面
- 状态机面
- 执行证据面
---
## 1. 当前落地的 worker
位于：
- `acr-engine/scripts/bootstrap_phase1_reference_members_live.py`
- `acr-engine/workers/mark_job_status.py`
- `acr-engine/workers/run_chromaprint_job.py`
- `acr-engine/workers/run_embedding_job.py`
- `acr-engine/workers/_job_common.py`
### 角色划分
| worker | 作用 |
|---|---|
| `mark_job_status.py` | 通用状态推进器 |
| `run_chromaprint_job.py` | exact lane worker |
| `run_embedding_job.py` | semantic lane worker |
| `_job_common.py` | 共享的 job 读取、scope 解析、状态回写逻辑 |
### 配套 bootstrap
为了让 worker 不再面对空 scope，这轮还补上了：
- `acr-engine/scripts/bootstrap_phase1_reference_members_live.py`
它会把当前 `recording.is_reference = true` 的录音挂到：
- `phase1_hot_reference_v1`
这样 worker 可以真实看到：
- `recording_count`
- `ready_asset_count`
- `active_window_count`
---
## 2. 当前状态机
```mermaid
flowchart LR
A[pending] --> B[running]
B --> C[completed]
B --> D[failed]
```
### 当前已验证的状态流转
- `pending -> running`
- `running -> completed`（dry-run 模式）
### 当前状态保护
- worker 认领 job 时要求前置状态为 `pending`
- worker 完成 job 时要求前置状态为 `running`
- `mark_job_status.py` 只接受：
- `pending`
- `running`
- `completed`
- `failed`
- `finished_at` 只在首次完成时落值，不再被重复覆盖
### 已验证的 guard 行为
当前已真实验证：
1. 同一 chromaprint job 第一次 dry-run：
- 成功 `pending -> running -> completed`
2. 不做 reset，直接第二次执行同一 job：
- 被前置状态保护拒绝
对应证据：
- `acr-engine/data/pgvector_eval/music20/phase1_worker_double_claim_guard_report.json`
### 设计意图
先把 **作业契约与状态流转** 固定住，再把真正的模型推理塞进去。
这样后续不管换成：
- `Chromaprint`
- `MERT`
- `MuQ`
- `CoverHunter encoder`
都不需要重做 orchestration 数据结构。
---
## 3. worker 输入契约
### 环境变量
| 变量 | 说明 |
|---|---|
| `PG_DSN` | PostgreSQL 连接串 |
| `PG_SCHEMA` | 目标 schema |
| `EXTRACTION_JOB_ID` | 要执行的作业 id |
| `FEATURE_SET_ID` | 规划时附带，worker 可用于一致性检查 |
| `TARGET_SCOPE` | 规划时附带，worker 当前以 DB 中 job 记录为准 |
| `MODEL_NAME` | embedding worker 用于防错 |
| `MODEL_VERSION` | embedding worker 用于防错 |
| `VECTOR_TABLE` | embedding worker 目标向量表 |
| `OUTPUT_TARGET` | `audio_fingerprint` 或 `audio_embedding` |
### CLI 参数
三个 worker 都支持显式 CLI 参数覆盖 env。
### planner 命令模板的当前约定
`plan_phase1_extraction_jobs_live.py` 现在会显式生成：
```bash
cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" ...
```
这样复制命令时，如果调用方忘了提供数据库连接串，会立刻失败，而不是静默跑空。
当前 planner 还会显式使用：
```bash
/usr/local/miniconda3/bin/python
```
原因是当前环境里 `python` 不在 PATH 上，但这个解释器路径已被验证可用。
对于当前 dry-run worker，planner 的主命令模板也会显式带上：
```bash
--complete-dry-run
```
这样 `primary_command` 就能直接复现：
```text
pending -> running -> completed
```
---
## 4. PostgreSQL 读取契约
worker 当前真实读取：
1. `feature_extraction_job`
2. `feature_set_registry`
3. `model_registry`
4. `reference_set_registry` / `reference_set_member`
5. `recording_asset`
6. `audio_window`
### 为什么要读 scope summary
因为 Phase-1 第一阶段的核心不是“立刻抽出 embedding”，而是先确定：
- 这次 job 面向哪个 reference set
- 涉及多少 recording
- 涉及多少 ready asset
- 涉及多少 active window
这样后续做：
- 分片
- 并行
- 重试
- SLA 估算
才有稳定基线。
---
## 5. 当前 dry-run 的真实意义
当前 worker 还没有真正调用模型做特征提取；它做的是：
1. 验证 planner 命令模板可被真实消费
2. 验证 job -> feature_set -> model 的 join 契约
3. 验证 target scope 解析
4. 验证 PostgreSQL 作业状态回写
5. 为下一步真推理保留稳定入口
所以它不是假文档，而是：
> **先把工业执行面的骨架打通，再把模型推理填进去。**
---
## 6. 推荐执行顺序
```mermaid
flowchart TD
A[bootstrap model/feature/reference registry] --> B[bootstrap feature_extraction_job]
B --> C[plan pending jobs]
C --> D[run worker dry-run]
D --> E[validate status transitions]
E --> F[replace dry-run with real extractor]
```
---
## 7. exact lane 与 semantic lane 的后续替换点
### 7.1 Chromaprint worker
后续把下面逻辑塞进 `run_chromaprint_job.py`：
1. 读取 `recording_asset`
2. 读取可用音频并提取 exact-lane hash
3. 写 artifact JSON
4. 写 `audio_fingerprint`
5. 更新 `output_count`
6. 标记 `completed`
### 当前 exact lane 的真实状态
这轮已经把 `run_chromaprint_job.py` 从“只有 dry-run”推进到：
- 如果 source audio 可读：
- 生成 repo-local chromaprint-style hash artifact
- 写入 `audio_fingerprint`
- 如果 source audio 不可读：
- 明确把 job 标记为 `failed`
- 把 `failure_reason`、`missing_asset_count`、`missing_asset_samples` 写回 PostgreSQL
### 当前失败语义
当前 exact lane 采用的是 **全量成功 / 否则失败**：
- 只要 scope 内任意 asset：
- 缺文件
- 解码失败
- hash 提取失败
就整体标记：
- `job_status = failed`
- `failure_reason = unreadable_audio_assets`
这样不会把“部分成功”伪装成 `completed`。
### 当前依赖策略
当前 exact lane 不再强依赖 `librosa`：
- 优先使用 `librosa`（如果环境里存在）
- 否则回退到：
- Python `wave`
- `numpy` 线性重采样
- `numpy` FFT spectrogram
这使得 worker contract 能在更瘦的运行环境里继续工作。
### 当前幂等保护
`audio_fingerprint` 现在补了：
- `UNIQUE(feature_set_id, asset_id)`
对应 worker 写入改成：
- `INSERT ... ON CONFLICT DO UPDATE`
因此 exact lane 对同一 `(feature_set_id, asset_id)` 的重复写入不再依赖应用层先查再写。
### 7.2 Embedding worker
`run_embedding_job.py` 现在已经不再只是简单 dry-run。当前它已经具备：
1. 真实读取 `reference_set -> audio_window -> recording_asset` scope
2. 真实检查目标向量表是否存在且与维度匹配
3. 真实检查模型 runtime 依赖是否齐全
4. 真实检查 source audio 是否存在
5. 把 blocker 明确写回 `feature_extraction_job.metadata_json`
6. 在 blocker 存在时把 job 诚实标记为 `failed`
### 当前失败语义
semantic lane 当前采用的是 **preflight all-or-nothing**：
- 只要 scope 内音频路径不可达 / 文件不存在，记为：
- `unreadable_audio_assets`
- 只要模型 runtime 依赖导入不满足，记为：
- `model_runtime_unavailable`
- 只要目标向量表非法 / 缺失 / 维度不匹配，记为对应 blocker
worker 会把这些 blocker 聚合到：
- `failure_reason = preflight_failed`
- `preflight_blockers = [...]`
这样不会把“模型没法跑”误写成 completed，也不会只暴露第一个错误。
### 当前 vector table 负例证据
除了正常 `audio_embedding_vector_768` 存在性校验外，本轮还对 semantic lane 补了 3 类 live 负例：
- `audio_embedding_vector_192` -> `vector_table_dim_mismatch`
- `audio_embedding_vector_1024` -> `vector_table_not_allowlisted`
- 缺失 `audio_embedding_vector_768` 的隔离 schema -> `vector_table_missing_in_schema`
对应产物：
- `acr-engine/scripts/run_embedding_vector_table_negative_matrix_live.py`
- `acr-engine/data/pgvector_eval/music20/embedding_vector_table_negative_matrix_report.json`
这说明 semantic worker 当前不只是会在“环境缺依赖”时失败，也能把 **配置错误的向量表** 精确落账。
### 当前 live 证据
MERT 5s/2.5s job (`extraction_job_id=2`) 在 `acr_test` 上已经真实验证：
- `scope_window_count = 20`
- `job_status = failed`
- `output_count = 0`
- `preflight_blockers = ['unreadable_audio_assets', 'model_runtime_unavailable']`
- `runtime_report.missing_dependencies = ['torch', 'torchaudio', 'transformers']`
- `audio_embedding_vector_768` 已通过存在性与维度校验
对应产物：
- `acr-engine/data/pgvector_eval/music20/phase1_worker_embedding_write_attempt.json`
- `acr-engine/data/pgvector_eval/music20/phase1_worker_embedding_write_guard_report.json`
- `acr-engine/data/pgvector_eval/music20/phase1_worker_embedding_post_state.json`
### 当前幂等保护
为了服务后续真正的 window embedding upsert，`audio_embedding` 现在补了两条唯一键：
- `UNIQUE(feature_set_id, window_id) WHERE window_id IS NOT NULL`
- `UNIQUE(feature_set_id, asset_id) WHERE window_id IS NULL AND asset_id IS NOT NULL`
这让后续真实 encoder 接入后可以直接做：
- window 级 embedding upsert
- asset 级 embedding upsert
而不需要先查再写。
当前这两条唯一键里，asset-level 路径也已经有 live 证据：
- `scripts/validate_audio_embedding_asset_upsert_live.py`
- `audio_embedding_asset_upsert_live_report.json`
已验证：
- 重复 `INSERT` 会被 `uq_audio_embedding_feature_asset` 拒绝
- `ON CONFLICT ... DO UPDATE` 会复用同一个 `embedding_id`
- `audio_embedding` / `audio_embedding_vector_192` 行数都保持为 `1`
### 下一步替换点
当 runtime 与音频挂载到位后，只需要把 guarded failure path 替换成真实 inference：
1. 加载 `MERT` / `MuQ` / `ECAPA`
2. 提取向量
3. 写 `audio_embedding`
4. 写 `audio_embedding_vector_<dim>`
5. 更新 `output_count`
6. 标记 `completed`
也就是说，**PostgreSQL worker contract 已经固定，下一步换的是 encoder adapter，不是 orchestration 结构。**
---
## 8. 解决了什么问题
这次 worker contract 落地，主要解决了 4 个问题：
1. **planner 不再只是纸面计划**
2. **job status 有了真实推进器**
3. **后续换模型不用重做 orchestration**
4. **可以先 dry-run 验证执行链，再接入重模型**
---
## 9. 当前边界
当前还没有完成的部分：
- exact lane 虽已有真实写入路径，但当前 live 环境仍被 `/workspace/downloads` 缺失阻塞
- semantic lane 已有真实 preflight failure contract，但还没有接上真正的 `MERT / MuQ / ECAPA` inference adapter
- `failed` 重试策略
- job 分片执行器
- 更完整的 embedding artifact / checksum 治理策略
但现在已经足够支撑下一阶段：
> **把真实 extractor 接到已经验证过的 PostgreSQL worker contract 上。**
# PostgreSQL DB Schema Samples / 融合优先 DDL 草案与查询样例
# PostgreSQL Schema Samples / song-centric 4 表 DDL 与样例
> 更新：2026-06-04
> 目标：把当前 **song-centric + 融合优先** 设计落成一版可以直接评审和继续实现的 PostgreSQL DDL 草案。
> 更新：2026-06-04
> SQL 文件：[`acr-engine/sql/acr_pg_schema_songcentric_v1.sql`](../acr-engine/sql/acr_pg_schema_songcentric_v1.sql)
> live smoke：[`acr-engine/scripts/smoke_songcentric_schema_live.py`](../acr-engine/scripts/smoke_songcentric_schema_live.py)
---
## 一页结论
## 1. 一页结论
当前默认物理模型只看 4 张表：
当前默认物理模型：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
对应逻辑语义：
当前默认逻辑语义：
```text
song -> asset -> window -> fingerprint / embedding
```
其中：
- `media_entity`：当前默认只承载 `song`
- `audio_object`：统一承载 `asset` 与 `window`
- `feature_fact`：统一承载 `fingerprint` 与 `embedding`
- `set_membership`：统一承载 `reference / hot / eval` 等集合关系
- `audio_object` 统一承载原始音频和切片
- `feature_fact` 统一承载 exact/semantic 特征
- `set_membership` 统一承载 reference/eval/hot 集关系
---
## 1. 4 张表分别存什么
## 2. 切片 / 模型 / feature 落在哪张表
| 表 | 当前主要 type | 存什么 | 为什么存在 |
| 对象 | 表 | 关键字段 | 示例 |
|---|---|---|---|
| `media_entity` | `song` | 歌曲主实体 | 最终归属对象是 `song_id` |
| `audio_object` | `asset`, `window` | 原始音频文件 + 切片 | 同一个 song 下可有多个音频，切片仍需 evidence |
| `feature_fact` | `fingerprint`, `embedding` | 模型、feature set、特征结果 | 统一 exact/semantic 特征事实 |
| `set_membership` | `reference_set`, `eval_set`, `hot_set` | 谁属于哪个集合 | 管理 reference 与评测范围 |
| song | `media_entity` | `entity_type='song'` | `song_000001` |
| asset | `audio_object` | `object_type='asset'` | 一首歌的原始 wav/mp3/flac |
| window | `audio_object` | `object_type='window'` | `0-5000ms`, `2500-7500ms` |
| fingerprint | `feature_fact` | `feature_type='fingerprint'` | chromaprint |
| embedding | `feature_fact` | `feature_type='embedding'` | MERT/MuQ/fallback vector |
| model | `feature_fact` | `model_name`, `model_version` | `mert-v1-95m`, `muq-base`, `local_wavehash_embed` |
| feature set | `feature_fact` | `feature_set_name`, `feature_schema_ver` | `mert_5s_hop2.5_v1` |
---
## 2. 当前推荐 DDL 草案
## 3. DDL
### 2.1 `media_entity`
### 3.1 `media_entity`
```sql
create table if not exists media_entity (
......@@ -62,16 +62,9 @@ create table if not exists media_entity (
constraint fk_media_entity_parent
foreign key (parent_entity_id) references media_entity(entity_id)
);
create unique index if not exists uq_media_entity_song_biz_key
on media_entity(entity_type, biz_key)
where biz_key is not null;
create index if not exists idx_media_entity_root_song
on media_entity(root_song_id);
```
### 2.2 `audio_object`
### 3.2 `audio_object`
```sql
create table if not exists audio_object (
......@@ -99,23 +92,9 @@ create table if not exists audio_object (
or (object_type = 'window' and parent_object_id is not null)
)
);
create index if not exists idx_audio_object_song_type
on audio_object(song_id, object_type);
create index if not exists idx_audio_object_parent
on audio_object(parent_object_id);
create unique index if not exists uq_audio_object_asset_checksum
on audio_object(song_id, checksum)
where object_type = 'asset' and checksum is not null;
create unique index if not exists uq_audio_object_window_range
on audio_object(parent_object_id, start_ms, end_ms)
where object_type = 'window';
```
### 2.3 `feature_fact`
### 3.3 `feature_fact`
```sql
create table if not exists feature_fact (
......@@ -142,23 +121,9 @@ create table if not exists feature_fact (
or (feature_type = 'embedding' and (embedding_uri is not null or vector_table_name is not null))
)
);
create index if not exists idx_feature_fact_object_type
on feature_fact(object_id, feature_type);
create index if not exists idx_feature_fact_song_type
on feature_fact(song_id, feature_type);
create unique index if not exists uq_feature_fact_embedding
on feature_fact(object_id, model_name, model_version, feature_set_name, feature_type)
where feature_type = 'embedding';
create unique index if not exists uq_feature_fact_fingerprint
on feature_fact(object_id, model_name, model_version, feature_set_name, feature_type)
where feature_type = 'fingerprint';
```
### 2.4 `set_membership`
### 3.4 `set_membership`
```sql
create table if not exists set_membership (
......@@ -174,285 +139,245 @@ create table if not exists set_membership (
created_at timestamptz not null default now(),
updated_at timestamptz not null default now()
);
create unique index if not exists uq_set_membership_unique
on set_membership(set_type, set_name, member_type, member_id);
create index if not exists idx_set_membership_set_lookup
on set_membership(set_type, set_name, is_active, priority);
```
---
## 3. 切片 / 模型 / feature 到底落哪张表
| 对象 | 落表 | 关键字段 |
|---|---|---|
| song | `media_entity` | `entity_type='song'` |
| 原始音频 | `audio_object` | `object_type='asset'` |
| 切片窗口 | `audio_object` | `object_type='window'`, `parent_object_id=<asset_id>` |
| 指纹特征 | `feature_fact` | `feature_type='fingerprint'` |
| embedding 特征 | `feature_fact` | `feature_type='embedding'` |
| 模型名/版本 | `feature_fact` | `model_name`, `model_version` |
| feature set | `feature_fact` | `feature_set_name`, `feature_schema_ver` |
| reference 集归属 | `set_membership` | `set_type='reference_set'` |
---
## 4. 流程图
## 4. 典型写入流程图
### 4.1 落库流程
### 4.1 表写入顺序
```mermaid
flowchart TD
A[media_entity\nentity_type=song] --> B[audio_object\nobject_type=asset]
B --> C[audio_object\nobject_type=window]
C --> D1[feature_fact\nfeature_type=fingerprint]
C --> D2[feature_fact\nfeature_type=embedding]
B --> E[set_membership\nreference_set]
A[insert song] --> B[insert asset]
B --> C[insert windows]
C --> D1[insert fingerprint facts]
C --> D2[insert embedding facts]
A --> E[insert set_membership]
B --> E
C --> E
```
### 4.2 查询回溯流程
### 4.2 查询回溯顺序
```mermaid
flowchart LR
A[feature_fact] --> B[audio_object window]
B --> C[audio_object asset]
C --> D[media_entity song]
A[query features] --> B[feature_fact]
B --> C[window]
C --> D[asset]
D --> E[song]
```
### 4.3 写入时序图
```mermaid
sequenceDiagram
participant ING as Ingest/Extract Job
participant DB as PostgreSQL
ING->>DB: insert media_entity(song)
ING->>DB: insert audio_object(asset)
ING->>DB: insert audio_object(window)
ING->>DB: insert feature_fact(fingerprint)
ING->>DB: insert feature_fact(embedding)
ING->>DB: insert set_membership(reference_set)
```
---
## 5. 样例数据
### 4.4 Phase-1 bootstrap 流程
### 5.1 写 song
```mermaid
flowchart TD
A[bootstrap_songcentric_phase1_live.py] --> B[media_entity song x N]
B --> C[audio_object asset x N]
C --> D[audio_object window x N]
D --> E1[feature_fact fingerprint x N]
D --> E2[feature_fact embedding x N]
C --> F[set_membership reference_set x N]
```sql
insert into media_entity (
entity_type, biz_key, title, artist_name, metadata_json
) values (
'song', 'song_000001', 'Song Alpha', 'Artist A',
'{"source":"catalog_import","language":"zh"}'::jsonb
)
returning entity_id;
```
当前 live bootstrap 脚本：[`acr-engine/scripts/bootstrap_songcentric_phase1_live.py`](../acr-engine/scripts/bootstrap_songcentric_phase1_live.py)
### 5.2 写 asset
### 4.5 Manifest 导入流程
```mermaid
flowchart TD
A[songcentric_manifest_sample.jsonl] --> B[import_songcentric_manifest_live.py]
B --> C[media_entity song]
B --> D[audio_object asset]
B --> E[audio_object window x N]
B --> F[feature_fact]
B --> G[set_membership]
```sql
insert into audio_object (
object_type, song_id, source_type, storage_uri, storage_scheme,
checksum, codec, sample_rate, channels, duration_ms, metadata_json
) values (
'asset', :song_id, 'catalog_master',
's3://bucket/song_alpha/clip1.wav', 's3',
'sha256:asset001', 'wav', 44100, 2, 183000,
'{"uploader":"pipeline_v1"}'::jsonb
)
returning object_id;
```
当前样例 manifest：[`acr-engine/data/pgvector_eval/music20/songcentric_manifest_sample.jsonl`](../acr-engine/data/pgvector_eval/music20/songcentric_manifest_sample.jsonl)
当前导入脚本：[`acr-engine/scripts/import_songcentric_manifest_live.py`](../acr-engine/scripts/import_songcentric_manifest_live.py)
### 5.3 写 window
当前带 feature 样例 manifest：[`acr-engine/data/pgvector_eval/music20/songcentric_feature_manifest_sample.jsonl`](../acr-engine/data/pgvector_eval/music20/songcentric_feature_manifest_sample.jsonl)
### 4.6 真实目录生成 manifest 流程
```mermaid
flowchart TD
A[real audio directory] --> B[build_songcentric_manifest_from_directory.py]
B --> C[songcentric_directory_manifest.jsonl]
C --> D[import_songcentric_manifest_live.py]
D --> E[media_entity]
D --> F[audio_object]
D --> G[set_membership]
```sql
insert into audio_object (
object_type, song_id, parent_object_id,
start_ms, end_ms, duration_ms, metadata_json
) values
('window', :song_id, :asset_id, 0, 5000, 5000, '{"hop_ms":2500}'::jsonb),
('window', :song_id, :asset_id, 2500, 7500, 5000, '{"hop_ms":2500}'::jsonb)
returning object_id;
```
当前目录构建脚本：[`acr-engine/scripts/build_songcentric_manifest_from_directory.py`](../acr-engine/scripts/build_songcentric_manifest_from_directory.py)
### 4.7 真实目录补特征再导入流程
### 5.4 写 fingerprint
```mermaid
flowchart TD
A[real audio directory] --> B[build_songcentric_manifest_from_directory.py]
B --> C[songcentric_directory_manifest.jsonl]
C --> D[enrich_songcentric_manifest_with_local_features.py]
D --> E[songcentric_directory_manifest_with_features.jsonl]
E --> F[import_songcentric_manifest_live.py]
F --> G[feature_fact]
```sql
insert into feature_fact (
feature_type, object_id, song_id,
model_name, model_version, feature_set_name, feature_schema_ver,
fingerprint_value, checksum, metadata_json
) values (
'fingerprint', :window_id, :song_id,
'chromaprint', '1.0', 'chromaprint_5s_v1', 'v1',
'AQAAE0mUaEkSZSo...', 'sha256:fp001',
'{"lane":"exact"}'::jsonb
);
```
当前特征补全脚本：[`acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py`](../acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py)
### 4.8 目录链中的 exact lane 提升
### 5.5 写 embedding
当前 `enrich_songcentric_manifest_with_local_features.py` 已优先复用仓库内 `ChromaprintMatcher` 生成 fingerprint；只有失败时才回退到 `local_wavehash`。
本轮 fresh evidence：
- `wav_windows_seen = 5`
- `matcher_fingerprint_count = 5`
- `fallback_fingerprint_count = 0`
这说明当前目录链里的 exact lane 已经不只是临时 hash，而是优先接上了仓库现有 fingerprint 提取能力。
### 4.9 目录链中的 semantic lane 运行时选择
当前 `enrich_songcentric_manifest_with_local_features.py` 对 semantic lane 采用 **runtime-aware** 选择：
- 如果 `torch / torchaudio / transformers` 可用，则预留真实 semantic adapter 入口
- 如果不可用，则明确落到 `local_wavehash_embed` fallback，并把缺失依赖写进 metadata/report
本轮 fresh evidence：
- `semantic_runtime_available = false`
- `semantic_runtime_missing = ["torch", "torchaudio", "transformers"]`
- `semantic_fallback_count = 5`
这说明当前 host 上 semantic lane 还未接真实模型，但链路已经具备明确的运行时分流与可审计证据。
### 4.10 一键 song-centric 目录链 runner
```mermaid
flowchart TD
A[run_songcentric_directory_pipeline_live.py] --> B[build manifest]
B --> C[enrich features]
C --> D[import manifest]
D --> E[runner report]
```sql
insert into feature_fact (
feature_type, object_id, song_id,
model_name, model_version, feature_set_name, feature_schema_ver,
embedding_dim, embedding_uri, vector_table_name, checksum, metadata_json
) values (
'embedding', :window_id, :song_id,
'mert-v1-95m', 'hf-main', 'mert_5s_hop2.5_v1', 'v1',
768, 's3://bucket/embeddings/song_alpha_win0001.npy', 'audio_embedding_vector_768',
'sha256:emb001', '{"lane":"semantic"}'::jsonb
);
```
当前 runner：[`acr-engine/scripts/run_songcentric_directory_pipeline_live.py`](../acr-engine/scripts/run_songcentric_directory_pipeline_live.py)
### 5.6 写 set membership
它会在一条命令里输出：
- 目录扫描结果
- exact lane 是否走 `ChromaprintMatcher`
- semantic lane 是否 runtime-ready
- live PostgreSQL 导入后的计数与 lineage 样例
```sql
insert into set_membership (
set_type, set_name, member_type, member_id, song_id, priority, metadata_json
) values
('reference_set', 'phase1_hot_reference_v1', 'song', :song_id, :song_id, 100, '{}'::jsonb),
('reference_set', 'phase1_hot_reference_v1', 'asset', :asset_id, :song_id, 100, '{}'::jsonb),
('reference_set', 'phase1_hot_reference_v1', 'window', :window_id, :song_id, 100, '{}'::jsonb);
```
---
## 5. 最常用 SQL 样例
## 6. 典型查询
### 5.1 写一首歌
### 6.1 查看某首歌有哪些 asset
```sql
insert into media_entity (entity_type, biz_key, title, artist_name)
values ('song', 'song-10001', 'Song 10001', 'Artist A')
returning entity_id;
select object_id, storage_uri, checksum, duration_ms
from audio_object
where song_id = :song_id
and object_type = 'asset'
order by object_id;
```
### 5.2 写一个 asset
### 6.2 查看某个 asset 切了哪些 window
```sql
insert into audio_object (
object_type, song_id, source_type, storage_uri, storage_scheme,
checksum, codec, sample_rate, channels, duration_ms
) values (
'asset', :song_id, 'official', 's3://bucket/song10001/master.wav', 's3',
'sha256:xxx', 'wav', 44100, 2, 215000
) returning object_id;
select object_id, start_ms, end_ms, duration_ms
from audio_object
where parent_object_id = :asset_id
and object_type = 'window'
order by start_ms;
```
### 5.3 写一个 window
### 6.3 查看某个 window 被哪些模型编码过
```sql
insert into audio_object (
object_type, song_id, parent_object_id, start_ms, end_ms, duration_ms
) values (
'window', :song_id, :asset_id, 30000, 35000, 5000
) returning object_id;
select feature_type, model_name, model_version, feature_set_name, embedding_dim,
fingerprint_value, embedding_uri, vector_table_name
from feature_fact
where object_id = :window_id
order by feature_type, model_name, model_version;
```
### 5.4 写一条 embedding
### 6.4 从 feature 回查 song
```sql
insert into feature_fact (
feature_type, object_id, song_id,
model_name, model_version, feature_set_name,
feature_schema_ver, embedding_dim, embedding_uri, vector_table_name
) values (
'embedding', :window_id, :song_id,
'mert', 'v1-95m', 'mert_5s_hop2.5_meanpool',
'v1', 768, 's3://bucket/emb/song10001_win0001.npy', 'audio_embedding_vector_768'
);
select ff.feature_id,
ff.feature_type,
ff.model_name,
w.object_id as window_id,
w.start_ms,
w.end_ms,
a.object_id as asset_id,
a.storage_uri,
s.entity_id as song_id,
s.title,
s.artist_name
from feature_fact ff
join audio_object w
on w.object_id = ff.object_id
and w.object_type = 'window'
join audio_object a
on a.object_id = w.parent_object_id
and a.object_type = 'asset'
join media_entity s
on s.entity_id = ff.song_id
where ff.feature_id = :feature_id;
```
### 5.5 把 asset 挂到 reference 集
### 6.5 查询 reference set 中的全部 window
```sql
insert into set_membership (
set_type, set_name, member_type, member_id, song_id, priority
) values (
'reference_set', 'phase1_hot_reference_v1', 'asset', :asset_id, :song_id, 100
);
select sm.set_name,
sm.member_id as window_id,
sm.song_id,
ao.parent_object_id as asset_id,
ao.start_ms,
ao.end_ms
from set_membership sm
join audio_object ao
on ao.object_id = sm.member_id
and sm.member_type = 'window'
where sm.set_type = 'reference_set'
and sm.set_name = 'phase1_hot_reference_v1'
and sm.is_active = true
order by sm.song_id, ao.start_ms;
```
### 5.6 从 embedding 回查 song
---
```sql
select ff.feature_id,
ff.model_name,
ff.model_version,
ff.feature_set_name,
win.object_id as window_id,
ast.object_id as asset_id,
song.entity_id as song_id,
song.title,
song.artist_name
from feature_fact ff
join audio_object win
on win.object_id = ff.object_id
and win.object_type = 'window'
join audio_object ast
on ast.object_id = win.parent_object_id
and ast.object_type = 'asset'
join media_entity song
on song.entity_id = ff.song_id
and song.entity_type = 'song'
where ff.feature_id = :feature_id;
## 7. 一个最小存储样例怎么理解
```text
song(Song Alpha)
-> asset(clip1.wav)
-> window(0-5000ms)
-> fingerprint(chromaprint)
-> embedding(mert-v1-95m)
-> window(2500-7500ms)
-> fingerprint(chromaprint)
-> embedding(mert-v1-95m)
```
落表后意味着：
- `song` 在 `media_entity`
- `asset/window` 都在 `audio_object`
- `chromaprint/mert` 都在 `feature_fact`
- 它们是否属于 hot reference 在 `set_membership`
---
## 6. 当前设计意图
## 8. 设计意图总结
这套结构主要解决：
- 同一 song 下多个音频文件
- 同一 asset 下多个切片窗口
- 同一 window 被多个模型重复编码
- fingerprint / embedding 统一落库
- reference/eval/hot 统一集合治理
- 查询后快速归属到 `song_id`
### 为什么切片和原始音频统一用 `audio_object`
- 新同学更容易理解
- asset/window 共用大量字段
- 减少专用表数量
---
### 为什么模型和特征统一用 `feature_fact`
- 不再一模型一张表
- 不再 fingerprint 一张表、embedding 一张表后继续扩散
- 更适合未来继续换 MERT / MuQ / 新模型
## 9. 当前最该关注的后续演进点
### 为什么 reference 集用 `set_membership`
- song / asset / window / feature 都可以挂集合
- reference / eval / hot 切换统一处理
1. 保持 4 表主链不变
2. 给 semantic lane 接真实 `MERT` / `MuQ` adapter
3. 继续复用 `feature_fact.model_name/model_version/feature_set_name` 做模型演进
4. 必要时再补更重的 registry / vector table 治理
---
## 7. 当前最推荐的实现顺序
## 10. 相关文档
1. 先建 `media_entity`
2. 再建 `audio_object`
3. 再建 `feature_fact`
4. 最后建 `set_membership`
5. 先打通 `song -> asset -> window -> embedding/fingerprint`
6. 再继续补更重的治理能力
- [README.md](./README.md)
- [start-here.md](./start-here.md)
- [session-handoff.md](./session-handoff.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
......
# PostgreSQL 数据模型与 DDL 设计说明
# PostgreSQL 数据模型 / 当前 song-centric 4 表方案
> 更新：2026-06-04
> 关联 SQL：[`acr-engine/sql/acr_pg_schema_v2.sql`](../acr-engine/sql/acr_pg_schema_v2.sql)
> 目标：给出面向版权保护 / 大规模曲库 / 可替换 encoder 的 PostgreSQL 数据字典、DDL 设计意图、流程图与典型使用路径。
## 一页结论
当前推荐的 PostgreSQL 设计，不再围绕“某一个模型的 embedding 表”来建，而是围绕下面这条稳定主链来建：
```text
canonical_song -> work -> recording -> recording_asset -> audio_window
-> model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint
-> reference_set_registry -> retrieval_index_registry -> retrieval_candidate -> match_decision
```
这套设计解决的是：
1. **song/work/recording 混在一起的问题**
2. **未来换模型就得改表的问题**
3. **窗口级检索无法回溯证据的问题**
4. **exact / semantic / future cover lane 无法统一聚合的问题**
---
## 0.1 为什么会感觉链路很多
本质上当前文档把 **3 类问题** 放在同一个总图里，所以看起来链路很长：
1. **业务归属层**：`canonical_song / work / recording`
- 解决“最终归哪个 song_id / work_id / recording_id”
2. **物理音频层**：`recording_asset / audio_window`
- 解决“实际文件是什么、切成了哪些检索窗口”
3. **检索计算层**：`model_registry / feature_set_registry / audio_embedding / audio_fingerprint / retrieval_index_registry`
- 解决“用了哪个模型、哪套特征、哪套索引”
所以这不是一条单链，而是：
- 一条 **归属回溯链**
- 一条 **音频资产链**
- 一条 **特征/索引链**
把三者混看，就会误以为每次查询都要手工经过所有表。实际上在线检索真正关心的是：
```text
window -> candidate -> recording -> song
```
---
## 0.2 当前是否可以简化
可以。
如果当前阶段的目标是：
> 先服务版权保护场景，让 query 能快速稳定地命中正确 `song_id`
那么 Phase-1 完全可以收敛为下面这套 **最小可用骨架**：
```text
song -> recording -> recording_asset -> audio_window
-> audio_fingerprint
-> audio_embedding
```
为了支持模型替换，再保留一个轻量版本登记层：
```text
feature_set_registry
```
也就是说，Phase-1 最小主链可以压缩成：
```text
song -> recording -> asset -> window -> feature
```
其中 `feature` 可具体落成：
- `audio_fingerprint`
- `audio_embedding`
---
## 0.3 哪些层建议 Phase-1 保留，哪些层可以弱化
### 建议保留
| 层 | 是否保留 | 原因 |
|---|---|---|
| `song` | 保留 | 最终业务返回对象 |
| `recording` | 保留 | 同一 song 下会有多个版本/录音 |
| `recording_asset` | 保留 | 一个 recording 可能有多个真实文件 |
| `audio_window` | 保留 | 检索和 evidence 的最小计算单元 |
| `feature_set_registry` | 保留 | 避免把 embedding/fingerprint 固化成表列 |
| `audio_embedding` / `audio_fingerprint` | 保留 | 真正的检索特征事实表 |
### 可以弱化或延期
| 层 | 当前建议 | 原因 |
|---|---|---|
| `work` | 可延期 | 如果当前只需稳定返回 `song_id`，可先不显式拆作品层 |
| `canonical_song` | 可与 `song` 合并理解 | 当前重点不是权利层深治理，而是先完成可用归属主键 |
| `retrieval_index_registry` | 可先弱化 | Phase-1 可先把索引治理做轻，不必一开始做太重 |
| `match_decision` 全量审计 | 可逐步补齐 | 先保证召回闭环，再加强审计/解释性 |
---
## 0.3.1 `recording` 和 `recording_asset` 能不能合并
可以合并，但**只适合非常早期、非常受控的数据集**。
### 什么时候可以临时合并
只有当下面条件基本都成立时，才可以把二者临时看成一个对象：
1. 每个 `song` 只有一个可用录音版本
2. 每个录音只有一个音频文件
3. 不区分 master / distribution / captured / query_sample
4. 不需要追踪同一录音的多个来源文件
5. 不需要后续补高码率、补母带、补平台版本
在这种情况下，可以暂时把模型理解成：
```text
song -> recording_asset -> audio_window
```
也就是让 `recording_asset` 同时承担“版本对象 + 物理文件对象”的职责。
### 为什么长期不建议合并
因为 `recording` 和 `recording_asset` 回答的是两个不同问题：
- `recording` 回答：**这是哪个录音版本**
- `recording_asset` 回答：**这个录音版本对应哪个具体文件**
一旦进入真实版权保护场景，下面几类情况会非常常见：
1. **同一录音有多个文件版本**
例如 wav/flac/mp3、不同码率、不同平台导出件。
2. **同一 song 有多个录音版本**
例如 official/live/remaster/short/bgm cut。
3. **同一录音要接多个来源**
例如平台抓取、业务导出、人工补档。
4. **query 命中的是 asset，但归属要落到 recording/song**
如果不拆层，后面聚合和去重会比较乱。
### 当前最推荐的判断
对于你现在这个目标：
- 约 `100w` 音频
- 约 `30w` 歌曲
- 面向版权保护 / 听歌识曲 / 版本归属
**不建议把 `recording` 和 `recording_asset` 合并进正式 schema。**
原因很直接：
- 数据量已经不小
- 后续大概率会遇到多版本、多来源、多文件问题
- 现在省掉一层，后面重构成本会更高
### 更务实的折中方案
如果你觉得当前实现心智负担太高，可以不在产品/算法讨论里反复强调 `recording_asset`，而是采用下面口径：
```text
song -> recording -> asset -> window -> feature
```
也就是说：
- **概念上保留** `recording` 和 `asset` 两层
- **沟通上简写** 为 `recording -> asset`
- **实现上继续分表**，避免未来返工
这通常是 Phase-1 最稳妥的折中。
> 更新：2026-06-04
> 关联 SQL：[`acr-engine/sql/acr_pg_schema_songcentric_v1.sql`](../acr-engine/sql/acr_pg_schema_songcentric_v1.sql)
---
## 0.4 一个更容易理解的口径
建议把当前体系理解为下面两条核心链：
## 1. 一页结论
### 归属链
当前默认只认 4 张核心物理表：
```text
window -> asset -> recording -> song
media_entity -> audio_object -> feature_fact -> set_membership
```
作用：
- 检索命中后，回溯最终归属到哪个 `song_id`
### 特征链
逻辑语义这样理解：
```text
window -> fingerprint / embedding -> candidate -> aggregate
song -> asset -> window -> fingerprint / embedding
```
作用：
- 真正完成召回、打分、聚合与排序
这样看时，整个设计就不再是“很多层没必要”，而是：
- **归属层负责回答是谁**
- **窗口层负责回答命中了哪一段**
- **特征层负责回答怎么检索出来**
---
## 1. 设计意图
## 1.1 这套设计想解决什么
### 问题 A：同一首歌可能有多个录音版本
所以必须区分：
- `canonical_song`：业务最终归一 song
- `work`：作品层
- `recording`：具体录音版本
### 问题 B：一个录音可能有多个文件资产
所以必须有：
- `recording_asset`
### 问题 C：检索真正命中的是片段，不是整首歌
所以必须有：
- `audio_window`
### 问题 D：未来底座会切换
所以必须有：
- `model_registry`
- `feature_set_registry`
### 问题 E：你会同时存在多个索引后端
所以必须有：
- `retrieval_index_registry`
这套设计的核心价值：
- **song-centric**：最终稳定返回 `song_id`
- **融合优先**：减少 `recording/work/version` 首阶段理解成本
- **特征统一**：exact lane 和 semantic lane 统一落到 `feature_fact`
- **模型可替换**：换 `model_name/model_version/feature_set_name` 不必重拆 schema
- **证据可回溯**：任何召回都能回查到具体 `window -> asset -> song`
---
## 1.2 为什么不用“reference_embeddings / query_embeddings”那种原型表继续扩
因为原型表有几个限制：
1. 维度写死，如 `vector(192)`
2. 数据对象太扁平，只围绕 `song_id`
3. 无法优雅支持多个 encoder
4. 无法表达同一 recording 下的多资产、多窗口、多 feature_set
所以原型版 SQL 适合 demo，不适合你现在的 100w 音频目标。
## 2. 为什么现在收敛成 4 表
### 当前最建议的简化口径
当前目标不是先建一个最完整的音乐版权知识图谱，而是先把下面这件事做稳：
如果团队正在进入 Phase-1 实施，不必把所有表同时视为“首批必须上线的复杂系统”。
更推荐按下面顺序理解和落库：
> 收到一个录音/BGM/片段/翻唱相关查询后，能够快速定位它最可能对应哪个 `song_id`。
1. `song -> recording -> recording_asset -> audio_window`
2. `feature_set_registry -> audio_fingerprint / audio_embedding`
3. `reference_set_registry` 与更重的索引治理随后补齐
因此当前优先级是：
1. 先固定 `song` 作为最终归属对象
2. 保留 `asset`，支持同一 `song` 下多个音频文件
3. 保留 `window`，支持切片级 evidence 与 offset
4. 用一张 `feature_fact` 同时承载 fingerprint 与 embedding
5. 用一张 `set_membership` 管理 reference/eval/hot 集合
---
## 1.2 当前业务前提变化：版本暂不重要，先做 song-centric
## 3. 4 张表分别解决什么问题
如果当前业务约束是：
> **同一个歌曲下可以有多个录音或多个音频，但暂时不关心版本语义，只需要最终稳定归到同一个 `song_id`**
那么当前 Phase-1 最推荐的默认口径应进一步收敛为：
```text
song -> asset -> window -> feature
```
也就是说：
- `song` 是当前唯一必须稳定返回的归属对象
- 同一个 `song` 下允许存在多个音频文件
- 这些音频文件可以是官方、抓取、BGM、片段、query sample 等不同来源
- 现阶段先不把“录音版本差异”提升成必须单独建模的核心层
### 当前最推荐的物理实现
在这个业务前提下，最推荐直接采用 **3+1 张融合表**：
| 物理表 | 主要 type | 当前作用 |
| 表 | 当前主要 type | 解决的问题 |
|---|---|---|
| `media_entity` | `song` | 只承载最终业务归属对象 |
| `audio_object` | `asset`, `window` | 承载音频文件与切片窗口 |
| `feature_fact` | `fingerprint`, `embedding` | 承载检索特征事实 |
| `set_membership` | `reference_set`, `hot_set`, `eval_set` | 承载 reference / eval 等集合关系 |
对应逻辑主链：
| `media_entity` | `song` | 最终归属对象是谁 |
| `audio_object` | `asset`, `window` | 实际音频文件是什么、切成了哪些窗口 |
| `feature_fact` | `fingerprint`, `embedding` | 每个窗口/对象用了哪个模型、产出了什么特征 |
| `set_membership` | `reference_set`, `eval_set`, `hot_set` | 哪些 song/asset/window/feature 属于哪个集合 |
```text
song -> asset -> window -> feature
```
### 切片数据、模型、feature 具体落在哪些表
---
在当前 **song-centric + 融合优先** 设计下，可以直接按下面理解：
## 4. 切片 / 模型 / feature 分别在哪张表
| 你关心的对象 | 当前推荐表 | 关键 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 集 |
| song | `media_entity` | `entity_type='song'` | 最终返回 `song_id` |
| asset | `audio_object` | `object_type='asset'` | 存原始音频文件元数据 |
| window | `audio_object` | `object_type='window'`, `parent_object_id=<asset_id>` | 存切片范围、offset、evidence |
| fingerprint | `feature_fact` | `feature_type='fingerprint'`, `fingerprint_value` | exact lane 检索 |
| embedding | `feature_fact` | `feature_type='embedding'`, `embedding_uri/vector_table_name`, `embedding_dim` | semantic lane 检索 |
| model identity | `feature_fact` | `model_name`, `model_version` | 区分 MERT / MuQ / ECAPA / fallback |
| feature set identity | `feature_fact` | `feature_set_name`, `feature_schema_ver` | 区分特征配置、窗口策略、schema 版本 |
| reference routing | `set_membership` | `set_type`, `set_name` | 控制 reference/eval/hot 范围 |
### 4.1 一个关键设计点
当前 **模型信息不单独放 registry 表作为默认主链依赖**，而是先直接沉淀在 `feature_fact`：
- 这样 Phase-1 更轻
- 更适合“直接复用开源 encoder，不先训练/微调”的当前策略
- 后续如果要补 registry，也可以把 `feature_fact` 中已有事实反向注册
最关键的一点是：
---
> **切片本身也落在 `audio_object`，只是 `object_type=window`；模型与特征统一落在 `feature_fact`。**
## 5. 核心流程图
### 对应流程图
### 5.1 落库流程
```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
A[media_entity\nentity_type=song] --> B[audio_object\nobject_type=asset]
B --> C[audio_object\nobject_type=window]
C --> D1[feature_fact\nfeature_type=fingerprint]
C --> D2[feature_fact\nfeature_type=embedding]
A --> E[set_membership]
B --> E
C --> E
```
### 对应写入流程
### 5.2 查询回溯流程
```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)
flowchart LR
A[query audio] --> B[切片成 query windows]
B --> C[抽 fingerprint / embedding]
C --> D[命中 feature_fact]
D --> E[audio_object window]
E --> F[audio_object asset]
F --> G[media_entity song]
G --> H[输出 song_id + evidence]
```
### 一个最实用的查询回溯口径
如果 query 命中了一条 embedding/fingerprint，回溯路径就是：
### 5.3 表职责视图
```text
feature_fact -> audio_object(window) -> audio_object(asset) -> media_entity(song)
```mermaid
flowchart TB
M[media_entity\n谁] --> A[audio_object\n哪份音频/哪段切片]
A --> F[feature_fact\n用了哪个模型/产出什么特征]
M --> S[set_membership\n属于哪个 reference/eval/hot 集]
A --> S
F --> R[召回/匹配/聚合]
```
这条链已经足够支撑你当前最关心的问题：
- 这个切片来自哪个音频文件
- 这个音频文件归到哪个 `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 融合优先：逻辑分层保留，物理表尽量收敛
如果你的核心诉求是：
> **尽量减少表数量，用 `type` + 通用关联表达多种对象，而不是一路拆很多表再 join**
那么推荐采用下面这个口径：
- **逻辑层** 当前默认保留 `song / asset / window / feature`；`recording` 仅保留为未来扩展语义
- **物理层** 尽量融合成少数几张通用表
也就是说：
> **概念上分层，落库上收敛。**
### 推荐的融合优先物理视图
| 物理表 | 主要 type | 作用 |
|---|---|---|
| `media_entity` | `song`（当前默认）, `work`/`recording`（未来扩展） | 承载业务归属对象 |
| `audio_object` | `asset`, `window` | 承载真实音频文件与切片对象 |
| `feature_fact` | `fingerprint`, `embedding` | 承载检索特征事实 |
| `set_membership` | `reference_set`, `hot_set`, `eval_set` | 承载集合归属关系 |
这样，Phase-1 在物理表层面可以被收敛成：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
而不是新同学第一眼就看到很多高度专用表。
## 6. 每张表的设计意图
### 对应的逻辑语义
### 6.1 `media_entity`
#### `media_entity`
用 `entity_type` 区分：
- `song`（当前默认必用）
- `work`（可选）
- `recording`（未来扩展）
用途：
- 作为 song 主实体表
- 统一承载 `song_id`
- 后续如需要，也允许保留 `work/recording` type，但当前默认只把 `song` 当主语义
公共字段可统一为：
当前最常用字段：
- `entity_id`
- `entity_type`
- `parent_entity_id`
- `root_song_id`
- `biz_key`
- `title`
- `artist_name`
- `entity_status`
- `metadata_json`
#### `audio_object`
用 `object_type` 区分：
- `asset`
- `window`
设计意图：
- 不再把 song 相关字段散落到多张表
- 先把最终归属对象固定下来
公共字段可统一为：
- `object_id`
### 6.2 `audio_object`
用途：
- 同时管理 `asset` 与 `window`
- 用 `parent_object_id` 建立 `asset -> window` 父子关系
当前最常用字段：
- `object_type`
- `recording_entity_id`
- `song_id`
- `parent_object_id`
- `storage_uri`
- `codec`
- `sample_rate`
- `start_ms` / `end_ms`
- `duration_ms`
- `checksum`
- `metadata_json`
- `duration_ms`
- `start_ms`
- `end_ms`
解释：
- `asset` 行表示真实音频文件
- `window` 行表示由某个 `asset` 切出来的检索窗口
设计意图：
- 同一 `song` 下可有多个音频文件
- 同一音频文件可切成多个检索窗口
- 查询命中后可以回查具体 offset
#### `feature_fact`
用 `feature_type` 区分：
- `fingerprint`
- `embedding`
### 6.3 `feature_fact`
公共字段可统一为：
- `feature_id`
用途：
- 统一存 exact lane 和 semantic lane 的特征事实
- 统一挂模型信息、特征集信息、特征载荷位置
当前最常用字段：
- `feature_type`
- `object_id`
- `song_id`
- `model_name`
- `model_version`
- `feature_set_name`
- `embedding_dim`
- `fingerprint_value` / `embedding_uri`
- `fingerprint_value`
- `embedding_uri`
- `vector_table_name`
- `metadata_json`
这样可以避免：
- 一套模型一张表
- 一类特征一张表
- 后续换模型就改 schema
### 为什么这比“纯拆表”更适合当前 Phase-1
优点：
1. **新同学更容易理解**：看到的是 3~4 张核心表，而不是十几张专用表
2. **更符合当前业务前提**：多个音频直接挂到同一个 `song_id`，先不强区分 recording
3. **模型演进更平滑**：`feature_fact` 可以同时容纳不同模型与不同特征
4. **更符合当前目标**：先把识别闭环跑通，而不是先把治理模型拆到很细
### 但不要融合过头
虽然推荐物理收敛，但仍然不建议极端融合成一张大全表。
例如下面这种仍然过度扁平：
```text
song_everything
```
原因是它会把：
- 归属对象
- 音频对象
- 检索特征
- 集合关系
全部揉在一起，导致：
- 空字段过多
- 约束难写
- 批量写入难做
- 查询语义不清晰
因此更推荐的边界是：
```text
实体一张表 + 音频对象一张表 + 特征事实一张表 + 集合关系一张表
```
这是“融合优先但不过度融合”的平衡点。
---
## 1.3 Phase-1 极简 schema 视图
如果只从“第一阶段必须落哪些表”来理解，推荐优先采用“融合优先”的最小表集合：
| 层 | 融合优先推荐表 | 当前作用 |
|---|---|---|
| 实体层 | `media_entity` | 当前默认只承载 `song` |
| 音频对象层 | `audio_object` | 统一承载 `asset/window` |
| 特征层 | `feature_fact` | 统一承载 `fingerprint/embedding` |
| 集合层 | `set_membership` | 统一承载 `reference/hot/eval` 等集合关系 |
也就是说，Phase-1 如果按物理实现优先，真正应该先落稳的是：
```text
media_entity -> audio_object -> feature_fact -> set_membership
```
如果按逻辑语义理解，则当前默认对应：
```text
song -> asset/window -> fingerprint/embedding -> reference membership
```
### 这版极简 schema 明确不要求第一天就重投入的内容
可以后补：
- `work`
- 更重的 `retrieval_index_registry`
- 更细的 `retrieval_candidate / match_decision` 在线审计表
- 复杂的多 lane 重排治理表
### 但是极简不等于扁平
即使走极简版，也**不建议**退回到下面这种扁平结构：
```text
song -> embedding
song -> fingerprint
```
原因：
- 没有 `recording`，版本信息会丢
- 没有 `asset`，文件来源与去重会乱
- 没有 `window`，evidence/offset/多段聚合会弱很多
- 没有 `feature_set_registry`，模型升级会把 schema 写死
### 一个最实用的实现口径
如果团队现在就要开干，最推荐的实施顺序是：
1. 先落 `song / recording / recording_asset / audio_window`
2. 再落 `feature_set_registry / audio_fingerprint / audio_embedding`
3. 再落 `reference_set_registry / reference_set_member`
4. 最后再补 `work / retrieval_index_registry / match_decision` 等增强层
这样既能保持当前 Phase-1 简洁，也不会破坏未来扩展。
---
## 2. 数据主链
```mermaid
flowchart LR
A[canonical_song] --> B[work]
B --> C[recording]
C --> D[recording_asset]
D --> E[audio_window]
E --> F[audio_embedding]
E --> G[audio_fingerprint]
F --> H[retrieval_index_registry]
G --> H
H --> I[retrieval_candidate]
I --> J[match_decision]
```
---
## 3. 表分组
| 分组 | 表 | 作用 |
|---|---|---|
| 版权与实体 | `canonical_song`, `work`, `recording` | 统一业务归属 |
| 资产层 | `recording_asset` | 管理真实文件资产 |
| 窗口层 | `audio_window` | 管理检索最小证据片段 |
| 模型与特征 | `model_registry`, `feature_set_registry`, `audio_embedding`, `audio_fingerprint` | 管理模型版本与特征事实 |
| reference 集 | `reference_set_registry`, `reference_set_member` | 管理热 reference 集与版本化切换 |
| 索引层 | `retrieval_index_registry` | 记录后端索引 |
| 匹配层 | `retrieval_candidate`, `match_decision` | 在线召回与最终归一 |
---
## 4. 关键表说明
设计意图：
- 避免为不同模型建一堆平行 embedding 表
- 未来换 MERT / MuQ / 其他 encoder 时只增 feature rows，不改主 schema
- exact / semantic 两条 lane 可以共用同一归属链
## 4.1 `canonical_song`
最终业务主键。
### 6.4 `set_membership`
用途：
- 服务最终返回 `canonical_song_id`
- 权利归属、产品展示、对外业务都以它为准
- 统一管理 reference_set / eval_set / hot_set
- member 可以是 `song/asset/window/feature`
## 4.2 `work`
作品层。
用途：
- 同一首歌的不同翻唱/演绎归一到作品层
- future phase 的 cover/version lane 常常先聚到 `work_id`
## 4.3 `recording`
录音层。
用途：
- official/live/remaster/cover/ugc 等不同版本分开管理
- 允许多个 recording 最终映射到同一个 `canonical_song`
## 4.4 `recording_asset`
文件资产层。
用途：
- 同一个 recording 可有多个文件版本
- 可区分 master/reference/distribution/captured/query_sample
## 4.5 `audio_window`
窗口层。
用途：
- 建指纹
- 抽 embedding
- 在线输出 evidence window
- 对 intro/chorus 等片段做后续治理
## 4.6 `model_registry`
模型注册表。
用途：
- 记录 `model_name/model_version/output_embedding_dim`
- 未来切换 MERT/MuQ/其他底座时不改业务表
## 4.7 `feature_set_registry`
特征版本表。
用途：
- 记录窗长、hop、pooling、layer、metric
- 同一模型不同用法变成不同 feature_set
## 4.8 `audio_embedding`
embedding 元数据事实表。
用途：
- 记录某个 asset/window 由哪个 feature_set 生成了什么 embedding
- 可指向 pgvector，也可只指向外部 parquet/npy
## 4.9 `reference_set_registry` / `reference_set_member`
reference 集版本表。
用途：
- 把“当前线上热 reference 集”提升成显式对象
- 支持 A/B、灰度、回滚、历史回放
- 让 `is_reference` 从单条 recording 标签升级为“可切换集合”
## 4.10 `retrieval_index_registry`
索引注册表。
用途：
- 同一 feature_set 可挂多个 backend / shard / version
- 支持 pgvector / faiss / milvus 并存
## 4.11 `retrieval_candidate`
召回候选。
用途：
- 保存 exact lane / semantic lane / future cover lane 的候选
- 便于线下分析与线上回放
## 4.12 `match_decision`
最终判定。
用途：
- 输出 `canonical_song_id / work_id / recording_id`
- 保留判定理由与分数
设计意图：
- reference 范围不硬编码到 song 表里
- 评测集、热集、灰度集能共用一张关系表
---
## 5. 示例流程图
## 7. 为什么“切片数据 + 模型 + feature”这样分布最合理
## 5.1 离线建库流程
### 切片数据放 `audio_object`
因为切片本质是音频对象的一种：
- 它有父 asset
- 它有 `start_ms/end_ms`
- 它需要被回溯和复用
```mermaid
flowchart TD
A[导入音频资产] --> B[写 recording_asset]
B --> C[切窗并写 audio_window]
C --> D[注册 model_registry / feature_set_registry]
D --> E[抽取 embedding / fingerprint]
E --> F[写 audio_embedding / audio_fingerprint]
F --> G[构建 retrieval index]
G --> H[登记 retrieval_index_registry]
```
### 模型信息放 `feature_fact`
因为模型是“某次特征计算”的属性：
- 同一个 window 可能被多个模型重复编码
- 同一个模型也可能有多个版本
- 模型名和版本应该和 feature 结果绑定，而不是只和 asset 绑定
## 5.2 在线检索流程
### feature 放 `feature_fact`
因为 feature 是事实：
- 某个对象
- 用某个模型
- 以某个 feature set
- 产出某个结果
```mermaid
sequenceDiagram
participant Q as Query Audio
participant DB as PostgreSQL
participant IDX as Retrieval Index
participant SVC as Matching Service
Q->>SVC: 输入 query
SVC->>DB: 读取 active feature_set
SVC->>IDX: exact lane / semantic lane 查询
IDX-->>SVC: 候选 window / recording
SVC->>DB: 回查 window -> recording -> work -> canonical_song
SVC->>DB: 写 retrieval_candidate
SVC->>DB: 写 match_decision
SVC-->>Q: 返回 canonical_song_id + evidence
```
这正好就是一条事实记录。
---
## 5.3 生产冻结前建议补硬的 4 个点
### A. lineage 硬约束
建议通过 trigger / transaction invariant 保证以下链路永远一致：
- `recording.work_id -> work.work_id`
- `recording.canonical_song_id -> work.canonical_song_id`
- `audio_window.asset_id -> recording_asset.recording_id -> recording/work/song`
- `audio_embedding.window_id -> audio_window.recording/work/song`
### B. reference set 版本化
建议把“热 reference 集”提升成显式对象，而不是只依赖 `is_reference`。
这样可以支持：
- hot/cold reference 切换
- A/B 对照
- encoder 升级期间的双索引并存
- 历史回放
### C. 候选实体多态约束
`candidate_level + candidate_id` 很灵活，但生产化时至少要加枚举/约束，避免数据面上出现无效 level。
### D. 向量维度扩展规则
当前 `192/768` 物理表是热路径实现，不是最终维度上限。新增 encoder 维度时应遵循固定 playbook：
1. 新增一张 `audio_embedding_vector_<dim>` 物理表
2. 回填对应 `feature_set` 的 embeddings
3. 构建对应索引
4. 通过 `retrieval_index_registry` 切换 active 热索引
## 8. 第一个阶段如何服务 100w 音频 / 30w 歌曲
---
### 建议的落盘顺序
## 6. 推荐 DDL 的主要原则
1. 先写 `media_entity(song)`
2. 再写 `audio_object(asset)`
3. 再批量切 `audio_object(window)`
4. 再按模型批次写 `feature_fact`
5. 最后写 `set_membership(reference_set/hot_set/eval_set)`
## 原则 1：对象关系稳定，模型可变
稳定的是：
- `song/work/recording/asset/window`
### 为什么这样落
可变的是：
- `model_name`
- `feature_set`
- `index_backend`
## 原则 2：向量不要写死为唯一真相
推荐把向量事实拆成：
- PostgreSQL 元数据主表
- 向量可在 pgvector 分表或外部文件中存放
## 原则 3：窗口是最小证据粒度
因为版权保护最终不只是“命中这首歌”，还要回答：
- 命中的是哪一段
- 哪个录音版本
- 归属到哪个 work/song
因为这能把“音频对象生命周期”和“模型计算生命周期”解耦：
- 音频先入库
- 切片先固定
- exact lane 可先跑
- semantic lane 之后补跑也不影响主链
---
## 7. 推荐的物理实现思路
## 9. Phase-1 推荐策略
## 7.1 PostgreSQL 负责
- 主数据
- 模型注册
- 特征注册
- 索引注册
- 检索候选
- 审核/决策
### 9.1 exact lane
- 默认：`ChromaprintMatcher`
- 落到：`feature_fact(feature_type='fingerprint')`
## 7.2 pgvector 负责
- 热 reference 集合
- 线上低延迟近邻查询
### 9.2 semantic lane
- 当前优先：`MERT`
- challenger：`MuQ`
- 当前 host 若 runtime 不可用，保留 fallback
- 落到：`feature_fact(feature_type='embedding')`
## 7.3 外部对象存储/文件层负责
- 原始音频
- 标准化音频
- 大体量 embedding parquet/npy
- 索引 shard 文件
### 9.3 为什么不是 ECAPA-TDNN 主导
- ECAPA 更偏 speaker/audio identity 方向
- 当前目标是版权保护 / song-level ACR
- `MERT` / `MuQ` 更适合作为 song semantic baseline/challenger
---
## 8. 为什么这个设计更适合 SOTA 演进
因为未来你最可能变化的不是 `canonical_song` 结构，而是：
| 会变化的东西 | 对应表 |
|---|---|
| 底座模型 | `model_registry` |
| 特征版本 | `feature_set_registry` |
| embedding dim | `model_registry.output_embedding_dim` |
| 池化与层选择 | `feature_set_registry.pooling_strategy/layer_selection` |
| 索引后端 | `retrieval_index_registry.index_backend` |
## 10. 当前方案解决的问题
所以 schema 的目标是：
> **允许模型变、索引变、特征变，但不让主数据和业务归属逻辑跟着崩。**
这套 4 表设计，当前主要解决：
- 同一 `song` 下多音频文件管理
- 切片级 evidence 管理
- fingerprint 与 embedding 统一落库
- 模型切换时不重构主 schema
- reference/eval/hot 集统一治理
- 检索命中后快速回到 `song_id`
---
## 9. DDL 文件说明
推荐直接使用：
- [`acr-engine/sql/acr_pg_schema_v2.sql`](../acr-engine/sql/acr_pg_schema_v2.sql)
其中包含：
- 主数据表
- 模型注册表
- 特征表
- 向量物理表（192/768 维示例）
- 索引建议
而原有：
- [`acr-engine/sql/pgvector_schema.sql`](../acr-engine/sql/pgvector_schema.sql)
## 11. 当前不刻意解决的问题
建议视为：
- 原型版 / demo 版 / 兼容参考
Phase-1 暂不强求：
- 复杂 `work / recording / version` 治理
- 完整权利层图谱
- 训练/微调闭环
- 重型 registry-first 体系
---
## 10. 实施顺序建议
### 第一批必须先落
1. `canonical_song`
2. `work`
3. `recording`
4. `recording_asset`
5. `audio_window`
6. `model_registry`
7. `feature_set_registry`
8. `audio_embedding`
9. `retrieval_index_registry`
### 第二批再补
1. `retrieval_candidate`
2. `match_decision`
3. `audio_fingerprint`
4. 更多维度的向量物理表
这些都可以后续逐步加，但不该反向阻塞当前主链。
---
## 11. 典型注册与查询示例
## 11.1 注册一个开源模型
```sql
insert into model_registry (
model_name, model_family, model_version, model_source, model_uri,
input_sample_rate, default_window_sec, default_hop_sec, output_embedding_dim,
pooling_supported, layer_selection_supported, is_trainable
) values (
'mert', 'music_ssl', 'v1-95m', 'github', 'https://github.com/yizhilll/MERT',
24000, 5.0, 2.5, 768,
array['mean','cls'], true, false
);
```
## 11.2 注册一个 feature set
```sql
insert into feature_set_registry (
model_id, feature_name, feature_level, extraction_granularity,
window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select
model_id, 'semantic_embedding', 'window', 'sliding_window',
5.0, 2.5, 768, 'mean', 'final',
true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'mert' and model_version = 'v1-95m';
```
## 11.3 查询当前激活的 reference feature set
```sql
select fs.feature_set_id, mr.model_name, mr.model_version,
fs.window_sec, fs.hop_sec, fs.pooling_strategy, fs.distance_metric
from feature_set_registry fs
join model_registry mr on mr.model_id = fs.model_id
where fs.status = 'active'
and fs.feature_level = 'window'
and fs.feature_name = 'semantic_embedding'
order by fs.feature_set_id desc;
```
## 11.4 从候选 window 回查到最终 song
```sql
select rc.query_id, rc.rank_no, rc.normalized_score,
aw.window_id, aw.start_sec, aw.end_sec,
r.recording_id, r.version_type,
w.work_id,
cs.canonical_song_id, cs.title, cs.primary_artist
from retrieval_candidate rc
join audio_window aw on aw.window_id = rc.evidence_window_id
join recording r on r.recording_id = aw.recording_id
join work w on w.work_id = aw.work_id
join canonical_song cs on cs.canonical_song_id = aw.canonical_song_id
where rc.query_id = :query_id
order by rc.rank_no asc;
```
## 11.5 查询某个 song 的全部 reference 资产和窗口
```sql
select cs.canonical_song_id, cs.title,
r.recording_id, r.version_type, r.is_reference,
ra.asset_id, ra.storage_uri,
aw.window_id, aw.window_index, aw.start_sec, aw.end_sec
from canonical_song cs
join recording r on r.canonical_song_id = cs.canonical_song_id
join recording_asset ra on ra.recording_id = r.recording_id
left join audio_window aw on aw.asset_id = ra.asset_id
where cs.canonical_song_id = :canonical_song_id
order by r.reference_priority asc, ra.asset_id asc, aw.window_index asc;
```
## 11.6 查询某个 feature set 是否已完成索引构建
```sql
select fs.feature_set_id, mr.model_name, mr.model_version,
ri.index_backend, ri.index_type, ri.row_count, ri.index_status, ri.built_at
from feature_set_registry fs
join model_registry mr on mr.model_id = fs.model_id
left join retrieval_index_registry ri on ri.feature_set_id = fs.feature_set_id
where fs.feature_set_id = :feature_set_id;
```
---
## 12. 当前建议结论
如果你今天就要开始 PostgreSQL 落库，最推荐的做法是：
## 12. 相关文档
1. 先把 `song/work/recording/asset/window` 落稳
2. 同时把 `model_registry / feature_set_registry` 落稳
3. Phase-1 只注册开源 encoder feature set，不写死到某个 embedding 列
4. 先把热 reference 集上 pgvector，冷数据通过外部文件或后续索引层接入
- [README.md](./README.md)
- [start-here.md](./start-here.md)
- [session-handoff.md](./session-handoff.md)
- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
......
# Production Encoder Freeze & Embedding Strategy / 生产 Encoder 冻结与 Embedding 策略答疑
> 更新：2026-06-03
> 关联文档：[持续开发交接文档](./session-handoff.md) · [PostgreSQL 数据模型](./postgresql-data-model.md) · [Phase-1 实施清单](./phase1-implementation-checklist.md)
## 一页结论
围绕你当前最关心的生产问题，可以先压缩成 6 句话：
1. **当前先冻结 encoder 是正确决定。** 对 30 万首生产曲库来说，先稳定 embedding 空间，比继续频繁改模型更重要。
2. **当前结构具备泛化能力。** 线上识别主路径是“固定 encoder 抽 embedding + reference 检索”，不是只能识别训练时见过的 closed-set 分类标签。
3. **模型权重可以外置复用。** 你可以把当前 `best_model.pt` 当成独立 encoder，用在别的 wav/mp3/flac/ogg 歌曲集合上。
4. **如果 encoder 变了，向量库就必须重建。** 歌曲元数据不用重做，但所有旧 embedding / ANN index / pgvector 向量都应视为旧版本。
5. **30 万首场景下必须做 embedding 版本化。** 不建议“直接覆盖旧库”，而应并行维护 `encoder_version=v1/v2/...`。
6. **最稳的上线策略是：先冻结 v1，上线使用；新模型只做离线 shadow build + A/B，收益足够大再切换。**
---
## 1. 当前项目进度：已经走到哪里
## 1.1 当前状态
根据 [持续开发交接文档](./session-handoff.md)，当前项目已经从“原型是否能跑通”进入“真实数据验证 + 工程化推进”阶段：
- synthetic 数据链路已跑通：生成、训练、建索引、识别、评测都已具备
- 开放数据链路已闭环：`inspect-local -> prepare-local -> validate-local -> train -> build-index -> evaluate -> generate_artifacts`
- 当前最佳候选方向已收敛到 `hum_focus`
- 真实 FMA smoke 已跨过训练，进入了 `build-index` 阶段
这说明当前不是“从零开始想方案”，而是已经具备：
1. **一个可以独立抽 embedding 的 encoder**
2. **一个可以对 reference 曲库建索引的 pipeline**
3. **一个可以对 query 做识别的 hybrid 检索链路**
## 1.2 当前最适合的策略
在这个阶段，最重要的不是继续频繁换 encoder，而是：
```mermaid
flowchart TD
A[已有可运行模型与索引链] --> B[冻结生产 Encoder v1]
B --> C[完成 30 万首建库与使用]
C --> D[收集真实线上/离线问题]
D --> E[离线评估新 Encoder v2]
E --> F[证明显著收益后再迁移]
```
也就是：**先让一版可用的 embedding 体系稳定下来，再做后续升级。**
---
## 2. 当前结构是否有泛化能力
## 2.1 简短回答
**有。**
但这里的“泛化”要分成两层理解：
| 泛化层次 | 当前是否支持 | 说明 |
|---|---|---|
| 新歌曲入库后可被识别 | 支持 | 只要用同一 encoder 生成 reference embedding 即可 |
| 完全未知分布上保持稳定高精度 | 尚未完全证明 | 当前更多是结构可行、真实大规模效果还需继续验证 |
## 2.2 为什么说当前结构具备泛化能力
当前识别主链路不是：
- “输入 query -> 分类头直接输出某个固定 song class”
而是：
- “输入 query -> encoder 抽 embedding -> 在 reference embedding 库中做相似度检索”
结构图如下：
```mermaid
flowchart LR
Q[query wav/mp3 片段] --> E1[冻结 Encoder v1]
E1 --> QE[query embedding]
QE --> S[similarity search]
R[30 万首 reference 曲库] --> E2[同一个冻结 Encoder v1]
E2 --> RE[reference embeddings]
RE --> S
S --> O[候选歌曲 + 分数]
```
这种结构天然支持：
- 新歌曲加入 reference 曲库
- 不重训模型的情况下扩歌库
- 针对 query 做检索而不是固定类分类
## 2.3 但泛化能力的上限受什么影响
当前真实效果主要还受这些因素制约：
1. **训练数据分布**
- 目前 hard case 已关注 `humming_like` / `confused`
- 但你的线上 30 万首曲库是否和当前训练/验证分布一致，仍需要真实数据验证
2. **reference 建库方式**
- 当前 reference 端是 **5 秒窗口 + 2.5 秒 stride** 的重叠滑窗
- 这对片段识别是好的，但代价是窗口数上升、建库成本变高
3. **query 形式差异**
- 无损整曲、压缩 mp3、录音片段、截短片段、混响/手机采样等都会影响效果
4. **混合检索策略**
- 当前不是纯 embedding 检索，而是 `chromaprint + embedding + melody rerank` 的 hybrid
- 这对鲁棒性是加分项，但也意味着线上治理时要同时考虑指纹索引和向量索引
---
## 3. 为什么当前先冻结 Encoder
## 3.1 业务原因
你现在的生产环境里有 **30 万首歌曲**。这会带来一个决定性的工程事实：
> **一旦 encoder 改了，就不是“换个模型文件”这么简单，而是整套向量空间都可能变。**
如果还没冻结 encoder，就会出现这些问题：
- 今天建的 30 万 embedding，明天可能全部作废
- pgvector / Faiss / Milvus / 自研 ANN 索引都要全量重建
- 离线评测和线上灰度无法稳定对齐
- 回滚困难：你很难知道 query 是按哪个模型算的，reference 又是按哪个模型建的
## 3.2 工程原因
冻结 encoder 后，你才能稳定以下这些对象：
| 资产 | 是否应随 encoder 冻结 | 原因 |
|---|---|---|
| `best_model.pt` | 是 | 它决定向量空间 |
| `n_mels/sample_rate/window/stride` | 是 | 这些决定 embedding 分布 |
| `embedding_dim` | 是 | 向量表结构和索引依赖它 |
| reference embeddings | 是 | 必须和 query embedding 同版本 |
| ANN index / pgvector 索引 | 是 | 建立在具体 embedding 空间上 |
## 3.3 当前建议的冻结定义
建议把当前生产 encoder 冻结为一组明确配置，而不是只记一个文件名。
推荐至少记录这些字段：
```yaml
encoder_version: ecapa_hum_focus_v1
checkpoint_path: /abs/path/to/best_model.pt
embedding_dim: 192
sample_rate: 16000
n_mels: 128
n_fft: 512
hop_length: 160
reference_window_sec: 5.0
reference_stride_sec: 2.5
query_runtime_window_sec: 5.0
feature_family: mel
index_family: hybrid_chromaprint_ecapa
status: frozen_for_production
```
---
## 4. 模型权重能否外置，给其他歌曲使用
## 4.1 简短回答
**可以，而且应该这样做。**
你可以把当前冻结好的 `best_model.pt` 视为一个独立的音乐 embedding encoder，用来处理：
- 新增歌曲入库
- 旧歌库全量建 embedding
- 任意 query 音频片段识别
- 后续 pgvector / ANN 向量服务对接
## 4.2 外置使用时的推荐组织方式
推荐把“模型”和“索引产物”分开管理：
```mermaid
flowchart TD
A[models/] --> A1[ecapa_hum_focus_v1/best_model.pt]
A --> A2[ecapa_hum_focus_v1/encoder_manifest.yaml]
B[indexes/] --> B1[ecapa_hum_focus_v1/chromaprint.pkl]
B --> B2[ecapa_hum_focus_v1/reference_embs.npy]
B --> B3[ecapa_hum_focus_v1/reference_ids.npy]
B --> B4[ecapa_hum_focus_v1/index_metadata.json]
C[metadata/] --> C1[song_catalog.csv]
C --> C2[manifests/catalog.json]
```
## 4.3 外置后能做什么
### 场景 A：直接给新歌曲建库
- 你有一批新歌（wav/mp3/flac/ogg）
- 不重训
- 用冻结 encoder 直接建 reference embedding
- 加入曲库识别
### 场景 B：给 query 片段做识别
- 你有 5~10 秒左右的查询片段
- 用同一 encoder 抽 query embedding
- 在 reference 库做相似度匹配
### 场景 C：离线批量生成 pgvector/ANN 数据
- 你可以把 reference embeddings 作为离线产物导出
- 再灌入 PostgreSQL + pgvector / Faiss / Milvus / 自研检索服务
---
## 5. 你手头有无损、压缩、片段等 wav/mp3 文件集合，应该怎么直接使用
## 5.1 总体原则
你手头的文件不需要先人工区分“是不是训练专用格式”。
当前最重要的是把它们统一进入这套结构：
```mermaid
flowchart LR
A[原始 wav/mp3/flac/ogg] --> B[标准化目录]
B --> C[manifest]
C --> D[reference 建库]
C --> E[query 验证]
D --> F[线上识别/检索]
```
## 5.2 建议先分三类素材
| 类别 | 作用 | 建议处理方式 |
|---|---|---|
| 完整歌曲 / 主版本 | 做 reference | 全部入库 |
| 截断片段 / 业务 query 样本 | 做评测 query | 固定留作测试集 |
| 低码率/手机录音/混响压缩片段 | 做 hard case query | 用来验证鲁棒性 |
## 5.3 最短直接使用流程
### 第 1 步：冻结 encoder v1
先不要继续换模型，先把当前决定好的 checkpoint 固定下来。
### 第 2 步：准备音频目录
例如：
```text
input_music/
song_a.flac
song_b.mp3
song_c.wav
...
```
### 第 3 步：检查目录是否适合进入当前链路
```bash
cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python src/data/manifest_tools.py inspect-audio-dir \
/abs/path/to/input_music \
--query-duration 8.0 \
--eval-ratio 0.2
```
### 第 4 步：生成统一 manifest
```bash
cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python src/data/manifest_tools.py audio-dir-to-splits \
/abs/path/to/input_music \
/abs/path/to/output_dataset \
--source-dataset prod_music \
--eval-ratio 0.2 \
--query-duration 8.0 \
--query-strategy hybrid \
--query-stride 2.5
```
建议说明：
- `query-duration=8.0`：适合作为线下验证 query 长度
- `query-strategy=hybrid`：更贴近当前项目已有的音乐感知切片方向
- `query-stride=2.5`：如果你希望验证覆盖率更高，可以生成更多 query
### 第 5 步：用冻结 encoder 建 reference index
```bash
cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python run_demo.py build-index \
--data /abs/path/to/output_dataset/manifests \
--model /abs/path/to/frozen/best_model.pt \
--output /abs/path/to/output_index \
--device cpu
```
### 第 6 步：做离线识别验证
```bash
cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python evaluate.py \
--data /abs/path/to/output_dataset/manifests \
--model /abs/path/to/frozen/best_model.pt \
--index-prefix /abs/path/to/output_index/reference \
--split test \
--device cpu \
--fast-eval \
--output-json /abs/path/to/output_reports/eval.json
```
### 第 7 步：确认后再推到生产向量库
当离线评测满足最低要求后，再把 reference embedding 导入生产检索系统，而不是一上来直接刷 30 万首正式库。
---
## 6. 如果要快速微调，应该怎么做
## 6.1 原则
**“快速微调”不等于“马上用 30 万首全量重训”。**
对你当前场景，最合理的是：
1. 先冻结生产 encoder v1
2. 用一个代表性子集训练/微调候选 v2
3. 只在离线环境评估 v2
4. 证明收益大于迁移成本，才考虑升级生产 encoder
## 6.2 推荐的微调子集组成
建议优先抽一个 **几千到几万首规模的代表性集合**，覆盖：
- 无损高质量版本
- 常见压缩版本（mp3/aac 等）
- 短片段
- 开头/中段/结尾片段
- 旋律近似、编曲相似的易混淆歌曲
- 手机采样 / 录屏 / 二次压缩音频
- 业务上最常见失败样本
## 6.3 推荐微调流程
```mermaid
flowchart TD
A[冻结 Encoder v1] --> B[抽代表性子集]
B --> C[生成 manifests]
C --> D[训练 v2 候选]
D --> E[建 v2 索引]
E --> F[固定测试集评测]
F --> G{收益显著?}
G -- 否 --> H[继续使用 v1]
G -- 是 --> I[准备 30 万首离线重刷 v2]
```
## 6.4 微调时的判断标准
不要只看训练 loss，至少要看：
| 指标 | 作用 |
|---|---|
| top1 / topk | 基本识别率 |
| hard-case 命中率 | 看压缩/片段/混淆样本提升是否真实 |
| 新增模型对旧强项的回退 | 防止“补一个洞，漏一大片” |
| 全量建库速度 | 看新模型是否导致生产成本显著上升 |
| 线上 query 延迟 | 看推理成本是否可接受 |
## 6.5 微调后的发布原则
微调完成后不要立刻替换 v1，而要：
1. 标记为 `encoder_version=v2_candidate`
2. 只做离线建库和评测
3. 在真实样本上和 v1 做 A/B
4. 显著更优后再升级
---
## 7. 如果 embedding 变了，哪些数据必须重建
## 7.1 要区分“元数据”和“向量数据”
| 数据类型 | 是否需要重建 | 说明 |
|---|---|---|
| 歌曲主数据（song_id/路径/业务标签） | 通常不需要 | 这些不依赖向量空间 |
| manifest | 通常不需要全重做 | 除非你的切片策略/数据治理规则也变了 |
| reference embeddings | 必须重建 | 因为 encoder 变了 |
| query embeddings 缓存 | 必须重建 | 否则和 reference 不同空间 |
| pgvector 行数据 | 必须重建 | 向量本体变了 |
| ANN 索引（Faiss/Milvus/HNSW/IVF 等） | 必须重建 | 建立在旧向量之上 |
| chromaprint 索引 | 不一定 | 只要指纹算法不变，可独立复用 |
## 7.2 为什么必须重建
因为向量相似度检索默认假设：
> query embedding 和 reference embedding 来自同一个特征空间。
如果 query 用的是 `encoder v2`，reference 还停留在 `encoder v1`，就会出现：
- 分数不可比
- recall 明显下降
- 线上结果随机波动
- A/B 结论失真
## 7.3 推荐的迁移策略
不要“原地覆盖旧 embedding”，而应采用双版本并行：
```mermaid
flowchart LR
A[Encoder v1] --> B[index_v1]
C[Encoder v2] --> D[index_v2]
E[Query] --> F{使用哪个版本?}
F --> B
F --> D
```
推荐步骤：
1. 保留 `v1` 生产库不动
2. 离线刷 `v2` 的 30 万 embedding
3. 建 `v2` 的 ANN / pgvector 索引
4. 用相同 query 集对比 v1/v2
5. 确认收益后切主流量
6. 回滚时直接切回 v1
---
## 8. 30 万首生产环境推荐的版本化方案
## 8.1 推荐最小字段
### 歌曲元数据表
| 字段 | 说明 |
|---|---|
| `song_id` | 稳定歌曲 ID |
| `audio_uri` | 原始音频路径/对象存储地址 |
| `duration_sec` | 时长 |
| `codec/container` | 格式信息 |
| `catalog_status` | 是否可入 reference 库 |
| `business_tags` | 业务标签 |
### embedding 表
| 字段 | 说明 |
|---|---|
| `song_id` | 对应歌曲 |
| `encoder_version` | 如 `ecapa_hum_focus_v1` |
| `window_index` | 第几个 reference window |
| `offset_sec` | 窗口起点 |
| `embedding_dim` | 例如 192 |
| `embedding` | 向量本体 |
| `built_at` | 构建时间 |
| `source_audio_hash` | 原音频指纹/摘要，便于查重与失效控制 |
### index manifest
| 字段 | 说明 |
|---|---|
| `encoder_version` | 当前索引对应的 encoder |
| `checkpoint_path` | 模型文件 |
| `feature_config` | mel/n_mels/sample_rate 等 |
| `reference_window_sec` | 例如 5.0 |
| `reference_stride_sec` | 例如 2.5 |
| `catalog_size` | 曲库规模 |
| `num_reference_windows` | 总窗口数 |
| `built_at` | 构建时间 |
## 8.2 推荐目录结构
```text
prod_artifacts/
models/
ecapa_hum_focus_v1/
best_model.pt
encoder_manifest.yaml
indexes/
ecapa_hum_focus_v1/
chromaprint.pkl
chromaprint_progress.json
reference_embs.npy
reference_ids.npy
index_metadata.json
reports/
ecapa_hum_focus_v1/
eval.json
hard_case_eval.json
```
---
## 9. 当前建议的生产操作手册
## 9.1 目标
当前目标不是继续改模型，而是先完成：
1. 冻结 encoder v1
2. 用 v1 支撑第一版 30 万首曲库建库
3. 建立版本化规范
4. 为后续 v2 升级预留迁移机制
## 9.2 分步操作
### Phase 1：冻结与归档
- [ ] 选定当前生产 checkpoint
- [ ] 为该 checkpoint 生成 `encoder_manifest.yaml`
- [ ] 记录 `encoder_version`
- [ ] 固定 reference window / stride / mel 配置
- [ ] 禁止直接覆盖此 checkpoint
### Phase 2：小规模真实集验证
- [ ] 抽 1k~10k 首真实歌曲做第一次建库
- [ ] 抽真实 query 集做评测
- [ ] 统计 top1/topk/hard-case 结果
- [ ] 验证索引构建速度、磁盘占用、查询延迟
### Phase 3：30 万首全量离线建库
- [ ] 清洗 song_id 与元数据
- [ ] 生成标准 catalog/manifests
- [ ] 用冻结 encoder v1 批量生成 reference embeddings
- [ ] 生成 chromaprint / 向量索引
- [ ] 导入生产检索服务
### Phase 4：上线与观测
- [ ] 上线 v1
- [ ] 记录 query 失败样本
- [ ] 归档 hard-case
- [ ] 为 v2 微调准备离线样本集
### Phase 5：未来升级
- [ ] 训练 `v2_candidate`
- [ ] 离线全量重刷 `index_v2`
- [ ] 做离线 A/B
- [ ] 收益显著后再切换主版本
---
## 10. 常见问题 FAQ
## 10.1 我现在有一大堆 wav/mp3，可以直接用吗？
**可以。**
先不要纠结格式本身，先把它们组织成统一音频目录，再生成 manifests，再用冻结 encoder 建 reference index。
## 10.2 无损和压缩版本要不要分开？
**建议保留来源信息，但 reference 主库优先保留“主版本”。**
如果同一首歌有多个编码版本：
- 主版本作为 reference 主资产
- 其他压缩版本优先作为评测 query / hard case
这样更利于真实评估鲁棒性。
## 10.3 片段文件可以直接拿来做 query 吗？
**可以。**
尤其适合作为：
- clean query
- compressed query
- hard case query
但如果要把它当训练样本，最好仍然能回溯到稳定的 `song_id` 和原 reference。
## 10.4 如果后面发现 encoder 不够好怎么办？
不要直接替换现网。正确做法是：
1. 保持 v1 不动
2. 离线训练 v2
3. 离线重刷 v2 的全量 embedding
4. 对比 v1/v2
5. 确认收益后再切
## 10.5 现在有没有必要立刻上全量 30 万首？
**建议先做一轮中等规模验证，再上全量。**
推荐先做：
- 1k 首小验证
- 1w~5w 首中等规模验证
- 验证速度/精度/存储后，再上 30 万
## 10.6 现阶段最重要的一句话建议是什么？
> **先冻结 encoder v1，把 embedding/version/index 治理做好，再讨论 v2。**
---
## 11. 最终建议
对你现在的阶段，我的建议优先级是：
1. **冻结当前 encoder**
2. **建立 embedding 版本化规范**
3. **先做小到中规模真实集建库验证**
4. **再推进 30 万首全量建库**
5. **把新模型升级变成“离线重刷 + A/B + 切换”的标准动作**
这样做的好处是：
- 你现在就能开始用
- 后面也不会因为继续调模型把生产库拖乱
- 未来升级有明确路径，不会出现“模型变了，数据全乱了”的问题
## Sources
- [持续开发交接文档](./session-handoff.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-engine/src/data/manifest_tools.py](../acr-engine/src/data/manifest_tools.py)
# Session Handoff / 持续开发交接文档
> 更新：2026-06-04
> 目的：让下次启动的新 session 在 **3~10 分钟内** 明确：
> 1. 当前项目已经走到哪里
> 2. 应该先读哪些文档
> 3. 应该从哪一步开始推进
> 4. 哪些是稳定结论，哪些还是待验证缺口
> 目标：让下次启动的新 session 在 **3~10 分钟内** 知道从哪里开始。
---
## 0. 下次启动先做什么
## 1. 下次启动先做什么
如果下次启动要继续当前主线（**song-centric 真实目录 -> feature -> PostgreSQL**），先执行：
优先直接跑当前主线：
```bash
cd /workspace
......@@ -22,8 +17,15 @@ cd /workspace
--output-dir acr-engine/data/pgvector_eval/music20
```
或：
```bash
acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
```
当前 fresh evidence：
- `song_count = 2`
- `asset_count = 2`
- `window_count = 5`
- `matcher_fingerprint_count = 5`
- `fallback_fingerprint_count = 0`
......@@ -31,198 +33,128 @@ cd /workspace
- `semantic_runtime_missing = [torch, torchaudio, transformers]`
- `import_counts = media_entity:9 / audio_object:22 / feature_fact:24 / set_membership:9`
如果只是回归历史 Phase-1 planner/worker 合同，再执行：
```bash
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`
这条 runner 会一次性执行：
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. 补 `torch / torchaudio / transformers / speechbrain`
而不是回头怀疑 PostgreSQL contract。
---
## 1. 当前项目一句话状态
## 2. 当前一句话状态
项目已经从“原型能否跑通”转为：
> **4 表 song-centric schema 已在 live PostgreSQL 上真实打通了“真实目录 -> 切片 -> exact/semantic feature enrichment -> import -> feature_fact”的宿主链。**
> **面向版权保护 / 听歌识曲 / 版本归属的可演进音乐 ACR 系统。**
当前目标是让 `100w` 音频、约 `30w` 歌曲能通过稳定的数据主链和模型注册机制，支撑检索、归属、升级与回滚。
下一步最应该做的是：
> **在不破坏这条宿主链的前提下，把 semantic lane 从 runtime-aware fallback 升级到真实 MERT / MuQ adapter。**
---
## 2. 当前稳定结论
## 3. 当前稳定结论
### 技术路线
- exact lane：`Chromaprint`
- semantic baseline：`MERT-v1-95M`
- semantic challenger：`MuQ`
- `ECAPA`：historical baseline
- Phase-1：先走 **encoder-only**，先不用微调底座
### 3.1 默认物理模型
### 数据主链
```text
canonical_song -> work -> recording -> recording_asset -> audio_window
media_entity -> audio_object -> feature_fact -> set_membership
```
### 模型主链
### 3.2 默认逻辑语义
```text
model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint -> retrieval_index_registry
song -> asset -> window -> fingerprint / embedding
```
### reference set 结论
- 保留 `is_reference=true`
- 但生产切换必须依赖 `reference_set_registry / reference_set_member`
- 后续 A/B、热切换、回滚都围绕 reference set 版本化进行
### 3.3 关键设计取舍
- 最终归属对象当前只要求稳定返回 `song_id`
- 同一个 `song` 下允许多个音频文件
- `window` 仍保留，因为它是切片/evidence/offset/召回最小单元
- `feature_fact` 统一承载 `fingerprint` 与 `embedding`
- Phase-1 不先训练/微调，先直接复用开源 encoder
---
## 3. 当前已经完成的关键交付
## 4. 切片 / 模型 / feature 分别在哪张表
### 文档与设计
- 文档主入口已收敛到 `README -> start-here -> session-handoff`
- SOTA 演进路径已明确
- PostgreSQL 主数据与特征模型已固定为 v2 推荐方案
- Phase-1 实施 checklist / registry bootstrap / worker contract 文档已齐备
### PostgreSQL / live contract
- `acr-engine/sql/acr_pg_schema_v2.sql` 已落地
- `model_registry / feature_set_registry / reference_set_registry` 已 live bootstrap 验证
- `audio_embedding` 的 asset-level 幂等 upsert 已 live 验证
- semantic vector-table 负例矩阵已 live 验证
- planner validation commands 已可被 runner 一键执行
### worker / script
- `run_chromaprint_job.py` 已具备真实写入路径
- `run_embedding_job.py` 已具备 preflight failure contract
- `run_phase1_prereq_audit_live.py` 已能输出 host 前置条件审计
- `run_planner_validation_commands_live.py` 已收敛最短验证链路
| 对象 | 表 | 关键字段 |
|---|---|---|
| song | `media_entity` | `entity_type='song'` |
| asset | `audio_object` | `object_type='asset'` |
| window | `audio_object` | `object_type='window'`, `parent_object_id=<asset_id>` |
| model identity | `feature_fact` | `model_name`, `model_version`, `feature_set_name` |
| fingerprint payload | `feature_fact` | `feature_type='fingerprint'`, `fingerprint_value` |
| embedding payload | `feature_fact` | `feature_type='embedding'`, `embedding_uri/vector_table_name`, `embedding_dim` |
| set routing | `set_membership` | `set_type`, `set_name`, `member_type`, `member_id` |
---
## 4. 当前明确的 blocker
### 环境 blocker
- `/workspace/downloads` 缺失
- 缺少 `torch`
- 缺少 `torchaudio`
- 缺少 `transformers`
- 缺少 `speechbrain`
### 能力 blocker
- 还未真实跑通 `MERT / MuQ` inference
- 还未完成线上融合策略
- 还未接入更大规模真实 reference set
因此当前最该优先推进的是：
> **把环境补齐，再把 semantic lane 从 guarded failure 推到真实抽特征。**
---
## 5. 下次启动先读什么
按这个顺序即可：
1. [README.md](./README.md)
2. [start-here.md](./start-here.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)
6. [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md)
7. [phase1-worker-contract.md](./phase1-worker-contract.md)
8. [CHANGELOG.md](./CHANGELOG.md)
## 5. 当前流程图
```mermaid
flowchart TD
A[song / media_entity] --> B[asset / audio_object]
B --> C[window / audio_object]
C --> D1[fingerprint / feature_fact]
C --> D2[embedding / feature_fact]
A --> E[set_membership]
B --> E
C --> E
D1 --> F[召回与归属到 song_id]
D2 --> F
```
---
## 6. 下次启动优先动作
## 6. 当前已经真实验证过什么
### 路线 A：继续环境恢复
1. 检查 `/workspace/downloads` 是否已挂载
2. 检查 `torch / torchaudio / transformers / speechbrain` 是否已可导入
3. 重跑 planner validation runner
4. 确认 `ready_jobs` 是否从 `0` 开始提升
### live PostgreSQL
- DSN: `postgres://d2:d2pass@127.0.0.1:5432/d2`
- schema: `acr_songcentric_test`
### 路线 B：继续语义特征抽取实现
1. 查看 `acr-engine/workers/run_embedding_job.py`
2. 保持现有失败语义 contract
3. 接入真实 inference adapter
4. 复用现有 `audio_embedding` upsert 逻辑
### 路线 C：继续数据规模化落库
1. 查看 [postgresql-data-model.md](./postgresql-data-model.md)
2. 查看 [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
3. 规划 100w 音频导入批次
4. 固定 `reference_set` / `feature_set` / `index` 版本治理
### 已验证链路
1. `acr-engine/sql/acr_pg_schema_songcentric_v1.sql` 可真实建表
2. `bootstrap_songcentric_phase1_live.py` 可重复 seed
3. `import_songcentric_manifest_live.py` 可幂等导入 `song/asset/window/membership`
4. manifest 中 `windows[].features[]` 已可直接落 `feature_fact`
5. 真实目录 -> manifest -> import 已验证通过
6. 真实目录 -> fingerprint enrichment -> import 已验证通过
7. exact lane 已优先复用仓库内 `ChromaprintMatcher`
8. semantic lane 已 runtime-aware，但当前 host 因依赖缺失仍走 fallback
---
## 7. 当前不要再重复讨论的结论
## 7. 当前 host 的真实 blocker
- 不要回退到只有 `song_id` 的扁平表
- 不要把 embedding 设计成固定列
- 不要在 Phase-1 先讨论重新训练底座
- 不要把当前问题误判成 PostgreSQL schema 问题
- 缺 `torch`
- 缺 `torchaudio`
- 缺 `transformers`
- 因此当前 `semantic_runtime_available = false`
---
这说明当前主要 blocker 是：
> **语义 encoder runtime 还没就绪，不是 schema 没设计好。**
## 8. 关键文件入口
---
### 文档
- [README.md](./README.md)
- [start-here.md](./start-here.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
- [phase1-worker-contract.md](./phase1-worker-contract.md)
## 8. 下次继续时先看哪些文件
### 代码与脚本
- `acr-engine/sql/acr_pg_schema_v2.sql`
- `acr-engine/workers/run_chromaprint_job.py`
- `acr-engine/workers/run_embedding_job.py`
- `acr-engine/scripts/run_planner_validation_commands_live.py`
- `acr-engine/scripts/run_phase1_prereq_audit_live.py`
1. [README.md](./README.md)
2. [start-here.md](./start-here.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
5. [CHANGELOG.md](./CHANGELOG.md)
关键代码：
- `acr-engine/sql/acr_pg_schema_songcentric_v1.sql`
- `acr-engine/scripts/run_songcentric_directory_pipeline_live.py`
- `acr-engine/scripts/build_songcentric_manifest_from_directory.py`
- `acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py`
- `acr-engine/scripts/import_songcentric_manifest_live.py`
- `acr-engine/scripts/start_songcentric_shortest_path.sh`
---
## 9. 当前验证状态摘要
### 已验证
- planner validation runner 可执行且 `all_passed = true`
- exact lane 当前会诚实落成 `failed/unreadable_audio_assets`
- semantic lane 当前会诚实落成 `preflight_failed`
- asset-level embedding upsert 幂等合同已验证
- vector table 负例矩阵已验证
- prerequisites audit 已验证
## 9. 下一步优先顺序
### 未验证
- MERT / MuQ 真实 inference
- 更大规模生产 reference set 导入
- 最终线上融合与重排策略
1. 保持当前 4 表 schema 不回退
2. 给 `enrich_songcentric_manifest_with_local_features.py` 接真实 semantic adapter
3. 保留 fallback 分支，不破坏当前 host 的可运行性
4. 重新跑主链 runner，确认 semantic lane 有 fresh 证据
---
## 一句话 handoff
> 下次接手不要再从总方案开始，先跑 runner；若结果仍显示 downloads/runtime 缺失，就优先补环境，再推进 semantic lane 真实抽特征。
> 下次不要再从总方案争论开始，直接跑 song-centric runner；如果 exact 正常、semantic 仍 fallback，就继续补真实 semantic adapter 和依赖。
......
# 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 的核心不是“哪一个模型最终赢”，而是“数据规范 + 模型注册 + 特征注册 + 索引注册”这套长期结构先稳定下来。
# Start Here / 新同学接手入口
> 目标：让新来的同学在 **10 分钟内**知道：先跑什么、先读什么、当前卡在哪、下一步该做什么。
> 目标：让新同学在 **10 分钟内** 知道现在的主链、先跑什么、先看什么。
---
## 1. 先执行这条命令
如果当前目标是验证 **song-centric 真实目录 -> feature -> PostgreSQL** 主链，优先跑：
```bash
cd /workspace
/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
......@@ -17,167 +15,116 @@ cd /workspace
--output-dir acr-engine/data/pgvector_eval/music20
```
或：
```bash
acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
```
当前 fresh evidence：
- `song_count = 2`
- `asset_count = 2`
- `window_count = 5`
- `matcher_fingerprint_count = 5`
- `fallback_fingerprint_count = 0`
- `semantic_runtime_available = false`
- `import_counts.feature_fact = 24`
如果你当前目标是验证老的 Phase-1 planner/worker 合同，再跑下面这条：
```bash
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. `prereq_audit`
2. `worker_contract_smoke`
3. `semantic_vector_negative_matrix`
4. `asset_level_upsert_validation`
### 看到下面这些结果时应该如何判断
如果你看到：
- `downloads_root_exists = false`
- `ready_jobs = 0`
- exact lane = `failed/unreadable_audio_assets`
- semantic lane = `4/4 failed`
说明当前优先级是：
1. 挂载 `/workspace/downloads`
2. 安装 `torch / torchaudio / transformers / speechbrain`
也就是说：
> 当前首要问题是运行环境前置条件，不是 PostgreSQL schema，也不是 worker contract 设计错误。
- `semantic_runtime_missing = [torch, torchaudio, transformers]`
- `import_counts = media_entity:9 / audio_object:22 / feature_fact:24 / set_membership:9`
---
## 2. 接手时只读这 5 份文档
## 2. 只读这 4 份文档
1. [README.md](./README.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)
如果你负责算法或检索，再补：
- [sota-evolution-guide.md](./sota-evolution-guide.md)
- [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md)
- [phase1-worker-contract.md](./phase1-worker-contract.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
---
## 3. 用一句话理解项目
## 3. 用一句话理解当前项目
我们在做的是一个面向 **版权保护 / 听歌识曲 / 版本归属** 的音乐 ACR 系统，
目标是从 `100w` 音频、约 `30w` 歌曲中，快速定位正确的 `song_id` 归属；当前阶段暂不把版本/recording 作为必须返回对象。
我们当前做的是一个 **面向版权保护的 song-centric 音乐 ACR 系统**：
目标是在约 `100w` 音频、约 `30w` 歌曲里，把录音、BGM、片段、翻唱相关查询尽快定位到应归属的 `song_id`。
---
## 4. 当前主线方案
## 4. 当前最重要的设计结论
### 检索主线
- exact lane：`Chromaprint`
- semantic lane baseline：`MERT-v1-95M`
- semantic lane challenger：`MuQ`
- historical baseline：`ECAPA`
### 4.1 不再默认走旧的多层 v2 体系
当前默认只认 4 张核心物理表：
### 当前 Phase-1 最小主线
```text
song -> asset -> window
media_entity -> audio_object -> feature_fact -> set_membership
```
### 可演进完整版主线
```text
canonical_song -> work -> recording -> recording_asset -> audio_window
```
### 4.2 逻辑语义这样理解
### 模型主线
```text
model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint -> retrieval_index_registry
song -> asset -> window -> fingerprint / embedding
```
---
### 4.3 切片 / 模型 / feature 到底落哪里
## 5. 当前哪些已经稳定
| 对象 | 表 | 关键字段 |
|---|---|---|
| song | `media_entity` | `entity_type='song'` |
| 原始音频文件 | `audio_object` | `object_type='asset'` |
| 切片窗口 | `audio_object` | `object_type='window'`, `parent_object_id=<asset_id>` |
| 指纹特征 | `feature_fact` | `feature_type='fingerprint'`, `fingerprint_value` |
| embedding 特征 | `feature_fact` | `feature_type='embedding'`, `embedding_uri/vector_table_name` |
| 模型信息 | `feature_fact` | `model_name`, `model_version`, `feature_set_name` |
| reference/eval/hot 集 | `set_membership` | `set_type`, `set_name` |
- PostgreSQL v2 schema 已落地
- registry bootstrap 已有 live 验证
- worker contract 已有 live 验证
- exact / semantic 的失败语义已可审计
- planner 已能输出 validation commands
- planner validation runner 已可一键执行
---
## 6. 当前哪些还没完成
## 5. 当前主链流程图
- 还没有真正跑通 MERT / MuQ inference
- 当前 host 没有 `/workspace/downloads`
- 当前 host 缺 `torch / torchaudio / transformers / speechbrain`
- 还没完成最终线上融合策略
- 还没接入更大规模真实 reference set
```mermaid
flowchart TD
A[media_entity\nentity_type=song] --> B[audio_object\nobject_type=asset]
B --> C[audio_object\nobject_type=window]
C --> D1[feature_fact\nfingerprint]
C --> D2[feature_fact\nembedding]
B --> E[set_membership\nreference_set / eval_set / hot_set]
C --> E
```
---
## 7. 如果你现在继续推进，按这个顺序
### 路线 A：先解环境
1. 挂载 `/workspace/downloads`
2. 安装 semantic runtime 依赖
3. 重跑 planner validation runner
4. 确认 `ready_jobs` 是否开始恢复
## 6. 当前哪些已经稳定
### 路线 B：先解实现
1. 阅读 [phase1-worker-contract.md](./phase1-worker-contract.md)
2. 阅读 `acr-engine/workers/run_embedding_job.py`
3. 用真实 inference adapter 替换 guarded failure path
4. 保持当前 PostgreSQL contract 不变
### 路线 C：先解数据
1. 阅读 [postgresql-data-model.md](./postgresql-data-model.md)
2. 阅读 [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
3. 准备更大的 reference set
4. 保持 `reference_set_registry / reference_set_member` 版本化
- live PostgreSQL schema 已真实建表通过
- 真实目录 -> manifest -> import 已打通
- 真实目录 -> fingerprint enrichment -> import 已打通
- semantic lane 已做成 runtime-aware
- 当前 host 无 `torch/torchaudio/transformers` 时会明确 fallback，不会伪装成功
- 当前 exact lane 已优先复用仓库内 `ChromaprintMatcher`
---
## 8. 当前不建议优先做的事
## 7. 当前最该继续什么
- 不要重新讨论要不要 `song/work/recording` 分层
- 不要回退到只有 `song_id` 的扁平表
- 不要先讨论重新训练底座
- 不要把当前问题误判成 PostgreSQL contract 设计问题
### 第一优先级
把 semantic lane 从 fallback 升级成真实 encoder adapter，且不破坏现有宿主链。
---
### 当前 host 事实
- `torch` 缺失
- `torchaudio` 缺失
- `transformers` 缺失
- 当前因此 `semantic_runtime_available = false`
## 9. 仓库常用入口
---
### 文档
- [README.md](./README.md)
- [session-handoff.md](./session-handoff.md)
- [postgresql-data-model.md](./postgresql-data-model.md)
- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
- [phase1-worker-contract.md](./phase1-worker-contract.md)
## 8. 当前不要再绕回去的点
### 脚本
- `acr-engine/scripts/run_planner_validation_commands_live.py`
- `acr-engine/scripts/run_phase1_prereq_audit_live.py`
- `acr-engine/scripts/run_phase1_worker_contract_smoke_live.py`
- `acr-engine/scripts/run_embedding_vector_table_negative_matrix_live.py`
- `acr-engine/scripts/validate_audio_embedding_asset_upsert_live.py`
- `acr-engine/scripts/run_songcentric_directory_pipeline_live.py`
- 不要回退到旧的 v2 schema 作为默认口径
- 不要重新引入 `recording/work/version` 作为 Phase-1 必须返回对象
- 不要先讨论训练/微调
- 不要把“模型底座可替换”误解成“数据库要重新拆很多层”
---
## 一句话结论
> 新同学接手时，先跑 runner，再读 5 份核心文档；当前首要问题是环境前置条件，不是 schema/contract 本身。
> 当前最重要的是守住 4 表 song-centric 主链，并在这个主链上把 semantic encoder 真正接起来。
......