Skip to main content

Crate asr_core

Crate asr_core 

Source
Expand description

§asr-core

Crates.io Documentation CI License

嵌入 Rust 应用的语音识别库。统一文件与麦克风输入、会话结束、取消、分句、实时观察和错误处理。

当前文档对应 0.0.1。

已实现的适配器(真实环境验证状态见验证记录):

后端工作方式Feature
Zipformer transducer本地流式,中间结果与端点分句backend-sherpa
SenseVoice / Paraformer本地 VAD 切段后识别backend-sherpa,vad-silero
Offline transducer本地 VAD 切段后识别,支持热词backend-sherpa,vad-silero
Qwen3-ASR本地 LLM 识别(中英等多语言),支持热词backend-sherpa,vad-silero
FunASR-Nano本地 LLM 识别(中英日 + 中文方言),支持热词backend-sherpa,vad-silero
FireRedASR2(AED/CTC)本地 VAD 切段后识别(中英)backend-sherpa,vad-silero
DashScopeParaformer WebSocket 实时协议backend-dashscope
OpenAI 兼容 HTTP完整 WAV 上传;可选 JSON、text、SSEbackend-openai-http
HTTP 按句上传VAD 切段后依次上传backend-openai-http,vad-silero
OpenAI RealtimeGA 纯转写 WebSocket,24kHz PCMbackend-openai-realtime
默认麦克风F32/I16/U16,回调外批处理capture-cpal
音频文件解码WAV/FLAC/MP3/M4A(AAC)/OGG/WebM → 单声道 f32decode-symphonia
本地 OpenAI 兼容转写服务把 prepare 好的 Engine 暴露为 POST /v1/audio/transcriptionsserve-openai-http

§安装

默认 feature 为空;按实际后端显式启用,避免无意引入 CPAL、sherpa-onnx 或网络运行时:

[dependencies]
asr-core = { version = "0.0.1", features = ["backend-openai-http"] }

本地 sherpa-onnx + 麦克风:

[dependencies]
asr-core = { version = "0.0.1", default-features = false, features = ["backend-sherpa", "vad-silero", "capture-cpal"] }

DashScope:

[dependencies]
asr-core = { version = "0.0.1", default-features = false, features = ["backend-dashscope"] }

OpenAI Realtime:

[dependencies]
asr-core = { version = "0.0.1", default-features = false, features = ["backend-openai-realtime"] }

无 feature 的核心不引入 CPAL、sherpa-onnx 或网络运行时。模型资产由宿主显式准备;punct-sherpa 为本地后端提供可选标点恢复。文件转写默认只读 16-bit PCM WAV(audio::read_wav_pcm16),启用 decode-symphonia 后 audio::read_audio / audio::decode_audio(路径 / 字节入参)另外覆盖 FLAC / MP3 / M4A(AAC) / Ogg Vorbis / MKV-WebM 与 float、24-bit 等 WAV 变体——symphonia 没有 Opus 解码器,.opus 与 ogg-opus 不在其列。

§文件转写

use std::time::{Duration, Instant};
use asr_core::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let audio = audio::read_wav_pcm16("speech.wav")?;
    let engine = Engine::prepare(
        EngineConfig::OpenAiHttp(OpenAiHttpConfig::new(
            "https://api.openai.com/v1", "your-transcription-model",
            Secret::new(std::env::var("ASR_API_KEY")?),
        )),
        EngineOptions::default(),
    )?;
    let outcome = engine.transcribe(
        &audio,
        SessionOptions::new(audio.spec),
        Instant::now() + Duration::from_secs(60),
    )?;
    println!("{}", outcome.transcript.text());
    Ok(())
}

非 WAV 输入启用 decode-symphonia 后改用 audio::read_audio(字节已在内存里则用 audio::decode_audio),解码为原生采样率的单声道 f32(声道按帧平均,采样率对齐交给会话内重采样),格式由内容探测决定:

let audio = audio::read_audio("speech.mp3")?;

没有自动重试、协议猜测或后端回退。HTTP API 根地址可包含 /v1/ 和代理前缀,接口追加 audio/transcriptions。第三方需要实现音频协议,仅聊天接口兼容不够。配置不序列化密钥,Debug 输出也隐藏密钥。

