phase1-implementation-checklist.md 6.91 KB

Raw Blame History Permalink



Phase-1 实施清单 / Encoder-only Implementation Checklist


更新：2026-06-04

目标：把“先不上微调、先用开源 encoder”的 Phase-1 方案拆成可执行步骤，方便数据、检索、平台、运维团队并行推进。


一页结论

Phase-1 的交付目标不是“证明某个新模型绝对最优”，而是：


把 PostgreSQL 主数据模型 落稳
把 reference 资产 / window / feature_set 跑通
用 MERT + MuQ 建立 encoder-only baseline
把 fingerprint lane + semantic lane 的聚合链先跑通
给 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. 本阶段容易踩的坑


先把 embedding 存储设计死到某个模型维度
只保留 song_id，不保留 work/recording
reference set 没有版本化
query 结果无法回查具体 evidence window
exact lane 被过早删除


7. 当前建议结论

如果你要马上排计划，建议按这个优先级：


Schema v2 与主数据导入
reference set + audio_window
MERT/MuQ feature_set 初始化
encoder-only 抽特征
双路召回与聚合
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 的条件，推荐优先执行：

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