Skip to main content

asr_core/
config.rs

1//! Backend configuration and validation contracts.
2
3#[cfg(feature = "backend-openai-http")]
4use crate::audio;
5use crate::audio::AudioSpec;
6#[cfg(any(
7    feature = "backend-dashscope",
8    feature = "backend-openai-http",
9    feature = "backend-openai-realtime"
10))]
11use crate::AsrError;
12use serde::{Deserialize, Serialize};
13use std::{fmt, path::PathBuf, time::Duration};
14use zeroize::Zeroize;
15
16/// API key wrapper: redacted by `Debug`, skipped by serde, and zeroized
17/// in memory when dropped.
18#[derive(Clone, Default, PartialEq, Eq)]
19pub struct Secret(pub(crate) String);
20
21impl Secret {
22    pub fn new(value: impl Into<String>) -> Self {
23        Self(value.into())
24    }
25}
26
27impl Drop for Secret {
28    fn drop(&mut self) {
29        self.0.zeroize();
30    }
31}
32
33impl fmt::Debug for Secret {
34    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
35        f.write_str("[REDACTED]")
36    }
37}
38
39fn default_connect_timeout() -> Duration {
40    Duration::from_secs(10)
41}
42
43fn default_send_timeout() -> Duration {
44    Duration::from_secs(5)
45}
46
47fn default_response_timeout() -> Duration {
48    Duration::from_secs(30)
49}
50
51#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
52#[serde(deny_unknown_fields)]
53pub struct Timeouts {
54    #[serde(default = "default_connect_timeout")]
55    pub connect: Duration,
56    #[serde(default = "default_send_timeout")]
57    pub send: Duration,
58    #[serde(default = "default_response_timeout")]
59    pub response: Duration,
60}
61
62impl Default for Timeouts {
63    fn default() -> Self {
64        Self {
65            connect: default_connect_timeout(),
66            send: default_send_timeout(),
67            response: default_response_timeout(),
68        }
69    }
70}
71
72fn default_vad_threshold() -> f32 {
73    0.5
74}
75
76fn default_vad_min_silence() -> f32 {
77    0.5
78}
79
80fn default_vad_min_speech() -> f32 {
81    0.25
82}
83
84fn default_vad_max_speech() -> f32 {
85    15.0
86}
87
88#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
89#[serde(deny_unknown_fields)]
90pub struct VadConfig {
91    pub model: PathBuf,
92    #[serde(default = "default_vad_threshold")]
93    pub threshold: f32,
94    #[serde(default = "default_vad_min_silence")]
95    pub min_silence: f32,
96    #[serde(default = "default_vad_min_speech")]
97    pub min_speech: f32,
98    #[serde(default = "default_vad_max_speech")]
99    pub max_speech: f32,
100}
101
102impl VadConfig {
103    pub fn new(model: impl Into<PathBuf>) -> Self {
104        Self {
105            model: model.into(),
106            threshold: default_vad_threshold(),
107            min_silence: default_vad_min_silence(),
108            min_speech: default_vad_min_speech(),
109            max_speech: default_vad_max_speech(),
110        }
111    }
112}
113
114/// 标点恢复模型目录(解压后的 sherpa-onnx punctuation 归档,
115/// 如 `sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8/`)。
116/// 目录内容决定模型家族:含 `bpe.vocab` 为英文 CNN-BiLSTM,否则为中英 CT-Transformer。
117#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
118#[serde(deny_unknown_fields)]
119pub struct PunctConfig {
120    pub model: PathBuf,
121}
122
123impl PunctConfig {
124    pub fn new(model: impl Into<PathBuf>) -> Self {
125        Self {
126            model: model.into(),
127        }
128    }
129}
130
131#[non_exhaustive]
132#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
133pub enum OfflineFamily {
134    SenseVoice,
135    Paraformer,
136    /// 离线 transducer(encoder/decoder/joiner + tokens.txt),支持热词。
137    Transducer,
138    /// Qwen3-ASR(LLM 型,中英 + 多语言),支持引擎级热词。
139    Qwen3Asr,
140    /// FunASR-Nano(Fun-ASR-Nano-2512,LLM 型,中英日 + 中文方言),
141    /// 支持引擎级热词。
142    FunAsrNano,
143    /// FireRedASR-AED(attention-encoder-decoder,encoder + decoder +
144    /// tokens.txt,中英)。兼容 FireRedASR 1.0-AED-L 与 FireRedASR2 的
145    /// sherpa-onnx AED 导出。不支持热词与语言覆盖。
146    FireRedAsrAed,
147    /// FireRedASR-CTC(单 model.onnx + tokens.txt,中英;FireRedASR2 官方
148    /// 导出即此形态)。不支持热词与语言覆盖。
149    FireRedAsrCtc,
150}
151
152/// Backend-neutral speech phrases. A backend either accepts the complete set
153/// for a session or rejects it as an unsupported capability.
154#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
155#[serde(deny_unknown_fields)]
156pub struct SpeechHints {
157    pub phrases: Vec<String>,
158}
159
160impl SpeechHints {
161    pub fn new(phrases: Vec<String>) -> Self {
162        Self { phrases }
163    }
164}
165
166#[derive(Debug, Clone)]
167pub struct SessionOptions {
168    pub input: AudioSpec,
169    pub queue_duration: Duration,
170    pub max_chunk_duration: Duration,
171    pub max_duration: Duration,
172    pub event_capacity: usize,
173    pub max_transcript_bytes: usize,
174    /// Backend-neutral phrases for backends that support per-session hints.
175    pub hints: Option<SpeechHints>,
176}
177
178impl SessionOptions {
179    pub fn new(input: AudioSpec) -> Self {
180        Self {
181            input,
182            ..Self::default()
183        }
184    }
185}
186
187impl Default for SessionOptions {
188    fn default() -> Self {
189        Self {
190            input: AudioSpec {
191                sample_rate: 16_000,
192            },
193            queue_duration: Duration::from_secs(2),
194            max_chunk_duration: Duration::from_secs(1),
195            max_duration: Duration::from_secs(1200),
196            event_capacity: 256,
197            max_transcript_bytes: 8 * 1024 * 1024,
198            hints: None,
199        }
200    }
201}
202
203/// A default phrase carried by a transducer bias configuration.
204#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
205#[serde(deny_unknown_fields)]
206pub struct BiasPhrase {
207    pub phrase: String,
208    pub score: Option<f32>,
209}
210
211impl BiasPhrase {
212    pub fn new(phrase: impl Into<String>) -> Self {
213        Self {
214            phrase: phrase.into(),
215            score: None,
216        }
217    }
218
219    pub fn scored(phrase: impl Into<String>, score: f32) -> Self {
220        Self {
221            phrase: phrase.into(),
222            score: Some(score),
223        }
224    }
225}
226
227fn default_bias_score() -> f32 {
228    2.0
229}
230
231/// Default recognizer ONNX inference threads: conservative so several
232/// concurrent sessions stay within a typical core count. Hosts exposing
233/// their own thread knob can anchor on this value to keep their default
234/// in sync with [`StreamingConfig`] / [`OfflineConfig`].
235pub const DEFAULT_NUM_THREADS: usize = 2;
236
237/// Upper bound for recognizer `num_threads`, enforced by
238/// [`crate::utils::precheck::validate`] and `Engine::prepare`; also keeps
239/// the `usize -> i32` handoff to sherpa-onnx overflow-free.
240pub const MAX_NUM_THREADS: usize = 256;
241
242fn default_num_threads() -> usize {
243    DEFAULT_NUM_THREADS
244}
245
246/// Requested execution provider for local recognition. The native sherpa-onnx
247/// and ONNX Runtime libraries must support the selected provider. Upstream may
248/// fall back to CPU; this value is not a report of actual device utilization.
249#[non_exhaustive]
250#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
251#[serde(rename_all = "lowercase")]
252pub enum ExecutionProvider {
253    #[default]
254    Cpu,
255    /// NVIDIA CUDA on Linux or Windows; requires a CUDA-enabled native build.
256    Cuda,
257    /// Apple CoreML; may schedule work on CPU, GPU, or Neural Engine.
258    CoreMl,
259}
260
261impl ExecutionProvider {
262    pub const fn as_str(self) -> &'static str {
263        match self {
264            Self::Cpu => "cpu",
265            Self::Cuda => "cuda",
266            Self::CoreMl => "coreml",
267        }
268    }
269}
270
271impl std::str::FromStr for ExecutionProvider {
272    type Err = crate::AsrError;
273
274    fn from_str(value: &str) -> Result<Self, Self::Err> {
275        match value {
276            "cpu" => Ok(Self::Cpu),
277            "cuda" => Ok(Self::Cuda),
278            "coreml" => Ok(Self::CoreMl),
279            _ => Err(crate::AsrError::invalid(
280                "provider must be cpu, cuda, or coreml",
281            )),
282        }
283    }
284}
285
286/// Transducer-only decoding bias. Configuring it selects modified beam search
287/// and enables per-session [`SpeechHints`].
288#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
289#[serde(deny_unknown_fields)]
290pub struct TransducerBiasConfig {
291    pub phrases: Vec<BiasPhrase>,
292    #[serde(default = "default_bias_score")]
293    pub default_score: f32,
294    pub modeling_unit: Option<String>,
295}
296
297impl TransducerBiasConfig {
298    pub fn new(phrases: Vec<BiasPhrase>) -> Self {
299        Self {
300            phrases,
301            default_score: default_bias_score(),
302            modeling_unit: None,
303        }
304    }
305}
306
307#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
308#[serde(deny_unknown_fields)]
309pub struct StreamingConfig {
310    pub model_dir: PathBuf,
311    /// Recognizer execution provider; VAD and punctuation use CPU.
312    #[serde(default)]
313    pub provider: ExecutionProvider,
314    pub punctuation: Option<PunctConfig>,
315    /// Transducer decoding bias; also enables per-session speech hints.
316    pub bias: Option<TransducerBiasConfig>,
317    /// Recognizer ONNX inference threads; VAD and punctuation models keep
318    /// their own fixed settings.
319    #[serde(default = "default_num_threads")]
320    pub num_threads: usize,
321}
322
323impl StreamingConfig {
324    pub fn new(model_dir: impl Into<PathBuf>) -> Self {
325        Self {
326            model_dir: model_dir.into(),
327            provider: ExecutionProvider::default(),
328            punctuation: None,
329            bias: None,
330            num_threads: default_num_threads(),
331        }
332    }
333}
334
335#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
336#[serde(deny_unknown_fields)]
337pub struct OfflineConfig {
338    pub model_dir: PathBuf,
339    /// Recognizer execution provider; VAD and punctuation use CPU.
340    #[serde(default)]
341    pub provider: ExecutionProvider,
342    pub family: OfflineFamily,
343    pub language: Option<String>,
344    pub vad: VadConfig,
345    pub punctuation: Option<PunctConfig>,
346    /// Transducer-only decoding bias; also enables per-session speech hints.
347    pub transducer_bias: Option<TransducerBiasConfig>,
348    /// Engine-level prompt phrases for Qwen3-ASR and FunASR-Nano.
349    pub prompt_hints: Option<SpeechHints>,
350    /// Recognizer ONNX inference threads; VAD and punctuation models keep
351    /// their own fixed settings.
352    #[serde(default = "default_num_threads")]
353    pub num_threads: usize,
354}
355
356impl OfflineConfig {
357    pub fn new(model_dir: impl Into<PathBuf>, family: OfflineFamily, vad: VadConfig) -> Self {
358        Self {
359            model_dir: model_dir.into(),
360            provider: ExecutionProvider::default(),
361            family,
362            language: None,
363            vad,
364            punctuation: None,
365            transducer_bias: None,
366            prompt_hints: None,
367            num_threads: default_num_threads(),
368        }
369    }
370}
371
372#[non_exhaustive]
373#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
374pub enum HttpMode {
375    #[default]
376    WholeRecording,
377    Utterances(VadConfig),
378}
379
380#[non_exhaustive]
381#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
382pub enum HttpResponse {
383    #[default]
384    Json,
385    Text,
386    Sse,
387}
388
389fn default_http_sample_rate() -> u32 {
390    16_000
391}
392
393fn default_max_upload_bytes() -> usize {
394    24 * 1024 * 1024
395}
396
397fn default_max_response_bytes() -> usize {
398    1024 * 1024
399}
400
401#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
402#[serde(deny_unknown_fields)]
403pub struct OpenAiHttpConfig {
404    pub api_root: String,
405    pub model: String,
406    #[serde(skip)]
407    pub api_key: Secret,
408    #[serde(default = "default_http_sample_rate")]
409    pub sample_rate: u32,
410    #[serde(default)]
411    pub mode: HttpMode,
412    #[serde(default)]
413    pub response: HttpResponse,
414    pub language: Option<String>,
415    pub prompt: Option<String>,
416    #[serde(default = "default_max_upload_bytes")]
417    pub max_upload_bytes: usize,
418    #[serde(default = "default_max_response_bytes")]
419    pub max_response_bytes: usize,
420    #[serde(default)]
421    pub timeouts: Timeouts,
422}
423
424impl OpenAiHttpConfig {
425    pub fn new(api_root: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
426        Self {
427            api_root: api_root.into(),
428            model: model.into(),
429            api_key,
430            sample_rate: default_http_sample_rate(),
431            mode: HttpMode::default(),
432            response: HttpResponse::default(),
433            language: None,
434            prompt: None,
435            max_upload_bytes: default_max_upload_bytes(),
436            max_response_bytes: default_max_response_bytes(),
437            timeouts: Timeouts::default(),
438        }
439    }
440
441    #[cfg(feature = "backend-openai-http")]
442    pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
443        validate_cloud_parameters(&self.model, &self.timeouts, &self.api_key, "OpenAI HTTP")?;
444        AudioSpec::mono(self.sample_rate)?;
445        if audio::pcm16_wav_sample_capacity(self.max_upload_bytes)
446            .is_none_or(|capacity| capacity == 0)
447            || self.max_response_bytes == 0
448        {
449            return Err(AsrError::invalid(
450                "upload and response limits must be positive",
451            ));
452        }
453        Ok(())
454    }
455}
456
457#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
458#[serde(deny_unknown_fields)]
459pub struct DashScopeConfig {
460    pub endpoint: String,
461    pub model: String,
462    #[serde(skip)]
463    pub api_key: Secret,
464    #[serde(default)]
465    pub timeouts: Timeouts,
466}
467
468impl DashScopeConfig {
469    pub fn new(endpoint: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
470        Self {
471            endpoint: endpoint.into(),
472            model: model.into(),
473            api_key,
474            timeouts: Timeouts::default(),
475        }
476    }
477
478    #[cfg(feature = "backend-dashscope")]
479    pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
480        validate_cloud_parameters(&self.model, &self.timeouts, &self.api_key, "DashScope")
481    }
482}
483
484fn default_true() -> bool {
485    true
486}
487
488#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
489#[serde(deny_unknown_fields)]
490pub struct OpenAiRealtimeConfig {
491    pub endpoint: String,
492    pub model: String,
493    #[serde(skip)]
494    pub api_key: Secret,
495    #[serde(default = "default_true")]
496    pub server_vad: bool,
497    #[serde(default)]
498    pub timeouts: Timeouts,
499}
500
501impl OpenAiRealtimeConfig {
502    pub fn new(endpoint: impl Into<String>, model: impl Into<String>, api_key: Secret) -> Self {
503        Self {
504            endpoint: endpoint.into(),
505            model: model.into(),
506            api_key,
507            server_vad: true,
508            timeouts: Timeouts::default(),
509        }
510    }
511
512    #[cfg(feature = "backend-openai-realtime")]
513    pub(crate) fn validate_parameters(&self) -> Result<(), AsrError> {
514        validate_cloud_parameters(
515            &self.model,
516            &self.timeouts,
517            &self.api_key,
518            "OpenAI Realtime",
519        )
520    }
521}
522
523#[non_exhaustive]
524#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
525pub enum EngineConfig {
526    Streaming(StreamingConfig),
527    Offline(OfflineConfig),
528    DashScope(DashScopeConfig),
529    OpenAiHttp(OpenAiHttpConfig),
530    OpenAiRealtime(OpenAiRealtimeConfig),
531}
532
533#[cfg(any(
534    feature = "backend-dashscope",
535    feature = "backend-openai-http",
536    feature = "backend-openai-realtime"
537))]
538pub(crate) fn validate_model(model: &str) -> Result<(), AsrError> {
539    if model.trim().is_empty() {
540        Err(AsrError::invalid("model is required"))
541    } else {
542        Ok(())
543    }
544}
545
546#[cfg(any(
547    feature = "backend-dashscope",
548    feature = "backend-openai-http",
549    feature = "backend-openai-realtime"
550))]
551pub(crate) fn validate_timeouts(timeouts: &Timeouts) -> Result<(), AsrError> {
552    for (name, timeout) in [
553        ("connect", timeouts.connect),
554        ("send", timeouts.send),
555        ("response", timeouts.response),
556    ] {
557        if timeout.is_zero() {
558            return Err(AsrError::invalid(format!(
559                "{name} timeout must be positive"
560            )));
561        }
562        if timeout > crate::deadline::MAX_NETWORK_TIMEOUT {
563            return Err(AsrError::invalid(format!(
564                "{name} timeout must not exceed 24 hours"
565            )));
566        }
567        crate::deadline::after(timeout, name)?;
568    }
569    Ok(())
570}
571
572/// The parameter checks every cloud backend shares: a usable model id,
573/// sane timeouts and a non-empty API key, with `service` naming the
574/// backend in the API-key error.
575#[cfg(any(
576    feature = "backend-dashscope",
577    feature = "backend-openai-http",
578    feature = "backend-openai-realtime"
579))]
580fn validate_cloud_parameters(
581    model: &str,
582    timeouts: &Timeouts,
583    api_key: &Secret,
584    service: &str,
585) -> Result<(), AsrError> {
586    validate_model(model)?;
587    validate_timeouts(timeouts)?;
588    if api_key.0.trim().is_empty() {
589        return Err(AsrError::invalid(format!("{service} requires an API key")));
590    }
591    Ok(())
592}
593
594#[cfg(test)]
595mod tests;