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 Chinese OpenAI API quickstart

zhifu gao9f494cbae765
diff --git a/README_zh.md b/README_zh.md
index 64ca96e1c..21647bddb 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -50,7 +50,7 @@ result = model.generate(input="meeting.wav")
> **部署为 API 服务:** `funasr-server --device cuda` → 本地 OpenAI 兼容接口 localhost:8000
>
-> **接入 AI Agent:** [MCP 服务](examples/mcp_server/) 支持 Claude/Cursor · [OpenAI API](examples/openai_api/) 支持 LangChain/Dify/AutoGen
+> **接入 AI Agent:** [MCP 服务](examples/mcp_server/) 支持 Claude/Cursor · [OpenAI API](examples/openai_api/README_zh.md) 支持 LangChain/Dify/AutoGen
### 为什么选 FunASR?
@@ -197,7 +197,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
```
-[OpenAI API 示例 →](./examples/openai_api/) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
+[OpenAI API 示例 →](./examples/openai_api/README_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
---
diff --git a/docs/deployment_matrix_zh.md b/docs/deployment_matrix_zh.md
index dd6ecd4a3..95e3c7a65 100644
--- a/docs/deployment_matrix_zh.md
+++ b/docs/deployment_matrix_zh.md
@@ -7,8 +7,8 @@
| 路径 | 适合场景 | 从这里开始 | 运维提示 |
|---|---|---|---|
| Python API | Notebook、离线任务、首次模型评测 | [README 快速开始](../README_zh.md#快速开始) | 最简单;调用方自己负责批处理、重试和文件管理。 |
-| OpenAI 兼容 API | 私有语音 API、Agent、Dify/LangChain/AutoGen 风格客户端 | [OpenAI API 示例](../examples/openai_api/) | 已支持 OpenAI audio API 的应用最容易接入。 |
-| Docker Compose API | 可复现本地 smoke test 或小型内部服务 | [OpenAI API Docker 文档](../examples/openai_api/#docker-deployment) | 默认 CPU;容器里使用 CUDA 前需要先适配 CUDA-capable 镜像。 |
+| 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 镜像。 |
| Runtime WebSocket 服务 | 实时字幕、会议、客服流式音频 | [Runtime 服务文档](../runtime/readme_cn.md) | 需要中间结果、断句或长连接音频流时选择。 |
| vLLM 加速 | Fun-ASR-Nano 等 LLM-based ASR 高吞吐 | [vLLM 指南](./vllm_guide.md) | 适合 LLM 解码吞吐;不适用于非自回归 Paraformer。 |
| MCP 服务 | Claude/Cursor/桌面 Agent 语音工具 | [MCP 示例](../examples/mcp_server/) | 适合把 ASR 结果暴露成一个本地工具。 |
diff --git a/docs/migration_from_whisper_zh.md b/docs/migration_from_whisper_zh.md
index e540aa0bc..bcf4e3243 100644
--- a/docs/migration_from_whisper_zh.md
+++ b/docs/migration_from_whisper_zh.md
@@ -30,7 +30,7 @@
|---|---|---|
| Whisper 文件转写 | 使用 SenseVoice、Paraformer 或 Fun-ASR-Nano 的 [README 快速开始](../README_zh.md#快速开始) | 转写质量、时间戳、速度、模型下载、CPU/GPU 行为。 |
| Whisper + pyannote | VAD、标点和 `spk_model="cam++"` | 说话人标签、换人位置、重叠说话、长静音。 |
-| OpenAI 音频 API 或云端批量 ASR | [OpenAI 兼容 API 示例](../examples/openai_api/) | `/v1/audio/transcriptions`、响应格式、客户端兼容性、上传限制。 |
+| OpenAI 音频 API 或云端批量 ASR | [OpenAI 兼容 API 示例](../examples/openai_api/README_zh.md) | `/v1/audio/transcriptions`、响应格式、客户端兼容性、上传限制。 |
| Dify/LangChain/AutoGen Agent 音频 | [客户端配方](../examples/openai_api/CLIENTS.md) 或 [MCP 服务](../examples/mcp_server/) | 工具延迟、文件处理、鉴权边界、错误返回。 |
| 实时字幕或客服流式识别 | [Runtime 服务文档](../runtime/readme_cn.md) | 分块、断句、重连、背压、中间/最终结果行为。 |
| 字幕生成 | [字幕示例](../examples/subtitle/) | 分段可读性、行长、说话人标签、SRT/VTT 兼容性。 |
diff --git a/docs/use_case_showcase_zh.md b/docs/use_case_showcase_zh.md
index de9e3965c..972e2e3b4 100644
--- a/docs/use_case_showcase_zh.md
+++ b/docs/use_case_showcase_zh.md
@@ -9,7 +9,7 @@ FunASR 不只是一个离线转写命令。这个页面把常见的评测、部
| 本地转写一个文件 | [README 快速开始](../README_zh.md#快速开始) | 几分钟内验证安装、模型下载和首次推理。 |
| 对比准确率和速度 | [性能评测报告](https://modelscope.github.io/FunASR/zh/benchmark.html) | 选型前先查看 184 条长音频评测结果。 |
| 从 Whisper/云端 ASR 迁移 | [迁移指南](./migration_from_whisper_zh.md) | 将现有流水线映射到 FunASR,用代表性音频评测并规划安全上线。 |
-| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/)、[客户端配方](../examples/openai_api/CLIENTS.md) 和 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md) | 复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端,音频不出内网。 |
+| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/README_zh.md)、[客户端配方](../examples/openai_api/CLIENTS.md) 和 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md) | 复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端,音频不出内网。 |
| 给 Agent 增加语音输入 | [MCP 服务](../examples/mcp_server/) 和 [语音输入示例](../examples/voice_input/) | 将本地 ASR 接入 Claude、Cursor 和桌面 Agent 工作流。 |
| 选择部署路径 | [部署选型表](./deployment_matrix_zh.md) | 对比 Python API、OpenAI API、Docker Compose、WebSocket、vLLM、MCP、批处理、字幕和 Triton。 |
| 部署流式 ASR | [Runtime 服务文档](../runtime/readme_cn.md) | 面向实时字幕、客服、会议等低延迟场景。 |
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index fdd209f60..e6dc1fbb8 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -1,3 +1,5 @@
+(English|[简体中文](README_zh.md))
+
# FunASR OpenAI-Compatible API Server
Drop-in replacement for OpenAI's `/v1/audio/transcriptions` endpoint. Works with **any agent framework** that supports OpenAI audio API.
diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.md
new file mode 100644
index 000000000..95ffdc91f
--- /dev/null
+++ b/examples/openai_api/README_zh.md
@@ -0,0 +1,162 @@
+([English](README.md)|简体中文)
+
+# FunASR OpenAI 兼容 API 服务
+
+FunASR OpenAI 兼容 API 提供 `/v1/audio/transcriptions`,可作为私有语音转写服务接入 OpenAI 风格 SDK、Agent 框架、Dify、n8n、HTTP 节点和内部业务系统。
+
+## 快速开始
+
+```bash
+pip install funasr fastapi uvicorn python-multipart
+python server.py --model sensevoice --device cuda --port 8000
+```
+
+服务通常会在模型加载后启动。健康检查:`GET /health`。
+
+需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN.md) 和 [OpenAPI 规范](OPENAPI.md)。
+
+### 端到端 smoke test
+
+在另一个终端运行:
+
+```bash
+bash smoke_test.sh
+```
+
+等价手动命令:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/health
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
+## 使用 OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
+
+result = client.audio.transcriptions.create(
+ model="sensevoice", # 也可以使用 "paraformer"、"paraformer-en"、"fun-asr-nano"
+ file=open("meeting.wav", "rb"),
+)
+print(result.text)
+
+verbose = client.audio.transcriptions.create(
+ model="sensevoice",
+ file=open("meeting.wav", "rb"),
+ response_format="verbose_json",
+)
+print(verbose.segments)
+```
+
+## 使用 curl
+
+```bash
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice
+
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
+## 可用模型
+
+| Model | GPU 速度 | CPU 速度 | 语言 | 特性 |
+|---|---|---|---|---|
+| `sensevoice` | 170x realtime | 17x realtime | zh/en/ja/ko/yue | 情感与事件标签 |
+| `paraformer` | 120x realtime | 15x realtime | zh/en | 标点恢复 |
+| `paraformer-en` | 120x realtime | 15x realtime | en | 英文识别 |
+| `fun-asr-nano` | 17x realtime | 3.6x realtime | 31 languages | LLM-based,时间戳 |
+
+## API 端点
+
+| Endpoint | Method | 说明 |
+|---|---|---|
+| `/v1/audio/transcriptions` | POST | OpenAI 兼容音频转写 |
+| `/v1/models` | GET | 列出模型别名 |
+| `/health` | GET | 健康检查、已加载模型和可用模型 |
+| `/docs` | GET | FastAPI Swagger 文档 |
+
+不想写代码验证接口时,可以导入 [Postman 集合](POSTMAN.md)。如果要接入 API 网关、开发者门户或生成内部客户端,可以使用 [OpenAPI 规范](OPENAPI.md)。
+
+## Agent 与低代码工作流
+
+适用场景包括 **LangChain**、**LlamaIndex**、**AutoGen**、**CrewAI**、**Semantic Kernel**、**Dify**、**n8n** 和任何支持 OpenAI audio API 或 multipart HTTP 的系统。
+
+- SDK 和 Agent tool 写法见 [客户端配方](CLIENTS.md)。
+- Dify、n8n、HTTP 节点和 webhook worker 见 [工作流配方](WORKFLOWS_zh.md)。
+- 图形界面 smoke test 见 [Postman 集合](POSTMAN.md)。
+- schema 驱动导入见 [OpenAPI 规范](OPENAPI.md)。
+
+## Docker 部署
+
+默认镜像以 CPU 模式启动,适合作为可复现 smoke test。
+
+```bash
+cd examples/openai_api
+cp .env.example .env
+
+docker compose up --build
+```
+
+等价 `docker run`:
+
+```bash
+docker build -t funasr-api .
+
+docker run --rm -p 8000:8000 \
+ -e FUNASR_DEVICE=cpu \
+ -e FUNASR_MODEL=sensevoice \
+ funasr-api
+```
+
+GPU 环境需要 NVIDIA Container Toolkit 和 CUDA-capable PyTorch/FunASR 镜像。适配 CUDA 依赖后,可使用:
+
+```bash
+docker run --rm --gpus all -p 8000:8000 \
+ -e FUNASR_DEVICE=cuda \
+ -e FUNASR_MODEL=sensevoice \
+ funasr-api
+```
+
+验证容器:
+
+```bash
+BASE_URL=http://localhost:8000 bash smoke_test.sh
+```
+
+## 配置
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `--host` | `0.0.0.0` | 监听地址 |
+| `--port` | `8000` | 监听端口 |
+| `--device` | `cuda` | `cuda`、`cpu` 或 `mps` |
+| `--model` | `sensevoice` | 启动时预加载模型 |
+
+Docker 环境变量:
+
+| Env | 默认值 | 说明 |
+|---|---|---|
+| `FUNASR_PORT` | `8000` | 传给 `server.py` 的容器端口 |
+| `FUNASR_DEVICE` | `cpu` | 容器设备模式;只有在镜像已适配 CUDA 时才设为 `cuda` |
+| `FUNASR_MODEL` | `sensevoice` | 容器启动时加载的模型别名 |
+
+## 故障排查
+
+| 现象 | 处理方式 |
+|---|---|
+| CUDA 不可用 | 先用 `--device cpu` 跑通 smoke test。 |
+| 8000 端口被占用 | 改用 `--port 9000`,并运行 `BASE_URL=http://localhost:9000 bash smoke_test.sh`。 |
+| 模型下载很慢 | 换稳定网络,或提前从 ModelScope/Hugging Face 下载模型。 |
+| Dify/n8n 容器里访问 `localhost` 失败 | 使用工作流运行时可访问的主机名、Compose service name 或 Kubernetes service name。 |
+| 响应中没有 `segments` | 设置 `response_format=verbose_json`。 |