FunASR Colab 快速上手：零环境配置、浏览器内完成中文语音识别

FunASR Colab 快速上手：零环境配置、浏览器内完成中文语音识别

【免费下载链接】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 仓库中的 Colab 快速体验文档（examples/colab/README_zh.md）及其配套 Notebook（examples/colab/funasr_quickstart.ipynb）展开，介绍如何在无需配置本地 Python 环境的前提下，直接在浏览器中安装 FunASR、自动选择 CPU/GPU、用paraformer-zh+ VAD + 标点模型转写公开样例与自己的音频，并导出 transcript JSON。读完本文，你将掌握一条从零到产出转写结果的完整 Colab 工作流，并理解其背后AutoModel.generate()的调用链与批处理原理。

为什么用 Colab 体验 FunASR

FunASR 是面向训练、推理、流式 ASR、VAD、标点、说话人分离等场景的开源语音识别工具包。对第一次接触它的人来说，最大的门槛往往不在模型本身，而在于本地依赖（Python 版本、PyTorch、音频解码库、模型下载缓存）的装配。Colab 方案把这个门槛移到了云端：

• 无需本地环境：浏览器即开即用，Colab 大多数 runtime 已内置 PyTorch；
• 设备自适应：runtime 有 GPU 时自动使用cuda:0，否则回退 CPU，适合先跑通再上规模；
• 与生产路径一致：Notebook 调用的就是 FunASR 的AutoModel主接口，验证通过后可平滑迁移到 部署选型表 中的服务化方案。

Notebook 源文件位于 examples/colab/funasr_quickstart.ipynb，可通过 Colab 的 "Open In Colab" 入口直接打开运行。另外，README 还提到一个基于Fun-ASR-Nano 原生 Transformers的独立 Notebook：面向正式版 5.17.0、CPU 场景，使用官方样例和自己的录音即可体验，无需安装 FunASR 工具库，与下方基于工具库的 Notebook 属于两个独立环境。

Notebook 覆盖内容一览

从 README_zh.md 和 funasr_quickstart.ipynb 的 cell 结构看，这个快速体验 Notebook 完整覆盖了五个步骤：

1. 在 Colab 中安装 FunASR 和运行依赖；
2. 自动探测 runtime 设备：有 GPU 用cuda:0，否则用 CPU；
3. 使用paraformer-zh、VAD（fsmn-vad）和标点（ct-punc）模型转写公开样例音频；
4. 上传自己的音频文件，用同一套模型完成转写；
5. 保存 transcript JSON，便于分享、对比或提交 issue。

下面按 Notebook 的 cell 顺序逐节展开，并在关键处结合 auto_model.py 的源码说明底层原理。

第一步：安装依赖

Notebook 的第一个 code cell 只有一行：

!pip -q install -U funasr modelscope soundfile

• funasr：核心工具包，提供AutoModel统一推理入口（源码见 funasr/auto/auto_model.py）；
• modelscope：ModelScope 模型仓库的 Python SDK，用于首次运行时自动下载模型文件；
• soundfile：音频读写库，负责将 WAV/FLAC 等格式解码为模型可用的采样序列。

由于 Colab 大部分 runtime 已预装 PyTorch，这里无需显式安装 torch。-q表示静默安装，减少日志刷屏。注意：该 cell 首次执行可能耗时几分钟，因为它会安装 FunASR 并下载若干 Python wheel。

第二步：自动选择 CPU 或 GPU

import json import torch device = "cuda:0" if torch.cuda.is_available() else "cpu" print(f"Using device: {device}")

逻辑非常直白：torch.cuda.is_available()为真则用cuda:0，否则回退cpu。若想在 Colab 中启用 GPU，需在运行前通过菜单Runtime > Change runtime type > GPU切换。device变量会传入后面的AutoModel(...)构造，确保模型权重加载到正确设备。

第三步：用公开样例跑通全流程

from funasr import AutoModel sample_url = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav" model = AutoModel( model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc", device=device, ) result = model.generate(input=sample_url, batch_size_s=60) print(json.dumps(result, ensure_ascii=False, indent=2))

这是整个 Notebook 的核心 cell，一次性组合了三个子模型：

输入sample_url直接传了一个HTTP 音频 URL（公开样例vad_example.wav），AutoModel会自动下载并解码。

底层调用链：generate 的路由逻辑

从 auto_model.py 的源码可以看到，generate()是面向用户的主入口，它会根据是否配置了vad_model自动路由：

• 未配置 VAD：走inference()单段推理；若同时配置了punc_model，还会对每段文本单独跑一次标点推理（见 L735-L748）；
• 配置了 VAD：走inference_with_vad()长音频分段流水线（见 L750-L754）。

