RealtimeSTT 转录引擎选型与扩展指南从 faster-whisper 到多引擎工厂【免费下载链接】RealtimeSTTA robust, efficient, low-latency speech-to-text library with advanced voice activity detection, wake word activation and instant transcription.项目地址: https://gitcode.com/GitHub_Trending/re/RealtimeSTTRealtimeSTT 通过一个懒加载lazy-loaded的引擎工厂统一路由语音识别后端AudioToTextRecorder用transcription_engine选择最终转录引擎用realtime_transcription_engine单独指定实时interim转录引擎两者可以相同也可以不同。本文基于 docs/transcription-engines.md 系统梳理全部受支持引擎、选型依据、参数注入方式、模型下载行为并结合仓库源码说明引擎工厂的底层实现与自定义引擎的扩展契约读完你可以在不同硬件与依赖约束下正确选型、配置并扩展 RealtimeSTT 的语音转写后端。引擎架构懒加载工厂与双引擎路由RealtimeSTT 的转录引擎体系建立在工厂 适配器模式之上核心入口是 RealtimeSTT/transcription_engines/factory.py 中的create_transcription_engine(name, config)normalized_name (name or faster_whisper).strip().lower().replace(-, _) if normalized_name not in ENGINE_CLASS_PATHS: available_engines , .join(sorted(ENGINE_CLASS_PATHS)) raise UnsupportedTranscriptionEngineError( fUnsupported transcription engine {name}. Available engines: {available_engines} ) engine_cls _load_engine_class(normalized_name) return engine_cls(config)几个值得注意的设计点名称规范化引擎名先做strip().lower().replace(-, _)所以 Python 风格sherpa_onnx_parakeet与 CLI 风格sherpa-onnx-parakeet的写法都可用仓库中tests/unit/test_cohere_transcribe_engine.py、test_granite_speech_engine.py等测试也验证了带连字符的引擎名能正确解析。懒加载_load_engine_class通过import_module在引擎被选中的那一刻才导入对应模块保证可选的重量级依赖faster-whisper、NeMo、Transformers 等不会污染默认安装。这正是不选引擎就不装依赖的机制来源。默认兜底name为空时回退到faster_whisper与文档中兼容性默认值为 faster_whisper完全一致。错误提示友好不支持的引擎名会抛出UnsupportedTranscriptionEngineError错误信息会列出全部可用引擎错误类型定义于 RealtimeSTT/transcription_engines/base.py。引擎的公共契约定义在 RealtimeSTT/transcription_engines/base.py所有引擎继承BaseTranscriptionEngine实现transcribe()并返回统一的TranscriptionResult含text与语言元数据TranscriptionInfo共享配置由TranscriptionEngineConfig数据类承载模型名、download_root、compute_type、device、beam_size、batch_size、engine_options 等。支持流式推理的引擎还可实现StreamingTranscriptionSession。在运行链路中最终转录由一个独立 worker 进程承担RealtimeSTT/core/transcription.py 的TranscriptionWorker.run()在进程内调用create_transcription_engine构造引擎并用RealtimeSTT/assets/warmup_audio.wav做一次预热的engine.warmup()把模型加载成本前置到首次用户请求之前。实时转录引擎则在 RealtimeSTT/core/initialization.py 中单独构造。如何选择引擎按使用场景起步原文档给出了一张按使用场景推荐的选型表直接决定了多数项目的起步引擎使用场景推荐起步引擎理由默认本地 GPU/CPU Whisper 路径faster_whisper通过RealtimeSTT[faster-whisper]安装成熟稳定支持常见 Whisper 模型名与 CTranslate2 模型目录仅 CPU 的小型 Whisper 模型实验whisper_cpp通过pywhispercpp调用 whisper.cpp依赖少适合 CPU 快速验证兼容 OpenAI 本地 Whisper 包openai_whisper使用原版openai-whisperPython 包英文 CPU 服务器 手动下载 ONNX 模型sherpa_onnx_moonshine离线 CPU INT8 路径本地模型文件可预期CPU 上不带 NeMo 运行 Parakeetsherpa_onnx_parakeet通过 sherpa-onnx 的离线 CPU INT8 ParakeetKroko/Banafo.data流式模型kroko_onnx可选 Kroko-ONNX 运行时支持社区或授权 Pro 模型及实时流式预览NVIDIA ParakeetLinux/WSL2parakeet使用 NVIDIA NeMo ASR 加载 Parakeet 检查点Meta Omnilingual ASRLinux/WSL2 Python 3.11.xomnilingual_asr使用 Meta 的 Omnilingual ASR 包原生 Windows 与 Python 3.12.x 在当前上游依赖栈下不具备实际可安装性Hugging Face 语音语言模型granite_speech、qwen3_asr、moonshine、cohere_transcribe均为模型族包 Transformers 的薄适配层选型逻辑的本质是硬件形态 × 运行时依赖 × 模型族三个维度GPU 优先 faster-whisper / parakeet纯 CPU 离线优先 sherpa-onnxINT8流式原生模型优先 kroko_onnx需要最新 HF 模型则走 Transformers 适配层。全部受支持引擎名一览引擎名会做规范化处理-替换为_因此下表中的 Python 风格与 CLI 风格名称均可用。此表与 factory.py 中ENGINE_CLASS_PATHS的注册项一一对应引擎名状态参考文档faster_whisper默认生产后端docs/engines/faster-whisper.mdwhisper_cpp可选生产后端docs/engines/whisper-cpp.mdopenai_whisper可选生产后端docs/engines/openai-whisper.mdmoonshine、moonshine_streaming实验性 Transformers 后端仅英文适配器docs/engines/moonshine.mdsherpa_onnx_moonshine、sherpa_moonshine、moonshine_sherpa_onnxCPU INT8 sherpa-onnx 后端docs/engines/sherpa-onnx.mdkroko_onnx、kroko、banafo_kroko可选 Kroko-ONNX 后端docs/engines/kroko-onnx.mdparakeet、nvidia_parakeet实验性 NVIDIA NeMo 后端docs/engines/parakeet-nemo.mdsherpa_onnx_parakeet、sherpa_parakeet、parakeet_sherpa_onnxCPU INT8 sherpa-onnx 后端docs/engines/sherpa-onnx.mdomnilingual_asr、omnilingual、meta_omnilingual_asr、omni_asr实验性 Meta Omnilingual ASR 后端Linux/WSL2 Python 3.11.xdocs/engines/omnilingual-asr.mdgranite_speech、granite实验性 Transformers 后端docs/engines/hf-transformers.mdqwen3_asr、qwen_asr实验性 Qwen ASR 后端docs/engines/hf-transformers.mdcohere_transcribe、cohere实验性 Transformers 后端需要指定语言docs/engines/cohere.mdopenai_api占位实现尚未接线不可用除上述外factory.py 还注册了funasr引擎而openai_api在 RealtimeSTT/transcription_engines/openai_api_engine.py 中只是占位尚未接入完整调用链。任何未注册名称都会触发上述UnsupportedTranscriptionEngineError错误信息中会列出可用引擎清单。配置后端最终转录与实时转录的引擎选择使用默认引擎最简单的方式是显式指定faster_whisper也是兼容性默认值from RealtimeSTT import AudioToTextRecorder recorder AudioToTextRecorder( modelsmall.en, transcription_enginefaster_whisper, )最终与实时转录使用不同引擎enable_realtime_transcriptionTrue时可以给实时转录单独指定更轻量的后端让最终精度与实时速度各取所长from RealtimeSTT import AudioToTextRecorder recorder AudioToTextRecorder( transcription_enginefaster_whisper, modelsmall.en, enable_realtime_transcriptionTrue, realtime_transcription_enginewhisper_cpp, realtime_model_typetiny.en, realtime_transcription_engine_options{ model: {n_threads: 8}, transcribe: {single_segment: True, no_context: True}, }, )关键规则如果realtime_transcription_engine为None实时转录会自动复用transcription_engine指定的同一后端。这一逻辑在 RealtimeSTT/core/initialization.py 中实现——realtime_transcription_engine取init_args中对应值缺省时回退到主引擎realtime_transcription_engine_options同理为None时直接复用transcription_engine_options。也就是说两个引擎既共享配置也可独立配置。实时转录引擎的初始化同样发生在 initialization.py通过create_transcription_engine构造并传入实时专用配置初始化失败会被捕获并记录日志不会拖垮主引擎。引擎专属选项transcription_engine_options 的注入方式不同后端需要各自的专属参数通过transcription_engine_options最终与realtime_transcription_engine_options实时两个字典注入。原文档给出的 sherpa-onnx Moonshine 示例recorder AudioToTextRecorder( transcription_enginesherpa_onnx_moonshine, modelmodels/sherpa-onnx-moonshine-tiny-en-int8, devicecpu, languageen, transcription_engine_options{ num_threads: 2, provider: cpu, }, )这些选项字典刻意保持引擎专属对某引擎有意义的键对另一个引擎可能被忽略甚至非法。从源码看该字典最终被放进TranscriptionEngineConfig.engine_options见 RealtimeSTT/core/transcription.py 与 base.py由各适配器自行解释RealtimeSTT 不做跨引擎的键翻译。以 sherpa-onnx 引擎为例详见 docs/engines/sherpa-onnx.md常用键包括选项含义model_dir显式指定已解压的模型目录files覆盖单个 ONNX / tokens 文件名的字典num_threadsCPU 工作线程数providerONNX Runtime 提供方通常为cpudecoding_methodsherpa-onnx 解码方式默认greedy_searchdebug开启 sherpa-onnx 调试输出rule_fsts、rule_fars可选文本归一化资源input_sample_rate、sample_rate输入/模型采样率控制Parakeet 还支持model_type、max_active_paths、hotwords_file、hotwords_score、blank_penalty、feature_dim、lm、lm_scale等 transducer 选项。而 faster-whisper 引擎的共享参数映射关系更直接详见 docs/engines/faster-whisper.mdmodel→WhisperModel(model_size_or_path...)、device→WhisperModel(device...)、compute_type→WhisperModel(compute_type...)、gpu_device_index→WhisperModel(device_index...)、beam_size/initial_prompt/suppress_tokens/faster_whisper_vad_filter逐项透传给model.transcribe(...)当batch_size 0时还会用BatchedInferencePipeline包装模型开启批量推理见 RealtimeSTT/transcription_engines/faster_whisper_engine.py。模型下载行为自动下载与手动放置不同引擎族的模型获取策略差异很大原文档对此有明确划分引擎族自动下载手动放置faster_whisper是针对已知 Hugging Face/CTranslate2 模型 id本地 CTranslate2 模型目录可直接作为model传入whisper_cpp通常可以针对pywhispercpp支持的模型名可用本地 ggml 模型路径或download_root/models_diropenai_whisper是通过openai-whisper支持该包支持的本地模型名/路径moonshine、granite_speech、qwen3_asr、cohere_transcribe是通过 Hugging Face 或引擎包下载受访问权限约束支持时download_root映射到缓存选项parakeetNeMo是通过 NeMo 模型加载可在transcription_engine_options中传入 NeMo 缓存/模型选项omnilingual_asr是通过 Omnilingual/fairseq2/Hugging Face 缓存路径Linux/WSL2 Python 3.11.x传入 Omnilingual 模型卡如omniASR_CTC_1B_v2RealtimeSTT 不会移动或删除已下载资源。未知的 v2 模型卡属于依赖不匹配不应据此回退到旧的非 v2 模型卡sherpa_onnx_*否需手动下载并解压 sherpa-onnx 模型包再传入解压后的目录kroko_onnx是针对已知的公开 Community.data文件启用时Pro/私有模型需要已有的.data路径、直链 URL 或显式的 repo/token 选项其中 sherpa-onnx 的手动流程最典型下载.tar.bz2归档如sherpa-onnx-moonshine-tiny-en-int8.tar.bz2、sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8.tar.bz2后必须解压并让model指向解压目录而不是归档文件本身。Moonshine Tiny 包内应有preprocess.onnx、encode.int8.onnx、uncached_decode.int8.onnx、cached_decode.int8.onnx、tokens.txtParakeet 包内应有encoder.int8.onnx、decoder.int8.onnx、joiner.int8.onnx、tokens.txt。另一个便捷途径是选parakeet家族引擎并指定backend: sherpa_onnx选项让download_root下的已知模型 id 自动解析到预期的解压目录见 docs/engines/sherpa-onnx.md。Kroko-ONNX 的构建安装则走专用命令详见 docs/engines/kroko-onnx.mdpython -m pip install RealtimeSTT[kroko-builder,silero-onnx-cpu] stt-install-kroko --buildWindows 上需先启动 Docker Desktop要求 WSL2 后端真正运行docker version应同时输出 Client 与 Server 段Linux 上则打补丁后从源码安装。--skip-install可只构建 wheel 而不装入当前 Python 环境。每个可选引擎的独立页面都记录了其安装命令、模型行为、重要选项与故障排查可作为本文的逐引擎补充读物。扩展新引擎实现契约与接入工厂原文档给出了第三方接入的明确契约仓库源码可以逐条印证继承BaseTranscriptionEngine实现transcribe(audio, languageNone, use_promptTrue)返回TranscriptionResult支持流式时额外实现StreamingTranscriptionSession接口定义见 RealtimeSTT/transcription_engines/base.py。注册到工厂在 RealtimeSTT/transcription_engines/factory.py 的ENGINE_CLASS_PATHS中添加引擎名: (.模块名, 类名)并支持必要的别名。保持懒加载引擎模块内通过import_module延迟导入可选依赖。faster-whisper 适配器就是范例——faster_whisper_engine.py 在构造时import_module(faster_whisper)缺包时抛出包含安装提示的TranscriptionEngineError。基础类还提供两个可复用工具_normalize_audio()在normalize_audioTrue时按峰值归一化音频除以峰值再乘 0.95见 base.py_get_prompt()在启用提示词时返回initial_prompt。这两个助手保证各适配器的行为一致性。契约测试应覆盖缺失依赖时的错误消息、参数映射、音频归一化、结果转换以及工厂选择逻辑而真实模型测试应保持 opt-in需要真实下载模型的用例不进默认测试套件。仓库中 tests/unit/test_additional_transcription_engines.py 与各引擎专属测试如 tests/unit/test_kroko_onnx_engine.py、tests/unit/test_cohere_transcribe_engine.py正是围绕这些契约编写的实例可作为新引擎测试的模板。常见问题与调优要点实时转录滞后换更小的实时模型如realtime_model_typetiny.en、降低beam_size_realtime、增大realtime_processing_pause默认0.2秒或把实时引擎切到 CPU 友好后端如whisper_cpp。共享模型争用use_main_model_for_realtimeTrue可省内存但最终与实时转录共用同一模型时会互相争用、降低响应速度需按负载权衡。CUDA 加载失败按机器 CUDA 版本重装 PyTorch/torchaudio模型下载失败则检查download_root可写性与 Hugging Face Hub 连通性。sherpa-onnx 缺文件报错会直接点名缺失的 ONNX 或tokens.txt路径确认归档已解压而非仅下载Moonshine 的 sherpa-onnx 适配器仅支持英文。引擎参数无效牢记选项字典是引擎专属的跨引擎复用前先查阅对应引擎页的参数表。引擎架构与全部可选引擎的细节可进一步参阅 docs/transcription-engines.md、docs/configuration.md完整构造参数参考以及 docs/engines 目录下的逐引擎文档。【免费下载链接】RealtimeSTTA robust, efficient, low-latency speech-to-text library with advanced voice activity detection, wake word activation and instant transcription.项目地址: https://gitcode.com/GitHub_Trending/re/RealtimeSTT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
