sherpa-onnx API完全手册：开发者必备工具

【免费下载链接】sherpa-onnx k2-fsa/sherpa-onnx: Sherpa-ONNX 项目与 ONNX 格式模型的处理有关，可能涉及将语音识别或者其他领域的模型转换为 ONNX 格式，并进行优化和部署。 项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx

1. 项目概述

Sherpa-ONNX是一个基于ONNX（Open Neural Network Exchange）格式的语音识别工具包，提供跨平台、高性能的语音处理能力。它支持多种语音识别模型（如Transducer、Paraformer、Whisper等），并提供多语言API接口，适用于从嵌入式设备到云端服务器的各种应用场景。

2. 核心API架构

Sherpa-ONNX提供两类核心识别器：离线识别器（OfflineRecognizer）和流式识别器（OnlineRecognizer），分别针对不同应用场景。

2.1 离线识别器（OfflineRecognizer）

离线识别器适用于处理完整音频文件，支持多种模型类型，通过不同的工厂方法初始化：

模型类型	Python构造方法	C++构造方法	典型应用
Transducer	from_transducer()	OfflineRecognizer::Create(config)	高精度语音转写
Paraformer	from_paraformer()	OfflineRecognizer::Create(config)	实时性要求高的场景
Whisper	from_whisper()	OfflineRecognizer::Create(config)	多语言识别与翻译
NeMo CTC	from_nemo_ctc()	OfflineRecognizer::Create(config)	轻量级部署
SenseVoice	from_sense_voice()	OfflineRecognizer::Create(config)	中文优化模型

Python初始化示例（Transducer模型）：

import sherpa_onnx

recognizer = sherpa_onnx.OfflineRecognizer.from_transducer(
    encoder="/path/to/encoder.onnx",
    decoder="/path/to/decoder.onnx",
    joiner="/path/to/joiner.onnx",
    tokens="/path/to/tokens.txt",
    num_threads=4,
    decoding_method="modified_beam_search",
    max_active_paths=4,
    hotwords_file="/path/to/hotwords.txt",
    hotwords_score=1.5,
    provider="cpu",  # 或 "cuda" 启用GPU加速
)

2.2 流式识别器（OnlineRecognizer）

流式识别器支持实时音频流处理，适用于麦克风输入、实时会议转录等场景：

C++初始化示例：

#include "sherpa-onnx/cxx/online-recognizer.h"

sherpa_onnx::OnlineRecognizerConfig config;
config.model_config.encoder = "/path/to/encoder.onnx";
config.model_config.decoder = "/path/to/decoder.onnx";
config.model_config.joiner = "/path/to/joiner.onnx";
config.model_config.tokens = "/path/to/tokens.txt";
config.model_config.provider = "cpu";  // GPU: "cuda"
config.enable_endpoint_detection = true;
config.rule1_min_trailing_silence = 2.4;
config.rule2_min_trailing_silence = 1.2;
config.rule3_min_utterance_length = 20.0;

auto recognizer = sherpa_onnx::OnlineRecognizer::Create(config);
auto stream = recognizer->CreateStream();

3. 多语言API详解

3.1 Python API

Python API提供简洁的高层接口，适合快速开发和原型验证。

3.1.1 离线文件识别流程

# 1. 初始化识别器
recognizer = sherpa_onnx.OfflineRecognizer.from_whisper(
    encoder="/path/to/whisper-encoder.onnx",
    decoder="/path/to/whisper-decoder.onnx",
    tokens="/path/to/tokens.txt",
    language="zh",
    task="transcribe",
)

# 2. 读取音频文件
def read_wav(filename):
    with wave.open(filename, 'rb') as f:
        # 音频读取逻辑...
        return samples, sample_rate

# 3. 创建流并处理
streams = []
for filename in ["audio1.wav", "audio2.wav"]:
    samples, sample_rate = read_wav(filename)
    stream = recognizer.create_stream()
    stream.accept_waveform(sample_rate, samples)
    streams.append(stream)

# 4. 批量解码
recognizer.decode_streams(streams)

# 5. 获取结果
for stream in streams:
    print(stream.result.text)

