Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Switch branch/tag
phase1-implementation-checklist.md 6.24 KB

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. 推荐时间顺序

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，而不必手工拼测试命令。