torch.jit.trace 实战解析:parakeet-ctc-110m-coreml 如何把 PyTorch 模型编译成 CoreML
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)。
本次导出的三个模型目录就对应其中几个组件:
- MelSpectrogram.mlmodelc/:波形
[240000](15 秒 × 16 kHz)→ Mel 特征[1, 1, 1501, 80] - AudioEncoder.mlmodelc/:编码器 + joint 投影 + CTC 头的融合版本
- CtcHead.mlmodelc/:CTC 头,
[1, 512, 188]→[1, 188, 1025]
📦 转换流水线总览:从 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)。
这一步有两个用途:
- 确定形状:后续定义 CoreML 输入输出 Schema 时,直接引用参考张量的真实 shape;
- 精度校验基准:转换后可以逐组件对比最大绝对/相对误差。
第 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 工程范本:
- 分组件导出而非整模型硬转——把 NeMo 混合模型拆成 preprocessor / encoder / ctc_head / decoder / joint 等可独立调度的单元,流式场景更灵活;
- trace 前做足准备:eval 模式、参考前向、张量 clone、统一 Wrapper 签名;
- 形状即契约:固定 15 秒窗口 +
RangeDim例外 + 元数据落盘,让静态图的可控性贯穿始终; - 产物自证:
model.mil、metadata.json、weight.bin三件套让每次转换都可审计、可复现。
如果你想在自己的项目里复用这套流程,建议直接精读 convert/parakeet-tdt-ctc-110m/coreml/ 下的两个文件:convert-parakeet.py(流水线)和 individual_components.py(Wrapper 与转换参数),基本就是 torch.jit.trace + coremltools 的完整实战笔记。