production-encoder-freeze-and-embedding-strategy.md 18.6 KB

Raw Blame History Permalink



Production Encoder Freeze & Embedding Strategy / 生产 Encoder 冻结与 Embedding 策略答疑


更新：2026-06-03

关联文档：持续开发交接文档 · PostgreSQL 数据模型 · Phase-1 实施清单


一页结论

围绕你当前最关心的生产问题，可以先压缩成 6 句话：


当前先冻结 encoder 是正确决定。 对 30 万首生产曲库来说，先稳定 embedding 空间，比继续频繁改模型更重要。

当前结构具备泛化能力。 线上识别主路径是“固定 encoder 抽 embedding + reference 检索”，不是只能识别训练时见过的 closed-set 分类标签。

模型权重可以外置复用。 你可以把当前 best_model.pt 当成独立 encoder，用在别的 wav/mp3/flac/ogg 歌曲集合上。

如果 encoder 变了，向量库就必须重建。 歌曲元数据不用重做，但所有旧 embedding / ANN index / pgvector 向量都应视为旧版本。

30 万首场景下必须做 embedding 版本化。 不建议“直接覆盖旧库”，而应并行维护 encoder_version=v1/v2/...。
最稳的上线策略是：先冻结 v1，上线使用；新模型只做离线 shadow build + A/B，收益足够大再切换。


1. 当前项目进度：已经走到哪里


1.1 当前状态

根据 持续开发交接文档，当前项目已经从“原型是否能跑通”进入“真实数据验证 + 工程化推进”阶段：


synthetic 数据链路已跑通：生成、训练、建索引、识别、评测都已具备
开放数据链路已闭环：inspect-local -> prepare-local -> validate-local -> train -> build-index -> evaluate -> generate_artifacts

当前最佳候选方向已收敛到 hum_focus

真实 FMA smoke 已跨过训练，进入了 build-index 阶段


这说明当前不是“从零开始想方案”，而是已经具备：


一个可以独立抽 embedding 的 encoder
一个可以对 reference 曲库建索引的 pipeline
一个可以对 query 做识别的 hybrid 检索链路


1.2 当前最适合的策略

在这个阶段，最重要的不是继续频繁换 encoder，而是：

flowchart TD
    A[已有可运行模型与索引链] --> B[冻结生产 Encoder v1]
    B --> C[完成 30 万首建库与使用]
    C --> D[收集真实线上/离线问题]
    D --> E[离线评估新 Encoder v2]
    E --> F[证明显著收益后再迁移]


也就是：先让一版可用的 embedding 体系稳定下来，再做后续升级。


2. 当前结构是否有泛化能力


2.1 简短回答

有。

但这里的“泛化”要分成两层理解：


泛化层次
当前是否支持
说明


新歌曲入库后可被识别
支持
只要用同一 encoder 生成 reference embedding 即可


完全未知分布上保持稳定高精度
尚未完全证明
当前更多是结构可行、真实大规模效果还需继续验证


2.2 为什么说当前结构具备泛化能力

当前识别主链路不是：


“输入 query -> 分类头直接输出某个固定 song class”


而是：


“输入 query -> encoder 抽 embedding -> 在 reference embedding 库中做相似度检索”


结构图如下：

flowchart LR
    Q[query wav/mp3 片段] --> E1[冻结 Encoder v1]
    E1 --> QE[query embedding]
    QE --> S[similarity search]

    R[30 万首 reference 曲库] --> E2[同一个冻结 Encoder v1]
    E2 --> RE[reference embeddings]
    RE --> S

    S --> O[候选歌曲 + 分数]


这种结构天然支持：


新歌曲加入 reference 曲库
不重训模型的情况下扩歌库
针对 query 做检索而不是固定类分类


2.3 但泛化能力的上限受什么影响

当前真实效果主要还受这些因素制约：


训练数据分布


目前 hard case 已关注 humming_like / confused

但你的线上 30 万首曲库是否和当前训练/验证分布一致，仍需要真实数据验证


reference 建库方式


当前 reference 端是 5 秒窗口 + 2.5 秒 stride 的重叠滑窗
这对片段识别是好的，但代价是窗口数上升、建库成本变高


query 形式差异


无损整曲、压缩 mp3、录音片段、截短片段、混响/手机采样等都会影响效果


混合检索策略


当前不是纯 embedding 检索，而是 chromaprint + embedding + melody rerank 的 hybrid
这对鲁棒性是加分项，但也意味着线上治理时要同时考虑指纹索引和向量索引


3. 为什么当前先冻结 Encoder


3.1 业务原因

