FunASR：工业级离线/流式语音识别工具包部署与使用指南
FunASR 是阿里达摩院（ModelScope）开源的端到端语音识别基础工具包，定位为工业级离线、流式与边缘部署的一体化 ASR 框架。它把模型、运行时、服务化、客户端 SDK 整合在同一仓库，覆盖 ASR、VAD、标点恢复、说话人分离、情感识别、音频事件检测全链路，并提供 OpenAI 兼容的 HTTP 服务、Docker 镜像、llama.cpp/GGUF 单二进制边缘运行时，是国内工业界使用最广的中文 ASR 框架之一。FunASR 论文发表于 INTERSPEECH 2023。
一、项目官方信息
| 项目 | 信息 |
|---|---|
| GitHub 仓库 | modelscope/FunASR |
| 官方文档 | funasr.com |
| 开源协议 | MIT（工具包源码）；模型权重单独授权 |
| 主要语言 | Python |
| Star 数 | 21k+ |
| 旗舰模型 | Fun-ASR-Nano（800M）、SenseVoiceSmall（234M）、Paraformer-zh（220M） |
| 会议 | INTERSPEECH 2023 |
二、官方图片
FunASR 仓库社交预览图：
三、环境要求
- Python ≥ 3.8（服务化推荐 3.11）；
- 先安装 PyTorch 与 torchaudio（CPU 版直接装，GPU 版按 pytorch.org 选择对应 CUDA 版本）；
- GPU 推理需先验证
python -c "import torch; print(torch.cuda.is_available())"输出True，否则用device="cpu"； - 模型权重首次运行自动从 ModelScope/Hugging Face 下载；
- 边缘部署可选 llama.cpp/GGUF 单二进制，无需 Python 运行时。
四、部署步骤
1. pip 安装
pip install torch torchaudio
pip install funasr
2. 源码安装
git clone https://github.com/modelscope/FunASR.git && cd FunASR
pip install -e ./
3. 基础识别（Fun-ASR-Nano）
from funasr import AutoModel
model = AutoModel(model="FunAudioLLM/Fun-ASR-Nano-2512", device="cuda")
result = model.generate(input="asr_example_zh.wav")
print(result[0]["text"])
4. 中文生产流水线（VAD + ASR + 标点 + 说话人）
from funasr import AutoModel
model = AutoModel(
model="paraformer-zh",
vad_model="fsmn-vad",
punc_model="ct-punc",
spk_model="cam++",
device="cuda",
)
result = model.generate(input="asr_example_zh.wav", hotword="关键词 20")
5. 五语言识别 + VAD + 说话人（SenseVoiceSmall）
from funasr import AutoModel
from funasr.utils.postprocess_utils import rich_transcription_postprocess
model = AutoModel(
model="iic/SenseVoiceSmall",
vad_model="fsmn-vad",
spk_model="cam++",
device="cpu",
)
result = model.generate(input="asr_example_zh.wav", batch_size_s=300)
for seg in result[0]["sentence_info"]:
print(f"[{seg['start']/1000:.1f}s] Speaker {seg['spk']}: {rich_transcription_postprocess(seg['sentence'])}")
6. 流式实时识别
import soundfile as sf
model = AutoModel(model="paraformer-zh-streaming", device="cuda")
audio, sr = sf.read("speech.wav", dtype="float32") # 16 kHz mono
chunk_size = [0, 10, 5] # 600 ms chunks
chunk_stride = chunk_size[1] * 960
cache = {}
n_chunks = (len(audio) - 1) // chunk_stride + 1
for i in range(n_chunks):
chunk = audio[i * chunk_stride : (i + 1) * chunk_stride]
res = model.generate(input=chunk, cache=cache, is_final=(i == n_chunks - 1),
chunk_size=chunk_size, encoder_chunk_look_back=4, decoder_chunk_look_back=1)
if res[0]["text"]:
print(res[0]["text"], end="", flush=True)
7. CLI 命令行
funasr audio.wav
funasr audio.wav --output-format json
funasr audio.wav --output-format srt --output-dir ./subs
funasr audio.wav --spk --timestamps -f json
funasr audio.wav --model paraformer --language zh
funasr *.wav --output-format srt --output-dir ./output
可用模型：sensevoice（默认）、paraformer、paraformer-en、fun-asr-nano。
8. OpenAI 兼容 HTTP 服务
python3.11 -m venv .venv-funasr-http
. .venv-funasr-http/bin/activate
python -m pip install torch torchaudio
python -m pip install funasr fastapi uvicorn python-multipart
funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
调用：
curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
-F file=@sample.wav \
-F model=sensevoice \
-F response_format=verbose_json
9. Docker 流式服务
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
10. 边缘部署（llama.cpp/GGUF 单二进制）
bash download-funasr-model.sh sensevoice ./gguf
./llama-funasr-sensevoice -m ./gguf/sensevoice-small-q8.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav
Windows 支持 Vulkan 与 CUDA（含 Blackwell sm_120）后端，无需安装 CUDA Toolkit。
11. vLLM 大规模批量推理
from funasr.auto.auto_model_vllm import AutoModelVLLM
model = AutoModelVLLM(model="FunAudioLLM/Fun-ASR-Nano-2512", tensor_parallel_size=1)
results = model.generate(["audio1.wav", "audio2.wav"], language="auto")
五、使用方法
模型选择
- Fun-ASR-Nano：中英日 + 中文方言口音，800M，离线文件转写；
- Fun-ASR-MLT-Nano：31 语言版，800M；
- SenseVoiceSmall：中英日韩粤 + 情感/音频事件标签，234M，CPU 友好；
- Paraformer-zh / Paraformer-zh-streaming：中文离线/流式，220M；
- fsmn-vad + cam++：VAD 与说话人嵌入，作为 pipeline 组件；
- ct-punc：标点恢复；
- emotion2vec_plus_large：情感识别；
- MOSS-Transcribe-Diarize：第三方 OpenMOSS 离线 ASR + 时间戳 + 匿名说话人。
作为 AI Agent 工具
仓库提供 MCP Server（examples/mcp_server/）接入 Claude/Cursor；OpenAI 兼容 API 可被 LangChain/Dify/AutoGen 直接调用。
六、常见问题 FAQ
Q1：FunASR 是什么？ 工业级端到端语音识别工具包，支持离线、流式、边缘部署，覆盖 ASR/VAD/标点/说话人/情感全链路。
Q2：怎么安装？
先装 PyTorch+torchaudio，再 pip install funasr。
Q3：GPU 不可用怎么办？
把 device="cuda" 改成 device="cpu"，或重装对应 CUDA 版本的 PyTorch。
Q4：首次运行很慢？ 模型权重自动下载，800M 模型约 1.6GB，需耐心等待；后续走本地缓存。
Q5：怎么做到说话人分离？
AutoModel 加 spk_model="cam++"，结果在 sentence_info 里给匿名 speaker id。
Q6：支持流式识别吗？ 支持，用 Paraformer-zh-streaming 检查点与流式 SDK / WebSocket 服务。
Q7：边缘设备怎么部署？ 用 llama.cpp/GGUF 单二进制，无需 Python，中文 CER 比 whisper.cpp 低约 3 倍。
七、跳转链接
- GitHub 仓库：modelscope/FunASR
- 官方文档：funasr.com
- ModelScope 模型：Fun-ASR-Nano-2512
- Hugging Face：funasr
- llama.cpp 发布：Releases