Sherpa语音框架实战：5分钟搞定跨平台语音识别部署（含Python示例）

最近在折腾一个智能家居的语音控制模块，需要在树莓派和安卓手机上都能跑起来，还要兼顾实时性。试了一圈，从传统的Kaldi到一些云服务方案，要么部署起来像在解一道复杂的数学题，要么对网络依赖太强。直到发现了Sherpa，这个由K2-FSA团队推出的框架，它给我的第一印象是“清爽”——没有冗长的依赖链，预置的模型开箱即用，跨平台支持做得相当到位。如果你也是一个需要在不同设备上快速集成语音识别（ASR）功能的开发者，无论是做实时字幕、语音助手，还是嵌入式设备的离线语音交互，这篇文章或许能帮你省下不少摸索的时间。我们不谈空洞的理论，直接从环境搭建、模型选择到代码实战，一步步拆解如何用Sherpa在5分钟内跑起一个可用的语音识别demo。

1. 环境准备与框架选择

在开始写代码之前，选对“兵器”很重要。Sherpa不是一个单一的库，而是一个针对不同部署场景优化过的项目集合。直接pip install sherpa可能会让你困惑，因为你需要根据目标平台和性能需求，从三个核心子项目中做出选择。

首先，确保你的基础环境就绪。推荐使用Python 3.8或以上版本，并创建一个独立的虚拟环境，避免包冲突。

# 创建并激活虚拟环境（以Linux/macOS为例）
python3 -m venv sherpa-env
source sherpa-env/bin/activate

# 对于Windows用户
# python -m venv sherpa-env
# sherpa-env\Scripts\activate

接下来就是关键的选择环节了。Sherpa提供了三个主要的推理后端，它们决定了你的应用将在何种引擎上运行：

子项目名称核心推理引擎适用平台与场景特点简述
sherpaPyTorchLinux, Windows, macOS (开发/研究/服务器)功能最全，支持最新的流式模型（如Zipformer），方便进行模型实验和微调。
sherpa-onnxONNX Runtime全平台 (包括Android, iOS, Raspberry Pi)跨平台之王，通过ONNX模型格式实现一次导出，多处运行。性能均衡，社区模型支持广。
sherpa-ncnnNCNN资源受限的嵌入式/移动端 (Android, ARM Linux)极致轻量，模型体积小，纯CPU推理效率高，专为离线、低功耗场景优化。

提示：如果你是第一次接触，并且希望在个人电脑（Windows/Linux/macOS）上快速验证效果，我强烈推荐从 sherpa-onnx 开始。它平衡了易用性和跨平台能力，后续迁移到移动端也最平滑。

根据你的选择进行安装。这里以sherpa-onnx为例，因为它最能体现“5分钟部署”的主题：

pip install sherpa-onnx

这个命令会自动安装sherpa-onnx及其依赖（包括ONNX Runtime）。安装过程通常很顺利。如果你想体验更前沿的流式识别模型，可以尝试安装PyTorch版本的sherpa，但请注意它可能需要额外的PyTorch环境配置。

2. 获取与理解预训练模型

框架装好了，接下来需要“大脑”——也就是语音识别模型。Sherpa的强大之处在于它提供了官方预训练的、开箱即用的模型，我们无需从头训练。模型通常以.onnx或.pt文件格式提供，包含了编码器、解码器、joiner等组件。

官方模型库是首选的起点。你可以从Sherpa项目的GitHub Release页面或相关文档中找到模型下载链接。一个典型的用于非流式（即整段音频一次性识别）的中英文识别模型包可能包含以下文件：

# 模型文件示例
sherpa-onnx-streaming-zipformer-bilingual-zh-en-2024-08-19/
├── encoder-epoch-99-avg-1.onnx
├── decoder-epoch-99-avg-1.onnx
├── joiner-epoch-99-avg-1.onnx
├── tokens.txt
└── words.txt
  • encoder.onnx, decoder.onnx, joiner.onnx：这三个是核心的神经网络组件文件，构成了识别模型的主体。
  • tokens.txt：这是建模单元（如中文汉字、英文字母、子词）的词汇表。识别结果最初会以这些“令牌”（token）的ID序列输出。
  • words.txt：可选文件。如果提供，框架会将token ID序列映射回可读的单词或汉字序列。对于中英文混合模型，这个词表会同时包含中文汉字和英文单词。

注意：务必根据你安装的Sherpa变体（sherpa-onnx 或 sherpa-ncnn）下载对应格式的模型。sherpa-onnx使用.onnx格式模型，而sherpa-ncnn使用特定的.param和.bin格式模型。官方提供的模型通常都已适配好。

