Skip to content

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

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

qiulangfddf9b486bc8
diff --git a/docs/vllm_guide.md b/docs/vllm_guide.md
index 1894bf29b..aa4111d61 100644
--- a/docs/vllm_guide.md
+++ b/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.
diff --git a/docs/vllm_guide_zh.md b/docs/vllm_guide_zh.md
index 0568fcd42..102cd006e 100644
--- a/docs/vllm_guide_zh.md
+++ b/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 驱动。
diff --git a/tests/test_vllm_model_source_docs.py b/tests/test_vllm_model_source_docs.py
index 32a90bd6b..860aa8224 100644
--- a/tests/test_vllm_model_source_docs.py
+++ b/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}"
+ ("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"),
[