FunASR 语音识别本地部署：从环境自检到首次转写的 3 条路径

FunASR 语音识别本地部署从环境自检到首次转写的 3 条路径【免费下载链接】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 语音识别工具包可以在自己的机器上跑完整条转写流水线音频不出机器也不用向云端按分钟付费。读完这篇你能独立完成安装、跑通第一次本地转写并知道常见报错该查哪里。一、能力速览FunASR 工具箱里装了什么先用一段话把盒子里有什么讲清楚。FunASR 是阿里巴巴达摩院开源的语音识别工具箱MIT 协议模型权重单独授权它不是单一模型而是模型 流水线 部署工具的组合你按场景挑模型它把语音端点检测VAD、识别、标点恢复、说话人分离拼成一条流水线一次调用出结果。场景对应组件一句话说明离线文件转写SenseVoiceSmall录音丢进去出带标点完整文字CPU 上约 17 倍实时实时流式听写Paraformer 流式模型 2pass边说边出字先快速出字再由离线模型修正说话人分离 时间戳FSMN-VAD CAM输出说话人 0 在第 0.6 秒说了……的分句标点恢复CT-Transformer给裸文本自动加标点中英文都支持服务化OpenAI 兼容接口 / MCP一条命令起/v1/audio/transcriptions可对接 AI Agent流式听写走的 2pass 路线结构如下模型库Paraformer、FSMN-VAD、CT-Transformer 等经过中间的 funasr 核心库通向三条出口Python 示例训练 / 推理 / 微调、Runtime 导出LibTorch / ONNX / TensorRT、各种服务形态gRPC、WebSocket、Triton。二、✅ 环境检查清单安装之前逐项核对大多数安装问题用下表逐项核对就能挡在动手之前。项目标准验证命令操作系统Linux / Windows / macOS 均可—Python≥ 3.8python --versionPyTorch torchaudioPyTorch ≥ 1.13且两者来自同一安装渠道python -m pip list \| grep -E torch\|torchaudioGPU可选没有也能 CPU 跑但要换模型选择装好后运行torch.cuda.is_available()打印True才能用devicecuda磁盘空间模型缓存需几个 GB 空闲SenseVoiceSmall 约 234M 参数Fun-ASR-Nano 约 800M常规磁盘管理即可网络首次运行自动下载模型国内网络 ModelScope 入口更稳见报错对照章第二条CPU 与 GPU 的取舍不是能不能跑而是选哪个模型CPU 上选 SenseVoiceSmall 或 ParaformerFun-ASR-Nano支持中文方言和 26 种地域口音的 LLM-ASR需要 GPU。更细的环境说明见安装与环境细节。三、三条安装路径FunASR 安装的最短路线挑一条走装完直接进入验收章。已有 Python 环境两行命令搞定适合已有 Python 环境的 Linux / macOS / Windows顺序是先装推理框架再装工具包。# 第一步安装 PyTorch 和 torchaudioCPU 环境直接装默认 wheel python -m pip install -U torch torchaudio # 第二步安装 FunASR 工具包 python -m pip install -U funasr装完你多得到一个 Python 库funasr和一个命令行工具funasr两者都能直接用。要改源码或追最新 commit适合参与开发、或需要最新修复的场景先克隆仓库再以可编辑模式安装。# 克隆仓库gitcode 镜像地址 git clone https://gitcode.com/GitHub_Trending/fun/FunASR cd FunASR # 以可编辑模式安装改动源码即时生效 python -m pip install -e ./这一步执行后pip里注册的funasr指向本地源码目录后续改代码不用重装。Windows 或不想碰 Python预编译二进制机器是 Windows、或只想跑独立可执行文件时走基于 llama.cpp 的 GGUF 预编译包单个自包含二进制、无需 Python、内置 FSMN-VAD支持 SenseVoice / Paraformer / Fun-ASR-Nano。# 第一步下载 GGUF 模型到本地 gguf 目录Windows PowerShell 示例 hf download FunAudioLLM/SenseVoiceSmall-GGUF sensevoice-small-q8.gguf --local-dir .\gguf hf download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir .\gguf # 第二步运行识别CPU 直接跑Vulkan/CUDA 包按所选硬件执行 .\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wavWindows 包分 CPU、Vulkan、CUDA 三类Vulkan 包用显卡驱动自带系统 Vulkan loader、不另装 SDKCUDA 包面向特定 GPU 架构且已内置所需 cuBLAS DLL按自己硬件对号入座。你得到的是一个零依赖、直接可跑的二进制。还有一条零安装路径不想配置本地环境的话打开仓库里的 Colab 快速体验在浏览器里转写公开样例或上传自己的音频。四、验收三关确认 FunASR 部署成功装完先用三关确认装对了任何一关通过即可。第一关Python 最小流水线。组合 SenseVoiceSmall FSMN-VAD CAM看到带说话人标签和时间戳的输出即为通过# SenseVoiceSmall FSMN-VAD CAM 最小流水线device 按自检结果填 cuda 或 cpu from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess model AutoModel(modeliic/SenseVoiceSmall, vad_modelfsmn-vad, spk_modelcam, devicecpu) result model.generate( inputhttps://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav) # 期望输出带说话人 id 和时间戳 for seg in result[0][sentence_info]: print(f[{seg[start]/1000:.1f}s] 说话人{seg[spk]}: {rich_transcription_postprocess(seg[sentence])}) # [0.6s] 说话人0: 欢迎大家来体验达摩院推出的语音识别模型首次运行会自动把模型下载到缓存目录出现下载进度条属于正常现象耐心等第一次即可。第二关CLI 一行命令。# 命令行最简验证默认模型直接出文字、json 结构化输出、srt 生成字幕 funasr audio.wav # 最简用法默认 sensevoice 模型 funasr audio.wav -f json # 结构化输出便于程序处理 funasr audio.wav -f srt -o ./subs # 直接生成 SRT 字幕文件可选模型sensevoice默认、paraformer、paraformer-en、fun-asr-nano完整选项表见命令行完整选项。第三关可选服务端口可访问。走服务化路线时先装fastapi uvicorn python-multipart起服务后做冒烟测试# 启动 OpenAI 兼容服务默认监听 8000 端口 funasr-server --model sensevoice --device cuda# 用一段本地 WAV 打接口返回转写 JSON 即为成功 curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions \ -F fileexample.wav \ -F modelFunAudioLLM/SenseVoiceSmall三关命中任意一关即安装无误全部没有直接去报错对照章。五、显存不够三步降档调 batch 参数这一章只处理三个参数都出现在generate调用里因果链比背数值更重要。参数它管什么什么时候动它batch_size_s动态 batch 的总音频时长秒默认示例常用 300显存不够第一步先减它推理起始阶段显存占用主要由它决定batch_size_threshold_s超过该阈值强制 batch 降为 1VAD 切出的长片段仍 OOM 时调小它max_single_segment_timeVAD 单段最长时间毫秒前两招都不够时缩短 VAD 切段长度CPU 机器不用纠结 batch选 SenseVoiceSmall 或 Paraformer-zh 单条跑即可SenseVoice 在 CPU 上约 17 倍实时音频很长时直接一次传入整条流水线内部会做 VAD 切分。单卡 GPU、内存 16GB 左右batch_size_s300起步遇到 OOM 按上表顺序依次调小。高吞吐批处理换用 vLLM 推理路径AutoModelVLLMFun-ASR-Nano 配 vLLM 官方基准可达 340 倍实时这已经超出参数调优范畴属于换引擎。口诀一句话先降batch_size_s再降batch_size_threshold_s最后才碰max_single_segment_time一上来就改短 VAD 段长会牺牲识别质量。六、 报错对照四个高频问题的快答先对报错再找原因。import funasr 失败 / DLL 架构错误大概率是torch、torchaudio、funasr版本或安装渠道不匹配混装了不兼容的 CUDA wheel。 先装torch和torchaudio再装funasr三者来自同一渠道且版本兼容仍失败就新建干净虚拟环境复现并记录 Python 版本、操作系统、pip list | grep -E torch|torchaudio|funasr和完整报错。模型下载慢或反复失败默认模型源与网络环境不匹配或断点缓存损坏。 国内网络优先走 ModelScope 源海外 Hugging Face 通常更快下载中断后只清理该模型的半截缓存再重试不要整个缓存目录一删了之。funasr-server 起来了但接口 4xx/5xx服务依赖缺失FastAPI、Uvicorn、multipart 上传支持或浏览器 CORS 被默认关闭拦截。 先用一段很短的本地 WAV 对/v1/audio/transcriptions做冒烟测试curl 能通但浏览器报错时按funasr-server --device cpu --model sensevoice --cors-origin http://localhost:3000重启每个可信 origin 都要重复传一次。WebSocket 实时识别输出为空或延迟巨大客户端音频格式与服务端要求不匹配——采样率、通道数、chunk size、PCM 编码任一不对都会看起来像服务端故障长静音也会触发误判。 先用一段已知可用的短 WAV 排查确认 16kHz 单声道 PCM 后再换长音频逐步定位。更多细节见故障排查详解。七、 跑通之后三条进阶路线能跑通之后往哪走三条路线各占一段。接入 AI Agent 与业务系统。OpenAI 兼容接口可以直接对接 LangChain、Dify 等编排框架完整示例见openai_api 示例仓库自带 MCP 服务examples/mcp_server/让 Claude、Cursor 直接调用转写能力语音 Agent 场景可看 OpenClaw 实时转写插件。提升特定领域准确率。用热词做软提示是最轻量的手段——Python 侧model.generate(input..., hotword关键词 20)命令行侧funasr audio.wav --hotwords FunASR,达摩院热词是提升提示而非确定性纠错电话车牌这类强专业场景建议走微调路线训练脚本参考examples/aishell/。换更强的识别引擎。中文方言、多语种混杂的复杂音频把模型换成 Fun-ASR-Nanodevicecuda或 31 语种的 Fun-ASR-MLT-Nano高吞吐场景切 vLLM 推理路径AutoModelVLLM。离线流水线内部结构见下图语音进来先过 FSMN-VAD 切段再经声学模型、解码器、标点预测、逆文本正则化逐级处理。八、继续深挖的入口文档与示例索引安装与环境细节命令行工具完整选项模型选择指南从 Whisper 或云端 API 迁移服务部署SDK、Docker、实时 / 离线使用案例与社区集成社区项目列表模型列表与链接汇总Colab 零安装体验最直接的行动有 GPU 的走路径一加第一关Windows 无 Python 环境的直接跑预编译包。看到终端上输出欢迎大家来体验达摩院推出的语音识别模型就算真正入门了。【免费下载链接】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），仅供参考