除了官方模型，Sherpa-onnx还有一个巨大的优势：它能够直接运行大量现有的ONNX格式语音模型。例如，你可以将Hugging Face上热门的Whisper模型转换为ONNX格式后，直接使用Sherpa-onnx进行推理。这极大地扩展了其应用范围。

为了方便演示，我们可以先使用一个Sherpa-onnx内置的、无需额外下载的微型测试模型，或者从官方示例中找到一个明确可用的模型URL进行体验。在实际项目中，你需要根据识别语言（中/英/双语）、是否需要流式识别、对精度和速度的权衡来选择最合适的模型。

3. 编写第一个识别脚本：从文件到文字

现在，让我们进入最激动人心的环节——写代码。我们将创建一个Python脚本，读取一个WAV音频文件，并输出识别出的文字。以下是一个完整且可运行的示例：

#!/usr/bin/env python3
"""
Sherpa-onnx 非流式语音识别示例
用于一次性识别整个音频文件。
"""
import sherpa_onnx
import soundfile as sf  # 用于读取音频文件
import sys

def recognize_from_file(model_dir, audio_filename):
    """
    对单个音频文件进行识别
    Args:
        model_dir: 包含 encoder.onnx, decoder.onnx 等模型文件的目录路径
        audio_filename: 要识别的.wav文件路径
    """
    # 1. 创建识别器配置
    recognizer_config = sherpa_onnx.OfflineRecognizerConfig(
        # 指定模型文件路径
        model=sherpa_onnx.OfflineModelConfig(
            transducer=sherpa_onnx.OfflineTransducerModelConfig(
                encoder=model_dir + "/encoder-epoch-99-avg-1.onnx",
                decoder=model_dir + "/decoder-epoch-99-avg-1.onnx",
                joiner=model_dir + "/joiner-epoch-99-avg-1.onnx",
            )
        ),
        # 指定词汇表文件
        tokens=model_dir + "/tokens.txt",
        # 如果存在words.txt，也指定上，用于输出汉字/单词
        decoding_method="greedy_search",  # 解码方式，贪心搜索速度最快
        num_threads=4,  # 推理使用的线程数，根据CPU核心数调整
    )

    # 2. 初始化识别器
    recognizer = sherpa_onnx.OfflineRecognizer(recognizer_config)

    # 3. 读取音频文件
    # 注意：sherpa-onnx 要求音频为单声道，采样率16kHz
    audio, sample_rate = sf.read(audio_filename)
    if audio.ndim > 1:
        audio = audio[:, 0]  # 取第一个声道转为单声道
    if sample_rate != 16000:
        # 此处简化处理，实际应用中应使用librosa等库进行重采样
        print(f"警告：音频采样率为{sample_rate}Hz，非16kHz，可能影响识别精度。")
        # 这里假设音频已经是16kHz，否则需要重采样代码

    # 4. 执行识别
    stream = recognizer.create_stream()
    stream.accept_waveform(sample_rate, audio)
    recognizer.decode(stream)
    result = stream.result.text

    # 5. 输出结果
    print(f"音频文件: {audio_filename}")
    print(f"识别结果: {result}")
    print("-" * 50)
    return result

if __name__ == "__main__":
    # 参数配置：请根据实际情况修改
    # 假设你的模型文件存放在当前目录的 `model` 文件夹下
    MODEL_DIR = "./model"
    # 假设你的测试音频文件名为 `test.wav`
    AUDIO_FILE = "test.wav"

    # 执行识别
    try:
        text = recognize_from_file(MODEL_DIR, AUDIO_FILE)
    except FileNotFoundError as e:
        print(f"错误：未找到文件。请确保模型目录{MODEL_DIR}和音频文件{AUDIO_FILE}存在。")
        print(f"详细错误: {e}")
        sys.exit(1)
    except Exception as e:
        print(f"识别过程中发生未知错误: {e}")
        sys.exit(1)

把上面的代码保存为recognize_file.py。在运行前，你需要准备两件事：

  1. 模型：从Sherpa-onnx的GitHub仓库下载一个预训练的中英文模型（例如sherpa-onnx-streaming-zipformer-bilingual-zh-en-2024-08-19.tar.bz2），解压后将其中的文件夹重命名为model，并放在与脚本相同的目录下。
  2. 音频：录制或准备一个内容为“今天天气怎么样”的WAV文件，命名为test.wav，确保是单声道、16kHz采样率，也放在脚本目录下。

然后在终端运行：

python recognize_file.py

如果一切顺利，你将在几秒内看到终端打印出识别出的文字。这个过程涵盖了加载模型、读取音频、前向推理和解码的完整流程。第一次成功运行的瞬间，那种“通了”的感觉，正是快速部署工具带来的最大快乐。

4. 实现流式识别与实时交互

