# FunASR 开源语音识别工具包

## 项目概述

FunASR 是 ModelScope 社区推出的工业级端到端语音识别工具包，定位为"基础端到端语音识别工具包"。它并非单一模型，而是一套包含训练、推理、流式 ASR、VAD、标点恢复、说话人分离等完整流水线的开源工具集。项目采用 MIT 许可证开源，核心代码使用 Python 编写。官方推荐模型包括 Fun-ASR-Nano（中英日及中文方言、需 GPU）、Fun-ASR-MLT-Nano（31 种语言）、SenseVoiceSmall（中英日韩粤五语言并支持情感与音频事件识别）以及 Paraformer（低延迟流式识别）。项目同时提供 OpenAI 兼容 API 服务、MCP Server、vLLM 加速和 llama.cpp/GGUF 边缘端部署能力。

## 核心功能

- 离线批量语音识别（ASR）：支持 Fun-ASR-Nano、SenseVoiceSmall、Paraformer、Qwen3-ASR、GLM-ASR、Whisper 等多个系列模型，按需选用。
- 实时流式识别：基于 Paraformer-zh-streaming，支持 WebSocket 服务，可逐块输入音频并输出中间结果，也可配合 vLLM 为 Fun-ASR-Nano 提供流式解码。
- 语音活动检测（VAD）：内置 FSMN-VAD 模型，支持动态静音阈值，用于切分长音频并保留短句完整性。
- 标点恢复：ct-punc 模型可为识别文本恢复中英文标点。
- 说话人分离：通过 CAM++ 模型实现说话人识别与分离，配合 VAD 输出带说话人标签和时间戳的结构化结果。
- 情感识别与音频事件：SenseVoiceSmall 与 emotion2vec+large 支持情感识别，SenseVoiceSmall 还可输出音频事件标签。
- 热词与关键词：支持 `hotword` 参数和 `POSTPROCESS_HOTWORDS` 确定性后处理纠错，也支持解码阶段偏置。
- 字幕生成：CLI 支持直接输出 SRT/TSV 字幕文件，并自动请求句级时间戳和标点。
- 服务化部署：`funasr-server` 提供 OpenAI 兼容的 `/v1/audio/transcriptions` API；`funasr-realtime-server` 提供 WebSocket 流式服务。
- 智能体集成：提供 MCP Server 示例，可与 Claude、Cursor 等桌面智能体集成；提供 OpenAI API 示例以接入 LangChain、Dify、AutoGen 等。
- 边缘端推理：llama.cpp/GGUF 运行时可将 SenseVoice、Paraformer、Fun-ASR-Nano 编译为单一自包含二进制，在 CPU/边缘设备上运行，运行时无需 Python。
- 训练与微调：支持数据准备、模型训练、Fun-ASR-Nano LoRA 微调等流程。

## 适用与不适用场景

**适用场景：**

- 中文会议转写、录音归档、字幕生成，尤其是需要方言或口音支持的中文场景。
- 私有化语音识别服务，替换云端 ASR 或 Whisper 本地部署。
- 实时字幕、直播字幕、客服流式音频识别。
- 语音智能体（如 OpenClaw、Pipecat、Dify、RAGFlow 等）的本地 STT 后端。
- 在 CPU 上运行的低成本批量转写任务（官方基准显示 SenseVoiceSmall CPU 可达 17x 实时）。
- 需要情感识别、音频事件检测、说话人分离的复合语音分析任务。

**不适用或需谨慎的场景：**

- 纯英文、少量使用且不需要额外功能的场景：Whisper 可能足够，FunASR 的额外流水线价值有限。
- 需要 57 语言全覆盖的统一模型：FunASR 的语言覆盖是 checkpoint 特异的，需按模型查看支持语种（如 Fun-ASR-MLT-Nano 31 语言、Qwen3-ASR 52 语言）。
- Ascend NPU 生产部署：Fun-ASR-Nano 在昇腾 NPU（torch_npu）上仅有社区兼容性证据，且明显慢于 CPU，官方尚未将其列为生产运行时。
- 需要 8kHz G.711 mu-law 直接识别的电话音频：部分集成（如 OpenClaw）需要先进行格式转换。
- 热词需求需先明确是"识别后纠错"还是"解码阶段偏置"，不同运行时支持程度不同（如 ONNX/C++ 链路建议用确定性后处理）。

