Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Switch branch/tag
session-handoff.md 11.5 KB

Session Handoff / 持续开发交接文档

更新：2026-06-04 目的：让下次启动的新 session 在 3~10 分钟内 明确：

  1. 当前项目已经走到哪里
  2. 应该先读哪些文档
  3. 应该从哪一步开始推进
  4. 哪些是当前稳定结论，哪些还只是待验证假设

一页结论

当前项目主线已经从“原型是否能跑通”切到：

为版权保护场景建设一个可演进的音乐 ACR / 检索系统， 目标是让 100w 音频、约 30w 歌曲能够在未来通过 canonical_song / work / recording / recording_asset / audio_window 这条主数据链，以及 model_registry / feature_set_registry 这套模型注册机制，稳定支撑检索、归属、升级与回滚。

当前已经完成的关键交付：

  • 文档体系已重构为“角色化阅读路径”
  • SOTA 演进路径已明确：Phase-1 先走 encoder-only
  • PostgreSQL 主数据与特征注册 DDL 已落地为推荐版 schema
  • Phase-1 实施 checklist 和 model/feature/reference set 初始化手册已补齐
  • acr_test schema 上已经真实完成 Phase-1 model_registry / feature_set_registry / reference_set_registry bootstrap 验证

当前最重要的下一步不是继续写方案，而是：

  1. 按 schema v2 落 PostgreSQL 主数据模型
  2. 把 reference set / audio_window / feature_set 初始化做起来
  3. 接入 MERT / MuQ 的 encoder-only 抽特征链
  4. 跑通 fingerprint lane + semantic lane 的第一版聚合闭环

下次启动先读什么

最短阅读顺序（推荐）

  1. docs/README.md
  2. docs/acr-architecture.md
  3. docs/sota-evolution-guide.md
  4. docs/postgresql-data-model.md
  5. docs/phase1-implementation-checklist.md
  6. docs/model-feature-registry-bootstrap.md
  7. docs/phase1-worker-contract.md
  8. docs/CHANGELOG.md

如果只想快速恢复上下文，至少读前 5 个。

当前稳定结论（可以直接继承）

1. 技术方向

  • 当前 ECAPA 路线保留为 baseline，不再作为长期主底座。
  • Phase-1 主推 encoder-only foundation 路线。
    • exact lane：Chromaprint
    • semantic lane 主 baseline：MERT-v1-95M
    • semantic lane challenger：MuQ
  • Phase-2 才考虑 version / cover lane。
  • Phase-3 再进入工业化检索/重排/治理。

2. 数据主链

后续主数据一律围绕：

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

不要再退回到仅有 song_id 的扁平结构。

3. 模型/特征主链

后续 encoder、feature、索引一律围绕：

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

不要设计成固定列：

  • mert_embedding
  • muq_embedding
  • ecapa_embedding

4. reference 集合

当前结论是：

  • 需要显式 reference_set_registry
  • is_reference=true 仍然保留，但不再足够表达生产切换
  • 未来热 reference 集、A/B、回滚、encoder 升级都要依赖 reference set 版本化

本轮新增/修改的关键文件

主文档

SQL / schema

  • acr-engine/sql/acr_pg_schema_v2.sql

历史/补充说明（仍有参考价值）

当前推荐的启动动作

路线 A：如果下次 session 继续“补文档/补设计”

优先顺序：

  1. 补 数据导入手册：100w 音频如何映射到 canonical_song/work/recording/recording_asset
  2. 补 检索聚合设计文档：fingerprint lane + semantic lane 的分数融合与 song/work 聚合规则
  3. 补 索引与版本治理文档：reference set / feature set / index set 的上线切换规则

路线 B：如果下次 session 开始“进入实现”

直接按下面顺序推进：

  1. 建库执行 acr-engine/sql/acr_pg_schema_v2.sql
  2. 初始化 canonical_song / work / recording / recording_asset
  3. 初始化 reference_set_registry
  4. 生成 audio_window
  5. 初始化 model_registry / feature_set_registry
  6. 接入 MERT / MuQ encoder-only 抽特征
  7. 构建 semantic index
  8. 跑通 query -> candidate -> canonical_song 闭环

下次 session 第一条可直接复制执行的检查命令

cd /workspace
sed -n '1,220p' docs/README.md
sed -n '1,260p' docs/phase1-implementation-checklist.md
sed -n '1,260p' docs/model-feature-registry-bootstrap.md
sed -n '1,260p' docs/postgresql-data-model.md

如果要直接看 schema：

cd /workspace
sed -n '1,320p' acr-engine/sql/acr_pg_schema_v2.sql

当前实现与未来实现的边界

当前仓库已经有的东西

  • Chromaprint 原型链
  • ECAPA embedding baseline
  • hybrid engine 原型
  • 早期 pgvector prototype schema

当前还没做完的东西

  • PostgreSQL v2 schema 的实际落库
  • Phase-1 的 reference set 初始化
  • MERT / MuQ encoder-only 特征抽取与入库
  • semantic lane 的第一版 production-oriented 聚合

所以：

当前项目的“方案层”已经足够启动实现， 下次 session 不应再从头讨论“要不要 song/work/recording”， 而应该直接进入 Schema -> Reference Set -> Feature Set -> Extraction -> Retrieval 的执行链。

当前验证状态

