FunASR：工业级离线/流式语音识别工具包部署与使用指南

FunASR 是阿里巴巴达摩院（ModelScope）开源的端到端语音识别基础工具包，论文发表于 INTERSPEECH 2023。它定位为面向离线识别、流式识别与边缘部署的工业级一体化语音识别框架，把模型权重、推理运行时、服务化网关与客户端 SDK 整合在同一仓库中，完整覆盖语音活动检测（VAD）、语音识别（ASR）、标点恢复、说话人分离与聚类、情感识别、音频事件检测等全链路能力，并对外提供 OpenAI 兼容的 HTTP 接口、Docker 镜像与 llama.cpp/GGUF 单二进制边缘运行时。无论是开发者在本地做一次命令行转写，还是企业要把长音频批量转成带时间戳与说话人标记的字幕，都可以在这一个工具包里找到对应方案，因此它也是国内工业界使用最广的中文 ASR 框架之一。

FunASR 与"单一模型仓库"不同：它是一个工具箱，需要使用者分别选择任务、checkpoint 与运行时。一个模型或适配器支持的能力，并不代表所有服务后端都支持——例如某个 GPU 拆分引擎能用的 checkpoint，边缘 GGUF 包未必覆盖；流式 checkpoint 也不能拿去跑离线批量。仓库在 README 中明确区分了任务、权重与运行时入口三层，并给出部署矩阵供选型，这也是它区别于纯模型发布仓库的关键设计。整体能力覆盖六大方向：ASR 语音识别、VAD 语音活动检测、标点恢复、说话人 pipeline（检测、嵌入、聚类编号）、情感与音频事件模型，以及 OpenAI 兼容服务；同时支持把能力封装为 MCP 服务接入 Claude/Cursor，封装为 OpenAI API 接入 LangChain/Dify/AutoGen，或通过实时转写插件接入私有部署的语音 Agent。

一、项目官方信息

一、项目官方信息

二、官方图片

FunASR 仓库封面与社交预览图：

说明：封面图已托管在本站附件目录，部署时无需重新下载。

三、环境要求

FunASR 同时提供纯 Python 工具链与免 Python 的 GGUF 边缘运行时，两类环境要求不同：

• Python 工具链：Python ≥ 3.8（跑 HTTP 服务官方推荐 3.11），PyTorch ≥ 1.13，并安装 torchaudio。先装 pip install torch torchaudio，再装 pip install funasr。
• GPU 支持：如果使用 NVIDIA 显卡，应先到 pytorch.org 选择与本机驱动匹配的 CUDA wheel，再安装 FunASR；安装后务必运行 python -c "import torch; print(torch.cuda.is_available())"，只有输出 True 时才把 device 设为 "cuda"，否则一律先用 device="cpu"。
• 模型下载：首次运行时权重会自动从 ModelScope 或 Hugging Face 拉取，需要预留磁盘与网络；离线内网可提前把模型目录拷入。
• 额外组件：使用 Silero VAD 需执行 pip install "funasr[silero]"；使用 OpenAI 兼容服务还需 fastapi uvicorn python-multipart。
• 边缘部署：llama.cpp/GGUF 路线只需一个自包含二进制，内置 FSMN-VAD，不要求 Python 运行时；Windows 可选用 Vulkan 包（装当前显卡驱动即可）或 CUDA 包（architecture 86 用标准包，RTX 50/Blackwell 用 windows-x64-cuda-blackwell 包）。

四、部署步骤

1. pip 安装（推荐）

pip install torch torchaudio
pip install funasr

升级到指定版本：

python -m pip install -U "funasr==1.4.16"

2. 源码安装

git clone https://github.com/modelscope/FunASR.git && cd FunASR
pip install -e ./

源码方式要求 Python ≥ 3.8、PyTorch ≥ 1.13 并已安装 torchaudio，适合需要阅读 SDK 契约或参与贡献的开发者。

3. 本地 OpenAI 兼容 HTTP 服务（CPU 配方）

在新目录中用 POSIX shell 与 Python 3.11 建立独立虚拟环境，把 PyPI 发布包装进去（而不是装当前源码 checkout）。该服务默认不内置鉴权，应只保留 loopback 监听；要对其他客户端开放前先阅读仓库内的安全指南。

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
python -m pip check
funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu

