FunASR 语音识别快速上手从零到第一次成功转写的完整指南【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR你有没有过这样的经历手头一堆录音文件想变成文字却卡在环境怎么配、模型下哪里、代码怎么写这三道坎上FunASR就是为这一类需求准备的开源语音识别工具箱——它把离线转写、实时流式识别、语音端点检测、标点恢复、说话人分离打包在一起你用一行 pip 命令装好再用几行 Python 就能拿到带标点的识别文本。读完这篇文章你会拿到一个能跑通本地语音识别的最小环境一条安装命令、一段验证脚本、一次真实场景的转写实践。先说清楚一个概念FunASR 不是一个模型而是一组模型加一套流水线。比如你要做会议录音转写它就自动帮你串起三段流程——先用 VAD语音端点检测负责找出哪里有人说话切出语音片段再交给识别模型转成文字最后补上标点。你只管调用分工它来完成。✅ 开工前自检5 分钟过一遍清单安装本身不复杂但提前把环境对齐能省掉后面 80% 的折腾。打开终端对照下面的清单逐项确认检查项达标标准确认动作操作系统Windows / macOS / Linux 均可三者都被官方支持无需额外准备Python 版本3.8 ~ 3.13执行python --version查看pip 可用能正常安装第三方包执行pip --version查看内存建议 8GB 及以上4GB 也能跑但只适合短音频磁盘空间预留 2GB 以上模型会下载到本地缓存NVIDIA 显卡可选有独立显卡才需要有卡会快很多没有就全程用 CPU一样能跑通只有最后一项是锦上添花。官方数据显示SenseVoice 模型在纯 CPU 上就能做到17 倍实时转写 1 分钟音频约需 3.5 秒所以对普通用户来说一台普通电脑完全够用。建议的做法用虚拟环境隔离本次安装避免污染系统里已有的 Python 包。# 1) 准备环境二选一虚拟环境或已装好 conda 时新建环境 python -m venv funasr-env # 2) 安装依赖先装 PyTorch 音频框架再装 FunASR pip install torch torchaudio pip install funasr顺序不能颠倒PyTorch 是 FunASR 的计算底座先装它后面的依赖检查才会顺畅。国内网络如果下载慢可以在 pip 后加-i https://mirror.sjtu.edu.cn/pypi/web/simple走镜像源。 跑通验证看到第一段文字就算成功装完别急着写业务代码。先做一个冒烟测试——用官方样例音频跑一次转写确认从下载模型到输出文字这条链路全部畅通from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess # 首次运行会自动下载 SenseVoiceSmall 模型约几百 MB耐心等一次即可 model AutoModel(modeliic/SenseVoiceSmall, vad_modelfsmn-vad, devicecpu) result model.generate(inputhttps://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav) for seg in result[0][sentence_info]: print(f[{seg[start]/1000:.1f}s] {rich_transcription_postprocess(seg[sentence])})执行后你会看到类似这样的输出[0.6s] 欢迎大家来体验达摩院推出的语音识别模型看到带时间戳的中文句子恭喜你的 FunASR 已经跑通了。这一小段代码其实组合了三个组件SenseVoiceSmall负责识别fsmn-vad负责切分语音片段sentence_info则是带时间戳的分句结果。你不需要理解每个参数只要记住这个调用骨架后面换模型只改model里的名字就行。️ 第一次正式使用转写你自己的录音验证通过后把示例音频换成你自己的文件FunASR 就正式进入工作状态。这里给一个最小可用的真实场景一段会议录音转成带标点的文字。如果你更喜欢在终端里干活FunASR 装好后自带一个funasr命令行工具对脚本和自动化特别友好# 批量转写当前目录所有 wav输出结构化 JSON 到 output 文件夹 funasr *.wav -f json -o ./output几个高频选项按需加在后面--language zh明确指定中文跳过自动检测--spk开启说话人分离区分谁在说--timestamps输出到字级时间戳方便做字幕对齐-f srt -o ./subs直接生成 SRT 字幕文件做视频字幕一步到位音频文件本身没有苛刻要求常见格式wav、mp3、m4a 等都可以直接传入支持传本地路径也支持传一个 URL 让 FunASR 自己拉取。⚙️ 参数与性能分档按你的配置选打法不用追求最快按硬件档位选合适模型体验就很好。官方 benchmark 里的几个数字供你参考你的配置推荐模型参考速度说明纯 CPU / 核显SenseVoiceSmall17 倍实时本文默认路线省心8GB 内存SenseVoiceSmall单任务顺序跑—别同时开多个转写任务16GB 内存SenseVoiceSmall可批量处理—长音频建议先切段再转写NVIDIA GPUFun-ASR-Nano vLLM340 倍实时追求极致吞吐时再上支持中/英/日及多种中文方言三条通用建议没有 GPU 就把devicecpu写死省得每次自动检测打转长音频先切分几百分钟的录音直接喂进去容易超时切成 10 分钟以内的段更稳妥批量任务控制并发一次跑 2~4 个任务为宜开太多反而互相抢资源。 排错地图按现象对号入座第一次用卡住很正常。别慌对照下面现象 → 定位动作逐项排查基本能覆盖新手期遇到的所有问题你看到的现象先做这一个动作import funasr 报错确认是先装了torch/torchaudio再装的 funasr两者版本要配套。仍报错就新建一个干净的虚拟环境重跑模型下载慢或中断国内网络优先用 ModelScope 源中断后清掉该模型的半截缓存再重试无需重装有显卡但提示 CUDA 不可用执行python -c import torch; print(torch.cuda.is_available())若为False说明 PyTorch 与驱动不匹配按 pytorch.org 重装对应版本急用时先改devicecpu不阻塞进度结果为空或漏识别先换一段已知能听清的短 WAV 测试采样率、编码不匹配常被误判为识别坏了转写速度比预期慢看是否误把大批文件并行喂给了 CPU 机器降并发、切短音频想接成 API 服务但请求失败先用一个短 WAV 对/v1/audio/transcriptions做冒烟测试再排查浏览器跨域需要逐个传入--cors-origin如果对照后仍有问题把操作系统、Python 版本、pip list中 torch/torchaudio/funasr 的版本、完整报错整理好去项目 Issues 里提Deployment Help类问题响应会快很多。完整的故障场景可以在 docs/troubleshooting_zh.md 查到。 进阶玩法三个最常用的自定义开关跑通之后这三个能力是社区使用频率最高的自定义点热词定制识别专有名词、产品名、人名时容易跑偏给命令加--hotwords 关键词A,关键词B即可注入软提示不用重新训练模型。换模型不换框架AutoModel(model...)里填的模型 id 决定了整套行为——想要低延迟流式识别就换paraformer想要 31 语种多语言就换 MLT 系列框架代码一行不动。怎么选看 docs/model_selection_zh.md 的对照表。服务化输出funasr-server一条命令把转写能力变成 OpenAI 兼容接口LangChain、Dify 这类框架可以直接对接需要接入 AI Agent 的话examples/openai_api/README_zh.md 和 examples/mcp_server/ 有完整示例。 收尾与下一步到这里你已经走完了一条完整链路自检 → 安装 → 跑通验证 → 真实转写。接下来可以按兴趣选方向继续不确定该用哪个模型→ 读 docs/model_selection_zh.md按场景对号入座从 Whisper 或云端 API 迁过来→ 参考 docs/migration_from_whisper_zh.md里面有评测脚本和迁移检查单想做字幕、会议转写这类具体场景→ 浏览 docs/use_case_showcase_zh.md 的社区实践遇到新问题→ docs/troubleshooting_zh.md 或项目 Issues 区提问时带上版本和完整日志。FunASR 把语音变文字这条路上最琐碎的环节都预装好了你要做的只是按下回车然后听它把声音变成文字。转写你的第一段录音吧。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考