Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
feat: expose realtime websocket keepalive options (#3121)
zhifu gaoac84c4bf674a
diff --git a/docs/vllm_guide.md b/docs/vllm_guide.mdindex b898942c9..d7b0713ba 100644--- a/docs/vllm_guide.md+++ b/docs/vllm_guide.md@@ -594,6 +594,19 @@ CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/Speaker diarization is disabled by default; add `--enable-spk` only when the `spk` field is required.+For long-lived microphone sessions behind Docker, nginx, or a cloud load+balancer, keep WebSocket ping/pong enabled and tune the timeout to be longer+than short network stalls:++```bash+CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \+ --port 10095 --language 中文 \+ --ws-ping-interval 20 --ws-ping-timeout 60+```++Set `--ws-ping-interval 0` only when an external gateway already owns+keepalive/reconnect policy.+### 6.3 WebSocket Protocol**Connection**: `ws://host:10095`diff --git a/docs/vllm_guide_zh.md b/docs/vllm_guide_zh.mdindex 9b66e3ea2..a5a4db46b 100644--- a/docs/vllm_guide_zh.md+++ b/docs/vllm_guide_zh.md@@ -598,6 +598,18 @@ CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/说话人分离默认关闭;只有确实需要 `spk` 字段时再加 `--enable-spk`。+如果麦克风长连接经过 Docker、nginx 或云负载均衡,建议保持 WebSocket+ping/pong 开启,并把 timeout 调到能覆盖短暂网络抖动:++```bash+CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \+ --port 10095 --language 中文 \+ --ws-ping-interval 20 --ws-ping-timeout 60+```++只有在外部网关已经统一负责 keepalive / reconnect 策略时,才考虑设置+`--ws-ping-interval 0` 关闭服务端 ping。+### 6.3 WebSocket 协议**连接**:`ws://host:10095`diff --git a/examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py b/examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.pyindex a8d8e5049..43e785329 100644--- a/examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py+++ b/examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py@@ -536,12 +536,32 @@ async def handle_client(websocket, args):logger.error(f"Error: {e}", exc_info=True)+def _positive_or_none(value):+ return None if value <= 0 else value+++def build_websocket_serve_kwargs(args):+ return {+ "max_size": args.ws_max_size,+ "ping_interval": _positive_or_none(args.ws_ping_interval),+ "ping_timeout": _positive_or_none(args.ws_ping_timeout),+ "close_timeout": args.ws_close_timeout,+ }++async def main(args):load_models(args)logger.info(f"Server on ws://0.0.0.0:{args.port}")+ serve_kwargs = build_websocket_serve_kwargs(args)+ logger.info(+ "WebSocket options: "+ f"max_size={serve_kwargs['max_size']}, "+ f"ping_interval={serve_kwargs['ping_interval']}, "+ f"ping_timeout={serve_kwargs['ping_timeout']}, "+ f"close_timeout={serve_kwargs['close_timeout']}"+ )async with websockets.serve(- lambda ws: handle_client(ws, args), "0.0.0.0", args.port,- max_size=10*1024*1024,+ lambda ws: handle_client(ws, args), "0.0.0.0", args.port, **serve_kwargs,):await asyncio.Future()@@ -569,6 +589,14 @@ def build_arg_parser():parser.add_argument("--tensor-parallel-size", type=int, default=1)parser.add_argument("--gpu-memory-utilization", type=float, default=0.8)parser.add_argument("--max-model-len", type=int, default=2048)+ parser.add_argument("--ws-ping-interval", type=float, default=20.0,+ help="WebSocket ping interval in seconds; <=0 disables keepalive pings.")+ parser.add_argument("--ws-ping-timeout", type=float, default=20.0,+ help="WebSocket ping timeout in seconds; <=0 disables ping timeout.")+ parser.add_argument("--ws-close-timeout", type=float, default=10.0,+ help="WebSocket close handshake timeout in seconds.")+ parser.add_argument("--ws-max-size", type=int, default=10 * 1024 * 1024,+ help="Maximum incoming WebSocket message size in bytes.")return parserdiff --git a/tests/test_realtime_ws_service.py b/tests/test_realtime_ws_service.pyindex f33a34ccd..1ed0231a4 100644--- a/tests/test_realtime_ws_service.py+++ b/tests/test_realtime_ws_service.py@@ -36,6 +36,41 @@ def test_cli_defaults_disable_speaker_and_bound_partial_window():assert args.partial_window_sec == 15.0+def test_websocket_keepalive_kwargs_are_configurable():+ module = load_service_module()++ args = module.build_arg_parser().parse_args(+ [+ "--ws-ping-interval", "35",+ "--ws-ping-timeout", "70",+ "--ws-close-timeout", "12",+ "--ws-max-size", "12345",+ ]+ )++ assert module.build_websocket_serve_kwargs(args) == {+ "max_size": 12345,+ "ping_interval": 35.0,+ "ping_timeout": 70.0,+ "close_timeout": 12.0,+ }+++def test_websocket_keepalive_kwargs_can_disable_ping():+ module = load_service_module()++ args = module.build_arg_parser().parse_args(+ [+ "--ws-ping-interval", "0",+ "--ws-ping-timeout", "0",+ ]+ )++ kwargs = module.build_websocket_serve_kwargs(args)+ assert kwargs["ping_interval"] is None+ assert kwargs["ping_timeout"] is None++def test_create_speaker_tracker_skips_spk_when_disabled():module = load_service_module()args = types.SimpleNamespace(enable_spk=False, device="cuda:0")