等模型下载完毕、服务启动后，另开一个终端用 curl 7.76 以上版本拉取公开样例音频并发起转写：

curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
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

4. Docker 流式服务

docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12

该镜像提供在线流式识别的 C++/WebSocket 服务端，适合客户端逐块推送音频的实时场景。需要离线联合转写与匿名说话人标注（moss-transcribe-diarize）时，应按官方 MOSS 文档准备独立环境，而不是在上述 CPU 环境里再叠一条命令；复用 8000 端口前先停掉 CPU 服务。

5. 边缘部署：llama.cpp / GGUF 单二进制

在 CPU 与边缘设备上，可用单个自包含二进制运行 SenseVoice、Paraformer 或 Fun-ASR-Nano，无需 Python，并内置 FSMN-VAD：

# Linux / macOS：在解压后的发布目录中执行
bash download-funasr-model.sh sensevoice ./gguf        # 也可使用 paraformer 或 nano
./llama-funasr-sensevoice -m ./gguf/sensevoice-small-q8.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav

Windows PowerShell 下需要先安装 hf CLI 再拉取权重：

hf download FunAudioLLM/SenseVoiceSmall-GGUF sensevoice-small-q8.gguf --local-dir .\gguf
hf download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir .\gguf
.\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav
# 使用 windows-x64-vulkan 包并装当前显卡驱动，可追加 --backend vulkan
# RTX 30 系列等 architecture 86 GPU 可使用 windows-x64-cuda 包，追加 --backend cuda

预编译二进制在 GitHub Releases 下载，当前 runtime 版本为 v0.2.6，提供 Linux Vulkan tarball、Windows Vulkan zip、Windows CUDA zip 与 Blackwell 专用 CUDA zip 四种包；Windows 包使用系统 Vulkan loader 与静态 MSVC runtime，用户只需装兼容 NVIDIA 驱动，无需另装 CUDA Toolkit。

6. vLLM 高吞吐批处理

Fun-ASR-Nano 可接入 vLLM 做高吞吐批处理，需使用文档指定的 GPU 拆分引擎环境，并以固定版本约束依赖：

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")

上线后应检查实际后端加载日志，不能仅凭模型名就认定 vLLM 已生效。

五、使用方法

1. 五语言识别 + VAD + 说话人（SenseVoiceSmall 流水线）

下面的示例先用 CPU，组合 FSMN-VAD 与 CAM++ 完成带说话人编号与时间戳的分段：

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="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav")

# AutoModel pipeline 返回带说话人 id 和时间戳的 VAD 分段：
for seg in result[0]["sentence_info"]:
    print(f"[{seg['start']/1000:.1f}s] 说话人{seg['spk']}: {rich_transcription_postprocess(seg['sentence'])}")

CAM++ 提取 spk_embedding 说话人嵌入，AutoModel 再对嵌入聚类并为 VAD 分段分配说话人编号；该编号只在当前录音内有效，不是已知人物身份识别，也不是 SenseVoiceSmall 权重的内置输出。需要 GPU 时先验证环境，再把 device 改为 "cuda"。

2. LLM 语音识别：Fun-ASR-Nano

Fun-ASR-Nano 基于 SenseVoice 编码器加 Qwen3-0.6B 解码器，是 LLM-ASR 模型，支持中文、英语、日语，并覆盖 7 种中文方言与 26 种地域口音：

from funasr import AutoModel

model = AutoModel(model="FunAudioLLM/Fun-ASR-Nano-2512", vad_model="fsmn-vad", device="cuda")
result = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav")

需要 31 语种时应改用独立的 Fun-ASR-MLT-Nano-2512 权重；Nano 与 MLT-Nano 语言范围不同，务必按 checkpoint 选择，不能把 31 语种能力归给基础 Nano。

3. 中文生产级流水线（VAD + 识别 + 标点 + 说话人）

from funasr import AutoModel

