docs(vllm): clarify native transcription boundary (#3601)

Signed-off-by: LauraGPT <[email protected]>
Co-authored-by: LauraGPT <[email protected]>

docs/vllm_guide.md

@@ -89,13 +89,23 @@ do not try to serve that config-only directory directly with vLLM.
 
 #### B. Native vLLM transcription integration
 
-The vLLM supported-model table lists
-[`allendou/Fun-ASR-Nano-2512-vllm`](https://huggingface.co/allendou/Fun-ASR-Nano-2512-vllm)
-for its native `FunASRForConditionalGeneration` architecture. That is a
-community-converted full checkpoint hosted outside the official FunAudioLLM
-organization. Use its model card and vLLM's native transcription API only when
-you intentionally choose that separate path. Do not substitute it for the
-official checkpoint in the FunASR `AutoModelVLLM` examples below.
+The official native checkpoint is
+[`FunAudioLLM/Fun-ASR-Nano-2512-vllm`](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-vllm).
+The vLLM supported-model table also lists
+[`allendou/Fun-ASR-Nano-2512-vllm`](https://huggingface.co/allendou/Fun-ASR-Nano-2512-vllm),
+a community-converted full checkpoint hosted outside the official FunAudioLLM
+organization, for its native `FunASRForConditionalGeneration` architecture.
+Use either native checkpoint only when you intentionally choose vLLM's native
+transcription API. Do not substitute either one for the official checkpoint in
+the FunASR `AutoModelVLLM` examples below.
+
+Both native paths use `vllm serve` for non-realtime request/response
+transcription at `/v1/audio/transcriptions`; they do not register
+`/v1/realtime`. vLLM registers that WebSocket endpoint only for models that
+declare the realtime task, and `FunASRForConditionalGeneration` is not in its
+[Realtime Transcription table](https://docs.vllm.ai/en/latest/models/supported_models/#realtime-transcription).
+For realtime streaming, use the FunASR streaming SDK inference or streaming ASR
+service. The `AutoModelVLLM` examples in path A are offline inference as well.
 
 **Hardware**: GPU ≥ 8 GB VRAM, CUDA ≥ 11.8. 16 GB+ recommended.
 

docs/vllm_guide_zh.md

@@ -86,13 +86,22 @@ model = AutoModelVLLM(
 
 #### B. vLLM 原生转写路径
 
-vLLM 的支持模型表把
+官方维护的 native checkpoint 是
+[`FunAudioLLM/Fun-ASR-Nano-2512-vllm`](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-vllm)。
+vLLM 的支持模型表也把
 [`allendou/Fun-ASR-Nano-2512-vllm`](https://huggingface.co/allendou/Fun-ASR-Nano-2512-vllm)
-列为原生 `FunASRForConditionalGeneration` 架构的示例。这是托管在官方
+列为原生 `FunASRForConditionalGeneration` 架构示例；后者是托管在官方
 FunAudioLLM 组织之外的社区转换完整 checkpoint。只有明确选择 vLLM 原生转写
-接口时，才应按该模型卡与 vLLM 文档使用它；不要用它替换下文 FunASR
+接口时，才应使用这两种 native checkpoint；不要用它们替换下文 FunASR
 `AutoModelVLLM` 示例中的官方 checkpoint。
 
+两种 native 路径都通过 `vllm serve` 提供非实时的请求/响应式转写
+`/v1/audio/transcriptions`，不会注册 `/v1/realtime`。vLLM 只为声明
+realtime 任务的模型注册该 WebSocket 端点，`FunASRForConditionalGeneration`
+当前不在它的 [Realtime Transcription 表](https://docs.vllm.ai/en/latest/models/supported_models/#realtime-transcription)
+中。需要实时流式识别时，请使用 FunASR 流式 SDK 推理或流式 ASR 服务；路径 A 的
+`AutoModelVLLM` 示例同样属于离线推理。
+
 **硬件**：GPU ≥ 8GB VRAM，CUDA ≥ 11.8。推荐 16GB+。
 
 为什么不要单独执行 `pip install torch torchaudio` ? torch/torchaudio/torchvision 的版本由 vLLM 版本决定—— 每个大版本会一起升级(见 vLLM 的 [requirements/cuda.txt](https://github.com/vllm-project/vllm/blob/main/requirements/cuda.txt))。手动安装会拉到最新 wheel,可能是为比你驱动更新的 CUDA runtime 编译的;PyTorch 会在 CUDA 初始化阶段、FunASR 启动前就报 The NVIDIA driver on your system is too old。让 vLLM 统一钉定这三件套即可避免。若仍遇到该错误,请安装其 CUDA 构建与 nvidia-smi 显示的 CUDA 匹配的 vLLM 版本(如 CUDA 12.x 用 vllm==0.19.1),或先升级 NVIDIA 驱动。

tests/test_vllm_model_source_docs.py

@@ -47,6 +47,38 @@ def test_v2_guide_keeps_native_vllm_and_funasr_realtime_paths_separate():
         assert marker in text, f"docs/vllm_guide_zh_v2.md is missing {marker}"
 
 
+@pytest.mark.parametrize(
+    ("relpath", "required_markers"),
+    [
+        (
+            "docs/vllm_guide.md",
+            (
+                "FunAudioLLM/Fun-ASR-Nano-2512-vllm",
+                "/v1/audio/transcriptions",
+                "/v1/realtime",
+                "realtime streaming",
+            ),
+        ),
+        (
+            "docs/vllm_guide_zh.md",
+            (
+                "FunAudioLLM/Fun-ASR-Nano-2512-vllm",
+                "/v1/audio/transcriptions",
+                "/v1/realtime",
+                "实时流式识别",
+            ),
+        ),
+    ],
+)
+def test_primary_vllm_guides_bound_native_transcription_to_request_response(
+    relpath, required_markers
+):
+    text = (ROOT / relpath).read_text(encoding="utf-8")
+
+    for marker in required_markers:
+        assert marker in text, f"{relpath} is missing {marker}"
+
+
 @pytest.mark.parametrize(
     ("relpath", "required_markers", "stale_claim"),
     [