## 技术架构与依赖

- 核心语言：Python（Python ≥ 3.8，支持 <=3.13）。
- 深度学习框架：PyTorch + torchaudio（PyTorch >= 1.11）。安装时需先安装与 NVIDIA 驱动匹配的 PyTorch CUDA 版本，再用 `pip install funasr`。
- 模型 Hub：支持 ModelScope（默认）与 Hugging Face（`--hub hf`）双来源加载。
- 核心 API：`from funasr import AutoModel`，一个调用即可编排 ASR/VAD/标点/说话人模型的组合流水线；`AutoModelVLLM` 用于 vLLM 批量加速。
- 服务组件：vLLM（LLM 解码加速）、FastAPI + uvicorn + python-multipart（OpenAI 兼容 API）、WebSocket（流式服务）。
- 边缘运行时：llama.cpp/GGUF 预编译二进制，支持 Linux/macOS/Windows 的 CPU、AVX2、Vulkan、CUDA 后端。
- 开源许可证：工具包源码为 MIT；预训练模型权重按各模型卡单独许可，部分引用 FunASR Model Open Source License Agreement。

## 安装与快速开始

```bash
# CPU 环境
pip install torch torchaudio
pip install funasr

# GPU 环境：先按 https://pytorch.org/get-started/locally/ 安装匹配 CUDA 的 PyTorch/torchaudio，再安装 funasr
# 验证 GPU 是否可用
python - <<'PY'
import torch
print(torch.cuda.is_available())
PY
```

快速开始（旗舰模型 Fun-ASR-Nano，需 GPU）：

```python
from funasr import AutoModel

model = AutoModel(model="FunAudioLLM/Fun-ASR-Nano-2512", device="cuda")
result = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav")
print(result[0]["text"])
```

CPU 上可使用 SenseVoiceSmall 组合 VAD 与说话人分离：

```python
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="your_audio.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'])}")
```

命令行快速使用：

```bash
funasr audio.wav                 # 基础转写
funasr audio.wav -f json         # JSON 输出
funasr audio.wav -f srt -o ./subs   # SRT 字幕
funasr meeting.wav --spk --timestamps -f json   # 说话人 + 时间戳
```

## 典型使用方法

**中文生产流水线（VAD + ASR + 标点 + 说话人）**

```python
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="audio.wav", hotword="关键词 20")
```

**流式逐块识别**

```python
import soundfile as sf
model = AutoModel(model="paraformer-zh-streaming", device="cuda")
audio, sr = sf.read("speech.wav", dtype="float32")
chunk_size = [0, 10, 5]
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)
```

**vLLM 批量加速**

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

**启动 OpenAI 兼容 API 服务**

```bash
pip install funasr vllm fastapi uvicorn python-multipart
funasr-server --device cuda
# 端点：POST http://localhost:8000/v1/audio/transcriptions
```

**情感识别**

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

**边缘端 GGUF 运行**（以 Linux/macOS 为例）

```bash
bash download-funasr-model.sh sensevoice ./gguf
./llama-funasr-sensevoice -m ./gguf/sensevoice-small-q8.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav
```

## 配置与部署要点

