parakeet-ultra-coreml 目录全解读:4 个 Core ML 组件与双词表文件逐一拆解
parakeet-ultra-coreml 目录全解读:4 个 Core ML 组件与双词表文件逐一拆解
parakeet-ultra-coreml 是 NVIDIA Parakeet-TDT-0.6B Ultra 语音识别模型的 Core ML 移植版,专为 Apple Silicon(M 系列 Mac、iPhone/iPad)打造。它把完整的自动语音识别(ASR)流水线拆成 4 个 .mlmodelc 组件模型,配合 2 个词表文件即可在 iOS 17+ / macOS 14+ 上实现 25 种语言的高精度音频转写,LibriSpeech test-clean 词错率低至 2.13%。下面逐一拆解这个目录里的每一个文件。
仓库文件结构一览
整个仓库非常简洁,核心就是「4 个模型目录 + 2 个词表 + 1 份配置」:
| 文件 | 角色 | 量化格式 |
|---|---|---|
| Preprocessor.mlmodelc/ | 音频前端:原始波形 → Mel 频谱 | int8 |
| Encoder.mlmodelc/ | 编码器:把语音编码成上下文特征 | int8 linear per-channel |
| Decoder.mlmodelc/ | RNNT 预测网络(语言侧) | fp16 |
| JointDecisionv3.mlmodelc/ | 联合网络:决定"输出哪个词元" | fp16 |
| parakeet_vocab.json | v3 词表(8192 个词元) | — |
| parakeet_v3_vocab.json | v3 词表(上一行的同版本副本) | — |
| config.json | 组件契约与运行参数说明 | — |
💡 每个
.mlmodelc目录内部结构相同:model.mil(计算图)、weights/weight.bin(权重)、coremldata.bin(常量数据)、analytics/(编译产物分析信息)。其中weight.bin通过 Git LFS 存储,克隆时需要git lfs拉取真实权重。
先懂架构:RNNT 语音识别的 4 步流水线
Parakeet 采用 RNNT(RNN Transducer) 架构,识别一次音频要经过四个核心 ML 组件:
1️⃣ Preprocessor(预处理):把 16kHz 原始音频波形(audio_signal [1, 240000],约 10 秒)转成 Mel 频谱(mel [1, 128, 1501])。
2️⃣ Encoder(编码器):将 15 秒固定窗口的 Mel 频谱编码为 1024 维上下文特征(输出 encoder [1, 1024, 188]),是整条流水线中计算量最大的部分。
3️⃣ Decoder(解码器):RNNT 的"语言侧"预测网络,维度 640,负责根据已生成的文本序列预测下一个词元。
4️⃣ Joint(联合网络):融合 encoder 与 decoder 的输出(decoder_step [1, 640, 1] + encoder_step [1, 1024, 1]),单步决定是"继续听音频"还是"吐出某个词元",并直接输出 top-K 64 候选。
📌 这个组件契约名为
parakeet-tdt-0.6b-v3-coreml(见 config.json),与 v3 版本完全兼容——Ultra 是 v3 架构的"满血精度后训练"版本,可无缝替换。
组件逐一拆解
1. Preprocessor.mlmodelc:音频的"翻译官"
最小的组件,负责 Mel 频谱前端处理,沿用了 v3 的前端实现。输入是 audio_signal(fp32)和 audio_length,输出 mel 与 mel_length。它的 metadata.json 中还记录了模型操作直方图(conv、matmul、log 等算子统计),方便开发者核对编译结果。
2. Encoder.mlmodelc:体积最大、优化最狠的核心
这是整个仓库的重头戏,权重文件约 595 MB,采用 int8 linear per-channel 量化(逐通道 INT8 线性量化)。关键点:
- ✅ 量化后精度无损——README 明确标注其 WER 与 fp16 版本完全一致(2.13% / 3.79%);
- ✅ 速度与 iOS 18 导出的版本相当;
- ⚙️
config.json中建议的算力单元是cpuAndNeuralEngine,让 ANE(Apple 神经网络引擎)深度参与。
3. Decoder.mlmodelc:文本侧的"语言模型"
RNNT 预测网络,fp16 精度,要求 iOS 17+。输入是批处理的上下文状态(c_in 与 h_in,[2, 1, 640])以及目标序列,在解码循环中逐步生成词元。
4. JointDecisionv3.mlmodelc:最终裁决者
同样 fp16、iOS 17+。它把编码器与解码器的单步输出拼接起来,输出 top-K 64 的联合分布,是 RNNT"贪心解码/beam search"每一步的决策核心。文件名中的 v3 表明其接口与 v3 契约对齐。
双词表文件:为什么有两个一模一样的词表?
parakeet_vocab.json 与 parakeet_v3_vocab.json 均为 8192 个词元,经逐字节比对内容完全相同。双份文件是"兼容性设计":
parakeet_vocab.json是 FluidAudio 运行时按默认版本名加载的文件;parakeet_v3_vocab.json保留了 v3 的原始命名,方便从 v3 迁移的代码零改动运行。
词表前几位是特殊控制词元,例如:<unk>、<|nospeech|>(无语音段)、<|startoftranscript|>、<|pnc|>(标点开关)、<|itn|>(逆文本归一化)、<|timestamp|>(时间戳)、<|diarize|>(说话人分离)、<|emo:happy|> 等情绪标记——这也解释了它为何支持 25 种语言 + 多种输出约定。
精度与速度表现
官方在 M 系列 Mac 上用完整语料实测(corpus-level WER):
| 测试集 | v3 (Core ML) | ultra(本仓库) |
|---|---|---|
| LibriSpeech test-clean(2620 条) | 2.27% | 2.13% |
| LibriSpeech test-other(2939 条) | 4.12% | 3.81% |
| FLEURS 24 语言 × 100 条均值 | 14.81% | 11.67% |
Ultra 在全部 24 个 FLEURS 语言上全面胜出;int8 编码器与 fp16 版本精度一致,整体速度与 v3 在同一台机器上背靠背测试仅差几个百分点(ANE 加速比 126.7× vs 128.6×)。
如何使用这套模型
配合 FluidAudio 框架(≥ 下一版本发布)即可加载,README 中给出了 Swift 与 CLI 两种入口:
let models = try await AsrModels.downloadAndLoad(version: .ultra)
let asr = AsrManager()
try await asr.initialize(models: models)
let result = try await asr.transcribe(audioFileURL)
swift run fluidaudiocli transcribe audio.wav --model-version ultra
总结:这个仓库到底解决了什么
- 🚀 苹果生态的原生 ASR:把 0.6B 级 SOTA 语音识别模型完整搬到 Core ML,跑在 ANE/NPU 上;
- 📦 即插即用:组件契约与 v3 对齐,
--model-version ultra一行切换; - ⚖️ 量化不损精度:int8 编码器 WER 与 fp16 完全相同,体积大幅缩小;
- 🌍 25 种语言 + 情绪/说话人/时间戳等输出约定,词表 8192 词元。
如果你想深入转换细节,README 提到上游转换脚本位于 FluidInference/mobius 项目的 models/stt/parakeet-ultra/coreml 路径;模型许可为 CC-BY-4.0,与上游 checkpoint 一致。