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同一个 ONNX 模型文件在服务器上跑、在手机上跑端到端延迟都能压到 100ms 上下——这是 sherpa-onnx 的核心卖点。它是一套基于 ONNX Runtime 的离线语音引擎覆盖语音识别ASR、文本转语音TTS、VAD 端点检测、说话人分离、关键词唤醒、音频标签、语音增强等能力全程不依赖互联网。下文以 Linux、Android、iOS、Windows、HarmonyOS 五个平台为主线把源码编译、预编译包集成、服务化部署、模型选型和调优参数一次讲透所有命令均可直接执行。先看收益再决定读多深读完能做的事所在章节在 Linux / macOS 上完成全量编译并看懂每个 CMake 开关Linux 源码编译给 Android / iOS 工程接入 AAR 与预编译框架移动端最快集成路径拉起一个流式 ASR 服务并接上各类客户端生产环境服务化部署按设备形态选模型体积 / 实时因子 / 内存对照表模型选型对比交叉编译到 ARM / RISC-V点亮 NPU 加速鸿蒙与嵌入式交叉编译全局速览一条部署管线而不是一堆平台补丁传统做法是每个平台写一套适配代码sherpa-onnx 的路径相反模型与推理逻辑只写一次平台差异全部收敛到构建系统与语言绑定层。整条管线如下五个主力平台的支持情况与延迟量级目标平台主流架构交付形态参考端到端延迟Linuxx64 / ARM64 / RISC-V源码构建~80ms实时因子 0.8Androidarm64-v8a / armeabi-v7aAAR 包 / 预编译 APK~120msiOSarm64预编译框架 / Pod~95msWindowsx64 / ARM64MSVC 构建~110msHarmonyOSarm64-v8aHAR 包~150ms绑定层的厚度也是这套方案的一部分仓库为每种语言都配了独立示例目录找哪个语言先看哪里——语言示例目录C / Cc-api-examples/ 、cxx-api-examples/Pythonpython-api-examples/Java / Kotlinjava-api-examples/ 、kotlin-api-examples/C# / Go / Rustdotnet-examples/ 、go-api-examples/ 、rust-api-examples/Dart / Flutterdart-api-examples/ 、flutter-examples/Swift / Pascal / Node.jsswift-api-examples/ 、pascal-api-examples/ 、nodejs-examples/浏览器wasm/Linux 源码编译从零到可用的完整步骤这是所有平台的基础路线也最适合作为验证环境。以 Ubuntu 20.04 为例先装齐工具链与音频依赖再克隆代码sudo apt install -y build-essential cmake git libsndfile1-dev libportaudio2 git clone https://gitcode.com/GitHub_Trending/sh/sherpa-onnx cd sherpa-onnx mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease .. make -j$(nproc)编译开关比命令本身更值得花时间CMakeLists.txt 里常用的几个选项作用默认值SHERPA_ONNX_ENABLE_PYTHON生成 Python 绑定OFFBUILD_SHARED_LIBS输出动态库而非静态库OFFSHERPA_ONNX_ENABLE_GPU用 CUDA 版 ONNX RuntimeOFFSHERPA_ONNX_ENABLE_WEBSOCKET内置 websocket 服务端/客户端ONSHERPA_ONNX_ENABLE_PORTAUDIO麦克风采集无头服务器可关ONCMAKE_INSTALL_PREFIX安装目标路径建议指向/usr/local系统默认同样的流程在 macOS 上成立只是依赖换成 Homebrew 管理brew install cmake pkg-config portaudio cmake -B build -DCMAKE_BUILD_TYPERelease .. cmake --build build -j8x86_64 与 arm64Apple Silicon都能直接产出无需额外配置。Windows 平台编译与打包Windows 路线的要点不是会不会编译而是三个容易踩的开关。先用 Visual Studio 2022 生成器配置mkdir build; cd build cmake -G Visual Studio 17 2022 -A x64 .. msbuild sherpa-onnx.sln /p:ConfigurationRelease编译期细节/utf-8源码含非 ASCII 字符不开会在个别编译器版本上报 C4819/wd4251关掉 C/CLI 兼容性警告避免日志刷屏/MP多处理器并行编译大工程能省掉一半等待时间运行时库仓库默认静态 CRT/MT见SHERPA_ONNX_USE_STATIC_CRT如果你要把产物当 DLL 分发给用动态 CRT 的工程需要cmake -DSHERPA_ONNX_USE_STATIC_CRTOFF ..重配。下图是同一套 Flutter 示例在 Windows 端运行 TTS 的效果可以直观感受一套代码多端的实际产出移动端最快集成路径Android 与 iOSAndroidAAR 接入 权限清单不想自己交叉编译时直接引预编译 AAR 是最短路径在app模块的 gradle 里加一行dependencies { implementation com.k2fsa.sherpa:onnx:1.7.0 }音频与模型下载功能对应的权限缺一不可uses-permission android:nameandroid.permission.RECORD_AUDIO / uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE /android/ 目录里按场景拆了十余个可直接运行的 Demo 工程选一个最贴近你业务的抄结构即可SherpaOnnx流式实时识别SherpaOnnx2Pass流式 非流式双级识别SherpaOnnxVadAsrVAD 切句 非流式 ASR 的经典组合SherpaOnnxTtsEngine替换系统 TTS 引擎电子书、听书类应用SherpaOnnxWebSocket作为客户端连回 Python 流式服务端SherpaOnnxSpeakerDiarization/SherpaOnnxSpeakerIdentification说话人分离与识别。批量构建不同功能的 APK 有现成脚本见 scripts/apk/。iOSCocoaPods SwiftUI 示例在 Podfile 中配置好项目源之后锁定版本号引入pod SherpaOnnx, :tag v1.7.0ios-swiftui/ 提供四个 SwiftUI 工程作参考SherpaOnnx基础识别、SherpaOnnx2Pass双阶段识别、SherpaOnnxLangID语种识别、SherpaOnnxTts合成。核心调用只有三步——组装配置、创建引擎、监听回调import SherpaOnnx // encoder/decoder/joiner 三个 ONNX 文件 词表 let cfg ModelConfig( encoderPath: Bundle.main.path(forResource: encoder, ofType: onnx)!, decoderPath: Bundle.main.path(forResource: decoder, ofType: onnx)!, joinerPath: Bundle.main.path(forResource: joiner, ofType: onnx)!, tokensPath: Bundle.main.path(forResource: tokens, ofType: txt)!) let engine SherpaOnnxStreamingAsr(config: cfg) engine.startRecording { result in // 回调在后台线程更新 UI 前要切回主线程 DispatchQueue.main.async { self.transcriptBox.text result.text } }HarmonyOS 与嵌入式交叉编译 NPU 加速HarmonyOS 应用结构harmony-os/ 下按能力分目录SherpaOnnxHar是核心 HAR 库其余是场景应用SherpaOnnxStreamingAsr流式识别、SherpaOnnxTts合成、SherpaOnnxVadAsrVAD ASR、说话人分离与识别各一个。构建流程hpm install sherpa_onnx ohos-builder build --mode release用工具链文件交叉编译 ARM / RISC-V面向 RK3399、树莓派一类的 ARM 板卡不要手改编译器交给工具链文件。仓库 toolchains/ 目录已经备好了五个aarch64-linux-gnu、arm-linux-gnueabihf32 位 ARM、ios、riscv64-linux-gnu、riscv64-linux-gnu-spacemit。以 AArch64 为例cmake -DCMAKE_TOOLCHAIN_FILE../toolchains/aarch64-linux-gnu.toolchain.cmake .. make -j4aarch64-linux-gnu.toolchain.cmake的核心就是四件事声明CMAKE_SYSTEM_NAME Linux与CMAKE_SYSTEM_PROCESSOR aarch64、指定交叉编译器前缀、锁定头文件/库只在目标 rootfs 里查找、追加-marcharmv8-a。RISC-V 板卡如 VisionFive 2换用 riscv64 工具链即可。点亮 NPU如果板卡带 NPUCMakeLists.txt 中按芯片逐个打开对应开关全部默认 OFF瑞芯微 RKNN-DSHERPA_ONNX_ENABLE_RKNNON高通 QNN-DSHERPA_ONNX_ENABLE_QNNON昇腾 Ascend-DSHERPA_ONNX_ENABLE_ASCEND_NPUON爱芯 Axera-DSHERPA_ONNX_ENABLE_AXERAON生产环境服务化部署流式 ASR 服务的完整步骤模型验证通过后下一步是把它变成多客户端可连的服务。仓库自带的 streaming_server.py 同时提供 websocket 接口与一个浏览器调试页面启动命令如下以中文 14M 流式 Zipformer 为例python3 python-api-examples/streaming_server.py \ --encoder ./sherpa-onnx-streaming-zipformer-zh-14M-2023-02-20/encoder.onnx \ --decoder ./sherpa-onnx-streaming-zipformer-zh-14M-2023-02-20/decoder.onnx \ --joiner ./sherpa-onnx-streaming-zipformer-zh-14M-2023-02-20/joiner.onnx \ --tokens ./sherpa-onnx-streaming-zipformer-zh-14M-2023-02-20/tokens.txt \ --num-threads 4 \ --port 6006服务端起来之后客户端任选其一都有对应示例命令行客户端python-api-examples/online-websocket-client-decode-file.py浏览器页面python-api-examples/web/Node.js 业务侧nodejs-examples/ Android 端回连android/SherpaOnnxWebSocket工程纯前端免安装wasm/ 的 WebAssembly 版本。服务端性能调优的三个抓手线程数--num-threads设为 CPU 核心数的 1.5 倍左右4 核配 6 线程让推理尽量吃满多核并发容量按峰值并发设置--max-batch-size例如 32让内存池可复用模型侧换 int8 量化版模型内存占用大约能降 40%精度损失通常可忽略。一套代码发五个端Flutter 与 Tauri如果你的业务本身就是跨端应用还有更省事的一层仓库直接维护了 Flutter 插件 flutter/ 与 tauri-examples/一份 Dart / Rust 代码可编译到 Android、iOS、Windows、macOS、Linux 与 Web。下面这张图是 Flutter TTS 示例在 macOS 端运行的实际画面与上文 Windows 截图出自同一个工程模型选型对比移动端、桌面端、服务器各选谁选模型先问设备再问精度需求。常用四款的硬指标模型体积实时因子 RTF内存占用适合端Zipformer-small14MB0.860MB移动端 / 树莓派级设备SenseVoice23MB0.685MB移动端多语种 方言Whisper tiny75MB1.2300MB桌面端通用多语种Paraformer116MB0.3450MB服务器 / 高吞吐服务判断口径很简单RTF 1 才能实时移动端同时卡体积和内存服务端只卡 RTF 与吞吐。配套的调优参数线程移动端设核心数 / 2防止过度调度反而劣化延迟服务端设核心数 × 1.5输入边界用--max-wav-duration限制单条音频长度长音频改走 VAD 切句内存开启--use-allocator-pool复用分配器量化移动端首选 int8实测精度损失 5%内存极度受限的嵌入式设备考虑 uint8。避坑清单九个容易翻车的细节要 Python 绑定却没加-DSHERPA_ONNX_ENABLE_PYTHONON——它默认是 OFF默认产出静态库BUILD_SHARED_LIBS默认 OFF想要 .so/.dll 需显式打开Windows 默认静态 CRTDLL 消费者报链接错误时先查SHERPA_ONNX_USE_STATIC_CRTNPU 开关RKNN/QNN/Ascend/Axera全部默认 OFF没开等于纯 CPUGPU 推理需要-DSHERPA_ONNX_ENABLE_GPUON并自备 CUDA 环境Windows 上另有一个 DirectML 开关交叉编译只认-DCMAKE_TOOLCHAIN_FILE手动指定编译器的做法在依赖查找阶段就会出错无头服务器上建议关掉 PortAudioSHERPA_ONNX_ENABLE_PORTAUDIOOFF少一个系统依赖移动端线程数盲目拉满反而因为调度抖动把延迟做高拿桌面端大模型100MB直接塞进手机端安装包包体与首包下载都会很难看——先量化、再裁剪。下一步三条最小行动路径验证构建任选一个流式 Zipformer 模型跑一遍 c-api-examples/ 里的decode-file-c-api确认二进制产物可用验证服务拉起streaming_server.py用浏览器调试页或 websocket 客户端打一条真实语音验证选型固定模型后把num-threads按 1 / 2 / 4 扫一遍并记录 RTF用数据而不是直觉定线程数。编译报错或延迟不达标时先回到避坑清单逐条对照——绝大多数平台问题其实是构建开关问题。选定你的目标平台从对应的章节开始动手即可。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考