whisper-small.en 模型文件全景解析:31 个 encoder 与 decoder ONNX 文件各是干什么的?
whisper-small.en 模型文件全景解析:31 个 encoder 与 decoder ONNX 文件各是干什么的?
whisper-small.en 是面向 Transformers.js 的 Whisper 英文语音识别模型(ASR)的 ONNX 权重仓库,由 Xenova 基于 openai/whisper-small.en 转换而来。打开 onnx/ 目录你会看到 31 个 .onnx 文件:7 个 encoder、24 个 decoder,每个文件对应一种"模型结构 × 量化方式"的组合。本文帮你一次性搞清楚这 31 个 whisper-small.en ONNX 模型文件各是干什么的、文件为什么这么大、以及该选哪一个。
仓库目录结构一览 📁
整个仓库只有两类文件:onnx/ 子目录里的模型权重,以及根目录的模型配置与分词器文件。
whisper-small.en/
├── onnx/ # 31 个 ONNX 模型文件(300+ MB 量级)
├── config.json # 模型结构:层数、维度、词表等
├── generation_config.json # 生成参数:最大长度、强制 token 等
├── preprocessor_config.json # 音频前处理:16kHz、80 维 Mel、30 秒分块
├── quantize_config.json # 量化配置(QInt8 / QUInt8)
├── tokenizer.json / vocab.json / merges.txt # BPE 分词器
└── README.md # 使用说明
几个关键超参可以直接从 config.json 看到:d_model 为 768、encoder 和 decoder 各 12 层、词表 51864 个 token;generation_config.json 中 is_multilingual: false,说明这是仅支持英文的 .en 版本。
Whisper 模型原理:encoder 与 decoder 如何分工?
Whisper 是一个典型的 encoder-decoder 架构语音识别模型,可以把转写过程想象成"听 + 说"两个阶段:
- encoder(编码器):把 30 秒一段的音频(16kHz 采样,见 preprocessor_config.json)转换为 80 维的 Mel 频谱特征,再编码成一段"语义表示"。这一步每个音频片段只算一次。
- decoder(解码器):像写文章一样,逐个 token 地"读出"英文文本,直到输出结束符
</think> </output>。
这也解释了为什么仓库里有 encoder 和 decoder 两组文件——它们是流水线上前后两个独立的神经网络,各自需要单独加载推理。
31 个 ONNX 文件全景清单
31 个文件可以拆成 4 个系列,命名规律是:模型结构名 + 量化后缀。
① encoder_model 系列(7 个文件)
负责"听懂音频",输入 Mel 频谱,输出 1500 帧(对应 30 秒音频)的编码表示:
| 文件 | 精度 | 体积 | 说明 |
|---|---|---|---|
| encoder_model.onnx | FP32 | ≈336 MB | 原始精度,质量最好 |
| encoder_model_fp16.onnx | FP16 | ≈168 MB | 半精度,体积减半 |
| encoder_model_quantized.onnx | Int8 | ≈88 MB | 动态量化(见下文) |
| encoder_model_uint8.onnx | UInt8 | ≈88 MB | 无符号 Int8 权重 |
| encoder_model_q4.onnx | 4-bit | ≈63 MB | 4 位量化 |
| encoder_model_q4f16.onnx | 4-bit+FP16 | ≈52 MB | 最省内存的 encoder |
| encoder_model_bnb4.onnx | 4-bit(nf4) | ≈58 MB | bitsandbytes 风格 4 位 |
⚠️ 注意:encoder 系列没有
_int8文件,它的 Int8 版本就叫quantized/uint8,而 decoder 三者都有。
② decoder_model 系列(8 个文件)
负责"读出文本",处理前几个 token(开始符 </think>、语言标识 <|en|>、转写指令等)。体积最大的一类:
| 文件 | 精度 | 体积 |
|---|---|---|
| decoder_model.onnx | FP32 | ≈586 MB |
| decoder_model_fp16.onnx | FP16 | ≈293 MB |
| decoder_model_int8.onnx | Int8 | ≈300 MB |
| decoder_model_uint8.onnx | UInt8 | ≈300 MB |
| decoder_model_quantized.onnx | Int8 | ≈149 MB |
| decoder_model_q4f16.onnx | 4-bit+FP16 | ≈138 MB |
| decoder_model_q4.onnx | 4-bit | ≈222 MB |
| decoder_model_bnb4.onnx | 4-bit(nf4) | ≈215 MB |
③ decoder_model_merged 系列(8 个文件)
merged = "把 decoder_model 和 decoder_with_past_model 合并成一个文件"。这样运行时无需在两个模型之间切换,加载逻辑更简单,是 Transformers.js 目前推荐的部署形态。8 个量化档位与 decoder_model 系列一一对应(FP32 约 587 MB,_q4f16 最小仅 ≈139 MB)。
④ decoder_with_past_model 系列(8 个文件)
with past = 带 KV cache 的解码器,用于"逐 token 自回归"阶段。生成第 N 个词时,它接收之前所有词的注意力缓存(past key values),只计算新 token,避免每步都重算历史。8 个量化档位同样齐全,_q4f16 版本 ≈130 MB,是全部 31 个文件中最小的。
推理流程(非 merged 模式):
音频 → encoder → 语义表示
↘
decoder_model(处理起始 token)→ decoder_with_past_model(逐词生成,带缓存)→ 文本
量化后缀速查表:fp16、int8、q4、bnb4 都是什么?
同样的模型,为什么会有 8 个版本?答案是量化(Quantization)——用更少的比特数存储权重,换取更小的体积和更快的推理,代价是轻微的精度损失。
| 后缀 | 量化方式 | 权重精度 | 典型体积比 |
|---|---|---|---|
| (无后缀) | 未量化 | FP32(32 位浮点) | 100% |
_fp16 |
半精度 | FP16(16 位浮点) | ≈50% |
_int8 / _uint8 |
动态量化 | 8 位整型 | ≈50% |
_quantized |
动态量化 | QInt8/QUInt8 | ≈25%(decoder) |
_q4 |
4 位量化 | 4 位整型 | ≈40% |
_q4f16 |
4 位量化 + FP16 计算 | 4 位整型 | ≈25% |
_bnb4 |
bitsandbytes nf4 | 4 位整型 | ≈40% |
具体量化策略(哪些算子量化、用什么权重类型)记录在 quantize_config.json 中:decoder 类模型用 QInt8,encoder 用 QUInt8,且均为逐张量(per_channel: false)量化。
关键配置文件速读 🔧
| 文件 | 作用 |
|---|---|
| config.json | 模型架构:WhisperForConditionalGeneration、12+12 层、max_length: 448 |
| generation_config.json | 生成控制:is_multilingual: false(仅英文)、时间戳头对齐表 |
| preprocessor_config.json | 音频前端:sampling_rate: 16000、chunk_length: 30(秒)、80 维 Mel |
| tokenizer.json / vocab.json / merges.txt | BPE 分词器,含 `< |
| quantize_config.json / quant_config.json | 两套量化配置,定义各 ONNX 子图的量化算子与权重类型 |
如何选择最适合你的 ONNX 模型文件?
不用纠结,按运行环境对号入座即可:
- 浏览器 / 内存受限环境(推荐):选
_q4f16或_quantized系列(encoder ≈52–88 MB,decoder ≈130–149 MB),总下载量最低,精度损失在语音识别场景通常可接受。 - 追求最高精度、设备性能足够:选无后缀的 FP32 原始文件,或
_fp16作为折中。 - 使用 Transformers.js 加载:通常走 merged 系列,例如 decoder_model_merged_q4f16.onnx,一次加载完成全部解码,避免双模型切换。
- 注意语言限制:
.en版本只识别英文,非英文音频请选用对应的 multilingual 权重仓库。
⚡ 小贴士:onnx/ 目录文件通过 Git LFS 管理,克隆时会自动拉取大文件;如果只关心某几个量化版本,可以只下载对应的 LFS 对象以节省带宽。
常见问题 FAQ ❓
Q:encoder 和 decoder 文件一定要配套相同精度吗? A:技术上可以混用(例如 FP32 encoder + Int8 decoder),但为了精度一致和推理图匹配,建议同一系列、同一量化档位配对。
Q:merged 文件和普通的 decoder_model + decoder_with_past_model 区别在哪? A:merged 把两阶段的计算图融合进单个 ONNX 文件,运行时无需切换模型实例,是更现代、更省事的部署方式;后两者是拆分形态,供需要精细控制流程的框架使用。
Q:为什么 encoder 系列没有 _int8 文件?
A:encoder 的 8 位量化版本以 quantized(QInt8 方案)和 uint8(QUInt8 方案)两个名字提供,量化策略可参考 quantize_config.json 中 encoder_model 的 weight_type: QUInt8 配置。
Q:文件里的 50257、50256 这些数字是什么?
A:是特殊 token 的 id,比如 </think>(50257)、</think>(50256)、<|en|>(50258),完整映射见 special_tokens_map.json。
总结
- whisper-small.en 仓库 = 7 个 encoder + 24 个 decoder 的 ONNX 文件,本质是"3 种 decoder 结构(普通 / merged / with-past)× 8 种精度档位"的组合矩阵;
- 精度档位从 FP32 一路量化到 4-bit,体积可从 500+ MB 压到 130 MB 左右;
- 浏览器部署优先选
_q4f16或_quantized,本地高性能设备选 FP32/FP16; - 该模型仅支持英文语音识别,30 秒音频分块、16kHz 输入。
理解了这套命名规则,你再看其他 Transformers.js 模型的 ONNX 仓库时,也能一眼看懂每个文件的用途了。