已验证

  • 新文档结构已补齐并接入 README
  • Phase-1 方案、PostgreSQL 设计、实施 checklist、registry bootstrap 均已提交
  • architect 审核结论：APPROVED
  • 代码已推送远端
  • PostgreSQL acr_test live 路径已再次验证：recording / audio_window / audio_embedding 三类 lineage trigger 均有真实负例证据
  • 机械校验已补齐：live_pgvector_music20_eval.py 的 py_compile 通过，相关变更 diff --check 通过
  • PostgreSQL acr_test schema 上已真实写入 Phase-1 registry bootstrap：chromaprint / mert / muq / ecapa + 5 组 feature set + phase1_hot_reference_v1
  • Phase-1 registry bootstrap 已有幂等性证据：同 schema 连续执行两次后，model_registry=5 / feature_set_registry=6 / reference_set_registry=2 保持不变
  • PostgreSQL acr_test schema 上已真实创建 5 条 feature_extraction_job，后续 MERT / MuQ 接入可直接从 pending jobs 启动
  • PostgreSQL acr_test schema 上已真实生成 Phase-1 extraction execution plan，当前顺序是 chromaprint -> mert -> mert-long -> muq -> ecapa
  • extraction plan 报告里已包含 command_suggestions / primary_command，下次可直接从 plan 抄 worker 命令模板
  • Phase-1 worker 入口已真实落地：run_chromaprint_job.py / run_embedding_job.py / mark_job_status.py
  • 下一阶段已经不是“补 planner”，而是把 dry-run worker 替换为真实 extractor，并把 audio_fingerprint / audio_embedding 写入做成幂等执行
  • semantic lane 也已完成 live failure contract：run_embedding_job.py 现在会同时暴露 unreadable_audio_assets 与 model_runtime_unavailable，而不是把失败伪装成 completed
  • audio_embedding 已补上 window / asset 双路唯一键，后续真实 encoder 只需替换 inference adapter 即可复用同一 upsert 合同
  • scripts/run_phase1_embedding_preflight_matrix_live.py 已跑通，4 条 semantic jobs（mert/muq/ecapa）在 acr_test 上都被稳定标记为 preflight_failed；当前共性 blocker 已收敛为 /workspace/downloads 缺失 + 语义模型 runtime 缺失
  • scripts/validate_audio_embedding_asset_upsert_live.py 已在隔离 schema acr_asset_upsert_test 上验证 uq_audio_embedding_feature_asset：重复 insert 会被唯一键拒绝，upsert 会复用同一 embedding_id，说明 asset-level 幂等键也已有真实证据
  • scripts/run_phase1_worker_contract_smoke_live.py 已提供一条命令的全局 smoke：当前 exact lane = failed/unreadable_audio_assets，semantic lane = 4/4 failed，共性 blocker 已固化为音频挂载缺失 + 语义模型 runtime 缺失
  • scripts/run_embedding_vector_table_negative_matrix_live.py 已在 live PostgreSQL 上补齐 semantic vector-table 负例矩阵：vector_table_dim_mismatch、vector_table_not_allowlisted、vector_table_missing_in_schema 三类错误都能被稳定写入 vector_table_report.reason
  • scripts/run_phase1_prereq_audit_live.py 已给出当前 host 的先决条件审计：downloads_root_exists=false、ready_jobs=0/5，并把 torch/torchaudio/transformers/speechbrain 的缺失状态按 job 落成 JSON 报告
  • phase1_extraction_plan_report.json 现已附带 validation_commands，下次 session 可以直接从 planner 复制 prereq_audit / worker_contract_smoke / semantic_vector_negative_matrix / asset_level_upsert_validation 四类命令
  • phase1_validation_commands_execution_report.json 已证明 planner 里的 prereq_audit 与 worker_contract_smoke 两条 validation commands 可以被直接脚本消费且 returncode=0
  • phase1_hot_reference_v1 在 acr_test 里已经真实补齐 20 个 reference members，因此 worker dry-run 当前看到的 scope 已是 20 recordings / 20 assets / 20 windows
  • worker contract 现在已有基础前置状态保护；重复执行同一 chromaprint dry-run job 会被 expected_status=pending 明确拒绝，证据见 phase1_worker_double_claim_guard_report.json
  • exact lane 的 run_chromaprint_job.py 已具备非 dry-run 写入路径；当前在 acr_test 的 live 结果是因为 /workspace/downloads/... 缺失而明确 failed，不是继续假装 completed

未验证 / 仍是缺口

  • 未实际跑 MERT / MuQ encoder-only 特征抽取
  • semantic / cover 等后续 lane 仍主要停留在 dry-run；exact lane 已接上真实 audio_fingerprint 写入路径，但当前容器缺 reference 音频挂载，live 结果仍停在可审计失败
  • 还未落更大规模的生产 reference set 真实业务数据（当前仅验证了 acr_test 下的 20-song live members）
  • 未定义最终线上分数融合细则
  • type_8 / type_16 还没有进入当前 live JSONL 的 PostgreSQL 实测链
  • 当前容器里缺少 /workspace/downloads，因此暂时无法直接从业务样本目录继续补 type_8 / type_16 live query

因此下次 session 应优先从这些未验证缺口里挑一条推进，而不是重复写总方案。

最近相关提交

按当前 handoff 相关主线，最近重要提交是：

  • a549d1d — Clarify the ACR evolution path and freeze a production-grade data model
  • e514a6c — Keep the new ACR architecture guide clean for follow-up edits
  • 4b23f54 — Make the Phase-1 ACR plan executable for each delivery role
  • 0679481 — Attach runnable command templates to the extraction plan

如果下次需要追踪文档补充点，可以从这三个提交开始看。

一句话交接

下次启动不要再从“要不要换模型、要不要重构数据结构”开始讨论。 这些方向已经定了。直接从 PostgreSQL v2 schema 落库 + Phase-1 worker/extractor 执行链 开始推进。