Add install and deployment troubleshooting FAQ (#3366)

Co-authored-by: LauraGPT <lauragpt@users.noreply.github.com>

Author: LauraGPT

README.md

@@ -21,7 +21,7 @@
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> · <a href="./examples/colab/">Colab</a> · <a href="#benchmark">Benchmark</a> · <a href="./docs/model_selection.md">Model selection</a> · <a href="./docs/migration_from_whisper.md">Migration guide</a> · <a href="./docs/use_case_showcase.md">Use cases</a> · <a href="./docs/community_projects.md">Community integrations</a> · <a href="./docs/deployment_matrix.md">Deployment matrix</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a> · <a href="./CONTRIBUTING.md">Contribute</a>
+  <a href="#quick-start">Quick Start</a> · <a href="./examples/colab/">Colab</a> · <a href="#benchmark">Benchmark</a> · <a href="./docs/model_selection.md">Model selection</a> · <a href="./docs/migration_from_whisper.md">Migration guide</a> · <a href="./docs/use_case_showcase.md">Use cases</a> · <a href="./docs/community_projects.md">Community integrations</a> · <a href="./docs/deployment_matrix.md">Deployment matrix</a> · <a href="./docs/troubleshooting.md">Troubleshooting</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a> · <a href="./CONTRIBUTING.md">Contribute</a>
 </p>
 
 ---

README_zh.md

@@ -21,7 +21,7 @@
 </p>
 
 <p align="center">
-  <a href="#快速开始">快速开始</a> · <a href="./examples/colab/README_zh.md">Colab</a> · <a href="#性能评测">性能评测</a> · <a href="./docs/model_selection_zh.md">模型选择</a> · <a href="./docs/migration_from_whisper_zh.md">迁移指南</a> · <a href="./docs/use_case_showcase_zh.md">场景速览</a> · <a href="./docs/community_projects_zh.md">社区集成</a> · <a href="./docs/deployment_matrix_zh.md">部署选型</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a> · <a href="./CONTRIBUTING.md">贡献</a>
+  <a href="#快速开始">快速开始</a> · <a href="./examples/colab/README_zh.md">Colab</a> · <a href="#性能评测">性能评测</a> · <a href="./docs/model_selection_zh.md">模型选择</a> · <a href="./docs/migration_from_whisper_zh.md">迁移指南</a> · <a href="./docs/use_case_showcase_zh.md">场景速览</a> · <a href="./docs/community_projects_zh.md">社区集成</a> · <a href="./docs/deployment_matrix_zh.md">部署选型</a> · <a href="./docs/troubleshooting_zh.md">排障 FAQ</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a> · <a href="./CONTRIBUTING.md">贡献</a>
 </p>
 
 ---

docs/troubleshooting.md

@@ -0,0 +1,56 @@
+# Troubleshooting
+
+This short FAQ covers the install and deployment failures that most often block a first FunASR trial. For model choice, see the [model selection guide](./model_selection.md); for serving options, see the [deployment matrix](./deployment_matrix.md).
+
+## Install or import fails
+
+- Install `torch` and `torchaudio` first, then install FunASR:
+
+```bash
+python -m pip install -U torch torchaudio
+python -m pip install -U "funasr==1.3.26"
+```
+
+- Keep `torch`, `torchaudio`, and `torchvision` on compatible versions from the same install channel. If you use vLLM, follow [the vLLM guide](./vllm_guide.md) and avoid mixing unrelated CUDA wheels in the same environment.
+- If import still fails, create a fresh virtual environment and include the complete Python version, operating system, CUDA driver, `pip list | grep -E "torch|torchaudio|funasr"`, and the exact traceback in a **Deployment Help** issue.
+
+## Model download is slow or fails
+
+- In mainland China, try ModelScope first. Use the `iic/...` model names shown in the README and model zoo, or pass the ModelScope hub option when a command exposes it.
+- Outside mainland China, Hugging Face mirrors are often faster. For GGUF or edge runtime models, use the public FunAudioLLM repositories on Hugging Face.
+- If a download is interrupted, clear only the partial cache for that model and retry. Include the hub, model id, network environment, and error log in a **Deployment Help** issue.
+
+## `funasr-server` starts but OpenAI-compatible requests fail
+
+- Confirm the server extras are installed, including FastAPI, Uvicorn, and multipart upload support.
+- Smoke test the health of the OpenAI-compatible transcription route with a small local WAV file before wiring it into an agent or SDK:
+
+```bash
+curl -X POST "http://127.0.0.1:8000/v1/audio/transcriptions" \
+  -F "file=@example.wav" \
+  -F "model=FunAudioLLM/SenseVoiceSmall"
+```
+
+- If `/v1/audio/transcriptions` returns 4xx or 5xx, attach the startup command, full server log, request command, model id, hub, and audio duration.
+
+## WebSocket realtime output is empty or delayed
+
+- Check that the client sends the audio format expected by the WebSocket demo, especially sample rate, channel count, chunk size, and PCM encoding.
+- Use a short known-good WAV first. Long silence, unsupported codecs, or mismatched sample rates can look like a serving failure.
+- When filing **Deployment Help**, include the WebSocket URL, client command or browser console output, model id, sample rate, and the server-side session statistics.
+
+## llama.cpp or GGUF runtime does not start
+
+- Download the current `runtime-llamacpp-v0.1.8` release package from the README or [funasr.com/llama-cpp](https://www.funasr.com/llama-cpp.html).
+- Match the package to the machine: CPU builds work broadly, Vulkan builds need a working Vulkan runtime, and CUDA builds need compatible NVIDIA drivers.
+- Use the current GGUF model repositories on Hugging Face, such as `FunAudioLLM/Fun-ASR-Nano-GGUF` or `FunAudioLLM/SenseVoiceSmall-GGUF`.
+- For GPU issues, include `nvidia-smi`, operating system, driver version, runtime package name, model file name, and the complete llama.cpp command in a **Deployment Help** issue.
+
+## What to include in a Deployment Help issue
+
+Please include:
+
+- operating system, Python version, install command, and virtual environment tool;
+- `torch`, `torchaudio`, CUDA, driver, and GPU details;
+- FunASR version, model id, hub (`ModelScope` or `Hugging Face`), and deployment mode;
+- exact command, minimal audio sample details, full error log, and whether the same sample works in the local Python pipeline.

docs/troubleshooting_zh.md

@@ -0,0 +1,56 @@
+# 排障 FAQ
+
+这份简短 FAQ 汇总首次安装和部署 FunASR 时最常见的阻塞问题。模型选择请看[模型选择指南](./model_selection_zh.md)，服务化选型请看[部署选型](./deployment_matrix_zh.md)。
+
+## 安装或 import 失败
+
+- 先安装 `torch` 和 `torchaudio`，再安装 FunASR：
+
+```bash
+python -m pip install -U torch torchaudio
+python -m pip install -U "funasr==1.3.26"
+```
+
+- 保持 `torch`、`torchaudio`、`torchvision` 来自同一安装渠道且版本兼容。如果使用 vLLM，请按 [vLLM 指南](./vllm_guide_zh.md)配置，避免在同一环境里混装不匹配的 CUDA wheel。
+- 如果仍然 import 失败，建议新建干净虚拟环境复现，并在 **Deployment Help** issue 里附上 Python 版本、操作系统、CUDA driver、`pip list | grep -E "torch|torchaudio|funasr"` 和完整 traceback。
+
+## 模型下载慢或失败
+
+- 中国大陆网络优先尝试 ModelScope。README 和 model_zoo 里的 `iic/...` 模型名是当前入口；命令支持 hub 参数时可以选择 ModelScope。
+- 海外网络通常 Hugging Face 更快。GGUF 和边缘 runtime 模型请使用 Hugging Face 上的 FunAudioLLM 公开仓库。
+- 下载中断后，只清理该模型的半截缓存再重试。提交 **Deployment Help** issue 时请附 hub、model id、网络环境和错误日志。
+
+## `funasr-server` 启动后 OpenAI 兼容接口请求失败
+
+- 确认服务依赖已安装，包括 FastAPI、Uvicorn 和 multipart upload 支持。
+- 接入 agent 或 SDK 前，先用一个很短的本地 WAV 文件 smoke test `/v1/audio/transcriptions`：
+
+```bash
+curl -X POST "http://127.0.0.1:8000/v1/audio/transcriptions" \
+  -F "file=@example.wav" \
+  -F "model=FunAudioLLM/SenseVoiceSmall"
+```
+
+- 如果 `/v1/audio/transcriptions` 返回 4xx 或 5xx，请附启动命令、完整 server log、请求命令、model id、hub 和音频时长。
+
+## WebSocket 实时输出为空或延迟很大
+
+- 检查客户端发送的音频格式是否符合 WebSocket demo 要求，尤其是采样率、通道数、chunk size 和 PCM 编码。
+- 先用一段已知可用的短 WAV 文件排查。长静音、不支持的编码、采样率不匹配，都可能看起来像服务端失败。
+- 提交 **Deployment Help** 时，请附 WebSocket URL、客户端命令或浏览器 console、model id、采样率和服务端 session statistics。
+
+## llama.cpp 或 GGUF runtime 无法启动
+
+- 从 README 或 [funasr.com/llama-cpp](https://www.funasr.com/llama-cpp.html) 下载当前 `runtime-llamacpp-v0.1.8` release 包。
+- 按机器环境选择包：CPU 包兼容性最好，Vulkan 包需要可用 Vulkan runtime，CUDA 包需要兼容的 NVIDIA driver。
+- GGUF 模型请使用 Hugging Face 上当前的公开仓库，例如 `FunAudioLLM/Fun-ASR-Nano-GGUF` 或 `FunAudioLLM/SenseVoiceSmall-GGUF`。
+- GPU 问题请在 **Deployment Help** issue 里附 `nvidia-smi`、操作系统、driver 版本、runtime 包名、模型文件名和完整 llama.cpp 命令。
+
+## Deployment Help issue 需要提供什么
+
+请尽量提供：
+
+- 操作系统、Python 版本、安装命令和虚拟环境工具；
+- `torch`、`torchaudio`、CUDA、driver 和 GPU 信息；
+- FunASR 版本、model id、hub（`ModelScope` 或 `Hugging Face`）和部署方式；
+- 精确命令、最小音频样例信息、完整错误日志，以及同一音频在本地 Python pipeline 是否可用。

tests/test_docs_funasr_install_commands.py

@@ -92,6 +92,40 @@ def test_public_entrypoints_use_current_repository_urls():
             assert marker not in text
 
 
+def test_troubleshooting_faq_is_linked_from_readmes():
+    readme_links = [
+        ("README.md", "./docs/troubleshooting.md"),
+        ("README_zh.md", "./docs/troubleshooting_zh.md"),
+    ]
+
+    for readme, link in readme_links:
+        text = (ROOT / readme).read_text()
+        assert link in text
+
+
+def test_troubleshooting_faq_covers_common_install_and_deploy_failures():
+    docs = [
+        (ROOT / "docs/troubleshooting.md").read_text(),
+        (ROOT / "docs/troubleshooting_zh.md").read_text(),
+    ]
+    required_markers = [
+        "torch",
+        "torchaudio",
+        "ModelScope",
+        "Hugging Face",
+        "funasr-server",
+        "/v1/audio/transcriptions",
+        "WebSocket",
+        "llama.cpp",
+        "GGUF",
+        "Deployment Help",
+    ]
+
+    for text in docs:
+        for marker in required_markers:
+            assert marker in text
+
+
 def test_public_docs_do_not_advertise_stale_release_or_star_copy():
     checked_docs = [
         "docs/repository_roles.md",