Skip to content

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

Add Qwen3-ASR dependency guard

zhifu gao9b4f70042639
diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md
index 4822d3016..f75fd4760 100644
--- a/docs/tutorial/README.md
+++ b/docs/tutorial/README.md
@@ -258,7 +258,7 @@ print(res[0]["text"])
res = model.generate(input="audio.wav")
print(res[0]["text"], res[0].get("language", ""))
```
-Notes: Requires `pip install qwen-asr`. Supports 0.6B and 1.7B model sizes.
+Notes: Use `pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate`. `qwen-asr==0.0.6` pins `transformers==4.57.6`; newer incompatible Transformers builds may fail with nested `thinker_config` errors. Supports 0.6B and 1.7B model sizes.
#### Multi-language ASR (GLM-ASR)
```python
diff --git a/docs/tutorial/README_zh.md b/docs/tutorial/README_zh.md
index aa96952c0..7ad75345c 100644
--- a/docs/tutorial/README_zh.md
+++ b/docs/tutorial/README_zh.md
@@ -237,7 +237,7 @@ print(res[0]["text"])
res = model.generate(input="audio.wav")
print(res[0]["text"], res[0].get("language", ""))
```
-注:需要安装 `pip install qwen-asr`。支持 0.6B 和 1.7B 两种模型规格。
+注:请使用 `pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate`。`qwen-asr==0.0.6` 锁定 `transformers==4.57.6`;若环境中混入不兼容的新版 Transformers,可能触发嵌套 `thinker_config` 报错。支持 0.6B 和 1.7B 两种模型规格。
#### 多语言语音识别 (GLM-ASR)
```python
diff --git a/examples/industrial_data_pretraining/qwen3_asr/demo.py b/examples/industrial_data_pretraining/qwen3_asr/demo.py
index 277508d97..5bdb1f087 100644
--- a/examples/industrial_data_pretraining/qwen3_asr/demo.py
+++ b/examples/industrial_data_pretraining/qwen3_asr/demo.py
@@ -3,7 +3,7 @@
# Copyright FunASR (https://github.com/alibaba-damo-academy/FunASR). All Rights Reserved.
# MIT License (https://opensource.org/licenses/MIT)
-# To install requirements: pip install qwen-asr
+# To install requirements: pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate
from funasr import AutoModel
diff --git a/examples/industrial_data_pretraining/qwen3_asr/demo_ms.py b/examples/industrial_data_pretraining/qwen3_asr/demo_ms.py
index b56741b0d..7debfe71f 100644
--- a/examples/industrial_data_pretraining/qwen3_asr/demo_ms.py
+++ b/examples/industrial_data_pretraining/qwen3_asr/demo_ms.py
@@ -3,7 +3,7 @@
# Copyright FunASR (https://github.com/alibaba-damo-academy/FunASR). All Rights Reserved.
# MIT License (https://opensource.org/licenses/MIT)
-# To install requirements: pip install qwen-asr
+# To install requirements: pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate
from funasr import AutoModel
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
index 6e7e0789d..af9f82b4c 100644
--- a/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py
+++ b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py
@@ -26,7 +26,7 @@ finish_streaming_transcribe 同步调用、阻塞整个循环——这样压测
依赖:
- pip install qwen-asr[vllm] websockets numpy
+ pip install -U "qwen-asr[vllm]==0.0.6" "transformers==4.57.6" websockets numpy
启动:
python serve_qwen3_asr_ws.py --port 10095 --gpu-memory-utilization 0.8
# 可选:--chunk-size-sec 控制流式块大小(默认 2.0)。值越小出字越快/越勤,
diff --git a/funasr/models/qwen3_asr/model.py b/funasr/models/qwen3_asr/model.py
index 00feb4918..314219624 100644
--- a/funasr/models/qwen3_asr/model.py
+++ b/funasr/models/qwen3_asr/model.py
@@ -1,6 +1,9 @@
import logging
import os
import time
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import requires as _package_requires
+from importlib.metadata import version as _package_version
from typing import List, Optional, Union
import numpy as np
@@ -10,6 +13,71 @@ import torch.nn as nn
from funasr.register import tables
+def _qwen_asr_transformers_specifier():
+ try:
+ from packaging.requirements import InvalidRequirement, Requirement
+ except ImportError:
+ return None
+
+ requirements = _package_requires("qwen-asr") or []
+ for requirement_text in requirements:
+ try:
+ requirement = Requirement(requirement_text)
+ except InvalidRequirement:
+ continue
+ if requirement.name.lower() == "transformers":
+ return requirement.specifier
+ return None
+
+
+def _qwen_asr_install_command(qwen_asr_version, transformers_specifier=None):
+ if transformers_specifier:
+ transformers_requirement = f"transformers{transformers_specifier}"
+ return (
+ f'pip install -U "qwen-asr=={qwen_asr_version}" '
+ f'"{transformers_requirement}" accelerate'
+ )
+ return 'pip install -U "qwen-asr" transformers accelerate'
+
+
+def _check_qwen3_asr_dependencies():
+ try:
+ qwen_asr_version = _package_version("qwen-asr")
+ except PackageNotFoundError as e:
+ raise ImportError(
+ 'qwen-asr package is required for Qwen3-ASR. Install with: pip install -U "qwen-asr"'
+ ) from e
+
+ try:
+ transformers_version = _package_version("transformers")
+ except PackageNotFoundError as e:
+ raise ImportError(
+ "transformers is required by qwen-asr. "
+ f"Install with: {_qwen_asr_install_command(qwen_asr_version)}"
+ ) from e
+
+ transformers_specifier = _qwen_asr_transformers_specifier()
+ if transformers_specifier:
+ try:
+ from packaging.version import InvalidVersion, Version
+
+ Version(transformers_version)
+ is_compatible = transformers_version in transformers_specifier
+ except InvalidVersion:
+ is_compatible = True
+
+ if not is_compatible:
+ install_command = _qwen_asr_install_command(qwen_asr_version, transformers_specifier)
+ raise ImportError(
+ "Qwen3-ASR dependency mismatch: "
+ f"qwen-asr=={qwen_asr_version} requires transformers{transformers_specifier}, "
+ f"but the active environment has transformers=={transformers_version}. "
+ "This can trigger qwen_asr errors such as "
+ "`AttributeError: 'Qwen3ASRConfig' object has no attribute 'thinker_config'`. "
+ f"Run: {install_command}"
+ )
+
+
# qwen-asr's validate_language() only accepts canonical full names ("Chinese", "English",
# ...), but FunASR documents short/ISO codes ("zh", "en", "auto") as valid language hints.
# Defined at module level so the lookup table is built once, not on every inference call.
@@ -37,7 +105,7 @@ class Qwen3ASR(nn.Module):
for character-level timestamps.
Requirements:
- pip install qwen-asr
+ pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate
Models:
- Qwen/Qwen3-ASR-0.6B (lighter, ~4GB GPU memory)
@@ -67,13 +135,14 @@ class Qwen3ASR(nn.Module):
model_path = self._resolve_model_path(model_path, hub, kwargs)
self.model_path = model_path
+ _check_qwen3_asr_dependencies()
try:
from qwen_asr import Qwen3ASRModel
except ImportError as e:
# Only catch if the package itself is missing, not if its dependencies are broken
if "qwen_asr" in str(e):
raise ImportError(
- "qwen-asr package is required. Install with: pip install qwen-asr"
+ 'qwen-asr package is required. Install with: pip install -U "qwen-asr"'
) from e
raise e
diff --git a/tests/test_qwen3_asr_dependency_check.py b/tests/test_qwen3_asr_dependency_check.py
new file mode 100644
index 000000000..ad4563f15
--- /dev/null
+++ b/tests/test_qwen3_asr_dependency_check.py
@@ -0,0 +1,91 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT))
+
+from funasr.models.qwen3_asr import model as qwen3_model
+
+
+def test_qwen3_asr_dependency_check_reports_transformers_mismatch(monkeypatch):
+ def fake_version(package_name):
+ versions = {
+ "qwen-asr": "0.0.6",
+ "transformers": "5.5.0",
+ }
+ return versions[package_name]
+
+ def fake_requires(package_name):
+ assert package_name == "qwen-asr"
+ return ["transformers==4.57.6", "accelerate==1.12.0"]
+
+ monkeypatch.setattr(qwen3_model, "_package_version", fake_version)
+ monkeypatch.setattr(qwen3_model, "_package_requires", fake_requires)
+
+ with pytest.raises(ImportError) as exc_info:
+ qwen3_model._check_qwen3_asr_dependencies()
+
+ message = str(exc_info.value)
+ assert "Qwen3-ASR dependency mismatch" in message
+ assert "qwen-asr==0.0.6 requires transformers==4.57.6" in message
+ assert "active environment has transformers==5.5.0" in message
+ assert 'pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate' in message
+
+
+def test_qwen3_asr_dependency_check_accepts_matching_transformers(monkeypatch):
+ def fake_version(package_name):
+ versions = {
+ "qwen-asr": "0.0.6",
+ "transformers": "4.57.6",
+ }
+ return versions[package_name]
+
+ def fake_requires(package_name):
+ assert package_name == "qwen-asr"
+ return ["transformers==4.57.6", "accelerate==1.12.0"]
+
+ monkeypatch.setattr(qwen3_model, "_package_version", fake_version)
+ monkeypatch.setattr(qwen3_model, "_package_requires", fake_requires)
+
+ qwen3_model._check_qwen3_asr_dependencies()
+
+
+def test_qwen3_asr_dependency_check_matches_requirement_names_case_insensitively(monkeypatch):
+ def fake_version(package_name):
+ versions = {
+ "qwen-asr": "0.0.6",
+ "transformers": "5.5.0",
+ }
+ return versions[package_name]
+
+ def fake_requires(package_name):
+ assert package_name == "qwen-asr"
+ return ["Transformers==4.57.6"]
+
+ monkeypatch.setattr(qwen3_model, "_package_version", fake_version)
+ monkeypatch.setattr(qwen3_model, "_package_requires", fake_requires)
+
+ with pytest.raises(ImportError) as exc_info:
+ qwen3_model._check_qwen3_asr_dependencies()
+
+ assert "requires transformers==4.57.6" in str(exc_info.value)
+
+
+def test_qwen3_asr_dependency_check_does_not_crash_on_non_pep440_transformers(monkeypatch):
+ def fake_version(package_name):
+ versions = {
+ "qwen-asr": "0.0.6",
+ "transformers": "custom-main",
+ }
+ return versions[package_name]
+
+ def fake_requires(package_name):
+ assert package_name == "qwen-asr"
+ return ["transformers==4.57.6"]
+
+ monkeypatch.setattr(qwen3_model, "_package_version", fake_version)
+ monkeypatch.setattr(qwen3_model, "_package_requires", fake_requires)
+
+ qwen3_model._check_qwen3_asr_dependencies()