mirror of
https://github.com/modelscope/FunASR.git
synced 2026-10-12 02:19:18 +00:00
docs: add Chinese workflow recipes
Co-authored-by: xiaoyunchong.xyc <[email protected]>
This commit is contained in:
zhifu gao
co-authored by
xiaoyunchong.xyc
xiaoyunchong.xyc
parent
fa2e1a7f80
commit
2549bbc3bd
+1
-1
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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)。
|
||||
|
||||
### 我想要可复现的容器 demo
|
||||
|
||||
|
||||
@@ -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) | 面向实时字幕、客服、会议等低延迟场景。 |
|
||||
|
||||
@@ -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 formats
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ python server.py --model sensevoice --device cuda --port 8000
|
||||
|
||||
Server 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
|
||||
```python
|
||||
|
||||
@@ -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 preflight
|
||||
|
||||
@@ -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 file=@meeting.wav \
|
||||
-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`，使用返回列表中的别名。 |
|
||||
Reference in New Issue
Block a user