Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Load Qwen3-ASR checkpoints saved in the qwen-asr package layout (#14716)

Daniel Han862f1c384bc9
diff --git a/tests/python/test_qwen3_asr_package_layout.py b/tests/python/test_qwen3_asr_package_layout.py
new file mode 100644
index 00000000000..ce36f0d3072
--- /dev/null
+++ b/tests/python/test_qwen3_asr_package_layout.py
@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team.
+
+"""Qwen3-ASR checkpoints in the qwen-asr package layout (Qwen/Qwen3-ASR-0.6B, -1.7B) load their real weights."""
+
+import ast
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+UTILS_PATH = REPO_ROOT / "unsloth" / "models" / "_utils.py"
+LOADER_PATH = REPO_ROOT / "unsloth" / "models" / "loader.py"
+
+
+def _helpers():
+ tree = ast.parse(UTILS_PATH.read_text(encoding = "utf-8"))
+ wanted = {"_QWEN3_ASR_PACKAGE_KEY_MAPPING", "_convert_qwen3_asr_package_config"}
+ nodes = [
+ n
+ for n in tree.body
+ if (isinstance(n, ast.FunctionDef) and n.name in wanted)
+ or (isinstance(n, ast.Assign) and any(getattr(t, "id", None) in wanted for t in n.targets))
+ ]
+ ns = {"re": re}
+ exec(compile(ast.Module(nodes, []), str(UTILS_PATH), "exec"), ns)
+ return ns["_convert_qwen3_asr_package_config"], ns["_QWEN3_ASR_PACKAGE_KEY_MAPPING"]
+
+
+def _tiny_native():
+ torch = pytest.importorskip("torch")
+ transformers = pytest.importorskip("transformers")
+ Config = getattr(transformers, "Qwen3ASRConfig", None)
+ Model = getattr(transformers, "Qwen3ASRForConditionalGeneration", None)
+ if Config is None or Model is None:
+ pytest.skip("transformers has no Qwen3-ASR")
+ audio = dict(
+ d_model = 32,
+ encoder_layers = 1,
+ encoder_attention_heads = 2,
+ encoder_ffn_dim = 64,
+ output_dim = 32,
+ downsample_hidden_size = 16,
+ num_mel_bins = 128,
+ )
+ text = dict(
+ hidden_size = 32,
+ intermediate_size = 64,
+ num_hidden_layers = 1,
+ num_attention_heads = 2,
+ num_key_value_heads = 1,
+ head_dim = 16,
+ vocab_size = 256,
+ )
+ config = Config(
+ audio_config = audio,
+ text_config = text,
+ audio_token_id = 5,
+ pad_token_id = 0,
+ eos_token_id = 1,
+ tie_word_embeddings = True,
+ )
+ torch.manual_seed(0)
+ return Model(config).eval(), audio, text
+
+
+def _package_layout(model, audio, text, path):
+ """Re-save a native model the way the qwen-asr package does."""
+ import json
+ from safetensors.torch import save_file
+
+ inverse = [
+ (r"^model\.multi_modal_projector\.linear_1\.", "thinker.audio_tower.proj1."),
+ (r"^model\.multi_modal_projector\.linear_2\.", "thinker.audio_tower.proj2."),
+ (r"^model\.audio_tower\.", "thinker.audio_tower."),
+ (r"^model\.language_model\.", "thinker.model."),
+ (r"^lm_head\.", "thinker.lm_head."),
+ ]
+ out = {}
+ for key, value in model.state_dict().items():
+ for pattern, repl in inverse:
+ if re.match(pattern, key):
+ key = re.sub(pattern, repl, key, count = 1)
+ break
+ out[key] = value.contiguous().clone()
+ save_file(out, str(path / "model.safetensors"), metadata = {"format": "pt"})
+ thinker = {
+ "model_type": "qwen3_asr",
+ "audio_config": audio,
+ "text_config": text,
+ "audio_token_id": 5,
+ "pad_token_id": 0,
+ "eos_token_id": 1,
+ "tie_word_embeddings": True,
+ }
+ (path / "config.json").write_text(
+ json.dumps(
+ {
+ "architectures": ["Qwen3ASRForConditionalGeneration"],
+ "model_type": "qwen3_asr",
+ "thinker_config": thinker,
+ }
+ )
+ )
+
+
+def test_package_layout_loads_the_checkpoint_weights(tmp_path):
+ import torch
+ from transformers import AutoConfig, Qwen3ASRForConditionalGeneration
+
+ convert, mapping = _helpers()
+ native, audio, text = _tiny_native()
+ _package_layout(native, audio, text, tmp_path)
+
+ plain = AutoConfig.from_pretrained(tmp_path)
+ assert (
+ plain.text_config.hidden_size != text["hidden_size"]
+ ) # the defect: sizes fall back to defaults
+
+ config, key_mapping = convert(plain)
+ assert key_mapping == mapping
+ assert config.text_config.hidden_size == text["hidden_size"]
+ assert config.audio_config.output_dim == audio["output_dim"]
+
+ loaded = Qwen3ASRForConditionalGeneration.from_pretrained(
+ tmp_path, config = config, key_mapping = key_mapping
+ )
+ want, got = native.state_dict(), loaded.state_dict()
+ assert set(want) == set(got)
+ assert all(torch.equal(want[k], got[k]) for k in want)
+
+
+def test_native_and_other_configs_pass_through():
+ convert, _ = _helpers()
+ native, _, _ = _tiny_native()
+ assert convert(native.config) == (native.config, None)
+ converted, mapping = convert(native.config)
+ assert convert(converted)[1] is None # idempotent
+
+ class Other:
+ model_type = "qwen2_audio"
+ thinker_config = {"audio_config": {}, "text_config": {}}
+
+ other = Other()
+ assert convert(other) == (other, None)
+
+ class Aligner: # Qwen/Qwen3-ForcedAligner-0.6B: same layout, classifier head
+ model_type = "qwen3_asr"
+ thinker_config = {
+ "model_type": "qwen3_forced_aligner",
+ "audio_config": {},
+ "text_config": {},
+ }
+
+ aligner = Aligner()
+ assert convert(aligner) == (aligner, None)
+
+
+def test_fast_model_applies_and_drops_the_mapping():
+ source = LOADER_PATH.read_text(encoding = "utf-8")
+ assert "_convert_qwen3_asr_package_config(model_config)" in source
+ assert "if user_config is None and not fast_inference:" in source
+ assert "_drop_text_only_key_mapping(model, _qwen3_asr_key_mapping)" in source
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index af3000a45dd..0349eff00c1 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -2060,6 +2060,54 @@ def _install_text_only_conversion_carry():
modeling_utils.get_model_conversion_mapping = get_model_conversion_mapping
+# Qwen/Qwen3-ASR-0.6B and -1.7B ship the qwen-asr package layout: sub-configs under thinker_config and
+# weights under thinker.*. transformers' Qwen3ASRConfig reads no thinker_config, so it builds a
+# default-sized model that matches none of the checkpoint's weights (the -hf repos are native).
+_QWEN3_ASR_PACKAGE_KEY_MAPPING = {
+ r"^thinker\.audio_tower\.proj1\.": "model.multi_modal_projector.linear_1.",
+ r"^thinker\.audio_tower\.proj2\.": "model.multi_modal_projector.linear_2.",
+ r"^thinker\.audio_tower\.": "model.audio_tower.",
+ r"^thinker\.model\.": "model.language_model.",
+ r"^thinker\.lm_head\.": "lm_head.",
+}
+
+
+def _convert_qwen3_asr_package_config(config):
+ """(native config, key_mapping) for a qwen-asr package layout Qwen3-ASR config, else (config, None)."""
+ if getattr(config, "model_type", None) != "qwen3_asr":
+ return config, None
+ thinker = getattr(config, "thinker_config", None)
+ if not isinstance(thinker, dict) or not {"audio_config", "text_config"} <= set(thinker):
+ return config, None
+ # Qwen3-ForcedAligner shares the layout but is a classifier (thinker model_type qwen3_forced_aligner).
+ if thinker.get("model_type", "qwen3_asr") != "qwen3_asr":
+ return config, None
+ native = type(config)
+
+ def sub(d):
+ return {k: v for k, v in dict(d).items() if k != "model_type"}
+
+ extra = {
+ k: thinker[k]
+ for k in (
+ "audio_token_id",
+ "pad_token_id",
+ "eos_token_id",
+ "initializer_range",
+ "tie_word_embeddings",
+ )
+ if k in thinker
+ }
+ new = native(
+ audio_config = sub(thinker["audio_config"]), text_config = sub(thinker["text_config"]), **extra
+ )
+ new.architectures = ["Qwen3ASRForConditionalGeneration"]
+ for k in ("_name_or_path", "_commit_hash"):
+ if hasattr(config, k):
+ setattr(new, k, getattr(config, k))
+ return new, dict(_QWEN3_ASR_PACKAGE_KEY_MAPPING)
+
+
def _apply_text_only_key_mapping(kwargs, parent_config, text_config):
# Add the text-only key_mapping to from_pretrained kwargs, under any user mapping.
mapping = _get_text_only_key_mapping(parent_config, text_config)
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index b51baf2a3fe..96879177d79 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -189,6 +189,7 @@ from ._utils import (
_apply_text_only_key_mapping,
_get_remote_composite_text_only,
_merge_key_mapping,
+ _convert_qwen3_asr_package_config,
_rebase_user_quantization_config,
_drop_text_only_key_mapping,
_adapter_fits_text_model,
@@ -2934,6 +2935,16 @@ class FastModel(FastBaseModel):
old_model_name, kwargs, require_processor = _ckpt_is_vlm
)
+ _qwen3_asr_key_mapping = None
+ # vLLM reads the package layout (thinker_config) itself, so fast_inference keeps the repo config.
+ if user_config is None and not fast_inference:
+ model_config, _qwen3_asr_key_mapping = _convert_qwen3_asr_package_config(model_config)
+ if _qwen3_asr_key_mapping:
+ _merge_key_mapping(kwargs, _qwen3_asr_key_mapping)
+ print(
+ f"Unsloth: {old_model_name} uses the qwen-asr package layout; "
+ "converting it to transformers' Qwen3-ASR format while loading."
+ )
# Capture task intent before text_only can replace a parent VLM config with its nested text config.
task_config_attrs = _get_user_task_config_attrs(user_config)
for _cfg_key in ("num_labels", "id2label", "label2id", "problem_type"):
@@ -3228,6 +3239,8 @@ class FastModel(FastBaseModel):
**kwargs,
)
_drop_text_only_key_mapping(model, _text_key_mapping)
+ # Saves write the native layout, matching the converted config.
+ _drop_text_only_key_mapping(model, _qwen3_asr_key_mapping)
_record_modelscope_repo_id(model, modelscope_repo_id, modelscope_dir)
if resize_model_vocab is not None: