Skip to content

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

feat: WebSocket SPK as client-controlled param (SPK:true/false, default off)

游雁7d3c2161dba1
diff --git a/docs/vllm_guide.md b/docs/vllm_guide.md
index ff850a088..e69de29bb 100644
--- a/docs/vllm_guide.md
+++ b/docs/vllm_guide.md
@@ -1,504 +0,0 @@
-# FunASR vLLM 推理引擎指南
-
----
-
-## Benchmark
-
-**测试集**:184 文件,11541 秒,Fun-ASR-Nano / GLM-ASR-Nano。
-
-| 模型 | 引擎 | VAD | RTFx | CER | 备注 |
-|------|------|-----|------|-----|------|
-| Fun-ASR-Nano | PyTorch | dynamic | 21 | 8.06% | 基准 |
-| Fun-ASR-Nano | **vLLM batch** | dynamic | **340** | **8.20%** | 16x 加速 |
-| Fun-ASR-Nano | **离线服务 (no SPK)** | dynamic | **102** | 8.14% | |
-| Fun-ASR-Nano | **离线服务 (+SPK)** | dynamic | **46** | 8.19% | SPK 默认关闭 |
-| GLM-ASR-Nano | **vLLM batch** | fixed | **265** | 12.93% | 不支持长音频推理 |
-
-> vLLM 与 PyTorch CER 完全一致(差 < 0.2%),速度提升 16-340x。
-
----
-
-## 目录
-
-1. [安装与环境](#1-安装与环境)
-2. [vLLM 推理引擎架构](#2-vllm-推理引擎架构)
-3. [离线语音识别服务](#3-离线语音识别服务)
-4. [流式语音识别服务](#4-流式语音识别服务)
-5. [动态 VAD](#5-动态-vad)
-6. [API 参考](#6-api-参考)
-7. [FAQ](#7-faq)
-
----
-
-## 1. 安装与环境
-
-```bash
-pip install funasr>=1.3.0
-pip install vllm>=0.12.0
-pip install safetensors tiktoken websockets regex fastapi uvicorn python-multipart
-
-cd /path/to/FunASR && pip install -e .
-```
-
-**硬件**:GPU ≥ 8GB VRAM,CUDA ≥ 11.8。推荐 16GB+。
-
----
-
-## 2. vLLM 推理引擎架构
-
-### 整体架构
-
-FunASR 的 vLLM 集成将 ASR 模型拆分为两部分独立运行:
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│ FunASR + vLLM 推理架构 │
-├──────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────── PyTorch (单 GPU) ───────────────┐ │
-│ │ │ │
-│ │ Audio ──→ Frontend ──→ Audio Encoder ──→ Adaptor │
-│ │ (fbank) (SenseVoice/ (Transformer/ │
-│ │ Whisper) MLP) │
-│ │ │ │
-│ │ ▼ │
-│ │ Audio Embeddings │
-│ │ │ │
-│ │ Text Prompt ──→ Tokenize ──→ Embed │
-│ │ (system/user/ │ │
-│ │ hotwords/language) │ │
-│ │ ▼ │
-│ │ [Concat Embeddings] │
-│ └─────────────────────────────────┼─────────────┘ │
-│ │ │
-│ ▼ EmbedsPrompt │
-│ ┌─────────────── vLLM Engine ────────────────────┐ │
-│ │ │ │
-│ │ PagedAttention + Continuous Batching │ │
-│ │ KV Cache 管理 + CUDA Graph │ │
-│ │ Tensor Parallel (多卡) │ │
-│ │ │ │
-│ │ Qwen3-0.6B / Llama-2B (LLM 解码) │ │
-│ │ │ │
-│ └────────────────────┬───────────────────────────┘ │
-│ │ │
-│ ▼ │
-│ Generated Text │
-│ │ │
-│ ┌────────────────────┼──────────────────────────┐ │
-│ │ (可选) CTC Decoder ──→ Forced Alignment │ │
-│ │ ──→ 字级别时间戳 │ │
-│ └───────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────────┘
-```
-
-### 为什么用 vLLM?
-
-| 特性 | PyTorch generate() | vLLM |
-|------|-------------------|------|
-| KV Cache 管理 | 固定分配,浪费显存 | PagedAttention,按需分配 |
-| 批处理 | 需手动 padding | Continuous Batching,自动调度 |
-| CUDA 优化 | 无 | CUDA Graph + 算子融合 |
-| 多卡并行 | 手动实现 | Tensor Parallel 一行配置 |
-| 吞吐量 | RTFx ~20 | **RTFx 340+** |
-
-### 支持模型
-
-| 模型 | LLM 部分 | audio encoder | vLLM 加速 |
-|------|---------|---------------|-----------|
-| **Fun-ASR-Nano** | Qwen3-0.6B | SenseVoice | ✓ 21.7x |
-| **GLM-ASR-Nano** | Llama-2B | Whisper-like | ✓ 7.6x |
-| LLMASR | Qwen/Vicuna | Whisper | ✓ |
-| Paraformer | 无 LLM | — | ✗ 非自回归 |
-| SenseVoice | 无 LLM | — | ✗ encoder-decoder |
-
-### 关键实现细节
-
-1. **权重分离**:从 `model.pt` 提取 LLM 权重,转为 HuggingFace 格式供 vLLM 加载
-2. **EmbedsPrompt**:音频 embedding + 文本 embedding 拼接后作为 prompt embedding 送入 vLLM
-3. **use_low_frame_rate**:Fun-ASR-Nano 的 adaptor 输出需按公式截断到正确 token 数(一致性关键)
-4. **batch encode**:多条音频通过 `extract_fbank` → `audio_encoder` → `audio_adaptor` 一次前向
-5. **CTC 时间戳**:保留 encoder_out,生成文本后做 forced alignment 得到字级别时间
-
----
-
-## 3. 离线语音识别服务
-
-### 3.1 服务架构
-
-```
-客户端 serve_vllm.py
- │ │
- │── HTTP/OpenAI/WebSocket ──────────────→│
- │ │
- │ ┌────┴────────────────────────┐
- │ │ 1. 接收完整音频文件 │
- │ │ 2. 动态 VAD 分段(≤60s/段) │
- │ │ 3. vLLM batch 推理所有段 │
- │ │ 4. CTC 时间戳(逐字) │
- │ │ 5. 说话人分离(可选) │
- │ └────┬────────────────────────┘
- │ │
- │←── JSON 结果 ─────────────────────────│
-```
-
-**特点**:
-- 音频完整到达后处理,适合文件转写
-- 动态 VAD 保留长段(≤60s),减少边界切割损失
-- batch 推理所有 VAD 段,吞吐量高
-- 自动输出字级别时间戳
-- SPK 说话人分离默认关闭,客户端可开启
-
-### 3.2 启动服务
-
-```bash
-CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_vllm.py \
- --port 8899 \
- --model FunAudioLLM/Fun-ASR-Nano-2512 \
- --gpu-memory-utilization 0.5
-```
-
-### 3.3 协议一:HTTP REST — `POST /asr`
-
-功能最全的接口,支持 SPK、时间戳、热词。
-
-**请求**:`multipart/form-data`
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `file` | file | 必填 | 音频文件(wav/mp3/flac) |
-| `language` | string | None | 语种("中文"/"English"/...),None 为自动 |
-| `hotwords` | string | "" | 热词,逗号分隔 |
-| `spk` | bool | false | 是否开启说话人分离 |
-| `timestamp` | bool | true | 是否输出字级别时间戳 |
-
-**响应**:
-
-```json
-{
- "text": "完整识别文本",
- "segments": [
- {
- "text": "段文本",
- "start": 1.7,
- "end": 14.8,
- "speaker": "SPK0",
- "words": [
- {"word": "砸", "start": 2.02, "end": 2.08},
- {"word": "了", "start": 2.26, "end": 2.32}
- ]
- }
- ],
- "duration": 227.4,
- "processing_time": 3.422,
- "rtf": 0.015
-}
-```
-
-**客户端示例**:
-
-```bash
-# cURL
-curl -X POST http://localhost:8899/asr \
- -F "[email protected]" -F "language=中文" -F "spk=true"
-```
-
-```python
-# Python requests
-import requests
-resp = requests.post("http://localhost:8899/asr",
- files={"file": open("audio.wav", "rb")},
- data={"language": "中文", "spk": "true"})
-result = resp.json()
-```
-
-```javascript
-// JavaScript fetch
-const form = new FormData();
-form.append("file", audioBlob, "audio.wav");
-form.append("language", "中文");
-form.append("spk", "true");
-const resp = await fetch("http://localhost:8899/asr", { method: "POST", body: form });
-const result = await resp.json();
-```
-
-### 3.4 协议二:OpenAI Whisper 兼容 — `POST /v1/audio/transcriptions`
-
-兼容 OpenAI Whisper API 标准,可直接用 OpenAI SDK 接入。
-
-**请求**:`multipart/form-data`
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `file` | file | 必填 | 音频文件 |
-| `model` | string | "fun-asr-nano" | 模型名(兼容字段) |
-| `language` | string | None | 语种 |
-| `response_format` | string | "json" | "json" / "text" / "verbose_json" |
-| `timestamp_granularities` | string | "word" | "word" / "segment" |
-| `spk` | bool | false | 说话人分离(FunASR 扩展字段) |
-
-**响应**(`verbose_json`):
-
-```json
-{
- "task": "transcribe",
- "language": "zh",
- "duration": 5.17,
- "text": "我一直没有照顾孩子,但是我想要抚养权。",
- "segments": [
- {
- "id": 0, "start": 0.0, "end": 5.15,
- "text": "我一直没有照顾孩子,但是我想要抚养权。",
- "words": [{"word": "我", "start": 0.42, "end": 0.48}, ...]
- }
- ]
-}
-```
-
-**客户端示例**:
-
-```python
-# OpenAI SDK(推荐)
-from openai import OpenAI
-client = OpenAI(base_url="http://localhost:8899/v1", api_key="none")
-result = client.audio.transcriptions.create(
- model="fun-asr-nano",
- file=open("audio.wav", "rb"),
- response_format="verbose_json",
-)
-print(result.text)
-```
-
-```bash
-# cURL
-curl -X POST http://localhost:8899/v1/audio/transcriptions \
- -F "[email protected]" -F "model=fun-asr-nano" -F "response_format=verbose_json"
-```
-
-### 3.5 协议三:WebSocket — `ws://host:port/ws`
-
-
-离线服务的 WebSocket 接口,发送完整音频后获取结果。STOP 时自动进行说话人聚类,结果中包含 `spk` 字段。
-
-**客户端 → 服务端**:
-
-| 消息 | 说明 |
-|------|------|
-| `"START"` | 开始会话 |
-| `"LANGUAGE:中文"` | 设置语种(可选) |
-| `"HOTWORDS:词1,词2"` | 设置热词(可选) |
-| `[binary]` | PCM16 16kHz mono 音频数据 |
-| `"STOP"` | 结束,请求识别结果 |
-
-**服务端 → 客户端**:
-
-```json
-{"event": "started"}
-{"event": "language_set", "language": "中文"}
-{"sentences": [{"text":"...","start":..,"end":..}], "is_final": true, "duration_ms": 5170}
-{"event": "stopped"}
-```
-
-**客户端示例**:
-
-```python
-import asyncio, websockets, json, numpy as np, soundfile as sf
-
-async def offline_ws(audio_path):
- audio, sr = sf.read(audio_path)
- pcm = (audio * 32768).astype(np.int16)
-
- async with websockets.connect("ws://localhost:8899/ws") as ws:
- await ws.send("START")
- await ws.recv()
- await ws.send("LANGUAGE:中文")
- await ws.recv()
-
- # 发送完整音频
- await ws.send(pcm.tobytes())
- await ws.send("STOP")
-
- # 接收结果
- async for msg in ws:
- data = json.loads(msg)
- if data.get("is_final"):
- for s in data["sentences"]:
- print(f"[{s['start']/1000:.1f}s] {s['text']}")
- break
-
-asyncio.run(offline_ws("audio.wav"))
-```
-
----
-
-## 4. 流式语音识别服务
-
-### 4.1 服务架构
-
-```
-客户端(麦克风/音频流) serve_realtime_ws.py
- │ │
- │── WebSocket PCM16 16kHz ────────────→│
- │ (每帧 ~100ms,持续发送) │
- │ │
- │ ┌────┴─────────────────────────┐
- │ │ 实时循环: │
- │ │ ├─ 动态 VAD(60ms chunk) │
- │ │ ├─ 检测到端点 → vLLM 解码 │
- │ │ ├─ 未结束 → partial 预览 │
- │ │ └─ 说话人流式分配 │
- │ └────┬─────────────────────────┘
- │ │
- │←── JSON 实时推送 ───────────────────│
-```
-
-**特点**:
-- 音频逐帧到达,边收边处理
-- 基于 VAD 端点自然分句
-- 确认段文字锁定不变,partial 实时更新
-- 流式说话人分配 + STOP 时全局重聚类
-- 首字延迟 ~480ms
-
-### 4.2 启动服务
-
-```bash
-CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \
- --port 10095 --language 中文 --hotword-file 热词列表
-```
-
-### 4.3 WebSocket 协议
-
-**连接**:`ws://host:10095`
-
-**客户端 → 服务端**:
-
-| 消息 | 格式 | 说明 |
-|------|------|------|
-| 开始 | `"START"` | 初始化 session |
-| 热词 | `"HOTWORDS:词1,词2"` | 可选 |
-| 语种 | `"LANGUAGE:中文"` | 可选 |
-| 音频 | `binary` | PCM16 16kHz mono |
-| 结束 | `"STOP"` | 最终解码 + SPK 重聚类 |
-
-**服务端 → 客户端**:
-
-```json
-{"event": "started"}
-{"sentences": [{"text":"你好","start":300,"end":1200,"spk":0}], "partial": "世界", "is_final": false}
-{"sentences": [...], "is_final": true}
-{"event": "stopped"}
-```
-
-**字段**:`sentences[]` = 已锁定,`partial` = 正在说(会变),`is_final` = STOP 后为 true。
-
-**时序**:
-```
-Client Server
- │── START ───────→│
- │←─ started ──────│
- │── [audio] ─────→│
- │←─ {partial} ────│
- │── [audio] ─────→│
- │←─ {sentences+partial} ─│ (VAD 切了一句)
- │── STOP ────────→│
- │←─ {is_final:true} ────│
- │←─ stopped ─────│
-```
-
-### 4.4 客户端调用
-
-**Python CLI**:
-```bash
-python client_python.py --server ws://localhost:10095 --mic
-python client_python.py --server ws://localhost:10095 --file audio.wav
-```
-
-**浏览器**:打开 `client_mic.html`
-
-**自定义 Python**:
-```python
-import asyncio, websockets, numpy as np, json
-
-async def stream(audio_path):
- import soundfile as sf
- audio, sr = sf.read(audio_path)
- pcm = (audio * 32768).astype(np.int16)
-
- async with websockets.connect("ws://localhost:10095") as ws:
- await ws.send("START")
- await ws.recv()
-
- for i in range(0, len(pcm), 1600):
- await ws.send(pcm[i:i+1600].tobytes())
- await asyncio.sleep(0.05)
-
- await ws.send("STOP")
- async for msg in ws:
- data = json.loads(msg)
- if data.get("is_final"):
- for s in data["sentences"]:
- print(f"[{s['start']/1000:.1f}s] {s['text']}")
- break
-
-asyncio.run(stream("audio.wav"))
-```
-
----
-
-## 5. 动态 VAD
-
-fsmn-vad 默认启用动态静音阈值。离线和流式使用不同配置。
-
-| 累积时长 | 离线(保留长段 ≤60s) | 流式(平衡延迟) |
-|---------|-------------------|----------------|
-| ≤ 5s | 2000ms | 2000ms |
-| 5-10s | 2000ms | 1500ms |
-| 10-15s | 1000ms | 1000ms |
-| 15-20s | 1000ms | 800ms |
-| 20-30s | 800ms | 800ms |
-| 30-45s | 600ms | 400ms |
-| 45-60s | 200-400ms | 100ms |
-| > 60s | 100ms | 100ms |
-
-离线倾向保留长段减少边界损失;流式更快收紧以降低延迟。
-
-### 自定义
-
-```python
-model.generate(input="audio.wav", silence_schedule=[(5000,1500), (20000,800), (float('inf'),300)])
-```
-
-> GLM-ASR 不支持长段,使用时传 `dynamic_silence=False`。
-
----
-
-## 6. API 参考
-
-| 参数 | AutoModelVLLM | serve_vllm.py | serve_realtime_ws.py |
-|------|--------------|---------------|---------------------|
-| model | ✓ | --model | --model |
-| gpu_memory_utilization | ✓ | --gpu-memory-utilization | --gpu-memory-utilization |
-| tensor_parallel_size | ✓ | — | --tensor-parallel-size |
-| max_model_len | ✓ | --max-model-len | --max-model-len |
-| language | generate() 参数 | API 参数 | --language / LANGUAGE: |
-| hotwords | generate() 参数 | API 参数 | --hotword-file / HOTWORDS: |
-
----
-
-## 7. FAQ
-
-**Q: 离线还是流式?**
-完整文件 → 离线(高吞吐)。麦克风/直播 → 流式(低延迟)。
-
-**Q: GLM-ASR 用动态 VAD?**
-不支持长段推理,用 `dynamic_silence=False`。
-
-**Q: SPK 性能影响?**
-RTFx 102 → 46。CER 不变。默认关闭。
-
-**Q: 二次开发入口?**
-离线:`serve_vllm.process_audio()` / `FunASRNanoVLLM.generate()`
-流式:`serve_realtime_ws.RealtimeASRSession`
-
-**Q: 首次慢?**
-vLLM 初始化 60-90s,之后即时。
diff --git a/examples/industrial_data_pretraining/fun_asr_nano/serve_vllm.py b/examples/industrial_data_pretraining/fun_asr_nano/serve_vllm.py
index 0d9e9a033..1d4bd2db6 100644
--- a/examples/industrial_data_pretraining/fun_asr_nano/serve_vllm.py
+++ b/examples/industrial_data_pretraining/fun_asr_nano/serve_vllm.py
@@ -254,6 +254,7 @@ async def websocket_endpoint(websocket: WebSocket):
locked_sentences = []
language = None
hotwords = None
+ use_spk = False
is_active = False
try:
@@ -274,6 +275,9 @@ async def websocket_endpoint(websocket: WebSocket):
elif cmd.upper().startswith("HOTWORDS:"):
hotwords = [w.strip() for w in cmd[9:].split(",") if w.strip()]
await websocket.send_json({"event": "hotwords_set", "hotwords": hotwords})
+ elif cmd.upper().startswith("SPK:"):
+ use_spk = cmd[4:].strip().lower() in ("true", "1", "on", "yes")
+ await websocket.send_json({"event": "spk_set", "spk": use_spk})
elif cmd.upper() == "STOP":
if is_active and len(audio_buffer) > 0:
# Final: process remaining audio
@@ -305,8 +309,8 @@ async def websocket_endpoint(websocket: WebSocket):
"text": res[0]["text"], "start": start_ms, "end": end_ms
})
- # SPK: run full clustering on all sentences
- if locked_sentences and _spk_model is not None:
+ # SPK: run full clustering on all sentences (only if enabled)
+ if use_spk and locked_sentences and _spk_model is not None:
try:
from funasr.models.campplus.utils import sv_chunk, postprocess, distribute_spk
from funasr.models.campplus.cluster_backend import ClusterBackend