Skip to content

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

Add OpenAI API Docker validation helper (#3371)

zhifu gaode5418575de4
diff --git a/docs/community_growth_20k.md b/docs/community_growth_20k.md
index 32b998d34..91c7db423 100644
--- a/docs/community_growth_20k.md
+++ b/docs/community_growth_20k.md
@@ -351,7 +351,7 @@ Paste the Markdown output into launch notes, weekly community updates, or releas
- [x] Publish API server curl examples. On 2026-07-23, the OpenAI-compatible API docs already publish copy-paste curl paths in `examples/openai_api/README.md` and `examples/openai_api/README_zh.md`, plus scripted smoke tests in `examples/openai_api/smoke_test.sh` and `examples/openai_api/smoke_test.py`. The manual flow downloads `sample.wav`, checks `/health`, and posts to `/v1/audio/transcriptions` with `-F [email protected]`, `-F model=sensevoice`, and `response_format=verbose_json`; no-code and gateway users can use `examples/openai_api/POSTMAN.md` and `examples/openai_api/OPENAPI.md`.
- [x] Publish WebSocket streaming examples. On 2026-07-23, realtime WebSocket examples are published in `docs/vllm_guide.md`, `docs/vllm_guide_zh.md`, and `examples/industrial_data_pretraining/fun_asr_nano/docs/realtime_demo.md`. They show how to start `serve_realtime_ws.py`, connect to `ws://localhost:10095`, run `client_python.py --server ws://localhost:10095 --mic` or `client_python.py --server ws://localhost:10095 --file audio.wav`, interpret `partial`, `partial_start_ms`, and `is_final`, and run `realtime_ws_benchmark.py` for multi-client load checks.
-- [ ] Validate Docker CPU and GPU images.
+- [ ] Validate Docker CPU and GPU images. On 2026-07-23, `examples/openai_api/validate_docker.sh` was prepared so a Docker-capable host can run `bash validate_docker.sh` for the portable CPU image and `bash validate_docker.sh --gpu` for the NVIDIA Container Toolkit path. Current ops-host evidence: `ind-gpu8` has H100 GPUs but no `docker` CLI, and `funasr-web` also has no `docker` CLI, so do not mark this item complete until the script passes on a Docker host.
- [ ] Validate vLLM guide on one GPU server.
- [ ] Record concise terminal outputs for release notes.
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index 572f844a4..bf334dc29 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -160,6 +160,8 @@ BASE_URL=http://localhost:8000 bash smoke_test.sh
python smoke_test.py --base-url http://localhost:8000
```
+For a single build/run/smoke command, use `bash validate_docker.sh` for the portable CPU image. On a host with NVIDIA Container Toolkit and a CUDA-capable image, use `bash validate_docker.sh --gpu` to run the same smoke test with `FUNASR_DEVICE=cuda`.
+
## Kubernetes Deployment
Before sharing the service across a team or exposing it through a gateway, review the [security and gateway guide](SECURITY.md) for TLS, authentication, upload limits, rate limits, and logging.
diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.md
index 241189481..936bb8f8d 100644
--- a/examples/openai_api/README_zh.md
+++ b/examples/openai_api/README_zh.md
@@ -148,6 +148,8 @@ BASE_URL=http://localhost:8000 bash smoke_test.sh
python smoke_test.py --base-url http://localhost:8000
```
+如果想用一个命令完成 build、run 和 smoke test,可以用 `bash validate_docker.sh` 验证便携 CPU 镜像。具备 NVIDIA Container Toolkit 且镜像已适配 CUDA 时,可以用 `bash validate_docker.sh --gpu` 以 `FUNASR_DEVICE=cuda` 跑同一套 smoke test。
+
## Kubernetes 部署
在跨团队共享服务或通过网关暴露服务前,请先阅读 [安全与网关指南](SECURITY_zh.md),补齐 TLS、鉴权、上传限制、限流和日志策略。
diff --git a/examples/openai_api/validate_docker.sh b/examples/openai_api/validate_docker.sh
new file mode 100755
index 000000000..cf377973c
--- /dev/null
+++ b/examples/openai_api/validate_docker.sh
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+ cat <<'USAGE'
+Usage: bash validate_docker.sh [--gpu] [--tag funasr-api:local] [--port 8000]
+
+Build and smoke-test the OpenAI-compatible FunASR Docker example.
+
+Default mode validates the portable CPU image:
+ bash validate_docker.sh
+
+GPU mode requires NVIDIA Container Toolkit and a CUDA-capable image:
+ bash validate_docker.sh --gpu
+USAGE
+}
+
+want_gpu=0
+image_tag="funasr-api:local"
+host_port="8000"
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --gpu)
+ want_gpu=1
+ shift
+ ;;
+ --tag)
+ image_tag="${2:?missing value for --tag}"
+ shift 2
+ ;;
+ --port)
+ host_port="${2:?missing value for --port}"
+ shift 2
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ echo "Unknown argument: $1" >&2
+ usage >&2
+ exit 2
+ ;;
+ esac
+done
+
+if ! command -v docker >/dev/null 2>&1; then
+ echo "docker CLI is required for Docker validation." >&2
+ exit 127
+fi
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$script_dir"
+
+container_name="funasr-api-validate-${host_port}"
+base_url="http://127.0.0.1:${host_port}"
+
+cleanup() {
+ docker rm -f "$container_name" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+if [[ "$want_gpu" -eq 1 ]]; then
+ if ! command -v nvidia-smi >/dev/null 2>&1; then
+ echo "nvidia-smi is required for --gpu validation." >&2
+ exit 127
+ fi
+ if ! docker info 2>/dev/null | grep -qi "nvidia"; then
+ echo "NVIDIA Container Toolkit is required for --gpu validation." >&2
+ exit 1
+ fi
+fi
+
+echo "Building ${image_tag} from examples/openai_api/Dockerfile"
+docker build -t "$image_tag" .
+
+cleanup
+
+docker_args=(docker run --rm -d --name "$container_name" -p "${host_port}:8000")
+if [[ "$want_gpu" -eq 1 ]]; then
+ docker_args+=(--gpus all -e FUNASR_DEVICE=cuda)
+else
+ docker_args+=(-e FUNASR_DEVICE=cpu)
+fi
+docker_args+=(-e FUNASR_MODEL=sensevoice "$image_tag")
+
+echo "Starting ${container_name}"
+"${docker_args[@]}"
+
+echo "Waiting for /health"
+for _ in $(seq 1 60); do
+ if python - "$base_url" <<'PY' >/dev/null 2>&1
+import sys
+import urllib.request
+
+urllib.request.urlopen(sys.argv[1] + "/health", timeout=2).read()
+PY
+ then
+ break
+ fi
+ sleep 2
+done
+
+python smoke_test.py --base-url "$base_url"
+
+if [[ "$want_gpu" -eq 1 ]]; then
+ echo "GPU Docker validation passed for ${image_tag}"
+else
+ echo "CPU Docker validation passed for ${image_tag}"
+fi
diff --git a/tests/test_openai_api_docker_validation.py b/tests/test_openai_api_docker_validation.py
new file mode 100644
index 000000000..45e74eafe
--- /dev/null
+++ b/tests/test_openai_api_docker_validation.py
@@ -0,0 +1,53 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLE = ROOT / "examples" / "openai_api"
+PLAN = ROOT / "docs" / "community_growth_20k.md"
+
+
+def test_openai_api_docker_validation_script_documents_cpu_and_gpu_paths():
+ script = EXAMPLE / "validate_docker.sh"
+ text = script.read_text()
+
+ required = [
+ "docker build -t",
+ "docker run --rm -d",
+ "FUNASR_DEVICE=cpu",
+ "python smoke_test.py --base-url",
+ "--gpu",
+ "--gpus all",
+ "FUNASR_DEVICE=cuda",
+ "nvidia-smi",
+ "NVIDIA Container Toolkit",
+ ]
+ for marker in required:
+ assert marker in text
+
+
+def test_openai_api_readmes_link_docker_validation_script():
+ readmes = [
+ EXAMPLE / "README.md",
+ EXAMPLE / "README_zh.md",
+ ]
+
+ for readme in readmes:
+ text = readme.read_text()
+ assert "validate_docker.sh" in text
+ assert "FUNASR_DEVICE=cpu" in text
+ assert "FUNASR_DEVICE=cuda" in text
+
+
+def test_growth_plan_records_docker_validation_blocker_and_command():
+ text = PLAN.read_text()
+
+ required = [
+ "[ ] Validate Docker CPU and GPU images",
+ "`examples/openai_api/validate_docker.sh`",
+ "`bash validate_docker.sh`",
+ "`bash validate_docker.sh --gpu`",
+ "`ind-gpu8` has H100 GPUs but no `docker` CLI",
+ "`funasr-web` also has no `docker` CLI",
+ ]
+ for marker in required:
+ assert marker in text