nemotron-3-diarization-coreml 状态管理实战:spkcache 与 FIFO 更新循环、可学习静音嵌入的隐藏坑
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 循环,共四步:
- 推理:把
chunk加上当前spkcache、fifo一起喂给模型; - 取结果:拿到
preds(684 × 8 的逐帧说话人分数)和chunk_pre_encode_embs(本块新产生的 380 × 512 嵌入); - 后处理:按 config.json 中
postprocessing的参数(pred_score_threshold0.25、onset/offset0.5 等)把分数变成说话人活动区间; - 更新状态:
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% 以上的帧级对齐。