你现在的生产环境里有 30 万首歌曲。这会带来一个决定性的工程事实：


一旦 encoder 改了，就不是“换个模型文件”这么简单，而是整套向量空间都可能变。


如果还没冻结 encoder，就会出现这些问题：


今天建的 30 万 embedding，明天可能全部作废
pgvector / Faiss / Milvus / 自研 ANN 索引都要全量重建
离线评测和线上灰度无法稳定对齐
回滚困难：你很难知道 query 是按哪个模型算的，reference 又是按哪个模型建的


3.2 工程原因

冻结 encoder 后，你才能稳定以下这些对象：


资产
是否应随 encoder 冻结
原因


best_model.pt
是
它决定向量空间


n_mels/sample_rate/window/stride
是
这些决定 embedding 分布


embedding_dim
是
向量表结构和索引依赖它


reference embeddings
是
必须和 query embedding 同版本


ANN index / pgvector 索引
是
建立在具体 embedding 空间上


3.3 当前建议的冻结定义

建议把当前生产 encoder 冻结为一组明确配置，而不是只记一个文件名。

推荐至少记录这些字段：

encoder_version: ecapa_hum_focus_v1
checkpoint_path: /abs/path/to/best_model.pt
embedding_dim: 192
sample_rate: 16000
n_mels: 128
n_fft: 512
hop_length: 160
reference_window_sec: 5.0
reference_stride_sec: 2.5
query_runtime_window_sec: 5.0
feature_family: mel
index_family: hybrid_chromaprint_ecapa
status: frozen_for_production


4. 模型权重能否外置，给其他歌曲使用


4.1 简短回答

可以，而且应该这样做。

你可以把当前冻结好的 best_model.pt 视为一个独立的音乐 embedding encoder，用来处理：


新增歌曲入库
旧歌库全量建 embedding
任意 query 音频片段识别
后续 pgvector / ANN 向量服务对接


4.2 外置使用时的推荐组织方式

推荐把“模型”和“索引产物”分开管理：

flowchart TD
    A[models/] --> A1[ecapa_hum_focus_v1/best_model.pt]
    A --> A2[ecapa_hum_focus_v1/encoder_manifest.yaml]

    B[indexes/] --> B1[ecapa_hum_focus_v1/chromaprint.pkl]
    B --> B2[ecapa_hum_focus_v1/reference_embs.npy]
    B --> B3[ecapa_hum_focus_v1/reference_ids.npy]
    B --> B4[ecapa_hum_focus_v1/index_metadata.json]

    C[metadata/] --> C1[song_catalog.csv]
    C --> C2[manifests/catalog.json]


4.3 外置后能做什么


场景 A：直接给新歌曲建库


你有一批新歌（wav/mp3/flac/ogg）
不重训
用冻结 encoder 直接建 reference embedding
加入曲库识别


场景 B：给 query 片段做识别


你有 5~10 秒左右的查询片段
用同一 encoder 抽 query embedding
在 reference 库做相似度匹配


场景 C：离线批量生成 pgvector/ANN 数据


你可以把 reference embeddings 作为离线产物导出
再灌入 PostgreSQL + pgvector / Faiss / Milvus / 自研检索服务


5. 你手头有无损、压缩、片段等 wav/mp3 文件集合，应该怎么直接使用


5.1 总体原则

你手头的文件不需要先人工区分“是不是训练专用格式”。

当前最重要的是把它们统一进入这套结构：

flowchart LR
    A[原始 wav/mp3/flac/ogg] --> B[标准化目录]
    B --> C[manifest]
    C --> D[reference 建库]
    C --> E[query 验证]
    D --> F[线上识别/检索]


5.2 建议先分三类素材


类别
作用
建议处理方式


完整歌曲 / 主版本
做 reference
全部入库


截断片段 / 业务 query 样本
做评测 query
固定留作测试集


低码率/手机录音/混响压缩片段
做 hard case query
用来验证鲁棒性


5.3 最短直接使用流程


第 1 步：冻结 encoder v1

先不要继续换模型，先把当前决定好的 checkpoint 固定下来。


第 2 步：准备音频目录

例如：

input_music/
  song_a.flac
  song_b.mp3
  song_c.wav
  ...


第 3 步：检查目录是否适合进入当前链路

cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python src/data/manifest_tools.py inspect-audio-dir \
  /abs/path/to/input_music \
  --query-duration 8.0 \
  --eval-ratio 0.2


第 4 步：生成统一 manifest

cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python src/data/manifest_tools.py audio-dir-to-splits \
  /abs/path/to/input_music \
  /abs/path/to/output_dataset \
  --source-dataset prod_music \
  --eval-ratio 0.2 \
  --query-duration 8.0 \
  --query-strategy hybrid \
  --query-stride 2.5


