torch.jit.trace 实战解析:parakeet-ctc-110m-coreml 如何把 PyTorch 模型编译成 CoreML

原创2026-11-11 18:54:431,870 阅读
文章标签:语音人工智能本地部署

torch.jit.trace 实战解析:parakeet-ctc-110m-coreml 如何把 PyTorch 模型编译成 CoreML

parakeet-ctc-110m-coreml 是 NVIDIA Parakeet-TDT-CTC-110M 语音识别(ASR)模型的 CoreML 转换版,让模型可以直接跑在 Apple Silicon 上。它的核心转换手段就是 torch.jit.trace:先用一段有代表性的 15 秒音频"录制"出 PyTorch 的静态计算图,再交给 coremltools 编译成可在 macOS / iOS 上直接运行的 mlprogram 模型。

这篇文章带你完整走一遍这套 PyTorch 模型转 CoreML 的流水线:为什么要分组件导出、torch.jit.trace 的实战要点、输入输出契约怎么定、以及如何验证转换结果。


🧩 项目速览:一个"双头"语音识别模型

Parakeet-TDT-CTC-110M 是一个混合(hybrid)ASR 模型:共享同一个 Conformer 编码器,但挂了两套解码头,各司其职。

组件 作用 典型体积
Preprocessor 音频波形 → Mel 频谱 ~1 MB
Encoder Conformer 编码器(共享) ~400 MB
CTCHead CTC 输出投影,贪心解码,适合关键词检测 ~4 MB
Decoder TDT 预测网络(LSTM) ~25 MB
JointDecision TDT joint 网络 + 决策头 ~6 MB

整体规模约 436 MB,在 M4 Pro 上实测可达 358 倍实时(RTFx),Earnings22 数据集上 WER 为 17.97%,关键词召回率 100%(详见 README.md)。

本次导出的三个模型目录就对应其中几个组件:


📦 转换流水线总览:从 NeMo 到 mlpackage 的 5 步

转换入口是 convert-parakeet.py,整个流程可以概括为 5 步:

NeMo 模型(.nemo)
   │ ① 加载 / 自动下载
   ▼
② 用 Wrapper 包装各子模块(统一输入输出签名)
   │
   ▼
③ torch.inference_mode 下先跑一次"参考前向",得到参考输出
   │
   ▼
④ torch.jit.trace 录制静态计算图(每个组件单独 trace)
   │
   ▼
⑤ ct.convert 编译为 CoreML(mlprogram),保存 .mlpackage + 元数据

第 1 步:加载 NeMo 模型

脚本通过 nemo.collections.asr 的 EncDecHybridRNNTCTCBPEModel 恢复混合模型(见 convert-parakeet.py),支持本地 .nemo 文件或直接按 model_id 自动下载。加载后调用 asr_model.eval() 切到推理模式——eval 模式是 trace 的前提,否则 Dropout 等层会引入不确定性。

第 2 步:Wrapper 统一接口签名

NeMo 原生的子模块参数形式比较"随性"(keyword 参数、states 元组等),不利于直接 trace。项目在 individual_components.py 中为每个子模块写了轻量包装层,例如 CTCHeadWrapper:

class CTCHeadWrapper(torch.nn.Module):
    def forward(self, encoder_outputs: torch.Tensor) -> torch.Tensor:
        # 输入: [B, D_enc, T],输出: log probs [B, T, vocab+1]
        log_probs = self.module(encoder_output=encoder_outputs)
        return log_probs

包装层只做三件事:统一为位置参数、完成 dtype 转换、把嵌套返回值拆成扁平张量。这样 trace 出来的图干净、输入输出契约明确。

第 3 步:先跑"参考前向"

正式 trace 之前,脚本先在 torch.inference_mode() 下用一段真实的 15 秒音频(内置 yc_first_minute_16k_15s.wav,找不到则用随机噪声)跑一遍全部组件,得到 mel 特征、编码器输出、CTC log probs 等参考结果(convert-parakeet.py)。

这一步有两个用途:

  1. 确定形状:后续定义 CoreML 输入输出 Schema 时,直接引用参考张量的真实 shape;
  2. 精度校验基准:转换后可以逐组件对比最大绝对/相对误差。

第 4 步:torch.jit.trace 录制静态图

以 CTC 头为例(convert-parakeet.py):

traced_ctc_head = torch.jit.trace(ctc_head, (encoder_ref,), strict=False)
traced_ctc_head.eval()

torch.jit.trace 的本质是"带样例输入跑一遍 forward,把实际执行过的算子序列记录下来"。它不分析 Python 控制流,所以特别适合推理路径固定的模型——这正是 ASR 各子模块的特点。

全部 8 个导出目标(preprocessor、encoder、ctc_head、mel_encoder 融合版、decoder、joint、joint_decision、single_step joint_decision)都遵循同一模式:trace → 定义 ct.TensorType 输入输出 → ct.convert。

第 5 步:ct.convert 编译与保存

所有组件通过统一的 _coreml_convert 函数转换:

kwargs = {
    "convert_to": "mlprogram",   # 使用新版 MLProgram 格式
    "inputs": inputs,
    "outputs": outputs,
    "compute_units": cu,          # 各组件默认 CPU_ONLY
}

几个关键配置的意图:

  • convert_to="mlprogram":生成新式 mlmodelc 目录结构(model.mil + weights/weight.bin),而非旧的单文件 mlmodel;
  • minimum_deployment_target = iOS17:启用 iOS 17 / macOS 14 专属算子内核(如 Ios17.conv),_save_mlpackage 会逐个设置;
  • compute_precision 可选 FLOAT16:把非量化权重压到 fp16,直接看 CtcHead.mlmodelc/model.mil 就能发现权重已经以 fp16 常量形式写入 weight.bin。

