sherpa-onnx 推理底座

sherpa-onnx 是什么

sherpa-onnx 是 Next-gen Kaldi 团队基于 ONNX Runtime 的开源语音工具库：

• 流式 / 离线 ASR（Zipformer、Paraformer、Whisper、SenseVoice…）
• TTS（VITS、Matcha、Kokoro…）
• VAD（Silero）
• 声纹、关键词检测、说话人分割
• C++ / Python / Go / Swift / Kotlin / JS / WASM 等多语言绑定
• 纯 ONNX，CPU 即可跑，对边缘部署友好

在本项目里，sherpa-onnx 是 ASR 服务和 TTS 服务的推理底座——业务侧并不直接调它，但所有识别 / 合成的”算力”都由它提供。

在仓库中的位置

1
2
3
4
5
6
7
8
9
10
11

ai-voice-platform/
└── onnx-platform/
    ├── sherpa-onnx/            # 预编译产物（Windows/Linux）
    │   └── win_x64/
    │       ├── bin/            # sherpa-onnx-version.exe 等可执行
    │       ├── include/        # 头文件
    │       └── lib/            # 静态/动态库
    └── sherpa-demo/            # 5 个最小验证程序
        ├── src/                # demo 源码
        ├── CMakeLists.txt
        └── build.ps1           # 一键构建脚本

ASR 服务（onnx-platform/sherpa-asr-online-server/）和 TTS 服务
（onnx-platform/sherpa-tts-server/）都通过 CMake 链接到
onnx-platform/sherpa-onnx/ 下的头文件与库。

内置模型清单

1
2
3
4
5
6
7
8
9
10

ai-voice-platform/onnx-platform/models/
├── sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30/  # 默认流式 ASR（中文 int8）
├── sherpa-onnx-streaming-zipformer-bilingual-zh-en/     # 可选流式 ASR（中英双语，旧版预设）
├── sherpa-onnx-sense-voice/                             # 离线 ASR（多语种）
├── kokoro-multi-lang-v1_1/                              # 默认 TTS（中英双语多音色，103 说话人）
├── matcha-icefall-zh-en/                                # 可选 TTS（中英双语 Matcha）
├── vits-zh-aishell3/                                    # 可选 TTS（中文，多说话人）
├── emotion-text/                                        # 情绪分析：文本 BERT
├── emotion-audio/                                       # 情绪分析：音频 wav2vec2
└── silero_vad.onnx                                      # VAD

测试音频也在 models/ 下：sherpa-onnx-sense-voice/test_wavs/。

sherpa-demo —— 5 个最小验证程序

sherpa-demo/ 是仓库内 sherpa-onnx + 预置 models 的最小可运行验证集合。任一组件出问题时，先用 demo 复现来定位”是模型挂了”还是”服务封装挂了”。

构建

1
2

cd onnx-platform\sherpa-demo
.\build.ps1

等价于：

1
2
3

cmake -S . -B build/win_x64 -G "Visual Studio 17 2022" -A x64
cmake --build build/win_x64 --config Release
cmake --install build/win_x64 --config Release --prefix target/win_x64

完成后 5 个 demo exe + 必要的 sherpa-onnx 运行时 DLL 安装到 target\win_x64\ 下（CMake POST_BUILD + install）。

运行

工作目录建议 target\win_x64\。所有 demo 默认按 ..\..\..\models 自动定位模型根，可用第一个参数覆盖。

例：

1
2
3

.\demo_online_asr.exe
.\demo_online_asr.exe ..\..\..\models D:\test.wav
.\demo_tts.exe "今天天气真不错"

故障排查（demo 层）

如何替换/升级模型

模型文件全部是 .onnx + 元数据，与代码完全解耦。升级步骤：

1. 从 k2-fsa/sherpa-onnx Models 下载新模型
2. 解压到 models/<新模型目录>/
3. 改对应服务的 config.json 中的模型路径
4. 重启服务

例如把 ASR 模型从双语 zipformer 换成纯中文 zipformer：

1
2
3
4
5
6

{
  "asrEncoder": "../models/sherpa-onnx-streaming-zipformer-zh/encoder.onnx",
  "asrDecoder": "../models/sherpa-onnx-streaming-zipformer-zh/decoder.onnx",
  "asrJoiner": "../models/sherpa-onnx-streaming-zipformer-zh/joiner.onnx",
  "asrTokens":  "../models/sherpa-onnx-streaming-zipformer-zh/tokens.txt"
}

无需重新编译。

ASR 服务还内置了 asrModelName 预设（默认 sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30，
可切 sherpa-onnx-streaming-zipformer-bilingual-zh-en）。切换内置模型时改这一项即可，
无需逐个填 asrEncoder/Decoder/Joiner/Tokens；显式路径仅用于加载非内置模型。

在生产中需要关心 sherpa-onnx 吗

通常不需要。日常用法：

• 起 ASR / TTS 服务时 sherpa-onnx 是内嵌依赖，跟着 build.ps1 走
• 排查识别偏差、TTS 音质、VAD 切分时，回到 sherpa-demo/ 做最小复现
• 想换语言、换音色、换模型架构时，到 sherpa-onnx 官网找新模型、改路径

不在 sherpa-onnx 层做的事

sherpa-onnx 只负责”喂样本进去、拿结果出来”。

参考链接

• 项目主页：https://github.com/k2-fsa/sherpa-onnx
• 预训练模型库：https://k2-fsa.github.io/sherpa/onnx/pretrained_models/index.html
• Next-gen Kaldi：https://github.com/k2-fsa