sherpa-onnx Whisper 模型导出与部署指南:PyTorch 转 ONNX、对齐注意力头发现与词级时间戳实战
sherpa-onnx Whisper 模型导出与部署指南:PyTorch 转 ONNX、对齐注意力头发现与词级时间戳实战
导读
本文围绕 sherpa-onnx 仓库中 scripts/whisper 目录的整套工具链展开,讲解如何把 OpenAI Whisper 模型从 PyTorch 导出为 ONNX 格式、如何用 onnxruntime 取代 PyTorch 完成离线语音识别,并进一步导出带交叉注意力权重的模型以实现词级时间戳(word-level timestamps)。读完本文,你将掌握三条核心能力:使用 export-onnx.py 导出标准编码器/解码器模型、使用 find_alignment_heads.py 为自定义模型发现对齐注意力头、使用 export-onnx-with-attention.py 导出带时间戳能力的模型,并通过 sherpa-onnx 的 Python API 完成端到端推理验证。
一、为什么要做 Whisper 的 ONNX 导出
Whisper 官方实现基于 PyTorch,在推理时需要完整的 PyTorch 运行时,对嵌入式设备、移动端、Web 端和服务器端多语言部署场景并不友好。本目录的全部代码围绕一个目标:把 Whisper 转换为 ONNX 模型,用 onnxruntime 替换 PyTorch 做语音识别推理。转换完成后,即可直接交给 sherpa-onnx 运行——sherpa-onnx 的 OfflineRecognizer.from_whisper() 等接口正是为消费这类导出模型而设计的(见 offline_recognizer.py 与 C++ 侧实现 offline-recognizer-whisper-impl.h)。
该目录按部署目标划分了多个子目录:
- rknn/:面向 RK3588 等瑞芯微 NPU 平台的导出与板端测试(含 README.md 和
export_rknn.py); - qnn/:面向高通 QNN 平台的导出与测试;
- ascend-npu/:面向昇腾 NPU 平台的导出与测试;
- tools/:时间戳可视化的 HTML 查看器与 CSV 导出工具。
转换脚本分为两套:基础的 export-onnx.py(与 export_onnx.py 内容一致)负责导出标准模型;带注意力权重的 export-onnx-with-attention.py 负责导出可计算词级时间戳的模型。
二、环境准备与模型加载规则
2.1 依赖
核心依赖记录在 requirements.txt,即 openai-whisper。实际运行导出脚本还需要 torch、onnx、onnxruntime(后两个用于动态量化 quantize_dynamic),运行 test.py 验证还需要 kaldi_native_fbank、numpy、soundfile、librosa(非 16 kHz 音频重采样时用到)。
2.2 模型名称与 checkpoint 加载规则
--model 参数支持的取值由 export-onnx.py 中的 choices 决定,可分为三类:
| 类别 | 模型名 | 加载方式 |
|---|---|---|
| OpenAI 标准模型 | tiny、tiny.en、base、base.en、small、small.en、medium、medium.en、large-v1、large-v2、large、large-v3、turbo |
whisper.load_model(name) 自动下载 |
| distil-whisper 蒸馏模型 | distil-medium.en、distil-small.en、distil-large-v2、distil-large-v3、distil-large-v3.5 |
需预先把 checkpoint 下载到当前目录并命名为固定文件名,如 distil-small-en-original-model.bin、distil-large-v3-original-model.bin |
| icefall 微调模型 | medium-aishell(中文 AISHELL 数据集微调) |
需预先下载 medium-aishell.pt 到当前目录 |
从源码看,load_model()(export-onnx.py)对 distil 系列和微调模型不做自动下载,而是检查当前目录下是否存在约定文件名,缺失时直接抛出带下载指引的 ValueError。这是实际使用时最容易踩的坑,务必先确认 checkpoint 文件已就位。
2.3 音频特征维度的选择
导出脚本在生成 mel 频谱时会根据模型名选择 n_mels(export-onnx.py):
large、large-v3、turbo、distil-large-v3、distil-large-v3.5使用 128 维(这几类模型 feature dim 为 128);- 其余所有模型使用 80 维。
测试音频统一为 16 kHz 采样、2 秒随机噪声经 pad_or_trim 补齐到 30 秒(16000×30),用于固定导出时的输入形状。
三、基础导出:编码器与解码器拆分
3.1 使用命令
python3 export-onnx.py --model tiny
导出过程在 torch.no_grad() 与 disable_sdpa() 上下文内执行(export-onnx.py)。disable_sdpa 用于规避 ONNX 导出时 scaled_dot_product_attention() 的参数类型报错,这是 PyTorch 2.x 与 ONNX 导出链的已知兼容问题。
3.2 编码器导出与 KV Cache 预计算
为了把注意力计算改造成适合 ONNX 静态导出的形式,脚本对 Whisper 结构做了三层包装:
- 编码器:
modified_audio_encoder_forward去掉了原始的 30 秒形状断言,改为允许任意T <= 30s的动态帧数(export-onnx.py); AudioEncoderTensorCache:编码器输出音频特征后,立即遍历解码器每一层,用cross_attn.key/value预计算所有层的交叉注意力 K/V(export-onnx.py)。这是关键优化——解码阶段不再需要反复编码音频;- 编码器 ONNX 的输出为
n_layer_cross_k、n_layer_cross_v,形状为(n_text_layer, n_audio, n_audio_ctx, n_text_state),动态轴包括 batch(n_audio)与音频帧(T)。
3.3 解码器导出与自注意力 KV Cache
解码器被包装为 TextDecoderTensorCache,核心变化是显式维护自注意力 KV Cache(export-onnx.py):
- 输入
in_n_layer_self_k_cache/in_n_layer_self_v_cache形状为(n_text_layer, n_audio, n_text_ctx, n_text_state),初始化为全零; - 每次前向把新 token 的 K/V 写入 cache 的末尾位置,结合
offset定位当前解码位置; - 输出
logits、更新后的out_n_layer_self_k_cache/out_n_layer_self_v_cache; - 位置编码也按
offset动态切片,使模型能够逐步自回归解码。
最终导出产物清单(以 tiny 为例):
tiny-encoder.onnx
tiny-encoder.int8.onnx
tiny-decoder.onnx
tiny-decoder.int8.onnx
tiny-tokens.txt
其中 -tokens.txt 由 convert_tokens 从 Whisper 自带的 tiktoken 词表(multilingual.tiktoken 或 gpt2.tiktoken)转换而来,每行一个 token rank 对,供 sherpa-onnx 加载词表使用。
3.4 大模型的权重外部化
当导出文件名含 large 或 turbo 时,add_meta_data 会以 save_as_external_data=True 方式把权重单独保存为同名的 .weights 外部文件,避免单个 ONNX 文件超过 protobuf 的 2GB 上限。
3.5 编码器元数据(MetaData)
编码器 ONNX 内嵌了大量自定义元数据(export-onnx.py),运行时(sherpa-onnx 及本目录的 test.py)依赖这些字段完成解码初始化:
| 字段 | 含义 |
|---|---|
model_type |
固定为 whisper-{name},如 whisper-tiny |
n_mels / n_audio_ctx / n_audio_state / n_audio_head / n_audio_layer |
音频侧结构维度 |
n_vocab / n_text_ctx / n_text_state / n_text_head / n_text_layer |
文本侧结构维度 |
sot_sequence |
`< |
all_language_tokens / all_language_codes |
语言 token id 与语言代码(如 en,de,zh)映射 |
sot / eot / blank_id / no_speech |
特殊 token id |
transcribe / translate / sot_prev / sot_lm / no_timestamps |
任务相关 token id |
is_multilingual |
是否多语言模型(0/1) |
3.6 int8 动态量化
导出结束后脚本自动调用 onnxruntime.quantization.quantize_dynamic 生成 int8 版本(export-onnx.py):对 MatMul 算子做动态量化、权重类型为 QuantType.QInt8。int8 模型体积显著减小,适合资源受限的嵌入式与移动端部署。
四、词级时间戳:导出带交叉注意力权重的模型
4.1 为什么需要对齐注意力头
export-onnx-with-attention.py 导出的解码器多出一个输出 cross_attention_weights,形状为 (n_alignment_heads, n_audio_ctx)(batch 与 token 维度为动态轴)。这些权重记录了每个 token 解码时对音频帧的注意力分布,配合动态时间规整(DTW)即可计算词级时间戳。
但并非所有注意力头都适合做对齐——只有那些呈现单调递增注意力模式的头(即随着 token 逐个解码,注意力峰值在音频帧上不断前移)才是有用的 "alignment heads"。因此导出前必须明确告诉脚本用哪些头。
4.2 ALIGNMENT_HEADS 表与元数据回退
脚本顶部的 ALIGNMENT_HEADS 字典(export-onnx-with-attention.py)分为两类策略:
- OpenAI 官方模型(
tiny到turbo):值为哨兵常量USE_MODEL_METADATA = True,表示直接读取模型自带的alignment_heads稀疏张量元数据(官方 Whisper checkpoint 内已内置对齐头信息),由extract_alignment_heads_from_model()通过indices()解析出(layer, head)列表; - distil-whisper 蒸馏模型:由于这类模型元数据中头信息不完整,脚本内置了经验测定的对齐头,例如:
distil-small.en→[(3, 2)](4 层解码器,head 对角线得分 0.985)distil-medium.en→[(1, 11)](对角线得分 0.804)distil-large-v2→[(1, 12)](对角线得分 0.806)distil-large-v3/distil-large-v3.5→[(1, 3)]
这些经验值正是通过下文介绍的 find_alignment_heads.py 发现的,两者形成闭环。
4.3 注意力计算的手工重写
为了兼容 ONNX,脚本用手工矩阵运算替换了 SDPA(scaled dot-product attention):MultiHeadAttentionCrossWithWeights 先 reshape 出多头、按 head_dim ** -0.25 缩放计算 QK^T,softmax 得到权重矩阵 w,再只抽取本层中对齐头对应的行作为输出(export-onnx-with-attention.py)。解码器最后把各层的对齐头权重沿 head 维拼接,得到总输出 cross_attention_weights。
4.4 使用命令与产物差异
python3 export-onnx-with-attention.py --model tiny
与基础导出相比,差异点如下:
--model的choices仅限ALIGNMENT_HEADS中已定义(含元数据回退)的模型;- 编码器元数据中
version为"2"(表示 attention-enabled),并新增n_alignment_heads与alignment_heads("layer:head"逗号拼接)两个字段; - 解码器输出由 3 个变为 4 个:
logits、out_n_layer_self_k_cache、out_n_layer_self_v_cache、cross_attention_weights; cross_attention_weights的动态轴覆盖 batch、token 数与音频帧T,导出时通过断言确保形状为(n_audio, n_alignment_heads, n_tokens, n_audio_ctx)。
五、为自定义模型发现对齐注意力头
对于新的或自定义模型(尤其是 distil-whisper 变体),如果不知道对齐头在哪,使用 find_alignment_heads.py 即可自动分析发现:
python find_alignment_heads.py --model <model-name> --audio <test-audio.wav>
可选参数 --top-k(默认 10)控制输出候选头数量。该脚本复用 export_onnx.load_model() 加载模型,因此同样受上一节 checkpoint 预下载规则约束。
5.1 工作原理
脚本的核心逻辑分为两步(详见 find_alignment_heads.py):
- 逐 token 捕获交叉注意力:手工遍历解码器每一层,计算
QK^T并 softmax,记录每个(layer, head)在每次解码时最后一个 token 对全部音频帧的注意力向量,累积成[n_tokens, n_audio_frames]的注意力矩阵; - 按两个指标排序所有头:
- Monotonicity(单调性):统计各 token 注意力峰值(argmax)位置随 token 序列单调不减的比例,得分 0~1,越接近 1 说明峰值越严格前移(compute_monotonicity_score);
- Diagonal(对角性):把"每个 token 应对齐到第
i * n_frames / n_tokens个音频帧"视为理想对角线,计算实际峰值位置与理想位置的相关系数(仅保留正值),衡量注意力是否贴合期望的对角模式(compute_diagonal_score); - Combined(综合分):
(monotonicity + diagonal) / 2,作为最终排序依据。
5.2 输出解读
示例输出(与仓库 README 一致):
Top 15 alignment head candidates:
------------------------------------------------------------
Layer Head Monotonic Diagonal Combined
------------------------------------------------------------
3 2 0.846 0.985 0.915
0 0 0.962 0.617 0.789
...
判断建议:
- 综合分 > 0.7 的头是优质候选;
- 如果某个头的对角分单独超过 0.9,通常单头就足以支撑准确的时间戳计算;
- 脚本还会自动生成一段可直接粘贴进
export-onnx-with-attention.py中ALIGNMENT_HEADS表的 Python 代码(默认取综合分 > 0.7 的头,不足 6 个时取前 6 个),方便把发现结果固化下来。
5.3 验证实验:单头对齐的实际效果
仓库 README 中给出的内置经验值(如 distil-small.en 的 (3, 2) 头对角分 0.985)正是这一流程的产物,说明"单个高分对齐头 + DTW"即可在蒸馏模型上获得可用的词级时间戳,这也是官方 OpenAI 模型采用多对齐头、蒸馏模型通常只需 1~2 个头的原因。
六、导出后的推理验证与时间戳输出
6.1 用 test.py 验证 ONNX 模型
test.py 是完整的 onnxruntime 推理验证脚本,要求先运行导出脚本。典型用法:
python3 test.py --encoder tiny-encoder.onnx \
--decoder tiny-decoder.onnx \
--tokens tiny-tokens.txt \
--language en \
--task transcribe \
--test-attention \
en.wav
关键参数:
| 参数 | 说明 |
|---|---|
--encoder / --decoder / --tokens |
导出产物路径 |
--language |
实际口音语言(en/de/zh/jp/fr 等);不传时用前 30 秒自动检测语言 |
--task |
transcribe(转写)或 translate(翻译成英文) |
--test-attention |
验证交叉注意力输出;要求解码器有 4 个输出,即必须用 export-onnx-with-attention.py 导出的模型,否则直接报错 |
该脚本值得注意的工程细节:
- 特征计算完全走 kaldi_native_fbank:
compute_features用knf.OnlineWhisperFbank计算 log-mel 特征,并把尾部零填充 1500 帧(而非 30 秒全填充),保证能触发<|eot|>检测的同时不浪费算力——这正是"去掉 30 秒约束"改造在运行时的体现(test.py); - token 抑制:
suppress_tokens在初始步抑制<|eot|>、blank、<|notimestamps|>等 token,后续步持续抑制<|sot|>、<|nospeech|>与<|translate|>,与 OpenAI 官方解码策略对齐; - 时间戳验证:
verify_attention对每个 token 求对齐头权重的平均峰值帧,乘以 0.02 秒(50 帧/秒)换算成近似时间戳并打印。
6.2 用 sherpa-onnx 生成 token 时间戳 CSV
真正面向产品化的是 sherpa-onnx 的 Python 绑定。仓库提供了 whisper_timestamps_csv.py 示例,通过 OfflineRecognizer.from_whisper() 直接消费导出的模型:
python3 whisper_timestamps_csv.py \
--encoder tiny-encoder.onnx \
--decoder tiny-decoder.onnx \
--tokens tiny-tokens.txt \
--audio en.wav \
--output timestamps.csv \
--enable-segment-timestamps
配置要点(与 C++ 侧 OfflineWhisperModelConfig 对应):
language:默认en,多语言模型可指定其他语言代码;task:固定transcribe;enable_token_timestamps=True:开启 token 级时间戳,返回result.tokens、result.timestamps、result.durations;enable_segment_timestamps:可选开启分段级时间戳;num_threads:onnxruntime 线程数,默认 4。
脚本要求输入为单声道 16-bit WAV,输出 CSV 每行 token, timestamp, duration。另可配合 tools/timestamp_viewer.html 对时间戳结果做可视化检查。
6.3 其他平台验证路径
- RK3588 板端:先
export_onnx.py导出 ONNX,再用 rknn/export_rknn.py 转成 RKNN(--target-platform rk3588),最后用 rknn/test_on_rk3588_board.py 在板子上跑推理;参考 rknn/README.md; - QNN / 昇腾 NPU:分别使用 qnn/export_onnx.py 与 ascend-npu/export_onnx.py 完成平台适配。
七、模型结构维度速查
model-info.md 汇总了各尺寸模型的 ModelDimensions,导出前可据此核对元数据与运行时配置:
| 模型 | n_mels | n_audio_ctx | n_audio_state | n_audio_head | n_audio_layer | n_text_ctx | n_text_state | n_text_head | n_text_layer |
|---|---|---|---|---|---|---|---|---|---|
| tiny / tiny.en | 80 | 1500 | 384 | 6 | 4 | 448 | 384 | 6 | 4 |
| base / base.en | 80 | 1500 | 512 | 8 | 6 | 448 | 512 | 8 | 6 |
| small / small.en | 80 | 1500 | 768 | 12 | 12 | 448 | 768 | 12 | 12 |
| medium / medium.en | 80 | 1500 | 1024 | 16 | 24 | 448 | 1024 | 16 | 24 |
| large 系列 | 128 | 1500 | 1280 | 20 | 32 | 448 | 1280 | 20 | 32 |
其中 n_vocab 统一为 51865。注意 large、large-v3、turbo 及 distil-large 系列的 n_mels 为 128,与表中其余模型不同,这也是导出脚本按模型名分支选择特征维度的原因。
八、总结与最佳实践
综合仓库文档与源码,一条完整的 Whisper ONNX 落地路径为:
- 标准 OpenAI 模型直接用
export-onnx.py --model tiny导出;distil 系列先下载 checkpoint 到当前目录再导出; - 需要词级时间戳时,先运行
find_alignment_heads.py确认对齐头(官方模型会自动回退到模型元数据),再用export-onnx-with-attention.py导出 4 输出的解码器; - 用
test.py --test-attention在 onnxruntime 侧验证识别与时间戳正确性; - 接入 sherpa-onnx,通过
OfflineRecognizer.from_whisper()以enable_token_timestamps=True落地生产,或按需走 rknn/qnn/ascend-npu 平台适配。
建议优先选用 int8 量化版本(*.int8.onnx)做部署,并始终保留 *-tokens.txt 与编码器内嵌元数据——sherpa-onnx 运行时的语言检测、特殊 token 抑制与解码起始序列均依赖它们,任何一项缺失都会导致推理失败。