sherpa-onnx：跨平台全功能语音工具箱（ASR/TTS/VAD/说话人）部署指南

sherpa-onnx 是 k2-fsa（新一代 Kaldi）团队开源的跨平台语音推理框架，基于 ONNX Runtime 在本地运行几乎所有常见语音任务：语音识别（ASR，流式与非流式都支持）、语音合成（TTS）、说话人分离、说话人识别、说话人验证、语种识别、音频标签、语音活动检测（VAD）、语音增强、关键词检出（KWS）、声源分离、自动加标点乃至声音克隆。它最大的特点是「不挑硬件」：从服务器、手机、平板到树莓派、Jetson 边缘盒、RK3588、LicheePi4A、VisionFive 2 等开发板都能跑，且无需 GPU，普通 CPU 即可实时推理。开源协议为 Apache-2.0，文档站为 k2-fsa.github.io/sherpa/onnx。k2-fsa 团队是原 Kaldi 语音识别工具链的新一代继承者，sherpa-onnx 是其「让语音模型脱离训练框架、直接在任何设备上跑推理」这一理念的落地产物。与需要装整套 PyTorch 的推理方案相比，它只依赖 ONNX Runtime 这一个轻量运行时，安装包小、启动快、内存占用低。

为什么需要这样一个工具箱？在 sherpa-onnx 出现之前，想同时做识别、合成、说话人分离，往往要在每个平台分别找不同框架、不同模型格式，移动端和嵌入式上更是困难重重。sherpa-onnx 把这些能力统一到 ONNX Runtime 之上，模型只导出一份 .onnx，通过 C++/C/Python/Java/Swift 等绑定在任意平台调用，真正实现「一次导出，处处运行」。对个人开发者而言，它意味着笔记本甚至手机就能跑起一个离线语音助手；对企业而言，它意味着把语音能力部署到没有网络的边缘设备上也毫无压力。典型组合是 VAD+ASR 两级管线：silero-vad 先把长音频切成人声段，再交给识别模型逐段转写，既减少静音段的幻觉，又能控制每次送入模型的长度，这套组合在官方 WebAssembly 演示与 APK 中都是默认配置。

一、项目官方信息

二、官方图片

sherpa-onnx 项目官方配图：

三、功能矩阵

sherpa-onnx 在本地支持的功能一览：

这些功能各自解决一类实际问题：ASR 把语音转成文字，流式版本适合边说边出字的实时字幕与语音助手，非流式版本适合会议录音转写；TTS 把文字读出来，VITS 类模型支持多人音色与语速调节，ZipVoice、Pocket TTS 还支持零样本声音克隆；VAD 先判断「有没有人在说话」，常和 ASR 串成 VAD+ASR 两级管线，避免把静音段送进识别模型浪费算力；说话人分离回答「这句话是谁说的」，说话人验证则用于声纹门禁等「是不是这个人」的场景；语种识别用于多语种音频自动分流；音频标签可判断一段录音是鸟鸣、掌声还是街道噪声；语音增强与声源分离用于从嘈杂背景里把人声单独提出来；关键词检出让设备在离线状态下也能响应唤醒词。此外它还支持自动加标点，把流式识别产生的无标点文本补成正常可读的句子。

四、平台与语言支持

硬件架构：x86、x86_64、32 位 ARM（arm32）、64 位 ARM（arm64/aarch64）、RISC-V（riscv64）；操作系统：Linux、macOS、Windows、openKylin、Android、WearOS、iOS、HarmonyOS、Node.js、WebAssembly。设备清单还包括 NVIDIA Jetson Orin NX / Nano B01（CPU/GPU 均可）、树莓派、RV1126、LicheePi4A、VisionFive 2、旭日 X3 派、爱芯派、RK3588、SpacemiT-K1/K3 等。

