sherpa-onnx Whisper 模型导出与部署指南:PyTorch 转 ONNX、对齐注意力头发现与词级时间戳实战

原创2026-09-14 11:01:331,404 阅读
文章标签:语音音频人工智能NLP

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):

  1. 逐 token 捕获交叉注意力:手工遍历解码器每一层,计算 QK^T 并 softmax,记录每个 (layer, head) 在每次解码时最后一个 token 对全部音频帧的注意力向量,累积成 [n_tokens, n_audio_frames] 的注意力矩阵;
  2. 按两个指标排序所有头:
    • 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 其他平台验证路径

七、模型结构维度速查

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 落地路径为:

  1. 标准 OpenAI 模型直接用 export-onnx.py --model tiny 导出;distil 系列先下载 checkpoint 到当前目录再导出;
  2. 需要词级时间戳时,先运行 find_alignment_heads.py 确认对齐头(官方模型会自动回退到模型元数据),再用 export-onnx-with-attention.py 导出 4 输出的解码器;
  3. 用 test.py --test-attention 在 onnxruntime 侧验证识别与时间戳正确性;
  4. 接入 sherpa-onnx,通过 OfflineRecognizer.from_whisper() 以 enable_token_timestamps=True 落地生产,或按需走 rknn/qnn/ascend-npu 平台适配。

建议优先选用 int8 量化版本(*.int8.onnx)做部署,并始终保留 *-tokens.txt 与编码器内嵌元数据——sherpa-onnx 运行时的语言检测、特殊 token 抑制与解码起始序列均依赖它们,任何一项缺失都会导致推理失败。

登录后查看全文
sherpa-onnx