§GPU / 硬件加速

本地流式与离线识别可通过 provider 选择执行设备,默认 cpu,旧 JSON 配置可继续使用:

use asr_core::{ExecutionProvider, StreamingConfig};
let mut config = StreamingConfig::new("/path/to/model");
config.provider = ExecutionProvider::Cuda; // NVIDIA;Apple 使用 CoreMl

OfflineConfig 使用相同字段;文件示例支持 --provider cpu|cuda|coreml。 CUDA 需要匹配的 GPU 原生库,启用 backend-sherpa-shared 并在构建前设置 SHERPA_ONNX_LIB_DIR。CoreML 需要含 CoreML 的 Apple 原生库。选择 provider 并不保证全部计算在 GPU 上执行,上游可能回退 CPU;VAD 与标点仍使用 CPU。 完整部署步骤、模型选择和验证方式见后端配置。

§标点恢复(可选)

标点是否原生输出因家族而异:SenseVoice、Qwen3-ASR、FunASR-Nano 原生输出已带标点;流式 zipformer、离线 transducer、Paraformer、FireRedASR2 的原始输出没有标点。后一类家族启用 punct-sherpa 并在引擎配置中声明标点模型后,所有 final 自动经过标点后处理:

use asr_core::*;

let mut config = StreamingConfig::new(
    "sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20",
);
config.punctuation = Some(PunctConfig::new(
    "sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8",
));
let engine = Engine::prepare(EngineConfig::Streaming(config), EngineOptions::default())?;
// 模型随引擎一次加载、跨会话共享;配置即启用。
let session = engine.start(SessionOptions::default())?;

模型家族按目录内容自动识别:含 bpe.vocab 为英文 CNN-BiLSTM(半角标点加大小写恢复),否则为中英 CT-Transformer(纯英文输入会得到全角标点)。重复 final 会在推理前判重;推理失败回退原文,不影响会话。模型下载地址与体积见后端配置。

§热词(可选)

本地 transducer 引擎(流式 Zipformer、离线 transducer)与提示注入式 LLM 引擎(Qwen3-ASR、FunASR-Nano)支持语音提示。transducer 的打分语义只存在于 TransducerBiasConfig;通用会话提示 SpeechHints 只包含短语,不承诺具体分数。配置 transducer bias 后解码切换到 modified_beam_search(开销约为 greedy 的 2~4 倍),未配置时保持 greedy 不变。

use asr_core::*;

let mut config = StreamingConfig::new(
    "sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20",
);
// 引擎级词表对所有会话生效。建模单元按模型目录自动推断:
// 含 bpe.vocab 时按 tokens 是否含 CJK 取 cjkchar+bpe / bpe,否则 cjkchar。
config.bias = Some(TransducerBiasConfig::new(vec![
    BiasPhrase::new("语音识别"),
    BiasPhrase::scored("张三", 3.5),
]));
let engine = Engine::prepare(EngineConfig::Streaming(config), EngineOptions::default())?;

会话级短语与默认 bias 短语合并,适合各会话注入不同术语;要求引擎已配置 transducer bias(空短语表可仅启用机制),否则 start 返回 UnsupportedCapability:

let session = engine.start(SessionOptions {
    hints: Some(SpeechHints::new(vec!["本次会话的专有名词".into()])),
    ..Default::default()
})?;

Qwen3-ASR 与 FunASR-Nano 使用 OfflineConfig::prompt_hints,只在 Engine 准备时注入;它们不接受会话级 hints。SenseVoice、Paraformer 不接受 bias 或 prompt hints。transducer 短语不能包含 /、换行、:、,、#、@ 或控制字符;每条不超过 64 字符、每组不超过 256 条。中文建模单元会在 prepare/start 时按同一份 tokens 表检查 OOV。Qwen3/FunASR 的提示总字符数上限为 64,FunASR 另拒绝其上游分隔符 ;、;、,。模型可用性与下载地址见后端配置。

