nemotron-3-diarization-coreml 接口参考:chunk、spkcache、fifo 输入输出张量逐个讲透
nemotron-3-diarization-coreml 接口参考:chunk、spkcache、fifo 输入输出张量逐个讲透
nemotron-3-diarization-coreml 是 NVIDIA Nemotron-3-Diarization 说话人分离(speaker diarization)模型的 Core ML 端侧部署包,可在 macOS 14+ / iOS 17+ 的 Apple Silicon 上本地运行。本文逐个讲透它的流式推理接口:6 个输入张量(chunk、spkcache、fifo 等)与 3 个输出张量的形状、数据类型,以及几个写错就会导致"一个人被拆成多个说话人"的关键运行时设置。
一、这个模型是什么?
- 架构:Streaming Sortformer(前编码器 + Fast-Conformer + Transformer + 说话人头),完整模型包见 nemotron_3_diarization.mlpackage
- 工作模式:一次调用只处理一个 chunk(27.2 秒音频)。模型本身是无状态的,跨 chunk 的"记忆"(谁说过话、上个 chunk 结尾是什么)由调用方通过
spkcache/fifo传入 - 精度策略:权重以 fp16 存储(约 199 MB),加载时提升为 fp32 参与计算(
constexpr_cast),避免长音频下 fp16 舍入误差经说话人缓存反复累积漂移,实现与转换脚本见 conversion/13_fp16_storage.py - 验证结果:在真实会议录音上与 NVIDIA NeMo 参考实现逐帧比对,36 分钟音轨的帧级一致率达 99.94%~100.00%,速度约 21 ms / 27.2 s chunk(一整段 36 分钟音频约 2 秒跑完),详见 README.md
一句话理解:模型是"无状态的函数",状态(说话人缓存 + FIFO)是"由宿主程序保管的便签本",每处理一段音频就传进去、拿回来更新一次。
二、接口总览:6 个输入,3 个输出
整个接口的形状定义在 config.json,导出时的张量声明在 conversion/03_convert_coreml.py。
输入张量
| 名称 | 形状 | 类型 | 一句话含义 |
|---|---|---|---|
chunk |
1 × 3040 × 128 | float32 | 本段音频的 log-mel 特征(10 ms 跳步) |
chunk_lengths |
1 | int32 | chunk 中有效帧数 |
spkcache |
1 × 264 × 512 | float32 | 说话人缓存:8 个说话人的"声纹便签" |
spkcache_lengths |
1 | int32 | spkcache 中有效帧数 |
fifo |
1 × 40 × 512 | float32 | 上一个 chunk 尾部留下的特征(右上下文) |
fifo_lengths |
1 | int32 | fifo 中有效帧数 |
输出张量
| 名称 | 形状 | 一句话含义 |
|---|---|---|
spkcache_fifo_chunk_preds |
1 × 684 × 8 | 每帧对 8 个候选说话人的激活预测 |
chunk_pre_encode_embs |
1 × 380 × 512 | 本 chunk 的前编码器特征,用于写回状态 |
chunk_pre_encode_lengths |
1 | 上者有效帧数 |
三、输入张量逐个讲
1. chunk + chunk_lengths:本段音频的 log-mel 特征
- 形状
1 × 3040 × 128:3040 个 log-mel 帧 × 128 维 mel 频带。3040 帧 × 10 ms 跳步 = 30.4 秒,恰好覆盖 offline profile 的chunk_len 340 + chunk_right_context 40(共 380 个 80 ms 模型帧) - mel 特征不在模型图内:由宿主程序(你的音频前端)在外部计算后传入。这样前端参数即使有微小漂移,也不会与转换误差混在一起,是刻意的接口边界设计(见 conversion/03_convert_coreml.py 的说明)
chunk_lengths是 int32 标量。为什么不是 int64?因为 Core ML 不支持 int64 输入,导出包装层会在图内部把它to(torch.int64)还原(见 conversion/03_convert_coreml.py)
2. spkcache + spkcache_lengths:说话人缓存
- 形状
1 × 264 × 512:264 帧 × 512 维嵌入,是spkcache_len 264在 config.json 中定义的容量上限 - 它对应 8 个说话人槽位(
n_spk = 8,见 config.json),作用是把"模型已经见过的每个说话人是谁"压缩成声纹向量存进来,让模型在后续 chunk 中把同一人的声音归到同一个槽位 - ⚠️ 静默槽位的填法有讲究:空槽必须填充
learnable_sil_emb.f32(512 个原生小端 float32,即训练出的"静默嵌入"),不能用静音帧的滑动均值。这一点在 learnable_sil_emb.f32 和 README.md 中都被特别强调
3. fifo + fifo_lengths:跨 chunk 的"接力棒"
- 形状
1 × 40 × 512:40 帧 × 512 维,正好等于chunk_right_context 40(3.2 秒) - 内容是上一个 chunk 末尾的前编码器特征。流式推理时,模型需要"往回看"一点上下文,
fifo就是这段回看窗口 - 它保证 chunk 边界处的注意力不中断:当前 chunk 开头帧仍然能看到前一段结尾 40 帧的信息
四、输出张量逐个讲
1. spkcache_fifo_chunk_preds:逐帧说话人预测(核心结果)
- 形状
1 × 684 × 8。其中 684 = 264(spkcache)+ 40(fifo)+ 380(chunk 下采样后帧数),即把三段序列拼接起来、逐帧预测 - 每帧 8 个值对应 8 个说话人槽位的激活分数(softmax 概率)
- 拿到分数后还需一步后处理:
pred_score_threshold = 0.25、onset = 0.5、offset = 0.5,再转成"谁在哪个时间区间说话"的语音活动段(参数见 config.json)
2. chunk_pre_encode_embs + chunk_pre_encode_lengths:写回状态的"新便签"
- 形状
1 × 380 × 512:380 = 3040 / 8,即 log-mel 经 8 倍下采样(subsampling_factor)后的模型帧数,每帧 512 维 - 它就是本 chunk 的前编码器嵌入,宿主程序要拿它更新自己的状态:
- 尾部 40 帧写入
fifo,供下一个 chunk 回看; - 按
spkcache_update_period = 300(每 300 帧)的节奏刷新各说话人槽位在spkcache中的表示
- 尾部 40 帧写入
- 这套"宿主持有状态、每次调用传进传出"的循环对应 NeMo 的
streaming_update,也是模型保持无状态、便于 Core ML 部署的原因
五、⚙️ 必须与训练一致的运行时设置
这些参数如果和训练时不一致,后果是同一个声音被拆进多个说话人槽位(人变多了,但音频没变)。来源:README.md。
| 设置 | 要求值 | 说明 |
|---|---|---|
spkcache_sil_frames_per_spk |
1 |
每个说话人槽位的静默帧数 |
| 静默槽填充 | learnable_sil_emb.f32 |
禁用"静音帧均值"方案 |
chunk_len |
340 |
offline profile,对应 27.2 s |
chunk_right_context |
40 |
右上下文帧数 |
fifo_len |
40 |
FIFO 容量 |
spkcache_len |
264 |
说话人缓存容量 |
spkcache_update_period |
300 |
说话人缓存刷新周期 |
💡 注意:本包按 offline profile 导出。转换脚本里还保留了
low/verylow/ultralow三个低延迟档(1.04 s / 0.64 s / 0.32 s 缓冲),见 conversion/03_convert_coreml.py,但发布包的张量形状固定为 offline 档。
六、一次完整调用的数据流
- 宿主侧把 30.4 秒音频算成 log-mel → 得到
chunk (1×3040×128) - 把
spkcache、fifo(首次调用可全零/全静默嵌入)连同各自 lengths 一起喂给模型 - 拿到
spkcache_fifo_chunk_preds (1×684×8),按阈值后处理出说话人时间轴 - 用
chunk_pre_encode_embs (1×380×512)更新fifo(尾 40 帧)与spkcache(每 300 帧刷新一次) - 下一段音频,回到第 1 步
整条链路的转换与兼容性补丁(把 FlexAttention 换成 SDPA、用 gather 重写 concat_and_pad 等)在 conversion/coreml_patches.py 中可以查到。
七、相关文件速查
| 文件 | 内容 |
|---|---|
| config.json | 流式几何、缓存设置、后处理参数、I/O 形状与各文件 SHA-256 |
| README.md | 精度说明、验证结果、接口与运行时设置 |
| learnable_sil_emb.f32 | 512 维小端 float32 静默嵌入,用于填充说话人缓存静默槽 |
| conversion/03_convert_coreml.py | 核心导出脚本:接口定义、profile 选择、Core ML 转换 |
| conversion/13_fp16_storage.py | fp16 存权 + fp32 计算的精度导出方案 |
| conversion/coreml_patches.py | 让 NeMo 计算图可被 torch.jit 追踪的兼容补丁 |
八、常见疑问
Q:为什么三个 lengths 都是 int32? Core ML 没有 int64 张量输入, lengths 在包装层进入图后立即还原为 int64 供 NeMo 图使用,对外接口因此统一为 int32。
Q:spkcache_fifo_chunk_preds 为什么是 684 帧而不是 380?
它是三段拼接后的逐帧预测(264 spkcache + 40 fifo + 380 chunk)。真正对应当前 chunk 音频的是最后 380 行;前面的行主要服务于缓存与上下文的一致更新。
Q:静默槽为什么非要用 learnable_sil_emb.f32?
该嵌入是训练时学到的"标准静默表示"。若用运行时均值替代,槽位向量会偏离训练分布,等价于让模型遇到一种"没见过的静默",容易误判出额外的说话人。
Q:这个包能直接用于实时直播吗?
发布包是 offline profile(30.4 s 缓冲,一次调用 27.2 s 音频)。实时低延迟需要基于同一转换流程另导出 low / ultralow profile,接口形态相同,但各张量形状会随 profile 变化。