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
Add Qwen3-ASR dependency guard
zhifu gao9b4f70042639
diff --git a/docs/tutorial/README.md b/docs/tutorial/README.mdindex 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)```pythondiff --git a/docs/tutorial/README_zh.md b/docs/tutorial/README_zh.mdindex 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)```pythondiff --git a/examples/industrial_data_pretraining/qwen3_asr/demo.py b/examples/industrial_data_pretraining/qwen3_asr/demo.pyindex 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" acceleratefrom funasr import AutoModeldiff --git a/examples/industrial_data_pretraining/qwen3_asr/demo_ms.py b/examples/industrial_data_pretraining/qwen3_asr/demo_ms.pyindex 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" acceleratefrom funasr import AutoModeldiff --git a/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.py b/examples/industrial_data_pretraining/qwen3_asr/serve_qwen3_asr_ws.pyindex 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.pyindex 00feb4918..314219624 100644--- a/funasr/models/qwen3_asr/model.py+++ b/funasr/models/qwen3_asr/model.py@@ -1,6 +1,9 @@import loggingimport osimport time+from importlib.metadata import PackageNotFoundError+from importlib.metadata import requires as _package_requires+from importlib.metadata import version as _package_versionfrom typing import List, Optional, Unionimport numpy as np@@ -10,6 +13,71 @@ import torch.nn as nnfrom 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" accelerateModels:- 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 Qwen3ASRModelexcept ImportError as e:# Only catch if the package itself is missing, not if its dependencies are brokenif "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 eraise ediff --git a/tests/test_qwen3_asr_dependency_check.py b/tests/test_qwen3_asr_dependency_check.pynew file mode 100644index 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()