model-feature-registry-bootstrap.md 13.9 KB

Raw Blame History Permalink



模型与 Feature Set 初始化手册 / Model & Feature Registry Bootstrap


更新：2026-06-04

目标：给出 Phase-1 里 model_registry、feature_set_registry、reference_set_registry 的初始化约定，避免每次接入新 encoder 时重新设计。


一页结论

Phase-1 不微调底座时，真正需要初始化的不是“训练任务”，而是三类对象：


模型定义：model_registry


特征定义：feature_set_registry


reference 集定义：reference_set_registry


也就是说，先把“你要怎么用模型”写清楚，再开始抽特征。


1. 推荐命名约定


1.1 model_name

推荐固定小写：


chromaprint
mert
muq
ecapa

coverhunter_encoder（Phase-2+）


1.2 model_version

推荐表达清楚来源和规模：


v1-95m
v1-330m
large-msd-iter
acr-baseline-v1


1.3 feature set 命名

推荐格式：

<model_name>__<feature_name>__<window>x<hop>__<pooling>__<metric>


示例：


mert__semantic_embedding__5s_2.5s__mean__cosine
mert__semantic_embedding__10s_5s__mean__cosine
muq__semantic_embedding__5s_2.5s__mean__cosine


2. Phase-1 推荐初始化对象


2.1 模型清单


model_name
model_version
角色


chromaprint
v1
exact lane


mert
v1-95m
semantic 主 baseline


muq
large-msd-iter
semantic challenger


ecapa
acr-baseline-v1
历史 baseline / 对照


2.2 Feature set 清单


feature_set
目的


chromaprint asset-level
exact 匹配


mert 5s/2.5s mean
主 semantic baseline


mert 10s/5s mean
较长上下文验证


muq 5s/2.5s mean
challenger baseline


ecapa 5s/2.5s
历史对照


3. 推荐初始化 SQL


3.1 注册模型

insert into model_registry (
    model_name, model_family, model_version, model_source, model_uri,
    license_name, input_modality, input_sample_rate, input_channel_mode,
    default_window_sec, default_hop_sec, output_embedding_dim,
    pooling_supported, layer_selection_supported, is_trainable
) values
('chromaprint', 'fingerprint', 'v1', 'local', null,
 null, 'audio', 16000, 'mono',
 5.0, 2.5, null,
 array['none'], false, false),
('mert', 'music_ssl', 'v1-95m', 'github', 'https://github.com/yizhilll/MERT',
 null, 'audio', 24000, 'mono',
 5.0, 2.5, 768,
 array['mean','cls'], true, false),
('muq', 'music_ssl', 'large-msd-iter', 'github', 'https://github.com/tencent-ailab/MuQ',
 null, 'audio', 24000, 'mono',
 5.0, 2.5, 768,
 array['mean','cls'], true, false),
('ecapa', 'speech_derived', 'acr-baseline-v1', 'local', null,
 null, 'audio', 16000, 'mono',
 5.0, 2.5, 192,
 array['mean'], false, true);


3.2 注册 feature set