文件识别适用于录音转文字，但对于语音助手、实时字幕这类场景，我们需要流式识别——也就是用户一边说，系统一边出文字。Sherpa在流式识别上的设计非常优雅，它采用了“接收若干音频帧，立即解码”的机制，延迟可以控制在几百毫秒内。

实现流式识别的代码结构与离线识别类似，但核心对象和调用流程有所不同。下面我们构建一个模拟实时音频流的示例：从一个长音频文件中，以“块”（chunk）的形式模拟实时读取并送入识别器。

#!/usr/bin/env python3
"""
Sherpa-onnx 流式语音识别模拟示例
模拟从麦克风或网络流中实时读取音频块并进行识别。
"""
import sherpa_onnx
import soundfile as sf
import numpy as np
import time

def simulate_streaming_recognition(model_dir, audio_filename, chunk_duration_ms=500):
    """
    模拟流式识别：将长音频文件切分成小块，模拟实时输入。
    Args:
        model_dir: 模型目录
        audio_filename: 长音频文件
        chunk_duration_ms: 每次送入识别的音频块时长（毫秒）
    """
    # 1. 配置流式识别器 (注意这里使用 OnlineRecognizerConfig)
    recognizer_config = sherpa_onnx.OnlineRecognizerConfig(
        model=sherpa_onnx.OnlineModelConfig(
            transducer=sherpa_onnx.OnlineTransducerModelConfig(
                encoder=model_dir + "/encoder-epoch-99-avg-1.onnx",
                decoder=model_dir + "/decoder-epoch-99-avg-1.onnx",
                joiner=model_dir + "/joiner-epoch-99-avg-1.onnx",
            )
        ),
        tokens=model_dir + "/tokens.txt",
        decoding_method="greedy_search",
        max_active_paths=4,  # 流式解码相关参数，影响精度和速度
        num_threads=4,
        enable_endpoint_detection=True,  # 启用端点检测，用于判断一句话是否结束
        # 端点检测参数（可根据实际情况调整）
        endpoint_config=sherpa_onnx.EndpointConfig(
            rule1=sherpa_onnx.EndpointRule(
                must_contain_nonsilence=True,
                min_trailing_silence=2.0,  # 尾部静音至少2秒则判定一句话结束
            ),
            rule2=sherpa_onnx.EndpointRule(
                must_contain_nonsilence=False,
                min_trailing_silence=0.8,  # 用于快速响应的规则
            ),
        )
    )

    # 2. 初始化流式识别器
    recognizer = sherpa_onnx.OnlineRecognizer(recognizer_config)

    # 3. 读取音频并计算块大小
    audio, sample_rate = sf.read(audio_filename)
    if audio.ndim > 1:
        audio = audio[:, 0]
    # 计算每个音频块的样本数
    samples_per_chunk = int(sample_rate * chunk_duration_ms / 1000)

    # 4. 创建流对象并开始模拟
    stream = recognizer.create_stream()
    print("开始模拟流式识别... (按Ctrl+C中断)")
    print("-" * 50)

    total_samples = len(audio)
    for start in range(0, total_samples, samples_per_chunk):
        end = min(start + samples_per_chunk, total_samples)
        audio_chunk = audio[start:end]

        # 将当前音频块送入流
        stream.accept_waveform(sample_rate, audio_chunk.tolist())

        # 识别器进行解码
        recognizer.decode(stream)

        # 获取当前中间结果
        partial_result = stream.result.text
        is_endpoint = recognizer.is_endpoint(stream)  # 检查是否到达一句话的端点

        # 打印当前结果
        if partial_result:
            print(f"\r中间结果: {partial_result}", end='', flush=True)

        # 如果检测到端点，则输出最终结果并重置流以准备下一句
        if is_endpoint:
            final_result = stream.result.text
            if final_result:
                print(f"\n>>> 句子完成: {final_result}\n")
            # 重置流，开始识别下一句话
            stream = recognizer.create_stream()

        # 模拟实时等待，与实际录音节奏一致
        time.sleep(chunk_duration_ms / 1000.0)

    # 处理音频末尾可能未触发端点检测的剩余内容
    recognizer.decode(stream)
    final_result = stream.result.text
    if final_result:
        print(f"\n>>> 最终结果: {final_result}")

if __name__ == "__main__":
    MODEL_DIR = "./model"
    LONG_AUDIO = "long_conversation.wav"  # 准备一个包含多句话的长音频
    simulate_streaming_recognition(MODEL_DIR, LONG_AUDIO, chunk_duration_ms=300)

