从NeMo到CoreML:parakeet-ctc-110m-coreml模型转换全流程开发者指南
从NeMo到CoreML:parakeet-ctc-110m-coreml模型转换全流程开发者指南
parakeet-ctc-110m-coreml 是把 NVIDIA 的 Parakeet-TDT-CTC-110M 语音识别(ASR)模型从 NeMo 格式完整转换为 CoreML 格式的开源项目,让苹果 M 系列芯片设备可以直接跑本地语音识别。本文用最短的路径带你走通「NeMo → CoreML 模型转换」全流程:环境准备、转换步骤、关键参数、产物解读,以及 TDT / CTC 两种解码模式怎么选。
一、项目速览:它到底做了什么?
一句话概括:把 PyTorch/NeMo 训练出来的语音模型,拆成可被 Apple 芯片高效执行的 CoreML 子模块。
| 项目 | 说明 |
|---|---|
| 源模型 | NVIDIA Parakeet-TDT-CTC-110M(混合 ASR 模型,约 1.1 亿参数) |
| 目标格式 | CoreML(.mlpackage / .mlmodelc) |
| 运行平台 | macOS 13+,Apple Silicon(M1/M2/M3/M4) |
| 核心能力 | 本地离线语音转文字 + 关键词检测 |
| 实测性能 | M4 Pro 上达 358 倍实时(RTFx) |
💡 混合模型(Hybrid)的妙处在于:它共享同一个 Conformer 编码器,却挂着两个"头"——CTC 头负责快(贪心解码,适合关键词检测),TDT 头负责准(转录质量更高)。
二、模型架构:五个组件各管一段
理解转换流程前,先知道模型被拆成了哪几块(数据流从左到右):
| 组件 | 职责 | 输出 |
|---|---|---|
| Preprocessor | 音频波形 → Mel 频谱 | melspectrogram_features(80 维特征) |
| Encoder | Conformer 编码器(核心,~400MB) | 512 维时序特征 |
| CTC Head | 编码器特征 → 词表 logits | 1025 类 log 概率(1024 词 + blank) |
| Decoder | TDT 预测网络(LSTM) | 640 维上下文特征 |
| Joint Decision | TDT 联合网络 + 决策头 | token_id、token_prob、duration |
各组件的输入输出维度都记录在仓库中,例如 ctc_head_metadata.json 就写明了 CTC 头:输入 [1, 512, 188](15 秒音频 → 188 帧),输出 [1, 188, 1025]。
三、一键安装步骤(3 分钟上手)
环境要求:macOS 13+(Ventura 或更高)、Apple Silicon、Python 3.10+。
# 1. 获取仓库
git clone https://gitcode.com/hf_mirrors/FluidInference/parakeet-ctc-110m-coreml
# 2. 同步依赖(推荐 uv)
uv sync
# 3. 命令行直接转录(默认 TDT 模式,质量更高)
uv run scripts/inference.py --audio audio.wav
# 4. 或切到 CTC 模式(更快,适合关键词检测)
uv run scripts/inference.py --audio audio.wav --mode ctc
依赖声明见 pyproject.toml:运行只需要 coremltools、numpy、scipy;需要处理 MP3 等非 WAV 音频时,额外安装 .[audio](librosa)。
四、核心流程:NeMo → CoreML 转换四步走
整个转换脚本是 convert-parakeet.py,子模块封装在 individual_components.py。流程分为四步:
步骤 1:加载 NeMo 原始模型
脚本支持两种方式拿到原始权重:
# 安装转换依赖
uv sync --extra convert
# 自动下载 nvidia/parakeet-tdt_ctc-110m 并转换
uv run convert/parakeet-tdt-ctc-110m/coreml/convert-parakeet.py --output-dir ./model
# 或指定本地 .nemo 检查点文件
# --nemo-path /path/to/parakeet.nemo
模型以 EncDecHybridRNNTCTCBPEModel 类型恢复(见 convert-parakeet.py),随后从模型中提取采样率、词表大小(1024)、解码器隐层维度等元信息。
步骤 2:为每个子模块套上"Wrapper"
这是整个转换里最关键的设计:NeMo 的原始接口和 CoreML 转换器期望的输入/输出格式并不一致,所以项目为每个组件写了一层薄薄的包装(PreprocessorWrapper、EncoderWrapper、CTCHeadWrapper、JointWrapper 等,见 individual_components.py),作用包括:
- 统一张量格式:比如 Joint 网络内部要
[B, T, D],而外部约定是[B, D, T],Wrapper 里用transpose显式转换; - 拆开复合输出:如 Decoder 的隐状态
(h, c)被拆成独立输出张量; - 消除转换歧义:Joint 网络里的广播加法写成显式
unsqueeze,避免 coremltools 推断失败。
还有一个隐藏技巧:MelEncoderWrapper 把「Mel 频谱 + 编码器」融合成一个模型,省掉中间传张量的开销;JointDecisionSingleStep 则只处理单帧,专为流式/逐帧解码设计,还会额外输出 top-64 候选 token,方便宿主机侧做上下文偏置重排序。
步骤 3:TorchScript 追踪 + coremltools 转换
对每个封装好的模块执行 torch.jit.trace,再交给 ct.convert 导出(核心逻辑在 individual_components.py):
traced = torch.jit.trace(module, (sample_input,), strict=False)
model = ct.convert(traced, convert_to="mlprogram", inputs=..., outputs=...)
其中输入张量用真实音频跑一遍推理得到(仓库会优先使用自带的 15 秒 16kHz 测试音频做"追踪样本"),并声明了输入输出名称与类型,例如 preprocessor 的 audio 输入允许 1~240000 个采样点(RangeDim 可变长)。
步骤 4:生成配套元数据
转换完成后自动导出三份"说明书":
- vocab.json:1024 个 token 的完整词表(BPE 子词,如
▁the、ing),解码时用来把 token_id 还原成文字,对应仓库中的 vocab.json; - metadata.json:记录每个组件的文件名、输入输出形状、计算精度等;
- model.mlmodelc 结构:每个
.mlmodelc编译目录含model.mil(计算图)、weights/weight.bin(权重)和metadata.json(模式定义)。
五、关键转换参数一览表
以下固定设置决定了产物能在 iOS 17 / macOS 14 上运行并适配 ANE(神经引擎):
| 参数 | 取值 | 作用 |
|---|---|---|
convert_to |
mlprogram |
新版图格式,支持 iOS 17 算子与 ANE |
minimum_deployment_target |
iOS 17 | 启用新内核,保证设备兼容性 |
compute_units |
CPU_ONLY(默认) |
可按组件切换 ALL / CPU_AND_GPU / CPU_AND_NE |
compute_precision |
FLOAT32(默认)/ FLOAT16 |
FLOAT16 可让非量化权重大小减半 |
max_audio_seconds |
15.0 | 固定 15 秒音频窗口,240000 采样点 |
max_symbol_steps |
1 | 单步解码,匹配流式解码器 |
这些参数集中在 ExportSettings 中配置(见 convert-parakeet.py),CLI 还开放了 --preprocessor-cu、--mel-encoder-cu、--compute-precision 等选项,方便针对具体硬件调优。
六、转换产物:仓库目录结构解读
转换完成后,仓库长这样(每个 .mlmodelc 都是可直接 MLModel(contentsOf:) 加载的编译产物):
| 路径 | 内容 |
|---|---|
| AudioEncoder.mlmodelc/ | Conformer 编码器(权重已量化,存储精度 Mixed Float16/6-bit 调色板/稀疏) |
| MelSpectrogram.mlmodelc/ | Mel 频谱提取(波形 → 1501 帧 × 80 维) |
| CtcHead.mlmodelc/ / CtcHead.mlpackage/ | CTC 头,同一模型的编译版与源码版 |
| tokenizer.json、vocab.json | 分词器与词表(BPE,1024 tokens) |
| config.json | 词表大小、特殊 token ID 等配置 |
| ctc_head_metadata.json | CTC 头输入输出规格 |
| convert/ | NeMo → CoreML 转换脚本(本文主角) |
📌
.mlpackage是"包"格式(Manifest.json+ 规格 + 权重),适合分发和二次编辑;.mlmodelc是xcrun coreml-compile后的"编译产物",运行时零编译开销——仓库同时保留两种形态,开发调试用前者,上架部署用后者。
以 CtcHead.mlmodelc/metadata.json 为例,可以直接读出输入 encoder_output [1, 512, 188]、输出 ctc_logits [1, 188, 1025],以及它由 conv、softmax、log 等算子构成——这就是 CoreML 模型的"身份证"。
七、TDT 还是 CTC?解码模式选择指南
两种模式共用编码器,按需选择:
| 维度 | TDT 模式(推荐用于转录) | CTC 模式(推荐用于关键词检测) |
|---|---|---|
| 原理 | Token-Duration Transducer,联合网络逐步决策 | 贪心解码,逐帧取最大概率 |
| 质量 | 更高(Earnings22 上 WER 17.97%) | 略低 |
| 速度 | 稍慢 | 更快 |
| 典型场景 | 完整转写、会议记录 | 热词/关键词召回(实测 100%) |
关键词检测玩法:把自定义热词预先转成 token_id 序列,CTC 解码后做子序列匹配即可命中,无需重新训练模型。
八、性能与参考基准
- 推理速度:M4 Pro 上 RTFx ≈ 358×(每秒可处理约 59 分钟音频)
- 关键词召回:Earnings22(772 条音频)1309/1309,100%
- 词表规模:1024 BPE token,CTC 类别数 1025(含 blank)
- 模型体积:全套组件合计约 436MB,其中编码器占大头
⚠️ 15 秒窗口限制:当前导出固定 15 秒音频窗口(188 帧),长音频需在应用层做分片滚动处理。
九、常见问题(FAQ)
Q1:转换必须在 macOS 上跑吗?
coremltools 的 ct.convert 是纯 Python 实现,Linux 也能导出 .mlpackage,但 ANE 编译(.mlmodelc)和真机验证建议留在 Mac 上。
Q2:如何验证转换结果正确?
项目内置校验机制:用同一段真实音频分别跑 NeMo 原模型和 CoreML 模型,对比 token 序列与张量最大绝对/相对误差(ValidationSettings,见 individual_components.py),误差在容差内即通过。
Q3:能改词表做定制热词吗? CTC 模式支持"解码侧偏置":不改动模型权重,只在解码阶段对指定 token 加权或做子序列匹配,就能显著提升特定关键词的召回率。
Q4:和 0.6B 版本有什么区别?
110M 的编码器维度是 512(0.6B 为 1024),单帧 Joint 决策输入为 [1,512,1] × [1,640,1],整体更轻、更适合端侧部署。
总结
parakeet-ctc-110m-coreml 演示了一套非常标准的 NeMo → CoreML 转换范式:加载原始模型 → Wrapper 统一接口 → jit.trace 追踪 → ct.convert 导出 → 词表与元数据落盘。跟着 README.md 与 convert/ 目录下的脚本,你可以复现整个流程,甚至把同一套方法迁移到其他 NeMo ASR 模型上。对想在 Apple Silicon 上做本地语音识别、离线关键词检测的开发者来说,这是一个可以直接抄作业的完整模板。 🎯