仓库结构全解析:React Native ExecuTorch Whisper-Tiny的.pte文件、config.json与tokenizer是什么
仓库结构全解析:React Native ExecuTorch Whisper-Tiny的.pte文件、config.json与tokenizer是什么
React Native ExecuTorch Whisper-Tiny 是一个把 OpenAI whisper-tiny 语音识别模型导出为 ExecuTorch .pte 程序的模型仓库,专为 react-native-executorch 库提供可在手机上直接运行的语音转文字(speech-to-text)能力。本文带你逐一读懂仓库里的三类核心文件:.pte 模型文件、各级 config.json 元数据、tokenizer.json 词表,并附上新手挑选模型文件的实用方法。
这个仓库是做什么的?
一句话:它提供离线、端侧运行的 Whisper 语音识别模型"成品"。
- 上游模型是 OpenAI 最小的语音识别模型 whisper-tiny,已被转换为 ExecuTorch 的
.pte可执行程序 - 目标运行环境是 react-native-executorch 库对应的 ExecuTorch v1.4.1 运行时,老版本运行时可能无法加载这些文件
- 许可证为 Apache-2.0,模型按计算后端分目录存放,共 5 套:
coreml、mlx、vulkan、xnnpack、qnn
更多背景可阅读 README.md。
📦 仓库目录结构一览
.
├── config.json # 根元数据:模型名
├── tokenizer.json # 分词器/词表(约 2.4 MB)
├── coreml/ # Apple Core ML 后端
├── mlx/ # Apple MLX 后端
├── vulkan/ # Vulkan GPU 后端
├── xnnpack/ # CPU(XNNPACK)后端
└── qnn/ # 高通 NPU(QNN)后端
各目录的"分工"如下表:
| 目录 | 计算后端 | 典型设备 | 提供的模型变体 |
|---|---|---|---|
coreml/ |
Core ML | iPhone / iPad(Apple 芯片) | fp16 × 1 |
mlx/ |
MLX | Mac(Apple Silicon) | bf16、int8 |
vulkan/ |
Vulkan | 通用 GPU | fp16、int8 |
xnnpack/ |
XNNPACK | 手机 CPU | fp32、int8 |
qnn/ |
QNN | 高通骁龙 NPU | fp16 / int8 × 5 个版本(v69~v81) |
📄 .pte 文件:装进手机的"模型成品"
.pte 是 ExecuTorch 运行时的可移植程序文件,里面封装了网络结构与模型权重,运行时可直接加载执行,无需再训练或转换。
命名规则:whisper_tiny_<后端>_<精度>.pte,例如:
| 文件 | 后端 | 精度 | 大小 |
|---|---|---|---|
| whisper_tiny_coreml_fp16.pte | coreml | fp16 | 72.9 MB |
| whisper_tiny_mlx_bf16.pte | mlx | bf16 | 72.6 MB |
| whisper_tiny_mlx_int8.pte | mlx | int8 | 57.1 MB |
| whisper_tiny_vulkan_fp16.pte | vulkan | fp16 | 204 MB |
| whisper_tiny_vulkan_int8.pte | vulkan | int8 | 124 MB |
| whisper_tiny_xnnpack_fp32.pte | xnnpack | fp32 | 222 MB |
| whisper_tiny_xnnpack_int8.pte | xnnpack | int8 | 175 MB |
💡 精度决定文件大小:fp32(全精度)→ fp16 / bf16(半精度)→ int8(8 位量化)。不同后端在导出时的内存排布与算子融合不同,所以同一模型在不同目录下的体积也有差异。
qnn/目录有 10 个文件(qnn/config.json),v69~v81是面向不同版本高通 NPU 运行时构建的产物,其中标记default: true的 v81 版本是默认选择。
🧩 config.json:一份"模型说明书"
仓库里的 config.json 分两级,作用不同:
1️⃣ 根目录 config.json —— 只有一个字段:
{"modelName": "whisper-tiny"}
用来告诉下载器/模型注册表"这是哪个模型"。
2️⃣ 各后端目录的 config.json —— 例如 coreml/config.json,遵循 react-native-executorch-spec 官方 Schema($schema 字段),常见字段如下:
| 字段 | 含义 |
|---|---|
model / family |
模型名 whisper_tiny,模型家族 whisper |
capabilities |
能力标签,这里是 speech-to-text(语音转文字) |
backend |
当前目录对应的后端(coreml、mlx、vulkan、xnnpack、qnn) |
license |
许可证,均为 apache-2.0 |
tokenizer |
指向根目录 ../tokenizer.json(coreml、mlx 等目录显式声明) |
variants |
模型文件变体列表,见下方详解 |
variants 里的 methods 揭示了 Whisper 的"两步走"工作方式:
- encode(编码器):输入
480000个 float32 数 —— 正好是 30 秒 16kHz 音频的采样数;输出1500 × 384的声学特征(每秒 50 帧) - decode(解码器):输入已有 token、位置信息和 encode 特征,输出维度为
51865的 logits —— 正好对应 tokenizer 的词表大小,即"下一个词可能是词表中的哪一个"
🔤 tokenizer.json:把"数字"翻译回"文字"
tokens 与文字之间的桥梁 —— 这个 2.4 MB 的文件是 HuggingFace 标准格式的分词器:
- 模型推理只输出 token 编号序列,需要 tokenizer 把编号映射回可读文字
- 包含 5 万余个词条,覆盖多语言文本
- 还含 Whisper 特有特殊标记,如
<|en|>、<|zh|>(语言标签,告诉模型转成哪种语言)、<|startoftranscript|>(转写开始)等 - 它与
decode输出的51865维度一一呼应:模型负责"打分",tokenizer 负责"翻译"
✅ 新手选型:3 步挑对 .pte 文件
第 1 步 · 看设备选后端
| 你的设备 | 选哪个目录 |
|---|---|
| iPhone / iPad | coreml/ |
| Mac(Apple Silicon) | mlx/ |
| 安卓 + 骁龙芯片 | 优先 qnn/(NPU 加速),无 NPU 则用 xnnpack/ |
| 通用 GPU 场景 | vulkan/ |
第 2 步 · 看精度选体积:追求小体积与速度选 int8;对精度要求高选 fp16 / fp32。官方对比测试表明 int8 量化后的错误率与 fp32 基本持平,例如英语 WER 仅从 6.99 变为 7.05,中文 CER 从 29.57 变为 28.64(详见 README.md 测试表)。
第 3 步 · qnn 用户看版本:文件名中的 v69~v81 对应不同 NPU 运行时版本,不确定时直接使用默认 v81 版本(见 qnn/config.json)。
小结
.pte:ExecuTorch 可移植模型文件,按"后端 × 精度"提供多套变体,按需下载即可config.json:两级元数据——根目录声明模型名,目录级说明书描述后端、能力与输入输出规格tokenizer.json:模型输出编号到人类语言的"翻译官",与 51865 维输出维度对应
读懂这三类文件,你就能在 react-native-executorch 项目中快速为任意设备接入 Whisper 语音识别能力。