§会话契约

  • try_push 全块接收或返回原音频;队列满返回 WouldBlock。文件输入可用 push_wait。
  • 输入是固定采样率、单声道、有限的 f32,范围 [-1, 1]。后端重采样由库处理。
  • finish(deadline) 关闭输入,排空已接收音频,取得唯一终态。重复调用返回同一结果。
  • cancel 和 Session Drop 会取消会话。Session 自身保留输入所有权,因此 session.input().try_push(...) 形式的临时句柄不会意外取消;finish 显式关闭输入。
  • 原生推理无法强行中断;超时立即结束对外等待,执行槽保留到原生调用退出。
  • SessionFailure 保留确认文本和接收/处理帧数。错误不会伪装成成功空文本。
  • subscribe() 只允许取得一次;首次读取一定是 Update::Reset。Partial 按 utterance ID 合并,Segment 按输入顺序提交。
  • 慢消费者不会影响识别终态;增量队列溢出时下一次读取会得到从权威状态生成的 Reset,自行恢复完整视图。
  • 库核心不复制或保留输入录音;需要录音的宿主在音频生产端自行 tee,utils::audio::Recorder 是现成的参考实现。
  • 可选标点恢复只作用于确认分句,partial 保持原文;字节上限按加标点后的最终文本计。

默认输入队列 2 秒、单块最多 1 秒、会话音频最长 20 分钟、观察增量队列 256 条。每个 Engine 默认最多 8 个活跃会话;Engine clone 共享已准备资源和该执行限额。每次 Engine::prepare 都明确创建一组新资源,不做隐式缓存或加载合并。

核心不包含热加载管理器。宿主需要切换模型时,应先在后台调用 Engine::prepare,成功后再用自身的锁或原子容器替换当前 Engine;既有 Session 继续持有旧 Engine 的资源,新 Session 使用新 Engine。utils::manager::EngineManager 按此模式提供了开箱可用的参考实现(带 400 ms 防抖与代际跟踪):

let generation = manager.request_reload(config);
let snapshot = manager.wait(generation, Instant::now() + Duration::from_secs(30))?;

§可选宿主工具(utils)

utils 模块收录多个宿主共同需要、但保持在核心调用链之外的能力,全部为可选增值:核心调用链不依赖它们,宿主也可以用等效的自有实现。按需经 feature 启用:

能力路径feature
RMS 电平utils::audio::rms无
PCM16 WAV 编码(与 read_wav_pcm16 配对)utils::audio::encode_wav_pcm16无
录音 tee(带上限与截断标志)utils::audio::Recorder无
增量重采样(rubato 封装,AsrError 错误)utils::audio::Resampler无
引擎热切换(防抖、代际、显式回退)utils::manager::EngineManager无
模型目录家族探测utils::models::detectbackend-sherpa 或 punct-sherpa
配置预检(与 Engine::prepare 共用校验器)utils::precheck::validate无(本地分支需 backend-sherpa/vad-silero)
模型资产下载与校验(全程流式、原子发布)utils::download::{ensure, fetch}、utils::download::VAD_MODELmodel-download

utils::download 使用同步 blocking 客户端,不得在异步 runtime 线程内调用;请在专用线程(如 spawn_blocking)中执行。

§本地转写服务(serve)

serve-openai-http 把 Engine::prepare 好的引擎以 OpenAI 兼容 HTTP 服务暴露——与 backend-openai-http 客户端构成同一协议的两半(multipart 字段、{"text"} 响应体与错误体逐一对齐),既有 OpenAI 兼容调用方把 base_url 指到本机即可切换到本地推理——response_format 支持 json(OpenAI 客户端的默认)与 text,客户端零改动;stream=true 回答 text/event-stream,事件为 transcript.text.delta(增量)、transcript.text.done(终稿)与 error——与客户端 HttpResponse::Sse 模式解析的 wire 完全一致,partial 边转写边推送,客户端断连即取消服务端转写。带增量端点的引擎(流式 zipformer、云端后端)产出 delta;离线家族(无增量端点)保持 400 明确拒绝。model 字段不参与选择,服务只暴露启动时装载的模型(/v1/models 可查询)。引擎在启动时装载一次、跨请求共享,并发受 max_active_sessions 限额约束,超限请求以 503 拒绝而非排队;/v1/models 与 /health 供编排与探活:

run(
    Arc::new(engine),
    ServeOptions {
        bind: "127.0.0.1:8080".to_string(),
        language: Some("zh".to_string()),
        ..ServeOptions::default()
    },
)
.await

流式请求与响应的形状(model 接受但忽略;type 在 JSON data 内,客户端不依赖 SSE event: 行):

$ curl -F file=@audio.wav -F model=asr-core -F stream=true \
    http://127.0.0.1:8080/v1/audio/transcriptions

event: transcript.text.delta
data: {"delta":"你好","type":"transcript.text.delta"}

event: transcript.text.done
data: {"text":"你好世界","type":"transcript.text.done"}

需要自带 axum 路由的宿主用 serve::router 把同一服务组合进自己的应用。引擎装配(家族探测、模型装载)留在宿主侧——宿主 prepare 好引擎后交给 run/router。注意 multipart 上传全量缓冲在内存中(受 max_body_bytes 限制,默认 25 MiB,对齐 OpenAI 官方上限;自家 client 默认上传上限 24 MiB,低于此值;限制作用在 body 流上,超限上传在中途即被切断),解码后的音频同样驻留内存;每个请求的推理预算是 timeout_secs(缺省随音频时长伸展),由引擎协作检查与 HTTP 层硬墙双重强制,并发预算耗尽即 503。服务无内建鉴权与 TLS,默认只绑 127.0.0.1:8080,对外暴露请置于反向代理之后。上传若为 webm 容器(现实中即 opus 音轨,symphonia 没有 opus 解码器)会被前置拒绝并提示转码,请改发 wav/flac/mp3 等可解码格式。

§示例与验证

# OpenAI-compatible HTTP 后端
cargo run --no-default-features --features backend-openai-http --example transcribe -- CONFIG.json speech.wav

# 本地 sherpa-onnx 文件转写(流式 transducer 目录)
cargo run --no-default-features --features backend-sherpa --example transcribe_file -- MODEL_DIR speech.wav

# 本地离线转写(按目录自动识别 SenseVoice / FireRedASR2-AED / Qwen3-ASR / FunASR-Nano;--vad 为 silero VAD 模型文件。
# Paraformer、FireRedASR-CTC 与无标记 SenseVoice 共享扁平布局,无法自动区分,须用 transcribe 示例的 JSON 配置显式指定家族)
cargo run --no-default-features --features backend-sherpa,vad-silero --example transcribe_file -- MODEL_DIR speech.wav --vad silero_vad.onnx

# 本地转写 + 标点恢复(第三个位置参数为标点模型目录;流式 zipformer 去掉 --vad 即可)。
# 仅原始输出无标点的家族需要——流式 zipformer、离线 transducer、Paraformer、FireRedASR2;
# SenseVoice、Qwen3-ASR、FunASR-Nano 原生输出已带标点,无需配置
cargo run --no-default-features --features backend-sherpa,vad-silero,punct-sherpa --example transcribe_file -- MODEL_DIR speech.wav PUNCT_DIR --vad silero_vad.onnx

# 本地转写 + 热词偏置(英文模型需归档自带 bpe.vocab)
cargo run --no-default-features --features backend-sherpa --example transcribe_file -- MODEL_DIR speech.wav --hotwords "语音识别,张三"

# 调整识别线程数(默认 2;单会话文件转写可按机器核数调大换吞吐/延迟,
# 引擎配置字段 num_threads 的取值范围 1–256)
cargo run --no-default-features --features backend-sherpa --example transcribe_file -- MODEL_DIR speech.wav --threads 4

# 多格式文件转写(decode-symphonia:FLAC / MP3 / M4A / OGG / WebM;不带该 feature 时仅 16-bit PCM WAV)
cargo run --no-default-features --features backend-sherpa,decode-symphonia --example transcribe_file -- MODEL_DIR speech.mp3

# 显式流式提交;展示 try_push 遇到背压后保留原块并限期重试
cargo run --no-default-features --features backend-sherpa --example streaming -- MODEL_DIR speech.wav

# 麦克风 + HTTP 后端;实时展示 initial/overflow/final Reset、Partial、Segment 与断开
cargo run --no-default-features --features capture-cpal,backend-openai-http --example microphone -- CONFIG.json