转换完成后还导出 vocab.json(1024 词表 + blank)和 metadata.json,完整记录每个组件的输入输出 shape 与文件路径(convert-parakeet.py)。


🎯 torch.jit.trace 的 4 个实战要点

这套转换里对 trace 的处理相当讲究,归纳出 4 个值得学习的细节:

要点 1:用固定窗口"锁死"形状

trace 录下来的是静态图,形状信息来自样例输入。本项目统一锁定 15 秒窗口(max_audio_seconds=15.0,见 ExportSettings),于是所有组件形状稳定可预期:

张量 形状 来源
音频输入 [1, 240000] 15 s × 16 kHz
Mel 特征 [1, 1501, 80] 10 ms 帧移
编码器输出 [1, 512, 188] 下采样 8 倍
CTC logits [1, 188, 1025] 1024 词 + 1 blank

形状契约被完整记录在 ctc_head_metadata.json 中,运行时可直接校验。

变量长度的例外:只有 preprocessor 的音频输入用了 ct.RangeDim(1, max_samples) 声明可变长度(convert-parakeet.py),因为波形切片是最廉价的适配点——下游组件一律按固定 188 帧处理。

要点 2:trace 前 clone 掉推理张量

参考前向是在 torch.inference_mode() 下执行的,这类张量带有 inference 标志,直接拿去 trace 会报权限错误。脚本对每个参考张量先 .clone()(convert-parakeet.py)再传入 torch.jit.trace——这是 trace 时非常常见的坑。

要点 3:strict=False 放宽追踪

所有 trace 调用都带 strict=False,允许 trace 结果与原模块存在轻微结构差异而不中断,降低转换门槛。配合第 3 步的参考输出,精度问题可以在转换后量化对比发现,而不必在 trace 阶段"较真"。

要点 4:为流式推理定制"单步"变体

流式 ASR 的解码器每一步都要带上一步的 LSTM 状态。脚本把 decoder 的 _rnnt_export 标志置为 True(convert-parakeet.py),使 trace 出的解码器模型以外部状态 h_in/c_in 进、h_out/c_out 出的方式工作,max_symbol_steps=1 意味着模型只算一步,循环逻辑放在宿主侧。

更进一步,JointDecisionSingleStep 把输入切片到 [1, 512, 1] × [1, 640, 1],输出当前帧的 token_id、token_prob、duration 外加 top-K 候选(top_k=64),供宿主侧做上下文偏置重排——这是 trace 静态图与动态解码逻辑分工的典型示范:模型只做一步纯计算,调度交给外部。


✅ 如何验证转换结果

转换产物自带"证据链",验证起来很直观:

1. 看 MIL 图。CtcHead.mlmodelc/model.mil 全文只有几行,一眼看懂 CTC 头就是"1×1 卷积 + 转置 + softmax + log":

conv  →  transpose  →  softmax  →  log  →  ctc_logits

2. 看元数据。CtcHead.mlmodelc/metadata.json 记录了输入输出 Schema([1, 512, 188] → [1, 188, 1025])、算子直方图、存储精度(Float16),以及来源信息:source = torch==2.7.0、source_dialect = TorchScript——这正是 torch.jit.trace 的产物(TorchScript 图)被 coremltools 导入的直接证据。

3. 看权重与打包结构。CtcHead.mlpackage/Manifest.json 显示标准打包:Data/com.apple.CoreML/model.mlmodel(图结构)+ weights/weight.bin(权重二进制),运行时按 model.mil 中的 BLOBFILE(offset=...) 引用权重。

4. 看词表配置。config.json 给出 vocab_size=1024、pad/bos/eos 等 token id,与 vocab.json、tokenizer.json 共同支撑 CTC 解码时的 ID → 文本还原。


🚀 快速上手

环境要求:macOS 13+(Apple Silicon)、Python 3.10+。

# 安装推理依赖(uv 推荐)
uv sync

# 如需自己跑转换,额外安装 convert 依赖(torch + NeMo)
uv sync --extra convert

转换与推理脚本的依赖声明见 pyproject.toml。

推理用法(加载 .mlpackage 目录,TDT 模式出稿、CTC 模式查关键词):

uv run scripts/inference.py --audio audio.wav          # TDT 解码(默认,质量更高)
uv run scripts/inference.py --audio audio.wav --mode ctc   # CTC 解码(更快)
from scripts.inference import ParakeetCoreML

model = ParakeetCoreML(".")          # 当前目录下的 .mlpackage 文件
text = model.transcribe("audio.wav", mode="tdt")

📌 小结

parakeet-ctc-110m-coreml 给出了一个教科书级的 PyTorch 模型转 CoreML 工程范本:

  1. 分组件导出而非整模型硬转——把 NeMo 混合模型拆成 preprocessor / encoder / ctc_head / decoder / joint 等可独立调度的单元,流式场景更灵活;
  2. trace 前做足准备:eval 模式、参考前向、张量 clone、统一 Wrapper 签名;
  3. 形状即契约:固定 15 秒窗口 + RangeDim 例外 + 元数据落盘,让静态图的可控性贯穿始终;
  4. 产物自证:model.mil、metadata.json、weight.bin 三件套让每次转换都可审计、可复现。

如果你想在自己的项目里复用这套流程,建议直接精读 convert/parakeet-tdt-ctc-110m/coreml/ 下的两个文件:convert-parakeet.py(流水线)和 individual_components.py(Wrapper 与转换参数),基本就是 torch.jit.trace + coremltools 的完整实战笔记。

登录后查看全文
parakeet-ctc-110m-coreml