FunASR 排障实战指南从安装失败、模型下载卡顿到服务端延迟与 GGUF Runtime 启动问题的完整排查手册【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR导读本文是一份以首次安装与部署 FunASR 时最容易踩坑的问题为核心的排障 FAQ。围绕官方文档 docs/troubleshooting_zh.md 的骨架结合仓库源码如 funasr/bin/server.py、funasr/bin/_server_app.py、setup.py与测试用例逐类拆解安装/import 失败、模型下载慢、OpenAI 兼容接口请求失败、WebSocket 实时输出为空或延迟大、llama.cpp/GGUF runtime 无法启动等高频问题。读完本文你将掌握一套从环境准备、最小复现到提交可诊断 issue 的标准排障流程并能对照源码理解每个排查动作背后的原因。一、先明确定位这份 FAQ 解决什么问题这份 FAQ 不是通用 ASR 理论教程而是聚焦「第一次安装和部署」阶段的阻塞性问题。最近 issue 巡检显示最容易卡住首次试用者的有三类问题问题类别典型现象对应排查章节安装路径不确定不知道用哪个安装命令、哪个 model id、哪个 hub安装或 import 失败、模型下载慢或失败runtime 包选错CPU、CUDA、Vulkan、GGUF 不知道该下载哪个包llama.cpp 或 GGUF runtime 无法启动服务端输出异常实时服务、VAD、vLLM 或 server 输出延迟、为空、与本地 Python 不一致funasr-server启动后 OpenAI 兼容接口请求失败、WebSocket 实时输出为空或延迟很大另有一类被反复问到的问题是「电话车牌、方言、重复确认语音如何微调和评测」这类问题对应独立指南 车辆车牌微调指南。需要特别提醒热词是软提示soft prompt不是确定性的车牌纠错机制不要期望热词能百分百纠正识别结果。选型相关的问题不在这份 FAQ 范围内模型怎么选请参考模型选择指南服务化部署选型请参考部署选型。二、安装或 import 失败2.1 标准安装顺序先 torch后 FunASR最常见的 import 失败原因是依赖顺序颠倒或 torch 生态版本不齐。官方推荐的顺序是python -m pip install -U torch torchaudio python -m pip install -U funasr1.3.26先安装torch与torchaudio再安装 FunASR可以让 FunASR 在安装时基于已就位的 torch 版本解析依赖。从 setup.py 的install依赖组可以看到FunASR 的核心运行时依赖包括scipy、librosa、soundfile、PyYAML、omegaconf、hydra-core、modelscope、huggingface_hub、safetensors、transformers、sentencepiece等其中并没有硬性固定 torch 版本——这正说明 torch 生态的版本兼容需要由用户自己保证。2.2 保持 torch / torchaudio / torchvision 同源同版本torch、torchaudio、torchvision三者必须来自同一安装渠道且版本兼容。如果同时使用 vLLM请按照 vLLM 指南 配置环境避免在同一个环境里混装不匹配的 CUDA wheel。混装典型的症状是import torch 正常但一加载模型就报算子不匹配或libcudart版本冲突。2.3 仍然失败时的标准复现姿势如果 import 仍然失败官方建议新建一个干净的虚拟环境venv/conda均可在Deployment Helpissue 中附上完整环境信息Python 版本、操作系统、CUDA driver 版本pip list | grep -E torch|torchaudio|funasr的输出完整的 traceback不要只贴最后一行错误。从源码看funasr-server这类入口同样在启动时检查关键依赖funasr/bin/server.py 在import uvicorn/import fastapi失败时会打印Install with: pip install vllm fastapi uvicorn python-multipart并退出这也是典型的「服务已装但 extras 未装」报错。排查 import 问题时先区分是 FunASR 本体缺依赖还是某个命令入口server、train、export缺额外的 extras 依赖。三、模型下载慢或失败3.1 按网络环境选择 hub模型下载慢大多不是模型本身的问题而是网络路径选择问题中国大陆网络优先尝试 ModelScope。README 和 model_zoo 中iic/...开头的模型名是当前官方入口凡是命令支持 hub 参数的地方都可以显式选择 ModelScope。海外网络通常 Hugging Face 更快。GGUF 和边缘 runtime 模型请使用 Hugging Face 上 FunAudioLLM 组织的公开仓库例如FunAudioLLM/Fun-ASR-Nano-GGUF、FunAudioLLM/SenseVoiceSmall-GGUF。从 funasr/bin/server.py 可以看到服务端默认--hub msModelScope可通过--hub hf切换到 HuggingFace也支持--model-path直接指向本地模型路径或远端 model id——这意味着模型下载失败时可以先在本地手动下载好模型目录再通过--model-path指向它绕开运行时下载这一环节。3.2 中断后的处理下载中断后只清理该模型的半截缓存再重试不要清空整个缓存目录。提交Deployment Helpissue 时附上 hub、model id、网络环境和错误日志便于维护者判断是网络问题还是仓库问题。四、funasr-server启动后 OpenAI 兼容接口请求失败4.1 先确认服务依赖齐全funasr-server是 OpenAI 兼容的 ASR HTTP 服务入口依赖 FastAPI、Uvicorn 和 multipart upload 支持python-multipart。缺失任一依赖都会导致请求阶段失败。安装时可参考 examples/openai_api/README_zh.md 中的环境准备说明。4.2 接入前先做最小 smoke test在接入 agent 或 SDK 之前先用一个很短的本地 WAV 文件对转写路由做冒烟测试curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions \ -F fileexample.wav \ -F modelFunAudioLLM/SenseVoiceSmall这一步把问题空间一分为二curl 能通说明服务本身正常问题在客户端一侧curl 不通说明要回看服务配置与日志。仓库中的 examples/openai_api/smoke_test.py 提供了脚本化的冒烟测试可用--base-url与--model参数指向本地服务。4.3 curl 通但浏览器报 CORS按精确 origin 重启CORS 是浏览器安全策略不是鉴权或网络访问边界这一点在 examples/openai_api/SECURITY_zh.md 中反复强调。如果 curl 成功而浏览器报 CORS 或 network error需要按浏览器页面的**精确 originscheme、host、port**重启服务funasr-server --device cpu --model sensevoice \ --cors-origin http://localhost:3000源码实现印证了这里的两个关键行为CORS 默认关闭funasr/bin/server.py 中--cors-origin参数是actionappend且defaultNone不传即不启用每个可信 origin 都要单独传一次actionappend意味着可以重复传入例如同时使用localhost和127.0.0.1时要写两遍。在 funasr/bin/_server_app.py 中传入的 origins 会先做去重、剔除空串再注册CORSMiddleware且allow_credentialsFalse、方法限定为GET/POST/OPTIONS、请求头限定为Authorization与Content-Type。安全提示浏览器 CORS 默认关闭当机器可能被其他用户访问时不要使用通配符*作为 origin。CORS 只解决浏览器跨域策略问题不替代鉴权——生产环境请按 examples/openai_api/SECURITY_zh.md 配置 TLS、鉴权、上传大小限制与速率限制。4.4 请求返回 4xx / 5xx 时该附什么如果/v1/audio/transcriptions返回 4xx 或 5xx请在 issue 中附上启动命令、完整 server log、请求命令、model id、hub 和音频时长。注意--model auto时的默认行为从 funasr/bin/_server_app.py 可以看到cuda*设备默认加载fun-asr-nano其他设备默认加载sensevoice——如果预期模型与实际加载模型不一致也会表现为「结果和本地 Python 不一样」。五、WebSocket 实时输出为空或延迟很大实时场景流式字幕、客服语音的问题往往不是服务端宕机而是音频格式契约不匹配检查客户端发送的音频格式是否符合 WebSocket demo 要求尤其是采样率、通道数、chunk size 和 PCM 编码先使用一段已知可用的短 WAV 文件排查。长静音、不支持的编码、采样率不匹配都可能表现为「服务端没反应」看起来像服务端失败长静音会被 VAD 判定为无人说话输出为空是符合预期的行为不要误判为服务故障。WebSocket 相关的服务入口与协议说明参见 runtime/readme_cn.md 和 runtime/docs/websocket_protocol_zh.md。提交Deployment Help时请附上WebSocket URL、客户端命令或浏览器 console 输出、model id、采样率、以及服务端 session statistics如每个会话接收/返回的包数与字节数。六、llama.cpp 或 GGUF runtime 无法启动6.1 下载正确的 release 包GGUF 边缘部署走的是 llama.cpp 路径需要下载当前runtime-llamacpp-v0.1.9release 包README 与部署 hub 页面均有入口。该 runtime 的完整说明、构建方式与测试样例位于 runtime/llama.cpp/README.md包含 VAD、SenseVoice、Paraformer、Fun-ASR-Nano 等多个 GGUF 推理组件。6.2 按机器环境选择包类型包类型适用条件备注CPU 包兼容性最好几乎任何机器可用首次排障的首选Vulkan 包需要机器上有可用的 Vulkan runtime面向集成显卡/跨厂商 GPUCUDA 包需要兼容的 NVIDIA driver面向 NVIDIA GPU选包错误的典型表现是启动即报 driver / runtime 相关的动态库错误。6.3 使用正确的 GGUF 模型仓库GGUF 模型请使用 Hugging Face 上 FunAudioLLM 当前的公开仓库例如FunAudioLLM/Fun-ASR-Nano-GGUF或FunAudioLLM/SenseVoiceSmall-GGUF。模型文件与 runtime 版本需要配套混用旧模型文件与新 runtime 也可能导致启动失败。6.4 GPU 问题的诊断材料清单GPU 相关问题请在Deployment Helpissue 中附上nvidia-smi输出操作系统、driver 版本runtime 包名、模型文件名完整的 llama.cpp 启动命令不要只贴报错最后几行。七、提交 Deployment Help issue 需要提供什么一份可被快速定位的 issue 应尽量包含以下四类信息环境基线操作系统、Python 版本、安装命令、虚拟环境工具加速栈torch、torchaudio、CUDA、driver 和 GPU 信息GPU 问题必须附nvidia-smi任务参数FunASR 版本、model id、hubModelScope或Hugging Face和部署方式本地 Python / HTTP server / WebSocket / GGUF runtime复现材料精确命令、最小音频样例信息、完整错误日志以及同一音频在本地 Python pipeline 是否可用——这一条最关键它能立刻区分「模型/音频问题」还是「服务化封装问题」。八、排查方法论小结把这份 FAQ 串起来可以提炼出四条通用的排障原则分层验证本地 Python pipeline → curl smoke test → 浏览器/客户端接入逐层确认问题边界。参考 tests/run_test.py 中已有的冒烟测试组织方式先跑最小样例再上复杂场景。环境可复现固定 Python/torch/torchaudio 版本、固定 model id 与 hub、固定 runtime 包版本保证报错可被他人重现。音频先行所有服务端「没反应」的怀疑都先用一段已知可用的短 WAV 验证——很多看起来像服务端失败的问题实际上是采样率、编码或静音段的问题。信息给全报错时给出「启动命令 完整日志 环境信息 最小复现输入」而不是只贴一行错误提示。按这个流程走一遍绝大多数首次安装和部署 FunASR 时的阻塞问题都能在几分钟内定位到具体环节。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考