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/RealtimeSTTexample_fastapi_server是 RealtimeSTT 官方提供的浏览器流式参考服务器它通过 FastAPI 提供一套可直接使用的 Web UI 与 WebSocket 音频端点把浏览器麦克风流接入 RealtimeSTT并支持多个浏览器会话并发、共享 ASR 模型车道与按会话公平调度的实时转写。读完本文你将掌握该服务器的安装启动、多用户容量规划、运行时热配置、GPU/CPU 各引擎配方、调优 profile、WebSocket 二进制协议与性能测试方法并能直接复用到自己的实时语音产品中。一、服务器定位与总体架构example_fastapi_server的核心是 server.py约 3500 行它承担三件事服务静态浏览器 UIGET /返回 static/index.html暴露 WebSocket 端点WS /ws/transcribe接收浏览器麦克风音频二进制包也接收start/stop/clear等文本命令在服务端维护每会话的转写状态机每个已接受的 WebSocket 会话持有独立的轻量级AudioToTextRecorder状态机继承 RealtimeSTT 的 WebRTC VAD、Silero VAD、唤醒词钩子、early-final 转写与音节边界实时调度能力而重量级 ASR 引擎则被抽取为共享执行器而不是每个浏览器各加载一份模型。从 server.py 的create_app()可以看出完整的端点面端点作用GET /浏览器 UIGET /health就绪状态、活跃会话/说话人数、启动错误、调度器状态GET /api/config公开配置、容量上限、受支持引擎、运行时设置契约PATCH /api/config运行时热更新配置GET /api/metrics每会话计数器、队列深度、合并/丢弃计数、p50/p95 延迟、worker 忙闲比WS /ws/transcribe浏览器音频流与命令通道注意该参考服务器面向**源码检出source checkout**使用PyPI wheel 不包含它。仅用 pip 安装的用户应使用 Python recorder/API 示例需要本服务器时请克隆仓库或从 Git 安装参见 docs/fastapi-server.md。二、安装与环境准备官方推荐使用 Linux 环境运行 CUDA 密集型引擎Parakeet、Qwen vLLM、大型 Transformers 模型完整安装步骤如下python -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.txt服务器自身依赖非常轻——requirements.txt 只有fastapi0.115、uvicorn[standard]0.30、numpy、scipy四项。重依赖全部来自所选的转写引擎栈。可选引擎栈安装按需安装你计划运行的引擎对应 README 与 docs/transcription-engines.md# ParakeetNeMoCUDA python -m pip install nemo_toolkit[asr] soundfile librosa # CPU whisper.cpp python -m pip install pywhispercpp # CPU sherpa-onnx Moonshine python -m pip install sherpa-onnx # Meta Omnilingual ASRLinux/WSL2 python -m pip install RealtimeSTT[omnilingual] # 源码检出时使用 python -m pip install -e .[omnilingual]Kroko-ONNX 需要单独构建上游当前偏向 Linux/DockerWindows 原生构建失败时请改用 WSL2/Linux 运行服务器git clone https://github.com/kroko-ai/kroko-onnx.git cd kroko-onnx python -m pip install .三、快速启动默认 faster-whisper 配置python example_fastapi_server/server.py --host 0.0.0.0 --port 8010然后浏览器打开http://localhost:8010即可开始麦克风流式转写。命令行参数全部由 parse_args() 解析、settings_from_args() 组装成ServerSettings。核心引擎参数见下表默认值取自 ServerSettingsFlag含义默认值--engine/--transcription-engine最终转写引擎faster_whisper--model最终模型名或路径small.en--realtime-engine/--realtime-transcription-engine实时引擎省略时复用最终引擎无--realtime-model实时模型名或路径tiny.en--engine-options传给最终引擎的 JSON 对象无--realtime-engine-options传给实时引擎的 JSON 对象无--download-root模型缓存/查找根目录无--devicecuda或cpucuda--compute-type引擎精度/量化提示default--language语言代码en--use-main-model-for-realtime用单条共享模型车道同时承担实时与最终转写低内存模式关闭四、多用户会话架构深入4.1 会话级隔离session-scoped服务器接受多个独立浏览器会话。每个 WebSocket 被分配一个sessionId以下内容全部按会话隔离音频缓冲区、VAD 状态、转写片段segmentId、clear/reset 命令、实时文本、最终文本、状态、警告与错误参见 README。SegmentStateserver.py维护会话内的片段号生成逻辑实时事件与最终事件共享同一个segmentId最终文本到达后 UI 用最终块替换实时块。SegmentTimelineTrackerserver.py为每个片段记录录音起止时间戳、时长、pre-roll 范围与唤醒词时间线。4.2 VAD 为什么按会话隔离服务器刻意让 VAD会话级隔离。WebRTC/Silero 检测在流级别是有状态的模型权重、循环状态、线程访问若多个会话共享单个 VAD 对象除非实现能证明按会话分离模型权重、循环状态与线程访问否则就是正确性风险。README 明确指出未来优化可以共享不可变的 VAD 权重但必须保持每会话的 VAD 状态与重置语义README。在每个会话内部VoiceActivityDetector 优先使用 WebRTC VADwebrtcvad.Vadaggressiveness 由--webrtc-sensitivity指定无法加载时回退到基于 RMS 的能量 VAD阈值由--vad-energy-threshold控制默认 250.0。4.3 共享模型车道shared model lanes模型资源按车道共享而不是每个浏览器一份模型副本默认均衡模式一条共享最终模型车道 一条共享实时模型车道低内存模式--use-main-model-for-realtime让一条共享模型车道同时负责实时与最终转写。InferenceSchedulerserver.py负责创建车道main_worker用--engine/--modelrealtime_worker用--realtime-engine/--realtime-model未指定时回退到最终引擎。每条车道由SharedEngineWorkerserver.py在独立后台线程中驱动并在启动时用 RealtimeSTT/assets/warmup_audio.wav 做模型预热每个会话在 recorder 构造时也会预热 VAD 路径避免第一段语音付出 Silero/WebRTC 懒加载的运行期成本warmup_vad由--no-model-warmup关闭见 server.py。4.4 公平调度队列推理任务通过每会话公平队列调度FairInferenceQueueserver.py最终任务final按会话保留到--max-final-queue-depth-per-session上限超出即拒绝实时任务realtime同一会话的新实时任务会**合并coalesce**旧的未执行实时任务只保留最新一帧超过--max-realtime-queue-age-ms的陈旧任务直接丢弃。这样设计保证一个嘈杂客户端无法用过期的 interim 工作灌满全局队列同时队列在会话之间轮转round-robin没有会话会饿死其他会话。这些行为都有单元测试直接验证例如 test_fastapi_server_protocol.py 中的test_fair_queue_coalesces_realtime_but_preserves_finals、test_fair_queue_round_robins_between_sessions与test_fair_queue_drops_stale_realtime_jobs。4.5 容量控制参数容量是显式可配置的。官方推荐的容量参数组合READMEpython example_fastapi_server/server.py \ --max-sessions 4 \ --max-active-speakers 4 \ --max-global-inference-queue-depth 64 \ --max-final-queue-depth-per-session 8 \ --max-realtime-queue-age-ms 1500 \ --max-audio-queue-seconds-per-session 30各容量参数语义实现于SessionStore/RealtimeSession见 server.py参数默认值作用--max-sessions4最大浏览器会话数超出直接拒绝WebSocket 关闭码 1013--max-active-speakers4最大并发说话人数超出仅告警已接收会话继续尽可能保留最终转写--max-global-inference-queue-depth64全局推理队列总上限--max-final-queue-depth-per-session8每会话最终任务积压上限超出的 recorded segment 被裁剪丢弃--max-realtime-queue-age-ms1500实时任务最大排队年龄过期丢弃--max-audio-queue-seconds-per-session30.0单会话连续录音超过该时长被强制 finalize--audio-queue-size128每会话输入队列大小映射到 recorder 的allowed_latency_limit--max-audio-packet-bytes512KB单个二进制音频包上限--pre-recording-buffer-duration0.75每会话 pre-roll预录音缓冲时长会话插槽在构造 recorder/VAD之前被预留SessionStore.reserve()因此并发连接洪峰也不会实例化出超过会话上限的 recorder音频包只有在收到start命令之后才被接受见 server.py 中“Audio stream is stopped”的拒绝逻辑。长时间连续录音会在达到--max-audio-queue-seconds-per-session时被强制 finalize_force_finalize_after_limitserver.py。五、运行时配置GET/PATCH /api/config服务器的运行时可安全配置项通过GET /api/config暴露响应中的runtimeSettings契约实现于 runtime_settings_contract()把设置分成三类activeSessionSafe立即作用于正在运行的会话如max_sessions、max_active_speakers、各队列深度newSessionOnly仅复制到未来的浏览器会话已存在的会话保留其 recorder 配置如wake_words、silero_sensitivity、post_speech_silence_duration等 VAD/唤醒词/实时转写参数startupOnly因为共享推理 worker 已初始化而需要重启如引擎、模型路径、batch_size、beam_size、device热更新会被明确拒绝。三类全集分别定义在 ACTIVE_RUNTIME_SETTINGS、NEW_SESSION_RUNTIME_SETTINGS 与 STARTUP_ONLY_SETTINGS。值的类型校验由 coerce_setting_value() 依据INT_SETTINGS/FLOAT_SETTINGS/BOOL_SETTINGS/DICT_SETTINGS/TUPLE_FLOAT_SETTINGS分类表完成。示例把max_sessions提到 8 并给后续会话启用唤醒词jarviscurl -X PATCH http://localhost:8010/api/config \ -H Content-Type: application/json \ -d {settings:{max_sessions:8,wake_words:jarvis}}响应会逐项给出applied含appliesTo: active_sessions/new_sessions与rejected含reason: startup_only/unknown/invalid_value其行为被单元测试test_runtime_settings_update_distinguishes_safe_and_startup_only_fields覆盖test_fastapi_server_protocol.py。唤醒词模式唤醒词配置直接透传给每个浏览器会话的 recorderpython example_fastapi_server/server.py \ --wakeword-backend pvporcupine \ --wake-words jarvis \ --wake-words-sensitivity 0.7 \ --wake-word-timeout 5 \ --wake-word-followup-window 5相关 flag 还包括--wake-word-activation-delay唤醒模式延迟生效、--wake-word-buffer-duration从录音开头剥离的唤醒词音频、--openwakeword-model-paths、--openwakeword-inference-framework默认onnx。唤醒等待、检测、后续语音窗口、超时、录音开始/结束、实时与最终转写等状态迁移都会以timelineWebSocket 事件呈现并在浏览器 UI 中展示转写块携带片段时间、时长、pre-roll 与唤醒检测元数据实现于SegmentTimelineTracker与_publish_timeline_eventserver.py。六、GPU 引擎配方6.1 Parakeet 最终转写 小实时 Whisper 模型export HF_HOME$HOME/.cache/huggingface python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --realtime-engine faster_whisper \ --realtime-model tiny.en \ --device cuda \ --language en6.2 Parakeet 同时承担实时与最终转写python example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --use-main-model-for-realtime \ --profile parakeet-low-latency \ --device cuda \ --language en6.3 Meta Omnilingual ASRLinux 或 WSL2单条 CTC 模型车道同时负责实时与最终转写用--use-main-model-for-realtime合并车道以省显存PYTHONPATH. python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine omnilingual_asr \ --model omniASR_CTC_300M_v2 \ --realtime-engine omnilingual_asr \ --realtime-model omniASR_CTC_300M_v2 \ --use-main-model-for-realtime \ --device cuda \ --compute-type float16 \ --language eng_Latn \ --engine-options {batch_size:1,sample_rate:16000}WSL2 开启 localhost 转发后可在 Windows 浏览器直接打开http://localhost:8010。300M 模型跑通后若 GPU 显存足够可尝试omniASR_CTC_1B_v2。七、CPU 引擎配方Windows cmd.exe以下命令面向 Windowscmd.exe需在仓库根目录执行先用set PYTHON_EXEpython指向正确的解释器或虚拟环境中的 python。7.1 whisper.cpp CPU用tiny.en同时承担实时与最终转写实时侧使用 greedy 解码和 single-segment/no-context 设置换取更快的 interim 文本%PYTHON_EXE% 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}}7.2 sherpa-onnx Moonshine CPU一次性下载并解压 Tiny 与 Base 两个 int8 模型到test-model-cache\sherpa-onnxmkdir test-model-cache\sherpa-onnx curl.exe -L -o test-model-cache\sherpa-onnx\sherpa-onnx-moonshine-tiny-en-int8.tar.bz2 https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-moonshine-tiny-en-int8.tar.bz2 %PYTHON_EXE% -c import tarfile; tarfile.open(rtest-model-cache\sherpa-onnx\sherpa-onnx-moonshine-tiny-en-int8.tar.bz2, r:bz2).extractall(rtest-model-cache\sherpa-onnx) curl.exe -L -o test-model-cache\sherpa-onnx\sherpa-onnx-moonshine-base-en-int8.tar.bz2 https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-moonshine-base-en-int8.tar.bz2 %PYTHON_EXE% -c import tarfile; tarfile.open(rtest-model-cache\sherpa-onnx\sherpa-onnx-moonshine-base-en-int8.tar.bz2, r:bz2).extractall(rtest-model-cache\sherpa-onnx)Base 负责最终转写、Tiny 负责实时转写启用音节边界实时调度%PYTHON_EXE% example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine sherpa_onnx_moonshine --model sherpa-onnx-moonshine-base-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\:4,\provider\:\cpu\} --realtime-engine-options {\num_threads\:2,\provider\:\cpu\} --realtime-processing-pause 0.8 --realtime-use-syllable-boundaries --realtime-boundary-detector-sensitivity 0.6 --realtime-boundary-followup-delays 0.1,0.2,0.4需要更低内存时用 Tiny 同时承担最终与实时转写%PYTHON_EXE% example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --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 --realtime-boundary-detector-sensitivity 0.6 --realtime-boundary-followup-delays 0.1,0.2,0.47.3 Kroko-ONNX CPU一次性下载社区英文流式模型mkdir test-model-cache\kroko-onnx python -c from huggingface_hub import hf_hub_download; hf_hub_download(repo_idBanafo/Kroko-ASR, filenameKroko-EN-Community-64-L-Streaming-001.data, local_dirtest-model-cache/kroko-onnx)Kroko 同时承担最终与实时转写python example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine kroko_onnx --model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --realtime-engine kroko_onnx --realtime-model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --device cpu --language en --engine-options {\provider\:\cpu\,\num_threads\:2} --realtime-engine-options {\provider\:\cpu\,\num_threads\:1}或 Kroko 负责最终文本、轻量 whisper.cpp 负责实时python example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine kroko_onnx --model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --realtime-engine whisper_cpp --realtime-model tiny.en --device cpu --language en --engine-options {\provider\:\cpu\,\num_threads\:2}八、Parakeet 调优配置文件Whisper 系引擎用--beam-size/--beam-size-realtime直接做速度/质量权衡Parakeet TDT 使用不同的 NeMo 解码栈因此服务器改用--profile从批大小、实时节奏、VAD/分段时机三个维度调延迟。三个内置 profile 定义在 TUNING_PROFILESProfile设计意图关键取值parakeet-low-latency频繁 interim 更新、更小批次、更短静音窗batch_size1、realtime_processing_pause0.04、post_speech_silence_duration0.45、early_transcription_on_silence0.15parakeet-balanced浏览器听写场景的均衡默认batch_size8、realtime_processing_pause0.06、post_speech_silence_duration0.55、early_transcription_on_silence0.2parakeet-accurate-final更慢的最终化、更稳定的最终块batch_size16、realtime_processing_pause0.1、post_speech_silence_duration0.7、early_transcription_on_silence0.35profile 的默认值合并逻辑见 _tuning_defaults()基于BASE_TUNING_DEFAULTS叠加 profile 覆盖单元测试test_parakeet_tuning_profile_sets_latency_oriented_defaults验证了 low-latency 的取值test_fastapi_server_protocol.py。显式 flag 始终覆盖 profile 值python example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --use-main-model-for-realtime \ --profile parakeet-balanced \ --realtime-processing-pause 0.08 \ --post-speech-silence-duration 0.6九、WebSocket 协议详解9.1 上行二进制音频包浏览器向WS /ws/transcribe发送二进制音频包格式为编解码实现见 protocol.py4 字节小端无符号元数据长度UTF-8 JSON 元数据16-bit 小端单声道 PCM 音频字节。元数据示例来自 README{ sampleRate: 48000, channels: 1, format: pcm_s16le, frames: 1920 }服务端 packet_to_server_samples() 会校验包大小上限--max-audio-packet-bytes、通道数≤8、格式必须为pcm_s16le、frames与实际负载长度一致随后做多声道混音下采样并把任意采样率用scipy.signal.resample_poly重采样到服务器内部统一的 16000 Hz。非法包会以error事件where: audio_packet返回。9.2 下行服务器事件hello分配clientId与sessionId附公开设置、容量上限、受支持引擎ready模型车道初始化完成附公开设置与上限广播给所有会话timeline片段时序与唤醒词状态迁移realtime会话内segmentId的 interim 文本final同一segmentId的最终文本UI 用其替换 interim 块status/warning/error/clear/pong/metrics。所有携带文本的事件都包含sessionId并只路由到该会话clear只重置发起会话并丢弃早前会话世代的陈旧结果通过generation计数实现见RealtimeSession.clear()与handle_inference_result()server.py。实时文本若带realtime_callbackstabilized配置事件还会附带stableText/unstableText/consensusText等结构化稳定化字段见 server.py。9.3 文本命令命令是 JSON 对象例如{type: start}。支持start、stop、clear、ping回复pong、metrics回复会话级指标快照未知命令返回error实现见 server.py。十、引擎命名与规范化服务器把引擎名直接透传给 RealtimeSTT接受连字符命名并自动规范化normalize_engine_name去空白、转小写、-替换为_见 protocol.py。以下名字都可以直接使用READMEfaster_whisperwhisper_cppopenai_whisperparakeet/nvidia-parakeetsherpa-onnx-parakeetkroko-onnx/kroko/banafo-krokoomnilingual-asr/omnilingual/meta-omnilingual-asr/omni-asrcohere-transcribegranite-speechqwen3-asrmoonshine-streamingsherpa-onnx-moonshine引擎相关测试断言了kroko_onnx/kroko/banafo_kroko都在get_supported_transcription_engines()列表中test_fastapi_server_protocol.py并验证cohere-transcribe、moonshine-streaming会被规范化test_fastapi_server_protocol.py。后端专属参数字典以 JSON 传入例如python example_fastapi_server/server.py \ --engine cohere-transcribe \ --model CohereLabs/cohere-transcribe-03-2026 \ --engine-options {language:en}十一、健康检查与指标curl http://localhost:8010/health curl http://localhost:8010/api/metrics/health返回ok/ready、活跃会话/说话人数、拒绝会话数、调度器快照与启动错误server.py/api/metrics返回每会话计数器提交/完成/拒绝/合并/陈旧丢弃/强制 finalize、队列深度、p50/p95 排队延迟与推理延迟、worker 忙闲比RunningStats计算server.py。部署时应把/health用于就绪探针、/api/metrics用于负载与延迟监控模型缓存放在持久化存储上避免重启重下对外暴露时置于反向代理之后按所选引擎与硬件规模设定--max-sessions、--max-active-speakers、队列深度与模型车道数详见 docs/fastapi-server.md 的部署注意事项。十二、测试与性能基准12.1 快速单元测试不加载 ASR 模型使用假调度器覆盖协议编解码、队列合并/轮转/陈旧丢弃、运行时设置契约、引擎名规范化、profile 默认值等python -m unittest -v \ tests.unit.test_fastapi_server_protocol \ tests.unit.test_fastapi_server_multi_user测试入口在 tests/unit/test_fastapi_server_protocol.py其中test_audio_packet_round_trip等用例直接验证了二进制包的编码/解码往返与各类非法包拒绝test_fastapi_server_protocol.py。12.2 真实引擎多用户负载/质量/性能测试opt-in该测试会并行地把 tests/unit/audio/asr-reference.wav 流式灌入多个会话并将最终转写与 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_integrationREALTIMESTT_RUN_FASTAPI_MULTI_USER_ASR1运行同一测试当主要目标是测延迟时使用PERF名字。报告包含首次实时延迟、首次最终延迟、音频上传结束后的最终延迟、首次录音/VAD 启动时机、实时/最终事件节奏、WER、调度器 p50/p95 延迟、合并计数与拒绝/丢弃计数。设置REALTIMESTT_FASTAPI_ASR_METRICS_JSON/path/to/report.json可把报告写为 JSON。常用覆盖变量完整列表见 READMEREALTIMESTT_FASTAPI_ASR_CLIENTS4 REALTIMESTT_FASTAPI_ASR_ENGINEsherpa_onnx_moonshine REALTIMESTT_FASTAPI_ASR_MODELsherpa-onnx-moonshine-base-en-int8 REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINEsherpa_onnx_moonshine REALTIMESTT_FASTAPI_ASR_REALTIME_MODELsherpa-onnx-moonshine-tiny-en-int8 REALTIMESTT_FASTAPI_ASR_DOWNLOAD_ROOTtest-model-cache/sherpa-onnx REALTIMESTT_FASTAPI_ASR_DEVICEcpu REALTIMESTT_FASTAPI_ASR_MAX_WER0.30 REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONS{num_threads:4,provider:cpu} REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINE_OPTIONS{num_threads:2,provider:cpu} REALTIMESTT_FASTAPI_ASR_REALTIME_PROCESSING_PAUSE0.8 REALTIMESTT_FASTAPI_ASR_REALTIME_USE_SYLLABLE_BOUNDARIES1 REALTIMESTT_FASTAPI_ASR_REALTIME_BOUNDARY_FOLLOWUP_DELAYS0.1,0.2,0.4引擎选项变量也接受keyvalue列表形式如REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONSnum_threads4,providercpu更方便在 Windows cmd.exe 下使用。Kroko-ONNX 性能测试走同一套通用变量REALTIMESTT_FASTAPI_ASR_ENGINEkroko_onnx REALTIMESTT_FASTAPI_ASR_MODELtest-model-cache/kroko-onnx/Kroko-EN-Community-64-L-Streaming-001.data REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINEkroko_onnx REALTIMESTT_FASTAPI_ASR_REALTIME_MODELtest-model-cache/kroko-onnx/Kroko-EN-Community-64-L-Streaming-001.data REALTIMESTT_FASTAPI_ASR_DEVICEcpu REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONSprovidercpu,num_threads2 REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINE_OPTIONSprovidercpu,num_threads1Windows cmd.exe 下常见 4 客户端 sherpa-onnx Moonshine 配置可一键运行脚本默认值见 run_multi_user_perf.cmd4 客户端、Moonshine Base 最终 Tiny 实时、结果写入test-results\fastapi-4-user-perf.jsonexample_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十三、部署注意事项小结CUDA 密集型引擎Parakeet、Qwen vLLM、大型 Transformers使用 LinuxOmnilingual ASR 目前需要 Linux/WSL2 且 Python 3.11.xKroko-ONNX建议按RealtimeSTT[kroko-builder,silero-onnx-cpu]stt-install-kroko --build方式安装Windows 上用 Python 3.12 x64 并先启动 Docker Desktop模型缓存放持久化存储避免重启重复下载对外暴露时置于反向代理之后依据所选引擎与硬件规模规划--max-sessions、--max-active-speakers、队列深度与模型车道用/health做就绪探针、/api/metrics做负载与延迟监控。如需更多背景可继续阅读仓库中的 MULTI_USER_IMPLEMENTATION_GUIDE.md、docs/fastapi-server.md、docs/testing.md 与 docs/transcription-engines.md并对照核心库实现 RealtimeSTT/audio_recorder.py 理解会话内 recorder 状态机与 RealtimeSTT/transcription_engines/init.py 中的引擎工厂。【免费下载链接】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/RealtimeSTTexample_fastapi_server是 RealtimeSTT 官方提供的浏览器流式参考服务器它通过 FastAPI 提供一套可直接使用的 Web UI 与 WebSocket 音频端点把浏览器麦克风流接入 RealtimeSTT并支持多个浏览器会话并发、共享 ASR 模型车道与按会话公平调度的实时转写。读完本文你将掌握该服务器的安装启动、多用户容量规划、运行时热配置、GPU/CPU 各引擎配方、调优 profile、WebSocket 二进制协议与性能测试方法并能直接复用到自己的实时语音产品中。一、服务器定位与总体架构example_fastapi_server的核心是 server.py约 3500 行它承担三件事服务静态浏览器 UIGET /返回 static/index.html暴露 WebSocket 端点WS /ws/transcribe接收浏览器麦克风音频二进制包也接收start/stop/clear等文本命令在服务端维护每会话的转写状态机每个已接受的 WebSocket 会话持有独立的轻量级AudioToTextRecorder状态机继承 RealtimeSTT 的 WebRTC VAD、Silero VAD、唤醒词钩子、early-final 转写与音节边界实时调度能力而重量级 ASR 引擎则被抽取为共享执行器而不是每个浏览器各加载一份模型。从 server.py 的create_app()可以看出完整的端点面端点作用GET /浏览器 UIGET /health就绪状态、活跃会话/说话人数、启动错误、调度器状态GET /api/config公开配置、容量上限、受支持引擎、运行时设置契约PATCH /api/config运行时热更新配置GET /api/metrics每会话计数器、队列深度、合并/丢弃计数、p50/p95 延迟、worker 忙闲比WS /ws/transcribe浏览器音频流与命令通道注意该参考服务器面向**源码检出source checkout**使用PyPI wheel 不包含它。仅用 pip 安装的用户应使用 Python recorder/API 示例需要本服务器时请克隆仓库或从 Git 安装参见 docs/fastapi-server.md。二、安装与环境准备官方推荐使用 Linux 环境运行 CUDA 密集型引擎Parakeet、Qwen vLLM、大型 Transformers 模型完整安装步骤如下python -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.txt服务器自身依赖非常轻——requirements.txt 只有fastapi0.115、uvicorn[standard]0.30、numpy、scipy四项。重依赖全部来自所选的转写引擎栈。可选引擎栈安装按需安装你计划运行的引擎对应 README 与 docs/transcription-engines.md# ParakeetNeMoCUDA python -m pip install nemo_toolkit[asr] soundfile librosa # CPU whisper.cpp python -m pip install pywhispercpp # CPU sherpa-onnx Moonshine python -m pip install sherpa-onnx # Meta Omnilingual ASRLinux/WSL2 python -m pip install RealtimeSTT[omnilingual] # 源码检出时使用 python -m pip install -e .[omnilingual]Kroko-ONNX 需要单独构建上游当前偏向 Linux/DockerWindows 原生构建失败时请改用 WSL2/Linux 运行服务器git clone https://github.com/kroko-ai/kroko-onnx.git cd kroko-onnx python -m pip install .三、快速启动默认 faster-whisper 配置python example_fastapi_server/server.py --host 0.0.0.0 --port 8010然后浏览器打开http://localhost:8010即可开始麦克风流式转写。命令行参数全部由 parse_args() 解析、settings_from_args() 组装成ServerSettings。核心引擎参数见下表默认值取自 ServerSettingsFlag含义默认值--engine/--transcription-engine最终转写引擎faster_whisper--model最终模型名或路径small.en--realtime-engine/--realtime-transcription-engine实时引擎省略时复用最终引擎无--realtime-model实时模型名或路径tiny.en--engine-options传给最终引擎的 JSON 对象无--realtime-engine-options传给实时引擎的 JSON 对象无--download-root模型缓存/查找根目录无--devicecuda或cpucuda--compute-type引擎精度/量化提示default--language语言代码en--use-main-model-for-realtime用单条共享模型车道同时承担实时与最终转写低内存模式关闭四、多用户会话架构深入4.1 会话级隔离session-scoped服务器接受多个独立浏览器会话。每个 WebSocket 被分配一个sessionId以下内容全部按会话隔离音频缓冲区、VAD 状态、转写片段segmentId、clear/reset 命令、实时文本、最终文本、状态、警告与错误参见 README。SegmentStateserver.py维护会话内的片段号生成逻辑实时事件与最终事件共享同一个segmentId最终文本到达后 UI 用最终块替换实时块。SegmentTimelineTrackerserver.py为每个片段记录录音起止时间戳、时长、pre-roll 范围与唤醒词时间线。4.2 VAD 为什么按会话隔离服务器刻意让 VAD会话级隔离。WebRTC/Silero 检测在流级别是有状态的模型权重、循环状态、线程访问若多个会话共享单个 VAD 对象除非实现能证明按会话分离模型权重、循环状态与线程访问否则就是正确性风险。README 明确指出未来优化可以共享不可变的 VAD 权重但必须保持每会话的 VAD 状态与重置语义README。在每个会话内部VoiceActivityDetector 优先使用 WebRTC VADwebrtcvad.Vadaggressiveness 由--webrtc-sensitivity指定无法加载时回退到基于 RMS 的能量 VAD阈值由--vad-energy-threshold控制默认 250.0。4.3 共享模型车道shared model lanes模型资源按车道共享而不是每个浏览器一份模型副本默认均衡模式一条共享最终模型车道 一条共享实时模型车道低内存模式--use-main-model-for-realtime让一条共享模型车道同时负责实时与最终转写。InferenceSchedulerserver.py负责创建车道main_worker用--engine/--modelrealtime_worker用--realtime-engine/--realtime-model未指定时回退到最终引擎。每条车道由SharedEngineWorkerserver.py在独立后台线程中驱动并在启动时用 RealtimeSTT/assets/warmup_audio.wav 做模型预热每个会话在 recorder 构造时也会预热 VAD 路径避免第一段语音付出 Silero/WebRTC 懒加载的运行期成本warmup_vad由--no-model-warmup关闭见 server.py。4.4 公平调度队列推理任务通过每会话公平队列调度FairInferenceQueueserver.py最终任务final按会话保留到--max-final-queue-depth-per-session上限超出即拒绝实时任务realtime同一会话的新实时任务会**合并coalesce**旧的未执行实时任务只保留最新一帧超过--max-realtime-queue-age-ms的陈旧任务直接丢弃。这样设计保证一个嘈杂客户端无法用过期的 interim 工作灌满全局队列同时队列在会话之间轮转round-robin没有会话会饿死其他会话。这些行为都有单元测试直接验证例如 test_fastapi_server_protocol.py 中的test_fair_queue_coalesces_realtime_but_preserves_finals、test_fair_queue_round_robins_between_sessions与test_fair_queue_drops_stale_realtime_jobs。4.5 容量控制参数容量是显式可配置的。官方推荐的容量参数组合READMEpython example_fastapi_server/server.py \ --max-sessions 4 \ --max-active-speakers 4 \ --max-global-inference-queue-depth 64 \ --max-final-queue-depth-per-session 8 \ --max-realtime-queue-age-ms 1500 \ --max-audio-queue-seconds-per-session 30各容量参数语义实现于SessionStore/RealtimeSession见 server.py参数默认值作用--max-sessions4最大浏览器会话数超出直接拒绝WebSocket 关闭码 1013--max-active-speakers4最大并发说话人数超出仅告警已接收会话继续尽可能保留最终转写--max-global-inference-queue-depth64全局推理队列总上限--max-final-queue-depth-per-session8每会话最终任务积压上限超出的 recorded segment 被裁剪丢弃--max-realtime-queue-age-ms1500实时任务最大排队年龄过期丢弃--max-audio-queue-seconds-per-session30.0单会话连续录音超过该时长被强制 finalize--audio-queue-size128每会话输入队列大小映射到 recorder 的allowed_latency_limit--max-audio-packet-bytes512KB单个二进制音频包上限--pre-recording-buffer-duration0.75每会话 pre-roll预录音缓冲时长会话插槽在构造 recorder/VAD之前被预留SessionStore.reserve()因此并发连接洪峰也不会实例化出超过会话上限的 recorder音频包只有在收到start命令之后才被接受见 server.py 中“Audio stream is stopped”的拒绝逻辑。长时间连续录音会在达到--max-audio-queue-seconds-per-session时被强制 finalize_force_finalize_after_limitserver.py。五、运行时配置GET/PATCH /api/config服务器的运行时可安全配置项通过GET /api/config暴露响应中的runtimeSettings契约实现于 runtime_settings_contract()把设置分成三类activeSessionSafe立即作用于正在运行的会话如max_sessions、max_active_speakers、各队列深度newSessionOnly仅复制到未来的浏览器会话已存在的会话保留其 recorder 配置如wake_words、silero_sensitivity、post_speech_silence_duration等 VAD/唤醒词/实时转写参数startupOnly因为共享推理 worker 已初始化而需要重启如引擎、模型路径、batch_size、beam_size、device热更新会被明确拒绝。三类全集分别定义在 ACTIVE_RUNTIME_SETTINGS、NEW_SESSION_RUNTIME_SETTINGS 与 STARTUP_ONLY_SETTINGS。值的类型校验由 coerce_setting_value() 依据INT_SETTINGS/FLOAT_SETTINGS/BOOL_SETTINGS/DICT_SETTINGS/TUPLE_FLOAT_SETTINGS分类表完成。示例把max_sessions提到 8 并给后续会话启用唤醒词jarviscurl -X PATCH http://localhost:8010/api/config \ -H Content-Type: application/json \ -d {settings:{max_sessions:8,wake_words:jarvis}}响应会逐项给出applied含appliesTo: active_sessions/new_sessions与rejected含reason: startup_only/unknown/invalid_value其行为被单元测试test_runtime_settings_update_distinguishes_safe_and_startup_only_fields覆盖test_fastapi_server_protocol.py。唤醒词模式唤醒词配置直接透传给每个浏览器会话的 recorderpython example_fastapi_server/server.py \ --wakeword-backend pvporcupine \ --wake-words jarvis \ --wake-words-sensitivity 0.7 \ --wake-word-timeout 5 \ --wake-word-followup-window 5相关 flag 还包括--wake-word-activation-delay唤醒模式延迟生效、--wake-word-buffer-duration从录音开头剥离的唤醒词音频、--openwakeword-model-paths、--openwakeword-inference-framework默认onnx。唤醒等待、检测、后续语音窗口、超时、录音开始/结束、实时与最终转写等状态迁移都会以timelineWebSocket 事件呈现并在浏览器 UI 中展示转写块携带片段时间、时长、pre-roll 与唤醒检测元数据实现于SegmentTimelineTracker与_publish_timeline_eventserver.py。六、GPU 引擎配方6.1 Parakeet 最终转写 小实时 Whisper 模型export HF_HOME$HOME/.cache/huggingface python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --realtime-engine faster_whisper \ --realtime-model tiny.en \ --device cuda \ --language en6.2 Parakeet 同时承担实时与最终转写python example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --use-main-model-for-realtime \ --profile parakeet-low-latency \ --device cuda \ --language en6.3 Meta Omnilingual ASRLinux 或 WSL2单条 CTC 模型车道同时负责实时与最终转写用--use-main-model-for-realtime合并车道以省显存PYTHONPATH. python example_fastapi_server/server.py \ --host 0.0.0.0 \ --port 8010 \ --engine omnilingual_asr \ --model omniASR_CTC_300M_v2 \ --realtime-engine omnilingual_asr \ --realtime-model omniASR_CTC_300M_v2 \ --use-main-model-for-realtime \ --device cuda \ --compute-type float16 \ --language eng_Latn \ --engine-options {batch_size:1,sample_rate:16000}WSL2 开启 localhost 转发后可在 Windows 浏览器直接打开http://localhost:8010。300M 模型跑通后若 GPU 显存足够可尝试omniASR_CTC_1B_v2。七、CPU 引擎配方Windows cmd.exe以下命令面向 Windowscmd.exe需在仓库根目录执行先用set PYTHON_EXEpython指向正确的解释器或虚拟环境中的 python。7.1 whisper.cpp CPU用tiny.en同时承担实时与最终转写实时侧使用 greedy 解码和 single-segment/no-context 设置换取更快的 interim 文本%PYTHON_EXE% 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}}7.2 sherpa-onnx Moonshine CPU一次性下载并解压 Tiny 与 Base 两个 int8 模型到test-model-cache\sherpa-onnxmkdir test-model-cache\sherpa-onnx curl.exe -L -o test-model-cache\sherpa-onnx\sherpa-onnx-moonshine-tiny-en-int8.tar.bz2 https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-moonshine-tiny-en-int8.tar.bz2 %PYTHON_EXE% -c import tarfile; tarfile.open(rtest-model-cache\sherpa-onnx\sherpa-onnx-moonshine-tiny-en-int8.tar.bz2, r:bz2).extractall(rtest-model-cache\sherpa-onnx) curl.exe -L -o test-model-cache\sherpa-onnx\sherpa-onnx-moonshine-base-en-int8.tar.bz2 https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-moonshine-base-en-int8.tar.bz2 %PYTHON_EXE% -c import tarfile; tarfile.open(rtest-model-cache\sherpa-onnx\sherpa-onnx-moonshine-base-en-int8.tar.bz2, r:bz2).extractall(rtest-model-cache\sherpa-onnx)Base 负责最终转写、Tiny 负责实时转写启用音节边界实时调度%PYTHON_EXE% example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine sherpa_onnx_moonshine --model sherpa-onnx-moonshine-base-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\:4,\provider\:\cpu\} --realtime-engine-options {\num_threads\:2,\provider\:\cpu\} --realtime-processing-pause 0.8 --realtime-use-syllable-boundaries --realtime-boundary-detector-sensitivity 0.6 --realtime-boundary-followup-delays 0.1,0.2,0.4需要更低内存时用 Tiny 同时承担最终与实时转写%PYTHON_EXE% example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --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 --realtime-boundary-detector-sensitivity 0.6 --realtime-boundary-followup-delays 0.1,0.2,0.47.3 Kroko-ONNX CPU一次性下载社区英文流式模型mkdir test-model-cache\kroko-onnx python -c from huggingface_hub import hf_hub_download; hf_hub_download(repo_idBanafo/Kroko-ASR, filenameKroko-EN-Community-64-L-Streaming-001.data, local_dirtest-model-cache/kroko-onnx)Kroko 同时承担最终与实时转写python example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine kroko_onnx --model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --realtime-engine kroko_onnx --realtime-model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --device cpu --language en --engine-options {\provider\:\cpu\,\num_threads\:2} --realtime-engine-options {\provider\:\cpu\,\num_threads\:1}或 Kroko 负责最终文本、轻量 whisper.cpp 负责实时python example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine kroko_onnx --model test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data --realtime-engine whisper_cpp --realtime-model tiny.en --device cpu --language en --engine-options {\provider\:\cpu\,\num_threads\:2}八、Parakeet 调优配置文件Whisper 系引擎用--beam-size/--beam-size-realtime直接做速度/质量权衡Parakeet TDT 使用不同的 NeMo 解码栈因此服务器改用--profile从批大小、实时节奏、VAD/分段时机三个维度调延迟。三个内置 profile 定义在 TUNING_PROFILESProfile设计意图关键取值parakeet-low-latency频繁 interim 更新、更小批次、更短静音窗batch_size1、realtime_processing_pause0.04、post_speech_silence_duration0.45、early_transcription_on_silence0.15parakeet-balanced浏览器听写场景的均衡默认batch_size8、realtime_processing_pause0.06、post_speech_silence_duration0.55、early_transcription_on_silence0.2parakeet-accurate-final更慢的最终化、更稳定的最终块batch_size16、realtime_processing_pause0.1、post_speech_silence_duration0.7、early_transcription_on_silence0.35profile 的默认值合并逻辑见 _tuning_defaults()基于BASE_TUNING_DEFAULTS叠加 profile 覆盖单元测试test_parakeet_tuning_profile_sets_latency_oriented_defaults验证了 low-latency 的取值test_fastapi_server_protocol.py。显式 flag 始终覆盖 profile 值python example_fastapi_server/server.py \ --engine parakeet \ --model nvidia/parakeet-tdt-0.6b-v3 \ --use-main-model-for-realtime \ --profile parakeet-balanced \ --realtime-processing-pause 0.08 \ --post-speech-silence-duration 0.6九、WebSocket 协议详解9.1 上行二进制音频包浏览器向WS /ws/transcribe发送二进制音频包格式为编解码实现见 protocol.py4 字节小端无符号元数据长度UTF-8 JSON 元数据16-bit 小端单声道 PCM 音频字节。元数据示例来自 README{ sampleRate: 48000, channels: 1, format: pcm_s16le, frames: 1920 }服务端 packet_to_server_samples() 会校验包大小上限--max-audio-packet-bytes、通道数≤8、格式必须为pcm_s16le、frames与实际负载长度一致随后做多声道混音下采样并把任意采样率用scipy.signal.resample_poly重采样到服务器内部统一的 16000 Hz。非法包会以error事件where: audio_packet返回。9.2 下行服务器事件hello分配clientId与sessionId附公开设置、容量上限、受支持引擎ready模型车道初始化完成附公开设置与上限广播给所有会话timeline片段时序与唤醒词状态迁移realtime会话内segmentId的 interim 文本final同一segmentId的最终文本UI 用其替换 interim 块status/warning/error/clear/pong/metrics。所有携带文本的事件都包含sessionId并只路由到该会话clear只重置发起会话并丢弃早前会话世代的陈旧结果通过generation计数实现见RealtimeSession.clear()与handle_inference_result()server.py。实时文本若带realtime_callbackstabilized配置事件还会附带stableText/unstableText/consensusText等结构化稳定化字段见 server.py。9.3 文本命令命令是 JSON 对象例如{type: start}。支持start、stop、clear、ping回复pong、metrics回复会话级指标快照未知命令返回error实现见 server.py。十、引擎命名与规范化服务器把引擎名直接透传给 RealtimeSTT接受连字符命名并自动规范化normalize_engine_name去空白、转小写、-替换为_见 protocol.py。以下名字都可以直接使用READMEfaster_whisperwhisper_cppopenai_whisperparakeet/nvidia-parakeetsherpa-onnx-parakeetkroko-onnx/kroko/banafo-krokoomnilingual-asr/omnilingual/meta-omnilingual-asr/omni-asrcohere-transcribegranite-speechqwen3-asrmoonshine-streamingsherpa-onnx-moonshine引擎相关测试断言了kroko_onnx/kroko/banafo_kroko都在get_supported_transcription_engines()列表中test_fastapi_server_protocol.py并验证cohere-transcribe、moonshine-streaming会被规范化test_fastapi_server_protocol.py。后端专属参数字典以 JSON 传入例如python example_fastapi_server/server.py \ --engine cohere-transcribe \ --model CohereLabs/cohere-transcribe-03-2026 \ --engine-options {language:en}十一、健康检查与指标curl http://localhost:8010/health curl http://localhost:8010/api/metrics/health返回ok/ready、活跃会话/说话人数、拒绝会话数、调度器快照与启动错误server.py/api/metrics返回每会话计数器提交/完成/拒绝/合并/陈旧丢弃/强制 finalize、队列深度、p50/p95 排队延迟与推理延迟、worker 忙闲比RunningStats计算server.py。部署时应把/health用于就绪探针、/api/metrics用于负载与延迟监控模型缓存放在持久化存储上避免重启重下对外暴露时置于反向代理之后按所选引擎与硬件规模设定--max-sessions、--max-active-speakers、队列深度与模型车道数详见 docs/fastapi-server.md 的部署注意事项。十二、测试与性能基准12.1 快速单元测试不加载 ASR 模型使用假调度器覆盖协议编解码、队列合并/轮转/陈旧丢弃、运行时设置契约、引擎名规范化、profile 默认值等python -m unittest -v \ tests.unit.test_fastapi_server_protocol \ tests.unit.test_fastapi_server_multi_user测试入口在 tests/unit/test_fastapi_server_protocol.py其中test_audio_packet_round_trip等用例直接验证了二进制包的编码/解码往返与各类非法包拒绝test_fastapi_server_protocol.py。12.2 真实引擎多用户负载/质量/性能测试opt-in该测试会并行地把 tests/unit/audio/asr-reference.wav 流式灌入多个会话并将最终转写与 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_integrationREALTIMESTT_RUN_FASTAPI_MULTI_USER_ASR1运行同一测试当主要目标是测延迟时使用PERF名字。报告包含首次实时延迟、首次最终延迟、音频上传结束后的最终延迟、首次录音/VAD 启动时机、实时/最终事件节奏、WER、调度器 p50/p95 延迟、合并计数与拒绝/丢弃计数。设置REALTIMESTT_FASTAPI_ASR_METRICS_JSON/path/to/report.json可把报告写为 JSON。常用覆盖变量完整列表见 READMEREALTIMESTT_FASTAPI_ASR_CLIENTS4 REALTIMESTT_FASTAPI_ASR_ENGINEsherpa_onnx_moonshine REALTIMESTT_FASTAPI_ASR_MODELsherpa-onnx-moonshine-base-en-int8 REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINEsherpa_onnx_moonshine REALTIMESTT_FASTAPI_ASR_REALTIME_MODELsherpa-onnx-moonshine-tiny-en-int8 REALTIMESTT_FASTAPI_ASR_DOWNLOAD_ROOTtest-model-cache/sherpa-onnx REALTIMESTT_FASTAPI_ASR_DEVICEcpu REALTIMESTT_FASTAPI_ASR_MAX_WER0.30 REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONS{num_threads:4,provider:cpu} REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINE_OPTIONS{num_threads:2,provider:cpu} REALTIMESTT_FASTAPI_ASR_REALTIME_PROCESSING_PAUSE0.8 REALTIMESTT_FASTAPI_ASR_REALTIME_USE_SYLLABLE_BOUNDARIES1 REALTIMESTT_FASTAPI_ASR_REALTIME_BOUNDARY_FOLLOWUP_DELAYS0.1,0.2,0.4引擎选项变量也接受keyvalue列表形式如REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONSnum_threads4,providercpu更方便在 Windows cmd.exe 下使用。Kroko-ONNX 性能测试走同一套通用变量REALTIMESTT_FASTAPI_ASR_ENGINEkroko_onnx REALTIMESTT_FASTAPI_ASR_MODELtest-model-cache/kroko-onnx/Kroko-EN-Community-64-L-Streaming-001.data REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINEkroko_onnx REALTIMESTT_FASTAPI_ASR_REALTIME_MODELtest-model-cache/kroko-onnx/Kroko-EN-Community-64-L-Streaming-001.data REALTIMESTT_FASTAPI_ASR_DEVICEcpu REALTIMESTT_FASTAPI_ASR_ENGINE_OPTIONSprovidercpu,num_threads2 REALTIMESTT_FASTAPI_ASR_REALTIME_ENGINE_OPTIONSprovidercpu,num_threads1Windows cmd.exe 下常见 4 客户端 sherpa-onnx Moonshine 配置可一键运行脚本默认值见 run_multi_user_perf.cmd4 客户端、Moonshine Base 最终 Tiny 实时、结果写入test-results\fastapi-4-user-perf.jsonexample_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十三、部署注意事项小结CUDA 密集型引擎Parakeet、Qwen vLLM、大型 Transformers使用 LinuxOmnilingual ASR 目前需要 Linux/WSL2 且 Python 3.11.xKroko-ONNX建议按RealtimeSTT[kroko-builder,silero-onnx-cpu]stt-install-kroko --build方式安装Windows 上用 Python 3.12 x64 并先启动 Docker Desktop模型缓存放持久化存储避免重启重复下载对外暴露时置于反向代理之后依据所选引擎与硬件规模规划--max-sessions、--max-active-speakers、队列深度与模型车道用/health做就绪探针、/api/metrics做负载与延迟监控。如需更多背景可继续阅读仓库中的 MULTI_USER_IMPLEMENTATION_GUIDE.md、docs/fastapi-server.md、docs/testing.md 与 docs/transcription-engines.md并对照核心库实现 RealtimeSTT/audio_recorder.py 理解会话内 recorder 状态机与 RealtimeSTT/transcription_engines/init.py 中的引擎工厂。【免费下载链接】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），仅供参考