这份设备清单说明 sherpa-onnx 的目标不是「跑在数据中心 GPU 上」，而是「跑在任何能出声的设备上」：从 x86 服务器到 arm64 手机、从 riscv64 开发板到鸿蒙系统，它都给出了官方支持。即使是树莓派这种资源受限的板子，也能跑起离线 ASR；Jetson 系列则可以同时用 CPU 与 GPU 后端。对不想写代码的用户，官方还把每个能力做成了预构建安装包：Android 上有流式识别、模拟流式识别、非流式 TTS、VAD、VAD+ASR 两级、两遍识别（先出草稿再校正）、音频标签、WearOS 版音频标签、说话人识别、语种识别、关键词检出等 APK；Flutter 版 TTS 提供 Android、Linux、macOS、Windows 全平台安装包；Tauri 桌面应用则提供从文件或麦克风做非流式识别的开箱即用体验；Lazarus 还有专门的字幕生成应用。国内用户下载这些安装包时还能使用 GitHub 镜像加速地址。

编程语言 API 覆盖 C++、C、Python、JavaScript、Java、C#、Kotlin、Swift、Go、Dart、Rust、Object Pascal 共 12 种，并支持 WebAssembly。这意味着同一个 ONNX 模型，在 Python 里写脚本、在 Android 上用 Kotlin、在 iOS 上用 Swift、在 Web 上用 JS、在嵌入式里用 C++ 都能直接加载，不需要为每种语言重新训练或转换模型。框架集成方面提供 Flutter（Android/iOS/Windows/macOS/Linux/Web 全平台预构建 Demo）与 Tauri 桌面应用，预构建 Flutter/Tauri 安装包直接在 GitHub Releases 下载，iOS 需从源码构建。NPU 加速支持 Rockchip RKNN、Qualcomm QNN、Ascend NPU、Axera NPU 与 Intel NPU（OpenVINO），方便在边缘设备上以更低功耗获得实时性能——在 RK3588 等带 NPU 的板子上，识别与合成可以完全靠 NPU 跑，CPU 占用极低。

五、环境要求

Python 3.8 及以上；无需独立 GPU，CPU 即可实时推理；按目标架构选择 x64/arm64/arm32/riscv64 对应预编译包；预训练模型从 Hugging Face 的 k2-fsa 组织或 GitHub Releases 下载；可选 NPU 加速按对应厂商文档配置。移动端用户甚至不用写代码——官方提供预构建 Android APK（流式识别、TTS、VAD、VAD+ASR、两遍识别、音频标签、说话人识别、语种识别、关键词检出等）、WearOS 版音频标签应用、Flutter 应用与 Lazarus 字幕生成应用，装上即可体验。开发者则可以从源码编译 C++ 库，再按 HarmonyOS、iOS、Android NDK 等文档交叉编译到目标设备，配合官方提供的命令行工具（commandline-tools）在无 Python 环境的设备上直接跑识别与合成。

六、部署步骤

1. 安装 Python 包

pip 安装后即可 import sherpa_onnx 使用，Windows、macOS、Linux 的 x64 与 ARM64 都有预编译 wheel，无需本地编译 ONNX Runtime。

pip install sherpa-onnx

2. 下载预训练模型

以流式 Zipformer 中文小模型（适合 Cortex-A7）为例，从 GitHub Releases 下载压缩包并解压：

curl -SL -B -O https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-streaming-zipformer-zh-14M-2023-02-23.tar.bz2
tar xvf sherpa-onnx-streaming-zipformer-zh-14M-2023-02-23.tar.bz2

模型选择很丰富：流式有中英双语 Zipformer、14M 中文小模型、20M 英文模型、韩语、法语等；非流式有 SenseVoice（中英日韩粤+方言）、Paraformer 中文、Whisper tiny.en、Moonshine、NeMo Parakeet、TeleSpeech 方言模型等，完整列表见文档站的预训练模型页。具体来说，流式模型适合「边说边出字」：14M 参数的中文 Zipformer 小到能跑在 Cortex-A7 级别 CPU 上，适合极致低功耗的语音助手；双语 zipformer 模型支持中英混读；韩语、法语也有专门流式模型。非流式模型适合离线转写长音频：SenseVoice 一个模型覆盖中、英、日、韩、粤语及多种中文方言；Paraformer-large 同样支持中英加方言；Whisper tiny.en 适合英文轻量场景；NeMo Parakeet TDT 是从 NVIDIA 官方权重转换而来的英文模型；TeleSpeech CTC 则专注中文多方言。

