FunASR/README_zh.md

(English|简体中文|日本語|한국어)

面向离线、流式与边缘部署的工业级语音识别工具箱。
ASR · VAD · 标点 · 说话人 pipeline · 情感与音频事件模型 · OpenAI 兼容服务

快速开始 · 模型选择 · 模型列表 · 部署选型 · 部署中心 · 文档中心 · 性能评测 · 贡献

---

快速开始

不想先配置本地环境？可以打开 Colab 快速体验 在浏览器里转写公开样例或上传自己的音频。

FunASR 对你有帮助？欢迎 Star 项目，让更多开发者找到它。

pip install torch torchaudio
pip install funasr

如果要运行 GPU quickstart，请先按 pytorch.org 选择与你的 NVIDIA driver 匹配的 PyTorch / torchaudio CUDA wheel，再安装 FunASR。 安装后先确认 GPU 可见：

python - <<'PY'
import torch
print(torch.cuda.is_available())
PY

只有这里输出 True 时才使用 device="cuda"；否则请先使用 device="cpu"，或重新安装匹配 CUDA 的 PyTorch wheel。

以下 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'])}")

代码打印实际返回的 VAD 分段起点（秒）、匿名说话人编号和去除 SenseVoice 标签后的文本。文本与分段边界取决于音频和 checkpoint，这里不预设转写结果。

CAM++ 提取 spk_embedding 说话人嵌入，AutoModel 再聚类并为 VAD 分段分配 说话人编号；编号仅在当前录音内有效，不是已知人物身份，也不是 SenseVoiceSmall checkpoint 的内置输出。组件和返回字段见 SDK 契约。 需要 GPU 时，先按上文验证环境，再将 device 改为 "cuda"。 SenseVoice 论文见 arXiv:2407.04051， 模型见 Hugging Face checkpoint， 边缘部署可用 GGUF checkpoint。

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 checkpoint。Nano 与 MLT-Nano 的语言范围不同，使用时请按 checkpoint 选择。

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

部署为 API 服务： funasr-server --device cuda → 本地 OpenAI 兼容接口 localhost:8000

接入 AI Agent： MCP 服务 支持 Claude/Cursor · OpenAI API 支持 LangChain/Dify/AutoGen

接入语音 Agent： OpenClaw 实时转写插件 支持私有部署的 Talk 与 Voice Call 转写

为什么选 FunASR？

FunASR 是工具箱，需要分别选择任务、checkpoint 和运行时。 一个模型或适配器支持的能力，不代表所有服务后端都支持。

任务	Checkpoint 或 pipeline	运行时入口	主要边界
文件转写及情感/事件标签	SenseVoiceSmall	Python AutoModel，CPU 或 GPU	五语种 checkpoint；标签不代表说话人身份。
LLM 文件转写	Fun-ASR-Nano	AutoModel；文档指定的 GPU 拆分引擎 AutoModelVLLM	基础 Nano 覆盖中/英/日及中文方言/口音；时间戳取决于 checkpoint 和路径。
更多语种的文件转写	Fun-ASR-MLT-Nano	Python AutoModel	独立的 31 语种 checkpoint，不能把其覆盖范围归给基础 Nano。
分块实时转写	Paraformer-zh-streaming	流式 SDK 或 runtime WebSocket 服务	使用流式 checkpoint 和会话独立 cache，不能替换为离线 checkpoint。
带说话人的文件转写	SenseVoiceSmall + FSMN-VAD + CAM++	AutoModel 的 VAD 与嵌入聚类	编号仅在当前录音内有效，不是已注册人物身份识别。
联合文本、时间戳与说话人	第三方 OpenMOSS 的 MOSS-Transcribe-Diarize	MOSS 指南中的 FunASR adapter 或上游后端	离线、录音内匿名标签；统一路径不外接 VAD/说话人 pipeline。
原生 CPU/端侧转写	Fun-ASR-Nano 或 SenseVoiceSmall GGUF	llama.cpp runtime	需要匹配的转换权重，GGUF 不能作为 Python AutoModel checkpoint 加载。

Checkpoint、接口与协议边界见 Model Zoo 和 部署矩阵。请用目标音频与硬件评测后再选运行时。

第一次试用 FunASR？可以先跑 Colab 快速体验，再配置本地环境。还不确定先用哪个模型？先看 模型选择指南。计划从 Whisper 或云端 ASR 切换？请按 迁移指南 和 评测示例 用代表性音频评测、映射功能并安全上线。

---

性能评测

历史评测报告 与 拆分引擎测量 保留原始结果。 两者是独立记录，不能合并成通用速度排名或生产容量承诺。

请按 RTFx 与可复现评测说明 对齐 checkpoint/revision、音频集、硬件、批量大小、预热、计时范围与 CER/WER。 离线吞吐量不等于流式延迟；可使用 迁移评测示例 以相同口径测量自己的录音。

---

最新动态

• MOSS-Transcribe-Diarize 已接入 FunASR 服务、Docker、Kubernetes、vLLM/SGLang 工作流和 FunClip，一次完成长音频转写、时间戳与匿名说话人标注。部署 MOSS ->
• FunASR 1.4.14 补齐 MOSS 服务与 Model Zoo 入口，提升实时服务稳定性，并保留 NumPy ABI 兼容保护。升级命令：python -m pip install -U "funasr==1.4.14"。发布页 ->
• 工业部署 新增更快、更稳定的实时服务，以及覆盖 Linux、macOS、Windows 十种目标的 llama.cpp 预编译包。GPU 服务 -> · CPU/端侧包 ->

完整改动记录和可下载资产请查看 GitHub Releases。

---

安装

pip install funasr

从源码安装

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

环境要求：Python ≥ 3.8、PyTorch ≥ 1.13、torchaudio

