Phase-1 Worker Contract / 作业执行器契约

更新：2026-06-04
目标：把 Phase-1 从“只有 registry / plan”推进到“worker 可以真实消费 PostgreSQL 作业并更新状态”。

---

一页结论

当前 Phase-1 已经具备一条最小真实执行链：

1. planner 从 feature_extraction_job 读 pending jobs
2. worker 读取 extraction_job_id
3. worker 联表解析 feature_set_registry + model_registry
4. worker 解析 target_scope
5. worker 回写 feature_extraction_job.job_status / input_count / output_count / metadata_json

也就是说，现在 PostgreSQL 不只是“数据字典”，已经开始承担：

• 作业编排面
• 状态机面
• 执行证据面

---

1. 当前落地的 worker

位于：

• acr-engine/workers/mark_job_status.py
• acr-engine/workers/run_chromaprint_job.py
• acr-engine/workers/run_embedding_job.py
• acr-engine/workers/_job_common.py

角色划分

worker	作用
mark_job_status.py	通用状态推进器
run_chromaprint_job.py	exact lane worker
run_embedding_job.py	semantic lane worker
_job_common.py	共享的 job 读取、scope 解析、状态回写逻辑

---

2. 当前状态机

flowchart LR
    A[pending] --> B[running]
    B --> C[completed]
    B --> D[failed]

当前已验证的状态流转

• pending -> running
• running -> completed（dry-run 模式）

设计意图

先把 作业契约与状态流转 固定住，再把真正的模型推理塞进去。
这样后续不管换成：

• Chromaprint
• MERT
• MuQ
• CoverHunter encoder

都不需要重做 orchestration 数据结构。

---

3. worker 输入契约

环境变量

变量	说明
PG_DSN	PostgreSQL 连接串
PG_SCHEMA	目标 schema
EXTRACTION_JOB_ID	要执行的作业 id
FEATURE_SET_ID	规划时附带，worker 可用于一致性检查
TARGET_SCOPE	规划时附带，worker 当前以 DB 中 job 记录为准
MODEL_NAME	embedding worker 用于防错
MODEL_VERSION	embedding worker 用于防错
VECTOR_TABLE	embedding worker 目标向量表
OUTPUT_TARGET	audio_fingerprint 或 audio_embedding

CLI 参数

三个 worker 都支持显式 CLI 参数覆盖 env。

planner 命令模板的当前约定

plan_phase1_extraction_jobs_live.py 现在会显式生成：

PG_DSN="${PG_DSN:?set PG_DSN}" ...

这样复制命令时，如果调用方忘了提供数据库连接串，会立刻失败，而不是静默跑空。

---

4. PostgreSQL 读取契约

worker 当前真实读取：

1. feature_extraction_job
2. feature_set_registry
3. model_registry
4. reference_set_registry / reference_set_member
5. recording_asset
6. audio_window

为什么要读 scope summary

因为 Phase-1 第一阶段的核心不是“立刻抽出 embedding”，而是先确定：

• 这次 job 面向哪个 reference set
• 涉及多少 recording
• 涉及多少 ready asset
• 涉及多少 active window

这样后续做：

• 分片
• 并行
• 重试
• SLA 估算

才有稳定基线。

---

5. 当前 dry-run 的真实意义

当前 worker 还没有真正调用模型做特征提取；它做的是：

1. 验证 planner 命令模板可被真实消费
2. 验证 job -> feature_set -> model 的 join 契约
3. 验证 target scope 解析
4. 验证 PostgreSQL 作业状态回写
5. 为下一步真推理保留稳定入口

所以它不是假文档，而是：

先把工业执行面的骨架打通，再把模型推理填进去。

---

6. 推荐执行顺序

flowchart TD
    A[bootstrap model/feature/reference registry] --> B[bootstrap feature_extraction_job]
    B --> C[plan pending jobs]
    C --> D[run worker dry-run]
    D --> E[validate status transitions]
    E --> F[replace dry-run with real extractor]

---

7. exact lane 与 semantic lane 的后续替换点

7.1 Chromaprint worker

后续把下面逻辑塞进 run_chromaprint_job.py：

1. 读取 recording_asset
2. 调 chromaprint CLI / library
3. 写 audio_fingerprint
4. 更新 output_count
5. 标记 completed

7.2 Embedding worker

后续把下面逻辑塞进 run_embedding_job.py：

1. 读取 audio_window
2. 加载 MERT / MuQ / ECAPA
3. 提取向量
4. 写 audio_embedding
5. 写 audio_embedding_vector_<dim>
6. 更新 output_count
7. 标记 completed

---

8. 解决了什么问题

这次 worker contract 落地，主要解决了 4 个问题：

1. planner 不再只是纸面计划
2. job status 有了真实推进器
3. 后续换模型不用重做 orchestration
4. 可以先 dry-run 验证执行链，再接入重模型

---

9. 当前边界

当前还没有完成的部分：

• 真实 chromaprint 特征写入
• 真实 MERT / MuQ / ECAPA embedding 写入
• failed 重试策略
• job 分片执行器
• 幂等去重写入策略

但现在已经足够支撑下一阶段：

把真实 extractor 接到已经验证过的 PostgreSQL worker contract 上。