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 and QLoRA-train Moonshine Streaming checkpoints (#14945)

Daniel Hana3e7ac70b11e
diff --git a/tests/python/test_feature_extractor_only_checkpoints.py b/tests/python/test_feature_extractor_only_checkpoints.py
index c285a2e4e14..4a8b0a6cdae 100644
--- a/tests/python/test_feature_extractor_only_checkpoints.py
+++ b/tests/python/test_feature_extractor_only_checkpoints.py
@@ -125,7 +125,8 @@ def test_default_auto_model_loads_the_checkpoints_own_audio_head():
source = LOADER_PATH.read_text(encoding = "utf-8")
flat = "".join(source.split())
assert "_resolve_audio_auto_model(model_config,**_probe_hub_kwargs)" in flat
- assert "include_bare=resolve_model_class(auto_model,model_config,**_probe_hub_kwargs)" in flat
+ assert "auto_model=_resolve_non_vlm_auto_model(model_config,**_probe_hub_kwargs)" in flat
+ assert "include_bare=notcausal_maps" in flat
def test_audio_processor_frontends_are_right_padded_too():
diff --git a/tests/python/test_moonshine_4bit_head_skip.py b/tests/python/test_moonshine_4bit_head_skip.py
new file mode 100644
index 00000000000..7e0e238587b
--- /dev/null
+++ b/tests/python/test_moonshine_4bit_head_skip.py
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team.
+
+"""Moonshine's LM head is `proj_out`; untied on moonshine-streaming, so 4-bit loads quantized it and the
+fused CE loss failed reading it as a plain weight (`mat1 and mat2 shapes cannot be multiplied`)."""
+
+import ast
+from pathlib import Path
+
+import pytest
+
+VISION_PATH = Path(__file__).resolve().parents[2] / "unsloth" / "models" / "vision.py"
+
+
+def _architecture_skip_modules():
+ tree = ast.parse(VISION_PATH.read_text(encoding = "utf-8"))
+ node = next(
+ n
+ for n in tree.body
+ if isinstance(n, ast.FunctionDef) and n.name == "_architecture_skip_modules"
+ )
+ ns = {}
+ exec(compile(ast.Module([node], []), str(VISION_PATH), "exec"), ns)
+ return ns["_architecture_skip_modules"]
+
+
+def test_moonshine_keeps_its_lm_head_unquantized():
+ skip = _architecture_skip_modules()
+ for model_types in (["moonshine_streaming", "moonshine_streaming_encoder"], ["moonshine"]):
+ assert "proj_out" in skip(model_types), model_types
+ for model_types in (["whisper"], ["llama"], ["gemma3n"], [], None):
+ assert "proj_out" not in skip(model_types), model_types
+
+
+def test_only_the_head_matches_the_transformers_skip_matcher():
+ torch = pytest.importorskip("torch")
+ transformers = pytest.importorskip("transformers")
+ utils = pytest.importorskip("transformers.quantizers.quantizers_utils")
+ should_convert = getattr(utils, "should_convert_module", None)
+ config_class = getattr(transformers, "MoonshineStreamingConfig", None)
+ if should_convert is None or config_class is None:
+ pytest.skip("needs transformers 5 with Moonshine Streaming")
+ config = config_class(
+ encoder_config = {
+ "hidden_size": 32,
+ "intermediate_size": 64,
+ "num_hidden_layers": 1,
+ "num_attention_heads": 2,
+ "num_key_value_heads": 2,
+ },
+ hidden_size = 32,
+ intermediate_size = 64,
+ num_hidden_layers = 1,
+ num_attention_heads = 2,
+ num_key_value_heads = 2,
+ vocab_size = 128,
+ )
+ with torch.device("meta"):
+ model = transformers.AutoModelForSpeechSeq2Seq.from_config(config)
+ skip = _architecture_skip_modules()(["moonshine_streaming"])
+ kept = [
+ n
+ for n, m in model.named_modules()
+ if isinstance(m, torch.nn.Linear) and not should_convert(n, skip)
+ ]
+ assert kept == ["proj_out"]
diff --git a/tests/test_audio_load_routing.py b/tests/test_audio_load_routing.py
index 1cd69f19bdd..90b8f1b50bd 100644
--- a/tests/test_audio_load_routing.py
+++ b/tests/test_audio_load_routing.py
@@ -17,6 +17,7 @@ from unsloth.models._utils import ( # noqa: E402
)
from unsloth.models.loader import ( # noqa: E402
_resolve_audio_lm_auto_model,
+ _resolve_non_vlm_auto_model,
_resolve_omni_auto_model,
_resolve_speech_seq2seq_auto_model,
)
@@ -100,3 +101,26 @@ def test_audio_lm_routing_never_takes_text_or_vision_models():
continue
assert _resolve_audio_lm_auto_model(config_class()) is None
assert _audio_lm_class(transformers.AutoModelForCausalLM, config_class()) is None
+
+
+def test_config_without_architectures_loads_its_speech_seq2seq_class():
+ """moonshine-ai/moonshine-streaming-* ship a config with no `architectures`, and no causal-LM class maps it."""
+ config_class = getattr(transformers, "MoonshineStreamingConfig", None)
+ if config_class is None:
+ pytest.skip("this transformers has no Moonshine Streaming")
+ config = config_class()
+ assert not getattr(config, "architectures", None)
+ assert _resolve_non_vlm_auto_model(config) is transformers.AutoModelForSpeechSeq2Seq
+
+
+ "config, expected",
+ [
+ (lambda: transformers.LlamaConfig(), "AutoModelForCausalLM"),
+ (lambda: transformers.WhisperConfig(), "AutoModelForCausalLM"),
+ (lambda: transformers.Wav2Vec2Config(), "AutoModelForCausalLM"),
+ (lambda: transformers.Wav2Vec2Config(architectures = ["Wav2Vec2ForCTC"]), "AutoModelForCTC"),
+ ],
+)
+def test_non_vlm_routing_keeps_every_other_route(config, expected):
+ assert _resolve_non_vlm_auto_model(config()).__name__ == expected
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 8fd7fc0cf89..38d4f69baaa 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -833,6 +833,18 @@ def _resolve_audio_auto_model(
return None
+def _resolve_non_vlm_auto_model(model_config, **hub_kwargs):
+ """CTC / audio classification / bare audio encoders load their own head. A causal-LM mapping
+ (WhisperConfig -> WhisperForCausalLM) yields only to an audio head the checkpoint names."""
+ causal_maps = resolve_model_class(AutoModelForCausalLM, model_config, **hub_kwargs) is not None
+ return (
+ _resolve_audio_auto_model(model_config, include_bare = not causal_maps, **hub_kwargs)
+ # moonshine-streaming's repo config names no architectures; only its speech seq2seq class builds it.
+ or (None if causal_maps else _resolve_speech_seq2seq_auto_model(model_config, **hub_kwargs))
+ or AutoModelForCausalLM
+ )
+
+
def _get_user_task_config_attrs(user_config):
if user_config is None:
return {}
@@ -3221,20 +3233,7 @@ class FastModel(FastBaseModel):
or auto_model
)
else:
- auto_model = AutoModelForCausalLM
- # CTC / audio classification / bare audio encoders load their own head. A causal-LM mapping
- # (WhisperConfig -> WhisperForCausalLM) yields only to an audio head the checkpoint names.
- auto_model = (
- _resolve_audio_auto_model(
- model_config,
- include_bare = resolve_model_class(
- auto_model, model_config, **_probe_hub_kwargs
- )
- is None,
- **_probe_hub_kwargs,
- )
- or auto_model
- )
+ auto_model = _resolve_non_vlm_auto_model(model_config, **_probe_hub_kwargs)
load_in_4bit_kwargs = load_in_4bit
load_in_8bit_kwargs = load_in_8bit
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 7d892d5a7aa..12c3dd415e7 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -2739,6 +2739,9 @@ def _architecture_skip_modules(model_types):
# Gemma 3n AltUp clamps prediction_coefs.weight.data in place every training step, which fails on packed
# uint8 weights; the same four modules unsloth/gemma-3n-*-unsloth-bnb-4bit keeps in 16-bit.
# transformers 5 matches a skip key as a suffix of each Linear's name, so the ModuleList children are listed too.
+ # Moonshine's LM head is proj_out (untied on moonshine-streaming): kept 16-bit like lm_head, which the fused CE loss reads as a plain weight.
+ if any(mt in ("moonshine", "moonshine_streaming") for mt in model_types):
+ skip.append("proj_out")
if any(mt.startswith("gemma3n") for mt in model_types):
skip.extend(("correction_coefs", "prediction_coefs"))
for name in ("altup_projections", "altup_unembed_projections"):