- Quick Start · Benchmark · Model selection · Migration guide · Use cases · Deployment matrix · Models · Agent Integration · Docs · Contribute + Quick Start · Colab · Benchmark · Model selection · Migration guide · Use cases · Deployment matrix · Models · Agent Integration · Docs · Contribute
--- ## Quick Start +[](https://colab.research.google.com/github/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb) + +No local setup? Open the [Colab quickstart](./examples/colab/) to transcribe a public sample or upload your own audio in a browser. + ```bash pip install funasr ``` @@ -66,7 +70,7 @@ That's it. **One model, one call** — VAD segmentation, speech recognition, pun | Cost | Free | Free | $0.006/min+ | | CPU viable | ✅ 17x realtime | ❌ Too slow | N/A | -Choosing a first model? Start with the [model selection guide](./docs/model_selection.md). Planning a switch from Whisper or a cloud ASR provider? Use the [migration guide](./docs/migration_from_whisper.md) and [benchmark example](./examples/migration/) to test representative audio, map features, and roll out safely. +Trying FunASR for the first time? Use the [Colab quickstart](./examples/colab/) before setting up a local environment. Choosing a first model? Start with the [model selection guide](./docs/model_selection.md). Planning a switch from Whisper or a cloud ASR provider? Use the [migration guide](./docs/migration_from_whisper.md) and [benchmark example](./examples/migration/) to test representative audio, map features, and roll out safely. --- diff --git a/README_ja.md b/README_ja.md index a6cb2127c..d0593dfb0 100644 --- a/README_ja.md +++ b/README_ja.md @@ -132,7 +132,7 @@ funasr-server --device cuda docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12 ``` -[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html) +[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html) --- diff --git a/README_ko.md b/README_ko.md index ed08aadf0..d2e83b89f 100644 --- a/README_ko.md +++ b/README_ko.md @@ -132,7 +132,7 @@ funasr-server --device cuda docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12 ``` -[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html) +[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html) --- diff --git a/README_zh.md b/README_zh.md index 3405f5985..2adb6ba14 100644 --- a/README_zh.md +++ b/README_zh.md @@ -21,13 +21,17 @@- 快速开始 · 性能评测 · 模型选择 · 迁移指南 · 场景速览 · 部署选型 · 模型列表 · Agent 集成 · 文档 · 贡献 + 快速开始 · Colab · 性能评测 · 模型选择 · 迁移指南 · 场景速览 · 部署选型 · 模型列表 · Agent 集成 · 文档 · 贡献
--- ## 快速开始 +[](https://colab.research.google.com/github/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb) + +不想先配置本地环境？可以打开 [Colab 快速体验](./examples/colab/) 在浏览器里转写公开样例或上传自己的音频。 + ```bash pip install funasr ``` @@ -65,7 +69,7 @@ result = model.generate(input="meeting.wav") | 费用 | 免费 | 免费 | ¥0.04/分钟起 | | CPU 可用 | ✅ 17 倍实时 | ❌ 太慢 | 不适用 | -还不确定先用哪个模型？先看 [模型选择指南](./docs/model_selection_zh.md)。计划从 Whisper 或云端 ASR 切换？请按 [迁移指南](./docs/migration_from_whisper_zh.md) 和 [评测示例](./examples/migration/) 用代表性音频评测、映射功能并安全上线。 +第一次试用 FunASR？可以先跑 [Colab 快速体验](./examples/colab/)，再配置本地环境。还不确定先用哪个模型？先看 [模型选择指南](./docs/model_selection_zh.md)。计划从 Whisper 或云端 ASR 切换？请按 [迁移指南](./docs/migration_from_whisper_zh.md) 和 [评测示例](./examples/migration/) 用代表性音频评测、映射功能并安全上线。 --- diff --git a/docs/deployment_matrix.md b/docs/deployment_matrix.md index 2889937e4..5c692514e 100644 --- a/docs/deployment_matrix.md +++ b/docs/deployment_matrix.md @@ -6,6 +6,7 @@ Use this page to choose the shortest deployment path for a product, demo, benchm | Path | Best for | Start here | Operational notes | |---|---|---|---| +| Colab notebook | Browser smoke tests, first evaluation, shareable demos | [Colab quickstart](../examples/colab/) | No local setup; first run downloads model files, GPU runtime is faster. | | Python API | Notebooks, offline jobs, first model evaluation | [README quick start](../README.md#quick-start) | Lowest ceremony; caller owns batching, retries, and files. | | OpenAI-compatible API | Private speech API, agents, Dify/LangChain/AutoGen-style clients | [OpenAI API example](../examples/openai_api/) | Easiest integration for apps that already support OpenAI audio APIs. | | Docker Compose API | Reproducible local smoke test or small internal service | [OpenAI API Docker docs](../examples/openai_api/#docker-deployment) | CPU by default; adapt the image before using CUDA in containers. | @@ -21,7 +22,7 @@ Use this page to choose the shortest deployment path for a product, demo, benchm ### I want to try FunASR in five minutes -Use the Python API from the README. It is the shortest route for validating installation, model download, device selection, and basic output shape. If you are unsure which model to start with, use the [model selection guide](./model_selection.md). +Use the [Colab quickstart](../examples/colab/) when you want a browser-only smoke test, or use the Python API from the README for local work. It is the shortest route for validating installation, model download, device selection, and basic output shape. If you are unsure which model to start with, use the [model selection guide](./model_selection.md). ### I want a local replacement for cloud transcription diff --git a/docs/deployment_matrix_zh.md b/docs/deployment_matrix_zh.md index a12191c01..8ea4ac127 100644 --- a/docs/deployment_matrix_zh.md +++ b/docs/deployment_matrix_zh.md @@ -6,6 +6,7 @@ | 路径 | 适合场景 | 从这里开始 | 运维提示 | |---|---|---|---| +| Colab Notebook | 浏览器 smoke test、首次评估、可分享 demo | [Colab 快速体验](../examples/colab/) | 不需要本地环境；首次运行会下载模型，GPU runtime 更快。 | | Python API | Notebook、离线任务、首次模型评测 | [README 快速开始](../README_zh.md#快速开始) | 最简单；调用方自己负责批处理、重试和文件管理。 | | OpenAI 兼容 API | 私有语音 API、Agent、Dify/LangChain/AutoGen 风格客户端 | [OpenAI API 示例](../examples/openai_api/README_zh.md) | 已支持 OpenAI audio API 的应用最容易接入。 | | Docker Compose API | 可复现本地 smoke test 或小型内部服务 | [OpenAI API Docker 文档](../examples/openai_api/README_zh.md) | 默认 CPU；容器里使用 CUDA 前需要先适配 CUDA-capable 镜像。 | @@ -21,7 +22,7 @@ ### 我想五分钟内试跑 FunASR -使用 README 里的 Python API。它是验证安装、模型下载、设备选择和基础输出格式的最短路径。如果还不确定先用哪个模型，请看 [模型选择指南](./model_selection_zh.md)。 +如果只想在浏览器里 smoke test，可以先用 [Colab 快速体验](../examples/colab/)；本地工作再使用 README 里的 Python API。它是验证安装、模型下载、设备选择和基础输出格式的最短路径。如果还不确定先用哪个模型，请看 [模型选择指南](./model_selection_zh.md)。 ### 我想替代云端转写服务 diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md index e26abd901..4822d3016 100644 --- a/docs/tutorial/README.md +++ b/docs/tutorial/README.md @@ -16,6 +16,8 @@ FunASR has open-sourced a large number of pre-trained models on industrial data. ### Quick Start +No local setup? Run the [Colab quickstart](../../examples/colab/) first, then move to the command line when you are ready. + For command-line invocation: ```shell funasr ++model=paraformer-zh ++vad_model="fsmn-vad" ++punc_model="ct-punc" ++input=asr_example_zh.wav diff --git a/docs/tutorial/README_zh.md b/docs/tutorial/README_zh.md index b82a896de..2e882db1b 100644 --- a/docs/tutorial/README_zh.md +++ b/docs/tutorial/README_zh.md @@ -16,6 +16,8 @@ FunASR开源了大量在工业数据上预训练模型，您可以在 [模型许 ### 快速使用 +不想先配置本地环境？可以先跑 [Colab 快速体验](../../examples/colab/)，确认模型和输出格式后再切到命令行。 + 命令行方式调用： ```shell funasr ++model=paraformer-zh ++vad_model="fsmn-vad" ++punc_model="ct-punc" ++input=asr_example_zh.wav diff --git a/docs/use_case_showcase.md b/docs/use_case_showcase.md index 22a288f88..f48acd4c4 100644 --- a/docs/use_case_showcase.md +++ b/docs/use_case_showcase.md @@ -6,6 +6,7 @@ FunASR is useful far beyond a single offline transcription command. This page co | Goal | Start here | Why it matters | |---|---|---| +| Try FunASR in a browser | [Colab quickstart](../examples/colab/) | Run a public sample and upload your own audio before setting up a local environment. | | Transcribe one file locally | [README quick start](../README.md#quick-start) and [model selection guide](./model_selection.md) | Verify install, model choice, and model download in minutes. | | Compare accuracy and speed | [Benchmark report](https://modelscope.github.io/FunASR/benchmark.html) | Reproduce the 184-file long-audio benchmark before choosing a model. | | Migrate from Whisper/cloud ASR | [Migration guide](./migration_from_whisper.md) | Map existing pipelines to FunASR, benchmark representative audio, and plan a safe rollout. | diff --git a/docs/use_case_showcase_zh.md b/docs/use_case_showcase_zh.md index 1e99328bf..b50f4ca62 100644 --- a/docs/use_case_showcase_zh.md +++ b/docs/use_case_showcase_zh.md @@ -6,6 +6,7 @@ FunASR 不只是一个离线转写命令。这个页面把常见的评测、部 | 目标 | 从这里开始 | 为什么重要 | |---|---|---| +| 在浏览器里试用 FunASR | [Colab 快速体验](../examples/colab/) | 配置本地环境前，先跑公开样例并上传自己的音频。 | | 本地转写一个文件 | [README 快速开始](../README_zh.md#快速开始) 和 [模型选择指南](./model_selection_zh.md) | 几分钟内验证安装、模型选择、模型下载和首次推理。 | | 对比准确率和速度 | [性能评测报告](https://modelscope.github.io/FunASR/zh/benchmark.html) | 选型前先查看 184 条长音频评测结果。 | | 从 Whisper/云端 ASR 迁移 | [迁移指南](./migration_from_whisper_zh.md) | 将现有流水线映射到 FunASR，用代表性音频评测并规划安全上线。 | diff --git a/examples/colab/README.md b/examples/colab/README.md new file mode 100644 index 000000000..311394fe0 --- /dev/null +++ b/examples/colab/README.md @@ -0,0 +1,22 @@ +# FunASR Colab Quickstart + +Run FunASR in a browser without preparing a local Python environment. + +[](https://colab.research.google.com/github/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb) + +## What the notebook covers + +- Install FunASR and runtime dependencies in Colab. +- Pick `cuda:0` automatically when a Colab GPU is available, otherwise use CPU. +- Transcribe a public sample audio file with `paraformer-zh`, VAD, and punctuation. +- Upload your own audio file and run the same model. +- Save the transcript JSON for sharing or issue reports. + +## Notes + +- The first run downloads model files and may take a few minutes. +- CPU runtime works for a quick smoke test; GPU runtime is faster for longer audio. +- If you are evaluating production deployment, use the [deployment matrix](../../docs/deployment_matrix.md) after the notebook works. +- For OpenAI-compatible HTTP service testing, use [examples/openai_api](../openai_api/). + +Notebook source: [funasr_quickstart.ipynb](https://github.com/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb). diff --git a/examples/colab/funasr_quickstart.ipynb b/examples/colab/funasr_quickstart.ipynb new file mode 100644 index 000000000..f3588c576 --- /dev/null +++ b/examples/colab/funasr_quickstart.ipynb @@ -0,0 +1,160 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# FunASR Colab Quickstart\n", + "\n", + "Run FunASR in a browser, transcribe a public sample, then try your own audio file.\n", + "\n", + "Repository: https://github.com/modelscope/FunASR\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 1. Install dependencies\n", + "\n", + "The first cell can take a few minutes because it installs FunASR and downloads Python wheels. Colab already includes PyTorch in most runtimes.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!pip -q install -U funasr modelscope soundfile" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2. Select CPU or GPU\n", + "\n", + "For a faster run, choose **Runtime -> Change runtime type -> GPU** in Colab before running the notebook.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import json\n", + "import torch\n", + "\n", + "device = \"cuda:0\" if torch.cuda.is_available() else \"cpu\"\n", + "print(f\"Using device: {device}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 3. Transcribe a public sample\n", + "\n", + "This uses `paraformer-zh` with VAD and punctuation so the example works with a short public Mandarin sample.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from funasr import AutoModel\n", + "\n", + "sample_url = \"https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav\"\n", + "\n", + "model = AutoModel(\n", + " model=\"paraformer-zh\",\n", + " vad_model=\"fsmn-vad\",\n", + " punc_model=\"ct-punc\",\n", + " device=device,\n", + ")\n", + "\n", + "result = model.generate(input=sample_url, batch_size_s=60)\n", + "print(json.dumps(result, ensure_ascii=False, indent=2))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 4. Try your own audio file\n", + "\n", + "Upload a short `.wav`, `.mp3`, `.m4a`, or `.flac` file. For long recordings, split the audio or use a GPU runtime.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from google.colab import files\n", + "\n", + "uploaded = files.upload()\n", + "audio_path = next(iter(uploaded))\n", + "print(f\"Uploaded: {audio_path}\")\n", + "\n", + "user_result = model.generate(input=audio_path, batch_size_s=60)\n", + "print(json.dumps(user_result, ensure_ascii=False, indent=2))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 5. Save the transcript JSON\n", + "\n", + "Attach this JSON when you open a GitHub issue or compare model outputs.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "\n", + "Path(\"funasr_transcript.json\").write_text(\n", + " json.dumps(user_result, ensure_ascii=False, indent=2),\n", + " encoding=\"utf-8\",\n", + ")\n", + "files.download(\"funasr_transcript.json\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "- Choose a model: https://github.com/modelscope/FunASR/blob/main/docs/model_selection.md\n", + "- Compare with Whisper or cloud ASR: https://github.com/modelscope/FunASR/blob/main/docs/migration_from_whisper.md\n", + "- Deploy an OpenAI-compatible API: https://github.com/modelscope/FunASR/tree/main/examples/openai_api\n", + "- Read production deployment options: https://github.com/modelscope/FunASR/blob/main/docs/deployment_matrix.md\n" + ] + } + ], + "metadata": { + "colab": { + "provenance": [] + }, + "kernelspec": { + "display_name": "Python 3", + "name": "python3" + }, + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}