Sherpa-ONNX 语音合成(TTS)新手入门：5 个平台一次配好，附完整参数速查

Sherpa-ONNX 语音合成(TTS)新手入门：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

Sherpa-ONNX 是基于 ONNX Runtime 的离线语音工具箱，一条命令就能把中文、英文文本转成自然语音，无需联网，覆盖 Android、iOS、Windows、macOS、Linux、树莓派与 RISC-V 等环境。本文带你装好环境、选好模型，跑通第一句文本转语音(TTS)。

它解决什么问题

很多项目要在手机、桌面和嵌入式设备上朗读文本，却要为每个平台单独找引擎、调参数。Sherpa-ONNX 把 TTS、语音识别、声纹分离等能力统一成同一套 ONNX 模型和 C 核心，配合 Python、Java、Kotlin、Go、Swift、Dart、Rust 等 12 种语言的绑定，做到"模型一次准备、多端直接调用"。

• 完全离线运行，推理不依赖网络，适合隐私敏感的本地应用。
• 同一模型可在 CPU、CUDA、CoreML 等不同后端推理，性能随设备自适应。
• 内置多种开箱即用的 TTS 模型（VITS、Matcha、Kokoro、Kitten），下载即用。
• 提供跨平台示例工程（Android、iOS、HarmonyOS、桌面与 Flutter），可直接改参数验证效果。

快速上手

装环境：Python 路线最快，官方 wheel 已打包好，一条命令即可：

pip install sherpa-onnx soundfile

若要从源码构建，可先克隆仓库再进入 Python 示例目录：

git clone https://gitcode.com/GitHub_Trending/sh/sherpa-onnx cd sherpa-onnx/python-api-examples

选模型：不同模型在语种、音质和体积上各有取舍，按下表挑一个下载即可（各语言示例里都带了对应的下载脚本）。

最小可运行：不写代码也能先跑通。以中文 Matcha 为例，先下载模型与声码器，再调用 示例脚本：

python3 ./python-api-examples/offline-tts.py \ --matcha-acoustic-model=./matcha-icefall-zh-baker/model-steps-3.onnx \ --matcha-vocoder=./vocos-22khz-univ.onnx \ --matcha-lexicon=./matcha-icefall-zh-baker/lexicon.txt \ --matcha-tokens=./matcha-icefall-zh-baker/tokens.txt \ --tts-rule-fsts=./matcha-icefall-zh-baker/phone.fst,./matcha-icefall-zh-baker/date.fst,./matcha-icefall-zh-baker/number.fst \ --output-filename=./out.wav \ "今天天气不错，我们一起去公园散步吧。"

跑完会看到一段文本和实时因子(RTF)，out.wav里就是合成结果。

核心 API 走读

命令行之外，自己写应用时直接用 Python 绑定即可，核心只有四步：配置、实例化、生成、保存。

import sherpa_onnx import soundfile as sf config = sherpa_onnx.OfflineTtsConfig( model=sherpa_onnx.OfflineTtsModelConfig( matcha=sherpa_onnx.OfflineTtsMatchaModelConfig( acoustic_model="./matcha-icefall-zh-baker/model-steps-3.onnx", vocoder="./vocos-22khz-univ.onnx", lexicon="./matcha-icefall-zh-baker/lexicon.txt", tokens="./matcha-icefall-zh-baker/tokens.txt", ), num_threads=2, # 并行线程数 provider="cpu", # 可选 cpu / cuda / coreml ), rule_fsts="./matcha-icefall-zh-baker/phone.fst," "./matcha-icefall-zh-baker/date.fst," "./matcha-icefall-zh-baker/number.fst", ) tts = sherpa_onnx.OfflineTts(config) gen = sherpa_onnx.GenerationConfig() gen.sid = 0 # 说话人 ID gen.speed = 1.0 # 语速 gen.silence_scale = 0.2 # 停顿缩放 audio = tts.generate("欢迎使用 Sherpa-ONNX 语音合成。", gen) sf.write("./out.wav", audio.samples, samplerate=audio.sample_rate, subtype="PCM_16") print("时长(秒):", len(audio.samples) / audio.sample_rate)

几个关键参数：num_threads控制神经网络并行度，线程越多通常越快但受 CPU 上限；provider指定推理后端，无 GPU 就保持cpu；rule_fsts是中文文本规整规则，把数字、日期读对，缺了它中文数字会念得不自然；generate返回的audio.samples是浮点采样、audio.sample_rate是采样率，交给soundfile存盘即可。换 VITS/Kokoro/Kitten 模型时，只需把matcha=换成对应的vits=/kokoro=/kitten=配置块，其余流程不变。

各平台接入要点

Android在android/SherpaOnnxTts/下有现成工程，模型文件放进assets或下载后放到内部存储，注意在AndroidManifest声明录音/存储权限。内存紧张时优先选量化(fp16/int8)模型版本，播放生命周期要和 Activity 绑定，避免退出后残留占用。

iOS / macOSSwift 侧参考ios-swiftui/SherpaOnnxTts/，用 Pod 或 SwiftPM 引入共享库。模型路径建议放 Bundle 或 Documents 目录并先检查存在性；iOS 上可用coreml后端加速，但要先确认模型已转成对应版本。

Windows / Linux 桌面桌面用 Python 或 C++ 都方便，Linux 下provider可选cuda走 GPU。路径用绝对路径或相对仓库根的路径即可，跨平台打包时注意把模型文件随程序一起分发。

嵌入式 / 树莓派 / RISC-V资源受限设备把num_threads降到 1，选 Kitten 或 int8 量化模型，必要时裁剪到只保留 TTS 功能以减小二进制体积。

调参速查表

常见坑

• 合成结果是空文件或没声音？先确认所有.onnx、lexicon.txt、tokens.txt路径都对、文件下载完整，Matcha 还要求声码器vocos一并存在。
• 中文数字、日期读得不自然？忘了配rule_fsts，补上phone.fst/date.fst/number.fst后再合成。
• RTF 大于 1（比实时还慢）？减少线程数、换更小或量化模型，或在有 GPU 的机器上切到cuda后端。
• 中英混排读岔了？检查所选模型是否支持多语言，Kokoro 多语言版还需额外指定lexicon里的对应语言词典。

进阶方向

跑通基础后，可以试 边合成边播放脚本 降低首包延迟；按内容语种搭配不同模型（英文走 Kitten、纯中文走 VITS、混排走 Kokoro）以提升音质与速度平衡；还想让音色随参考音频变化，可看 零样本 TTS 示例。模型侧的转换与导出流程在 scripts/matcha-tts/、scripts/kokoro/等目录里有配套脚本。

先挑一个最贴近你项目的模型，把上面的最小例子改成自己的文本跑一遍，再按速查表微调sid和speed，几分钟就能得到一条可用的语音合成流水线。

【免费下载链接】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