# 中文生产级（VAD + 识别 + 标点 + 说话人）
model = AutoModel(model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc", spk_model="cam++", device="cuda")
result = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav", hotword="关键词 20")

# 使用 Silero VAD（先安装：python -m pip install "funasr[silero]"）
model = AutoModel(
    model="paraformer-zh", vad_model="silero-vad", device="cpu",
    vad_kwargs={"silero_threshold": 0.5, "silero_min_silence_duration_ms": 100},
)
result = model.generate(input="audio.wav")

4. 流式实时识别（逐块喂音频）

import soundfile as sf
model = AutoModel(model="paraformer-zh-streaming", device="cuda")
audio, sr = sf.read("speech.wav", dtype="float32")   # 16 kHz 单声道
chunk_size = [0, 10, 5]                               # 每块 600ms
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)

流式识别必须使用流式 checkpoint 与独立会话 cache，不能用离线 checkpoint 顶替。

5. 情感识别

model = AutoModel(model="emotion2vec_plus_large", device="cuda")
result = model.generate(input="audio.wav", granularity="utterance")

6. 命令行工具（Agent 友好）

# 转写音频（最简用法）
funasr audio.wav

# JSON 输出（适合 AI Agent 调用）
funasr audio.wav --output-format json

# 生成 SRT 字幕
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。

7. 模型选择速查

此外模型库还收录 Qwen3-ASR（1.7B、52 语种）、GLM-ASR-Nano（1.5B、17 语种）、Whisper-large-v3（1550M）与 Whisper-large-v3-turbo（809M）等第三方或联合模型，以及 290M 的 ct-punc 标点恢复、0.4M 的 fsmn-vad、7.2M 的 cam++ 说话人嵌入与 300M 的 emotion2vec+large 情感识别。

8. 核心模型逐条说明

• Fun-ASR-Nano（800M）：基于 SenseVoice 编码器加 Qwen3-0.6B 解码器的 LLM-ASR，支持中、英、日三种语言，外加 7 种中文方言与 26 种地域口音；同时提供官方 -hf 权重、Python 工具链权重与 GGUF 边缘权重三套。
• Fun-ASR-MLT-Nano（800M）：独立的 31 语种版本 checkpoint，语言范围与基础 Nano 不同，不能把它的多语种能力归给基础 Nano。
• SenseVoiceSmall（234M）：识别加情感加音频事件三任务合一，覆盖中、英、日、韩、粤五语种；情感与事件标签是模型输出的文本标签，不代表说话人身份。
• MOSS-Transcribe-Diarize：由第三方 OpenMOSS 发布的离线模型，FunASR 只提供适配器而不拥有权重；一次完成长音频转写、时间戳与匿名说话人标注，说话人标签仅在当前录音内有效，不是实时流式或已知人物识别。
• Paraformer-zh（220M）与 Paraformer-zh-streaming（220M）：前者做中文生产级文件转写并带时间戳，后者是流式分块版本，二者 checkpoint 不通用。
• ct-punc（290M）：中英标点恢复模型，常与识别模型串成流水线。
• fsmn-vad（0.4M）：极小体积的语音活动检测模型，负责切分语音段，是几乎所有流水线的前置组件。
• cam++（7.2M）：说话人嵌入模型，输出 spk_embedding，供 AutoModel 聚类后分配匿名编号。
• emotion2vec+large（300M）：语音情感识别，可按整句或细粒度粒度输出情感类别。

六、最新动态与版本边界

• MOSS-Transcribe-Diarize 已接入 FunASR 服务、Docker、Kubernetes、vLLM/SGLang 工作流和 FunClip，可一次完成长音频转写、时间戳与匿名说话人标注。
• FunASR 1.4.16 修复了 VAD、标点和说话人子模型在多次推理时的显式设备放置问题，并新增经过测试的原生 Transformers 使用指南，升级命令为 python -m pip install -U "funasr==1.4.16"。
• 原生 Transformers 5.17.0 已正式支持 Fun-ASR-Nano：不想装 FunASR 工具库或执行远程 Python 代码时，可直接用 Hugging Face API 转写，官方提供 CPU 快速开始、在线 Notebook 与 Python/批处理示例。
• 完整改动记录与可下载资产以 GitHub Releases 为准。

七、评测与可复现

