RealtimeSTT FastAPI 浏览器流式服务完全指南部署、配置、WebSocket 协议与多用户调度【免费下载链接】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本文是 RealtimeSTT 官方浏览器流式参考服务example_fastapi_server的完整技术指南覆盖从安装启动、引擎组合到多会话调度与监控的全链路。读完本文你将掌握如何把浏览器麦克风音频通过 WebSocket 实时推入 RealtimeSTT 的按会话录音状态机如何用共享推理车道final/realtime 双车道承载多用户并发如何通过/api/config做运行时热配置以及如何用/health与/api/metrics做容量评估与延迟监控。服务定位源码仓库专属的浏览器参考实现example_fastapi_server是 RealtimeSTT 的浏览器流式参考应用它同时提供本地浏览器 UI 和一个 WebSocket 端点将浏览器麦克风音频流入按会话隔离的 recorder 状态机见 example_fastapi_server/server.py 与 example_fastapi_server/static/index.html。需要特别注意的是该参考服务只面向源码检出source checkout场景不会随 PyPI wheel 一起安装。保持源码化可以让 wheel 保持精简也避免给仅需 recorder/API 库的用户引入额外的 Web 服务器依赖。因此仅通过pip install RealtimeSTT安装的用户请改用仓库内的 Python recorder/API 示例例如 tests/simple_test.py、tests/realtimestt_test.py 或 tests/openai_voice_interface.py想使用 FastAPI 参考服务器请 clone 本仓库或从 Git 安装后在源码根目录运行。从源码结构看server.py服务端的核心装配是RealtimeSTTService持有SessionStore会话准入与InferenceScheduler共享推理调度器FastAPI 应用通过 lifespan 启动服务与调度器。这也印证了文档中每个会话是轻量状态机、重型 ASR 引擎全局共享的设计。安装与运行安装依赖创建独立虚拟环境并安装项目依赖与服务器依赖Linux/macOS bashpython -m venv .venv-fastapi source .venv-fastapi/bin/activate python -m pip install -U pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -r example_fastapi_server/requirements.txtWindows PowerShell 对应版本python -m venv .venv-fastapi .\.venv-fastapi\Scripts\Activate.ps1 python -m pip install -U pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -r example_fastapi_server\requirements.txt服务器自身的最小依赖见 example_fastapi_server/requirements.txtfastapi0.115、uvicorn[standard]0.30、numpy、scipy。若缺少这些依赖server.py 会抛出明确提示引导安装。随后按需安装计划运行的可选引擎栈完整清单见 transcription-engines.md。仓库内的 tests/install_extras_matrix.py 与 tests/install_packages.py 提供了可选依赖矩阵的安装脚本可作为安装参考。启动服务器python example_fastapi_server/server.py --host 0.0.0.0 --port 8010打开浏览器访问http://localhost:8010服务器总体设计按会话隔离、按模型共享服务器接受多个浏览器会话。每个 WebSocket 在握手时由服务端分配一个sessionId实现为uuid4().hex见 server.py此后该会话的音频缓冲、VAD 状态、转写段 IDsegmentId、clear/reset 命令、实时文本、最终文本、警告与错误全部限定在该会话作用域内。从 server.py 与 server.py 可以看到两类会话实现RealtimeSession服务端自行维护 VAD 与分段的内联会话主要用于单元测试RecorderBackedRealtimeSession每个会话内部持有一个轻量级AudioToTextRecorder流状态机浏览器服务器由此完整继承了 recorder 已有的 WebRTC VAD、Silero VAD、唤醒词钩子、early-final 转写与音节边界实时调度。它把transcription_executor/realtime_transcription_executor注入为共享调度器执行器见 server.py因此重型 ASR 引擎由全局共享的工作线程加载而不是每个浏览器各自加载一份模型。InferenceSchedulerserver.py按use_main_model_for_realtime决定资源布局默认平衡模式一条共享 final 模型车道 一条共享 realtime 模型车道低内存模式--use-main-model-for-realtime让两条队列共用同一条模型车道。VAD 状态刻意保持按会话隔离。WebRTC/Silero 检测在流层面是有状态的若把单个共享 VAD 对象用于多路音频流会带来正确性风险权重、循环状态、线程访问都无法按会话分离。example_fastapi_server/MULTI_USER_IMPLEMENTATION_GUIDE.md 详细记录了这一多用户化改造的原则per-session 状态会话 ID、websocket、分段 ID、VAD/录音状态、音频有界队列、实时调度状态、配额与丢弃计数与 shared 推理资源共享模型、公平调度器、全局准入控制严格分层。公平调度与过载保护FairInferenceQueueserver.py实现按会话公平的调度final 作业按会话排队受max_final_queue_depth_per_session与max_global_inference_queue_depth双重限制realtime 作业每会话只保留最新一个新提交会以coalesced合并方式替换旧作业避免嘈杂客户端用过期中间结果灌满全局队列过期 realtime 作业在出队时按deadline_at由max_realtime_queue_age_ms折算判定为stale直接丢弃会话断开或 clear 时通过cancel_session清理该会话在队列中的所有作业。HTTP 端点一览服务器暴露以下端点见 server.py端点作用GET /返回浏览器 UIstatic/index.htmlGET /health就绪状态、活跃会话/说话人数、启动错误、调度器状态GET /api/config公开配置、容量限制、受支持的引擎列表PATCH /api/config运行时热更新部分配置GET /api/metrics计数器、队列深度、延迟、合并/丢弃统计、工作线程利用率WS /ws/transcribe浏览器音频流与控制命令通道配置参数全表核心引擎参数Flag含义默认值见 server.pyServerSettings--engine,--transcription-enginefinal 转写引擎faster_whisper--modelfinal 模型名或路径small.en--realtime-engine,--realtime-transcription-engine实时引擎缺省时与 final 引擎相同None回退到 final 引擎--realtime-model实时模型名或路径tiny.en--engine-options传给 final 引擎的 JSON 对象None--realtime-engine-options传给实时引擎的 JSON 对象None--download-root模型缓存或查找根目录None--devicecuda或cpucudaeffective_device会在 CUDA 不可用时自动回退cpu见 server.py--compute-type引擎精度/量化提示default--language语言代码en--use-main-model-for-realtime用一条共享模型车道同时服务 final 与 realtimeFalse引擎名在服务端经过normalize_engine_name归一化strip().lower().replace(-, _)见 example_fastapi_server/protocol.py因此whisper-cpp、sherpa-onnx-moonshine、kroko-onnx等连字符写法均可接受。可用的引擎注册表见 RealtimeSTT/transcription_engines/factory.py。VAD 与转写时机参数Flag含义默认值--min-length-of-recording最小录音时长秒不足则放弃该段0.2--min-gap-between-recordings两次录音之间的最小间隔0.0--post-speech-silence-duration结束一句话前所需的静音时长秒0.55--silero-sensitivitySilero VAD 灵敏度0.05--webrtc-sensitivityWebRTC VAD 激进程度0-3 整数3--early-transcription-on-silence静音期启动投机式 final 转写0.2--pre-recording-buffer-duration每会话预卷pre-roll时长秒在有语音前持续缓存音频语音出现时并入段首0.75--realtime-processing-pause实时更新固定节拍秒0.02--realtime-use-syllable-boundaries启用声学边界调度realtime 用音节边界切分False--realtime-boundary-detector-sensitivity边界检测器灵敏度0.6--realtime-boundary-followup-delays逗号分隔的实时补充延迟列表秒(0.05, 0.2)realtime_processing_pause与realtime_min_audio_seconds0.25、realtime_max_audio_seconds20.0共同决定实时作业的产生节奏_maybe_create_realtime_job_lockedserver.py在节拍窗口内、且已录制音频超过最小秒数时才提交实时作业音频窗口超过最大秒数时仅取末尾片段参与实时推断。唤醒词参数Flag含义--wakeword-backend传给AudioToTextRecorder的唤醒词后端例如pvporcupine或openwakeword--wake-words逗号分隔的唤醒词或所选后端的模型名--wake-words-sensitivity唤醒词检测灵敏度默认0.5--wake-word-activation-delay唤醒词模式生效前的延迟默认0.0--wake-word-timeout唤醒检测后等待语音的时间超时回到唤醒等待态默认5.0--wake-word-buffer-duration从录音段开头移除的唤醒词音频时长默认0.1--wake-word-followup-window录音结束后的可选宽限窗口期间会话保持在 Voice 模式后续语音无需重复唤醒词即可直接开始默认0.0即关闭--openwakeword-model-paths逗号分隔的 OpenWakeWord 模型路径--openwakeword-inference-frameworkOpenWakeWord 推理框架默认onnx唤醒词的wake_word_enabled()判定条件是后端与唤醒词均非空见 server.py。Follow-up 窗口的实现细节见_start_wakeword_followup_windowserver.py它在录音结束后临时把 recorder 的wakeword_detected置真并缩短超时窗口结束时恢复原值。容量与调度参数Flag含义默认值--max-sessions最大接受的浏览器会话数4--max-active-speakers最大并发活跃说话人数4--audio-queue-size每会话输入队列大小128--max-audio-packet-bytes单个二进制包最大字节数512 * 1024512 KiB--max-audio-queue-seconds-per-session强制结束超长连续录音秒30.0--max-realtime-queue-age-ms丢弃过期的实时作业毫秒1500--max-final-queue-depth-per-session限制每会话 final 积压8--max-global-inference-queue-depth全局调度器队列上限64--realtime-degradation-threshold-ms实时调度降级阈值毫秒1500--realtime-min-audio-seconds实时作业最小音频时长秒0.25--realtime-max-audio-seconds实时作业最大音频时长秒20.0--vad-energy-threshold服务端使用的音频能量门限RMS 阈值250.0--no-model-warmup禁用模型预热默认开启预热会话准入采用先预留、后构造的机制SessionStore.reserveserver.py会话槽位在构造 recorder/VAD 之前预留因此并发连接突发不会实例化出超过--max-sessions数量的 recorder。音频包只有在收到start命令后才被接受recorder 输入队列用--audio-queue-size映射为 recorder 的allowed_latency_limit约束连续录音达到--max-audio-queue-seconds-per-session会被强制 finalize_force_finalize_after_limitserver.py已完成录音的积压按--max-final-queue-depth-per-session裁剪_trim_recorded_audio_queueserver.py。此外还有命名调优档案可通过--profile选择显式 flag 会覆盖档案默认值见 server.pycustom使用显式 CLI 参数/默认值parakeet-low-latency面向频繁 interim 更新realtime_processing_pause0.04、post_speech_silence_duration0.45等parakeet-balanced兼顾延迟与最终稳定性realtime_processing_pause0.06、post_speech_silence_duration0.55parakeet-accurate-final偏向平静分段与最终质量realtime_processing_pause0.1、post_speech_silence_duration0.7。运行时配置契约Runtime SettingsGET /api/config返回的runtimeSettings契约把配置分成三类见 server.py 与runtime_settings_contractserver.pyactiveSessionSafe可热更新并立即影响正在运行的服务如log_level、max_sessions、max_active_speakers、max_audio_packet_bytes、max_final_queue_depth_per_session、max_global_inference_queue_depth、max_realtime_queue_age_ms、realtime_degradation_threshold_msnewSessionOnly只复制进未来新建的浏览器会话已有会话保持自己的 recorder 配置如 VAD/唤醒词/分段/实时节拍类参数startupOnly包括 ASR 引擎与模型路径在内的参数因共享推理工作线程已初始化而被拒绝如engine、model、device、compute_type、download_root、batch_size、beam_size等修改它们需要重启服务器。热更新示例curl -X PATCH http://localhost:8010/api/config \ -H Content-Type: application/json \ -d {settings:{max_sessions:8,wake_words:jarvis}}update_settingsserver.py会通过coerce_setting_valueserver.py按BOOL_SETTINGS/INT_SETTINGS/FLOAT_SETTINGS/DICT_SETTINGS/TUPLE_FLOAT_SETTINGS/OPTIONAL_STRING_SETTINGS严格校验类型非法请求返回 HTTP 400。引擎组合配方Engine Recipes以下配方均面向源码检出中的example_fastapi_server/server.py不适用于安装后的stt-server控制台脚本安装版 CLI 的支持参数请另行查看stt-server --help。默认 faster-whisperGPUpython example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine faster_whisper \ --model small.en \ --realtime-model tiny.en \ --device cuda \ --language enwhisper.cpp CPUfinal 与 realtime 都用 tiny.enpython -m pip install RealtimeSTT[whisper-cpp] python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine whisper_cpp \ --model tiny.en \ --realtime-engine whisper_cpp \ --realtime-model tiny.en \ --device cpu \ --beam-size 5 \ --beam-size-realtime 1 \ --download-root test-model-cache/pywhispercpp \ --engine-options {model:{n_threads:8,redirect_whispercpp_logs_to:null}} \ --realtime-engine-options {model:{n_threads:8,redirect_whispercpp_logs_to:null},transcribe:{single_segment:true,no_context:true,print_timestamps:false}}要点实时车道使用贪婪解码beam size 1与single_segment/no_context以获得更快的 interim 文本--beam-size与--beam-size-realtime是 Whisper 家族直接的速度 vs 质量开关。sherpa-onnx Moonshine CPUpython -m pip install sherpa-onnx python example_fastapi_server/server.py \ --engine sherpa_onnx_moonshine \ --model sherpa-onnx-moonshine-tiny-en-int8 \ --realtime-engine sherpa_onnx_moonshine \ --realtime-model sherpa-onnx-moonshine-tiny-en-int8 \ --device cpu \ --language en \ --download-root test-model-cache/sherpa-onnx \ --engine-options {num_threads:2,provider:cpu} \ --realtime-engine-options {num_threads:2,provider:cpu} \ --realtime-processing-pause 0.8 \ --realtime-use-syllable-boundaries更省内存的组合是 final 用 Base、realtime 用 Tiny--realtime-use-syllable-boundaries开启声学边界调度可与--realtime-boundary-detector-sensitivity 0.6、--realtime-boundary-followup-delays 0.1,0.2,0.4配合。Kroko-ONNX CPU同一模型同时服务 final 与 realtimePowerShell 示例$model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data python example_fastapi_server\server.py --engine kroko_onnx --model $model --realtime-engine kroko_onnx --realtime-model $model --device cpu --language en --engine-options {provider:cpu,num_threads:2} --realtime-engine-options {provider:cpu,num_threads:1}Kroko-ONNX final 轻量实时引擎$model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data python example_fastapi_server\server.py --engine kroko_onnx --model $model --realtime-engine whisper_cpp --realtime-model tiny.en --device cpu --language en --engine-options {provider:cpu,num_threads:2}Parakeet final 小型实时模型GPUpython example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --realtime-engine faster_whisper \ --realtime-model tiny.en \ --device cuda \ --language enParakeet 使用 NeMo 解码栈--beam-size不适用因此服务器为 Parakeet 提供了三个通过批大小、实时节拍与 VAD/分段时机调延迟的档案见上文--profile。Meta Omnilingual ASRLinux / WSL2 Python 3.11.x单 CTC 模型车道PYTHONPATH. python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine omnilingual_asr \ --model omniASR_CTC_1B_v2 \ --realtime-engine omnilingual_asr \ --realtime-model omniASR_CTC_1B_v2 \ --use-main-model-for-realtime \ --device cuda \ --compute-type float16 \ --realtime-processing-pause 0.05 \ --engine-options {batch_size:1,sample_rate:16000}WSL2 场景下Windows 浏览器在 localhost 转发开启时直接打开http://localhost:8010即可。该配方同样面向源码检出stt-server安装版 CLI 的选项需单独确认。唤醒词模式Porcupinepython example_fastapi_server/server.py \ --engine faster_whisper \ --model small.en \ --realtime-model tiny.en \ --wakeword-backend pvporcupine \ --wake-words jarvis \ --wake-words-sensitivity 0.7 \ --wake-word-timeout 5 \ --wake-word-followup-window 5WebSocket 协议详解浏览器向/ws/transcribe发送二进制音频包包格式为前 4 字节little-endian 无符号整数表示元数据长度随后是 UTF-8 编码的 JSON 元数据最后是 16-bit little-endian 单声道 PCM 音频字节。元数据示例{ sampleRate: 48000, channels: 1, format: pcm_s16le, frames: 1920 }协议编解码实现位于 example_fastapi_server/protocol.pyencode_audio_packet/decode_audio_packet严格校验元数据长度上限MAX_METADATA_BYTES 64 * 1024、JSON 合法性、payload 与frames字段一致性服务端解析见packet_to_server_samplesserver.py它仅接受pcm_s16le、通道数 1-8多通道会取均值降为单声道并重采样到服务端标准 16 kHz。文本命令是 JSON 对象{type: start}支持的命令start开始接收音频未 start 前音频包会被拒绝stop结束当前录音并冲刷缓冲音频回到 idleclear仅重置本会话的转写取消本会话排队中的过期作业并递增 generation 使旧结果失效ping服务端回pongmetrics服务端返回本会话的snapshot()指标服务端事件类型hello握手时分配clientId与sessionId附当前设置、限制与受支持引擎ready模型车道初始化完成含ok健康标志与启动错误timeline唤醒词状态、录音开始/结束、实时更新、final 转写开始、final 文本投递等时序事件realtime会话内segmentId的 interim 文本含可选的结构化稳定化字段stableText、unstableText、consensusText、isOutlier、commitReason等见_on_realtime_stabilization_eventserver.pyfinal同一segmentId的最终文本status会话/服务器状态idle/listening/wakeword_wait/wakeword_detected/recording/transcribing/voice/silence等warning可恢复问题如活跃说话人上限警告、realtime 过载丢包error命令、包格式、准入或运行时错误clear本会话转写重置带nextSegmentIdpongping 响应metrics按会话的指标响应。携带转写的realtime/final事件都带sessionId只路由到对应会话不会串音。realtime与final事件可能携带segment对象其中包含录音开始/结束时间戳、时长、预卷缓冲范围preRecordingBuffer.configuredSeconds/includedSeconds以及可用时的唤醒词时序wakeWord.detectedAt等见SegmentTimelineTrackerserver.py。指标与健康检查就绪检查与基础负载curl http://localhost:8010/health返回ok、ready、activeSessions、activeSpeakers、rejectedSessions、scheduler快照与startupErrors。运维细节curl http://localhost:8010/api/metrics指标涵盖活跃会话数、调度器健康度、队列深度按会话的 final/realtime 队列、合并的实时作业数coalescedRealtime、丢弃的过期作业数staleRealtimeDropped、p50/p95 队列延迟与推理延迟RunningStats计算见 server.py、工作线程忙占比busyRatio以及每会话的提交/完成/拒绝计数。浏览器 UI 行为UI 通过 JavaScript 连接/ws/transcribe发送浏览器麦克风音频包并按segmentId关联会话内的实时与最终转写块。每个转写块展示录音开始、录音结束、时长、预卷以及服务端可用的唤醒时序。左侧时间线列出唤醒等待/检测/超时事件、录音开始/结束、实时更新与最终文本投递。clear/重置只影响发起会话。准入限制是显式的当达到--max-sessions时新 WebSocket 客户端收到准入错误并以关闭码1013Try Again Later断开见 server.py当活跃说话人容量达到上限时已接受会话收到警告在可能的情况下保留既有 final 作业。测试快速假调度器测试不加载 ASR 模型python -m unittest -v \ tests.unit.test_fastapi_server_protocol \ tests.unit.test_fastapi_server_multi_user对应的源码位于 tests/unit/test_fastapi_server_protocol.py 与 tests/unit/test_fastapi_server_multi_user.py通过CollectingManager与假调度器验证协议编解码、会话隔离与多用户行为。可选的真实引擎负载/质量/性能测试该测试并行向多个会话流式灌入 tests/unit/audio/asr-reference.wav并将 final 转写与 tests/unit/audio/asr-reference.expected_sentences.json 比对随后输出每次运行的时序报告REALTIMESTT_RUN_FASTAPI_MULTI_USER_PERF1 \ python -m unittest -v tests.unit.test_fastapi_server_multi_user_asr_integration测试实现见 tests/unit/test_fastapi_server_multi_user_asr_integration.py。可用环境变量覆盖REALTIMESTT_FASTAPI_ASR_CLIENTS并发数、REALTIMESTT_FASTAPI_ASR_ENGINE/MODEL/REALTIME_ENGINE/REALTIME_MODEL、REALTIMESTT_FASTAPI_ASR_DEVICE、REALTIMESTT_FASTAPI_ASR_MAX_WER默认0.30、引擎选项变量接受 JSON 或keyvalue列表方便 Windows cmd.exe等设REALTIMESTT_FASTAPI_ASR_METRICS_JSON/path/to/report.json可额外写出 JSON 报告。Windowscmd.exe下 4 客户端 sherpa-onnx Moonshine 性能运行的现成脚本example_fastapi_server\run_multi_user_perf.cmd可先覆盖所需变量再调用例如set REALTIMESTT_FASTAPI_ASR_CLIENTS8 set REALTIMESTT_FASTAPI_ASR_METRICS_JSONtest-results\fastapi-8-user-perf.json example_fastapi_server\run_multi_user_perf.cmd更多测试细节见 testing.md。部署注意事项平台选择CUDA 重负载引擎Parakeet、Qwen vLLM、较大的 Transformers 模型请使用 Linux 或 WSL2Omnilingual ASR 目前需要 Linux/WSL2 且 Python 3.11.x。Kroko-ONNX需先以RealtimeSTT[kroko-builder,silero-onnx-cpu]安装并用stt-install-kroko --build构建再在 recorder 型服务器使用中选择kroko_onnxWindows 上需 Python 3.12 x64 且先启动 Docker Desktop。模型缓存将模型缓存放在持久化存储上避免重启后重复下载模型用--download-root指定。反向代理暴露到 localhost 之外时把服务器放到反向代理之后。容量规划根据所选引擎与硬件为--max-sessions、--max-active-speakers、队列深度与模型车道数合理定容。监控用/health做就绪探测用/api/metrics做负载与延迟监控结合--realtime-degradation-threshold-ms判断实时调度是否降级。【免费下载链接】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），仅供参考 RealtimeSTT FastAPI 浏览器流式服务完全指南：部署、配置、WebSocket 协议与多用户调度
RealtimeSTT FastAPI 浏览器流式服务完全指南部署、配置、WebSocket 协议与多用户调度【免费下载链接】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本文是 RealtimeSTT 官方浏览器流式参考服务example_fastapi_server的完整技术指南覆盖从安装启动、引擎组合到多会话调度与监控的全链路。读完本文你将掌握如何把浏览器麦克风音频通过 WebSocket 实时推入 RealtimeSTT 的按会话录音状态机如何用共享推理车道final/realtime 双车道承载多用户并发如何通过/api/config做运行时热配置以及如何用/health与/api/metrics做容量评估与延迟监控。服务定位源码仓库专属的浏览器参考实现example_fastapi_server是 RealtimeSTT 的浏览器流式参考应用它同时提供本地浏览器 UI 和一个 WebSocket 端点将浏览器麦克风音频流入按会话隔离的 recorder 状态机见 example_fastapi_server/server.py 与 example_fastapi_server/static/index.html。需要特别注意的是该参考服务只面向源码检出source checkout场景不会随 PyPI wheel 一起安装。保持源码化可以让 wheel 保持精简也避免给仅需 recorder/API 库的用户引入额外的 Web 服务器依赖。因此仅通过pip install RealtimeSTT安装的用户请改用仓库内的 Python recorder/API 示例例如 tests/simple_test.py、tests/realtimestt_test.py 或 tests/openai_voice_interface.py想使用 FastAPI 参考服务器请 clone 本仓库或从 Git 安装后在源码根目录运行。从源码结构看server.py服务端的核心装配是RealtimeSTTService持有SessionStore会话准入与InferenceScheduler共享推理调度器FastAPI 应用通过 lifespan 启动服务与调度器。这也印证了文档中每个会话是轻量状态机、重型 ASR 引擎全局共享的设计。安装与运行安装依赖创建独立虚拟环境并安装项目依赖与服务器依赖Linux/macOS bashpython -m venv .venv-fastapi source .venv-fastapi/bin/activate python -m pip install -U pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -r example_fastapi_server/requirements.txtWindows PowerShell 对应版本python -m venv .venv-fastapi .\.venv-fastapi\Scripts\Activate.ps1 python -m pip install -U pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -r example_fastapi_server\requirements.txt服务器自身的最小依赖见 example_fastapi_server/requirements.txtfastapi0.115、uvicorn[standard]0.30、numpy、scipy。若缺少这些依赖server.py 会抛出明确提示引导安装。随后按需安装计划运行的可选引擎栈完整清单见 transcription-engines.md。仓库内的 tests/install_extras_matrix.py 与 tests/install_packages.py 提供了可选依赖矩阵的安装脚本可作为安装参考。启动服务器python example_fastapi_server/server.py --host 0.0.0.0 --port 8010打开浏览器访问http://localhost:8010服务器总体设计按会话隔离、按模型共享服务器接受多个浏览器会话。每个 WebSocket 在握手时由服务端分配一个sessionId实现为uuid4().hex见 server.py此后该会话的音频缓冲、VAD 状态、转写段 IDsegmentId、clear/reset 命令、实时文本、最终文本、警告与错误全部限定在该会话作用域内。从 server.py 与 server.py 可以看到两类会话实现RealtimeSession服务端自行维护 VAD 与分段的内联会话主要用于单元测试RecorderBackedRealtimeSession每个会话内部持有一个轻量级AudioToTextRecorder流状态机浏览器服务器由此完整继承了 recorder 已有的 WebRTC VAD、Silero VAD、唤醒词钩子、early-final 转写与音节边界实时调度。它把transcription_executor/realtime_transcription_executor注入为共享调度器执行器见 server.py因此重型 ASR 引擎由全局共享的工作线程加载而不是每个浏览器各自加载一份模型。InferenceSchedulerserver.py按use_main_model_for_realtime决定资源布局默认平衡模式一条共享 final 模型车道 一条共享 realtime 模型车道低内存模式--use-main-model-for-realtime让两条队列共用同一条模型车道。VAD 状态刻意保持按会话隔离。WebRTC/Silero 检测在流层面是有状态的若把单个共享 VAD 对象用于多路音频流会带来正确性风险权重、循环状态、线程访问都无法按会话分离。example_fastapi_server/MULTI_USER_IMPLEMENTATION_GUIDE.md 详细记录了这一多用户化改造的原则per-session 状态会话 ID、websocket、分段 ID、VAD/录音状态、音频有界队列、实时调度状态、配额与丢弃计数与 shared 推理资源共享模型、公平调度器、全局准入控制严格分层。公平调度与过载保护FairInferenceQueueserver.py实现按会话公平的调度final 作业按会话排队受max_final_queue_depth_per_session与max_global_inference_queue_depth双重限制realtime 作业每会话只保留最新一个新提交会以coalesced合并方式替换旧作业避免嘈杂客户端用过期中间结果灌满全局队列过期 realtime 作业在出队时按deadline_at由max_realtime_queue_age_ms折算判定为stale直接丢弃会话断开或 clear 时通过cancel_session清理该会话在队列中的所有作业。HTTP 端点一览服务器暴露以下端点见 server.py端点作用GET /返回浏览器 UIstatic/index.htmlGET /health就绪状态、活跃会话/说话人数、启动错误、调度器状态GET /api/config公开配置、容量限制、受支持的引擎列表PATCH /api/config运行时热更新部分配置GET /api/metrics计数器、队列深度、延迟、合并/丢弃统计、工作线程利用率WS /ws/transcribe浏览器音频流与控制命令通道配置参数全表核心引擎参数Flag含义默认值见 server.pyServerSettings--engine,--transcription-enginefinal 转写引擎faster_whisper--modelfinal 模型名或路径small.en--realtime-engine,--realtime-transcription-engine实时引擎缺省时与 final 引擎相同None回退到 final 引擎--realtime-model实时模型名或路径tiny.en--engine-options传给 final 引擎的 JSON 对象None--realtime-engine-options传给实时引擎的 JSON 对象None--download-root模型缓存或查找根目录None--devicecuda或cpucudaeffective_device会在 CUDA 不可用时自动回退cpu见 server.py--compute-type引擎精度/量化提示default--language语言代码en--use-main-model-for-realtime用一条共享模型车道同时服务 final 与 realtimeFalse引擎名在服务端经过normalize_engine_name归一化strip().lower().replace(-, _)见 example_fastapi_server/protocol.py因此whisper-cpp、sherpa-onnx-moonshine、kroko-onnx等连字符写法均可接受。可用的引擎注册表见 RealtimeSTT/transcription_engines/factory.py。VAD 与转写时机参数Flag含义默认值--min-length-of-recording最小录音时长秒不足则放弃该段0.2--min-gap-between-recordings两次录音之间的最小间隔0.0--post-speech-silence-duration结束一句话前所需的静音时长秒0.55--silero-sensitivitySilero VAD 灵敏度0.05--webrtc-sensitivityWebRTC VAD 激进程度0-3 整数3--early-transcription-on-silence静音期启动投机式 final 转写0.2--pre-recording-buffer-duration每会话预卷pre-roll时长秒在有语音前持续缓存音频语音出现时并入段首0.75--realtime-processing-pause实时更新固定节拍秒0.02--realtime-use-syllable-boundaries启用声学边界调度realtime 用音节边界切分False--realtime-boundary-detector-sensitivity边界检测器灵敏度0.6--realtime-boundary-followup-delays逗号分隔的实时补充延迟列表秒(0.05, 0.2)realtime_processing_pause与realtime_min_audio_seconds0.25、realtime_max_audio_seconds20.0共同决定实时作业的产生节奏_maybe_create_realtime_job_lockedserver.py在节拍窗口内、且已录制音频超过最小秒数时才提交实时作业音频窗口超过最大秒数时仅取末尾片段参与实时推断。唤醒词参数Flag含义--wakeword-backend传给AudioToTextRecorder的唤醒词后端例如pvporcupine或openwakeword--wake-words逗号分隔的唤醒词或所选后端的模型名--wake-words-sensitivity唤醒词检测灵敏度默认0.5--wake-word-activation-delay唤醒词模式生效前的延迟默认0.0--wake-word-timeout唤醒检测后等待语音的时间超时回到唤醒等待态默认5.0--wake-word-buffer-duration从录音段开头移除的唤醒词音频时长默认0.1--wake-word-followup-window录音结束后的可选宽限窗口期间会话保持在 Voice 模式后续语音无需重复唤醒词即可直接开始默认0.0即关闭--openwakeword-model-paths逗号分隔的 OpenWakeWord 模型路径--openwakeword-inference-frameworkOpenWakeWord 推理框架默认onnx唤醒词的wake_word_enabled()判定条件是后端与唤醒词均非空见 server.py。Follow-up 窗口的实现细节见_start_wakeword_followup_windowserver.py它在录音结束后临时把 recorder 的wakeword_detected置真并缩短超时窗口结束时恢复原值。容量与调度参数Flag含义默认值--max-sessions最大接受的浏览器会话数4--max-active-speakers最大并发活跃说话人数4--audio-queue-size每会话输入队列大小128--max-audio-packet-bytes单个二进制包最大字节数512 * 1024512 KiB--max-audio-queue-seconds-per-session强制结束超长连续录音秒30.0--max-realtime-queue-age-ms丢弃过期的实时作业毫秒1500--max-final-queue-depth-per-session限制每会话 final 积压8--max-global-inference-queue-depth全局调度器队列上限64--realtime-degradation-threshold-ms实时调度降级阈值毫秒1500--realtime-min-audio-seconds实时作业最小音频时长秒0.25--realtime-max-audio-seconds实时作业最大音频时长秒20.0--vad-energy-threshold服务端使用的音频能量门限RMS 阈值250.0--no-model-warmup禁用模型预热默认开启预热会话准入采用先预留、后构造的机制SessionStore.reserveserver.py会话槽位在构造 recorder/VAD 之前预留因此并发连接突发不会实例化出超过--max-sessions数量的 recorder。音频包只有在收到start命令后才被接受recorder 输入队列用--audio-queue-size映射为 recorder 的allowed_latency_limit约束连续录音达到--max-audio-queue-seconds-per-session会被强制 finalize_force_finalize_after_limitserver.py已完成录音的积压按--max-final-queue-depth-per-session裁剪_trim_recorded_audio_queueserver.py。此外还有命名调优档案可通过--profile选择显式 flag 会覆盖档案默认值见 server.pycustom使用显式 CLI 参数/默认值parakeet-low-latency面向频繁 interim 更新realtime_processing_pause0.04、post_speech_silence_duration0.45等parakeet-balanced兼顾延迟与最终稳定性realtime_processing_pause0.06、post_speech_silence_duration0.55parakeet-accurate-final偏向平静分段与最终质量realtime_processing_pause0.1、post_speech_silence_duration0.7。运行时配置契约Runtime SettingsGET /api/config返回的runtimeSettings契约把配置分成三类见 server.py 与runtime_settings_contractserver.pyactiveSessionSafe可热更新并立即影响正在运行的服务如log_level、max_sessions、max_active_speakers、max_audio_packet_bytes、max_final_queue_depth_per_session、max_global_inference_queue_depth、max_realtime_queue_age_ms、realtime_degradation_threshold_msnewSessionOnly只复制进未来新建的浏览器会话已有会话保持自己的 recorder 配置如 VAD/唤醒词/分段/实时节拍类参数startupOnly包括 ASR 引擎与模型路径在内的参数因共享推理工作线程已初始化而被拒绝如engine、model、device、compute_type、download_root、batch_size、beam_size等修改它们需要重启服务器。热更新示例curl -X PATCH http://localhost:8010/api/config \ -H Content-Type: application/json \ -d {settings:{max_sessions:8,wake_words:jarvis}}update_settingsserver.py会通过coerce_setting_valueserver.py按BOOL_SETTINGS/INT_SETTINGS/FLOAT_SETTINGS/DICT_SETTINGS/TUPLE_FLOAT_SETTINGS/OPTIONAL_STRING_SETTINGS严格校验类型非法请求返回 HTTP 400。引擎组合配方Engine Recipes以下配方均面向源码检出中的example_fastapi_server/server.py不适用于安装后的stt-server控制台脚本安装版 CLI 的支持参数请另行查看stt-server --help。默认 faster-whisperGPUpython example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine faster_whisper \ --model small.en \ --realtime-model tiny.en \ --device cuda \ --language enwhisper.cpp CPUfinal 与 realtime 都用 tiny.enpython -m pip install RealtimeSTT[whisper-cpp] python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine whisper_cpp \ --model tiny.en \ --realtime-engine whisper_cpp \ --realtime-model tiny.en \ --device cpu \ --beam-size 5 \ --beam-size-realtime 1 \ --download-root test-model-cache/pywhispercpp \ --engine-options {model:{n_threads:8,redirect_whispercpp_logs_to:null}} \ --realtime-engine-options {model:{n_threads:8,redirect_whispercpp_logs_to:null},transcribe:{single_segment:true,no_context:true,print_timestamps:false}}要点实时车道使用贪婪解码beam size 1与single_segment/no_context以获得更快的 interim 文本--beam-size与--beam-size-realtime是 Whisper 家族直接的速度 vs 质量开关。sherpa-onnx Moonshine CPUpython -m pip install sherpa-onnx python example_fastapi_server/server.py \ --engine sherpa_onnx_moonshine \ --model sherpa-onnx-moonshine-tiny-en-int8 \ --realtime-engine sherpa_onnx_moonshine \ --realtime-model sherpa-onnx-moonshine-tiny-en-int8 \ --device cpu \ --language en \ --download-root test-model-cache/sherpa-onnx \ --engine-options {num_threads:2,provider:cpu} \ --realtime-engine-options {num_threads:2,provider:cpu} \ --realtime-processing-pause 0.8 \ --realtime-use-syllable-boundaries更省内存的组合是 final 用 Base、realtime 用 Tiny--realtime-use-syllable-boundaries开启声学边界调度可与--realtime-boundary-detector-sensitivity 0.6、--realtime-boundary-followup-delays 0.1,0.2,0.4配合。Kroko-ONNX CPU同一模型同时服务 final 与 realtimePowerShell 示例$model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data python example_fastapi_server\server.py --engine kroko_onnx --model $model --realtime-engine kroko_onnx --realtime-model $model --device cpu --language en --engine-options {provider:cpu,num_threads:2} --realtime-engine-options {provider:cpu,num_threads:1}Kroko-ONNX final 轻量实时引擎$model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data python example_fastapi_server\server.py --engine kroko_onnx --model $model --realtime-engine whisper_cpp --realtime-model tiny.en --device cpu --language en --engine-options {provider:cpu,num_threads:2}Parakeet final 小型实时模型GPUpython example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --realtime-engine faster_whisper \ --realtime-model tiny.en \ --device cuda \ --language enParakeet 使用 NeMo 解码栈--beam-size不适用因此服务器为 Parakeet 提供了三个通过批大小、实时节拍与 VAD/分段时机调延迟的档案见上文--profile。Meta Omnilingual ASRLinux / WSL2 Python 3.11.x单 CTC 模型车道PYTHONPATH. python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine omnilingual_asr \ --model omniASR_CTC_1B_v2 \ --realtime-engine omnilingual_asr \ --realtime-model omniASR_CTC_1B_v2 \ --use-main-model-for-realtime \ --device cuda \ --compute-type float16 \ --realtime-processing-pause 0.05 \ --engine-options {batch_size:1,sample_rate:16000}WSL2 场景下Windows 浏览器在 localhost 转发开启时直接打开http://localhost:8010即可。该配方同样面向源码检出stt-server安装版 CLI 的选项需单独确认。唤醒词模式Porcupinepython example_fastapi_server/server.py \ --engine faster_whisper \ --model small.en \ --realtime-model tiny.en \ --wakeword-backend pvporcupine \ --wake-words jarvis \ --wake-words-sensitivity 0.7 \ --wake-word-timeout 5 \ --wake-word-followup-window 5WebSocket 协议详解浏览器向/ws/transcribe发送二进制音频包包格式为前 4 字节little-endian 无符号整数表示元数据长度随后是 UTF-8 编码的 JSON 元数据最后是 16-bit little-endian 单声道 PCM 音频字节。元数据示例{ sampleRate: 48000, channels: 1, format: pcm_s16le, frames: 1920 }协议编解码实现位于 example_fastapi_server/protocol.pyencode_audio_packet/decode_audio_packet严格校验元数据长度上限MAX_METADATA_BYTES 64 * 1024、JSON 合法性、payload 与frames字段一致性服务端解析见packet_to_server_samplesserver.py它仅接受pcm_s16le、通道数 1-8多通道会取均值降为单声道并重采样到服务端标准 16 kHz。文本命令是 JSON 对象{type: start}支持的命令start开始接收音频未 start 前音频包会被拒绝stop结束当前录音并冲刷缓冲音频回到 idleclear仅重置本会话的转写取消本会话排队中的过期作业并递增 generation 使旧结果失效ping服务端回pongmetrics服务端返回本会话的snapshot()指标服务端事件类型hello握手时分配clientId与sessionId附当前设置、限制与受支持引擎ready模型车道初始化完成含ok健康标志与启动错误timeline唤醒词状态、录音开始/结束、实时更新、final 转写开始、final 文本投递等时序事件realtime会话内segmentId的 interim 文本含可选的结构化稳定化字段stableText、unstableText、consensusText、isOutlier、commitReason等见_on_realtime_stabilization_eventserver.pyfinal同一segmentId的最终文本status会话/服务器状态idle/listening/wakeword_wait/wakeword_detected/recording/transcribing/voice/silence等warning可恢复问题如活跃说话人上限警告、realtime 过载丢包error命令、包格式、准入或运行时错误clear本会话转写重置带nextSegmentIdpongping 响应metrics按会话的指标响应。携带转写的realtime/final事件都带sessionId只路由到对应会话不会串音。realtime与final事件可能携带segment对象其中包含录音开始/结束时间戳、时长、预卷缓冲范围preRecordingBuffer.configuredSeconds/includedSeconds以及可用时的唤醒词时序wakeWord.detectedAt等见SegmentTimelineTrackerserver.py。指标与健康检查就绪检查与基础负载curl http://localhost:8010/health返回ok、ready、activeSessions、activeSpeakers、rejectedSessions、scheduler快照与startupErrors。运维细节curl http://localhost:8010/api/metrics指标涵盖活跃会话数、调度器健康度、队列深度按会话的 final/realtime 队列、合并的实时作业数coalescedRealtime、丢弃的过期作业数staleRealtimeDropped、p50/p95 队列延迟与推理延迟RunningStats计算见 server.py、工作线程忙占比busyRatio以及每会话的提交/完成/拒绝计数。浏览器 UI 行为UI 通过 JavaScript 连接/ws/transcribe发送浏览器麦克风音频包并按segmentId关联会话内的实时与最终转写块。每个转写块展示录音开始、录音结束、时长、预卷以及服务端可用的唤醒时序。左侧时间线列出唤醒等待/检测/超时事件、录音开始/结束、实时更新与最终文本投递。clear/重置只影响发起会话。准入限制是显式的当达到--max-sessions时新 WebSocket 客户端收到准入错误并以关闭码1013Try Again Later断开见 server.py当活跃说话人容量达到上限时已接受会话收到警告在可能的情况下保留既有 final 作业。测试快速假调度器测试不加载 ASR 模型python -m unittest -v \ tests.unit.test_fastapi_server_protocol \ tests.unit.test_fastapi_server_multi_user对应的源码位于 tests/unit/test_fastapi_server_protocol.py 与 tests/unit/test_fastapi_server_multi_user.py通过CollectingManager与假调度器验证协议编解码、会话隔离与多用户行为。可选的真实引擎负载/质量/性能测试该测试并行向多个会话流式灌入 tests/unit/audio/asr-reference.wav并将 final 转写与 tests/unit/audio/asr-reference.expected_sentences.json 比对随后输出每次运行的时序报告REALTIMESTT_RUN_FASTAPI_MULTI_USER_PERF1 \ python -m unittest -v tests.unit.test_fastapi_server_multi_user_asr_integration测试实现见 tests/unit/test_fastapi_server_multi_user_asr_integration.py。可用环境变量覆盖REALTIMESTT_FASTAPI_ASR_CLIENTS并发数、REALTIMESTT_FASTAPI_ASR_ENGINE/MODEL/REALTIME_ENGINE/REALTIME_MODEL、REALTIMESTT_FASTAPI_ASR_DEVICE、REALTIMESTT_FASTAPI_ASR_MAX_WER默认0.30、引擎选项变量接受 JSON 或keyvalue列表方便 Windows cmd.exe等设REALTIMESTT_FASTAPI_ASR_METRICS_JSON/path/to/report.json可额外写出 JSON 报告。Windowscmd.exe下 4 客户端 sherpa-onnx Moonshine 性能运行的现成脚本example_fastapi_server\run_multi_user_perf.cmd可先覆盖所需变量再调用例如set REALTIMESTT_FASTAPI_ASR_CLIENTS8 set REALTIMESTT_FASTAPI_ASR_METRICS_JSONtest-results\fastapi-8-user-perf.json example_fastapi_server\run_multi_user_perf.cmd更多测试细节见 testing.md。部署注意事项平台选择CUDA 重负载引擎Parakeet、Qwen vLLM、较大的 Transformers 模型请使用 Linux 或 WSL2Omnilingual ASR 目前需要 Linux/WSL2 且 Python 3.11.x。Kroko-ONNX需先以RealtimeSTT[kroko-builder,silero-onnx-cpu]安装并用stt-install-kroko --build构建再在 recorder 型服务器使用中选择kroko_onnxWindows 上需 Python 3.12 x64 且先启动 Docker Desktop。模型缓存将模型缓存放在持久化存储上避免重启后重复下载模型用--download-root指定。反向代理暴露到 localhost 之外时把服务器放到反向代理之后。容量规划根据所选引擎与硬件为--max-sessions、--max-active-speakers、队列深度与模型车道数合理定容。监控用/health做就绪探测用/api/metrics做负载与延迟监控结合--realtime-degradation-threshold-ms判断实时调度是否降级。【免费下载链接】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），仅供参考