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 workflow recipes
zhifu gao2549bbc3bd28
diff --git a/README_zh.md b/README_zh.mdindex 7e3501b37..2e553c97c 100644--- a/README_zh.md+++ b/README_zh.md@@ -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.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API 示例 →](./examples/openai_api/) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.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 8180dc3ab..e31243527 100644--- a/docs/deployment_matrix_zh.md+++ b/docs/deployment_matrix_zh.md@@ -24,7 +24,7 @@### 我想替代云端转写服务-使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh`,再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 接入 SDK 或 HTTP 客户端。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS.md)。+使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh`,再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 接入 SDK 或 HTTP 客户端。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。### 我想要可复现的容器 demodiff --git a/docs/use_case_showcase_zh.md b/docs/use_case_showcase_zh.mdindex 8fd4f94b5..de9e3965c 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.md) | 复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端,音频不出内网。 |+| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/)、[客户端配方](../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/CLIENTS.md b/examples/openai_api/CLIENTS.mdindex 85c32dc6e..adffb9ac7 100644--- a/examples/openai_api/CLIENTS.md+++ b/examples/openai_api/CLIENTS.md@@ -1,6 +1,6 @@# Client Recipes for the FunASR OpenAI-Compatible API-Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md).+Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md).## Preflight@@ -96,7 +96,7 @@ Use a multipart HTTP node or custom tool:| Text fields | `model=sensevoice`, `response_format=verbose_json` || Result path | `text` for transcript, `segments` for timestamps/speakers |-When the workflow system cannot send files directly, upload audio to an internal object store first, then run a small worker that downloads the object and calls FunASR with the `requests` recipe above. See [workflow recipes](WORKFLOWS.md) for Dify, n8n, and webhook-worker patterns.+When the workflow system cannot send files directly, upload audio to an internal object store first, then run a small worker that downloads the object and calls FunASR with the `requests` recipe above. See [workflow recipes](WORKFLOWS.md) for Dify, n8n, and webhook-worker patterns, or the [Chinese workflow recipes](WORKFLOWS_zh.md).## Response formatsdiff --git a/examples/openai_api/README.md b/examples/openai_api/README.mdindex 33f1304b4..a7844a5d1 100644--- a/examples/openai_api/README.md+++ b/examples/openai_api/README.md@@ -11,7 +11,7 @@ python server.py --model sensevoice --device cuda --port 8000Server starts in ~20s (model loading). Health check: `GET /health`-Need copy-paste integration snippets for Python SDK, HTTP clients, agent tools, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md) and [workflow recipes](WORKFLOWS.md).+Need copy-paste integration snippets for Python SDK, HTTP clients, agent tools, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [workflow recipes](WORKFLOWS.md), and the [Chinese workflow recipes](WORKFLOWS_zh.md).### End-to-end smoke test@@ -89,7 +89,7 @@ curl http://localhost:8000/v1/audio/transcriptions \## Agent Framework Integration-Works with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, or any framework using OpenAI audio API. See [Client recipes](CLIENTS.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers.+Works with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, or any framework using OpenAI audio API. See [Client recipes](CLIENTS.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers ([中文](WORKFLOWS_zh.md)).### LangChain Example```pythondiff --git a/examples/openai_api/WORKFLOWS.md b/examples/openai_api/WORKFLOWS.mdindex 8bb0c03dc..4a8941ff6 100644--- a/examples/openai_api/WORKFLOWS.md+++ b/examples/openai_api/WORKFLOWS.md@@ -1,5 +1,7 @@# Low-code Workflow Recipes for the FunASR OpenAI-Compatible API+[中文](WORKFLOWS_zh.md)+Use this guide when you want Dify, n8n, webhook workers, or another workflow engine to call a private FunASR speech API. Start with the local smoke test in this directory, then replace `localhost` with the reachable service name inside your network.## Server preflightdiff --git a/examples/openai_api/WORKFLOWS_zh.md b/examples/openai_api/WORKFLOWS_zh.mdnew file mode 100644index 000000000..edf48d8d3--- /dev/null+++ b/examples/openai_api/WORKFLOWS_zh.md@@ -0,0 +1,162 @@+# FunASR OpenAI 兼容 API 低代码工作流配方++[English](WORKFLOWS.md)++当你希望让 Dify、n8n、HTTP 节点、webhook worker 或其他低代码工作流引擎调用私有 FunASR 语音 API 时,可以从这份配方开始。建议先在本目录跑通本地 smoke test,再把 `localhost` 换成工作流运行环境能够访问到的服务名或内网地址。++## 服务预检++```bash+cd examples/openai_api+python server.py --model sensevoice --device cuda --port 8000+```++在工作流所在主机或容器中执行:++```bash+export FUNASR_BASE_URL=http://<funasr-host>:8000+curl -fsS "$FUNASR_BASE_URL/health"+curl -fsS "$FUNASR_BASE_URL/v1/models"+```++如果工作流引擎运行在 Docker 中,`localhost` 通常指的是工作流容器自身。请改用 Docker Compose service name、Kubernetes service name 或内网主机名。++## Multipart HTTP 请求++所有工作流引擎最终都需要发出下面这种请求:++| 字段 | 值 |+|---|---|+| Method | `POST` |+| URL | `http://<funasr-host>:8000/v1/audio/transcriptions` |+| Body type | `multipart/form-data` |+| File field | `file` |+| Text field | `model=sensevoice` |+| Text field | `response_format=verbose_json` |+| Timeout | 根据最长音频时长设置,例如长录音可先设为 300 秒。 |++等价 curl 命令:++```bash+curl "$FUNASR_BASE_URL/v1/audio/transcriptions" \+ -F [email protected] \+ -F model=sensevoice \+ -F response_format=verbose_json+```++常用响应字段映射:++| 路径 | 用途 |+|---|---|+| `text` | 纯文本转写结果,可传给聊天机器人、工单、知识库或后续摘要节点。 |+| `segments` | 请求 `verbose_json` 时返回的时间戳、说话人等分段信息。 |+| `duration` | API 返回的音频处理时长,适合写入日志和监控。 |+| `model` | 本次请求使用的模型别名。 |++## Dify 自定义工具或 HTTP 节点++当 Dify 应用接收上传音频文件,或收到内部音频存储 URL 时,可以使用下面两种模式。++### 直接上传文件++在 HTTP request 节点或自定义工具中配置:++- Method: `POST`+- URL: `http://<funasr-host>:8000/v1/audio/transcriptions`+- Body: `multipart/form-data`+- File part: `file`,绑定到上传音频变量+- Text parts: `model=sensevoice`、`response_format=verbose_json`+- Output variable: 把 `text` 映射为转写文本;需要时间戳或说话人信息时保留 `segments`++### 音频 URL 转写++有些工作流工具只能传文件 URL,而不能直接传 multipart 二进制。此时建议加一个内网 worker:++1. Dify 将音频 URL 和元数据发送给 worker。+2. worker 从可信存储下载音频。+3. worker 使用 multipart 请求调用 FunASR。+4. worker 将 `text`、`segments` 和运行日志返回给 Dify。++```python+import requests++FUNASR_URL = "http://funasr-api:8000/v1/audio/transcriptions"++def transcribe_from_url(audio_url: str) -> dict:+ audio_response = requests.get(audio_url, timeout=120)+ audio_response.raise_for_status()+ files = {"file": ("audio.wav", audio_response.content, "audio/wav")}+ data = {"model": "sensevoice", "response_format": "verbose_json"}+ response = requests.post(FUNASR_URL, files=files, data=data, timeout=300)+ response.raise_for_status()+ return response.json()+```++请把这个 worker 放在可信内网中,并在下载用户提供的链接前校验允许访问的域名或存储桶。++## n8n HTTP Request 节点++一个常见 n8n 流程是:触发器 -> 二进制音频数据 -> HTTP Request -> 转写结果消费节点。++推荐 HTTP Request 配置:++| n8n 设置 | 值 |+|---|---|+| Method | `POST` |+| URL | `http://<funasr-host>:8000/v1/audio/transcriptions` |+| Send Body | enabled |+| Body Content Type | `Form-Data` / multipart |+| Binary file field | `file` |+| Additional form fields | `model=sensevoice`、`response_format=verbose_json` |+| Response Format | JSON |+| Timeout | 长录音场景需要调大。 |++请求之后,使用 `{{$json.text}}` 作为转写文本。如果启用了 `verbose_json`,可以把 `{{$json.segments}}` 传给字幕、说话人分析或质检节点。++## Webhook worker 模式++当工作流引擎不能稳定发送 multipart 文件,或音频需要预处理时,可以把转写封装成一个内部 webhook worker。++```python+from pathlib import Path+import tempfile+import requests++FUNASR_URL = "http://localhost:8000/v1/audio/transcriptions"++def transcribe_bytes(filename: str, payload: bytes, content_type: str = "audio/wav") -> dict:+ with tempfile.NamedTemporaryFile(suffix=Path(filename).suffix or ".wav") as tmp:+ tmp.write(payload)+ tmp.flush()+ with open(tmp.name, "rb") as audio:+ response = requests.post(+ FUNASR_URL,+ files={"file": (filename, audio, content_type)},+ data={"model": "sensevoice", "response_format": "verbose_json"},+ timeout=300,+ )+ response.raise_for_status()+ return response.json()+```++这个 worker 也适合集中做音频转码、文件大小限制、请求 ID、鉴权、重试和审计日志。++## 生产环境护栏++- 在跨团队共享 FunASR 服务前,先加好鉴权、TLS、上传大小限制和限流。+- 使用 `/health` 做工作流 readiness check,使用 `/v1/models` 校验模型别名。+- 记录 request id、音频时长、模型别名、响应格式、设备、延迟和错误类型。+- 按最长音频时长设置工作流超时;超长录音建议先切分,再交给低代码工具处理。+- 私有音频放在可信存储中,避免把签名 URL、凭据或转写文本写入公开日志。+- 上生产前,至少用一个公开 smoke 样例和一个真实业务样例完整跑通同一条工作流。++## 故障排查++| 现象 | 处理方式 |+|---|---|+| 工作流能访问 `/health`,但转写失败 | 确认请求是 `multipart/form-data`,且二进制字段名是 `file`。 |+| Dify 或 n8n 访问 `localhost` 失败 | 换成工作流运行时可访问的主机名、Compose service name 或 Kubernetes service name。 |+| 响应中没有 `segments` | 设置 `response_format=verbose_json`。 |+| 请求超时 | 调大 HTTP timeout,或先切分长录音。 |+| 第一次请求很慢 | 使用 `--model sensevoice` 预加载模型,并用 `/health` 做 readiness check。 |+| 模型别名未知 | 调用 `/v1/models`,使用返回列表中的别名。 |