官方历史评测报告与拆分引擎测量是两份独立记录，保留原始结果，不能合并成通用速度排名或生产容量承诺。要对齐评测口径，必须统一 checkpoint/revision、音频集、硬件、批量大小、预热步骤、计时范围与 CER/WER 指标；离线吞吐量不等于流式延迟。计划从 Whisper 或云端 ASR 迁移时，应按官方迁移指南用代表性音频评测、映射功能后再安全上线。

八、AI Agent 与第三方集成

• MCP 服务：仓库内置 MCP server 示例，可把 FunASR 封装为 Claude/Cursor 可调用的工具。
• OpenAI API：提供 OpenAI 兼容服务端，支持 LangChain、Dify、AutoGen 等编排框架接入，并附客户端配方、JavaScript/TypeScript 配方、Postman 集合、OpenAPI 规范与 Kubernetes 模板。
• 语音 Agent：OpenClaw 实时转写插件支持私有部署的 Talk 与 Voice Call；社区还提供 Hugging Face speech-to-speech 加 SenseVoice 的方案。
• Gradio 演示：仓库提供 OpenAI API 配套的 Gradio Demo，便于快速体验。

九、常见问题 FAQ

Q：装好后报 CUDA 不可用怎么办？ A：先运行 python -c "import torch; print(torch.cuda.is_available())"，输出为 False 时把代码里的 device="cuda" 改回 "cpu"，或按 pytorch.org 重装与驱动匹配的 CUDA wheel，不要在 CPU 环境强行指定 cuda。

Q：Fun-ASR-Nano 为什么只能转中英日？ A：基础 Nano 覆盖中/英/日及 7 种中文方言、26 种地域口音；需要 31 种语言必须换用独立的 Fun-ASR-MLT-Nano-2512 权重，两者不能混用。

Q：说话人编号能用来识别"这是谁"吗？ A：不能。CAM++ 只在同一段录音内对嵌入做聚类并分配匿名编号，跨录音不连续，也不做已注册人物身份识别。需要已知人物身份应另行建立声纹库。

Q：流式接口能直接用 paraformer-zh 离线权重吗？ A：不能。分块实时转写必须使用 paraformer-zh-streaming 流式 checkpoint，配合独立会话 cache 与 chunk_size=[0,10,5]（每块 600ms），离线权重无法顶替。

Q：GGUF 权重能直接在 Python AutoModel 里加载吗？ A：不能。GGUF 只用于 llama.cpp 边缘运行时；Python 工具链请使用 ModelScope/Hugging Face 上的常规 checkpoint。

Q：服务起来后端口被占用？ A：funasr-server 默认示例用 8000 端口；MOSS 联合服务复用同一端口前需先停掉 CPU 服务，避免端口冲突。

Q：性能评测怎么看？ A：官方历史评测与拆分引擎测量是独立记录，不能合并成通用速度排名。请按 RTFx 与可复现评测说明对齐 checkpoint/revision、音频集、硬件、批量大小、预热与计时范围后自测；离线吞吐量不等于流式延迟。

Q：许可证上有什么要注意的？ A：本仓库的 FunASR 工具包源码采用 MIT 协议，但预训练模型权重单独授权，需以各模型卡标注的协议为准；若模型卡链接仓库内的 FunASR 模型开源协议，则适用该协议。第三方 MOSS 模型另有其协议，商用前务必分别核对。学术引用可使用 INTERSPEECH 2023 的 FunASR BibTeX 条目。

Q：第一次接触该从哪开始？ A：不想先配本地环境的，可直接打开仓库提供的 Colab 快速体验，在浏览器里转写公开样例或上传自己的音频；还不确定选哪个模型的，先看官方模型选择指南；计划从 Whisper 或云端 ASR 切换的，按迁移指南用代表性音频评测后再上线。

十、跳转链接

• GitHub 仓库：modelscope/FunASR
• 官方站点与部署中心：funasr.com
• 在线文档：FunASR 文档中心
• ModelScope 模型：FunAudioLLM 组织
• Hugging Face：FunASR 账号
• SenseVoice 论文：arXiv:2407.04051
• 运行时发布：Releases v0.2.6
• 问题反馈：GitHub Issues