3. 离线文件转写

OfflineRecognizer.from_transducer 加载 transducer 类模型（encoder/decoder/joiner 三个 onnx 文件加 tokens.txt），num_threads 控制推理线程，decoding_method 可选 greedy_search 或 greedy_search；识别时创建 stream、写入整段波形、调用 decode_stream 即可拿到文字。

import sherpa_onnx
recognizer = sherpa_onnx.OfflineRecognizer.from_transducer(
    encoder="model/encoder-epoch-99-avg-1.onnx",
    decoder="model/decoder-epoch-99-avg-1.onnx",
    joiner="model/joiner-epoch-99-avg-1.onnx",
    tokens="model/tokens.txt",
    num_threads=1, sample_rate=16000, feature_dim=80,
    decoding_method="greedy_search",
)
stream = recognizer.create_stream()
stream.accept_waveform(16000, audio_samples)
recognizer.decode_stream(stream)
print(stream.result.text)

4. 流式麦克风识别

OnlineRecognizer.from_transducer 加载流式模型，配合 sounddevice 从麦克风持续读入 1024 帧采样，写进 stream 后反复调用 is_ready/decode_stream/get_result 拿到增量识别文本，适合实时字幕、语音助手等边说边出字的场景。

import sherpa_onnx, sounddevice as sd
recognizer = sherpa_onnx.OnlineRecognizer.from_transducer(
    encoder="model/encoder.onnx", decoder="model/decoder.onnx",
    joiner="model/joiner.onnx", tokens="model/tokens.txt",
    num_threads=2, sample_rate=16000, feature_dim=80,
)
with sd.InputStream(samplerate=16000, channels=1, dtype="float32") as stream:
    s = recognizer.create_stream()
    while True:
        samples, _ = stream.read(1024)
        s.accept_waveform(16000, samples.reshape(-1))
        while recognizer.is_ready(s):
            recognizer.decode_stream(s)
            print(recognizer.get_result(s).text)

5. TTS 合成

TTS 侧通过 OfflineTtsConfig 配置 VITS 类模型（model.onnx + lexicon.txt + tokens.txt），generate() 传入文本、sid 选择音色、speed 控制语速，直接返回可播放的波形数组。除 VITS 外还支持 Piper、Matcha、MeloTTS 等，中文可选用 vits-icefall-zh-aishell3 等模型。

import sherpa_onnx
tts_config = sherpa_onnx.OfflineTtsConfig(
    model=sherpa_onnx.OfflineTtsModelConfig(
        vits=sherpa_onnx.OfflineTtsVitsModelConfig(
            model="vits-icefall-zh-aishell3/model.onnx",
            lexicon="vits-icefall-zh-aishell3/lexicon.txt",
            tokens="vits-icefall-zh-aishell3/tokens.txt",
        )
    ),
    max_num_sentences=1,
)
tts = sherpa_onnx.OfflineTts(tts_config)
audio = tts.generate("你好，欢迎使用 sherpa-onnx 语音合成。", sid=0, speed=1.0)

七、使用方法与生态

sherpa-onnx 的设计哲学是「同一套 ONNX 模型，换个平台重新加载即可」：模型文件与平台解耦，Python、C++、Android、Flutter、Web 加载的是同一份 .onnx。想零安装体验，可以直接用 Hugging Face Spaces 上的在线演示（说话人分离、ASR、Whisper 识别、TTS、字幕生成、音频标签、声源分离、语种识别，另有 WebAssembly 版在浏览器本地跑实时识别与语音合成，国内用户还有 ModelScope 镜像）。WebAssembly 版演示尤其能说明它的轻量：打开网页后，语音识别、VAD、TTS、说话人分离全部在浏览器里本地运行，不向服务器发任何音频，涵盖中英双语 Zipformer、Paraformer、SenseVoice、Whisper tiny.en、Moonshine、Piper/Matcha 多语种 TTS 等模型，甚至包括 ZipVoice 与 Pocket TTS 的声音克隆。

