Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

feat: expose realtime websocket keepalive options (#3121)

zhifu gaoac84c4bf674a
diff --git a/docs/vllm_guide.md b/docs/vllm_guide.md
index 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.md
index 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.py
index 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 parser
diff --git a/tests/test_realtime_ws_service.py b/tests/test_realtime_ws_service.py
index 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")