nemotron-3-diarization-coreml 状态管理实战:spkcache 与 FIFO 更新循环、可学习静音嵌入的隐藏坑

原创2026-11-12 22:40:591,329 阅读
文章标签:语音本地部署深度学习

nemotron-3-diarization-coreml 状态管理实战:spkcache 与 FIFO 更新循环、可学习静音嵌入的隐藏坑

nemotron-3-diarization-coreml 是 NVIDIA Nemotron-3 说话人分离(Speaker Diarization)模型的 Core ML 导出版,可在 macOS 14+ / iOS 17+ 上完全离线、端侧运行流式说话人分离。它的模型是无状态的:每次调用只处理一个音频 chunk,全部"记忆"都由宿主代码通过两块状态张量 spkcache(说话人缓存)和 fifo(滚动缓冲),外加一个 512 维可学习静音嵌入(learnable silence embedding)来维护。本文带你走通这套状态管理:更新循环怎么转、哪里最容易踩坑。

先搞清楚:模型接口长什么样

整个包只有一个模型文件 nemotron_3_diarization.mlpackage,一次调用 = 一个 chunk,输入输出如下(详见 README.md 的 Interface 一节):

输入 形状 说明
chunk 1 × 3040 × 128 log-mel 特征,10 ms 跳帧
chunk_lengths 1 int32
spkcache 1 × 264 × 512 说话人缓存(宿主维护)
spkcache_lengths 1 int32
fifo 1 × 40 × 512 滚动嵌入缓冲(宿主维护)
fifo_lengths 1 int32
输出 形状
spkcache_fifo_chunk_preds 1 × 684 × 8
chunk_pre_encode_embs 1 × 380 × 512
chunk_pre_encode_lengths 1

几个数字值得先对一下账 🧮:

  • 每个 pre-encode 帧对应 80 ms 音频,chunk 的 3040 个 mel 帧经 8 倍下采样后正好得到 380 帧,其中 340 帧是新音频(27.2 秒),40 帧是右上下文;
  • 输出 preds 的 684 列 = 264(spkcache)+ 40(fifo)+ 380(chunk),即三段状态拼起来逐帧打 8 个说话人槽的分数;
  • 仓库交付的是 offline 档位(chunk 340 / 右上下文 40 / fifo 40 / spkcache 264),适合批处理;转换脚本 conversion/03_convert_coreml.py 里还内置了 low(1.04 s 缓冲)、verylow(0.64 s)、ultralow(0.32 s)三个更低延迟的档位。

更新循环:两次调用之间,宿主该做什么

README 里有一句最关键的话:"One call processes one chunk; the caller owns the speaker cache and FIFO update between calls"——状态更新的完整责任在调用方。标准流程是 NeMo 的 streaming_update 循环,共四步:

  1. 推理:把 chunk 加上当前 spkcache、fifo 一起喂给模型;
  2. 取结果:拿到 preds(684 × 8 的逐帧说话人分数)和 chunk_pre_encode_embs(本块新产生的 380 × 512 嵌入);
  3. 后处理:按 config.json 中 postprocessing 的参数(pred_score_threshold 0.25、onset/offset 0.5 等)把分数变成说话人活动区间;
  4. 更新状态:
    • fifo:把新的 pre-encode 嵌入追加进去,只保留最近的 40 帧;
    • spkcache:每 spkcache_update_period = 300 帧刷新一次,用最新的高分嵌入更新各说话人槽位;
    • 静音槽:每个说话人槽保留 1 帧静音位(spkcache_sil_frames_per_spk = 1),必须填入 learnable_sil_emb.f32 里的训练好向量——这是下一个标题的主角。

循环画出来就是这样(每 27.2 秒音频走一圈,约 21 ms 算力):

chunk + spkcache + fifo ──► Core ML 调用 ──► preds + 新嵌入
        ▲                              │
        └──── 宿主按 streaming_update 规则回填 ┘

⚠️ 可学习静音嵌入:三个最容易踩的坑

learnable_sil_emb.f32 是 512 个裸的 float32(小端)——这是模型训练出来的专用静音表示,不是"随便一段安静音频的均值"。围绕它有三条硬性要求,来自 README 的 "Required runtime settings":

坑 正确做法 踩了会怎样
用零向量、或"静音帧的运行均值"填充静音槽 用 learnable_sil_emb.f32 的训练向量填充 与训练分布不一致,结果开始漂移
spkcache_sil_frames_per_spk 随意设置 必须 = 1,和训练保持一致 一个声音被拆进多个说话人槽
流式几何参数自定 严格使用 offline 档位:chunk_len 340、右上下文 40、fifo_len 40、spkcache_len 264、更新周期 300 输出质量劣化

一句话总结:静音嵌入是"训练时学好的身份牌",自己算出来的均值填回去,模型认不出来。

想校验文件完整性?config.json 末尾为 learnable_sil_emb.f32、model.mlmodel、weight.bin 等每个文件都提供了 SHA-256。

精度陷阱:fp16 存储、fp32 计算

第二个"隐藏坑"不在状态里,而在数值精度上。这个包的策略是:权重以 fp16 存储(整包约 199 MB),加载时通过 constexpr_cast 展宽到 fp32,所有运算都在 fp32 完成。

为什么要这么绕?因为如果整条链都用 fp16 计算,每个 chunk 引入的微小舍入误差会经说话人缓存反馈回去、逐块累积——长音频越算越歪。实测在一段 36 分钟的会议录音上,纯 fp16 计算版与 NeMo 参考只对齐了 98.4%–98.9% 的帧,还会凭空多出一个说话人,而且 GPU、CPU、Neural Engine 上全都复现。实现细节可看 conversion/13_fp16_storage.py 的注释。

验证结果:帧级对齐 NeMo 参考

采用与 NeMo 相同的流式循环和后处理,在真实会议录音上的帧级一致率:

音频 NeMo 说话人数 Core ML 说话人数 帧级一致率
70 秒(单麦克风) 2 2 100.00%
36 分钟(麦克风轨) 4 4 99.94%
36 分钟(应用音频轨) 5 5 100.00%

速度约 21 ms / 27.2 秒 chunk——一段 36 分钟的录音算完大约 2 秒,端侧实时绰绰有余 ✅。

文件结构与上手

文件 作用
nemotron_3_diarization.mlpackage Core ML 模型(pre-encoder、Fast-Conformer、transformer、说话人头)
learnable_sil_emb.f32 512 维训练好的静音嵌入,用于填充 spkcache 静音槽
config.json 流式几何、缓存/后处理参数、I/O 形状、各文件 SHA-256
conversion/ 生成该包的脚本(转换、fp16 存储、coremltools 补丁)

其中 conversion/coreml_patches.py 把 NeMo 里不可 trace 的 FlexAttention 换成等价的 SDPA、用 gather 重写 concat_and_patch 等,是"能转成 Core ML"的关键;conversion/03_convert_coreml.py 则展示了完整的导出入口与四档延迟配置。

本地克隆仓库即可开始:

git clone https://gitcode.com/hf_mirrors/altic-dev/nemotron-3-diarization-coreml

最后再划一下重点 🎯:跑通 nemotron-3-diarization-coreml 的关键只有三件事——按 streaming_update 规则回填 spkcache 与 fifo、静音槽用 learnable_sil_emb.f32 填充且每说话人 1 帧静音位、流式几何参数与 offline 档位完全一致。做到这三点,就能拿到与 NeMo 参考 99.94% 以上的帧级对齐。

登录后查看全文
nemotron-3-diarization-coreml