企业官网建设流程全解析

sherpa-onnx 离线语音合成：10 行代码生成自然语音，一套代码跑遍六大平台

【免费下载链接】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 的离线语音工具链，其中 TTS（文本转语音）部分不需要联网，把文本变成可播放的 wav 音频。它用同一套 C++ 核心对外提供 Python、Java、Swift、Go 等 12 种语言接口，预构建示例覆盖了 Android、iOS、HarmonyOS、Windows、macOS、Linux 六类系统，还能在 RK NPU、Ascend NPU 等嵌入式硬件上运行。

它能帮你解决什么

调用云端 TTS 接口的应用，一断网或一超流量，朗读功能就直接失效；而 sherpa-onnx 把模型放在本地，全程不依赖网络，也省掉按量计费。

同一个项目要同时交付手机和桌面端时，通常要为每个平台对接不同的 TTS SDK，行为还互相不一致；这里所有平台共用同一个推理内核，只换语言绑定，合成结果各端一致。

目标设备是树莓派、RK3588、RISC-V 这类资源受限的机器时，商业 TTS 服务基本覆盖不到；它原生支持 arm32/arm64/x86/RISC-V，并提供多品牌 NPU 加速路径。

和"浏览器内置 SpeechSynthesis"或"单个 Python 模型脚本"这类方案相比，差异点在于它同时交付推理库、模型矩阵和全平台示例工程，选型的重点从"能不能跑"变成"选哪个模型"。

5 分钟跑通第一个 Demo

环境准备，克隆仓库并安装 Python 包：

git clone https://gitcode.com/GitHub_Trending/sh/sherpa-onnx pip install sherpa-onnx

下载一个约 12MB 的 Piper 英语轻量模型：

cd sherpa-onnx && curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-amy-low.tar.bz2 && tar xf vits-piper-en_US-amy-low.tar.bz2

最小可运行代码（仓库里可直接跑 python-api-examples/offline-tts.py，命令行参数一一对应下面这些配置项）：

