sherpa-onnx 完整解析：5 分钟跑通本地离线语音识别与语音合成

【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx

给 App 加语音输入、做语音助手设备，大多数人第一反应是接云端语音服务：接入快，但音频必须出网。这带来三个麻烦——隐私敏感场景（企业内网、会议录音）不敢用；长期运行的设备要按量付费；弱网或无网环境直接失效。如果希望"离线语音识别"完全跑在设备本地，可选方案并不多，sherpa-onnx 是其中落地案例最多、语言覆盖最广的一个。

sherpa-onnx 是基于 next-gen Kaldi + ONNX Runtime 的开源语音 AI 推理框架，把语音转文字（ASR）、文字转语音（TTS）、说话人分离、语音增强、声源分离、语音活动检测（VAD）这些能力打包成可离线运行的引擎。核心卖点是"一份模型、到处跑"：同一个 ONNX 模型文件，可以在树莓派、RK3588 开发板、Android/iOS 手机或 x86 服务器上运行，官方提供 C++、C、Python、Go、Rust、Java、Kotlin、Swift、C#、Dart、JavaScript、Pascal 共 12 种语言的 API，还支持 WebAssembly。

sherpa-onnx 是什么：一个完全离线的语音 AI 推理引擎

一句话说清：sherpa-onnx 是"模型 + 运行时 + 多语言接口"的工具包，把主流开源语音模型转成 ONNX 格式，再提供统一的推理接口。它解决的问题可以归纳为三点：

1. 离线：运行时不访问网络，模型就是本地文件，提前下载好即可；
2. 模型统一：它不自己训练模型，而是统一接入 Whisper、Paraformer、SenseVoice、Zipformer、NeMo、WeNet（CTC / transducer）、silero VAD 等现成开源模型；
3. 跨平台：C++ 核心做薄，各语言绑定做薄。README 中的平台清单覆盖 Linux、macOS、Windows、Android、iOS、HarmonyOS、Raspberry Pi、Jetson、RV1126、VisionFive 2 等，并支持 RKNN、Qualcomm QNN、Ascend、Axera、Intel OpenVINO 等 NPU。

原理拆解：为什么一份模型能在手机和服务器上跑

sherpa-onnx 的架构关键在分层。C++ 核心位于 sherpa-onnx/csrc/，负责特征提取（FBank）、ONNX Runtime 推理和词表解码；Python、Go、Rust、Java 等语言绑定都是薄封装。Python 的调用链是"Python API → pybind11 → C++ 核心 → ONNX Runtime"，所以在任何平台上，同一份业务逻辑不用改。

有两个设计细节值得理解。

第一，模型只是"文件 + tokens.txt"。OfflineRecognizer的工厂方法from_whisper()、from_paraformer()、from_transducer()只是参数组合不同，内部流程一致：读音频 → 提取 fbank 特征（默认feature_dim=80、sample_rate=16000）→ 过 ONNX 模型 → 用greedy_search或 beam search 把 token 解码成文字。这意味着从 Whisper 换到 Paraformer，改的只是构造函数那一行。

第二，推理后端可切换。--provider参数可选 cpu、cuda、coreml 等。以 OPENVINO.md 里的 Intel NPU 方案为例：计算重的 encoder 交给 OpenVINO 的 NPU 执行，而 decoder/joiner 这类小模型留在 CPU，避免小算子反复调度到 NPU 的开销——这是典型的端侧拆分思路。

上图是仓库 python-api-examples/web/ 里的浏览器演示：核心编译成 WebAssembly 后，直接在浏览器里完成识别，不需要服务端。

快速上手：pip install 和最小识别示例

Python 用户上手成本最低：pip install sherpa-onnx即可（仓库根目录的 setup.py 就是发布包的来源）。识别模型需要单独下载model.onnx和tokens.txt，README 里按 ASR、TTS、VAD 分类给了模型清单。

最小非流式（离线）识别示例：

import sherpa_onnx recognizer = sherpa_onnx.OfflineRecognizer.from_paraformer( paraformer="/path/to/paraformer.onnx", tokens="/path/to/tokens.txt", num_threads=2, sample_rate=16000, feature_dim=80, ) stream = recognizer.create_stream() stream.accept_waveform(16000, samples) # float32 数组，取值范围 [-1, 1] recognizer.decode_streams([stream]) print(stream.result.text)

两个容易忽略的细节：官方示例 python-api-examples/offline-decode-files.py 中，wav 文件采样率不必是 16 kHz，库内部会自动重采样；麦克风输入同理（官方 mic 示例故意用 48 kHz 采集，交给库转换）。另外示例脚本会打印 RTF（耗时/音频时长），RTF 小于 1 说明跑得比实时快，TTS 演示截图里 RTF 0.305 即合成 1 秒音频只需 0.305 秒。

🧩 深度特性：流式识别、VAD 切分、热词偏置

流式识别（online ASR）。流式 transducer 模型分 encoder/decoder/joiner 三件套，创建 stream 后每来一小块音频就喂一次。核心循环如下：

stream = recognizer.create_stream() while True: samples = read_mic_chunk(0.1) # 每次读 100ms 音频 stream.accept_waveform(16000, samples) while recognizer.is_ready(stream): recognizer.decode_stream(stream) print(recognizer.get_result(stream), end="\r")

VAD + 非流式 ASR 组合。这是"长音频转写"最常用的架构：先让 silero-vad 把连续音频切成语音段，再逐段丢给 Paraformer / Whisper。对应示例是 python-api-examples/vad-with-non-streaming-asr.py，仓库里 android/ 下的 SherpaOnnxVadAsr 演示 App 也是同一套流程，可以直接对照 App 层怎么写。

热词偏置与 TTS。ASR 支持--hotwords-file（每行一个词）加--hotwords-score（默认 1.5）来提升专有名词、行业术语的召回率；TTS 侧则覆盖 VITS、Piper、Matcha、Kokoro、ZipVoice（零样本声音克隆）等多个模型族，官方示例同样打印 RTF，方便你判断能否满足实时性要求。

以上特性的完整代码都能在 c-api-examples/、flutter-examples/ 等目录找到，基本每种功能都有 C/C++ 和脚本语言两版对照。

落地与边界：适合谁，不适合谁

适合的场景：隐私敏感（音频不出设备）、嵌入式与边缘设备（模型普遍提供 INT8 量化版本，ARM32/64、RISC-V 都有预构建 APK/Flutter 演示）、以及需要 ASR + VAD + TTS + 唤醒词由同一个 SDK 统一承载的产品。

需要清醒的地方：它提供的是"推理引擎"，不是开箱即用的云语音服务。你仍要自己选型——Whisper、Paraformer、SenseVoice 在中英文上的表现各有取舍，模型权重也要自己下载，这部分才是真正的工作量大头。服务化能力（连接管理、并发、计费）要自己搭，仓库提供了 WebSocket server/client 示例可参考。GPU/NPU 加速依赖特定编译的 onnxruntime，例如 OpenVINO EP 需要带该 provider 的 onnxruntime 构建，细节见 OPENVINO.md；新手从 CPU 路径起步最稳。

收尾

如果你要落地本地离线语音识别与 TTS，建议先用 Python API 配 Whisper 或 Paraformer 的 INT8 模型验证效果，跑通后再考虑 C++ 集成或移动端移植。仓库地址：https://gitcode.com/GitHub_Trending/sh/sherpa-onnx ，clone 下来后按 python-api-examples/ → c-api-examples/ → OPENVINO.md 的顺序读，一天内足够建立完整认知。

【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx