使用教程

从零开始，10 分钟掌握 FunASR 的完整使用方法。

30 秒快速体验

复制以下代码直接运行即可。无需任何配置，FunASR 会自动下载所需的模型：

pip install funasr

python -c "
from funasr import AutoModel
model = AutoModel(model='paraformer-zh', vad_model='fsmn-vad', punc_model='ct-punc')
res = model.generate(input='https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav')
print(res[0]['text'])
"

输出结果：

就是这么简单。一个模型对象搞定所有事情：音频加载、语音分段、语音识别和标点添加。

安装

# 稳定版
pip install funasr

# 最新版（推荐——包含最新模型和 bug 修复）
pip install git+https://github.com/modelscope/FunASR.git

我应该用哪个模型？

模型	适用场景	支持语言	速度	标点
Paraformer	中文生产级识别	中文、英文	快	需要 punc_model
Fun-ASR-Nano	多语言、方言、歌词	31 种语言	中等	内置 ✓
SenseVoice	情感 + 音频事件 + 识别	5 种语言	极快（10s 音频仅需 70ms）	内置 ✓
Qwen3-ASR	最高精度，上下文理解	52 种语言	较慢（大模型）	内置 ✓
Paraformer-Streaming	实时转写	中文	实时	需要 punc_model

应用场景

离线语音识别

Paraformer（中文）

from funasr import AutoModel

model = AutoModel(
    model="paraformer-zh",          # 中文 ASR
    vad_model="fsmn-vad",           # 支持任意长度音频
    vad_kwargs={"max_single_segment_time": 60000},
    punc_model="ct-punc",           # 添加标点
)
res = model.generate(input="meeting.wav", batch_size_s=300, hotword='达摩院 语音识别')
print(res[0]["text"])       # "欢迎大家来体验达摩院推出的语音识别模型。"
print(res[0]["timestamp"])  # [[880,1120],[1120,1360],...] (每个字的毫秒时间戳)

Fun-ASR-Nano（31 种语言）

from funasr import AutoModel

model = AutoModel(
    model="FunAudioLLM/Fun-ASR-Nano-2512",
    trust_remote_code=True,
    remote_code="./model.py",
    vad_model="fsmn-vad",
    vad_kwargs={"max_single_segment_time": 30000},
    device="cuda:0",
    hub="hf",
)
res = model.generate(input=["audio.wav"], cache={}, batch_size=1,
                     hotwords=["keyword"], language="中文")
print(res[0]["text"])        # 带标点的识别文本
print(res[0]["timestamps"])  # [{"token":"开","start_time":0.42,"end_time":0.48}, ...]

SenseVoice（识别 + 情感 + 音频事件）

from funasr import AutoModel
from funasr.utils.postprocess_utils import rich_transcription_postprocess

model = AutoModel(
    model="iic/SenseVoiceSmall",
    vad_model="fsmn-vad",
    vad_kwargs={"max_single_segment_time": 30000},
    device="cuda:0",
)
res = model.generate(input="audio.wav", cache={}, language="auto",
                     use_itn=True, batch_size_s=60, merge_vad=True, merge_length_s=15)

# 原始输出包含情感/事件标签：<|zh|><|HAPPY|><|Speech|>你好
text = rich_transcription_postprocess(res[0]["text"])
print(text)  # "你好"（干净文本）

Qwen3-ASR（52 种语言，最高精度）

# pip install qwen-asr
from funasr import AutoModel

model = AutoModel(model="Qwen/Qwen3-ASR-1.7B", hub="hf", device="cuda:0")
res = model.generate(input="audio.wav")
print(res[0]["text"])             # 识别文本
print(res[0].get("language"))    # 自动检测到的语言

流式语音识别（实时）

逐块处理音频实现实时转写。每送入一小段音频，立即返回识别出的部分文字。

from funasr import AutoModel
import soundfile

model = AutoModel(model="paraformer-zh-streaming")

speech, sr = soundfile.read("audio.wav")
chunk_size = [0, 10, 5]          # 600ms 显示，300ms 前瞻
chunk_stride = chunk_size[1] * 960  # 每块 9600 个采样点

cache = {}
total_chunks = int((len(speech) - 1) / chunk_stride + 1)
for i in range(total_chunks):
    chunk = speech[i * chunk_stride:(i + 1) * chunk_stride]
    is_final = (i == total_chunks - 1)

    res = model.generate(input=chunk, cache=cache, is_final=is_final,
                         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)  # 增量输出

输出（逐步打印）：

说话人分离（"谁说了什么"）

支持三个主要模型：Paraformer、Fun-ASR-Nano 和 SenseVoice。添加 spk_model="cam++" 即可为每句话标注说话人。

Paraformer + 说话人分离

from funasr import AutoModel

model = AutoModel(
    model="paraformer-zh",
    vad_model="fsmn-vad",
    punc_model="ct-punc",      # Paraformer 需要标点模型来做句子切分
    spk_model="cam++",
)
res = model.generate(input="meeting.wav", batch_size_s=300)

for sent in res[0]["sentence_info"]:
    print(f"[说话人 {sent['spk']}] [{sent['start']}-{sent['end']}ms] {sent['text']}")

