docs: add realtime session stats guidance

Document realtime WebSocket session-stats diagnostics for long sessions with speaker diarization.

Author: LauraGPT

docs/vllm_guide.md

@@ -607,6 +607,19 @@ CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/
 Set `--ws-ping-interval 0` only when an external gateway already owns
 keepalive/reconnect policy.
 
+For long-session debugging, especially with `--enable-spk`, enable periodic
+session-state logs:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \
+    --port 10095 --language 中文 --enable-spk \
+    --log-session-stats-interval 30
+```
+
+This prints a `Session stats:` line every 30 seconds. Include the last few
+lines in issue reports together with tail RTF, process RSS, GPU memory, and
+the final disconnect log.
+
 ### 6.3 WebSocket Protocol
 
 **Connection**: `ws://host:10095`
@@ -728,6 +741,7 @@ Because each refresh re-encodes from the sentence start, the longer a sentence,
 - **SPK is of limited effectiveness on Fun-ASR-Nano** (see #2944); most real-time ASR scenarios do not need speaker separation.
 - **Streaming SPK is expensive and grows with the session**: each sentence re-clusters **all historical embeddings** (**O(N²)**, more expensive per sentence as the session grows) and **synchronously blocks the event loop**; the session also **re-clusters everything again** at the end, so the per-sentence clustering during streaming is overwritten by the final result — redundant as far as the final output is concerned. This is especially pronounced under long sessions + high concurrency.
 - **Recommendation**: keep the default off for multi-client live ASR; if diarization is required, add `--enable-spk` and treat the final STOP-time labels as authoritative.
+- **Long-session diagnostics**: when a session still slows down or disconnects, rerun with `--log-session-stats-interval 30` and check whether `audio_buffer_samples`, `locked_sentences`, `speaker_history_chunks`, `speaker_history_embeddings`, and `speaker_centers` stay bounded. If those counters stay near their limits while RTF keeps rising, the remaining bottleneck is more likely model inference, response payload size, or environment scheduling rather than retained session state.
 
 ### 6.7 Production concurrency and multi-process deployment
 

docs/vllm_guide_zh.md

@@ -610,6 +610,17 @@ CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/
 只有在外部网关已经统一负责 keepalive / reconnect 策略时，才考虑设置
 `--ws-ping-interval 0` 关闭服务端 ping。
 
+长会话排障，尤其是启用 `--enable-spk` 时，可以打开周期性 session 状态日志：
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \
+    --port 10095 --language 中文 --enable-spk \
+    --log-session-stats-interval 30
+```
+
+服务端会每 30 秒输出一行 `Session stats:`。提交 issue 时请连同最后几行
+`Session stats`、末段 RTF、进程 RSS、GPU memory 和断线前后的服务端日志一起提供。
+
 ### 6.3 WebSocket 协议
 
 **连接**：`ws://host:10095`
@@ -731,6 +742,7 @@ Fun-ASR-Nano 的声学编码器（SenseVoice）是**全上下文、非流式**
 - **Fun-ASR-Nano 上 SPK 效果有限**（见 #2944），多数实时 ASR 场景并不需要说话人分离。
 - **流式 SPK 代价高且随会话变长**：每句对**全部历史 embedding** 做一次全量重聚类（**O(N²)**，会话越长每句越贵），且**同步阻塞事件循环**；而会话结束时还会**全量重聚一遍**，流式期间每句的聚类结果会被最终结果覆盖——对最终输出而言属于重复计算。长会话 + 高并发下尤其明显。
 - **建议**：多客户端实时转写优先保持默认关闭；确需 diarization 时再加 `--enable-spk`，并以 STOP 后的最终 `spk` 标签为准。
+- **长会话诊断**：如果 session 仍然逐渐变慢或断开，请用 `--log-session-stats-interval 30` 复测，并观察 `audio_buffer_samples`、`locked_sentences`、`speaker_history_chunks`、`speaker_history_embeddings` 和 `speaker_centers` 是否保持有界。如果这些计数都接近上限但 RTF 仍持续升高，剩余瓶颈更可能在模型推理、返回 payload 大小或环境调度，而不是 session 状态继续泄漏。
 
 ### 6.7 生产并发与多进程部署