Skip to content

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

feat(openai-api): production-ready server with full test coverage

游雁25e9063132b0
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index 1bd387eac..8548892cb 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -9,18 +9,29 @@ pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000
```
-## Usage with OpenAI SDK
+Server starts in ~20s (model loading). Health check: `GET /health`
+
+## Usage with OpenAI SDK (Python)
```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
+# Basic transcription
result = client.audio.transcriptions.create(
- model="sensevoice", # or "paraformer", "fun-asr-nano"
+ model="sensevoice", # or "paraformer", "paraformer-en", "fun-asr-nano"
file=open("meeting.wav", "rb"),
)
print(result.text)
+
+# With timestamps/segments
+result = client.audio.transcriptions.create(
+ model="sensevoice",
+ file=open("meeting.wav", "rb"),
+ response_format="verbose_json",
+)
+# Returns: text, segments (with start/end/speaker), duration
```
## Usage with curl
@@ -29,22 +40,65 @@ print(result.text)
curl http://localhost:8000/v1/audio/transcriptions \
-F model=sensevoice
+
+# With verbose output
+curl http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
```
## Available Models
-| Model | Speed | Languages | Features |
-|-------|-------|-----------|----------|
-| `sensevoice` | 170x realtime | 5 | Emotion detection |
-| `paraformer` | 120x realtime | zh/en | Punctuation, streaming |
-| `fun-asr-nano` | 17x realtime | 31 | LLM-based, timestamps |
+| Model | Speed (GPU) | Speed (CPU) | Languages | Features |
+|-------|-------------|-------------|-----------|----------|
+| `sensevoice` | 170x realtime | 17x realtime | zh/en/ja/ko/yue | Emotion detection |
+| `paraformer` | 120x realtime | 15x realtime | zh/en | Punctuation |
+| `paraformer-en` | 120x realtime | 15x realtime | en | English only |
+| `fun-asr-nano` | 17x realtime | 3.6x realtime | 31 languages | LLM-based, timestamps |
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/audio/transcriptions` | POST | Transcribe audio (OpenAI-compatible) |
+| `/v1/models` | GET | List available models |
+| `/health` | GET | Health check + loaded models |
+| `/docs` | GET | Interactive API documentation (Swagger) |
## Agent Framework Integration
-Works with: LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel, or any framework supporting OpenAI audio API.
+Works with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, or any framework using OpenAI audio API.
+### LangChain Example
```python
-# LangChain example
-from langchain_openai import ChatOpenAI
-# Just point your audio transcription to localhost:8000
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8000/v1", api_key="x")
+
+def transcribe_for_agent(audio_path: str) -> str:
+ """Tool function for LangChain agent."""
+ result = client.audio.transcriptions.create(
+ model="sensevoice", file=open(audio_path, "rb")
+ )
+ return result.text
+```
+
+## Docker Deployment
+
+```bash
+# Build
+docker build -t funasr-api .
+
+# Run with GPU
+docker run --gpus all -p 8000:8000 funasr-api
```
+
+## Configuration
+
+| Arg | Default | Description |
+|-----|---------|-------------|
+| `--host` | 0.0.0.0 | Bind address |
+| `--port` | 8000 | Port |
+| `--device` | cuda | Device (cuda/cpu/mps) |
+| `--model` | sensevoice | Pre-load model at startup |
diff --git a/examples/openai_api/server.py b/examples/openai_api/server.py
index 75616784a..47a324c53 100644
--- a/examples/openai_api/server.py
+++ b/examples/openai_api/server.py
@@ -16,63 +16,101 @@ import argparse
import tempfile
import time
import os
+import re
+import logging
from typing import Optional
import uvicorn
-from fastapi import FastAPI, UploadFile, File, Form
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
from fastapi.responses import JSONResponse
-app = FastAPI(title="FunASR OpenAI-Compatible API")
-
-MODEL_REGISTRY = {}
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+app = FastAPI(title="FunASR OpenAI-Compatible API", version="1.0.0")
-def get_model(model_name: str):
+MODEL_REGISTRY = {}
+DEVICE = "cpu"
+
+MODEL_CONFIGS = {
+ "sensevoice": {
+ "model": "iic/SenseVoiceSmall",
+ "vad_model": "fsmn-vad",
+ "vad_kwargs": {"max_single_segment_time": 30000},
+ },
+ "paraformer": {
+ "model": "paraformer-zh",
+ "vad_model": "fsmn-vad",
+ "punc_model": "ct-punc",
+ },
+ "paraformer-en": {
+ "model": "paraformer-en",
+ "vad_model": "fsmn-vad",
+ },
+ "fun-asr-nano": {
+ "model": "FunAudioLLM/Fun-ASR-Nano-2512",
+ "hub": "hf",
+ "trust_remote_code": True,
+ "vad_model": "fsmn-vad",
+ "vad_kwargs": {"max_single_segment_time": 30000},
+ },
+}
+
+
+def load_model(model_name: str):
+ """Load a model and store in registry."""
if model_name in MODEL_REGISTRY:
return MODEL_REGISTRY[model_name]
- from funasr import AutoModel
-
- configs = {
- "sensevoice": {
- "model": "iic/SenseVoiceSmall",
- "vad_model": "fsmn-vad",
- "vad_kwargs": {"max_single_segment_time": 30000},
- },
- "paraformer": {
- "model": "paraformer-zh",
- "vad_model": "fsmn-vad",
- "punc_model": "ct-punc",
- },
- "fun-asr-nano": {
- "model": "FunAudioLLM/Fun-ASR-Nano-2512",
- "hub": "hf",
- "trust_remote_code": True,
- "vad_model": "fsmn-vad",
- "vad_kwargs": {"max_single_segment_time": 30000},
- },
- }
+ if model_name not in MODEL_CONFIGS:
+ available = list(MODEL_CONFIGS.keys())
+ raise ValueError(f"Unknown model '{model_name}'. Available: {available}")
- if model_name not in configs:
- model_name = "sensevoice"
+ from funasr import AutoModel
- cfg = configs[model_name]
- cfg["device"] = app.state.device
+ cfg = MODEL_CONFIGS[model_name].copy()
+ cfg["device"] = DEVICE
cfg["disable_update"] = True
+
+ logger.info(f"Loading model '{model_name}' on {DEVICE}...")
+ t0 = time.time()
model = AutoModel(**cfg)
+ elapsed = time.time() - t0
+ logger.info(f"Model '{model_name}' loaded in {elapsed:.1f}s")
+
MODEL_REGISTRY[model_name] = model
return model
+def clean_text(text: str) -> str:
+ """Remove SenseVoice special tags from output."""
+ return re.sub(r'<\|[^|]*\|>', '', text).strip()
+
+
@app.post("/v1/audio/transcriptions")
async def transcribe(
file: UploadFile = File(...),
model: str = Form(default="sensevoice"),
language: Optional[str] = Form(default=None),
response_format: Optional[str] = Form(default="json"),
- timestamp_granularities: Optional[str] = Form(default=None),
):
- """OpenAI-compatible audio transcription endpoint."""
+ """
+ OpenAI-compatible audio transcription endpoint.
+
+ Accepts the same parameters as OpenAI's /v1/audio/transcriptions:
+ - file: Audio file (wav, mp3, flac, m4a, ogg, webm)
+ - model: Model to use (sensevoice, paraformer, fun-asr-nano)
+ - language: Optional language hint
+ - response_format: json or verbose_json
+ """
+ # Validate model
+ if model not in MODEL_CONFIGS:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Model '{model}' not found. Available: {list(MODEL_CONFIGS.keys())}"
+ )
+
+ # Save uploaded file
suffix = os.path.splitext(file.filename)[1] if file.filename else ".wav"
with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
content = await file.read()
@@ -80,21 +118,17 @@ async def transcribe(
tmp_path = tmp.name
try:
- asr_model = get_model(model)
+ asr_model = load_model(model)
t0 = time.time()
- kwargs = {"input": tmp_path, "batch_size": 1}
+ generate_kwargs = {"input": tmp_path, "batch_size": 1}
if language:
- kwargs["language"] = language
+ generate_kwargs["language"] = language
- result = asr_model.generate(**kwargs)
+ result = asr_model.generate(**generate_kwargs)
elapsed = time.time() - t0
- text = result[0]["text"]
-
- # Strip SenseVoice tags if present
- import re
- text = re.sub(r'<\|[^|]*\|>', '', text).strip()
+ text = clean_text(result[0]["text"])
if response_format == "verbose_json":
segments = []
@@ -103,48 +137,72 @@ async def transcribe(
segments.append({
"start": seg.get("start", 0) / 1000.0,
"end": seg.get("end", 0) / 1000.0,
- "text": seg.get("text", ""),
+ "text": clean_text(seg.get("text", "")),
"speaker": seg.get("spk", None),
})
return JSONResponse({
"text": text,
"segments": segments,
"language": language or "auto",
- "duration": elapsed,
+ "duration": round(elapsed, 3),
+ "model": model,
})
else:
return JSONResponse({"text": text})
+ except Exception as e:
+ logger.error(f"Transcription error: {e}")
+ raise HTTPException(status_code=500, detail=str(e))
finally:
os.unlink(tmp_path)
@app.get("/v1/models")
async def list_models():
- """List available models."""
- return JSONResponse({
- "data": [
- {"id": "sensevoice", "object": "model", "owned_by": "funasr"},
- {"id": "paraformer", "object": "model", "owned_by": "funasr"},
- {"id": "fun-asr-nano", "object": "model", "owned_by": "funasr"},
- ]
- })
+ """List available models (OpenAI-compatible)."""
+ models = []
+ for name in MODEL_CONFIGS:
+ models.append({
+ "id": name,
+ "object": "model",
+ "created": 1700000000,
+ "owned_by": "funasr",
+ "ready": name in MODEL_REGISTRY,
+ })
+ return JSONResponse({"object": "list", "data": models})
@app.get("/health")
async def health():
- return {"status": "ok", "models_loaded": list(MODEL_REGISTRY.keys())}
+ """Health check endpoint."""
+ return {
+ "status": "ok",
+ "device": DEVICE,
+ "models_loaded": list(MODEL_REGISTRY.keys()),
+ "models_available": list(MODEL_CONFIGS.keys()),
+ }
-if __name__ == "__main__":
- parser = argparse.ArgumentParser()
- parser.add_argument("--host", default="0.0.0.0")
- parser.add_argument("--port", type=int, default=8000)
- parser.add_argument("--device", default="cuda")
- parser.add_argument("--model", default="sensevoice", help="Pre-load model")
+def main():
+ parser = argparse.ArgumentParser(description="FunASR OpenAI-Compatible API Server")
+ parser.add_argument("--host", default="0.0.0.0", help="Bind host")
+ parser.add_argument("--port", type=int, default=8000, help="Bind port")
+ parser.add_argument("--device", default="cuda", help="Device: cuda, cpu, mps")
+ parser.add_argument("--model", default="sensevoice", help="Pre-load model at startup")
args = parser.parse_args()
- app.state.device = args.device
- get_model(args.model)
- print(f"FunASR API server ready on {args.host}:{args.port}")
+ global DEVICE
+ DEVICE = args.device
+
+ # Pre-load default model
+ load_model(args.model)
+
+ logger.info(f"FunASR API server starting on http://{args.host}:{args.port}")
+ logger.info(f" Device: {DEVICE}")
+ logger.info(f" Models: {list(MODEL_CONFIGS.keys())}")
+ logger.info(f" Docs: http://{args.host}:{args.port}/docs")
uvicorn.run(app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+ main()