Expand description
§asr-core
嵌入 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 |
| DashScope | Paraformer WebSocket 实时协议 | backend-dashscope |
| OpenAI 兼容 HTTP | 完整 WAV 上传;可选 JSON、text、SSE | backend-openai-http |
| HTTP 按句上传 | VAD 切段后依次上传 | backend-openai-http,vad-silero |
| OpenAI Realtime | GA 纯转写 WebSocket,24kHz PCM | backend-openai-realtime |
| 默认麦克风 | F32/I16/U16,回调外批处理 | capture-cpal |
| 音频文件解码 | WAV/FLAC/MP3/M4A(AAC)/OGG/WebM → 单声道 f32 | decode-symphonia |
| 本地 OpenAI 兼容转写服务 | 把 prepare 好的 Engine 暴露为 POST /v1/audio/transcriptions | serve-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 使用 CoreMlOfflineConfig 使用相同字段;文件示例支持 --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::detect | backend-sherpa 或 punct-sherpa |
配置预检(与 Engine::prepare 共用校验器) | utils::precheck::validate | 无(本地分支需 backend-sherpa/vad-silero) |
| 模型资产下载与校验(全程流式、原子发布) | utils::download::{ensure, fetch}、utils::download::VAD_MODEL | model-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
- Audio
Input - Backend
Capabilities - Bias
Phrase - A default phrase carried by a transducer bias configuration.
- Capture
Session - Owns microphone capture and its recognition session. Stopping drains the capture ring first.
- Dash
Scope Config - Engine
- Engine
Options - Offline
Config - Open
AiHttp Config - Open
AiRealtime Config - Partial
View - 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. - Punct
Config - 标点恢复模型目录(解压后的 sherpa-onnx punctuation 归档,
如
sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8/)。 目录内容决定模型家族:含bpe.vocab为英文 CNN-BiLSTM,否则为中英 CT-Transformer。 - Push
Error - Secret
- API key wrapper: redacted by
Debug, skipped by serde, and zeroized in memory when dropped. - Segment
- Session
- Session
Failure - Session
Options - Session
Outcome - Session
View - Speech
Hints - Backend-neutral speech phrases. A backend either accepts the complete set for a session or rejects it as an unsupported capability.
- Streaming
Config - Subscription
- Timeouts
- Transcript
- Transcript
Snapshot Sink - Receiver of transcript progress snapshots from
Engine::transcribe_streaming(and the serve layer built on it). - Transducer
Bias Config - Transducer-only decoding bias. Configuring it selects modified beam search
and enables per-session
SpeechHints. - VadConfig
Enums§
- Engine
Config - Error
Kind - Execution
Provider - 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.
- Http
Mode - Http
Response - Offline
Family - Session
Phase - 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 bycrate::utils::precheck::validateandEngine::prepare; also keeps theusize -> i32handoff to sherpa-onnx overflow-free.
Type Aliases§
- Session
Result - The failure remains boxed to keep this frequently returned result compact.