企业官网建设流程全解析

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 是开源语音识别工具包，覆盖训练、推理、流式 ASR、VAD、标点、说话人分离以及 OpenAI 兼容/MCP 服务等完整链路。本文基于仓库中 examples/colab/README_ja.md 与其配套的 funasr_quickstart.ipynb，讲解如何在不准备任何本地 Python 环境的情况下，仅凭浏览器在 Google Colab 中安装 FunASR、自动选择 CPU/GPU、用paraformer-zh+ VAD + 标点模型转写公开样例音频与自己的录音文件，并将转写结果保存为 JSON 用于共享与问题反馈。读完本文，你将掌握 FunASR 最短的端到端上手路径，并理解其底层AutoModel.generate()的调用链与动态批处理原理。

一、Notebook 能做什么

funasr_quickstart.ipynb是一个开箱即用的 Colab Notebook，覆盖以下完整流程：

• 在 Colab 运行时中安装 FunASR 及其运行时依赖；
• 当 Colab 分配了 GPU 时自动选择cuda:0，否则回退到 CPU；
• 使用paraformer-zh（ASR）、fsmn-vad（语音活动检测）与ct-punc（标点恢复）三个模型对公开样例音频进行转写；
• 上传自己的音频文件，用同一套模型完成转写；
• 将转写结果保存为 transcript JSON，便于共享、对比输出或提交 issue 时附带证据。

Notebook 一共包含 5 个可执行单元，从安装到产出 JSON 结果，每一单元职责单一、可独立重跑，非常适合作为理解 FunASR 推理 API 的起点。

二、第一步：安装依赖

Notebook 的第一个单元安装 FunASR 及其 Python 依赖。由于需要下载 wheel 包，首次执行可能需要几分钟；Colab 的大多数运行时已预装 PyTorch，因此无需单独安装：

!pip -q install -U funasr modelscope soundfile

其中：

• funasr：核心工具包，提供AutoModel推理接口与全部模型实现；
• modelscope：模型仓库 SDK，用于首次使用某个模型时自动下载权重（paraformer-zh等别名在 funasr/download/name_maps_from_hub.py 中映射到 ModelScope 仓库 ID）；
• soundfile：音频读写库，用于解码 WAV、FLAC 等格式。

在本地环境（非 Colab）中使用同一安装命令同样有效，区别仅在于 Colab 会自动注入google.colab.files等专属工具。

三、第二步：自动选择 CPU 或 GPU

为了获得更快的运行速度，建议在运行 Notebook 前通过Runtime -> Change runtime type -> GPU选择 GPU 运行时。设备选择单元使用 PyTorch 的标准 API 做自动探测：

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

device变量随后会作为参数传入AutoModel。从源码看，AutoModel.generate() 支持文件路径、URL、numpy 数组、bytes 与列表等多种输入；device决定模型与张量存放位置。需要说明的是：CPU 运行时完全可以跑通整个流程，适合短时 smoke test；长音频场景下 GPU 运行时明显更快。

四、第三步：转写公开样例音频

这是 Notebook 的核心单元。它加载paraformer-zh作为识别模型，fsmn-vad负责切分语音片段，ct-punc负责标点恢复，组合成一条完整的中文离线转写流水线：

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

几个关键点值得展开：

• paraformer-zh是别名而非仓库 ID。在 funasr/download/name_maps_from_hub.py 中，paraformer-zh映射到iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch（SEACO-Paraformer 大规模中文 ASR 模型）。同样的别名约定也出现在 funasr/cli.py 的paraformer快捷配置中（model="paraformer-zh"+vad_model="fsmn-vad"+punc_model="ct-punc"），与 Notebook 的用法完全一致。
• model.generate()会根据是否配置 VAD 自动路由。查看 auto_model.py 的实现：若未配置vad_model，走inference()单段解码路径；若配置了vad_model，走inference_with_vad()长音频分段路径，其流水线为：VAD 切分语音区域 → ASR 逐段识别（按时长排序以提升批处理效率）→ 时间戳合并（叠加 VAD 偏移量）→ 标点恢复 →（可选）说话人聚类。这也是样例音频vad_example.wav命名与配置 VAD 模型的原因——演示的是完整的长音频处理链路。
• batch_size_s=60控制动态批处理的音频总时长。源码中batch_size = max(int(kwargs.get("batch_size_s", 300)) * 1000, 1)（auto_model.py），即把 VAD 切出的多个语音片段按总时长聚合成批，单位是秒，默认值为 300 秒，Notebook 显式设为 60 秒以便在交互环境中更快看到首批结果；同时batch_size_threshold_s（默认 60 秒）限制单片段超过该阈值时不参与合批，且在 CPU 上batch_size会被置 0（auto_model.py），即逐段顺序解码。

