docs: clarify Fun-ASR-Nano HF CTC boundary

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

docs/vllm_guide.md

@@ -59,9 +59,13 @@ APIs are not interchangeable:
 Use the official `FunAudioLLM/Fun-ASR-Nano-2512` checkpoint from
 [ModelScope](https://modelscope.cn/models/FunAudioLLM/Fun-ASR-Nano-2512) or
 [Hugging Face](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512). The
-official Hugging Face repository does contain the complete `model.pt` at its
-root. The `Qwen3-0.6B/` subdirectory intentionally contains only the LLM config
-and tokenizer; it is not a standalone model download.
+current Hugging Face `model.pt` has incomplete CTC weights, so it remains
+usable for transcription but FunASR disables the affected CTC path rather than
+returning unreliable timestamps or speaker diarization. Use the ModelScope
+checkpoint when your deployment requires timestamps or speaker diarization;
+the publication repair is tracked in [#3496](https://github.com/modelscope/FunASR/issues/3496).
+The `Qwen3-0.6B/` subdirectory intentionally contains only the LLM config and
+tokenizer; it is not a standalone model download.
 
 ```python
 from funasr.auto.auto_model_vllm import AutoModelVLLM

docs/vllm_guide_zh.md

@@ -59,9 +59,11 @@ cd /path/to/FunASR && pip install -e .
 
 请从 [ModelScope](https://modelscope.cn/models/FunAudioLLM/Fun-ASR-Nano-2512)
 或 [Hugging Face](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512)
-下载官方 `FunAudioLLM/Fun-ASR-Nano-2512`。官方 Hugging Face 仓库的根目录
-实际包含完整的 `model.pt`；`Qwen3-0.6B/` 子目录按设计只保存 LLM 配置与
-tokenizer，不是可以单独加载的权重目录。
+下载官方 `FunAudioLLM/Fun-ASR-Nano-2512`。当前 Hugging Face 的 `model.pt`
+CTC 权重不完整，因此仍可用于转写，但 FunASR 会禁用受影响的 CTC 路径，避免
+返回不可靠的时间戳或说话人分离结果。部署需要时间戳或说话人分离时，请使用
+ModelScope checkpoint；权重发布修复进度见 [#3496](https://github.com/modelscope/FunASR/issues/3496)。
+`Qwen3-0.6B/` 子目录按设计只保存 LLM 配置与 tokenizer，不是可以单独加载的权重目录。
 
 ```python
 from funasr.auto.auto_model_vllm import AutoModelVLLM

docs/vllm_guide_zh_v2.md

@@ -59,9 +59,11 @@ cd /path/to/FunASR && pip install -e .
 
 请从 [ModelScope](https://modelscope.cn/models/FunAudioLLM/Fun-ASR-Nano-2512)
 或 [Hugging Face](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512)
-下载官方 `FunAudioLLM/Fun-ASR-Nano-2512`。官方 Hugging Face 仓库的根目录
-实际包含完整的 `model.pt`；`Qwen3-0.6B/` 子目录按设计只保存 LLM 配置与
-tokenizer，不是可以单独加载的权重目录。
+下载官方 `FunAudioLLM/Fun-ASR-Nano-2512`。当前 Hugging Face 的 `model.pt`
+CTC 权重不完整，因此仍可用于转写，但 FunASR 会禁用受影响的 CTC 路径，避免
+返回不可靠的时间戳或说话人分离结果。部署需要时间戳或说话人分离时，请使用
+ModelScope checkpoint；权重发布修复进度见 [#3496](https://github.com/modelscope/FunASR/issues/3496)。
+`Qwen3-0.6B/` 子目录按设计只保存 LLM 配置与 tokenizer，不是可以单独加载的权重目录。
 
 ```python
 from funasr.auto.auto_model_vllm import AutoModelVLLM

tests/test_vllm_model_source_docs.py

@@ -29,3 +29,48 @@ def test_vllm_guides_distinguish_official_and_native_model_paths(relpath):
 
     for marker in required_markers:
         assert marker in text, f"{relpath} is missing {marker}"
+
+
+@pytest.mark.parametrize(
+    ("relpath", "required_markers", "stale_claim"),
+    [
+        (
+            "docs/vllm_guide.md",
+            (
+                "https://github.com/modelscope/FunASR/issues/3496",
+                "incomplete CTC weights",
+                "timestamps or speaker diarization",
+                "Use the ModelScope\ncheckpoint",
+            ),
+            "does contain the complete `model.pt` at its root",
+        ),
+        (
+            "docs/vllm_guide_zh.md",
+            (
+                "https://github.com/modelscope/FunASR/issues/3496",
+                "CTC 权重不完整",
+                "时间戳或说话人分离",
+                "ModelScope checkpoint",
+            ),
+            "实际包含完整的 `model.pt`",
+        ),
+        (
+            "docs/vllm_guide_zh_v2.md",
+            (
+                "https://github.com/modelscope/FunASR/issues/3496",
+                "CTC 权重不完整",
+                "时间戳或说话人分离",
+                "ModelScope checkpoint",
+            ),
+            "实际包含完整的 `model.pt`",
+        ),
+    ],
+)
+def test_vllm_guides_document_hf_incomplete_ctc_checkpoint(
+    relpath, required_markers, stale_claim
+):
+    text = (ROOT / relpath).read_text(encoding="utf-8")
+
+    for marker in required_markers:
+        assert marker in text, f"{relpath} is missing {marker}"
+    assert stale_claim not in text, f"{relpath} still claims HF has complete CTC"