Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: add use case showcase

zhifu gao0b9c82819fbe
diff --git a/README.md b/README.md
index 13c192b44..12f3e1b99 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@
</p>
<p align="center">
- <a href="#quick-start">Quick Start</a> · <a href="#benchmark">Benchmark</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a> · <a href="./CONTRIBUTING.md">Contribute</a>
+ <a href="#quick-start">Quick Start</a> · <a href="#benchmark">Benchmark</a> · <a href="./docs/use_case_showcase.md">Use cases</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a> · <a href="./CONTRIBUTING.md">Contribute</a>
</p>
---
diff --git a/README_zh.md b/README_zh.md
index 3f31ef51e..c20892ca2 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -21,7 +21,7 @@
</p>
<p align="center">
- <a href="#快速开始">快速开始</a> · <a href="#性能评测">性能评测</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a> · <a href="./CONTRIBUTING.md">贡献</a>
+ <a href="#快速开始">快速开始</a> · <a href="#性能评测">性能评测</a> · <a href="./docs/use_case_showcase_zh.md">场景速览</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a> · <a href="./CONTRIBUTING.md">贡献</a>
</p>
---
diff --git a/docs/index.rst b/docs/index.rst
index 865ee10e4..a80518c1a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -104,6 +104,8 @@ Overview
:maxdepth: 1
:caption: Application
+ ./use_case_showcase.md
+ ./use_case_showcase_zh.md
./reference/application.md
.. toctree::
diff --git a/docs/use_case_showcase.md b/docs/use_case_showcase.md
new file mode 100644
index 000000000..1974094c1
--- /dev/null
+++ b/docs/use_case_showcase.md
@@ -0,0 +1,85 @@
+# FunASR Use-case Showcase
+
+FunASR is useful far beyond a single offline transcription command. This page collects the fastest paths for developers who want to evaluate, deploy, or integrate speech understanding in real products.
+
+## Choose the right path
+
+| Goal | Start here | Why it matters |
+|---|---|---|
+| Transcribe one file locally | [README quick start](../README.md#quick-start) | Verify install 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. |
+| Build a private speech API | [OpenAI-compatible API example](../examples/openai_api/) | Reuse LangChain, Dify, AutoGen, and other OpenAI-style clients without sending audio to a cloud ASR provider. |
+| Add speech input to agents | [MCP server](../examples/mcp_server/) and [voice input](../examples/voice_input/) | Connect local ASR to Claude, Cursor, and desktop agent workflows. |
+| Serve streaming ASR | [Runtime service docs](../runtime/readme.md) | Run WebSocket or service-mode ASR for live captioning and call-center style workloads. |
+| Accelerate LLM-based ASR | [vLLM guide](./vllm_guide.md) | Use tensor parallel decoding and streaming service support for Fun-ASR-Nano. |
+| Generate subtitles | [Subtitle example](../examples/subtitle/) | Turn long audio or video into subtitle files for media workflows. |
+| Process many recordings | [Batch ASR example](../examples/batch_asr_improved.py) | Build repeatable offline jobs for archives, meetings, and datasets. |
+
+## Production-oriented recipes
+
+### Private transcription API
+
+Use this path when an application already speaks OpenAI-style APIs or when audio cannot leave your environment.
+
+```bash
+pip install funasr fastapi uvicorn python-multipart
+funasr-server --model sensevoice --device cuda
+```
+
+```bash
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
+Recommended next steps:
+
+- Run the [OpenAI-compatible API smoke test](../examples/openai_api/smoke_test.sh).
+- Add authentication and network controls at your service boundary.
+- Record model name, device, driver, and audio duration in bug reports and benchmarks.
+
+### Agent speech input
+
+Use this path when you want to talk to coding agents, internal assistants, or workflow tools.
+
+- Start with the [MCP server example](../examples/mcp_server/) for Claude/Cursor-style tools.
+- Use the [voice input example](../examples/voice_input/) for desktop speech input experiments.
+- Keep latency visible: log audio duration, processing time, and selected model for each request.
+
+### Streaming and call-center workloads
+
+Use this path when partial results and low perceived latency matter more than a single final transcript.
+
+- Start from the [runtime service docs](../runtime/readme.md).
+- Pair ASR with VAD, punctuation, and speaker diarization when the transcript needs to be readable by humans.
+- Validate with realistic audio: background noise, long silence, overlapping speakers, and different microphone quality.
+
+### Benchmark before migrating from Whisper
+
+Use this path when deciding whether FunASR is a good replacement for Whisper or a cloud ASR provider.
+
+- Read the [public benchmark report](https://modelscope.github.io/FunASR/benchmark.html).
+- Benchmark your own sample set before migration; include both short clips and long-form recordings.
+- Track cost and throughput together: GPU speed, CPU viability, model download size, and deployment complexity.
+
+## Model selection hints
+
+| Need | Good first choice | Notes |
+|---|---|---|
+| Fast multilingual transcription | SenseVoice-Small | Strong default for local demos and private APIs. |
+| Mandarin production ASR | Paraformer-Large | Mature choice for Chinese speech recognition. |
+| LLM-based ASR experiments | Fun-ASR-Nano | Pair with the [vLLM guide](./vllm_guide.md) when throughput matters. |
+| Speaker-aware transcripts | SenseVoice or Paraformer with `spk_model="cam++"` | Useful for meetings, interviews, and customer calls. |
+| Live audio | Runtime WebSocket service | Validate chunking, VAD, and endpointing with real traffic. |
+
+## Share your result
+
+If FunASR works well in your project, consider opening a GitHub Discussion or issue with:
+
+- Use case and deployment mode.
+- Model, device, and processing speed.
+- Audio domain, language, and rough duration.
+- A public demo, screenshot, benchmark summary, or integration link when available.
+
+Concrete usage reports help new users choose the right path and help maintainers prioritize the next round of docs and examples.
diff --git a/docs/use_case_showcase_zh.md b/docs/use_case_showcase_zh.md
new file mode 100644
index 000000000..9568b4144
--- /dev/null
+++ b/docs/use_case_showcase_zh.md
@@ -0,0 +1,85 @@
+# FunASR 场景速览
+
+FunASR 不只是一个离线转写命令。这个页面把常见的评测、部署、Agent 集成和生产场景整理到一起,方便新用户快速找到入口。
+
+## 选择合适路径
+
+| 目标 | 从这里开始 | 为什么重要 |
+|---|---|---|
+| 本地转写一个文件 | [README 快速开始](../README_zh.md#快速开始) | 几分钟内验证安装、模型下载和首次推理。 |
+| 对比准确率和速度 | [性能评测报告](https://modelscope.github.io/FunASR/zh/benchmark.html) | 选型前先查看 184 条长音频评测结果。 |
+| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/) | 复用 LangChain、Dify、AutoGen 等 OpenAI 风格客户端,音频不出内网。 |
+| 给 Agent 增加语音输入 | [MCP 服务](../examples/mcp_server/) 和 [语音输入示例](../examples/voice_input/) | 将本地 ASR 接入 Claude、Cursor 和桌面 Agent 工作流。 |
+| 部署流式 ASR | [Runtime 服务文档](../runtime/readme_cn.md) | 面向实时字幕、客服、会议等低延迟场景。 |
+| 加速 LLM-based ASR | [vLLM 指南](./vllm_guide.md) | 为 Fun-ASR-Nano 使用 tensor parallel 解码和流式服务能力。 |
+| 生成字幕 | [字幕示例](../examples/subtitle/) | 将长音频或视频转成字幕文件。 |
+| 批量处理录音 | [批处理示例](../examples/batch_asr_improved.py) | 为录音归档、会议纪要、数据集处理搭建可重复流水线。 |
+
+## 面向生产的配方
+
+### 私有转写 API
+
+当应用已经兼容 OpenAI 风格接口,或音频不能离开私有环境时,优先使用这个路径。
+
+```bash
+pip install funasr fastapi uvicorn python-multipart
+funasr-server --model sensevoice --device cuda
+```
+
+```bash
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
+建议下一步:
+
+- 运行 [OpenAI 兼容 API smoke test](../examples/openai_api/smoke_test.sh)。
+- 在服务边界增加鉴权、限流和网络访问控制。
+- 记录模型、设备、驱动、音频时长和处理耗时,便于复现问题和 benchmark。
+
+### Agent 语音输入
+
+当你想把语音输入接到编码助手、内部助手或工作流工具时,使用这个路径。
+
+- Claude/Cursor 类工具优先看 [MCP 服务示例](../examples/mcp_server/)。
+- 桌面语音输入实验可以从 [voice input 示例](../examples/voice_input/) 开始。
+- 保持延迟可见:每次请求记录音频时长、处理耗时和模型名称。
+
+### 流式与客服场景
+
+当你更关注低延迟和中间结果,而不是单次完整转写时,使用这个路径。
+
+- 从 [Runtime 服务文档](../runtime/readme_cn.md) 开始。
+- 需要给人阅读时,把 ASR 与 VAD、标点恢复、说话人分离一起使用。
+- 用真实音频验证:背景噪声、长静音、多人重叠、不同麦克风质量。
+
+### 从 Whisper 迁移前先评测
+
+当你在评估是否用 FunASR 替代 Whisper 或云端 ASR 时,使用这个路径。
+
+- 阅读 [公开性能评测](https://modelscope.github.io/FunASR/zh/benchmark.html)。
+- 用自己的样本集再测一次;同时包含短音频和长音频。
+- 同时记录成本和吞吐:GPU 速度、CPU 可用性、模型下载体积、部署复杂度。
+
+## 模型选择建议
+
+| 需求 | 推荐先试 | 说明 |
+|---|---|---|
+| 快速多语种转写 | SenseVoice-Small | 本地 demo 和私有 API 的稳妥默认选择。 |
+| 中文生产 ASR | Paraformer-Large | 中文语音识别的成熟选择。 |
+| LLM-based ASR 实验 | Fun-ASR-Nano | 吞吐敏感时配合 [vLLM 指南](./vllm_guide.md)。 |
+| 带说话人信息的转写 | SenseVoice 或 Paraformer + `spk_model="cam++"` | 适合会议、访谈、客服录音。 |
+| 实时音频 | Runtime WebSocket 服务 | 用真实流量验证分块、VAD 和断句。 |
+
+## 分享你的结果
+
+如果 FunASR 在你的项目里效果不错,欢迎在 GitHub Discussion 或 issue 里分享:
+
+- 使用场景和部署方式。
+- 模型、设备和处理速度。
+- 音频领域、语言和大致时长。
+- 可以公开的 demo、截图、benchmark 摘要或集成链接。
+
+具体的使用反馈能帮助新用户更快选型,也能帮助维护者决定下一批文档和示例优先级。