Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 4b23f546 4b23f54681abd33b4f6fbda7d48576bcac056713 by cnb.bofCdSsphPA
Options

Make the Phase-1 ACR plan executable for each delivery role 

Constraint: The architecture and schema docs were already in place, but teams still lacked a concrete implementation checklist and registry bootstrap contract for encoder-only rollout
Rejected: leaving execution guidance implicit in architecture prose | would slow Phase-1 delivery and cause inconsistent model/feature initialization
Confidence: high
Scope-risk: narrow
Directive: treat Phase-1 implementation sequencing and model/feature/reference-set bootstrap as first-class docs that evolve with the schema
Tested: git diff --check on changed docs; Python document sanity check; README/CHANGELOG link coverage verified with rg
Not-tested: no runtime behavior changed; no database apply executed
1 parent e514a6c7
Inline Side-by-side
Showing 4 changed files with 461 additions and 8 deletions
## 2026-06-04
- 新增 [Phase-1 实施清单](./phase1-implementation-checklist.md)，把 encoder-only 路线拆成主数据、reference set、feature set、索引、评测的可执行阶段。
- 新增 [模型与 Feature Set 初始化手册](./model-feature-registry-bootstrap.md)，补齐 model_registry / feature_set_registry / reference_set_registry 的初始化约定与示例 SQL。
- 重构文档主阅读路径，新增按角色划分的文档入口：架构、开发、运维、模型底座。
- 新增 [SOTA 演进方案说明](./sota-evolution-guide.md)，明确 Phase-1 encoder-only 路线、MERT/MuQ 角色与后续 version/cover 演进。
- 重写 [ACR 系统蓝图](./acr-architecture.md)，补充角色视图、离线/在线职责分工与当前实现到目标实现的映射。
......
......@@ -20,25 +20,30 @@
1. [acr-architecture.md](./acr-architecture.md)
2. [sota-evolution-guide.md](./sota-evolution-guide.md)
3. [postgresql-data-model.md](./postgresql-data-model.md)
4. [session-handoff.md](./session-handoff.md)
4. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
5. [session-handoff.md](./session-handoff.md)
### 2. 开发 / 数据 / 检索工程师
1. [postgresql-data-model.md](./postgresql-data-model.md)
2. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
3. [acr-architecture.md](./acr-architecture.md)
4. [runbook.md](./runbook.md)
2. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
3. [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md)
4. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
5. [acr-architecture.md](./acr-architecture.md)
6. [runbook.md](./runbook.md)
### 3. 运维 / 平台 / 服务工程师
1. [acr-architecture.md](./acr-architecture.md)
2. [postgresql-data-model.md](./postgresql-data-model.md)
3. [service-api.md](./service-api.md)
4. [runbook.md](./runbook.md)
3. [phase1-implementation-checklist.md](./phase1-implementation-checklist.md)
4. [service-api.md](./service-api.md)
5. [runbook.md](./runbook.md)
### 4. 模型 / 底座 / 研究工程师
1. [sota-research-2026.md](./sota-research-2026.md)
2. [sota-evolution-guide.md](./sota-evolution-guide.md)
3. [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
4. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
3. [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md)
4. [production-encoder-freeze-and-embedding-strategy.md](./production-encoder-freeze-and-embedding-strategy.md)
5. [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md)
---
......@@ -49,6 +54,8 @@
| [acr-architecture.md](./acr-architecture.md) | 当前系统蓝图、角色分工、在线/离线链路 | 架构、开发、运维 |
| [sota-evolution-guide.md](./sota-evolution-guide.md) | SOTA 演进路径、Phase-1 encoder-only 方案、后续升级路线 | 架构、模型、检索 |
| [postgresql-data-model.md](./postgresql-data-model.md) | PostgreSQL 数据字典、DDL 设计意图、流程图、查询路径 | 数据、后端、检索、平台 |
| [phase1-implementation-checklist.md](./phase1-implementation-checklist.md) | Phase-1 落地 checklist，按阶段拆执行项 | 架构、开发、平台 |
| [model-feature-registry-bootstrap.md](./model-feature-registry-bootstrap.md) | 模型、feature set、reference set 初始化手册 | 模型、检索、数据 |
| [training-data-and-pgvector-guide.md](./training-data-and-pgvector-guide.md) | 当前训练/manifest/pgvector 原型链说明 | 开发、数据 |
| [session-handoff.md](./session-handoff.md) | 最新状态与续跑上下文 | 新 session 接手人 |
......
# 模型与 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`
这样数据、模型、索引三条线就都有了稳定入口。
# 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`
### 第一版聚合建议
- 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 与门禁