Skip to content

wanghai-tech / hikoon-ACR

Go to a project
Toggle navigation
Toggle navigation pinning
Switch branch/tag
start-here.md 4.85 KB

Start Here / 新同学接手入口

目标：让新来的同学在 10 分钟内知道：先跑什么、先读什么、当前卡在哪、下一步该做什么。

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

也可以用包装脚本：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

这条命令会执行

  1. prereq_audit
  2. worker_contract_smoke
  3. semantic_vector_negative_matrix
  4. asset_level_upsert_validation

看到下面这些结果时应该如何判断

如果你看到：

  • downloads_root_exists = false
  • ready_jobs = 0
  • exact lane = failed/unreadable_audio_assets
  • semantic lane = 4/4 failed

说明当前优先级是：

  1. 挂载 /workspace/downloads
  2. 安装 torch / torchaudio / transformers / speechbrain

也就是说：

当前首要问题是运行环境前置条件，不是 PostgreSQL schema，也不是 worker contract 设计错误。

2. 接手时只读这 5 份文档

  1. README.md
  2. session-handoff.md
  3. acr-architecture.md
  4. postgresql-data-model.md
  5. phase1-implementation-checklist.md

如果你负责算法或检索，再补：

3. 用一句话理解项目

我们在做的是一个面向 版权保护 / 听歌识曲 / 版本归属 的音乐 ACR 系统， 目标是从 100w 音频、约 30w 歌曲中，快速定位正确的 song_id 归属；当前阶段暂不把版本/recording 作为必须返回对象。

4. 当前主线方案

检索主线

  • exact lane：Chromaprint
  • semantic lane baseline：MERT-v1-95M
  • semantic lane challenger：MuQ
  • historical baseline：ECAPA

当前 Phase-1 最小主线

song -> asset -> window

可演进完整版主线

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

模型主线

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

5. 当前哪些已经稳定

  • PostgreSQL v2 schema 已落地
  • registry bootstrap 已有 live 验证
  • worker contract 已有 live 验证
  • exact / semantic 的失败语义已可审计
  • planner 已能输出 validation commands
  • planner validation runner 已可一键执行

6. 当前哪些还没完成

  • 还没有真正跑通 MERT / MuQ inference
  • 当前 host 没有 /workspace/downloads
  • 当前 host 缺 torch / torchaudio / transformers / speechbrain
  • 还没完成最终线上融合策略
  • 还没接入更大规模真实 reference set

7. 如果你现在继续推进，按这个顺序

路线 A：先解环境

  1. 挂载 /workspace/downloads
  2. 安装 semantic runtime 依赖
  3. 重跑 planner validation runner
  4. 确认 ready_jobs 是否开始恢复

路线 B：先解实现

  1. 阅读 phase1-worker-contract.md
  2. 阅读 acr-engine/workers/run_embedding_job.py
  3. 用真实 inference adapter 替换 guarded failure path
  4. 保持当前 PostgreSQL contract 不变

路线 C：先解数据

  1. 阅读 postgresql-data-model.md
  2. 阅读 postgres_db_schema_samples.md
  3. 准备更大的 reference set
  4. 保持 reference_set_registry / reference_set_member 版本化

8. 当前不建议优先做的事

  • 不要重新讨论要不要 song/work/recording 分层
  • 不要回退到只有 song_id 的扁平表
  • 不要先讨论重新训练底座
  • 不要把当前问题误判成 PostgreSQL contract 设计问题

9. 仓库常用入口

文档

脚本

  • acr-engine/scripts/run_planner_validation_commands_live.py
  • acr-engine/scripts/run_phase1_prereq_audit_live.py
  • acr-engine/scripts/run_phase1_worker_contract_smoke_live.py
  • acr-engine/scripts/run_embedding_vector_table_negative_matrix_live.py
  • acr-engine/scripts/validate_audio_embedding_asset_upsert_live.py

一句话结论

新同学接手时，先跑 runner，再读 5 份核心文档；当前首要问题是环境前置条件，不是 schema/contract 本身。