sherpa-onnx编译指南：从源码到可执行文件
项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx 引言：编译痛点与解决方案
你是否曾因跨平台编译语音模型部署工具而困扰？面对CMake复杂配置选项无从下手？遭遇依赖库版本冲突难以解决？本文将系统梳理sherpa-onnx从源码到可执行文件的全流程编译方案，涵盖Linux/macOS/Windows三大桌面系统及Android/iOS移动平台，提供15+实用编译模板与8类常见问题解决方案，助你2小时内完成从环境搭建到功能验证的全流程实践。
读完本文你将掌握：
- 3大桌面系统的依赖库自动化安装脚本
- 7类编译配置选项的实战组合策略
- 5种硬件加速方案的编译参数配置
- 跨平台编译产物的验证与调试技巧
- 静态/动态库切换的最佳实践指南
技术背景：sherpa-onnx编译架构解析
sherpa-onnx作为基于ONNX Runtime的语音处理工具包，其编译系统采用CMake+FetchContent架构，通过模块化设计实现跨平台支持。核心编译流程包含三大阶段：
关键技术特性：
- 多语言绑定：支持C++/Python/Java等12种编程语言API
- 硬件加速：集成CUDA/DirectML/RKNN等8种计算后端
- 模块化编译：通过23个CMake选项控制功能模块开关
- 自动依赖管理：内置35+第三方库的自动下载配置
环境准备：系统要求与依赖安装
系统兼容性矩阵
| 操作系统 | 最低版本 | 架构支持 | 编译工具链 |
|---|---|---|---|
| Ubuntu | 18.04 | x64/arm64/riscv64 | GCC 7.5+/Clang 9+ |
| macOS | 10.14 | x64/arm64 | Xcode 11+/Clang 11+ |
| Windows | 10 | x64/x86/arm64 | MSVC 2019+/MinGW-w64 |
| Android | 5.0 | armv7/arm64 | NDK r21+ |
| iOS | 12.0 | arm64/x86_64 | Xcode 12+ |
依赖库安装命令
Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y \
build-essential cmake git wget \
libssl-dev libasound2-dev \
libportaudio2 portaudio19-dev \
python3-dev python3-pip
macOS
brew install cmake git wget portaudio python
Windows
# 使用Chocolatey包管理器
choco install cmake git wget python portaudio
源码获取与目录结构
源码克隆
git clone https://gitcode.com/GitHub_Trending/sh/sherpa-onnx
cd sherpa-onnx
核心目录解析
sherpa-onnx/
├── cmake/ # CMake模块配置
├── sherpa-onnx/ # 核心源码
│ ├── csrc/ # C++实现
│ ├── python/ # Python绑定
│ └── c-api/ # C语言接口
├── scripts/ # 平台编译脚本
└── cxx-api-examples/ # 示例程序
通用编译流程：基础配置与构建
标准编译步骤
# 创建构建目录
mkdir build && cd build
# 配置CMake (默认Release模式)
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SHARED_LIBS=ON \
-DSHERPA_ONNX_ENABLE_PYTHON=ON
# 并行编译
make -j$(nproc)
# 安装 (可选)
sudo make install
关键CMake选项说明
| 选项名称 | 取值范围 | 默认值 | 说明 |
|---|---|---|---|
| BUILD_SHARED_LIBS | ON/OFF | OFF | 构建动态库/静态库 |
| SHERPA_ONNX_ENABLE_PYTHON | ON/OFF | OFF | 启用Python API |
| SHERPA_ONNX_ENABLE_GPU | ON/OFF | OFF | 启用NVIDIA GPU支持 |
| SHERPA_ONNX_ENABLE_TTS | ON/OFF | ON | 构建语音合成模块 |
| SHERPA_ONNX_ENABLE_WEBSOCKET | ON/OFF | ON | 启用WebSocket服务器功能 |
| SHERPA_ONNX_USE_PRE_INSTALLED_ONNXRUNTIME_IF_AVAILABLE | ON/OFF | ON | 使用系统已安装的ONNX Runtime |
平台专项编译指南
Linux平台优化编译
静态库编译 (推荐生产环境)
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SHARED_LIBS=OFF \
-DSHERPA_ONNX_LINK_LIBSTDCPP_STATICALLY=ON
NVIDIA GPU加速编译
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DSHERPA_ONNX_ENABLE_GPU=ON \
-DSHERPA_ONNX_LINUX_ARM64_GPU_ONNXRUNTIME_VERSION=1.18.1
Windows平台编译
MSVC编译
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
msbuild sherpa-onnx.sln /p:Configuration=Release /m
MinGW编译
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
mingw32-make -j4
macOS平台编译
通用二进制构建 (x64+arm64)
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
make -j8
移动平台交叉编译
Android编译
# 使用项目提供的脚本
cd scripts/android
./build-android-arm64-v8a.sh
iOS编译
# 使用项目提供的脚本
./scripts/build-ios.sh
嵌入式平台编译
RISC-V64平台
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=toolchains/riscv64-linux-gnu.toolchain.cmake \
-DBUILD_SHARED_LIBS=OFF
RK3588 NPU支持
./scripts/build-rknn-linux-aarch64.sh
WebAssembly编译
浏览器环境构建
# VAD+ASR功能模块
./scripts/build-wasm-simd-vad-asr.sh
Node.js环境构建
./scripts/build-wasm-simd-nodejs.sh
编译产物验证
C++示例验证
# 运行流式语音识别示例
./build/bin/sherpa-onnx-online-websocket-server \
--port 6006 \
--encoder ./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/encoder.onnx \
--decoder ./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/decoder.onnx \
--joiner ./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/joiner.onnx \
--tokens ./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/tokens.txt
Python API验证
import sherpa_onnx
config = sherpa_onnx.OnlineRecognizerConfig(
encoder_filename="encoder.onnx",
decoder_filename="decoder.onnx",
joiner_filename="joiner.onnx",
tokens="tokens.txt",
)
recognizer = sherpa_onnx.OnlineRecognizer(config)
print("Python API加载成功")
常见问题解决方案
编译错误排查流程
典型问题解决案例
1. ONNX Runtime下载失败
# 手动下载指定版本ONNX Runtime
wget https://github.com/microsoft/onnxruntime/releases/download/v1.16.0/onnxruntime-linux-x64-1.16.0.tgz
tar xzf onnxruntime-linux-x64-1.16.0.tgz
export SHERPA_ONNXRUNTIME_INCLUDE_DIR=./onnxruntime-linux-x64-1.16.0/include
export SHERPA_ONNXRUNTIME_LIB_DIR=./onnxruntime-linux-x64-1.16.0/lib
2. CUDA版本不匹配
# 指定兼容的ONNX Runtime GPU版本
cmake .. -DSHERPA_ONNX_ENABLE_GPU=ON \
-DSHERPA_ONNX_LINUX_ARM64_GPU_ONNXRUNTIME_VERSION=1.18.0
3. portaudio依赖缺失
# Ubuntu
sudo apt-get install portaudio19-dev
# macOS
brew install portaudio
# Windows
choco install portaudio
高级编译配置
最小化构建
cmake .. \
-DBUILD_SHARED_LIBS=OFF \
-DSHERPA_ONNX_ENABLE_TTS=OFF \
-DSHERPA_ONNX_ENABLE_SPEAKER_DIARIZATION=OFF \
-DSHERPA_ONNX_ENABLE_WEBSOCKET=OFF
调试模式构建
cmake .. \
-DCMAKE_BUILD_TYPE=Debug \
-DSHERPA_ONNX_ENABLE_CHECK=ON \
-DSHERPA_ONNX_ENABLE_SANITIZER=ON
自动化编译与CI/CD集成
GitHub Actions工作流示例
name: Build
on: [push]
jobs:
linux:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: sudo apt-get install -y build-essential cmake portaudio19-dev
- name: Build
run: |
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON
make -j4
总结与展望
本文详细阐述了sherpa-onnx的全平台编译方案，涵盖从环境准备到产物验证的完整流程。通过灵活配置CMake选项，开发者可根据实际需求定制构建方案，平衡功能、性能与体积。随着项目的持续迭代，未来编译系统将进一步简化，提供更丰富的硬件加速支持和更完善的多平台适配。
建议收藏本文作为编译参考手册，关注项目CHANGELOG获取最新编译特性更新。如有编译问题，可通过项目GitHub Issues或Discord社区获取支持。
附录：编译选项速查表
| 功能需求 | 推荐CMake选项组合 |
|---|---|
| 基础语音识别 | -DBUILD_SHARED_LIBS=ON -DSHERPA_ONNX_ENABLE_PORTAUDIO=ON |
| 语音合成+识别 | 默认配置即可 (TTS默认启用) |
| GPU加速 | -DSHERPA_ONNX_ENABLE_GPU=ON |
| 移动端部署 | -DBUILD_SHARED_LIBS=ON -DSHERPA_ONNX_ENABLE_JNI=ON |
| Web浏览器部署 | 使用build-wasm-simd-*系列脚本 |
| 静态链接部署 | -DBUILD_SHARED_LIBS=OFF -DSHERPA_ONNX_LINK_LIBSTDCPP_STATICALLY=ON |
| 开发调试 | -DCMAKE_BUILD_TYPE=Debug -DSHERPA_ONNX_ENABLE_CHECK=ON -DSHERPA_ONNX_ENABLE_SANITIZER=ON |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
