Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
Add install and deployment troubleshooting FAQ (#3366)
zhifu gaoc734cffd4d2e
diff --git a/README.md b/README.mdindex 5e34793f9..761342995 100644--- a/README.md+++ b/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>---diff --git a/README_zh.md b/README_zh.mdindex f31cb2cf7..d77c13048 100644--- a/README_zh.md+++ b/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>---diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdnew file mode 100644index 000000000..86cce5b7c--- /dev/null+++ b/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 "[email protected]" \+ -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.diff --git a/docs/troubleshooting_zh.md b/docs/troubleshooting_zh.mdnew file mode 100644index 000000000..d3c5e0ea0--- /dev/null+++ b/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 "[email protected]" \+ -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 是否可用。diff --git a/tests/test_docs_funasr_install_commands.py b/tests/test_docs_funasr_install_commands.pyindex e208c5563..f6f10028d 100644--- a/tests/test_docs_funasr_install_commands.py+++ b/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",