Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
docs: add Chinese OpenAI API quickstart
zhifu gao9f494cbae765
diff --git a/README_zh.md b/README_zh.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 ServerDrop-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.mdnew file mode 100644index 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 [email protected] \+ -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 [email protected] \+ -F model=sensevoice++curl http://localhost:8000/v1/audio/transcriptions \+ -F [email protected] \+ -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`。 |