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
test: add Python OpenAI API smoke test
zhifu gao0386bff0a40c
diff --git a/docs/deployment_matrix.md b/docs/deployment_matrix.mdindex 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 .envdocker 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 captioningdiff --git a/docs/deployment_matrix_zh.md b/docs/deployment_matrix_zh.mdindex 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 .envdocker 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.mdindex 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/FunASRcd FunASR/examples/openai_apibash 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.mdindex 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```bashbash 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:```bashBASE_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.mdindex 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```bashbash smoke_test.sh+# 不依赖 curl/bash 的跨平台方式:+python smoke_test.py```等价手动命令:@@ -132,6 +134,7 @@ docker run --rm --gpus all -p 8000:8000 \```bashBASE_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.pynew file mode 100755index 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())