返回的result是列表，每个元素对应一个输入样本，常见字段包括key（样本标识）、text（识别文本）、timestamp（字符级时间戳）等。

五、第四步：转写自己的音频文件

在公开样例验证通过后，可以上传自己的音频。Notebook 支持.wav、.mp3、.m4a、.flac等常见格式，并通过 Colab 的文件上传组件获取路径：

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

上传前建议先截取短片段（如 1 分钟内的 WAV/MP3）验证流程；长音频优先使用 GPU 运行时，或先在本地切成有代表性的区间再上传。

六、第五步：保存转写结果为 JSON

将转写结果落盘并触发浏览器下载，便于存档、横向对比不同模型输出，或在提交 issue 时作为可复现证据：

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

注意使用ensure_ascii=False保证中文原文可读，indent=2提升 JSON 的可读性，两者与前面打印结果的设置保持一致。

七、注意事项与使用备忘

根据 Notebook 文档（README_ja.md）的说明，实际使用中需留意以下几点：

• 首次运行耗时较长：第一次执行会下载模型文件，可能耗时数分钟；同一运行时的后续执行因模型已缓存会明显加快。
• CPU 与 GPU 的取舍：CPU 运行时适合快速 smoke test；长音频建议使用 GPU 运行时。
• 生产部署评估：Notebook 跑通后，如需评估生产部署方案，请参考 deployment_matrix.md 的部署矩阵，按工作负载选择 PythonAutoModel、OpenAI 兼容 HTTP 服务、Docker Compose、Kubernetes 或 Runtime WebSocket 服务等路径。
• OpenAI 兼容服务：如需体验 OpenAI 兼容的 HTTP 接口，可参考 examples/openai_api/README_ja.md。
• 模型选择：Notebook 使用的中文场景默认组合是paraformer-zh；若需要多语言、情感/事件标签或 CPU 评估路径，可参考 docs/model_selection.md 中的决策表，例如 SenseVoice-Small、Fun-ASR-Nano、MOSS-Transcribe-Diarize 等不同起点。

八、故障排查速查表

Notebook 文档附带的排查表覆盖了最常见的 Colab 使用问题，整理如下：

九、Notebook 之外的进阶路径

Notebook 的定位是"最短上手路径"，跑通之后可以沿着以下方向深入（对应 Notebook 末尾的 Next steps 指引）：

• 模型选型：阅读 docs/model_selection.md，根据"多语言私有转写、中文生产 ASR、流式字幕、批处理归档"等需求选择合适的模型与运行时；
• 从 Whisper 迁移：参考 docs/migration_from_whisper.md，先用 SenseVoice-Small 建立基线，再对比候选模型；
• OpenAI 兼容 API 部署：参考 examples/openai_api/ 下的服务端实现，复用 OpenAI 风格客户端、Dify、n8n、LangChain 等生态；
• 生产部署矩阵：参考 docs/deployment_matrix.md，按工作负载在 Notebook 评估、HTTP 服务、容器、集群与流式服务之间做选择。

需要强调的是：Notebook 与官方 Transformers 原生 Notebook（fun_asr_nano_transformers.ipynb）属于不同环境——前者基于 FunASR 工具包，后者基于 5.17.0 版本、CPU 与官方样例，两者加载契约不同，评估结果不宜直接相互套用。

十、从 Notebook 到源码：一次调用背后的完整链路

最后，把本文涉及的源码证据串联起来，形成对 FunASR 推理 API 的整体认知：

1. 入口：from funasr import AutoModel创建模型对象，paraformer-zh/fsmn-vad/ct-punc三个别名在 name_maps_from_hub.py 中解析为 ModelScope 仓库 ID 并自动下载；
2. 路由：AutoModel.generate() 依据是否配置vad_model在inference()（单段）与inference_with_vad()（VAD 分段）之间自动选择；
3. 批处理：batch_size_s换算为毫秒级动态批大小，VAD 片段按时长排序后聚合成批，兼顾吞吐与延迟；
4. 输出：各片段结果按原顺序还原，时间戳叠加 VAD 偏移量，最终返回统一的list[dict]结构，可无缝衔接保存 JSON 的收尾单元。

这条链路正是 Notebook 五步流程在源码层面的真实映射，理解它之后，将同一套AutoModelAPI 迁移到本地脚本、批处理任务乃至 HTTP 服务都只是参数与输入源的变化而已。

【免费下载链接】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