---

模型列表

列表包含第三方模型。MOSS-Transcribe-Diarize 由 OpenMOSS 发布，FunASR 提供适配器，并不拥有其权重。统一路径为离线处理，匿名说话人标签仅在当前录音 内有效，不是实时流式或已知人物身份识别。模型协议与工具箱 MIT 协议分别适用。

模型	任务	语言	参数量	链接
Fun-ASR-Nano	识别	中/英/日 + 中文方言	800M	⭐ 🤗 GGUF
Fun-ASR-MLT-Nano	识别	31 种语言	800M	⭐ 🤗
SenseVoiceSmall	识别 + 情感 + 事件	中/英/日/韩/粤	234M	⭐ 🤗 GGUF 论文
MOSS-Transcribe-Diarize	第三方 OpenMOSS：离线识别 + 时间戳 + 匿名说话人	以官方模型卡为准	以官方模型卡为准	🤗 指南
Paraformer-zh	识别 + 时间戳	中/英	220M	⭐ 🤗
Paraformer-zh-streaming	流式识别	中/英	220M	⭐ 🤗
Qwen3-ASR	识别，52 种语言	多语言	1.7B	使用
GLM-ASR-Nano	识别，17 种语言	多语言	1.5B	使用
Whisper-large-v3	识别 + 翻译	多语言	1550M	使用
Whisper-large-v3-turbo	识别 + 翻译	多语言	809M	使用
ct-punc	标点恢复	中/英	290M	⭐ 🤗
fsmn-vad	语音检测	中/英	0.4M	⭐ 🤗
cam++	说话人嵌入（speaker embeddings，pipeline 组件）	—	7.2M	⭐ 🤗
emotion2vec+large	情感识别	—	300M	⭐ 🤗

---

使用示例

Python 教程 · SDK 参数与输出 · 训练与微调 · 模型注册

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

# 中/英/日 + 中文方言
model = AutoModel(model="FunAudioLLM/Fun-ASR-Nano-2512", hub="hf", trust_remote_code=True,
                  vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000}, device="cuda")
result = model.generate(input="audio.wav", batch_size=1)

# 流式实时识别(逐块喂音频)
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)

# 情感识别
model = AutoModel(model="emotion2vec_plus_large", device="cuda")
result = model.generate(input="audio.wav", granularity="utterance")

命令行工具（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

---

部署

# OpenAI 兼容 API（推荐）
pip install funasr fastapi uvicorn python-multipart
funasr-server --model sensevoice --device cuda
# → POST /v1/audio/transcriptions，地址 localhost:8000
# 离线长音频联合转写 + 匿名说话人标签：
funasr-server --model moss-transcribe-diarize --device cuda:0

MOSS 服务、Docker、Kubernetes、vLLM、SGLang、LocalAI 与 FunClip 部署指南 →

使用公开样例音频验证服务：

curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@sample.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

# Docker 流式服务
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12

CPU / 边缘部署 - llama.cpp / GGUF（无需 GPU、无需 Python）

在 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 包，并安装 AMD、Intel 或 NVIDIA 的当前 Vulkan 显卡驱动：
.\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav --backend vulkan
# RTX 30 系列等架构 86 GPU 可使用 windows-x64-cuda 包：
.\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav --backend cuda

Linux GPU 用户可下载 funasr-llamacpp-linux-x64-vulkan.tar.gz，在已安装可用 Vulkan driver/ICD 的机器上运行：

./llama-funasr-sensevoice -m ./gguf/sensevoice-small-q8.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav --backend vulkan

Windows Vulkan ZIP 使用显卡驱动提供的系统 Vulkan loader，不需要另外安装 Vulkan SDK；当前与 Linux Vulkan 包一样，仅加速 SenseVoiceSmall。

带 tag 的发布提供两个 Windows CUDA 包：标准 windows-x64-cuda ZIP 面向 CUDA architecture 86，windows-x64-cuda-blackwell 面向 RTX 50 / Blackwell 的 architecture 120（sm_120）。两个 ZIP 都包含所需的 cuBLAS DLL，并使用静态 MSVC runtime；用户只需 安装兼容的 NVIDIA 驱动，无需另装 CUDA Toolkit。CI 验证架构与打包边界，但不代表已经在 Blackwell 实机上完成推理验证。

预编译二进制： Releases · v0.2.6 · Linux Vulkan tarball · Windows Vulkan zip · Windows CUDA zip · Windows Blackwell CUDA zip · 下载与快速开始： funasr.com/deploy/llama-cpp · GGUF 模型： Hugging Face · 文档与评测： runtime/llama.cpp/

OpenAI API 示例 → · Gradio Demo → · 客户端配方 → · JavaScript/TypeScript 配方 → · Kubernetes 模板 → · 工作流配方 → · Postman 集合 → · OpenAPI 规范 → · 安全指南 → · 部署选型 → · 部署文档 → · Agent 集成 →

---

社区

反馈问题前先查阅故障排查，并附上确切模型、运行时、环境与最小复现。

📖 文档	🐛 问题反馈
💬 讨论	🤗 HuggingFace
🤝 贡献指南	📈 20k 增长计划
🗺️ 仓库职责与路线图	🌐 funasr.com
🧩 社区集成	💡 使用案例

Star 趋势

许可证

• 本仓库的 FunASR 工具箱源码：MIT License。
• 预训练模型权重单独授权，请以各模型卡标注的协议为准；模型卡若链接本仓库的 FunASR 模型开源协议，则适用该协议。

引用

@inproceedings{gao2023funasr,
  author={Zhifu Gao and others},
  title={FunASR: A Fundamental End-to-End Speech Recognition Toolkit},
  booktitle={INTERSPEECH},
  year={2023}
}