本 Notebook 配置了fsmn-vad，因此实际进入inference_with_vad()。该方法在源码注释中给出了清晰的五步流水线（L858-L875）：

1. VAD 分段：用fsmn-vad把输入音频切分为语音区域；
2. ASR 识别：对每个片段执行paraformer-zh识别（片段按长度排序以提升批处理效率）；
3. 时间戳合并：将各片段的时间戳与 VAD 偏移量对齐合并；
4. 标点恢复：对合并后的文本调用ct-punc（配置了 punc_model 时）；
5. 说话人分离：若配置了spk_model，还会对说话人嵌入聚类并打标签（本 Notebook 未启用）。

generate()支持的输入类型相当灵活（见 L703-L708）：本地文件路径、HTTP URL、numpy 数组（float32、16kHz）、文件路径/数组列表、原始 bytes 均可。返回结果为list[dict]，每个样本包含key和text等字段。

关于 batch_size_s 参数

model.generate(input=sample_url, batch_size_s=60)中的batch_size_s是动态批处理的总时长（秒）。在 auto_model.py 中，它被换算为毫秒参与批大小计算：

batch_size = max(int(kwargs.get("batch_size_s", 300)) * 1000, 1)

即默认值为 300 秒，换算为 300000ms 后交给采样器做动态组批——把总时长接近的片段聚合到同一 batch，在吞吐与显存占用之间取得平衡。在 Colab 免费额度下，batch_size_s=60是一个保守且稳妥的选择；显存充裕时可适当调大以提升长音频吞吐。

第四步：上传自己的音频

from google.colab import files uploaded = files.upload() audio_path = next(iter(uploaded)) print(f"Uploaded: {audio_path}") user_result = model.generate(input=audio_path, batch_size_s=60) print(json.dumps(user_result, ensure_ascii=False, indent=2))

• files.upload()是 Colab 专属 API，会在浏览器中弹出文件选择框；
• 推荐上传短.wav、.mp3、.m4a或.flac文件；
• 长录音建议先截取有代表性的片段，或切换到 GPU runtime 后再跑完整文件；
• 关键点：这里复用了第三步创建好的model对象，模型权重只加载一次，上传文件后直接generate即可，无需重复初始化。

第五步：保存并下载 transcript JSON

from pathlib import Path Path("funasr_transcript.json").write_text( json.dumps(user_result, ensure_ascii=False, indent=2), encoding="utf-8", ) files.download("funasr_transcript.json")

这一步把识别结果序列化为 UTF-8 编码的 JSON 文件并触发浏览器下载。ensure_ascii=False保证中文文本以原文形式落盘而非\uXXXX转义，便于阅读和比对。这个 JSON 建议妥善保留：提交 issue 或对比不同模型输出时，直接附上该文件即可复现现场。

使用建议与注意事项

来自 README_zh.md 的官方建议，值得在动手前通读：

• 首次运行耗时：第一次运行会下载模型文件，可能需要几分钟；同一 runtime 内后续运行会明显变快（模型已缓存）；
• CPU vs GPU：CPU runtime 适合快速 smoke test（冒烟验证）；长音频建议切换到 GPU runtime；
• 生产部署衔接：先跑通 Notebook，再阅读 部署选型表 评估生产方案；如果要测试 OpenAI 兼容 HTTP 服务，参考 examples/openai_api/README_zh.md。

故障排查速查表

Notebook 运行中最常遇到的五类问题及处理方式，原文档以表格形式给出，完整保留如下：

跑通之后：继续深入 FunASR

Notebook 末尾的 "Next steps" 与 模型选择指南 共同指向了四条进阶路径：

1. 模型选型：本文使用的是中文生产路径paraformer-zh。需要多语种、情感/事件标签时，可改用 SenseVoice-Small（如iic/SenseVoiceSmall）；需要 LLM-based ASR（中/英/日 + 方言）时，可评估 Fun-ASR-Nano 系列。完整的选型决策表见 docs/model_selection_zh.md。
2. 与 Whisper 对比：评估是否从 Whisper 或云端 ASR 迁移时，参考 迁移指南 和 examples/migration 中的评测脚本，用自有音频建立基线后再做结论。
3. OpenAI 兼容 HTTP 服务：Colab 验证的是单机推理；面向服务化场景，examples/openai_api提供了 OpenAI 风格接口、Docker/Kubernetes 模板与多语言客户端示例，入口见 examples/openai_api/README_zh.md。
4. 生产部署矩阵：按工作负载（Notebook 评估、内部 HTTP 服务、实时音频、集群私有服务）选择合适的运行路径，见 docs/deployment_matrix_zh.md。

从浏览器里的第一行pip install，到一条model.generate(input=...)产出带标点的中文转写，再到 JSON 落盘与生产路径衔接——这条 Colab 快速体验链路既是新手友好的第一课，也是后续深入 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