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
docs: add vllm_guide_zh_v2.md — merged batch inference + streaming SDK into service guide
游雁8ca7fb2b8c07
diff --git a/docs/vllm_guide_zh_v2.md b/docs/vllm_guide_zh_v2.mdnew file mode 100644index 000000000..f4f0ffc2c--- /dev/null+++ b/docs/vllm_guide_zh_v2.md@@ -0,0 +1,619 @@+# 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. [流式 SDK 推理](#4-流式-sdk-推理)+5. [离线语音识别服务](#5-离线语音识别服务)+6. [流式语音识别服务](#6-流式语音识别服务)+7. [动态 VAD](#7-动态-vad)+8. [API 参考](#8-api-参考)+9. [FAQ](#9-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. 离线批量推理++适用于大规模音频转写、离线批量处理。vLLM 的批处理能力在此场景优势最大。++### 通用接口(推荐)++```python+from funasr.auto.auto_model_vllm import AutoModelVLLM++model = AutoModelVLLM(+ model="FunAudioLLM/Fun-ASR-Nano-2512",+ hub="ms", # 或 "hf"+ tensor_parallel_size=2, # 多卡并行+ gpu_memory_utilization=0.8,+)++results = model.generate(+ ["audio1.wav", "audio2.wav"],+ language="中文",+ hotwords=["张三", "北京"],+)+for r in results:+ print(f"[{r['key']}] {r['text']}")+```++### 直接接口++```python+from funasr.models.fun_asr_nano.inference_vllm import FunASRNanoVLLM++engine = FunASRNanoVLLM.from_pretrained(+ model="FunAudioLLM/Fun-ASR-Nano-2512",+ tensor_parallel_size=4,+)++results = engine.generate(+ inputs="wav.scp", # 支持 scp/jsonl/文件列表+ hotwords=["开放时间"],+ language="中文",+ max_new_tokens=512,+)+```++### 命令行++```bash+cd examples/industrial_data_pretraining/fun_asr_nano++# 单文件+python demo_vllm.py --input audio.wav --language 中文++# 批量 + 多卡+python demo_vllm.py --input wav.scp --tensor-parallel-size 4 --batch-size 32++# 带热词 + 保存结果+python demo_vllm.py --input audio.wav --hotwords 张三 北京 --output results.jsonl+```++---++## 4. 流式 SDK 推理++将音频按 720ms chunk 逐步处理,输出逐步稳定的识别结果。适用于 SDK 集成实时字幕场景。++### 设计原理++```+音频流(720ms chunks)+ │ 累积重编码(每个 chunk 包含从头到当前的全部音频)+ ▼+┌──────────────────────┐+│ Stage 1: 前 10 chunk │ ← 无 prev_text,批量生成+│ 找到稳定输出 │+└──────────┬───────────┘+ ▼+┌──────────────────────┐+│ Stage 2: 后续 chunk │ ← 用稳定输出作 prev_text+└──────────┬───────────┘+ ▼+每个 chunk: [fixed 区域(确认)] + [8字 unfixed(可能变)]+```++### 用法++```python+from funasr.models.fun_asr_nano.inference_vllm_streaming import FunASRNanoStreamingVLLM++engine = FunASRNanoStreamingVLLM.from_pretrained(+ model="FunAudioLLM/Fun-ASR-Nano-2512",+ chunk_ms=720,+ rollback_chars=8,+)++for result in engine.streaming_generate("audio.wav", language="中文"):+ if result["is_final"]:+ print(f"最终: {result['text']}")+ else:+ print(f"[{result['audio_duration_ms']:.0f}ms] 确认: {result['fixed_text']}")+```++### 输出特性++| 累积音频 | 输出质量 |+|---------|---------|+| < 1.5s | 空或噪声 |+| 1.5-3.0s | 部分正确 |+| > 3.0s | 准确输出 |++> Note: `repetition_penalty=1.3` 内部硬编码,防止短 chunk 重复退化。++---++## 5. 离线语音识别服务++### 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"))+```++---++## 6. 流式语音识别服务++### 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"))+```++---++## 7. 动态 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`。++---++## 8. 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: |++---++## 9. 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,之后即时。