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 Postman and OpenAPI guides

zhifu gao19c62e9713ba
diff --git a/README_zh.md b/README_zh.md
index 21647bddb..44981fcd4 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/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)
+[OpenAI API 示例 →](./examples/openai_api/README_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN_zh.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI_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.md
index 95e3c7a65..182429b74 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_zh.md)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI.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)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI_zh.md)。
### 我想要可复现的容器 demo
diff --git a/examples/openai_api/OPENAPI.md b/examples/openai_api/OPENAPI.md
index 168b3de13..56b750612 100644
--- a/examples/openai_api/OPENAPI.md
+++ b/examples/openai_api/OPENAPI.md
@@ -1,5 +1,7 @@
# OpenAPI Spec for the FunASR OpenAI-Compatible API
+(English|[简体中文](OPENAPI_zh.md))
+
Use [`openapi.json`](openapi.json) when you want to inspect, mock, document, or import the FunASR speech API before wiring it into an application, API gateway, workflow engine, or SDK generator.
The running FastAPI server also exposes live docs at `/docs` and a generated schema at `/openapi.json`. This checked-in spec is a portable reference for the example server in this directory.
diff --git a/examples/openai_api/OPENAPI_zh.md b/examples/openai_api/OPENAPI_zh.md
new file mode 100644
index 000000000..bdad4ba04
--- /dev/null
+++ b/examples/openai_api/OPENAPI_zh.md
@@ -0,0 +1,53 @@
+# FunASR OpenAI 兼容 API OpenAPI 规范
+
+[English](OPENAPI.md)
+
+当你希望在接入应用、API 网关、开发者门户、工作流引擎或 SDK 生成器之前,先查看、mock、导入或发布 FunASR 语音 API 时,可以使用 [`openapi.json`](openapi.json)。
+
+运行中的 FastAPI 服务也会在 `/docs` 暴露 Swagger UI,并在 `/openapi.json` 暴露实时 schema。仓库里的 `openapi.json` 是这个示例服务的便携参考规范,便于在服务启动前完成评估和导入。
+
+## 导入方式
+
+| 工具 | 使用方式 |
+|---|---|
+| Swagger Editor 或 Redoc | 导入 `openapi.json`,查看 `/health`、`/v1/models` 和 `/v1/audio/transcriptions`。 |
+| Postman | 如果偏好 schema 驱动集合,可导入 `openapi.json`;如果想直接 smoke test,可使用现成的 [Postman 集合](POSTMAN_zh.md)。 |
+| Dify、n8n 或内部工作流工具 | 结合规范中的 multipart 请求结构和 [工作流配方](WORKFLOWS_zh.md) 配置 HTTP 节点。 |
+| API 网关或内部开发者门户 | 发布该规范,并把 server URL 改成你的 FunASR API 可访问地址。 |
+| 客户端生成 | 生成内部小客户端,并确保 multipart `file` 字段映射为二进制上传。 |
+
+## Server URL
+
+规范内置了两个示例地址:
+
+- `http://localhost:8000`
+- `http://funasr-api:8000`
+
+请替换为你的应用、容器或工作流运行环境能访问到的地址。
+
+## 端点
+
+| Endpoint | Method | 用途 |
+|---|---|---|
+| `/health` | `GET` | 健康检查、设备、已加载模型和可用别名。 |
+| `/v1/models` | `GET` | OpenAI 风格模型列表,包含 `ready` 状态。 |
+| `/v1/audio/transcriptions` | `POST` | multipart 音频转写;使用 `response_format=verbose_json` 返回 segments。 |
+
+## Multipart 转写字段
+
+| Field | Type | Required | 说明 |
+|---|---|---|---|
+| `file` | binary | yes | 音频文件,例如 wav、mp3、flac、m4a、ogg 或 webm。 |
+| `model` | string | no | 默认 `sensevoice`;可用别名由 `/v1/models` 返回。 |
+| `language` | string | no | 可选语言提示。 |
+| `response_format` | string | no | 使用 `json` 或 `verbose_json`。 |
+
+## 对照运行中的服务验证
+
+```bash
+cd examples/openai_api
+python server.py --model sensevoice --device cuda --port 8000
+curl -fsS http://localhost:8000/openapi.json > /tmp/funasr-openapi-live.json
+```
+
+实时 FastAPI schema 可能包含框架级校验细节;仓库中的静态规范保留更小、更稳定的公开集成面。
diff --git a/examples/openai_api/POSTMAN.md b/examples/openai_api/POSTMAN.md
index 729b66103..b23adc2b1 100644
--- a/examples/openai_api/POSTMAN.md
+++ b/examples/openai_api/POSTMAN.md
@@ -1,5 +1,7 @@
# Postman Collection for the FunASR OpenAI-Compatible API
+(English|[简体中文](POSTMAN_zh.md))
+
Use the Postman collection when you want to verify a private FunASR speech API before wiring it into Dify, n8n, an agent framework, or an internal service. If you prefer schema-driven imports, use the [OpenAPI spec](OPENAPI.md).
## Import
diff --git a/examples/openai_api/POSTMAN_zh.md b/examples/openai_api/POSTMAN_zh.md
new file mode 100644
index 000000000..8461638e7
--- /dev/null
+++ b/examples/openai_api/POSTMAN_zh.md
@@ -0,0 +1,39 @@
+# FunASR OpenAI 兼容 API Postman 集合
+
+[English](POSTMAN.md)
+
+当你希望先用图形界面验证私有 FunASR 语音 API,再接入 Dify、n8n、Agent 框架或内部服务时,可以导入 Postman collection。需要按 schema 导入时,可使用 [OpenAPI 规范](OPENAPI_zh.md)。
+
+## 导入步骤
+
+1. 启动服务:
+
+ ```bash
+ cd examples/openai_api
+ python server.py --model sensevoice --device cuda --port 8000
+ ```
+
+2. 在 Postman 中导入 [`funasr-openai-api.postman_collection.json`](funasr-openai-api.postman_collection.json)。
+3. 将 collection 变量 `FUNASR_BASE_URL` 改成可访问的服务地址,例如 `http://localhost:8000` 或 `http://funasr-api:8000`。
+4. 第一次 smoke test 建议保持 `MODEL_ALIAS=sensevoice`;也可以先运行 `/v1/models`,再复制返回的模型别名。
+
+## 请求列表
+
+| Request | 用途 |
+|---|---|
+| `Health check` | 确认服务可访问并返回 JSON。 |
+| `List model aliases` | 查看服务暴露的 OpenAI 兼容模型别名。 |
+| `Transcribe audio - verbose JSON` | 上传音频并返回 `text`、`segments` 和耗时信息。 |
+| `Transcribe audio - text only` | 最小转写请求,适合验证 OpenAI 兼容客户端。 |
+
+发送转写请求前,请打开 `Body` tab,在 `file` form-data 字段选择本地音频文件。
+
+## 故障排查
+
+| 现象 | 处理方式 |
+|---|---|
+| `ECONNREFUSED` | 确认服务已启动,并且 Postman 能访问 `FUNASR_BASE_URL`。 |
+| Docker 服务正常但 Postman 连不上 | 使用 Docker Compose 暴露到宿主机的端口,例如 `http://localhost:8000`。 |
+| `422` 或提示缺少文件 | 确认 `file` form-data 行已启用,并指向本地音频文件。 |
+| 模型别名未知 | 先运行 `List model aliases`,再把返回的别名填入 `MODEL_ALIAS`。 |
+| 响应中没有 `segments` | 设置 `RESPONSE_FORMAT=verbose_json`。 |
diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.md
index 95ffdc91f..6f15cf49c 100644
--- a/examples/openai_api/README_zh.md
+++ b/examples/openai_api/README_zh.md
@@ -13,7 +13,7 @@ python server.py --model sensevoice --device cuda --port 8000
服务通常会在模型加载后启动。健康检查:`GET /health`。
-需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN.md) 和 [OpenAPI 规范](OPENAPI.md)。
+需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md) 和 [OpenAPI 规范](OPENAPI_zh.md)。
### 端到端 smoke test
@@ -86,7 +86,7 @@ curl http://localhost:8000/v1/audio/transcriptions \
| `/health` | GET | 健康检查、已加载模型和可用模型 |
| `/docs` | GET | FastAPI Swagger 文档 |
-不想写代码验证接口时,可以导入 [Postman 集合](POSTMAN.md)。如果要接入 API 网关、开发者门户或生成内部客户端,可以使用 [OpenAPI 规范](OPENAPI.md)。
+不想写代码验证接口时,可以导入 [Postman 集合](POSTMAN_zh.md)。如果要接入 API 网关、开发者门户或生成内部客户端,可以使用 [OpenAPI 规范](OPENAPI_zh.md)。
## Agent 与低代码工作流
@@ -94,8 +94,8 @@ curl http://localhost:8000/v1/audio/transcriptions \
- SDK 和 Agent tool 写法见 [客户端配方](CLIENTS.md)。
- Dify、n8n、HTTP 节点和 webhook worker 见 [工作流配方](WORKFLOWS_zh.md)。
-- 图形界面 smoke test 见 [Postman 集合](POSTMAN.md)。
-- schema 驱动导入见 [OpenAPI 规范](OPENAPI.md)。
+- 图形界面 smoke test 见 [Postman 集合](POSTMAN_zh.md)。
+- schema 驱动导入见 [OpenAPI 规范](OPENAPI_zh.md)。
## Docker 部署
diff --git a/examples/openai_api/WORKFLOWS_zh.md b/examples/openai_api/WORKFLOWS_zh.md
index 7800bcbc0..a3267c0b0 100644
--- a/examples/openai_api/WORKFLOWS_zh.md
+++ b/examples/openai_api/WORKFLOWS_zh.md
@@ -23,7 +23,7 @@ curl -fsS "$FUNASR_BASE_URL/v1/models"
## Postman smoke test
-在配置低代码工具前,可以先导入 [Postman collection](POSTMAN.md),从图形界面跑通 health、模型列表和转写请求;需要按 schema 导入时可使用 [OpenAPI spec](OPENAPI.md)。设置 `FUNASR_BASE_URL`,在 multipart `file` 字段选择本地音频文件,第一次测试建议保持 `MODEL_ALIAS=sensevoice`。
+在配置低代码工具前,可以先导入 [Postman collection](POSTMAN_zh.md),从图形界面跑通 health、模型列表和转写请求;需要按 schema 导入时可使用 [OpenAPI spec](OPENAPI_zh.md)。设置 `FUNASR_BASE_URL`,在 multipart `file` 字段选择本地音频文件,第一次测试建议保持 `MODEL_ALIAS=sensevoice`。
## Multipart HTTP 请求