建议说明：


query-duration=8.0：适合作为线下验证 query 长度

query-strategy=hybrid：更贴近当前项目已有的音乐感知切片方向

query-stride=2.5：如果你希望验证覆盖率更高，可以生成更多 query


第 5 步：用冻结 encoder 建 reference index

cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python run_demo.py build-index \
  --data /abs/path/to/output_dataset/manifests \
  --model /abs/path/to/frozen/best_model.pt \
  --output /abs/path/to/output_index \
  --device cpu


第 6 步：做离线识别验证

cd /root/vprecog/acr-engine
/usr/local/miniconda3/bin/python evaluate.py \
  --data /abs/path/to/output_dataset/manifests \
  --model /abs/path/to/frozen/best_model.pt \
  --index-prefix /abs/path/to/output_index/reference \
  --split test \
  --device cpu \
  --fast-eval \
  --output-json /abs/path/to/output_reports/eval.json


第 7 步：确认后再推到生产向量库

当离线评测满足最低要求后，再把 reference embedding 导入生产检索系统，而不是一上来直接刷 30 万首正式库。


6. 如果要快速微调，应该怎么做


6.1 原则

“快速微调”不等于“马上用 30 万首全量重训”。

对你当前场景，最合理的是：


先冻结生产 encoder v1
用一个代表性子集训练/微调候选 v2
只在离线环境评估 v2
证明收益大于迁移成本，才考虑升级生产 encoder


6.2 推荐的微调子集组成

建议优先抽一个 几千到几万首规模的代表性集合，覆盖：


无损高质量版本
常见压缩版本（mp3/aac 等）
短片段
开头/中段/结尾片段
旋律近似、编曲相似的易混淆歌曲
手机采样 / 录屏 / 二次压缩音频
业务上最常见失败样本


6.3 推荐微调流程

flowchart TD
    A[冻结 Encoder v1] --> B[抽代表性子集]
    B --> C[生成 manifests]
    C --> D[训练 v2 候选]
    D --> E[建 v2 索引]
    E --> F[固定测试集评测]
    F --> G{收益显著?}
    G -- 否 --> H[继续使用 v1]
    G -- 是 --> I[准备 30 万首离线重刷 v2]


6.4 微调时的判断标准

不要只看训练 loss，至少要看：


指标
作用


top1 / topk
基本识别率


hard-case 命中率
看压缩/片段/混淆样本提升是否真实


新增模型对旧强项的回退
防止“补一个洞，漏一大片”


全量建库速度
看新模型是否导致生产成本显著上升


线上 query 延迟
看推理成本是否可接受


6.5 微调后的发布原则

微调完成后不要立刻替换 v1，而要：


标记为 encoder_version=v2_candidate

只做离线建库和评测
在真实样本上和 v1 做 A/B
显著更优后再升级


7. 如果 embedding 变了，哪些数据必须重建


7.1 要区分“元数据”和“向量数据”


数据类型
是否需要重建
说明


歌曲主数据（song_id/路径/业务标签）
通常不需要
这些不依赖向量空间


manifest
通常不需要全重做
除非你的切片策略/数据治理规则也变了


reference embeddings
必须重建
因为 encoder 变了


query embeddings 缓存
必须重建
否则和 reference 不同空间


pgvector 行数据
必须重建
向量本体变了


ANN 索引（Faiss/Milvus/HNSW/IVF 等）
必须重建
建立在旧向量之上


chromaprint 索引
不一定
只要指纹算法不变，可独立复用


7.2 为什么必须重建

因为向量相似度检索默认假设：


query embedding 和 reference embedding 来自同一个特征空间。


如果 query 用的是 encoder v2，reference 还停留在 encoder v1，就会出现：


分数不可比
recall 明显下降
线上结果随机波动
A/B 结论失真


7.3 推荐的迁移策略

不要“原地覆盖旧 embedding”，而应采用双版本并行：

flowchart LR
    A[Encoder v1] --> B[index_v1]
    C[Encoder v2] --> D[index_v2]
    E[Query] --> F{使用哪个版本?}
    F --> B
    F --> D


推荐步骤：


保留 v1 生产库不动
离线刷 v2 的 30 万 embedding
建 v2 的 ANN / pgvector 索引
用相同 query 集对比 v1/v2
确认收益后切主流量
回滚时直接切回 v1


8. 30 万首生产环境推荐的版本化方案


8.1 推荐最小字段


歌曲元数据表


字段
说明


song_id
稳定歌曲 ID


