nemotron-3-diarization-coreml 接口参考:chunk、spkcache、fifo 输入输出张量逐个讲透

原创2026-11-12 15:41:21182 阅读
文章标签:语音本地部署深度学习

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 的前编码器嵌入,宿主程序要拿它更新自己的状态:
    1. 尾部 40 帧写入 fifo,供下一个 chunk 回看;
    2. 按 spkcache_update_period = 300(每 300 帧)的节奏刷新各说话人槽位在 spkcache 中的表示
  • 这套"宿主持有状态、每次调用传进传出"的循环对应 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 档。

六、一次完整调用的数据流

  1. 宿主侧把 30.4 秒音频算成 log-mel → 得到 chunk (1×3040×128)
  2. 把 spkcache、fifo(首次调用可全零/全静默嵌入)连同各自 lengths 一起喂给模型
  3. 拿到 spkcache_fifo_chunk_preds (1×684×8),按阈值后处理出说话人时间轴
  4. 用 chunk_pre_encode_embs (1×380×512) 更新 fifo(尾 40 帧)与 spkcache(每 300 帧刷新一次)
  5. 下一段音频,回到第 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 变化。

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