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 OpenAI API smoke test quickstart

zhifu gao2d8bd6da018c
diff --git a/README.md b/README.md
index 28c5dfe2f..13c192b44 100644
--- a/README.md
+++ b/README.md
@@ -177,14 +177,26 @@ result = model.generate(input="audio.wav", granularity="utterance")
```bash
# OpenAI-compatible API (recommended)
pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
+funasr-server --model sensevoice --device cuda
# → POST /v1/audio/transcriptions at localhost:8000
+```
+
+Verify it with a public sample:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+```bash
# Docker streaming service
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
```
-[Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
+[OpenAI API example →](./examples/openai_api/) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
---
diff --git a/README_zh.md b/README_zh.md
index 03f440e56..3f31ef51e 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -176,14 +176,26 @@ result = model.generate(input="audio.wav", granularity="utterance")
```bash
# OpenAI 兼容 API(推荐)
pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
+funasr-server --model sensevoice --device cuda
# → POST /v1/audio/transcriptions,地址 localhost:8000
+```
+
+使用公开样例音频验证服务:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+```bash
# Docker 流式服务
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
```
-[部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
+[OpenAI API 示例 →](./examples/openai_api/) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
---
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index 8548892cb..b9160b274 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -11,6 +11,25 @@ python server.py --model sensevoice --device cuda --port 8000
Server starts in ~20s (model loading). Health check: `GET /health`
+### End-to-end smoke test
+
+In another terminal, download a public sample and verify both health and transcription:
+
+```bash
+bash smoke_test.sh
+```
+
+Equivalent manual commands:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/health
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
## Usage with OpenAI SDK (Python)
```python
@@ -102,3 +121,9 @@ docker run --gpus all -p 8000:8000 funasr-api
| `--port` | 8000 | Port |
| `--device` | cuda | Device (cuda/cpu/mps) |
| `--model` | sensevoice | Pre-load model at startup |
+
+## 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 model download is slow, retry with a stable network or pre-download the model from ModelScope/Hugging Face.
diff --git a/examples/openai_api/smoke_test.sh b/examples/openai_api/smoke_test.sh
new file mode 100755
index 000000000..9db0752b1
--- /dev/null
+++ b/examples/openai_api/smoke_test.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-http://localhost:8000}"
+MODEL="${MODEL:-sensevoice}"
+RESPONSE_FORMAT="${RESPONSE_FORMAT:-verbose_json}"
+AUDIO_PATH="${1:-sample.wav}"
+SAMPLE_URL="${SAMPLE_URL:-https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav}"
+
+if [ ! -f "$AUDIO_PATH" ]; then
+ echo "Downloading sample audio to $AUDIO_PATH"
+ curl -L "$SAMPLE_URL" -o "$AUDIO_PATH"
+fi
+
+echo "Checking $BASE_URL/health"
+curl -fsS "$BASE_URL/health"
+printf '\n\n'
+
+echo "Transcribing $AUDIO_PATH with model=$MODEL"
+curl -fsS "$BASE_URL/v1/audio/transcriptions" \
+ -F "file=@${AUDIO_PATH}" \
+ -F "model=${MODEL}" \
+ -F "response_format=${RESPONSE_FORMAT}"
+printf '\n'