3.1.2 麦克风实时识别

import sounddevice as sd

recognizer = sherpa_onnx.OnlineRecognizer.from_paraformer(
    encoder="/path/to/encoder.onnx",
    decoder="/path/to/decoder.onnx",
    tokens="/path/to/tokens.txt",
    enable_endpoint_detection=True,
)

stream = recognizer.create_stream()
sample_rate = 16000
block_size = 160  # 10ms

def callback(indata, frames, time, status):
    stream.accept_waveform(sample_rate, indata[:, 0])
    if recognizer.is_ready(stream):
        recognizer.decode_stream(stream)
    if recognizer.is_endpoint(stream):
        print(stream.result.text)
        recognizer.reset(stream)

with sd.InputStream(samplerate=sample_rate, channels=1, callback=callback, blocksize=block_size):
    while True:
        pass

3.2 C++ API

C++ API提供底层控制能力，适合高性能嵌入式部署。

3.2.1 流式识别核心逻辑

#include <iostream>
#include "sherpa-onnx/cxx/online-recognizer.h"

int main() {
    // 配置初始化
    sherpa_onnx::OnlineRecognizerConfig config;
    // ... 配置参数设置 ...

    auto recognizer = sherpa_onnx::OnlineRecognizer::Create(config);
    auto stream = recognizer->CreateStream();

    // 模拟音频流输入
    float sample_rate = 16000;
    std::vector<float> samples(16000);  // 1秒音频

    stream->AcceptWaveform(sample_rate, samples.data(), samples.size());
    
    while (recognizer->IsReady(stream.get())) {
        recognizer->DecodeStream(stream.get());
    }

    if (recognizer->IsEndpoint(stream.get())) {
        auto result = recognizer->GetResult(stream.get());
        std::cout << result.text << std::endl;
        recognizer->Reset(stream.get());
    }

    return 0;
}

3.3 Java API

Java API适合Android平台集成，提供面向对象的接口设计：

import com.k2fsa.sherpa.onnx.*;

public class SherpaOnnxDemo {
    public static void main(String[] args) {
        OfflineRecognizerConfig config = OfflineRecognizerConfig.builder()
            .setModelPath("sense-voice-model")
            .setTokensPath("tokens.txt")
            .setNumThreads(2)
            .build();

        OfflineRecognizer recognizer = new OfflineRecognizer(config);
        OfflineStream stream = recognizer.createStream();
        
        // 读取音频数据
        float[] samples = readAudio("test.wav");
        stream.acceptWaveform(16000, samples);
        
        recognizer.decodeStream(stream);
        OfflineRecognizerResult result = stream.getResult();
        System.out.println(result.text);
    }
}

4. 高级功能配置

4.1 热词增强

通过hotwords_file和hotwords_score参数提升特定词汇识别率：

# 热词文件格式: 每行一个词和权重，如:
# 人工智能 2.0
# 机器学习 1.8

recognizer = sherpa_onnx.OfflineRecognizer.from_transducer(
    # ... 基础配置 ...
    hotwords_file="hotwords.txt",
    hotwords_score=1.5,
    modeling_unit="cjkchar",  # 针对中文优化
)

4.2 端点检测

流式识别中通过端点检测自动断句：

config.enable_endpoint_detection = true;
config.rule1_min_trailing_silence = 2.4;  // 规则1: 尾部静音2.4秒
config.rule2_min_trailing_silence = 1.2;  // 规则2: 短静音1.2秒
config.rule3_min_utterance_length = 20.0; // 规则3: 最小语音长度20秒

4.3 多线程与硬件加速

配置示例：

# 使用CUDA加速
recognizer = sherpa_onnx.OnlineRecognizer.from_transducer(
    # ... 模型配置 ...
    provider="cuda",
    device=0,  # 指定GPU设备
    trt_max_workspace_size=2147483647,  # TensorRT工作空间
)

5. 环境配置与安装

5.1 编译依赖

依赖项	版本要求	作用
CMake	≥3.18	构建系统
ONNX Runtime	≥1.14.0	推理引擎
PyBind11	≥2.6.0	Python绑定
PortAudio	≥19.6.0	音频输入