- 模型选择：官方提供模型选择指南（docs/model_selection.md），首次使用时建议参照；注意语言覆盖是 checkpoint 特异的，Fun-ASR-Nano 与 Fun-ASR-MLT-Nano 是不同的模型选择。
- 部署路径选择：推荐从最小方案开始。浏览器快速体验用 Colab；本地离线任务用 Python API；需要替换云端服务优先用 OpenAI 兼容 API；已有 Xinference 则用其内置音频模型规格；Kubernetes 用户可直接套用官方模板（默认 ClusterIP）。
- 流式服务部署：使用 WebSocket 运行时，上线前应验证 chunk size、VAD、断句、标点、说话人分离、重连行为和客户端背压。
- vLLM 加速注意：适用于 LLM 解码（Fun-ASR-Nano），不适用于非自回归 Paraformer；需关注 GPU 显存、tensor parallel size、warmup 时间，并使用自有音频分布做 benchmark。
- GGUF/llama.cpp：Windows CUDA 包当前面向 CUDA architecture 86；RTX 50/Blackwell（sm_120）应使用 CPU 包或自行编译并指定 `-DCMAKE_CUDA_ARCHITECTURES=120`。Windows Vulkan 包依赖系统 GPU 驱动提供的 Vulkan loader。
- API 安全：将 API 暴露到可信网络之外前，应增加上传大小限制、鉴权、TLS 与限流，并参考官方安全与网关指南。
- 热词：明确热词是确定性后处理还是解码阶段偏置；固定专有名词可用 `POSTPROCESS_HOTWORDS:wrong=>right` 与模型级 `HOTWORDS:` 分开处理。
- Docker：官方提供 CPU/GPU 镜像与 docker-compose 示例；容器内使用 CUDA 前需要 CUDA-capable 镜像并设置 `FUNASR_DEVICE=cuda`。
- 环境验证：GPU 环境务必先确认 `torch.cuda.is_available()` 为 True 再使用 `device="cuda"`，否则需重新安装匹配 CUDA 的 PyTorch。
- 流式长会话：排查 WebSocket 长会话问题时可用 `--enable-spk --log-session-stats-interval 30` 输出 Session stats。

## 限制、风险与许可证

**限制与风险：**

- 基准数据说明：官方性能数字（如 Fun-ASR-Nano + vLLM 340x 实时、SenseVoiceSmall CPU 17x 实时）来自特定长音频测试集与硬件（NVIDIA H100/A100 等），不构成所有 GPU、batch、语料形态的保证；流式延迟与离线 RTFx 不能混用。
- Ascend NPU 上 Fun-ASR-Nano 并非官方生产运行时；社区测试显示其显著慢于 CPU，且 vLLM-Ascend 路径仍存在算子兼容问题。
- Windows CUDA 包对新一代 NVIDIA GPU（RTX 50/Blackwell）暂不适用，需等待专用 CUDA 资产或自行编译。
- 模型许可证独立于工具包：FunASR 源码为 MIT；各预训练模型权重按模型卡单独授权，使用前需逐一确认。
- 仓库资料显示项目仍在高频迭代，文档中部分内容（如社区增长计划、第三方 PR 状态）属于运营材料而非产品承诺。

**许可证：**

- FunASR 工具包源码：MIT License。
- 预训练模型权重：另行授权，以各模型卡为准；引用 FunASR Model Open Source License Agreement 的按该协议执行。

## 官方链接

- 仓库主页：https://github.com/modelscope/FunASR
- 在线文档：https://modelscope.github.io/FunASR/
- 部署中心：https://www.funasr.com/
- PyPI：https://pypi.org/project/funasr/
- Hugging Face 组织：https://huggingface.co/funasr
- 论文：FunASR: A Fundamental End-to-End Speech Recognition Toolkit（INTERSPEECH 2023）

## 信息来源和分析时间

本说明基于以下资料整理：

- 仓库 README（含 Quick Start、Model Zoo、Usage、Deploy、Benchmark、What's new、License 等节）
- 仓库内置文档：部署选型表（docs/deployment_matrix*.md）、CLI 说明（docs/cli.md）、安装文档（docs/installation/installation.md）、贡献指南（CONTRIBUTING.md）、社区集成列表（docs/community_projects*.md）、社区增长计划（docs/community_growth_20k.md）等
- 仓库最新 Release：v1.4.1（发布于 2026-08-04）

分析时间：2026-08-05。

注：仓库资料中出现的部分日期、版本号与第三方集成状态以仓库原文为准；未在仓库资料中提供的信息（如特定训练超参数、完整 API 参数表等）已在本文中省略，未作臆测补充。