FunASR 语音识别：两条命令装好，本地第一次转写 10 分钟跑通

FunASR 语音识别：两条命令装好，本地第一次转写 10 分钟跑通

【免费下载链接】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 是一套可本地部署的开源语音识别工具箱，新手没有显卡的 CPU 机器就能起步：VAD、转写、标点、说话人分离串成一条流水线，一次调用直接出文字。工具源码 MIT 协议，模型权重按各模型卡标注的协议执行，不走按分钟计费的云端。

装 FunASR 之前确认三件事

• Python ≥ 3.8，python --version看一眼；
• PyTorch ≥ 1.13，且 torchaudio 与 torch 来自同一安装渠道，混装是后面 import 报错的头号原因；
• 磁盘留几个 GB，首次运行会自动下载模型权重，SenseVoiceSmall 只有几百 MB。

没有显卡也没关系。CPU 和 GPU 的区别不是"能不能跑"，而是"选哪个模型"：CPU 上 SenseVoiceSmall、Paraformer 都够用；基于 LLM 的 Fun-ASR-Nano（支持中文方言和 26 种地域口音）需要显卡。

pip 安装（有 Python 环境就走这条）

新手最常见的路线，三条命令：

python3 -m venv .venv && source .venv/bin/activate # 建独立虚拟环境 python -m pip install -U torch torchaudio # 先装推理框架 python -m pip install -U funasr # 再装 FunASR

源码安装（想改代码或跟进最新修复）

先git clone https://gitcode.com/GitHub_Trending/fun/FunASR，再进 FunASR 目录执行python -m pip install -e .。可编辑模式注册后，改源码即时生效，不用重装。更细的环境配置（Conda、离线机器）见 docs/installation/installation_zh.md。

预编译包（Windows / 没有 Python 的机器）

仓库提供基于 llama.cpp 的 GGUF 预编译包：单个自包含二进制，不需要 Python，内置 FSMN-VAD，支持 SenseVoice / Paraformer / Fun-ASR-Nano。下好 GGUF 权重后执行llama-funasr-sensevoice -m sensevoice.gguf --vad fsmn-vad.gguf -a audio.wav即可转写，CPU / Vulkan / CUDA 三种构建按硬件选，细节在 runtime/llama.cpp/README.md。

怎么确认装对了？先跑一次最省事的。

第一次转写：看到这行输出就说明装对了

最小示例就五行的量：

from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess model = AutoModel(model="iic/SenseVoiceSmall", device="cpu") result = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav") print(rich_transcription_postprocess(result[0]["text"]))

首次运行会自动下载模型，看到进度条属正常。终端里打印出一句中文，比如"欢迎大家来体验达摩院推出的语音识别模型" ✅ 安装就成功了；有显卡的机器把device="cpu"换成"cuda"速度更快。

不想写 Python 也行，命令行一条出字：

funasr audio.wav # 默认 sensevoice，输出纯文本 funasr audio.wav -f json # 结构化输出，方便程序解析 funasr ./*.wav -f srt -o ./subs # 批量生成 SRT 字幕

注意 CLI 只接受本地文件，不接受 URL。换模型用--model paraformer，加热词用--hotwords "FunASR,达摩院"。

能做什么：对号看你的场景

整箱东西有三类出口：用 Python 脚本做训练、推理、微调；导出成 LibTorch / ONNX / TensorRT 做原生部署；或者直接起 gRPC、WebSocket、Triton 这类服务。模型侧 Paraformer、FSMN-VAD、CT-Transformer 等按需取用。

按场景挑路：

• 离线会议纪要：录音丢进去，出来带标点的完整文字。CPU 上 SenseVoiceSmall 约 17 倍实时，30 分钟的录音一分多钟处理完。
• 实时听写：WebSocket 服务走 2pass 模式，流式模型先出字，VAD 检测到尾点后用离线模型修正加标点。
• 区分谁说了什么：FSMN-VAD 配 CAM++，输出带说话人标签和时间的分句，纪要不用猜。
• 服务化：funasr-server起一个 OpenAI 兼容的/v1/audio/transcriptions接口，curl 就能调，也方便对接编排框架。

显存爆了或者太慢？按这个顺序调参数

遇到 OOM，generate里先看这三项：

⚠️ 别一上来就缩短 VAD 段长，那会牺牲识别质量。高吞吐批处理场景别在参数上纠缠，直接换引擎：AutoModelVLLM走 vLLM 路线，Fun-ASR-Nano 配 vLLM 的官方基准能到 340 倍实时。

卡住了？对照这四个高频问题

import funasr报 DLL 或架构错误大概率是 torch、torchaudio、funasr 来自不同安装渠道。按 torch → torchaudio → funasr 的顺序同渠道重装；还不行就新建干净虚拟环境，记下pip list和完整报错。

模型下载慢或反复失败大概率是 hub 源和网络不匹配，或半截缓存损坏。默认走 ModelScope，海外网络加--hub hf换 Hugging Face；中断后只清那个模型的缓存重试，别把整个缓存目录删了。

服务起来了但接口 4xx/5xx大概率缺 FastAPI、Uvicorn、multipart 上传依赖。先用一段很短的本地 WAV 对/v1/audio/transcriptions冒烟测试；curl 通但浏览器被拦时，重启加--cors-origin传精确 origin，多个可信源要各传一次。

实时识别输出为空或延迟巨大大概率是客户端音频格式不匹配——采样率、通道、chunk、PCM 编码任何一个不对都像服务端故障。先确认 16kHz 单声道 PCM，用一段已知能跑的短 WAV 定位。更多情况翻 docs/troubleshooting_zh.md。

跑通之后，还有三条路可以往深走

如果你想接入业务系统：OpenAI 兼容接口直接对接 LangChain、Dify，完整示例在examples/openai_api/；想让 Claude、Cursor 直接调用转写能力，用examples/mcp_server/里现成的 MCP 服务。

如果你想提升特定领域准确率：热词是最轻量的软提示，Python 侧model.generate(input=..., hotword="关键词 20")，命令行侧--hotwords；但热词是提示增强而非确定性纠错，电话车牌这类强专业场景建议走微调，训练脚本参考examples/aishell/。

如果你想规模化上生产：runtime/下有 Docker 镜像、Triton 部署材料，模型怎么选细看 docs/model_selection_zh.md。

打开终端，把安装那三条命令敲一遍，终端里出现那句"欢迎大家来体验达摩院推出的语音识别模型"，你就入门了。

【免费下载链接】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