import sherpa_onnx, soundfile as sf config = sherpa_onnx.OfflineTtsConfig( model=sherpa_onnx.OfflineTtsModelConfig( vits=sherpa_onnx.OfflineTtsVitsModelConfig( model="./vits-piper-en_US-amy-low/en_US-amy-low.onnx", tokens="./vits-piper-en_US-amy-low/tokens.txt", data_dir="./vits-piper-en_US-amy-low/espeak-ng-data", # espeak-ng 发音字典 ) ), num_threads=2, # 推理线程数；provider 默认 cpu，也支持 cuda/coreml ) tts = sherpa_onnx.OfflineTts(config) audio = tts.generate("Hello, this is sherpa-onnx.", sherpa_onnx.GenerationConfig(speed=1.0)) # speed 越大语速越快 sf.write("out.wav", audio.samples, audio.sample_rate) print(len(audio.samples) / audio.sample_rate) # 约 3~4 秒音频

预期输出：终端打印 "Saved to out.wav" 及 Elapsed seconds、Audio duration、RTF 三行指标，生成的 wav 用任意播放器打开即可听到女声朗读。下面这张图是官方 Web 端示例的运行界面（音频在浏览器里本地合成）：

浏览器端本地合成，无需后端

核心概念速查

最容易被忽略的是max_num_sentences：输入长文本时，默认值 1 会把文本拆句分批推理，这是防 OOM 的保护机制，不是性能瓶颈。源码注释明确说明在 CPU 上小值并不比大值更慢，所以长文本场景保持默认 1 即可，不必调大。

多端部署速查

Android 端预构建 APK 可直接安装体验，源码在 android/SherpaOnnxTts/：

Android 示例应用：输入文本、选择模型、本地合成

macOS 端是原生窗口应用，支持 arm64 与 x86_64：

macOS 端合成效果

Windows 与 Ubuntu（Linux）各有一个桌面示例，同一套模型文件可复用：

Windows 端合成界面

Ubuntu 端合成界面

选平台时的优先级建议：验证模型效果先用 Python 脚本，最快；需要同时交付移动端和桌面端就选 Flutter 示例工程，一套 Dart 代码多端复用；要嵌入既有产品再切对应语言的 API（C/C++/Java/Swift/Go）。

从 Demo 到生产：三个关键升级

升级 1：模型选型策略。判断依据只有一条：目标设备的内存和延迟预算。预算紧张（<1GB 可用内存、要 500ms 内出声）选 Kitten Nano fp16 这类量化小模型；中英文混排场景选 Kokoro 多语言版（python-api-examples/offline-tts.py 的 Example 7 参数就是现成配置）；追求中文音质选 Matcha 或 VITS 中文模型。完整模型清单在仓库 TTS 模型发布页，注意 Kokoro 有纯英语版和多语言版之分，选错会读不了另一种语言。

# 按场景选模型文件，配置结构不变，只换 model 字段 models = { "mobile": "kitten-nano-en-v0_1-fp16/model.fp16.onnx", # 轻量，量化 "mix-zh-en": "kokoro-multi-lang-v1_0/model.onnx", # 中英混读 "zh-hq": "matcha-icefall-zh-baker/model-steps-3.onnx", # 中文高音质 }

升级 2：性能调优。用 RTF（推理耗时 / 音频时长）作为验收指标，生产上要求 RTF < 1。移动端固定 1~2 线程避免抢核；桌面端 2~4 线程；长文本保持max_num_sentences=1分批，单批峰值内存可控制在几十 MB 量级。模型只加载一次并复用OfflineTts实例，重复 generate 不要再重建配置。

def tune(device): # 按设备类型给默认值，运行时用实测 RTF 覆盖 if device == "mobile": return dict(num_threads=1, max_num_sentences=1) # 省内存防抢占 return dict(num_threads=4, max_num_sentences=1) # 桌面端

升级 3：错误处理与降级。生产环境三个高频异常：一是模型文件缺失或路径不对，OfflineTts(config)构造直接抛异常，应在启动阶段加载并校验，失败就提示用户下载模型；二是长文本导致 OOM，按句分批并捕获异常；三是合成失败本身，generate返回len(audio.samples) == 0表示出错（仓库示例就是这么判断的），此时降级到系统自带 TTS 而不是让界面卡死。

try: audio = tts.generate(text, gen_config) if len(audio.samples) == 0: raise RuntimeError("empty audio") except Exception: system_speak(text) # 降级到 OS 自带 TTS，保证朗读功能不中断

高频踩坑排查

Q：合成出的 wav 是 0 秒或空文件？排查：打开debug=1看 stderr 报错；确认 tokens.txt / lexicon.txt 路径存在；确认输入文本语言与模型匹配。 根因：参数缺失或模型语言不匹配时，generate 不抛异常，而是返回空 samples。

Q：长文本合成时进程被 OOM Killer 杀掉？排查：把max_num_sentences从 -1 改回默认 1；检查是否整篇文档一次性传入。 根因：整段文本进单批推理，中间张量内存随文本长度线性增长。

Q：Kokoro 模型读中文没有声音？排查：确认下的是kokoro-multi-lang而不是kokoro-en；检查lexicon是否同时配了 us-en 和 zh 两个文件。 根因：kokoro-en版本只支持英语，中文需要多语言版。

Q：RTF 明显大于 1，合成比实时还慢？排查：num_threads降到 2 以内（开太多线程在核少的机器上反而更慢）；换 fp16/int8 量化模型；NPU 设备确认走对加速路径。 根因：模型参数量超出该 CPU 的单核吞吐能力，线程数未适配。

还能往哪走

音色克隆：python-api-examples/zipvoice-tts.py 和 python-api-examples/pocket-tts.py 展示了给一段参考音频就能复现该音色的零样本克隆用法，客服、有声书场景可以直接用。

跨端工程化：flutter-examples/tts/ 下lib/model_config.dart给了多模型切换的写法，配合generate-asset-list.py可以把任意 TTS 模型打进六个平台的安装包。

离线语音闭环：TTS 之外，VAD 端点检测、ASR 识别、声纹识别在同一套 API 里都有，python-api-examples/vad-with-non-streaming-asr.py 是"听音—识别"半边，接上 TTS 就是一个完全离线的语音助手。

模型文件选哪个拿不准，先去仓库 TTS 模型发布页的试听空间逐个试听，再回 python-api-examples/offline-tts.py 换参数验证，比看参数表可靠。

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