session-handoff.md 6.22 KB

Raw Blame History Permalink



Session Handoff / 持续开发交接文档


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


当前项目已经走到哪里
应该先读哪些文档
应该从哪一步开始推进
哪些是稳定结论，哪些还是待验证缺口


0. 下次启动先做什么

先执行：

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 会一次性执行：


prereq_audit
worker_contract_smoke
semantic_vector_negative_matrix
asset_level_upsert_validation


如果结果仍是：


downloads_root_exists = false
ready_jobs = 0
exact = failed/unreadable_audio_assets

semantic = 4/4 failed


则说明当前优先级仍然是：


补 /workspace/downloads 挂载
补 torch / torchaudio / transformers / speechbrain


而不是回头怀疑 PostgreSQL contract。


1. 当前项目一句话状态

项目已经从“原型能否跑通”转为：


面向版权保护 / 听歌识曲 / 版本归属的可演进音乐 ACR 系统。


当前目标是让 100w 音频、约 30w 歌曲能通过稳定的数据主链和模型注册机制，支撑检索、归属、升级与回滚。


2. 当前稳定结论


技术路线


exact lane：Chromaprint

semantic baseline：MERT-v1-95M

semantic challenger：MuQ


ECAPA：historical baseline
Phase-1：先走 encoder-only，先不用微调底座


数据主链

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


模型主链

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


reference set 结论


保留 is_reference=true

但生产切换必须依赖 reference_set_registry / reference_set_member

后续 A/B、热切换、回滚都围绕 reference set 版本化进行


3. 当前已经完成的关键交付


文档与设计


文档主入口已收敛到 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 已收敛最短验证链路


4. 当前明确的 blocker


环境 blocker


/workspace/downloads 缺失
缺少 torch

缺少 torchaudio

缺少 transformers

缺少 speechbrain


能力 blocker


还未真实跑通 MERT / MuQ inference
还未完成线上融合策略
还未接入更大规模真实 reference set


因此当前最该优先推进的是：


把环境补齐，再把 semantic lane 从 guarded failure 推到真实抽特征。


5. 下次启动先读什么

按这个顺序即可：


README.md
start-here.md
acr-architecture.md
postgresql-data-model.md
phase1-implementation-checklist.md
model-feature-registry-bootstrap.md
phase1-worker-contract.md
CHANGELOG.md


6. 下次启动优先动作


路线 A：继续环境恢复


检查 /workspace/downloads 是否已挂载
检查 torch / torchaudio / transformers / speechbrain 是否已可导入
重跑 planner validation runner
确认 ready_jobs 是否从 0 开始提升


路线 B：继续语义特征抽取实现


查看 acr-engine/workers/run_embedding_job.py

保持现有失败语义 contract
接入真实 inference adapter
复用现有 audio_embedding upsert 逻辑


路线 C：继续数据规模化落库


查看 postgresql-data-model.md

查看 postgres_db_schema_samples.md

规划 100w 音频导入批次
固定 reference_set / feature_set / index 版本治理


7. 当前不要再重复讨论的结论


不要回退到只有 song_id 的扁平表
不要把 embedding 设计成固定列
不要在 Phase-1 先讨论重新训练底座
不要把当前问题误判成 PostgreSQL schema 问题


8. 关键文件入口


文档


README.md
start-here.md
postgresql-data-model.md
phase1-worker-contract.md


代码与脚本


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


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 已验证


未验证


MERT / MuQ 真实 inference
更大规模生产 reference set 导入
最终线上融合与重排策略


一句话 handoff


下次接手不要再从总方案开始，先跑 runner；若结果仍显示 downloads/runtime 缺失，就优先补环境，再推进 semantic lane 真实抽特征。