insert into feature_set_registry (
    model_id, feature_name, feature_level, extraction_granularity,
    window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
    normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
       5.0, 2.5, 768, 'mean', 'final',
       true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'mert' and model_version = 'v1-95m';

insert into feature_set_registry (
    model_id, feature_name, feature_level, extraction_granularity,
    window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
    normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
       10.0, 5.0, 768, 'mean', 'final',
       true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'mert' and model_version = 'v1-95m';

insert into feature_set_registry (
    model_id, feature_name, feature_level, extraction_granularity,
    window_sec, hop_sec, embedding_dim, pooling_strategy, layer_selection,
    normalize_l2, distance_metric, quantization_type, feature_schema_version
)
select model_id, 'semantic_embedding', 'window', 'sliding_window',
       5.0, 2.5, 768, 'mean', 'final',
       true, 'cosine', 'none', 'v1'
from model_registry
where model_name = 'muq' and model_version = 'large-msd-iter';


3.3 注册 reference set

insert into reference_set_registry (
    set_name, description, encoder_scope, status
) values (
    'phase1_hot_reference_v1',
    'Phase-1 主 reference 集，仅包含当前线上热参考 recording',
    'mert-v1-95m / muq-large-msd-iter',
    'active'
);


4. reference set 的运营原则


当前建议


一个时间点只允许一个主 active hot reference set
新 encoder / 新聚合策略上线时，新建 set，不覆盖旧 set
A/B 或 shadow 期间，允许多个 set 并存，但只有一个主线上标记


为什么

这样可以支持：


线上回滚
encoder 升级
索引热切换
离线重放


5. 维度扩展规则

当前 DDL 只演示了：


audio_embedding_vector_192
audio_embedding_vector_768


后续如果接入新 encoder 维度，如 1024：


新增 audio_embedding_vector_1024

对应 feature_set 的 embedding_dim=1024

独立建索引
通过 retrieval_index_registry 切换


原则


维度变化是 feature set 升级，不是主数据模型升级
主数据层不该因 encoder 升级而改表


6. 当前推荐顺序

flowchart TD
    A[注册 model_registry] --> B[注册 feature_set_registry]
    B --> C[注册 reference_set_registry]
    C --> D[抽取 embeddings/fingerprint]
    D --> E[写 audio_embedding/audio_fingerprint]
    E --> F[建 retrieval_index_registry]


7. 最后建议

如果你今天就开始做 Phase-1 初始化，建议最少先注册：


chromaprint v1
mert v1-95m
muq large-msd-iter
mert 5s/2.5s mean
muq 5s/2.5s mean
phase1_hot_reference_v1


这样数据、模型、索引三条线就都有了稳定入口。


10. Phase-1 worker contract（新增执行层）

当前已经不只是 registry/bootstrap 了，还补上了最小真实 worker 执行面：


acr-engine/scripts/bootstrap_phase1_reference_members_live.py
acr-engine/workers/mark_job_status.py
acr-engine/workers/run_chromaprint_job.py
acr-engine/workers/run_embedding_job.py


这层的作用不是立即跑完真实抽特征，而是先把下面这条链打通：

planner -> feature_extraction_job -> worker -> PostgreSQL status update


当前能力


读取 feature_extraction_job

联表解析 feature_set_registry + model_registry

解析 target_scope

回写 pending -> running -> completed

为后续真模型推理保留稳定契约


推荐阅读

详细契约与流程图见：


docs/phase1-worker-contract.md


8. live PostgreSQL bootstrap 脚本

为了避免每次手工执行 SQL，本仓库现在提供了一个可直接连 PostgreSQL 的 live bootstrap 脚本：


acr-engine/scripts/bootstrap_phase1_model_registry_live.py


用途：


向目标 schema 写入 model_registry

写入 feature_set_registry

写入 reference_set_registry

采用 幂等式 upsert / ensure 方式，适合重复执行


8.1 执行命令

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/bootstrap_phase1_model_registry_live.py \
  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
  --schema acr_test \
  --output data/pgvector_eval/music20/phase1_registry_bootstrap_report.json


8.2 当前已验证结果（acr_test）

本轮已在 acr_test schema 上真实执行，写入结果如下：


对象
数量


model_registry
5


feature_set_registry
6


reference_set_registry
2


其中新增的 Phase-1 对象包含：


models


chromaprint v1
mert v1-95m
muq large-msd-iter
ecapa acr-baseline-v1


feature sets


chromaprint fingerprint_asset
mert semantic_embedding 5s/2.5s
mert semantic_embedding 10s/5s
muq semantic_embedding 5s/2.5s
ecapa semantic_embedding 5s/2.5s


reference set


phase1_hot_reference_v1


8.3 当前产物


acr-engine/data/pgvector_eval/music20/phase1_registry_bootstrap_report.json
acr-engine/data/pgvector_eval/music20/phase1_registry_bootstrap_idempotency_report.json


这个文件已经记录了：


model_id
feature_set_id
reference_set_id
最终表计数


因此，下次 session 不需要再从 SQL 片段手工执行开始，而可以直接从 live bootstrap 脚本接上。


8.4 幂等性验证（已做）

同一套命令在 acr_test schema 上连续执行两次后，已经拿到真实幂等性证据：


项目
第 1 次
第 2 次


model_registry
5
5


feature_set_registry
6
6


reference_set_registry
2
2


第二次执行时：


models 全部表现为 updated


feature_sets 全部表现为 reused


reference_set 表现为 updated


结论：


当前 bootstrap 脚本可重复执行，不会把 Phase-1 registry 数据重复灌爆。


9. Phase-1 extraction job bootstrap

当 model_registry / feature_set_registry / reference_set_registry 都已经存在后，下一步不是立刻手工跑抽特征，而是先把 待执行 job 写到 feature_extraction_job。

本仓库现在已经提供：


acr-engine/scripts/bootstrap_phase1_extraction_jobs_live.py


用途：


根据已存在的 feature_set_registry

为 phase1_hot_reference_v1 生成待执行 extraction jobs
把 Phase-1 的 exact / semantic lanes 统一放进 PostgreSQL job 表


9.1 执行命令

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/bootstrap_phase1_extraction_jobs_live.py \
  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
  --schema acr_test \
  --output data/pgvector_eval/music20/phase1_extraction_jobs_report.json


9.2 当前已验证结果（acr_test）

本轮已真实创建 5 条待执行 job：


lane
model
feature
target_scope
status


exact
chromaprint
fingerprint_asset
reference_set:phase1_hot_reference_v1
pending


semantic
mert

semantic_embedding 5s/2.5s
reference_set:phase1_hot_reference_v1
pending


semantic
mert

semantic_embedding 10s/5s
reference_set:phase1_hot_reference_v1
pending


semantic
muq

semantic_embedding 5s/2.5s
reference_set:phase1_hot_reference_v1
pending


semantic
ecapa

semantic_embedding 5s/2.5s
reference_set:phase1_hot_reference_v1
pending


对应 live 报告：


acr-engine/data/pgvector_eval/music20/phase1_extraction_jobs_report.json


这意味着：


现在 PostgreSQL 里已经不只是“模型定义”和“特征定义”，而是连 下一步该跑哪些抽特征任务 都已经具备结构化入口了。


10. Phase-1 extraction plan（从 pending jobs 生成）

当 feature_extraction_job 已经存在后，下一步通常不是马上手敲命令，而是先从 PostgreSQL 生成一个统一执行计划。

本仓库现在已经提供：


acr-engine/scripts/plan_phase1_extraction_jobs_live.py


用途：


读取 feature_extraction_job

过滤 job_status=pending

联表 feature_set_registry + model_registry

生成按 lane / priority 排序的 execution plan


10.1 执行命令

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/plan_phase1_extraction_jobs_live.py \
  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
  --schema acr_test \
  --job-status pending \
  --output data/pgvector_eval/music20/phase1_extraction_plan_report.json


10.2 当前已验证结果（acr_test）

本轮已真实生成一份 ordered execution plan：


order
lane
model
feature
physical_target


1
exact
chromaprint
fingerprint_asset
audio_fingerprint


2
semantic
mert
semantic_embedding 5s/2.5s
audio_embedding


3
semantic
mert
semantic_embedding 10s/5s
audio_embedding


4
semantic
muq
semantic_embedding 5s/2.5s
audio_embedding


5
semantic
ecapa
semantic_embedding 5s/2.5s
audio_embedding


其中 planner 还会自动给出：


vector_table


audio_embedding_vector_768
audio_embedding_vector_192


target_scope
execution_notes


当前产物：


acr-engine/data/pgvector_eval/music20/phase1_extraction_plan_report.json


结论：


现在 PostgreSQL 里已经不仅能描述“有哪些 job”，还可以直接生成按执行顺序排好的抽特征计划。


10.3 ready-to-run command suggestions（已补齐）

本轮又进一步把 planner 升级为：每条 job 都生成 command suggestion。

示例：


exact lane

cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" EXTRACTION_JOB_ID=1 FEATURE_SET_ID=2 TARGET_SCOPE='reference_set:phase1_hot_reference_v1' PG_SCHEMA=acr_test OUTPUT_TARGET=audio_fingerprint \
/usr/local/miniconda3/bin/python workers/run_chromaprint_job.py --complete-dry-run


semantic lane

cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" EXTRACTION_JOB_ID=2 FEATURE_SET_ID=3 TARGET_SCOPE='reference_set:phase1_hot_reference_v1' PG_SCHEMA=acr_test MODEL_NAME=mert MODEL_VERSION=v1-95m VECTOR_TABLE=audio_embedding_vector_768 OUTPUT_TARGET=audio_embedding \
/usr/local/miniconda3/bin/python workers/run_embedding_job.py --complete-dry-run


这意味着下个 session 不需要先手工拼环境变量和 job 绑定关系，而可以直接从 planner 报告里复制命令模板。


10.4 planner 现在也会附带 validation commands

除了 per-job command suggestion，当前 planner 还会输出一组全局验证入口：


prereq_audit
worker_contract_smoke
semantic_vector_negative_matrix
asset_level_upsert_validation


也就是：


先审计 host 前置条件
再跑 exact+semantic 的 contract smoke
再检查 semantic vector-table 负例是否稳定
再验证 asset-level upsert contract


这让 planner 从“只会排任务”升级成“同时给出执行前检查入口”的交付物。