5.2 源码编译

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/sh/sherpa-onnx
cd sherpa-onnx

# 构建
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

# Python安装
cd ..
pip install .

5.3 预编译包安装

# PyPI
pip install sherpa-onnx

# conda
conda install -c conda-forge sherpa-onnx

6. 性能优化指南

6.1 模型优化

• 使用量化模型（如INT8）减少内存占用
• 调整num_threads参数（建议设置为CPU核心数的1/2）
• 流式模型选择较小的chunk_size平衡延迟与精度

6.2 实时性调优

6.3 内存管理

• 批量处理音频时复用Stream对象
• 大模型使用provider="cuda"释放CPU内存
• 定期清理不再使用的识别器实例

7. 常见问题解决

7.1 模型加载失败

• 检查ONNX Runtime版本兼容性
• 验证模型文件路径与完整性
• 确保tokens.txt与模型匹配

7.2 识别精度问题

• 调整decoding_method（modified_beam_search精度更高）
• 使用语言模型（--lm参数）进行重打分
• 检查音频采样率是否为16000Hz

7.3 跨平台兼容性

• Windows: 确保Visual C++运行时已安装
• Android: 使用NDK r23以上版本编译
• iOS: 禁用Bitcode并链接Accelerate框架

8. 完整代码示例

8.1 Python离线批量识别

import wave
import numpy as np
import sherpa_onnx

def main():
    # 模型配置
    recognizer = sherpa_onnx.OfflineRecognizer.from_whisper(
        encoder="whisper-encoder.onnx",
        decoder="whisper-decoder.onnx",
        tokens="tokens.txt",
        language="zh",
        task="transcribe",
        num_threads=4,
    )

    # 处理多个文件
    for filename in ["audio1.wav", "audio2.wav"]:
        with wave.open(filename) as f:
            samples = np.frombuffer(f.readframes(-1), np.int16).astype(np.float32) / 32768
            sample_rate = f.getframerate()

        stream = recognizer.create_stream()
        stream.accept_waveform(sample_rate, samples)
        recognizer.decode_stream(stream)
        print(f"{filename}: {stream.result.text}")

if __name__ == "__main__":
    main()

8.2 C++流式麦克风识别

#include <iostream>
#include "sherpa-onnx/cxx/online-recognizer.h"
#include "sherpa-onnx/cxx/alsa.h"

int main() {
    sherpa_onnx::OnlineRecognizerConfig config;
    // ... 配置参数 ...

    auto recognizer = sherpa_onnx::OnlineRecognizer::Create(config);
    auto stream = recognizer->CreateStream();

    sherpa_onnx::Alsa alsa("default", 16000, 1);
    alsa.Start();

    const int32_t block_size = 160;  // 10ms
    std::vector<float> samples(block_size);

    while (true) {
        alsa.Read(block_size, samples.data());
        stream->AcceptWaveform(16000, samples.data(), block_size);

        if (recognizer->IsReady(stream.get())) {
            recognizer->DecodeStream(stream.get());
        }

        if (recognizer->IsEndpoint(stream.get())) {
            auto result = recognizer->GetResult(stream.get());
            std::cout << result.text << std::endl;
            recognizer->Reset(stream.get());
        }
    }

    return 0;
}

9. 总结与展望

Sherpa-ONNX通过统一的API接口简化了语音识别技术的落地应用，支持从嵌入式设备到云端服务器的全场景部署。未来版本将重点提升：

• 多模态交互能力（语音+视觉）
• 低资源语言模型支持
• 端到端语音理解功能

收藏本文档，关注项目更新，获取最新API特性与最佳实践指南！

---

相关资源：

• 官方示例库：python-api-examples/ cxx-api-examples/
• 模型下载：https://gitcode.com/GitHub_Trending/sh/sherpa-onnx/releases
• 技术交流：项目Issue与Discussions板块

【免费下载链接】sherpa-onnx k2-fsa/sherpa-onnx: Sherpa-ONNX 项目与 ONNX 格式模型的处理有关，可能涉及将语音识别或者其他领域的模型转换为 ONNX 格式，并进行优化和部署。 项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx