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: rename to '离线 SDK 推理' + add design principles, sync zh/en/v2
游雁0f780ce592fd
diff --git a/docs/vllm_guide.md b/docs/vllm_guide.mdindex 925f8256a..6c65c028c 100644--- a/docs/vllm_guide.md+++ b/docs/vllm_guide.md@@ -1,6 +1,6 @@# FunASR vLLM Inference Engine Guide-FunASR integrates the vLLM high-throughput inference engine to accelerate autoregressive decoding of LLM-based ASR models. Three modes are supported: offline batch inference, streaming SDK inference, and production-grade WebSocket real-time service.+FunASR integrates the vLLM high-throughput inference engine to accelerate autoregressive decoding of LLM-based ASR models. Three modes are supported: offline SDK inference, streaming SDK inference, and production-grade WebSocket real-time service.---@@ -8,7 +8,7 @@ FunASR integrates the vLLM high-throughput inference engine to accelerate autore1. [Overview](#1-overview)2. [Installation & Environment](#2-installation--environment)-3. [Offline Batch Inference](#3-offline-batch-inference)+3. [Offline SDK Inference](#3-offline-sdk-inference)4. [Streaming SDK Inference](#4-streaming-sdk-inference)5. [Real-time WebSocket Service](#5-real-time-websocket-service)6. [Performance Comparison](#6-performance-comparison)@@ -64,7 +64,7 @@ FunASR integrates the vLLM high-throughput inference engine to accelerate autore| Mode | Entry Point | Use Case ||------|-------------|----------|-| [Offline Batch Inference](#3-offline-batch-inference) | `AutoModelVLLM` / `FunASRNanoVLLM` | Large-scale transcription, batch processing |+| [Offline SDK Inference](#3-offline-sdk-inference) | `AutoModelVLLM` / `FunASRNanoVLLM` | Large-scale transcription, batch processing || [Streaming SDK Inference](#4-streaming-sdk-inference) | `FunASRNanoStreamingVLLM` | Real-time subtitles (SDK integration) || [WebSocket Real-time Service](#5-real-time-websocket-service) | `serve_realtime_ws.py` | Production deployment, multi-client access |@@ -93,10 +93,76 @@ cd /path/to/FunASR && pip install -e .----## 3. Offline Batch Inference+## 3. Offline SDK InferenceBest for large-scale audio transcription and offline batch processing. vLLM's batching capability provides the greatest advantage in this scenario.+### Design Principles++The offline SDK inference splits the ASR pipeline into two stages executed independently:++```+┌─────────────────────────────────────────────────────────────────────┐+│ Stage 1: Audio Encoding (PyTorch, single GPU) │+├─────────────────────────────────────────────────────────────────────┤+│ │+│ Audio file list ──→ Group (batch=8) ──→ Frontend (Fbank) │+│ │ │ │+│ │ ▼ │+│ │ SenseVoice Encoder │+│ │ │ │+│ │ ▼ │+│ │ Audio Adaptor │+│ │ (dim transform + LFR truncation)│+│ │ │ │+│ └─── Shared text prompt encoding ─┐ ▼ │+│ (system/hotwords/language) │ audio_embeds │+│ │ │ │ │+│ ▼ │ ▼ │+│ prefix_emb ──→ [concat: prefix | audio | suffix] │+│ │ │+│ ▼ │+│ EmbedsPrompt (N samples) │+└──────────────────────────────────────────────┼─────────────────────┘+ │+ ▼+┌─────────────────────────────────────────────────────────────────────┐+│ Stage 2: LLM Decoding (vLLM, multi-GPU Tensor Parallel) │+├─────────────────────────────────────────────────────────────────────┤+│ │+│ EmbedsPrompt × N ──→ vLLM Continuous Batching │+│ (PagedAttention + CUDA Graph) │+│ │ │+│ ▼ │+│ Generated token_ids × N │+│ │ │+│ ▼ │+│ Decode + post-processing (clean special tokens) │+│ │ │+│ ▼ │+│ (Optional) CTC Forced Alignment → char timestamps│+└─────────────────────────────────────────────────────────────────────┘+```++**Key design decisions:**++1. **Weight separation**: On first run, extracts `llm.*` prefixed weights from `model.pt` and saves them in HuggingFace safetensors format for vLLM (cached in `Qwen3-0.6B-vllm/` directory)+2. **Embedding concatenation**: Text prompt is encoded via the LLM's `embed_tokens` layer, then concatenated with audio adaptor output along the sequence dimension: `[prefix_emb | audio_emb | suffix_emb]`, submitted to vLLM as `EmbedsPrompt`+3. **Low Frame Rate truncation**: Adaptor output is truncated to the correct length using: `fake_token_len = ((((fbank_len - 3 + 2) // 2 - 3 + 2) // 2) - 1) // 2 + 1`, ensuring consistency with PyTorch training+4. **Batch audio encoding**: Multiple audio files are grouped (batch_size=8) through encoder + adaptor forward pass, reducing GPU kernel launch overhead+5. **Shared text prompt**: When hotwords/language are the same within a batch, prefix_emb and suffix_emb are computed only once+6. **CTC timestamps**: Encoder output is preserved; after LLM generates text, forced alignment produces character-level timestamps++**Why faster than PyTorch generate()?**++| Dimension | PyTorch | vLLM |+|-----------|---------|------|+| KV Cache | Fixed pre-allocation (wastes memory) | PagedAttention on-demand allocation |+| Batching | Manual padding required | Continuous Batching auto-scheduling |+| CUDA | Sequential per-sample | CUDA Graph + operator fusion |+| Multi-GPU | Manual implementation | Tensor Parallel one-line config |+| Result | RTFx ~20 | **RTFx 340+** (16x speedup) |+### Universal Interface (Recommended)```pythondiff --git a/docs/vllm_guide_zh.md b/docs/vllm_guide_zh.mdindex 62950051a..bce42db5e 100644--- a/docs/vllm_guide_zh.md+++ b/docs/vllm_guide_zh.md@@ -1,101 +1,200 @@# FunASR vLLM 推理引擎指南-FunASR 集成 vLLM 高吞吐推理引擎,用于加速 LLM-based ASR 模型的自回归解码。支持离线批量推理、SDK 流式推理、生产级 WebSocket 实时服务三种模式。-----## 目录+## Benchmark-1. [概述](#1-概述)-2. [安装与环境](#2-安装与环境)-3. [离线批量推理](#3-离线批量推理)-4. [流式 SDK 推理](#4-流式-sdk-推理)-5. [实时 WebSocket 服务](#5-实时-websocket-服务)-6. [性能对比](#6-性能对比)-7. [API 参考](#7-api-参考)-8. [FAQ](#8-faq)+**测试集**: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% | 不支持长音频推理 |-## 1. 概述--### 适用模型--| 模型 | vLLM 支持 | 说明 |-|------|-----------|------|-| **FunASRNano** | ✓ | Qwen3-0.6B LLM,支持离线和流式 |-| **LLMASR** | ✓ | Whisper + Qwen/Vicuna/LLaMA |-| **GLMASR** | ✓ | GLM-ASR-Nano |-| **QwenAudioWarp** | ✓ | Qwen-Audio |-| Paraformer | ✗ | 非自回归模型(CIF predictor),无 LLM 解码 |-| SenseVoice | ✗ | Whisper-like encoder-decoder,非 LLM |-| Conformer/Transformer | ✗ | CTC/attention 解码,非 LLM |--### 架构--```-┌────────────────────────────────────────────────────────┐-│ FunASR + vLLM │-├────────────────────────────────────────────────────────┤-│ │-│ Audio ──→ Frontend ──→ Audio Encoder ──→ Adaptor │-│ (fbank) (SenseVoice) (Transformer) │-│ │ │-│ ▼ │-│ Audio Embeddings │-│ │ │-│ Text Prompt ──→ Tokenize ──→ Embed ──→ [Concat] │-│ (hotwords/language/itn) │ │-│ ▼ │-│ ┌──────────────┐ │-│ │ vLLM Engine │ │-│ │ (Qwen3 etc) │ │-│ │ TP 并行加速 │ │-│ └──────┬───────┘ │-│ ▼ │-│ Generated Text │-│ │-│ (可选) CTC Forced Alignment ──→ 字级别时间戳 │-└────────────────────────────────────────────────────────┘-```--### 三种使用模式--| 模式 | 入口 | 适用场景 |-|------|------|---------|-| [离线批量推理](#3-离线批量推理) | `AutoModelVLLM` / `FunASRNanoVLLM` | 大规模转写、批量处理 |-| [流式 SDK 推理](#4-流式-sdk-推理) | `FunASRNanoStreamingVLLM` | 实时字幕展示(SDK 集成) |-| [WebSocket 实时服务](#5-实时-websocket-服务) | `serve_realtime_ws.py` | 生产部署、多端接入 |+> vLLM 与 PyTorch CER 完全一致(差 < 0.2%),速度提升 16-340x。----## 2. 安装与环境+## 目录++1. [安装与环境](#1-安装与环境)+2. [vLLM 推理引擎架构](#2-vllm-推理引擎架构)+3. [离线 SDK 推理](#3-离线-sdk-推理)+4. [流式 SDK 推理](#4-流式-sdk-推理)+5. [离线语音识别服务](#5-离线语音识别服务)+6. [流式语音识别服务](#6-流式语音识别服务)+7. [动态 VAD](#7-动态-vad)+8. [API 参考](#8-api-参考)+9. [FAQ](#9-faq)-### 依赖+---++## 1. 安装与环境```bashpip install funasr>=1.3.0pip install vllm>=0.12.0-pip install safetensors tiktoken websockets regex+pip install safetensors tiktoken websockets regex fastapi uvicorn python-multipart-# FunASR 开发模式安装(需要 auto_model_vllm)cd /path/to/FunASR && pip install -e .```-### 硬件要求+**硬件**:GPU ≥ 8GB VRAM,CUDA ≥ 11.8。推荐 16GB+。-| 配置 | 最低要求 | 推荐 |-|------|---------|------|-| GPU 显存 | 8GB | 16GB+ |-| CUDA | 11.8 | 12.0+ |-| GPU 数量 | 1 | 2+(tensor parallel) |+---++## 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. 离线 SDK 推理适用于大规模音频转写、离线批量处理。vLLM 的批处理能力在此场景优势最大。+### 设计原理++离线 SDK 推理将 ASR 流水线拆分为两阶段独立执行:++```+┌─────────────────────────────────────────────────────────────────────┐+│ 阶段 1: 音频编码(PyTorch, 单 GPU) │+├─────────────────────────────────────────────────────────────────────┤+│ │+│ 音频文件列表 ──→ 分组(每 8 条)──→ Frontend(Fbank) │+│ │ │ │+│ │ ▼ │+│ │ SenseVoice Encoder │+│ │ │ │+│ │ ▼ │+│ │ Audio Adaptor │+│ │ (dim 转换 + low_frame_rate 截断) │+│ │ │ │+│ └─── 共享文本 prompt 预编码 ─────┐ ▼ │+│ (system/hotwords/language) │ audio_embeds │+│ │ │ │ │+│ ▼ │ ▼ │+│ prefix_emb ──→ [concat: prefix | audio | suffix] │+│ │ │+│ ▼ │+│ EmbedsPrompt(N 条) │+└──────────────────────────────────────────────┼──────────────────────┘+ │+ ▼+┌─────────────────────────────────────────────────────────────────────┐+│ 阶段 2: LLM 解码(vLLM, 多 GPU Tensor Parallel) │+├─────────────────────────────────────────────────────────────────────┤+│ │+│ EmbedsPrompt × N ──→ vLLM Continuous Batching │+│ (PagedAttention + CUDA Graph) │+│ │ │+│ ▼ │+│ Generated token_ids × N │+│ │ │+│ ▼ │+│ Decode + 后处理(去特殊标记、清洗) │+│ │ │+│ ▼ │+│ (可选) CTC Forced Alignment → 字级别时间戳 │+└─────────────────────────────────────────────────────────────────────┘+```++**关键设计决策:**++1. **权重分离**:首次运行时从 `model.pt` 提取 `llm.*` 前缀的权重,保存为 HuggingFace safetensors 格式供 vLLM 加载(缓存到 `Qwen3-0.6B-vllm/` 目录)+2. **Embedding 拼接**:文本 prompt 通过 LLM 的 `embed_tokens` 层编码为 embedding,与音频 adaptor 输出在序列维度拼接:`[prefix_emb | audio_emb | suffix_emb]`,以 `EmbedsPrompt` 形式送入 vLLM+3. **Low Frame Rate 截断**:adaptor 输出需按公式 `fake_token_len = ((((fbank_len - 3 + 2) // 2 - 3 + 2) // 2) - 1) // 2 + 1` 截断到正确长度,确保与 PyTorch 训练时一致+4. **批量音频编码**:多条音频按 batch_size=8 分组通过 encoder + adaptor 前向,减少 GPU kernel launch 开销+5. **文本 prompt 共享**:同一批次内 hotwords/language 相同时,prefix_emb 和 suffix_emb 只计算一次+6. **CTC 时间戳**:保留 encoder_out,LLM 生成文本后做 forced alignment 得到字级别时间++**为什么比 PyTorch generate() 快?**++| 维度 | PyTorch | vLLM |+|------|---------|------|+| KV Cache | 固定预分配(浪费显存) | PagedAttention 按需分配 |+| 批处理 | 需手动 padding 对齐 | Continuous Batching 自动调度 |+| CUDA | 逐 sample 串行 | CUDA Graph + 算子融合 |+| 多卡 | 需手动实现 | Tensor Parallel 一行配置 |+| 结果 | RTFx ~20 | **RTFx 340+**(16倍加速) |+### 通用接口(推荐)```python@@ -204,399 +303,383 @@ for result in engine.streaming_generate("audio.wav", language="中文"):----## 5. 实时 WebSocket 服务--生产级实时语音识别服务,集成 VAD 分句 + vLLM 推理 + 说话人分离 + 热词。--### 推理逻辑+## 5. 离线语音识别服务-**核心设计:基于 VAD 端点逐段解码(非固定 chunk)**+### 3.1 服务架构```-音频流 ──→ StreamingVAD (60ms) ──→ 检测到端点 ──→ vLLM 解码整段- │ │- │ ▼- │ locked_sentences(锁定)- │ │- │ ▼- │ SPK assign(说话人分配)- │- └──→ 未结束 ──→ vLLM partial decode(每0.48s)- │- ▼- partial text(预览,会覆盖)+客户端 serve_vllm.py+ │ │+ │── HTTP/OpenAI/WebSocket ──────────────→│+ │ │+ │ ┌────┴────────────────────────┐+ │ │ 1. 接收完整音频文件 │+ │ │ 2. 动态 VAD 分段(≤60s/段) │+ │ │ 3. vLLM batch 推理所有段 │+ │ │ 4. CTC 时间戳(逐字) │+ │ │ 5. 说话人分离(可选) │+ │ └────┬────────────────────────┘+ │ │+ │←── JSON 结果 ─────────────────────────│```-**两条推理路径:**+**特点**:+- 音频完整到达后处理,适合文件转写+- 动态 VAD 保留长段(≤60s),减少边界切割损失+- batch 推理所有 VAD 段,吞吐量高+- 自动输出字级别时间戳+- SPK 说话人分离默认关闭,客户端可开启-| 路径 | 触发条件 | 输出 |-|------|---------|------|-| 确认段解码 | VAD 检测到静音端点 | 锁定到 sentences,永不改变 |-| Partial 预览 | 每 0.48s + 新音频 ≥ 960ms | 临时文字,随时覆盖 |--**动态 VAD 阈值:**+### 3.2 启动服务-| 累积时长 | 静音阈值 | 效果 |-|---------|---------|------|-| ≤ 5s | 2.0s | 短句不切碎 |-| 5-10s | 1.5s | 正常分句 |-| 10-15s | 1.0s | 开始收紧 |-| 15-30s | 0.8s | 较快切分 |-| 30-45s | 0.4s | 防止过长 |-| > 45s | 0.1s | 强制切分 |+```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+```-**STOP 最终处理:**-1. 剩余音频喂给 VAD(is_final=True)-2. 强制结束当前在说话的段-3. 全局 SPK 重聚类(修正说话人 ID)-4. 返回 `is_final: true`+### 3.3 协议一:HTTP REST — `POST /asr`-### 部署+功能最全的接口,支持 SPK、时间戳、热词。-```bash-cd examples/industrial_data_pretraining/fun_asr_nano+**请求**:`multipart/form-data`-# 单卡-CUDA_VISIBLE_DEVICES=0 python serve_realtime_ws.py --port 10095 --language 中文+| 参数 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `file` | file | 必填 | 音频文件(wav/mp3/flac) |+| `language` | string | None | 语种("中文"/"English"/...),None 为自动 |+| `hotwords` | string | "" | 热词,逗号分隔 |+| `spk` | bool | false | 是否开启说话人分离 |+| `timestamp` | bool | true | 是否输出字级别时间戳 |-# 多卡-CUDA_VISIBLE_DEVICES=0,1 python serve_realtime_ws.py \- --port 10095 --tensor-parallel-size 2 --language 中文+**响应**:-# 完整参数-python serve_realtime_ws.py \- --port 10095 \- --model FunAudioLLM/Fun-ASR-Nano-2512 \- --hub ms \- --device cuda:0 \- --decode-interval 0.48 \- --hotword-file 热词列表 \- --language 中文 \- --dtype bf16 \- --tensor-parallel-size 1 \- --gpu-memory-utilization 0.8 \- --max-model-len 2048+```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+}```-### 客户端+**客户端示例**:-| 客户端 | 用法 |-|--------|------|-| 浏览器 | 打开 `client_mic.html`(麦克风/文件/热词/说话人) |-| Python CLI | `python client_python.py --server ws://localhost:10095 --mic` |-| 测试脚本 | `python client_test.py --server ws://localhost:10095 --file audio.wav` |+```bash+# cURL+curl -X POST http://localhost:8899/asr \+ -F "[email protected]" -F "language=中文" -F "spk=true"+```-远程访问需 SSH 端口转发:`ssh -L 10095:localhost:10095 <server>`+```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()+```-### WebSocket 协议+```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`-| 消息 | 格式 | 说明 |-|------|------|------|-| 开始会话 | `"START"` | 初始化 session |-| 设置热词 | `"HOTWORDS:词1,词2"` | 可选 |-| 设置语种 | `"LANGUAGE:中文"` | 可选 |-| 音频数据 | `bytes` | PCM16, 16kHz, mono |-| 结束会话 | `"STOP"` | 触发最终解码 |+兼容 OpenAI Whisper API 标准,可直接用 OpenAI SDK 接入。-**服务端 → 客户端:**+**请求**:`multipart/form-data`-```json-// 事件-{"event": "started"}-{"event": "hotwords_set", "hotwords": ["词1", "词2"]}-{"event": "language_set", "language": "中文"}-{"event": "stopped"}+| 参数 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `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 扩展字段) |-// 实时结果-{- "sentences": [{"text": "已确认", "start": 1700, "end": 5500, "spk": 0}],- "partial": "正在说...",- "partial_start_ms": 5800,- "duration_ms": 7200,- "is_final": false-}+**响应**(`verbose_json`):-// 最终结果+```json{- "sentences": [{"text": "...", "start": ..., "end": ..., "spk": ...}, ...],- "partial": "",- "partial_start_ms": 0,- "duration_ms": 10000,- "is_final": true+ "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}, ...]+ }+ ]}```-**交互时序:**+**客户端示例**:-```-Client Server- │── "START" ─────────────────→│- │←─ {"event":"started"} ──────│- │── "HOTWORDS:张三,北京" ────→│- │←─ {"event":"hotwords_set"} ─│- │── "LANGUAGE:中文" ─────────→│- │←─ {"event":"language_set"} ─│- │── [audio bytes] ───────────→│- │←─ {sentences,partial} ──────│ (实时推送)- │── [audio bytes] ───────────→│- │←─ {sentences,partial} ──────│- │── "STOP" ──────────────────→│- │←─ {sentences,is_final:true} │ (最终结果)- │←─ {"event":"stopped"} ──────│+```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)```-### 热词文件--默认文件名 `热词列表`(`--hotword-file` 指定),一行一个词:--```-张三-李四-北京大学+```bash+# cURL+curl -X POST http://localhost:8899/v1/audio/transcriptions \+ -F "[email protected]" -F "model=fun-asr-nano" -F "response_format=verbose_json"```-也可通过 WebSocket 动态设置:`HOTWORDS:词1,词2,词3`-------## 6. 性能对比+### 3.5 协议三:WebSocket — `ws://host:port/ws`-### 离线推理-| 配置 | 5.6s 音频延迟 | 相对加速 |-|------|-------------|---------|-| PyTorch (baseline) | 0.89s | 1x |-| vLLM 1-GPU | 0.30s | **3x** |-| vLLM 2-GPU TP | ~0.20s | **4.5x** |+离线服务的 WebSocket 接口,发送完整音频后获取结果。STOP 时自动进行说话人聚类,结果中包含 `spk` 字段。-### 批量吞吐+**客户端 → 服务端**:-| Batch Size | 1-GPU | 2-GPU | 4-GPU |-|-----------|-------|-------|-------|-| 1 | ~1.5x | ~2x | ~2.5x |-| 16 | ~4x | ~7x | ~12x |-| 32 | ~5x | ~9x | ~15x |+| 消息 | 说明 |+|------|------|+| `"START"` | 开始会话 |+| `"LANGUAGE:中文"` | 设置语种(可选) |+| `"HOTWORDS:词1,词2"` | 设置热词(可选) |+| `[binary]` | PCM16 16kHz mono 音频数据 |+| `"STOP"` | 结束,请求识别结果 |-### WebSocket 实时服务+**服务端 → 客户端**:-| 指标 | 数值 |-|------|------|-| RTF | < 0.08 |-| 首字延迟 | ~480ms |-| 30s 音频总耗时 | ~2.3s |-| 并发 | 多 WebSocket 连接 |+```json+{"event": "started"}+{"event": "language_set", "language": "中文"}+{"sentences": [{"text":"...","start":..,"end":..}], "is_final": true, "duration_ms": 5170}+{"event": "stopped"}+```-### VAD + vLLM Pipeline+**客户端示例**:-| 场景 | PyTorch 串行 | vLLM 批量 | 加速 |-|------|-------------|-----------|------|-| 10 段 x 5s | ~9s | ~1.5s | **6x** |-| 20 段 x 5s | ~18s | ~2.5s | **7x** |+```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"))+```----## 7. API 参考+## 6. 流式语音识别服务-### AutoModelVLLM+### 4.1 服务架构-```python-from funasr.auto.auto_model_vllm import AutoModelVLLM+```+客户端(麦克风/音频流) serve_realtime_ws.py+ │ │+ │── WebSocket PCM16 16kHz ────────────→│+ │ (每帧 ~100ms,持续发送) │+ │ │+ │ ┌────┴─────────────────────────┐+ │ │ 实时循环: │+ │ │ ├─ 动态 VAD(60ms chunk) │+ │ │ ├─ 检测到端点 → vLLM 解码 │+ │ │ ├─ 未结束 → partial 预览 │+ │ │ └─ 说话人流式分配 │+ │ └────┬─────────────────────────┘+ │ │+ │←── JSON 实时推送 ───────────────────│```-通用入口,自动检测模型类型并选择对应的 vLLM 实现。--| 参数 | 默认值 | 说明 |-|------|--------|------|-| `model` | - | 模型名(hub)或本地路径 |-| `hub` | `"ms"` | `"ms"` / `"hf"` |-| `device` | `"cuda:0"` | 音频编码器设备 |-| `dtype` | `"bf16"` | 精度 |-| `tensor_parallel_size` | `1` | vLLM GPU 并行数 |-| `gpu_memory_utilization` | `0.8` | KV Cache 显存比例 |-| `max_model_len` | `4096` | 最大序列长度 |--### AutoModelVLLM.generate()--| 参数 | 默认值 | 说明 |-|------|--------|------|-| `inputs` | - | 音频路径/列表/numpy/tensor |-| `language` | `None` | 语种提示 |-| `hotwords` | `None` | 热词列表 |-| `itn` | `True` | 逆文本正则化 |-| `max_new_tokens` | `512` | 最大生成 token |-| `temperature` | `0.0` | 采样温度 |-| `repetition_penalty` | `1.0` | 重复惩罚 |--**返回**: `[{"key": str, "text": str, "timestamps": [...]}]`--### FunASRNanoStreamingVLLM.from_pretrained()--| 参数 | 默认值 | 说明 |-|------|--------|------|-| `model` | `"FunAudioLLM/Fun-ASR-Nano-2512"` | 模型名或路径 |-| `hub` | `"ms"` | 模型来源 |-| `device` | `"cuda:0"` | 设备 |-| `dtype` | `"bf16"` | 精度 |-| `tensor_parallel_size` | `1` | GPU 并行数 |-| `gpu_memory_utilization` | `0.8` | 显存比例 |-| `max_model_len` | `2048` | 序列长度 |-| `chunk_ms` | `720` | chunk 时长 |-| `rollback_chars` | `8` | 回退字符数 |--### streaming_generate()--| 参数 | 默认值 | 说明 |-|------|--------|------|-| `audio_input` | - | 音频路径/数据 |-| `chunk_ms` | `720` | chunk 大小 |-| `rollback_chars` | `8` | 回退字符 |-| `hotwords` | `None` | 热词 |-| `language` | `None` | 语种 |-| `max_new_tokens` | `200` | 每 chunk 最大 token |-| `temperature` | `0.0` | 采样温度 |--**Yields**: `{"text", "fixed_text", "is_final", "chunk_idx", "audio_duration_ms"}`--> `repetition_penalty=1.3` 内部硬编码。--### serve_realtime_ws.py 参数--| 参数 | 默认值 | 说明 |-|------|--------|------|-| `--port` | `10095` | WebSocket 端口 |-| `--model` | `FunAudioLLM/Fun-ASR-Nano-2512` | 模型 |-| `--hub` | `ms` | 来源 |-| `--device` | `cuda:0` | 设备 |-| `--decode-interval` | `0.48` | partial 解码间隔(秒) |-| `--hotword-file` | `热词列表` | 热词文件 |-| `--language` | `None` | 语种 |-| `--dtype` | `bf16` | 精度 |-| `--tensor-parallel-size` | `1` | GPU 并行 |-| `--gpu-memory-utilization` | `0.8` | 显存比例 |-| `--max-model-len` | `2048` | 序列长度 |+**特点**:+- 音频逐帧到达,边收边处理+- 基于 VAD 端点自然分句+- 确认段文字锁定不变,partial 实时更新+- 流式说话人分配 + STOP 时全局重聚类+- 首字延迟 ~480ms----+### 4.2 启动服务-## 8. FAQ+```bash+CUDA_VISIBLE_DEVICES=0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \+ --port 10095 --language 中文 --hotword-file 热词列表+```-### Q: 首次启动为什么慢?-vLLM 需要初始化 KV Cache 和 CUDA Graph warmup,约 60-90 秒。后续推理即时响应。+### 4.3 WebSocket 协议-### Q: CUDA OOM 怎么办?-- 减小 `gpu_memory_utilization`(如 0.6)-- 增加 `tensor_parallel_size` 分摊到多卡-- 减小 `max_model_len`+**连接**:`ws://host:10095`-### Q: Paraformer 能用 vLLM 吗?-不能。Paraformer 是非自回归模型(CIF predictor),所有 token 并行生成,不使用 KV-cache。vLLM 只加速自回归 LLM 解码。+**客户端 → 服务端**:-### Q: WebSocket 服务和 streaming_generate 有什么区别?+| 消息 | 格式 | 说明 |+|------|------|------|+| 开始 | `"START"` | 初始化 session |+| 热词 | `"HOTWORDS:词1,词2"` | 可选 |+| 语种 | `"LANGUAGE:中文"` | 可选 |+| 音频 | `binary` | PCM16 16kHz mono |+| 结束 | `"STOP"` | 最终解码 + SPK 重聚类 |-| | WebSocket 服务 | streaming_generate |-|---|---|---|-| 分句 | VAD 自然端点 | 固定 720ms chunk |-| 推理 | 每个 VAD 段整体解码 | 累积重编码全部音频 |-| 准确率 | 更高 | 前 3s 较低 |-| 场景 | 生产部署 | SDK 集成 |+**服务端 → 客户端**:-### Q: 流式推理前几秒输出为空?-正常。模型需要 ~3 秒累积音频才能产生有意义输出,这是模型特性而非 vLLM 限制。+```json+{"event": "started"}+{"sentences": [{"text":"你好","start":300,"end":1200,"spk":0}], "partial": "世界", "is_final": false}+{"sentences": [...], "is_final": true}+{"event": "stopped"}+```-### Q: 支持哪些音频格式?-wav、mp3、flac 等主流格式,采样率自动转为 16kHz。+**字段**:`sentences[]` = 已锁定,`partial` = 正在说(会变),`is_final` = STOP 后为 true。-### Q: 浏览器无法使用麦克风?-Chrome 要求 HTTPS 或 localhost。远程服务器用 SSH 端口转发:`ssh -L 10095:localhost:10095 <server>`+**时序**:+```+Client Server+ │── START ───────→│+ │←─ started ──────│+ │── [audio] ─────→│+ │←─ {partial} ────│+ │── [audio] ─────→│+ │←─ {sentences+partial} ─│ (VAD 切了一句)+ │── STOP ────────→│+ │←─ {is_final:true} ────│+ │←─ stopped ─────│+```-### Q: 多个并发连接会互相影响吗?-不会。每个 WebSocket 连接有独立的 session(VAD/ASR 状态隔离)。vLLM 内部会自动调度。+### 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+```-## 附录:DynamicStreamingVAD+**浏览器**:打开 `client_mic.html`-`funasr.models.fsmn_vad_streaming.dynamic_vad.DynamicStreamingVAD` 是通用的动态阈值流式 VAD 封装,-在 fsmn-vad 基础上根据当前语音段的累积时长动态调整静音切分阈值。+**自定义 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"))+```-### 设计动机+----fsmn-vad 默认使用固定静音阈值(800ms)。实际场景中:-- 短句(如"好的")需要等更长的静音才切,否则会把一句话切碎-- 长段(如会议发言 30s+)需要更快切分,否则 ASR 输入过长导致质量下降+## 7. 动态 VAD-### 用法+fsmn-vad 默认启用动态静音阈值。离线和流式使用不同配置。-```python-from funasr import AutoModel-from funasr.models.fsmn_vad_streaming.dynamic_vad import DynamicStreamingVAD+| 累积时长 | 离线(保留长段 ≤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 |-vad_model = AutoModel(model="fsmn-vad", device="cuda:0")+离线倾向保留长段减少边界损失;流式更快收紧以降低延迟。-# 使用默认阈值配置-vad = DynamicStreamingVAD(vad_model)+### 自定义-# 或自定义阈值-vad = DynamicStreamingVAD(- vad_model,- silence_schedule=[- (3000, 1500), # 累积 <=3s: 等 1.5s 静音- (10000, 800), # 累积 3-10s: 等 0.8s- (float('inf'), 300), # 累积 >10s: 等 0.3s- ],- speech_noise_thres=0.5,-)+```python+model.generate(input="audio.wav", silence_schedule=[(5000,1500), (20000,800), (float('inf'),300)])```-#### 流式调用--```python-import torch+> GLM-ASR 不支持长段,使用时传 `dynamic_silence=False`。-for audio_chunk in audio_stream: # 实时音频流- segments = vad.feed(torch.from_numpy(audio_chunk).float())- for seg in segments:- print(f"Speech: {seg[0]}-{seg[1]}ms")+----# 结束时-final_segments = vad.finalize()-```+## 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: |-```python-segments = vad.process(full_audio_tensor)-for seg in segments:- print(f"Speech: {seg[0]}-{seg[1]}ms")-```+----### 默认阈值配置+## 9. FAQ-| 累积时长 | 静音阈值 | 说明 |-|---------|---------|------|-| ≤ 5s | 2.0s | 短句不切碎 |-| 5-10s | 1.5s | 正常分句 |-| 10-15s | 1.0s | 开始收紧 |-| 15-30s | 0.8s | 较快切分 |-| 30-45s | 0.4s | 防止过长 |-| > 45s | 0.1s | 强制切分 |+**Q: 离线还是流式?**+完整文件 → 离线(高吞吐)。麦克风/直播 → 流式(低延迟)。-### 参数+**Q: GLM-ASR 用动态 VAD?**+不支持长段推理,用 `dynamic_silence=False`。-| 参数 | 默认值 | 说明 |-|------|--------|------|-| `vad_model` | - | FunASR AutoModel 加载的 fsmn-vad 实例 |-| `chunk_size_ms` | 60 | VAD 内部处理 chunk 大小 |-| `speech_noise_thres` | 0.5 | 语音/噪声判别阈值 |-| `speech_to_sil_thres_ms` | 150 | 语音转静音基础时间 |-| `silence_schedule` | 见上表 | 动态阈值配置 `[(上限ms, 静音ms), ...]` |-| `sample_rate` | 16000 | 采样率 |+**Q: SPK 性能影响?**+RTFx 102 → 46。CER 不变。默认关闭。-### 属性+**Q: 二次开发入口?**+离线:`serve_vllm.process_audio()` / `FunASRNanoVLLM.generate()`+流式:`serve_realtime_ws.RealtimeASRSession`-| 属性 | 说明 |-|------|------|-| `vad.is_speaking` | 当前是否在语音状态中 |-| `vad.current_duration_ms` | 当前段已累积时长 |-| `vad.current_threshold_ms` | 当前使用的静音阈值 |+**Q: 首次慢?**+vLLM 初始化 60-90s,之后即时。diff --git a/docs/vllm_guide_zh_v2.md b/docs/vllm_guide_zh_v2.mdindex 434c82bc5..bce42db5e 100644--- a/docs/vllm_guide_zh_v2.md+++ b/docs/vllm_guide_zh_v2.md@@ -22,7 +22,7 @@1. [安装与环境](#1-安装与环境)2. [vLLM 推理引擎架构](#2-vllm-推理引擎架构)-3. [离线 SDK 批量推理](#3-离线-sdk-批量推理)+3. [离线 SDK 推理](#3-离线-sdk-推理)4. [流式 SDK 推理](#4-流式-sdk-推理)5. [离线语音识别服务](#5-离线语音识别服务)6. [流式语音识别服务](#6-流式语音识别服务)@@ -125,13 +125,13 @@ FunASR 的 vLLM 集成将 ASR 模型拆分为两部分独立运行:----## 3. 离线 SDK 批量推理+## 3. 离线 SDK 推理适用于大规模音频转写、离线批量处理。vLLM 的批处理能力在此场景优势最大。### 设计原理-离线 SDK 批量推理将 ASR 流水线拆分为两阶段独立执行:+离线 SDK 推理将 ASR 流水线拆分为两阶段独立执行:```┌─────────────────────────────────────────────────────────────────────┐