Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

test: add Python OpenAI API smoke test

zhifu gao0386bff0a40c
diff --git a/docs/deployment_matrix.md b/docs/deployment_matrix.md
index 693fb80d7..a5af5b851 100644
--- a/docs/deployment_matrix.md
+++ b/docs/deployment_matrix.md
@@ -24,7 +24,7 @@ Use the Python API from the README. It is the shortest route for validating inst
### I want a local replacement for cloud transcription
-Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md). For API gateways, developer portals, and schema-driven imports, use the [OpenAPI spec](../examples/openai_api/OPENAPI.md).
+Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh` or `examples/openai_api/smoke_test.py`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md). For API gateways, developer portals, and schema-driven imports, use the [OpenAPI spec](../examples/openai_api/OPENAPI.md).
### I want a repeatable container demo
@@ -36,7 +36,7 @@ cp .env.example .env
docker compose up --build
```
-Keep CPU mode until you have a CUDA-capable PyTorch/FunASR image. After that, set `FUNASR_DEVICE=cuda` and verify with the same smoke test.
+Keep CPU mode until you have a CUDA-capable PyTorch/FunASR image. After that, set `FUNASR_DEVICE=cuda` and verify with the same smoke test. Use `python examples/openai_api/smoke_test.py --base-url http://localhost:8000` on systems without bash/curl.
### I need streaming or live captioning
diff --git a/docs/deployment_matrix_zh.md b/docs/deployment_matrix_zh.md
index 182429b74..c75189ee0 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_zh.md)。
+使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh` 或 `examples/openai_api/smoke_test.py`,再根据 [客户端配方](../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
@@ -36,7 +36,7 @@ cp .env.example .env
docker compose up --build
```
-在没有 CUDA-capable PyTorch/FunASR 镜像前保持 CPU 模式。准备好 CUDA 镜像后,再设置 `FUNASR_DEVICE=cuda` 并用同一个 smoke test 验证。
+在没有 CUDA-capable PyTorch/FunASR 镜像前保持 CPU 模式。准备好 CUDA 镜像后,再设置 `FUNASR_DEVICE=cuda` 并用同一个 smoke test 验证。没有 bash/curl 时可运行 `python examples/openai_api/smoke_test.py --base-url http://localhost:8000`。
### 我需要流式识别或实时字幕
diff --git a/examples/openai_api/BLOG_POST.md b/examples/openai_api/BLOG_POST.md
index c2e6028d1..0b6898800 100644
--- a/examples/openai_api/BLOG_POST.md
+++ b/examples/openai_api/BLOG_POST.md
@@ -31,6 +31,8 @@ In another terminal, use the bundled smoke test:
git clone https://github.com/modelscope/FunASR
cd FunASR/examples/openai_api
bash smoke_test.sh
+# Cross-platform alternative:
+python smoke_test.py
```
Or run the equivalent commands manually:
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index e6dc1fbb8..2807bd52a 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -21,6 +21,8 @@ In another terminal, download a public sample and verify both health and transcr
```bash
bash smoke_test.sh
+# Cross-platform alternative without curl/bash:
+python smoke_test.py
```
Equivalent manual commands:
@@ -144,6 +146,7 @@ Verify the container from another terminal:
```bash
BASE_URL=http://localhost:8000 bash smoke_test.sh
+python smoke_test.py --base-url http://localhost:8000
```
## Configuration
@@ -166,5 +169,5 @@ Docker environment variables:
## Troubleshooting
- If CUDA is unavailable, use `--device cpu` for a slower but simple smoke test.
-- If port 8000 is occupied, start with `--port 9000` and run `BASE_URL=http://localhost:9000 bash smoke_test.sh`.
+- If port 8000 is occupied, start with `--port 9000` and run `BASE_URL=http://localhost:9000 bash smoke_test.sh` or `python smoke_test.py --base-url http://localhost:9000`.
- If model download is slow, retry with a stable network or pre-download the model from ModelScope/Hugging Face.
diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.md
index 6f15cf49c..26e9cc970 100644
--- a/examples/openai_api/README_zh.md
+++ b/examples/openai_api/README_zh.md
@@ -21,6 +21,8 @@ python server.py --model sensevoice --device cuda --port 8000
```bash
bash smoke_test.sh
+# 不依赖 curl/bash 的跨平台方式:
+python smoke_test.py
```
等价手动命令:
@@ -132,6 +134,7 @@ docker run --rm --gpus all -p 8000:8000 \
```bash
BASE_URL=http://localhost:8000 bash smoke_test.sh
+python smoke_test.py --base-url http://localhost:8000
```
## 配置
@@ -156,7 +159,7 @@ Docker 环境变量:
| 现象 | 处理方式 |
|---|---|
| CUDA 不可用 | 先用 `--device cpu` 跑通 smoke test。 |
-| 8000 端口被占用 | 改用 `--port 9000`,并运行 `BASE_URL=http://localhost:9000 bash smoke_test.sh`。 |
+| 8000 端口被占用 | 改用 `--port 9000`,并运行 `BASE_URL=http://localhost:9000 bash smoke_test.sh` 或 `python smoke_test.py --base-url http://localhost:9000`。 |
| 模型下载很慢 | 换稳定网络,或提前从 ModelScope/Hugging Face 下载模型。 |
| Dify/n8n 容器里访问 `localhost` 失败 | 使用工作流运行时可访问的主机名、Compose service name 或 Kubernetes service name。 |
| 响应中没有 `segments` | 设置 `response_format=verbose_json`。 |
diff --git a/examples/openai_api/smoke_test.py b/examples/openai_api/smoke_test.py
new file mode 100755
index 000000000..56b682059
--- /dev/null
+++ b/examples/openai_api/smoke_test.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Cross-platform smoke test for the FunASR OpenAI-compatible API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import mimetypes
+import os
+from pathlib import Path
+import sys
+import urllib.error
+import urllib.request
+import uuid
+
+SAMPLE_URL = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav"
+
+
+def request_json(url: str, timeout: float) -> dict:
+ request = urllib.request.Request(url, headers={"Accept": "application/json"})
+ with urllib.request.urlopen(request, timeout=timeout) as response:
+ return json.loads(response.read().decode("utf-8"))
+
+
+def download_if_needed(path: Path, sample_url: str, timeout: float) -> None:
+ if path.exists():
+ return
+ print(f"Downloading sample audio to {path}")
+ with urllib.request.urlopen(sample_url, timeout=timeout) as response:
+ path.write_bytes(response.read())
+
+
+def multipart_body(audio_path: Path, model: str, response_format: str) -> tuple[bytes, str]:
+ boundary = f"----funasr-smoke-{uuid.uuid4().hex}"
+ content_type = mimetypes.guess_type(str(audio_path))[0] or "application/octet-stream"
+ parts: list[bytes] = []
+
+ def add_text(name: str, value: str) -> None:
+ parts.append(
+ (
+ f"--{boundary}\r\n"
+ f"Content-Disposition: form-data; name=\"{name}\"\r\n\r\n"
+ f"{value}\r\n"
+ ).encode("utf-8")
+ )
+
+ parts.append(
+ (
+ f"--{boundary}\r\n"
+ f"Content-Disposition: form-data; name=\"file\"; filename=\"{audio_path.name}\"\r\n"
+ f"Content-Type: {content_type}\r\n\r\n"
+ ).encode("utf-8")
+ )
+ parts.append(audio_path.read_bytes())
+ parts.append(b"\r\n")
+ add_text("model", model)
+ add_text("response_format", response_format)
+ parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+ return b"".join(parts), boundary
+
+
+def transcribe(base_url: str, audio_path: Path, model: str, response_format: str, timeout: float) -> dict:
+ body, boundary = multipart_body(audio_path, model, response_format)
+ request = urllib.request.Request(
+ f"{base_url}/v1/audio/transcriptions",
+ data=body,
+ method="POST",
+ headers={
+ "Accept": "application/json",
+ "Content-Type": f"multipart/form-data; boundary={boundary}",
+ "Content-Length": str(len(body)),
+ },
+ )
+ with urllib.request.urlopen(request, timeout=timeout) as response:
+ return json.loads(response.read().decode("utf-8"))
+
+
+def print_json(title: str, payload: dict) -> None:
+ print(f"\n== {title} ==")
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Smoke test the FunASR OpenAI-compatible API")
+ parser.add_argument("audio_path", nargs="?", default="sample.wav", help="Audio file to transcribe; downloads a sample if missing")
+ parser.add_argument("--base-url", default=os.getenv("BASE_URL", "http://localhost:8000"), help="FunASR API base URL")
+ parser.add_argument("--model", default=os.getenv("MODEL", "sensevoice"), help="Model alias to use")
+ parser.add_argument("--response-format", default=os.getenv("RESPONSE_FORMAT", "verbose_json"), choices=["json", "verbose_json"], help="Transcription response format")
+ parser.add_argument("--sample-url", default=os.getenv("SAMPLE_URL", SAMPLE_URL), help="Sample audio URL used when audio_path does not exist")
+ parser.add_argument("--timeout", type=float, default=float(os.getenv("TIMEOUT", "300")), help="HTTP timeout in seconds")
+ args = parser.parse_args()
+
+ base_url = args.base_url.rstrip("/")
+ audio_path = Path(args.audio_path)
+
+ try:
+ download_if_needed(audio_path, args.sample_url, args.timeout)
+ print_json("health", request_json(f"{base_url}/health", args.timeout))
+ print_json("models", request_json(f"{base_url}/v1/models", args.timeout))
+ print(f"\nTranscribing {audio_path} with model={args.model}, response_format={args.response_format}")
+ print_json("transcription", transcribe(base_url, audio_path, args.model, args.response_format, args.timeout))
+ except urllib.error.HTTPError as error:
+ detail = error.read().decode("utf-8", errors="replace")
+ print(f"HTTP {error.code} from {error.url}: {detail}", file=sys.stderr)
+ return 1
+ except Exception as error:
+ print(f"Smoke test failed: {error}", file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())