这段代码的关键点在于：

  • OnlineRecognizer 与 OnlineModelConfig：专门用于流式识别的配置类。
  • create_stream()：为每一段独立的音频流（例如一个用户的对话会话）创建一个上下文。
  • accept_waveform 与循环调用 decode：持续喂入音频数据并即时解码，获取partial_result（中间结果）。
  • 端点检测 (Endpoint Detection)：通过enable_endpoint_detection和相关参数配置，让识别器能自动判断用户何时说完一句话，从而输出final_result并重置流。这对于构建自然的对话交互至关重要。

将这个脚本保存为streaming_simulate.py并运行，你会看到文字随着模拟的“实时”音频输入而逐步出现和修正，最终在检测到静音后整句输出。将这里的模拟循环替换为从PyAudio等库获取的真实麦克风数据流，你就拥有了一个完整的实时语音识别应用核心。

5. 跨平台部署实战与性能调优

让代码在开发机上跑起来只是第一步，真正的挑战在于将它部署到各种目标设备上，并保持良好的性能。Sherpa的核心优势就在这里体现。

Android平台部署（以sherpa-onnx为例） 在Android上使用Sherpa-onnx，通常通过JNI（Java Native Interface）调用其C++库。官方提供了Android示例项目。大致步骤是：

  1. 将编译好的sherpa-onnx的C++共享库（.so文件）和对应的ONNX模型文件放入Android项目的jniLibs和assets目录。
  2. 在Java代码中加载原生库，并调用封装好的识别函数。
  3. 实时从Android的AudioRecord获取音频数据，传递给原生层处理。

一个简化的工作流程示意如下（伪代码）：

// Java层
public class SherpaAsrHelper {
    static {
        System.loadLibrary("sherpa-onnx-jni"); // 加载JNI库
    }
    private native long createRecognizer(String modelPath);
    private native void acceptWaveform(long ptr, float[] samples);
    private native String getResult(long ptr);
    private native void reset(long ptr);

    public void processAudioBuffer(short[] pcmData) {
        // 将short[]转换为float[]，并调用native方法
        float[] floatSamples = convertToFloat(pcmData);
        acceptWaveform(nativeHandle, floatSamples);
        String partialText = getResult(nativeHandle);
        // 更新UI...
    }
}

树莓派（Raspberry Pi）部署 在树莓派这类ARM设备上，直接使用Python版的sherpa-onnx是最快捷的方式。需要注意的是：

  • 使用pip install sherpa-onnx时，它会自动选择适用于ARM架构的ONNX Runtime轮子包。
  • 树莓派算力有限，建议选择更轻量级的模型（如Paraformer-small），或者使用sherpa-ncnn搭配其专用模型。
  • 关注内存占用。可以通过在创建识别器时设置num_threads=2或1来避免过度占用CPU资源。

性能调优技巧 无论部署在何处，以下几点都能有效提升体验：

  • 模型选择是根本：在精度可接受的范围内，选择更小、更快的模型。对于嵌入式设备，sherpa-ncnn提供的量化模型（INT8）通常是首选。
  • 调整解码参数：
    • decoding_method："greedy_search"最快，"modified_beam_search"精度更高但稍慢。
    • max_active_paths（束搜索宽度）：数值越大，搜索越充分，精度可能提升，但耗时增加。
  • 利用多线程：确保num_threads设置合理，通常设为设备CPU的物理核心数。
  • 音频预处理：务必保证输入音频是模型要求的格式（16kHz，单声道）。在麦克风采集端可以加入简单的噪声抑制或VAD（语音活动检测），只将有声音的片段送入识别器，能大幅减少无效计算。
  • 缓存识别器实例：在服务端部署时，避免为每个请求都重新加载模型。应该初始化一个全局的识别器实例，供多个并发请求复用（注意线程安全）。

我在一个树莓派4B的项目中，使用sherpa-ncnn的量化模型，实现了平均300毫秒以内的端到端识别延迟，完全满足了离线语音控制的需求。关键就在于选对了工具链（ncnn）和模型（量化版），并关闭了所有非必要的计算特性。

从桌面到云端，从手机到单片机，Sherpa通过其多样化的子项目和统一的接口设计，确实大幅降低了语音识别落地的复杂度。它没有试图解决所有问题，而是在“高效部署”这个痛点上做到了极致。当你下次再被语音识别项目的交叉编译、依赖冲突搞得焦头烂额时，不妨试试Sherpa，那5分钟的部署体验，可能会让你改变看法。

# 语音识别
Logo
乐奇 Rokid 开放社区

更多推荐

cover

AI眼镜的赢家不在硅谷，在一个县城

avatar 乐奇 Rokid 开放社区
cover

ChatGPT流量不到Google的1%，机会在智能体搜索

avatar 乐奇 Rokid 开放社区
cover

极刻觅镜 | AI眼镜日报｜智能眼镜日报：XREAL AURA发布、参议员质询Meta隐私

avatar 乐奇 Rokid 开放社区