audio_uri
原始音频路径/对象存储地址


duration_sec
时长


codec/container
格式信息


catalog_status
是否可入 reference 库


business_tags
业务标签


embedding 表


字段
说明


song_id
对应歌曲


encoder_version
如 ecapa_hum_focus_v1


window_index
第几个 reference window


offset_sec
窗口起点


embedding_dim
例如 192


embedding
向量本体


built_at
构建时间


source_audio_hash
原音频指纹/摘要，便于查重与失效控制


index manifest


字段
说明


encoder_version
当前索引对应的 encoder


checkpoint_path
模型文件


feature_config
mel/n_mels/sample_rate 等


reference_window_sec
例如 5.0


reference_stride_sec
例如 2.5


catalog_size
曲库规模


num_reference_windows
总窗口数


built_at
构建时间


8.2 推荐目录结构

prod_artifacts/
  models/
    ecapa_hum_focus_v1/
      best_model.pt
      encoder_manifest.yaml

  indexes/
    ecapa_hum_focus_v1/
      chromaprint.pkl
      chromaprint_progress.json
      reference_embs.npy
      reference_ids.npy
      index_metadata.json

  reports/
    ecapa_hum_focus_v1/
      eval.json
      hard_case_eval.json


9. 当前建议的生产操作手册


9.1 目标

当前目标不是继续改模型，而是先完成：


冻结 encoder v1
用 v1 支撑第一版 30 万首曲库建库
建立版本化规范
为后续 v2 升级预留迁移机制


9.2 分步操作


Phase 1：冻结与归档


 选定当前生产 checkpoint

 为该 checkpoint 生成 encoder_manifest.yaml


 记录 encoder_version


 固定 reference window / stride / mel 配置

 禁止直接覆盖此 checkpoint


Phase 2：小规模真实集验证


 抽 1k~10k 首真实歌曲做第一次建库

 抽真实 query 集做评测

 统计 top1/topk/hard-case 结果

 验证索引构建速度、磁盘占用、查询延迟


Phase 3：30 万首全量离线建库


 清洗 song_id 与元数据

 生成标准 catalog/manifests

 用冻结 encoder v1 批量生成 reference embeddings

 生成 chromaprint / 向量索引

 导入生产检索服务


Phase 4：上线与观测


 上线 v1

 记录 query 失败样本

 归档 hard-case

 为 v2 微调准备离线样本集


Phase 5：未来升级


 训练 v2_candidate


 离线全量重刷 index_v2


 做离线 A/B

 收益显著后再切换主版本


10. 常见问题 FAQ


10.1 我现在有一大堆 wav/mp3，可以直接用吗？

可以。

先不要纠结格式本身，先把它们组织成统一音频目录，再生成 manifests，再用冻结 encoder 建 reference index。


10.2 无损和压缩版本要不要分开？

建议保留来源信息，但 reference 主库优先保留“主版本”。

如果同一首歌有多个编码版本：


主版本作为 reference 主资产
其他压缩版本优先作为评测 query / hard case


这样更利于真实评估鲁棒性。


10.3 片段文件可以直接拿来做 query 吗？

可以。

尤其适合作为：


clean query
compressed query
hard case query


但如果要把它当训练样本，最好仍然能回溯到稳定的 song_id 和原 reference。


10.4 如果后面发现 encoder 不够好怎么办？

不要直接替换现网。正确做法是：


保持 v1 不动
离线训练 v2
离线重刷 v2 的全量 embedding
对比 v1/v2
确认收益后再切


10.5 现在有没有必要立刻上全量 30 万首？

建议先做一轮中等规模验证，再上全量。

推荐先做：


1k 首小验证
1w~5w 首中等规模验证
验证速度/精度/存储后，再上 30 万


10.6 现阶段最重要的一句话建议是什么？


先冻结 encoder v1，把 embedding/version/index 治理做好，再讨论 v2。


11. 最终建议

对你现在的阶段，我的建议优先级是：


冻结当前 encoder
建立 embedding 版本化规范
先做小到中规模真实集建库验证
再推进 30 万首全量建库
把新模型升级变成“离线重刷 + A/B + 切换”的标准动作


这样做的好处是：


你现在就能开始用
后面也不会因为继续调模型把生产库拖乱
未来升级有明确路径，不会出现“模型变了，数据全乱了”的问题


Sources


持续开发交接文档
postgresql-data-model.md
phase1-implementation-checklist.md
phase1-worker-contract.md
acr-engine/train.py
acr-engine/run_demo.py
acr-engine/src/engines/ecapa_embedder.py
acr-engine/src/data/manifest_tools.py