社区生态非常活跃，仓库列举了大量基于 sherpa-onnx 的实际项目：小智 AI 服务器 xiaozhi-esp32-server 把它用作 ESP32 开源聊天机器人的本地识别引擎；腾讯会议字幕工具 TMSpeech 用它实时转写会议内容；Open-LLM-VTuber 做虚拟主播语音助手；还有 Go 版与 C++ 版的 WebSocket ASR 服务器、SmartSub 字幕工具、flet_sherpa_onnx、achatbot-go 聊天机器人、fcitx5-vinput 语音输入法、Open-XiaoAI KWS 离线唤醒词、Loud Caption、Recly、Domia，以及 iOS 上的 VocaRead 朗读应用、sherpa-onnx-unity 游戏引擎集成、中国联通与中国人寿的官方 App，足见其在生产级落地中的成熟度。

八、常见问题（FAQ）

• 必须要 GPU 吗？ 不需要。sherpa-onnx 主打 CPU 实时推理，低功耗设备也能跑；有条件可用 RKNN/QNN/Ascend 等 NPU 进一步加速。
• 支持哪些语言的模型？ 中文（含方言）、英、日、韩、法、德、西、意、俄、泰、越南等都有现成模型，覆盖 Whisper、Paraformer、SenseVoice、Zipformer 等架构，详见文档站模型页。
• 手机上怎么用？ 直接下载预构建 Android APK 或 Flutter App，无需自己编译；iOS 与 HarmonyOS 需按文档从源码构建。
• 怎么选流式还是非流式模型？ 实时语音助手、麦克风输入用流式模型（OnlineRecognizer）；文件转写、字幕生成用非流式模型（OfflineRecognizer）。官方还提供「两遍识别」APK：第一遍流式快速出草稿，第二遍非流式大模型校正，兼顾实时性与准确率，适合会议字幕等场景。
• 想在浏览器里跑？ 用 WebAssembly 版 Hugging Face Space，或自行把 sherpa-onnx 编译为 WASM，识别全程在本地完成。
• TTS 怎么选音色和语速？ OfflineTts.generate() 的 sid 参数选择说话人 ID（多音色模型支持），speed 参数控制语速，max_num_sentences 控制一次合成多少句。
• 识别结果没有标点怎么办？ 官方提供专门的标点恢复模型，可在转写后把无标点文本补成正常句子；也可选择带标点能力的模型。
• 和 Whisper 是什么关系？ sherpa-onnx 是一个推理框架，它把 Whisper 等模型导出为 ONNX 后统一加载，所以你可以在树莓派上跑 Whisper，也可以跑 Zipformer、Paraformer，接口完全一致。
• 找不到模型怎么办？ 文档站的预训练模型页按流式/非流式/语种分类列出全部模型，每个模型都有对应的中文说明和下载地址；找不到的模型也可以自行用 ONNX 转换工具导出后按接口加载。
• 说话人分离怎么用？ 官方有预构建 Android APK 与 Hugging Face Space 演示，Python 侧加载 3D-Speaker 类模型即可；移动端可直接用预构建 APK 体验。
• 和 sherpa（k2-fsa 原版）什么关系？ sherpa-onnx 是 sherpa 的 ONNX Runtime 重写版，去掉了对 PyTorch 的运行时依赖，因此体积更小、跨平台更省心，适合部署。

九、跳转链接

• 项目仓库：github.com/k2-fsa/sherpa-onnx
• 官方文档：k2-fsa.github.io/sherpa/onnx
• 预训练模型：GitHub Releases asr-models
• 在线体验：Hugging Face Spaces
• 社区：Discord
• 视频演示：Bilibili 搜索「新一代Kaldi」

社区交流方面，官方在微信、QQ 均有「新一代 Kaldi」交流群，详情见社交群页面，遇到模型或部署问题可直接在群内或 GitHub Issues 反馈。

sherpa-onnx 适合的场景非常广：从离线语音助手、会议转写、字幕生成，到智能硬件、车载语音、嵌入式设备的本地识别与合成，只要希望「不依赖云端、跨设备跑语音模型」，都可以把它作为底座。其 Apache-2.0 协议也允许商业项目自由集成，是目前边缘侧语音落地少有的「全家桶」级开源方案，个人与企业均可放心使用，无需担心授权问题。