5分钟上手FunASR：语音识别极速入门教程
项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR 你还在为语音识别工具复杂的配置流程烦恼吗？5分钟，从安装到实现实时语音转文字，一文解决所有入门障碍！
读完本文，你将获得：
- 3种环境安装方案（Conda/pip/源码）的极速配置指南
- 4行Python代码实现语音识别的极简示例
- 非流式/流式/标点恢复/VAD四大核心功能的快速上手
- 工业级预训练模型的即插即用技巧
- 常见报错的10秒解决方案
目录
1. 环境准备：3种安装方式对比
1.1 系统要求速查表
| 操作系统 | 支持版本 | 推荐Python版本 | 依赖项 |
|---|---|---|---|
| Linux | Ubuntu 18.04+/CentOS 7+ | 3.8-3.10 | PyTorch≥1.11 |
| MacOS | 10.15+ | 3.8-3.10 | Xcode命令行工具 |
| Windows | 10+ | 3.8-3.10 | Visual C++ redistributable |
1.2 安装方式对比（推荐指数★★★★★）
方案A：Conda虚拟环境（推荐新手）
# Linux/Mac
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b
source ~/.bashrc
conda create -n funasr python=3.8 -y
conda activate funasr
pip install -U funasr -i https://mirror.sjtu.edu.cn/pypi/web/simple
方案B：pip直接安装（系统Python环境）
pip3 install -U funasr modelscope -i https://mirror.sjtu.edu.cn/pypi/web/simple
方案C：源码编译（开发者）
git clone https://gitcode.com/GitHub_Trending/fun/FunASR
cd FunASR
pip install -e . -i https://mirror.sjtu.edu.cn/pypi/web/simple
⚠️ 注意：Mac M1/M2用户需额外执行：
pip uninstall cffi pycparser ARCHFLAGS="-arch arm64" pip install cffi pycparser --compile --no-cache-dir
2. 核心功能体验：4个实战案例
2.1 基础语音识别（非流式）
from funasr import AutoModel
# 加载模型（自动下载工业级预训练模型）
model = AutoModel(model="paraformer-zh",
vad_model="fsmn-vad", # 语音活动检测
punc_model="ct-punc") # 标点恢复
# 音频文件识别（支持本地文件或网络URL）
wav_path = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav"
result = model.generate(input=wav_path)
print("识别结果：", result[0]["text"])
输出示例：
[{"text": "那今天的会就到这里吧，Happy New Year，明年见。"}]
2.2 实时流式识别（麦克风输入）
import sounddevice as sd
import numpy as np
model = AutoModel(model="paraformer-zh-streaming")
chunk_size = [0, 10, 5] # 600ms实时窗口
samplerate = 16000
cache = {}
def callback(indata, frames, time, status):
audio_data = indata.flatten().astype(np.float32)
is_final = False # 持续流式输入时设为False
res = model.generate(input=audio_data, cache=cache,
is_final=is_final, chunk_size=chunk_size)
if res[0]["text"]:
print(f"实时结果：{res[0]['text']}", end="\r")
# 启动麦克风录音
stream = sd.InputStream(samplerate=samplerate, channels=1, callback=callback)
with stream:
input("按Enter停止录音...\n")
2.3 语音活动检测（VAD）
model = AutoModel(model="fsmn-vad")
wav_path = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav"
result = model.generate(input=wav_path)
print("语音片段时间戳（毫秒）：", result[0]["value"])
# 输出示例：[[100, 1500], [2000, 3800]]
2.4 标点恢复与文本规范化
model = AutoModel(model="ct-punc")
text = "那今天的会就到这里吧 happy new year 明年见"
result = model.generate(input=text)
print("带标点结果：", result[0]["text"])
# 输出："那今天的会就到这里吧。Happy New Year，明年见。"
3. 模型选型指南：工业级SOTA模型推荐
| 模型名称 | 应用场景 | 优势 | 推理速度 | 推荐指数 |
|---|---|---|---|---|
| paraformer-zh | 通用语音识别 | 平衡速度与精度 | 快（CPU实时） | ★★★★★ |
| SenseVoiceSmall | 多语言识别 | 支持中英日韩 | 中 | ★★★★☆ |
| fsmn-vad | 语音端点检测 | 低资源消耗 | 极快 | ★★★★★ |
| ct-punc | 标点恢复 | 工业级准确率 | 快 | ★★★★☆ |
| cam++ | 说话人识别 | 1秒声纹注册 | 中 | ★★★☆☆ |
模型下载命令：
from modelscope import snapshot_download model_dir = snapshot_download("damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch")
4. 常见问题速解：5个坑点规避
4.1 安装问题
- M1/M2芯片报错：按1.2节方案A末尾的额外命令重新安装cffi
- PyTorch版本冲突：
pip install torch==1.11.0+cu113 -f https://download.pytorch.org/whl/torch_stable.html
4.2 模型下载失败
# 手动下载模型到~/.cache/modelscope/hub
git clone https://gitcode.com/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch
4.3 中文乱码问题
确保系统环境变量：export PYTHONUTF8=1
4.4 GPU内存不足
# 降低批量处理大小
model = AutoModel(model="paraformer-zh", batch_size=1)
4.5 长音频处理
# 自动分段处理（需VAD模型）
model = AutoModel(model="paraformer-zh", vad_model="fsmn-vad")
long_audio = "2小时会议录音.wav"
result = model.generate(input=long_audio, batch_size_s=300) # 300秒动态批处理
5. 进阶路线图：从demo到生产环境
总结与展望
通过本文你已掌握： ✅ FunASR的极速安装（3种方案适配不同环境） ✅ 4大核心功能的Python API调用（非流式/流式/VAD/标点） ✅ 工业级模型选型与参数调优技巧 ✅ 5类常见问题的10秒解决方案
下一步行动：
- 点赞收藏本文，关注项目获取最新模型
- 尝试用自己的音频文件运行示例代码
- 参与ModelScope社区贡献模型优化方案
开源项目地址：GitHub_Trending/fun/FunASR
模型许可证：支持商业使用（详见项目MODEL_LICENSE文件）
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
