Skip to content

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

feat: add Qwen3-ASR streaming WebSocket server with notes (#3035)

qiulang8f8ce5f48b77
diff --git a/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py
new file mode 100644
index 000000000..6e7e0789d
--- /dev/null
+++ b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""
+Qwen3-ASR streaming WebSocket service.
+
+把官方 example_qwen3_asr_vllm_streaming.py 的原生流式 API
+(init_streaming_state / streaming_transcribe / finish_streaming_transcribe)
+包成一个 WebSocket 服务,协议与 Fun-ASR-Nano 的 serve_realtime_ws.py 一致,
+因此可以直接用同一个 bench_streaming_ws.py 压测,对比。
+
+协议:
+ 1. 客户端连接 ws://host:port
+ 2. 客户端发文本 "START" → 服务端回 {"event": "started"}
+ 3. 客户端发二进制 int16 PCM 块(16kHz 单声道)
+ 4. 服务端随转写增长发 {"partial": "<当前文本>"}
+ 5. 客户端发文本 "STOP" → 服务端回
+ {"is_final": true, "sentences": [{"text": "<最终文本>"}]}
+ 然后 {"event": "stopped"}
+
+架构对齐 serve_realtime_ws.py:单 asyncio 事件循环,streaming_transcribe /
+finish_streaming_transcribe 同步调用、阻塞整个循环——这样压测出来的并发特性
+才和 Fun-ASR-Nano 那条同口径可比。生产扩展同样靠 多进程 + CUDA MPS + nginx
+(见 vllm_guide §6.7)。
+
+关于 VAD 参见配套说明文档
+
+
+依赖:
+ pip install qwen-asr[vllm] websockets numpy
+启动:
+ python serve_qwen3_asr_ws.py --port 10095 --gpu-memory-utilization 0.8
+ # 可选:--chunk-size-sec 控制流式块大小(默认 2.0)。值越小出字越快/越勤,
+ # 但并发开销越大(实测 1.0 比 2.0 明显更吃并发)。
+"""
+import asyncio
+import argparse
+import json
+import logging
+
+import numpy as np
+import websockets
+
+from qwen_asr import Qwen3ASRModel
+
+# websockets 默认会对每个连接打 INFO 级 "connection open/closed",压测时刷屏;
+# 提到 WARNING 关掉这条噪音(不影响连接行为,纯日志)。
+logging.getLogger("websockets").setLevel(logging.WARNING)
+
+SAMPLE_RATE = 16000
+
+# 全局只加载一次;所有连接共用模型,各自持有独立的 streaming state。
+asr = None
+
+# 流式块大小(秒),由 --chunk-size-sec 设置,handle_client 里 init_streaming_state 用。
+# 默认 2.0(官方 example 值);值越小出字越勤、并发开销越大。
+CHUNK_SIZE_SEC = 2.0
+
+
+def int16_pcm_to_float32(pcm_bytes: bytes) -> np.ndarray:
+ """bench 发来的是 int16 小端 PCM;Qwen3-ASR 的 streaming_transcribe 吃 float32 [-1,1)。"""
+ return np.frombuffer(pcm_bytes, dtype=np.int16).astype(np.float32) / 32768.0
+
+
+async def handle_client(ws, path=None): # path 兼容老版本 websockets 的两参回调
+ state = None
+ last_partial = None
+ try:
+ async for msg in ws:
+ # ---- 文本控制消息 ----
+ if isinstance(msg, str):
+ if msg == "START":
+ # 每个连接一份独立 state;参数同官方 example
+ state = asr.init_streaming_state(
+ unfixed_chunk_num=2,
+ unfixed_token_num=5,
+ chunk_size_sec=CHUNK_SIZE_SEC,
+ )
+ last_partial = None
+ await ws.send(json.dumps({"event": "started"}))
+
+ elif msg == "STOP":
+ if state is not None:
+ # 同步收尾,阻塞循环(与 serve_realtime_ws.py 句尾 finalize 同口径)
+ asr.finish_streaming_transcribe(state)
+ final_text = (state.text or "").strip()
+ await ws.send(json.dumps({
+ "is_final": True,
+ "sentences": [{"text": final_text}] if final_text else [],
+ }))
+ await ws.send(json.dumps({"event": "stopped"}))
+ break
+ # 其它文本忽略
+
+ # ---- 二进制音频块 ----
+ else:
+ if state is None:
+ continue # 还没 START,丢弃
+ seg = int16_pcm_to_float32(msg)
+ # 同步调用,阻塞整个事件循环 —— 这正是要复刻的单循环架构
+ asr.streaming_transcribe(seg, state)
+ text = state.text or ""
+ # 只在文本变化时发 partial,避免刷屏(不影响 bench 的首词延迟统计)
+ if text != last_partial:
+ last_partial = text
+ await ws.send(json.dumps({"partial": text}))
+
+ except websockets.exceptions.ConnectionClosed:
+ pass
+ except Exception:
+ logging.exception("Unexpected error in Qwen3-ASR WebSocket handler")
+
+
+async def amain(args):
+ global asr, CHUNK_SIZE_SEC
+ CHUNK_SIZE_SEC = args.chunk_size_sec
+ print(f"Loading {args.model} (gpu_memory_utilization={args.gpu_memory_utilization}, chunk_size_sec={CHUNK_SIZE_SEC}) ...")
+ # Streaming is vLLM-only and no forced aligner supported.(官方 example 注释)
+ asr = Qwen3ASRModel.LLM(
+ model=args.model,
+ gpu_memory_utilization=args.gpu_memory_utilization,
+ max_new_tokens=32, # 流式用小值,同官方 example
+ )
+ print(f"Serving on ws://{args.host}:{args.port} (Ctrl-C to stop)")
+ async with websockets.serve(
+ handle_client, args.host, args.port, max_size=10 * 1024 * 1024
+ ):
+ await asyncio.Future() # run forever
+
+
+def main():
+ p = argparse.ArgumentParser()
+ p.add_argument("--host", default="0.0.0.0")
+ p.add_argument("--port", type=int, default=10095)
+ p.add_argument("--model", default="Qwen/Qwen3-ASR-1.7B")
+ p.add_argument("--gpu-memory-utilization", type=float, default=0.8,
+ dest="gpu_memory_utilization")
+ p.add_argument("--chunk-size-sec", type=float, default=2.0,
+ dest="chunk_size_sec",
+ help="流式块大小(秒),传给 init_streaming_state。默认 2.0;越小出字越勤但并发开销越大(实测 1.0 比 2.0 明显更吃并发)")
+ args = p.parse_args()
+ asyncio.run(amain(args))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes.md b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes.md
new file mode 100644
index 000000000..c0375d164
--- /dev/null
+++ b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes.md
@@ -0,0 +1,171 @@
+# serve_qwen3_asr_ws.py 说明与已知问题
+
+本文档记录 `serve_qwen3_asr_ws.py` 的几个容易困惑/踩坑的点。代码里对应位置只留一行
+指向本文的精简注释,细节看这里。
+
+---
+
+## 1. 关于 VAD
+
+> 在开源仓库 github.com/QwenLM/Qwen3-ASR 没有关于 `VAD` 内容。但商用 [Qwen3-ASR的文档/示例](https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process)里**是有 VAD 设置**,例如:
+> ```json
+> "turn_detection": { "type": "server_vad", "threshold": 0.2, "silence_duration_ms": 800 }
+> ```
+
+VAD 在 ASR 里其实有两种完全不同的用途,容易混为一谈:
+
+- **A. 切段用的 VAD(给非流式 encoder 喂分段)**:像 Fun-ASR-Nano 这类模型 encoder 是
+ **非流式**的(一次要看完整一段),必须靠 VAD 把连续音频切成一句句、每句整体编码解码。
+ 这种 VAD 对 Fun-ASR-Nano 这类模型 **技术必需**——不切就没法编码。
+
+- **B. 端点/轮次检测用的 VAD(判断"这一轮说完了没")**:检测说话人停顿(如静音 800ms)
+ 来判定"一句话/一轮结束",从而触发"锁定文本 / 发 is_final / 该回应了"。这是**产品行为**
+ 层面的需求,和 encoder 能不能流式无关。
+
+对 **Qwen3-ASR 的开源流式 API**(本服务用的 `qwen-asr[vllm]` 的
+`init_streaming_state` / `streaming_transcribe`):
+
+- **不需要 A 类(切段)VAD**:它是**增量式**流式——每次只吃新增的一小段音频、状态向前
+ 滚动,连续转写,不存在"先切句再解码"。"哪些字定了、哪些会变"由 `unfixed_chunk_num` /
+ `unfixed_token_num` 表示(尾部 N 个 chunk/token 算"未定"、会被后续音频修正,其余视为
+ 已确认)——这相当于内置的 partial/锁定机制,取代了 A 类 VAD 的切段职责。所以在开源
+ 流式 API 的代码里搜不到 vad,是因为它**这一层不做切段**。
+
+- **仍然需要 B 类(端点)VAD —— 只是开源 API 自己不带**:自动判断"用户停顿=这一轮结束"
+ 这件事,`streaming_transcribe` 本身不管。商用服务在 ASR **之外**包了一层 `server_vad`
+ 来做(就是上面那段 `turn_detection`)。本服务目前是用客户端显式发 **`STOP`** 来代替
+ 这个端点判断(bench 里音频放完即发 STOP)。**若要在真实场景自动断句/断轮,需要自己在
+ 本服务之外接一个 VAD / 端点检测**(角色等同商用的 server_vad),而不是去 Qwen3-ASR
+ 内部找——它的开源流式 API 不含这一层。
+
+**一句话**:Qwen3-ASR 增量流式**省掉了"切段 VAD"(A)**,但**"端点/轮次 VAD"(B)这个
+职责依然存在**,商用版用 `server_vad` 实现、本服务用手动 `STOP` 代替。两者不矛盾。
+
+### 1.1 官方佐证:商用 Qwen-ASR-Realtime 的"VAD 模式 / Manual 模式"
+
+阿里云百炼的实时语音识别(Qwen-ASR-Realtime)文档明确把"断句由谁做"分成两种模式,
+本质就是 `session.turn_detection` 开还是关:
+
+- **VAD 模式(默认,`turn_detection` 配置为 server_vad)**:服务端自动检测语音起点/终点
+ 来断句,客户端只管持续发音频流,服务端在"检测到一句话结束"时自动返回最终结果。流程中
+ 服务端会发 `input_audio_buffer.speech_started` / `speech_stopped` 等事件——这就是上面说的
+ **B 类端点 VAD**,由服务端那一层(server_vad)实现,**不是** ASR 内核在切段。
+
+- **Manual 模式(`turn_detection` 设为 null)**:由**客户端**控制断句——发完一整句音频后,
+ 客户端发 `input_audio_buffer.commit` 通知服务端边界。适用于客户端能明确判断语句边界的
+ 场景(如"按住说话"、聊天发语音)。
+
+> 对应关系:本服务 `serve_qwen3_asr_ws.py` 用客户端显式发 **`STOP`** 来标记一轮结束,
+> 等价于商用的 **Manual 模式**(`turn_detection=null`,由客户端控制边界)。若要做成"服务端
+> 自动断句",就是去实现商用 **VAD 模式** 的那一层端点检测(server_vad),加在本服务的
+> 增量转写之外,而不是在 Qwen3-ASR 转写内核里找。
+>
+> 文档:实时语音识别(Qwen-ASR-Realtime)交互流程
+> (help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process): ”服务端自动检测语音的起点和终点(断句)。开发者只需持续发送音频流,服务端会在检测到一句话结束时自动返回最终识别结果。此模式适用于实时对话、会议记录等场景。“
+
+### 1.2 `chunk-size-sec` 控制流式块大小
+
+`chunk-size-sec` 控制流式块大小(默认 2.0)。值越小出字越快/越勤,但并发开销越大(实测 1.0 比 2.0 在L20 上,29秒音频 48路并发,1.0 全部失败,2.0 全部通过)。
+
+---
+
+## 2 必须用 vllm 0.14,不要用 0.19(rope_scaling / thinker_config 警告)
+
+本服务需要vllm加速, `qwen-asr[vllm]`,[它锁定 `vllm==0.14.0`](https://github.com/QwenLM/Qwen3-ASR/blob/main/pyproject.toml)。若换成更新的vllm版本, 比如 0.19.x,启动会**出现**:
+
+```
+Unrecognized keys in `rope_scaling` for 'rope_type'='default':
+ {'mrope_section', 'mrope_interleaved', 'interleaved'}
+thinker_config is None. Initializing thinker model with default values
+```
+
+**根因**:vllm 在 0.14 → 0.19 之间 (transformers 两版都是 4.57.6),config 解析里的
+`patch_rope_scaling_dict` 会把 `rope_type` 从 `'mrope'` 改写成 `'default'`(它把 mrope
+当 legacy、假设由 vllm 内部消化 `mrope_section` 等字段):
+
+```python
+elif rope_scaling["rope_type"] == "mrope":
+ assert "mrope_section" in rope_scaling
+ rope_scaling["rope_type"] = "default" # ← 改写
+```
+
+但 Qwen3-ASR 自带的 `Qwen3ASRThinkerTextRotaryEmbedding` 期望从 `rope_scaling` 里读到
+`"mrope"` 才走多模态 RoPE 分支:
+
+```python
+self.rope_type = config.rope_scaling.get("rope_type", "default")
+```
+
+被 vllm 改写成 `"default"` 后,它走了普通 RoPE,`mrope_section` / `mrope_interleaved` /
+`interleaved` 这几个键没人认领 → 打印 "Unrecognized keys" 警告,且音频/文本的多模态
+位置编码退化。`thinker_config is None` 那条同源:0.19 的加载路径没正确解析 Qwen3-ASR 的
+thinker 子配置,回退到默认参数。
+
+**影响与抉择**:在 0.19 上服务"能起、也能出字"(两条是 WARNING/INFO 不是 ERROR),抽查
+几条转写也"看着正常";但位置编码退化对长音频/复杂内容可能有害,且**未做 CER 量化对比**,
+无法判定等价。保守起见固定用 `qwen-asr[vllm]` 自带的 `vllm==0.14.0`。
+
+### 2.1 vllm 加速需要用 Qwen3ASRModel
+
+funasr 的`AutoModelVLLM` 不能加速 Qwen3-ASR , 必须要用 `from qwen_asr import Qwen3ASRModel`
+
+> 这解答 `#3026` 的问题
+
+### 2.2 关于模型下载
+
+**官方推荐做法([Qwen3-ASR README](https://github.com/QwenLM/Qwen3-ASR#released-models-description-and-download))**:如果运行环境不能在线下载,或无法访问 Hugging Face,先手动把权重下载到本地目录,再把本地路径传给 `--model`:
+
+```bash
+# ModelScope(国内推荐)
+pip install -U modelscope
+modelscope download --model Qwen/Qwen3-ASR-1.7B --local_dir ./Qwen3-ASR-1.7B
+
+# 启动时指定本地模型目录
+python serve_qwen3_asr_ws.py --model ./Qwen3-ASR-1.7B ...
+```
+
+注意:仅设置 `VLLM_USE_MODELSCOPE=True` 并安装 `modelscope` 只能接管一部分下载流程。vLLM 会从 ModelScope 拉取 config、tokenizer、merges、vocab、`model.safetensors.index.json` 等文件,但真正的权重 `model.safetensors` 仍可能回到 `huggingface.co` 拉取:
+
+这看起来是 Qwen-ASR 当前下载链路的一个问题:
+
+```
+Downloading Model from https://www.modelscope.cn to directory: /home/vllm/.cache/modelscope/hub/models/Qwen/Qwen3-ASR-1.7B
+2026-06-28 10:15:56,301 - modelscope - INFO - Got 10 files, start to download ...
+...
+2026-06-28 10:15:57,023 - modelscope - INFO - Finish downloading 10 files for repo 'Qwen/Qwen3-ASR-1.7B'███████████| 12.2k/12.2k [00:00<00:00, 38.6kB/s]
+...
+INFO 06-28 10:15:59 [model.py:530] Resolved architecture: Qwen3ASRForConditionalGeneration
+'(MaxRetryError('HTTPSConnectionPool(host=\'huggingface.co\', port=443): Max retries exceeded with url: /Qwen/Qwen3-ASR-1.7B/resolve/main/model.safetensors (Caused by NewConnectionError("HTTPSConnection(host=\'huggingface.co\', port=443): Failed to establish a new connection: [Errno 101] Network is unreachable"))'), '(Request ID: f4f58ad5-e161-42ec-baad-cb2b8dbb63b9)')' thrown while requesting HEAD https://huggingface.co/Qwen/Qwen3-ASR-1.7B/resolve/main/model.safetensors
+```
+
+---
+
+## 3. tokenizer 的 `fix_mistral_regex` 警告(无害,可忽略)
+
+启动时可能出现:
+
+```
+The tokenizer you are loading from '.../Qwen3-ASR-1.7B' with an incorrect regex
+pattern ... This will lead to incorrect tokenization. You should set the
+`fix_mistral_regex=True` flag when loading this tokenizer to fix this issue.
+```
+
+**原因**:Qwen3-ASR 的 tokenizer 沿用了一类带已知 regex 问题的分词器实现,底层库检测到
+该 regex 模式后给出提醒,建议加 `fix_mistral_regex=True` 修正切分。本服务通过 qwen-asr
+的高层 API 加载模型、并不直接构造 tokenizer,没有暴露这个开关,所以这条提醒按原样打印。
+
+**影响**:实测对中文 ASR 转写结果无可见影响(**抽查**多条转写正常,未做 CER 量化)。该
+regex 修正主要影响某些特殊 token 的边界切分,对语音转写路径未观察到差异。属于"提醒级"
+噪音,可忽略。若要彻底消除,需在更底层自行加载 tokenizer 时传 `fix_mistral_regex=True`,
+但 qwen-asr 高层 API 当前不直接支持,且无实测必要。
+
+---
+
+### 顺带:另外两条启动日志(均无害)
+
+- `Error retrieving safetensors: Repo id must be in the form ...`:把本地模型路径当成 HF
+ 仓库 id 去查线上元数据,失败后重试 2 次、回退本地加载,不影响功能。可设环境变量
+ `HF_HUB_OFFLINE=1` 消除。
+
+- `Downcasting torch.float32 to torch.bfloat16`:权重以 fp32 存、按 bf16 加载,正常省显存 /
+ 提速,bf16 与 fp32 指数位同宽,精度几乎无损。这是 INFO 不是错误。
diff --git a/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes_en.md b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes_en.md
new file mode 100644
index 000000000..f57068533
--- /dev/null
+++ b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws_notes_en.md
@@ -0,0 +1,205 @@
+# serve_qwen3_asr_ws.py — Notes & Known Issues
+
+This document records the confusing points / gotchas of `serve_qwen3_asr_ws.py`. The code
+only keeps one-line comments pointing here; details live in this file.
+
+---
+
+## 1. About VAD
+
+> The open-source repo github.com/QwenLM/Qwen3-ASR contains nothing about `VAD`. However,
+> the commercial [Qwen3-ASR docs/examples](https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process)
+> **do have VAD settings**, e.g.:
+> ```json
+> "turn_detection": { "type": "server_vad", "threshold": 0.2, "silence_duration_ms": 800 }
+> ```
+
+VAD actually serves two completely different purposes in ASR, which are easy to conflate:
+
+- **A. Segmentation VAD (feeding chunks to a non-streaming encoder)**: models like
+ Fun-ASR-Nano have a **non-streaming** encoder (it needs to see a whole segment at once),
+ so a VAD is required to cut the continuous audio into sentences, each encoded/decoded as a
+ whole. This kind of VAD is **technically mandatory** for such models — without cutting,
+ there is no way to encode.
+
+- **B. Endpoint / turn-detection VAD (deciding "has this turn finished?")**: detects speaker
+ pauses (e.g. 800ms of silence) to decide "a sentence/turn has ended", triggering "lock the
+ text / emit is_final / time to respond". This is a **product-behavior** need, unrelated to
+ whether the encoder is streaming.
+
+For **Qwen3-ASR's open-source streaming API** (this service uses `qwen-asr[vllm]`'s
+`init_streaming_state` / `streaming_transcribe`):
+
+- **No need for type-A (segmentation) VAD**: it is **incremental** streaming — each call only
+ consumes the newly added slice of audio, the state rolls forward, transcribing continuously;
+ there is no "cut first, then decode" step. "Which characters are final vs. still changing" is
+ expressed by `unfixed_chunk_num` / `unfixed_token_num` (the last N chunks/tokens are
+ "unfixed" and may be corrected by later audio; the rest are treated as confirmed) — this acts
+ as a built-in partial/locking mechanism that replaces type-A VAD's segmentation role. That is
+ why you can't find `vad` in the open-source streaming API: it simply **doesn't do
+ segmentation at this layer**.
+
+- **Still needs type-B (endpoint) VAD — the open-source API just doesn't ship one**:
+ automatically deciding "user paused = this turn ended" is not handled by
+ `streaming_transcribe` itself. The commercial service wraps a `server_vad` layer **outside**
+ the ASR (the `turn_detection` block above) to do it. This service currently uses an explicit
+ **`STOP`** message from the client to substitute for that endpoint decision (in the bench,
+ STOP is sent once the audio finishes). **To auto-segment/auto-endpoint in a real scenario,
+ you need to add a VAD / endpoint detector outside this service** (the same role as commercial
+ `server_vad`), rather than looking for one inside Qwen3-ASR — its open-source streaming API
+ does not include this layer.
+
+**In one line**: Qwen3-ASR's incremental streaming **removes the "segmentation VAD" (A)**, but
+the **"endpoint / turn VAD" (B) responsibility still exists** — the commercial version
+implements it via `server_vad`, while this service substitutes a manual `STOP`. The two are not
+contradictory.
+
+### 1.1 Official corroboration: the commercial Qwen-ASR-Realtime "VAD mode / Manual mode"
+
+Aliyun Bailian's real-time ASR (Qwen-ASR-Realtime) docs explicitly split "who does the
+segmentation" into two modes — essentially whether `session.turn_detection` is on or off:
+
+- **VAD mode (default, `turn_detection` set to server_vad)**: the server automatically detects
+ speech start/end to segment; the client just keeps streaming audio, and the server returns the
+ final result automatically when it "detects a sentence has ended". In the flow the server emits
+ `input_audio_buffer.speech_started` / `speech_stopped` events — this is exactly the **type-B
+ endpoint VAD** above, implemented by that server-side (server_vad) layer, **not** the ASR core
+ doing segmentation.
+
+- **Manual mode (`turn_detection` set to null)**: the **client** controls segmentation — after
+ sending a full sentence of audio, the client sends `input_audio_buffer.commit` to tell the
+ server the boundary. Suitable for scenarios where the client can clearly determine sentence
+ boundaries (e.g. "push-to-talk", sending a voice message in a chat app).
+
+> Mapping: this service `serve_qwen3_asr_ws.py` uses an explicit client **`STOP`** to mark the
+> end of a turn, which is equivalent to the commercial **Manual mode** (`turn_detection=null`,
+> client-controlled boundaries). To make it "server auto-segmentation", you would implement that
+> endpoint-detection layer of the commercial **VAD mode** (server_vad) — added outside this
+> service's incremental transcription, not found inside the Qwen3-ASR transcription core.
+>
+> Docs: Real-time Speech Recognition (Qwen-ASR-Realtime) interaction flow
+> (help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process)
+
+### 1.2 `chunk-size-sec` controls the streaming chunk size
+
+`chunk-size-sec` controls the streaming chunk size (default 2.0). Smaller = faster/more frequent
+output, but higher concurrency cost (measured on L20, 29s audio, 48-way concurrency: 1.0 →
+all failed, 2.0 → all passed).
+
+---
+
+## 2. Use vllm 0.14, not 0.19 (rope_scaling / thinker_config warnings)
+
+This service needs vllm acceleration via `qwen-asr[vllm]`, which
+[pins `vllm==0.14.0`](https://github.com/QwenLM/Qwen3-ASR/blob/main/pyproject.toml). Switching to
+a newer vllm (e.g. 0.19.x) will produce at startup:
+
+```
+Unrecognized keys in `rope_scaling` for 'rope_type'='default':
+ {'mrope_section', 'mrope_interleaved', 'interleaved'}
+thinker_config is None. Initializing thinker model with default values
+```
+
+**Root cause**: between vllm 0.14 → 0.19 (transformers is 4.57.6 in both, so it's ruled out),
+the config parsing in `patch_rope_scaling_dict` rewrites `rope_type` from `'mrope'` to
+`'default'` (treating mrope as legacy and assuming vllm internally consumes the `mrope_section`
+etc. fields):
+
+```python
+elif rope_scaling["rope_type"] == "mrope":
+ assert "mrope_section" in rope_scaling
+ rope_scaling["rope_type"] = "default" # ← rewrite
+```
+
+But Qwen3-ASR's own `Qwen3ASRThinkerTextRotaryEmbedding` expects to read `"mrope"` from
+`rope_scaling` to take the multimodal RoPE branch:
+
+```python
+self.rope_type = config.rope_scaling.get("rope_type", "default")
+```
+
+After vllm rewrites it to `"default"`, it takes the plain RoPE branch, and the keys
+`mrope_section` / `mrope_interleaved` / `interleaved` are left unclaimed → the "Unrecognized
+keys" warning, with degraded multimodal (audio/text) positional encoding. The
+`thinker_config is None` line has the same origin: 0.19's load path doesn't correctly parse
+Qwen3-ASR's thinker sub-config and falls back to default parameters.
+
+**Impact & decision**: on 0.19 the service "starts and does emit text" (both lines are
+WARNING/INFO, not ERROR), and spot-checked transcripts "look fine"; but the degraded positional
+encoding may be harmful for long/complex audio, and **no CER quantitative comparison was done**,
+so equivalence cannot be established. To be safe, stick with the `vllm==0.14.0` that
+`qwen-asr[vllm]` ships.
+
+### 2.1 vllm acceleration requires Qwen3ASRModel
+
+funasr's `AutoModelVLLM` cannot accelerate Qwen3-ASR; you must use
+`from qwen_asr import Qwen3ASRModel`.
+
+> This answers the question in `#3026`.
+
+### 2.2 Downloading model weights
+
+The [Qwen3-ASR README](https://github.com/QwenLM/Qwen3-ASR#released-models-description-and-download) recommends pre-downloading weights when the runtime cannot access remote model hubs. Download the model to a local directory first, then pass that path as `--model`:
+
+```bash
+# Option 1: ModelScope (recommended in Mainland China)
+pip install -U modelscope
+modelscope download --model Qwen/Qwen3-ASR-1.7B --local_dir ./Qwen3-ASR-1.7B
+
+# Option 2: Hugging Face
+pip install -U "huggingface_hub[cli]"
+huggingface-cli download Qwen/Qwen3-ASR-1.7B --local-dir ./Qwen3-ASR-1.7B
+
+# Start the WebSocket server with the pre-downloaded weights
+python serve_qwen3_asr_ws.py --model ./Qwen3-ASR-1.7B ...
+```
+
+Note: setting `VLLM_USE_MODELSCOPE=True` together with `pip install modelscope` only covers part of the download path. The vLLM layer fetches config, tokenizer, merges, vocab, and `model.safetensors.index.json` from ModelScope (log: `Downloading Model from https://www.modelscope.cn ... Finish downloading 10 files`), but the step that resolves the actual weights `model.safetensors` may still go back to `huggingface.co`:
+
+This appears to be an issue in the current Qwen-ASR download path:
+
+```
+Downloading Model from https://www.modelscope.cn to directory: /home/vllm/.cache/modelscope/hub/models/Qwen/Qwen3-ASR-1.7B
+2026-06-28 10:15:56,301 - modelscope - INFO - Got 10 files, start to download ...
+Downloading [configuration.json]: 100%|
+...
+INFO 06-28 10:15:59 [model.py:530] Resolved architecture: Qwen3ASRForConditionalGeneration
+'(MaxRetryError('HTTPSConnectionPool(host=\'huggingface.co\', port=443): Max retries exceeded with url: /Qwen/Qwen3-ASR-1.7B/resolve/main/model.safetensors (Caused by NewConnectionError("HTTPSConnection(host=\'huggingface.co\', port=443): Failed to establish a new connection: [Errno 101] Network is unreachable"))'), '(Request ID: f4f58ad5-e161-42ec-baad-cb2b8dbb63b9)')' thrown while requesting HEAD https://huggingface.co/Qwen/Qwen3-ASR-1.7B/resolve/main/model.safetensors
+```
+
+---
+
+## 3. tokenizer `fix_mistral_regex` warning (harmless, ignorable)
+
+At startup you may see:
+
+```
+The tokenizer you are loading from '.../Qwen3-ASR-1.7B' with an incorrect regex
+pattern ... This will lead to incorrect tokenization. You should set the
+`fix_mistral_regex=True` flag when loading this tokenizer to fix this issue.
+```
+
+**Cause**: Qwen3-ASR's tokenizer reuses a tokenizer implementation with a known regex issue; the
+underlying library detects that regex pattern and warns, suggesting `fix_mistral_regex=True` to
+fix the splitting. This service loads the model via qwen-asr's high-level API and does not
+construct the tokenizer directly, so it does not expose this flag — hence the warning prints
+as-is.
+
+**Impact**: measured to have no visible effect on Chinese ASR transcripts (**spot-checked**
+multiple transcripts as normal; no CER quantification). That regex fix mainly affects the
+boundary splitting of certain special tokens, and no difference was observed on the speech
+transcription path. It's "notice-level" noise and can be ignored. To eliminate it entirely you'd
+pass `fix_mistral_regex=True` when loading the tokenizer at a lower level, but the qwen-asr
+high-level API doesn't directly support that, and there's no measured need.
+
+---
+
+### Aside: two other startup log lines (both harmless)
+
+- `Error retrieving safetensors: Repo id must be in the form ...`: it treats the local model
+ path as an HF repo id to fetch online metadata, fails, retries twice, and falls back to local
+ loading — no functional impact. Can be silenced with the env var `HF_HUB_OFFLINE=1`.
+
+- `Downcasting torch.float32 to torch.bfloat16`: weights are stored as fp32 and loaded as bf16,
+ normally saving VRAM / speeding things up; bf16 has the same exponent width as fp32, so
+ precision loss is negligible. This is INFO, not an error.
diff --git a/tests/test_qwen3_asr_ws_example.py b/tests/test_qwen3_asr_ws_example.py
new file mode 100644
index 000000000..9b0bd9d22
--- /dev/null
+++ b/tests/test_qwen3_asr_ws_example.py
@@ -0,0 +1,56 @@
+import ast
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLE_DIR = ROOT / "examples" / "industrial_data_pretraining" / "qwen3_asr"
+SERVER_PATH = EXAMPLE_DIR / "serve_qwen3_asr_ws.py"
+NOTE_PATHS = [
+ EXAMPLE_DIR / "serve_qwen3_asr_ws_notes.md",
+ EXAMPLE_DIR / "serve_qwen3_asr_ws_notes_en.md",
+]
+
+
+class Qwen3AsrWebsocketExampleTest(unittest.TestCase):
+ def test_notes_do_not_contain_review_placeholders(self):
+ forbidden_phrases = ["以下是我的个人理解", "The following is my personal understanding"]
+ for note_path in NOTE_PATHS:
+ text = note_path.read_text(encoding="utf-8")
+ for phrase in forbidden_phrases:
+ with self.subTest(path=note_path.name, phrase=phrase):
+ self.assertNotIn(phrase, text)
+
+ def test_handler_logs_unexpected_exceptions(self):
+ tree = ast.parse(SERVER_PATH.read_text(encoding="utf-8"), filename=str(SERVER_PATH))
+ handle_client = next(
+ node
+ for node in tree.body
+ if isinstance(node, ast.AsyncFunctionDef) and node.name == "handle_client"
+ )
+
+ catches_generic_exception = False
+ logs_exception = False
+ for node in ast.walk(handle_client):
+ if not isinstance(node, ast.ExceptHandler):
+ continue
+ if isinstance(node.type, ast.Name) and node.type.id == "Exception":
+ catches_generic_exception = True
+ for child in ast.walk(node):
+ if not isinstance(child, ast.Call):
+ continue
+ func = child.func
+ if (
+ isinstance(func, ast.Attribute)
+ and isinstance(func.value, ast.Name)
+ and func.value.id == "logging"
+ and func.attr == "exception"
+ ):
+ logs_exception = True
+
+ self.assertTrue(catches_generic_exception)
+ self.assertTrue(logs_exception)
+
+
+if __name__ == "__main__":
+ unittest.main()