# 本地引擎的 OpenAI 兼容转写服务(family 语义同 transcribe_file 的离线家族;
# 扁平布局须 --family paraformer|firered-ctc;可选第三位置参数为标点模型目录,
# 另有 --language / --threads)
cargo run --no-default-features --features serve-openai-http,backend-sherpa,vad-silero --example serve -- MODEL_DIR --vad silero_vad.onnx --bind 127.0.0.1:8080

# 全量验证
cargo test --all-features --all-targets
cargo test --no-default-features

通用示例从 JSON 读取 EngineConfig,从 ASR_API_KEY 注入凭据。transcribe_file 的实时进度与分段转写输出到 stderr(分段定稿即打印,流式部分结果在交互式终端上单行刷新),完整转写只写 stdout,重定向互不干扰。麦克风示例按 Enter 完整停止。云端运行会向配置的服务上传输入音频。

详细说明:架构、后端配置、验证记录。真实模型测试单独标记 ignored;不在普通测试中下载模型或调用付费服务。未入 CI fixture 的大模型回归(Qwen3-ASR、FunASR-Nano、FireRedASR2 等)还需设 ASR_RUN_LARGE_MODEL_TEST=1 才实际执行,区别见验证记录。 Bounded, runtime-independent speech recognition sessions.

Engine::prepare creates reusable backend resources. Engine::start creates an isolated session; audio enters through AudioInput and final results are obtained with Session::finish. See the repository examples and docs/architecture.md for complete lifecycles.

Re-exports§

pub use audio::AudioBuffer;
pub use audio::AudioChunk;
pub use audio::AudioSpec;

Modules§

audio
File input and audio format conversion. Live capture is available with capture-cpal.
serve
The ASR server: one prepared engine, exposed over the OpenAI-compatible transcription API (serve-openai-http).
utils
Optional host conveniences around the engine core.

Structs§

AsrError
AudioInput
BackendCapabilities
BiasPhrase
A default phrase carried by a transducer bias configuration.
CaptureSession
Owns microphone capture and its recognition session. Stopping drains the capture ring first.
DashScopeConfig
Engine
EngineOptions
OfflineConfig
OpenAiHttpConfig
OpenAiRealtimeConfig
PartialView
Canonical partial transcript snapshot, shared by the session’s internal result storage/observation queue and the public observation APIs (SessionView::partials, Update::Partial’s payload shape), so the two can never drift.
PunctConfig
标点恢复模型目录(解压后的 sherpa-onnx punctuation 归档, 如 sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8/)。 目录内容决定模型家族:含 bpe.vocab 为英文 CNN-BiLSTM,否则为中英 CT-Transformer。
PushError
Secret
API key wrapper: redacted by Debug, skipped by serde, and zeroized in memory when dropped.
Segment
Session
SessionFailure
SessionOptions
SessionOutcome
SessionView
SpeechHints
Backend-neutral speech phrases. A backend either accepts the complete set for a session or rejects it as an unsupported capability.
StreamingConfig
Subscription
Timeouts
Transcript
TranscriptSnapshotSink
Receiver of transcript progress snapshots from Engine::transcribe_streaming (and the serve layer built on it).
TransducerBiasConfig
Transducer-only decoding bias. Configuring it selects modified beam search and enables per-session SpeechHints.
VadConfig

Enums§

EngineConfig
ErrorKind
ExecutionProvider
Requested execution provider for local recognition. The native sherpa-onnx and ONNX Runtime libraries must support the selected provider. Upstream may fall back to CPU; this value is not a report of actual device utilization.
HttpMode
HttpResponse
OfflineFamily
SessionPhase
Update

Constants§

DEFAULT_NUM_THREADS
Default recognizer ONNX inference threads: conservative so several concurrent sessions stay within a typical core count. Hosts exposing their own thread knob can anchor on this value to keep their default in sync with StreamingConfig / OfflineConfig.
MAX_NUM_THREADS
Upper bound for recognizer num_threads, enforced by crate::utils::precheck::validate and Engine::prepare; also keeps the usize -> i32 handoff to sherpa-onnx overflow-free.

Type Aliases§

SessionResult
The failure remains boxed to keep this frequently returned result compact.