输出：

Fun-ASR-Nano + 说话人分离（无需标点模型）

model = AutoModel(
    model="FunAudioLLM/Fun-ASR-Nano-2512",
    trust_remote_code=True, remote_code="./model.py",
    vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000},
    spk_model="cam++",     # 不需要 punc_model！
    device="cuda:0", hub="hf",
)
res = model.generate(input=["meeting.wav"], cache={}, batch_size=1, language="中文")
for sent in res[0]["sentence_info"]:
    print(f"说话人 {sent['spk']}: {sent.get('text', sent.get('sentence', ''))}")

SenseVoice + 说话人分离（无需标点模型）

model = AutoModel(
    model="iic/SenseVoiceSmall",
    vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000},
    spk_model="cam++",    # 不需要 punc_model！
    device="cuda:0",
)
res = model.generate(input="meeting.wav", cache={}, language="auto",
                     use_itn=True, batch_size_s=60, merge_vad=True, merge_length_s=15)
for sent in res[0]["sentence_info"]:
    print(f"说话人 {sent['spk']}: {rich_transcription_postprocess(sent['text'])}")

情感检测

专用情感模型（emotion2vec）

from funasr import AutoModel

model = AutoModel(model="iic/emotion2vec_plus_large", device="cuda:0")
res = model.generate(input="audio.wav", granularity="utterance")

print(res[0]["labels"])  # ['angry', 'happy', 'neutral', 'sad', ...]
print(res[0]["scores"])  # [0.01,   0.03,   0.89,      0.05, ...]
# → 该音频为"中性"情感，置信度 89%

SenseVoice（一次推理同时完成识别和情感检测）

SenseVoice 会在识别结果中直接嵌入情感标签：

# 原始输出："<|zh|><|HAPPY|><|Speech|><|withitn|>今天真是太开心了。"
# <|HAPPY|> 标签表示该段语音的情感
# 使用 rich_transcription_postprocess() 获取干净文本

语音活动检测（VAD）

离线模式（完整音频）

from funasr import AutoModel

model = AutoModel(model="fsmn-vad")
res = model.generate(input="audio.wav")
print(res[0]["value"])  # [[610, 5530], [7200, 12400], ...]
                         # 每对数字：[起始ms, 结束ms] 表示有声段

流式模式（逐块处理）

import soundfile
from funasr import AutoModel

model = AutoModel(model="fsmn-vad")
speech, sr = soundfile.read("audio.wav")
chunk_stride = int(200 * sr / 1000)  # 200ms 每块

cache = {}
for i in range(int((len(speech)-1)/chunk_stride+1)):
    chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
    is_final = i == int((len(speech)-1)/chunk_stride)
    res = model.generate(input=chunk, cache=cache, is_final=is_final, chunk_size=200)
    if res[0]["value"]:
        print(res[0]["value"])
        # [[610, -1]]   → 语音在 610ms 处开始
        # [[-1, 5530]]  → 语音在 5530ms 处结束
        # [[610, 5530]] → 完整的有声段

标点恢复

from funasr import AutoModel

model = AutoModel(model="ct-punc")
res = model.generate(input="那今天的会就到这里吧 happy new year 明年见")
print(res[0]["text"])  # "那今天的会就到这里吧，happy new year，明年见。"

ONNX 模型导出

# 将模型导出为 ONNX 格式
from funasr import AutoModel
model = AutoModel(model="paraformer", device="cpu")
model.export(quantize=False)   # 保存到模型缓存目录

# 使用 ONNX 模型（更快，无需 PyTorch）
# pip install funasr-onnx
from funasr_onnx import Paraformer
model = Paraformer("damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch",
                   batch_size=1, quantize=True)
result = model(["audio.wav"])
print(result)

常见问题与故障排除

模型下载慢

设置 hub="hf" 切换到 HuggingFace（海外更快），或者下载一次后使用本地路径：

model = AutoModel(model="/path/to/local/model", disable_update=True)

显存/内存溢出（OOM）

三个降低内存占用的方法：

1. 减小 batch_size_s（例如从 300 减到 60）
2. 减小 vad_kwargs 中的 max_single_segment_time（例如 30000 → 15000）
3. 添加 batch_size_threshold_s=30 强制对长段使用 batch=1

每次启动都显示 "Downloading Model..."

并非真的在重新下载，只是在校验本地缓存。要完全跳过：

model = AutoModel(model="/local/path/to/model", disable_update=True)

报错 "ModelName is not registered"

通常是因为 pip 安装的版本太旧。请从源码安装最新版：

pip install git+https://github.com/modelscope/FunASR.git

想关闭所有进度条和日志？

model = AutoModel(model="...", disable_update=True, disable_pbar=True, log_level="ERROR")

如何传入已加载的 numpy 音频数据？

import soundfile as sf
audio, sr = sf.read("audio.wav")  # numpy 数组，16kHz
res = model.generate(input=audio)  # 直接传入——不需要文件

GPU 没有被使用？

# 检查：
import torch
print(torch.cuda.is_available())  # 必须为 True

# 显式指定 GPU：
model = AutoModel(model="...", device="cuda:0")