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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Load 4.x remote code and config-only remote code on transformers 5 (Trinity-Large, MiniMax-M3) (#11658)
Daniel Han5e39eeada9d2
diff --git a/tests/test_attn_dtype_custom_datatype.py b/tests/test_attn_dtype_custom_datatype.pyindex 1fe8e03d41a..d98cf2dc0e0 100644--- a/tests/test_attn_dtype_custom_datatype.py+++ b/tests/test_attn_dtype_custom_datatype.py@@ -82,6 +82,11 @@ def _selected(dtype, do_forced_float32, correct_dtype):"auto_model": None,"model_name": "","resolve_model_class": lambda *args, **kwargs: None,+ "model_class": None,+ "attention_class_for_load": lambda *args, **kwargs: (None, True),+ "_builds_remote_class": False,+ "_remote_class": None,+ "supports_sdpa": True,}module = ast.Module(body = list(PREAMBLE), type_ignores = [])ast.fix_missing_locations(module)diff --git a/tests/test_remote_code_non_persistent_buffers.py b/tests/test_remote_code_non_persistent_buffers.pyindex e4ae270876a..d87510a1480 100644--- a/tests/test_remote_code_non_persistent_buffers.py+++ b/tests/test_remote_code_non_persistent_buffers.py@@ -40,7 +40,13 @@ def _remote_module():if name in sys.modules:return sys.modules[name]module = types.ModuleType(name)- sys.modules.setdefault("transformers_modules", types.ModuleType("transformers_modules"))+ # The real package, never a bare stand-in: one without __path__ breaks the relative imports of+ # every remote module transformers loads later in this process.+ from transformers.dynamic_module_utils import create_dynamic_module++ create_dynamic_module("transformers_modules")+ import transformers_modules # noqa: F401+sys.modules[name] = moduleclass TinyRemoteConfig(PretrainedConfig):diff --git a/tests/test_remote_code_transformers5_compat.py b/tests/test_remote_code_transformers5_compat.pynew file mode 100644index 00000000000..b23bfb457ec--- /dev/null+++ b/tests/test_remote_code_transformers5_compat.py@@ -0,0 +1,431 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.++"""Tiny CPU repros of 4.x remote code (Trinity-Large), a remote class shadowing a native name, and config-only remote code (MiniMax-M3) on transformers 5."""++import json+import textwrap+from types import SimpleNamespace++import pytest++[email protected](scope = "module")+def unsloth_loaded():+ try:+ import unsloth # noqa: F401 installs the import fixes+ except Exception as e: # pragma: no cover - environment without a usable accelerator+ pytest.skip(f"unsloth does not import here: {e}")+ import transformers+ return transformers+++def _write(path, name, source):+ (path / name).write_text(textwrap.dedent(source))+++_LEGACY_CONFIG = """+from transformers import PretrainedConfig+++class LegacyToyConfig(PretrainedConfig):+ model_type = "legacy_toy"++ def __init__(self, vocab_size = 64, hidden_size = 32, num_attention_heads = 2,+ num_hidden_layers = 1, rope_theta = 10000.0, rope_scaling = None, **kwargs):+ self.vocab_size = vocab_size+ self.hidden_size = hidden_size+ self.num_attention_heads = num_attention_heads+ self.num_hidden_layers = num_hidden_layers+ self.rope_theta = rope_theta+ self.rope_scaling = rope_scaling+ super().__init__(**kwargs)+"""++_LEGACY_MODELING = """+import torch+from torch import nn+from transformers import PreTrainedModel+from transformers.masking_utils import create_causal_mask+from transformers.modeling_outputs import CausalLMOutput+from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS++try:+ from .configuration_legacy_toy import LegacyToyConfig+except ImportError:+ from configuration_legacy_toy import LegacyToyConfig+++class LegacyToyRotaryEmbedding(nn.Module):+ def __init__(self, config, device = None):+ super().__init__()+ if config.rope_scaling is not None:+ self.rope_type = config.rope_scaling.get("rope_type", config.rope_scaling.get("type"))+ else:+ self.rope_type = "default"+ self.config = config+ self.rope_init_fn = ROPE_INIT_FUNCTIONS[self.rope_type]+ inv_freq, self.attention_scaling = self.rope_init_fn(self.config, device)+ self.register_buffer("inv_freq", inv_freq, persistent = False)+ self.original_inv_freq = self.inv_freq+++class LegacyToyPreTrainedModel(PreTrainedModel):+ config_class = LegacyToyConfig+ base_model_prefix = "model"+ _supports_sdpa = True+++class LegacyToyForCausalLM(LegacyToyPreTrainedModel):+ _tied_weights_keys = ["lm_head.weight"]++ def __init__(self, config):+ super().__init__(config)+ self.padding_idx = config.pad_token_id+ self.embed_tokens = nn.Embedding(config.vocab_size, config.hidden_size, self.padding_idx)+ self.rotary_emb = LegacyToyRotaryEmbedding(config)+ self.lm_head = nn.Linear(config.hidden_size, config.vocab_size, bias = False)+ self.post_init()++ def forward(self, input_ids = None, attention_mask = None, labels = None, **kwargs):+ inputs_embeds = self.embed_tokens(input_ids)+ cache_position = torch.arange(input_ids.shape[1], device = input_ids.device)+ mask = create_causal_mask(+ config = self.config,+ input_embeds = inputs_embeds,+ attention_mask = attention_mask,+ cache_position = cache_position,+ past_key_values = None,+ position_ids = cache_position.unsqueeze(0),+ )+ logits = self.lm_head(inputs_embeds * self.rotary_emb.inv_freq.mean())+ loss = None+ if labels is not None:+ loss = nn.functional.cross_entropy(logits.flatten(0, 1).float(), labels.flatten())+ return CausalLMOutput(loss = loss, logits = logits)+"""+++def legacy_repo(tmp_path):+ _write(tmp_path, "configuration_legacy_toy.py", _LEGACY_CONFIG)+ _write(tmp_path, "modeling_legacy_toy.py", _LEGACY_MODELING)+ config = {+ "model_type": "legacy_toy",+ "architectures": ["LegacyToyForCausalLM"],+ "auto_map": {+ "AutoConfig": "configuration_legacy_toy.LegacyToyConfig",+ "AutoModelForCausalLM": "modeling_legacy_toy.LegacyToyForCausalLM",+ },+ "vocab_size": 64,+ "hidden_size": 32,+ "num_attention_heads": 2,+ "num_hidden_layers": 1,+ }+ (tmp_path / "config.json").write_text(json.dumps(config))+ return tmp_path+++def test_transformers4_remote_model_builds_and_runs(unsloth_loaded, legacy_repo):+ import torch+ from transformers import AutoConfig, AutoModelForCausalLM++ config = AutoConfig.from_pretrained(legacy_repo, trust_remote_code = True)+ assert config.pad_token_id is None+ model = AutoModelForCausalLM.from_config(config, trust_remote_code = True)+ input_ids = torch.randint(0, 64, (1, 8))+ out = model(input_ids = input_ids, attention_mask = torch.ones_like(input_ids), labels = input_ids)+ assert torch.isfinite(out.loss)+ dim = 32 // 2+ expected = 1.0 / (10000.0 ** (torch.arange(0, dim, 2).float() / dim))+ assert torch.allclose(model.rotary_emb.inv_freq.float(), expected)+++def test_a_remote_file_edited_between_loads_is_patched_again(unsloth_loaded, legacy_repo):+ """transformers 5.4 re-executes a changed remote file in the same module object; new classes need the defaults too."""+ from transformers import AutoConfig++ assert AutoConfig.from_pretrained(legacy_repo, trust_remote_code = True).pad_token_id is None+ source = legacy_repo / "configuration_legacy_toy.py"+ source.write_text(source.read_text() + "\n# edited between loads\n")+ config = AutoConfig.from_pretrained(legacy_repo, trust_remote_code = True)+ assert config.pad_token_id is None+++def test_checkpoint_token_ids_still_win(unsloth_loaded, legacy_repo):+ from transformers import AutoConfig++ config_json = json.loads((legacy_repo / "config.json").read_text())+ config_json["pad_token_id"] = 3+ (legacy_repo / "config.json").write_text(json.dumps(config_json))+ config = AutoConfig.from_pretrained(legacy_repo, trust_remote_code = True)+ assert config.pad_token_id == 3+ assert vars(config).get("bos_token_id") is None+ assert config.to_dict().get("bos_token_id") is None+++def test_native_rope_registry_is_left_alone(unsloth_loaded, legacy_repo):+ """A "default" key in ROPE_INIT_FUNCTIONS would override every native model's own in `_init_weights`."""+ from transformers import AutoConfig, AutoModelForCausalLM+ from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS++ had_default = "default" in ROPE_INIT_FUNCTIONS+ config = AutoConfig.from_pretrained(legacy_repo, trust_remote_code = True)+ AutoModelForCausalLM.from_config(config, trust_remote_code = True)+ assert ("default" in ROPE_INIT_FUNCTIONS) == had_default+++def test_legacy_defaults_touch_only_remote_classes(unsloth_loaded):+ from transformers import PretrainedConfig+ for name in ("pad_token_id", "bos_token_id", "eos_token_id"):+ assert name not in PretrainedConfig.__dict__+++_SHADOW_CONFIG = """+from transformers import LlamaConfig as _NativeLlamaConfig+++class LlamaConfig(_NativeLlamaConfig):+ pass+"""++_SHADOW_MODELING = """+from transformers import LlamaForCausalLM as _NativeLlamaForCausalLM++try:+ from .configuration_shadow import LlamaConfig+except ImportError:+ from configuration_shadow import LlamaConfig+++class LlamaForCausalLM(_NativeLlamaForCausalLM):+ config_class = LlamaConfig+ _supports_flash_attn = False+ _supports_flash_attn_2 = False+ _supports_sdpa = True+"""+++def shadow_repo(tmp_path):+ _write(tmp_path, "configuration_shadow.py", _SHADOW_CONFIG)+ _write(tmp_path, "modeling_shadow.py", _SHADOW_MODELING)+ config = {+ "model_type": "llama",+ "architectures": ["LlamaForCausalLM"],+ "auto_map": {+ "AutoConfig": "configuration_shadow.LlamaConfig",+ "AutoModelForCausalLM": "modeling_shadow.LlamaForCausalLM",+ },+ "vocab_size": 64,+ "hidden_size": 32,+ "intermediate_size": 64,+ "num_attention_heads": 2,+ "num_key_value_heads": 2,+ "num_hidden_layers": 1,+ }+ (tmp_path / "config.json").write_text(json.dumps(config))+ return tmp_path+++def test_remote_class_is_what_attention_is_resolved_for(unsloth_loaded, shadow_repo):+ from transformers import AutoConfig, AutoModelForCausalLM+ from unsloth.models._utils import resolve_model_class, resolve_remote_code_model_class++ config = AutoConfig.from_pretrained(shadow_repo, trust_remote_code = True)+ assert type(config).__module__.startswith("transformers_modules")+ native = resolve_model_class(AutoModelForCausalLM, config)+ assert native is not None and native.__module__.startswith("transformers.")++ builds_remote, remote = resolve_remote_code_model_class(+ AutoModelForCausalLM, config, str(shadow_repo), trust_remote_code = True+ )+ assert builds_remote is True+ assert remote is not None and remote.__module__.startswith("transformers_modules")+ assert remote._supports_flash_attn is False+++def test_remote_class_only_replaces_a_native_class_it_shadows(unsloth_loaded):+ from unsloth.models._utils import attention_class_for_load++ class Native:+ _supports_sdpa = True++ class Remote:+ _supports_flash_attn_2 = True+ _supports_sdpa = False++ assert attention_class_for_load(Native, True, Remote, True) == (Remote, False)+ # No native class shadowed: remote flags must not route a working load onto flash attention.+ assert attention_class_for_load(None, True, Remote, True) == (None, False)+ Remote._supports_sdpa = True+ assert attention_class_for_load(None, True, Remote, True) == (None, True)+ assert attention_class_for_load(None, True, None, True) == (None, True)+ assert attention_class_for_load(Native, True, None, True) == (None, False)+ assert attention_class_for_load(Native, False, None, True) == (Native, True)+++def test_remote_class_not_used_without_trust(unsloth_loaded, shadow_repo):+ from transformers import AutoModelForCausalLM, LlamaConfig+ from unsloth.models._utils import resolve_remote_code_model_class++ config = LlamaConfig.from_pretrained(shadow_repo)+ assert resolve_remote_code_model_class(+ AutoModelForCausalLM, config, str(shadow_repo), trust_remote_code = False+ ) == (False, None)+ from transformers import AutoModelForSequenceClassification++ assert resolve_remote_code_model_class(+ AutoModelForSequenceClassification, config, str(shadow_repo), trust_remote_code = True+ ) == (False, None)+++def test_only_an_exact_registration_overrides_remote_code(unsloth_loaded):+ """Only an exact registration of this config class overrides auto_map, not a registered parent."""+ import torch.nn as nn+ from transformers import AutoConfig, AutoModelForCausalLM, PretrainedConfig+ from unsloth.models._utils import resolve_remote_code_model_class++ class ParentConfig(PretrainedConfig):+ model_type = "unsloth_exact_registration_parent"++ class ParentModel(nn.Module):+ config_class = ParentConfig++ class RemoteChildConfig(ParentConfig):+ pass++ AutoConfig.register(ParentConfig.model_type, ParentConfig, exist_ok = True)+ AutoModelForCausalLM.register(ParentConfig, ParentModel, exist_ok = True)+ try:+ child = RemoteChildConfig(auto_map = {"AutoModelForCausalLM": "modeling_missing.Missing"})+ assert resolve_remote_code_model_class(+ AutoModelForCausalLM, child, "/nonexistent/unsloth/repo", trust_remote_code = True+ ) == (True, None)+ finally:+ AutoModelForCausalLM._model_mapping._extra_content.pop(ParentConfig, None)+ from transformers.models.auto.configuration_auto import CONFIG_MAPPING+ CONFIG_MAPPING._extra_content.pop(ParentConfig.model_type, None)+++def test_the_remote_class_lookup_uses_the_loads_code_revision(unsloth_loaded, monkeypatch):+ import transformers.dynamic_module_utils as dynamic_module_utils+ from transformers import AutoModelForCausalLM, LlamaConfig+ from unsloth.models import vision+ from unsloth.models._utils import resolve_remote_code_model_class++ seen = {}++ def fetch(class_ref, repo, **kwargs):+ seen.update(kwargs)+ return None++ monkeypatch.setattr(dynamic_module_utils, "get_class_from_dynamic_module", fetch)+ config = LlamaConfig(auto_map = {"AutoModelForCausalLM": "modeling_x.X"})+ options = {+ "code_revision": "abc",+ "cache_dir": "/cache",+ "proxies": {"https": "http://proxy"},+ "force_download": True,+ }+ resolve_remote_code_model_class(+ AutoModelForCausalLM, config, "some/repo", trust_remote_code = True, **options+ )+ assert {k: seen.get(k) for k in options} == options+ import inspect++ assert set(options) <= set(vision._REMOTE_CLASS_HUB_OPTIONS)+ assert "for k in _REMOTE_CLASS_HUB_OPTIONS" in inspect.getsource(vision)+++def test_unfetchable_remote_class_is_unknown_not_native(unsloth_loaded):+ from transformers import AutoModelForCausalLM, LlamaConfig+ from unsloth.models._utils import resolve_remote_code_model_class++ config = LlamaConfig(auto_map = {"AutoModelForCausalLM": "modeling_missing.Missing"})+ assert resolve_remote_code_model_class(+ AutoModelForCausalLM, config, "/nonexistent/unsloth/repo", trust_remote_code = True+ ) == (True, None)+++_CONFIG_ONLY = """+from transformers import PretrainedConfig+++class LlavaConfig(PretrainedConfig):+ model_type = "llava"++ def __init__(self, vision_config = None, text_config = None, **kwargs):+ # What a converter-facing shim does: keep the sub-configs generic.+ self.vision_config = PretrainedConfig(**(vision_config or {}))+ self.text_config = PretrainedConfig(**(text_config or {}))+ super().__init__(**kwargs)+"""+++def _config_only_repo(path, auto_map):+ _write(path, "configuration_shim.py", _CONFIG_ONLY)+ config = {+ "model_type": "llava",+ "architectures": ["LlavaForConditionalGeneration"],+ "auto_map": auto_map,+ "vision_config": {+ "model_type": "clip_vision_model",+ "hidden_size": 32,+ "intermediate_size": 64,+ "num_attention_heads": 2,+ },+ "text_config": {+ "model_type": "llama",+ "hidden_size": 32,+ "intermediate_size": 64,+ "num_attention_heads": 2,+ },+ }+ (path / "config.json").write_text(json.dumps(config))+ return path+++def test_config_only_remote_code_loads_the_native_config(unsloth_loaded, tmp_path):+ from transformers import AutoConfig, LlavaConfig++ repo = _config_only_repo(tmp_path, {"AutoConfig": "configuration_shim.LlavaConfig"})+ config = AutoConfig.from_pretrained(repo, trust_remote_code = True)+ assert type(config) is LlavaConfig+ assert type(config.vision_config).__name__ == "CLIPVisionConfig"+ assert type(AutoConfig.from_pretrained(repo)) is LlavaConfig+++def test_config_only_swap_keeps_return_unused_kwargs(unsloth_loaded, tmp_path):+ from transformers import AutoConfig, LlavaConfig++ repo = _config_only_repo(tmp_path, {"AutoConfig": "configuration_shim.LlavaConfig"})+ config, unused = AutoConfig.from_pretrained(+ repo, trust_remote_code = True, return_unused_kwargs = True, foo = 1+ )+ assert type(config) is LlavaConfig and unused == {"foo": 1}+++def test_repo_with_its_own_model_keeps_its_config(unsloth_loaded, tmp_path):+ from transformers import AutoConfig++ repo = _config_only_repo(+ tmp_path,+ {+ "AutoConfig": "configuration_shim.LlavaConfig",+ "AutoModelForImageTextToText": "modeling_shim.Model",+ },+ )+ config = AutoConfig.from_pretrained(repo, trust_remote_code = True)+ assert type(config).__module__.startswith("transformers_modules")+++def test_native_config_with_config_only_auto_map_keeps_the_compiler(unsloth_loaded):+ from transformers import LlamaConfig+ from unsloth.models.loader import _config_uses_remote_code++ native = LlamaConfig(auto_map = {"AutoConfig": "configuration_x.XConfig"})+ assert _config_uses_remote_code(native) is False+ native.auto_map = {"AutoConfig": "c.X", "AutoModelForCausalLM": "m.X"}+ assert _config_uses_remote_code(native) is True+ assert _config_uses_remote_code(SimpleNamespace(auto_map = {"AutoConfig": "c.X"})) is Truediff --git a/tests/test_text_only_parent_conversions.py b/tests/test_text_only_parent_conversions.pynew file mode 100644index 00000000000..ccebff7a9fa--- /dev/null+++ b/tests/test_text_only_parent_conversions.py@@ -0,0 +1,171 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.++"""A text-only load of a VLM checkpoint (MiniMax-M3) must still apply the VLM's checkpoint conversions, else MoE / indexer weights load randomly initialised."""++import pytest++[email protected](scope = "module")+def tiny_minimax(tmp_path_factory):+ try:+ import unsloth # noqa: F401+ except Exception as e: # pragma: no cover+ pytest.skip(f"unsloth does not import here: {e}")+ import torch+ from transformers import AutoConfig+ from transformers.models.auto.configuration_auto import CONFIG_MAPPING++ if "minimax_m3_vl" not in CONFIG_MAPPING:+ pytest.skip("this transformers has no MiniMax-M3")+ from transformers import AutoModelForImageTextToText++ config = AutoConfig.for_model("minimax_m3_vl")+ text = config.text_config+ layers = 3+ for key, value in dict(+ hidden_size = 64,+ intermediate_size = 32,+ num_hidden_layers = layers,+ num_attention_heads = 4,+ num_key_value_heads = 2,+ head_dim = 16,+ rotary_dim = 8,+ dense_intermediate_size = 128,+ shared_intermediate_size = 32,+ num_local_experts = 4,+ num_experts_per_tok = 2,+ vocab_size = 256,+ index_n_heads = 2,+ index_head_dim = 16,+ index_block_size = 16,+ index_topk_blocks = 2,+ ).items():+ setattr(text, key, value)+ text.mlp_layer_types = ["dense"] + ["sparse"] * (layers - 1)+ text.layer_types = ["full_attention"] + ["minimax_m3_sparse"] * (layers - 1)+ vision = config.vision_config+ for key, value in dict(+ hidden_size = 32, intermediate_size = 64, num_hidden_layers = 1, num_attention_heads = 2+ ).items():+ setattr(vision, key, value)+ config.projector_hidden_size = 64+ config.image_token_index = config.video_token_index = 200+ torch.manual_seed(0)+ model = AutoModelForImageTextToText.from_config(config).to(torch.bfloat16)+ path = tmp_path_factory.mktemp("tiny_minimax_m3")+ model.save_pretrained(path)+ reference = {k: v.detach().clone() for k, v in model.state_dict().items()}+ return path, config, reference+++def test_saved_checkpoint_has_the_original_layout(tiny_minimax):+ path, _, _ = tiny_minimax+ from safetensors import safe_open++ files = sorted(path.glob("*.safetensors"))+ keys = set()+ for file in files:+ with safe_open(str(file), "pt") as handle:+ keys |= set(handle.keys())+ assert any(".block_sparse_moe.experts.0.w1.weight" in k for k in keys), sorted(keys)[:5]+++def test_text_only_load_keeps_every_decoder_weight(tiny_minimax):+ import torch+ from transformers import AutoModelForCausalLM+ from unsloth.models._utils import _apply_text_only_key_mapping, _get_text_only_config++ path, config, reference = tiny_minimax+ text_config = _get_text_only_config(config, str(path))+ kwargs = {}+ _apply_text_only_key_mapping(kwargs, config, text_config)+ assert kwargs.get("key_mapping")+ decoder = AutoModelForCausalLM.from_pretrained(+ path, config = text_config, dtype = torch.bfloat16, **kwargs+ )+ assert type(decoder).__name__ == "MiniMaxM3VLForCausalLM"+ loaded = decoder.state_dict()+ compared = 0+ for key, value in loaded.items():+ ref_key = key.replace("model.", "model.language_model.", 1)+ if ref_key not in reference:+ ref_key = key+ assert ref_key in reference, key+ assert torch.equal(value, reference[ref_key]), key+ compared += 1+ assert any("experts.gate_up_proj" in k for k in loaded)+ assert any("indexer" in k for k in loaded)+ assert compared == len(loaded)+++def test_only_prefix_moves_are_left_to_the_key_mapping():+ try:+ from transformers.conversion_mapping import get_checkpoint_conversion_mapping+ from transformers.core_model_loading import WeightConverter+ except Exception:+ pytest.skip("transformers without checkpoint conversion mappings")+ from unsloth.models._utils import _parent_conversions_for_text_only++ if get_checkpoint_conversion_mapping("minimax_m3_vl") is None:+ pytest.skip("this transformers has no MiniMax-M3")+ carried = _parent_conversions_for_text_only("minimax_m3_vl")+ sources = [+ str(s)+ for t in carried+ for s in (+ t.source_patterns+ if isinstance(t.source_patterns, (list, tuple))+ else [t.source_patterns]+ )+ ]+ assert not any(s.startswith("^") for s in sources)+ assert any(isinstance(t, WeightConverter) for t in carried)+ assert _parent_conversions_for_text_only("a_model_type_with_no_mapping") == []+++def test_other_loads_are_untouched(tiny_minimax):+ import torch+ from transformers import AutoModelForImageTextToText++ path, _, reference = tiny_minimax+ model = AutoModelForImageTextToText.from_pretrained(path, dtype = torch.bfloat16)+ state = model.state_dict()+ assert all(torch.equal(state[k], reference[k]) for k in reference)+++def test_the_parent_conversions_are_per_thread(tiny_minimax):+ """Carried conversions are thread-local to the requesting load; the lookup is never swapped."""+ import threading++ import transformers.conversion_mapping as conversion_mapping+ from unsloth.models import _utils++ path, config, _ = tiny_minimax+ text_config = _utils._get_text_only_config(config, str(path))+ _utils._apply_text_only_key_mapping({}, config, text_config)+ text_type = text_config.model_type+ lookup = conversion_mapping.get_checkpoint_conversion_mapping+ assert getattr(lookup, "_unsloth_text_only_carry", False)+ assert lookup(text_type) is None++ seen = {}+ inside, done = threading.Event(), threading.Event()++ def other_load():+ inside.wait(5)+ seen["other"] = conversion_mapping.get_checkpoint_conversion_mapping(text_type)+ done.set()++ thread = threading.Thread(target = other_load)+ thread.start()+ _utils._TEXT_ONLY_LOOKUP_OVERRIDES.value = {text_type: ["carried"]}+ try:+ seen["this"] = conversion_mapping.get_checkpoint_conversion_mapping(text_type)+ inside.set()+ done.wait(5)+ finally:+ _utils._TEXT_ONLY_LOOKUP_OVERRIDES.value = None+ thread.join(5)+ assert seen == {"this": ["carried"], "other": None}+ assert conversion_mapping.get_checkpoint_conversion_mapping is lookupdiff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.pyindex d2a5ef2fe80..88e4fadc5e1 100644--- a/unsloth/_gpu_init.py+++ b/unsloth/_gpu_init.py@@ -256,6 +256,8 @@ from .import_fixes import (fix_transformers_chunked_mask_block_sequence_ids,fix_transformers_rope_scaling_drops_theta,fix_transformers_validate_rope_ignore_keys,+ fix_transformers5_remote_code_legacy_defaults,+ fix_transformers_config_only_remote_code,fix_transformers_remote_rope_scaling_none,fix_transformers_is_torch_fx_available,fix_xformers_performance_issue,@@ -318,6 +320,8 @@ del check_transformers_prequantized_vlm_quant_state# retry in models/llama.py sees a config that kept its base (#2405).fix_transformers_rope_scaling_drops_theta()fix_transformers_validate_rope_ignore_keys()+fix_transformers5_remote_code_legacy_defaults()+fix_transformers_config_only_remote_code()# Remote code written for 4.x reads plain RoPE as rope_scaling None and imports is_torch_fx_available.fix_transformers_remote_rope_scaling_none()fix_transformers_is_torch_fx_available()diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.pyindex bdda74cd1de..a923e00b2e8 100644--- a/unsloth/import_fixes.py+++ b/unsloth/import_fixes.py@@ -2745,6 +2745,339 @@ def fix_transformers_rope_scaling_drops_theta():logger.info(f"Unsloth: Failed patching rope_scaling ({e})")+# Token ids 4.x `PretrainedConfig.__init__` set (None) on every config; 5 dropped them from the base.+_LEGACY_CONFIG_TOKEN_ATTRIBUTES = (+ "pad_token_id",+ "bos_token_id",+ "eos_token_id",+ "sep_token_id",+ "decoder_start_token_id",+)+_REMOTE_CODE_LEGACY_FLAG = "_unsloth_remote_code_legacy_defaults"+++def _legacy_config_attributes_missing_from_base():+ """Legacy token attributes the base config lacks, measured on an instance (empty on 4.x)."""+ try:+ from transformers import PretrainedConfig+ base = PretrainedConfig()+ except Exception:+ return ()+ missing = []+ for name in _LEGACY_CONFIG_TOKEN_ATTRIBUTES:+ try:+ getattr(base, name)+ except AttributeError:+ missing.append(name)+ except Exception:+ pass+ return tuple(missing)+++def _compute_legacy_default_rope_parameters(+ config = None,+ device = None,+ seq_len = None,+ **kwargs,+):+ """transformers 4.x `_compute_default_rope_parameters` (5 dropped "default")."""+ import torch++ base = getattr(config, "rope_theta", None)+ if base is None:+ parameters = getattr(config, "rope_parameters", None)+ if isinstance(parameters, dict):+ base = parameters.get("rope_theta")+ if base is None:+ base = 10000.0+ partial_rotary_factor = getattr(config, "partial_rotary_factor", None) or 1.0+ head_dim = getattr(config, "head_dim", None) or config.hidden_size // config.num_attention_heads+ dim = int(head_dim * partial_rotary_factor)+ inv_freq = 1.0 / (+ base+ ** (torch.arange(0, dim, 2, dtype = torch.int64).to(device = device, dtype = torch.float) / dim)+ )+ return inv_freq, 1.0+++class _RopeInitFunctionsWithDefault(dict):+ """Live view of `ROPE_INIT_FUNCTIONS` plus "default"; never add it to the real dict, whose spread in `_init_weights` would override every native default."""++ def __init__(self, live):+ super().__init__()+ self._live = live++ def __getitem__(self, key):+ try:+ return self._live[key]+ except KeyError:+ if key == "default":+ return _compute_legacy_default_rope_parameters+ raise++ def get(+ self,+ key,+ default = None,+ ):+ try:+ return self[key]+ except KeyError:+ return default++ def __contains__(self, key):+ return key == "default" or key in self._live++ def __setitem__(self, key, value):+ self._live[key] = value++ def __iter__(self):+ return iter(self._live)++ def __len__(self):+ return len(self._live)++ def keys(self):+ return self._live.keys()++ def items(self):+ return self._live.items()++ def values(self):+ return self._live.values()+++# 4.x mask-builder keywords 5 renamed or dropped: (old, new), new None if dropped.+_MASKING_LEGACY_KEYWORDS = (("input_embeds", "inputs_embeds"), ("cache_position", None))+++def _masking_legacy_keyword_changes():+ """Changed entries, read off `_preprocess_mask_arguments` since public builders may already be wrapped (unsloth_zoo)."""+ try:+ from transformers import masking_utils+ parameters = inspect.signature(masking_utils._preprocess_mask_arguments).parameters+ except Exception:+ return ()+ return tuple(+ (old, new)+ for old, new in _MASKING_LEGACY_KEYWORDS+ if old not in parameters and (new is None or new in parameters)+ )+++def _accept_legacy_mask_keywords(function, changes):+ @functools.wraps(function)+ def wrapper(*args, **kwargs):+ for old, new in changes:+ if old not in kwargs:+ continue+ value = kwargs.pop(old)+ if new is not None and new not in kwargs:+ kwargs[new] = value+ return function(*args, **kwargs)++ wrapper._unsloth_legacy_mask_keywords = True+ return wrapper+++def _patch_remote_code_module(+ module,+ missing_attributes,+ restore_default_rope,+ mask_keyword_changes = (),+):+ """Class attributes so checkpoint values win and config.json is unchanged; no module flag, since transformers re-executes changed remote files in the same module."""+ if module is None:+ return+ namespace = getattr(module, "__dict__", {})+ module_name = getattr(module, "__name__", None)+ if restore_default_rope:+ rope = namespace.get("ROPE_INIT_FUNCTIONS")+ if (+ isinstance(rope, dict)+ and not isinstance(rope, _RopeInitFunctionsWithDefault)+ and "default" not in rope+ ):+ module.ROPE_INIT_FUNCTIONS = _RopeInitFunctionsWithDefault(rope)+ if mask_keyword_changes:+ from transformers import masking_utils+ for name, value in list(namespace.items()):+ if (+ callable(value)+ and name.startswith("create_")+ and not getattr(value, "_unsloth_legacy_mask_keywords", False)+ and (+ value is getattr(masking_utils, name, None)+ or getattr(value, "__module__", None) == masking_utils.__name__+ )+ ):+ setattr(module, name, _accept_legacy_mask_keywords(value, mask_keyword_changes))+ config_base = module_base = None+ if missing_attributes:+ from transformers import PretrainedConfig as config_base+ if restore_default_rope:+ from torch.nn import Module as module_base+ for value in list(namespace.values()):+ if not isinstance(value, type) or value.__module__ != module_name:+ continue+ if config_base is not None and issubclass(value, config_base):+ for name in missing_attributes:+ if not any(name in klass.__dict__ for klass in value.__mro__):+ setattr(value, name, None)+ # 5's `_init_weights` calls the module's `compute_default_rope_parameters`; 4.x classes lack it.+ elif (+ module_base is not None+ and issubclass(value, module_base)+ and "RotaryEmbedding" in value.__name__+ and not hasattr(value, "compute_default_rope_parameters")+ ):+ value.compute_default_rope_parameters = staticmethod(+ _compute_legacy_default_rope_parameters+ )+++def _patch_remote_code_package(+ module_name,+ missing_attributes,+ restore_default_rope,+ mask_keyword_changes = (),+):+ if not module_name.startswith("transformers_modules."):+ return+ package = module_name.rpartition(".")[0]+ for name, module in list(sys.modules.items()):+ if name == package or name.startswith(package + "."):+ _patch_remote_code_module(+ module, missing_attributes, restore_default_rope, mask_keyword_changes+ )+++def fix_transformers5_remote_code_legacy_defaults():+ """Let 4.x remote code (Trinity-Large `modeling_afmoe.py`) build on 5; hooks `get_class_in_module` so native models are untouched."""+ try:+ import transformers.dynamic_module_utils as dynamic_module_utils+ from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS+ except Exception as e:+ logger.info(f"Unsloth: Skipping remote-code legacy defaults ({e})")+ return+ missing_attributes = _legacy_config_attributes_missing_from_base()+ restore_default_rope = "default" not in ROPE_INIT_FUNCTIONS+ mask_keyword_changes = _masking_legacy_keyword_changes()+ if not (missing_attributes or restore_default_rope or mask_keyword_changes):+ return+ original = getattr(dynamic_module_utils, "get_class_in_module", None)+ if original is None or getattr(original, _REMOTE_CODE_LEGACY_FLAG, False):+ return++ @functools.wraps(original)+ def get_class_in_module(*args, **kwargs):+ cls = original(*args, **kwargs)+ try:+ _patch_remote_code_package(+ getattr(cls, "__module__", "") or "",+ missing_attributes,+ restore_default_rope,+ mask_keyword_changes,+ )+ except Exception as e:+ logger.info(f"Unsloth: remote-code legacy defaults skipped ({e})")+ return cls++ setattr(get_class_in_module, _REMOTE_CODE_LEGACY_FLAG, True)+ dynamic_module_utils.get_class_in_module = get_class_in_module+ for name, module in list(sys.modules.items()):+ if name.startswith("transformers_modules."):+ try:+ _patch_remote_code_module(+ module, missing_attributes, restore_default_rope, mask_keyword_changes+ )+ except Exception:+ pass+++_CONFIG_ONLY_REMOTE_CODE_FLAG = "_unsloth_config_only_remote_code"+_CONFIG_ONLY_REMOTE_CODE_WARNED = set()+++def _remote_config_breaks_native_model(config):+ """True for a config-only remote repo (MiniMax-M3) whose config leaves a native sub-config a bare `PretrainedConfig`."""+ config_class = type(config)+ if not (getattr(config_class, "__module__", "") or "").startswith("transformers_modules"):+ return False+ auto_map = getattr(config, "auto_map", None)+ if not isinstance(auto_map, dict) or "AutoConfig" not in auto_map:+ return False+ if any(str(key).startswith("AutoModel") for key in auto_map):+ return False+ from transformers import PretrainedConfig+ from transformers.models.auto.configuration_auto import CONFIG_MAPPING++ model_type = getattr(config, "model_type", None)+ if not model_type or model_type not in CONFIG_MAPPING:+ return False+ native_class = CONFIG_MAPPING[model_type]+ if issubclass(config_class, native_class):+ return False+ for key in getattr(native_class, "sub_configs", None) or {}:+ try:+ sub_config = getattr(config, key, None)+ except Exception:+ continue+ if sub_config is not None and type(sub_config) is PretrainedConfig:+ return True+ return False+++def fix_transformers_config_only_remote_code():+ """Return the native config when `_remote_config_breaks_native_model`, so every caller (device-map planner too) sees it."""+ try:+ from transformers import AutoConfig+ except Exception as e:+ logger.info(f"Unsloth: Skipping config-only remote code fix ({e})")+ return+ original = AutoConfig.__dict__.get("from_pretrained")+ original_func = getattr(original, "__func__", None)+ if original_func is None or getattr(original_func, _CONFIG_ONLY_REMOTE_CODE_FLAG, False):+ return++ @functools.wraps(original_func)+ def from_pretrained(cls, pretrained_model_name_or_path, *args, **kwargs):+ result = original_func(cls, pretrained_model_name_or_path, *args, **kwargs)+ if not kwargs.get("trust_remote_code"):+ return result+ config = result[0] if isinstance(result, tuple) else result+ try:+ breaks = _remote_config_breaks_native_model(config)+ except Exception:+ breaks = False+ if not breaks:+ return result+ try:+ native = original_func(+ cls, pretrained_model_name_or_path, *args, **{**kwargs, "trust_remote_code": False}+ )+ except Exception as e:+ logger.info(f"Unsloth: Native config reload failed, keeping the remote one ({e})")+ return result+ model_type = getattr(config, "model_type", None)+ if model_type not in _CONFIG_ONLY_REMOTE_CODE_WARNED:+ _CONFIG_ONLY_REMOTE_CODE_WARNED.add(model_type)+ native_config = native[0] if isinstance(native, tuple) else native+ print(+ f"Unsloth: `{pretrained_model_name_or_path}` ships only a config class for "+ f"`{model_type}`, and transformers builds its own model for it. Using "+ f"transformers' `{type(native_config).__name__}`, since the repo's config "+ f"leaves sub-configs that model reads unparsed."+ )+ return native++ setattr(from_pretrained, _CONFIG_ONLY_REMOTE_CODE_FLAG, True)+ try:+ AutoConfig.from_pretrained = classmethod(from_pretrained)+ except Exception as e:+ logger.info(f"Unsloth: Failed patching AutoConfig.from_pretrained ({e})")++# ValueError: 'aimv2' is already used by a Transformers config, pick another name.def fix_vllm_aimv2_issue():spec = importlib.util.find_spec("vllm")diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.pyindex ed9e6d4dd2e..272e6c19321 100644--- a/unsloth/models/_utils.py+++ b/unsloth/models/_utils.py@@ -117,6 +117,7 @@ import copyimport refrom dataclasses import dataclass, fieldimport functools+import threadingimport textwrapimport loggingimport warnings, subprocess, inspect, psutil, os, math@@ -1113,6 +1114,69 @@ def resolve_model_class(auto_model, config):return result[0] if isinstance(result, (list, tuple)) else result[email protected]_cache(maxsize = None)+def _auto_loader_prefers_explicit_local_code():+ """5 lets a class registered for the exact config class beat auto_map; 4.x never does."""+ try:+ import inspect+ from transformers.models.auto.auto_factory import _BaseAutoModelClass+ return "explicit_local_code" in inspect.getsource(_BaseAutoModelClass.from_pretrained)+ except Exception:+ return True+++_REMOTE_CLASS_HUB_OPTIONS = ("code_revision", "cache_dir", "proxies", "force_download")+++def resolve_remote_code_model_class(+ auto_model,+ config,+ model_name,+ trust_remote_code = False,+ **hub_kwargs,+):+ """(True, cls) if the load builds the remote class, (True, None) if unfetchable, else (False, None); `resolve_model_class` matches by NAME and misses remote shadows (Trinity-Large)."""+ if not trust_remote_code or config is None or model_name is None:+ return False, None+ auto_map = getattr(config, "auto_map", None)+ auto_name = getattr(auto_model, "__name__", None)+ if not isinstance(auto_map, dict) or auto_name not in auto_map:+ return False, None+ # Exact match only, as transformers checks `type(config) in cls._model_mapping`.+ try:+ mapping = auto_model._model_mapping+ if type(config) in mapping and _auto_loader_prefers_explicit_local_code():+ from transformers.models.auto.auto_factory import _get_model_class+ local_class = _get_model_class(config, mapping)+ if not (getattr(local_class, "__module__", "") or "").startswith("transformers."):+ return False, None+ except Exception:+ pass+ class_ref = auto_map[auto_name]+ if isinstance(class_ref, (list, tuple)):+ class_ref = class_ref[0]+ if not isinstance(class_ref, str):+ return True, None+ try:+ from transformers.dynamic_module_utils import get_class_from_dynamic_module+ hub_kwargs = {k: v for k, v in hub_kwargs.items() if v is not None}+ return True, get_class_from_dynamic_module(class_ref, model_name, **hub_kwargs)+ except Exception:+ return True, None+++def attention_class_for_load(model_class, builds_remote_class, remote_class, supports_sdpa):+ """A remote class replaces only a native class it shadows; otherwise it may only rule sdpa out, so remote code that already loaded keeps its attention route."""+ if not builds_remote_class:+ return model_class, supports_sdpa+ if model_class is None and remote_class is None:+ return None, supports_sdpa+ return (+ remote_class if model_class is not None else None,+ bool(supports_sdpa) and bool(getattr(remote_class, "_supports_sdpa", False)),+ )++def _is_family_text_decoder(parent_model_type, text_model_type):# True only for the family's own text variant (gemma3 -> gemma3_text); a generic reused decoder (llava -> llama) would load random weights, so keep the full model.return bool(parent_model_type) and str(text_model_type).startswith(parent_model_type)@@ -1197,6 +1261,86 @@ def _get_text_only_key_mapping(parent_config, text_config):}+_TEXT_ONLY_PARENT_MODEL_TYPES = {}+# Per-thread, set only during one text-only `get_model_conversion_mapping` call.+_TEXT_ONLY_LOOKUP_OVERRIDES = threading.local()+_TEXT_ONLY_PREFIX_RENAME = r"^language_model\.model\."+++def _parent_conversions_for_text_only(parent_model_type):+ """VLM conversions a decoder-only load needs, minus start-anchored prefix renames the text-only key_mapping replaces."""+ try:+ from transformers.conversion_mapping import get_checkpoint_conversion_mapping+ from transformers.core_model_loading import WeightRenaming+ except Exception:+ return []+ kept = []+ for transform in get_checkpoint_conversion_mapping(parent_model_type) or []:+ sources = transform.source_patterns+ if not isinstance(sources, (list, tuple)):+ sources = [sources]+ if isinstance(transform, WeightRenaming) and all(str(s).startswith("^") for s in sources):+ continue+ kept.append(transform)+ return kept+++def _install_text_only_conversion_carry():+ """Give text-only VLM loads (Unsloth key_mapping, no own conversions) the VLM's conversions."""+ try:+ import transformers.conversion_mapping as conversion_mapping+ import transformers.modeling_utils as modeling_utils+ lookup = conversion_mapping.get_checkpoint_conversion_mapping+ except Exception:+ return+ original = getattr(modeling_utils, "get_model_conversion_mapping", None)+ if original is None or getattr(original, "_unsloth_text_only_carry", False):+ return++ # Installed once, never swapped per call: concurrent loads would race on the module global.+ if not getattr(lookup, "_unsloth_text_only_carry", False):++ @functools.wraps(lookup)+ def get_checkpoint_conversion_mapping(model_type, *args, **kwargs):+ overrides = getattr(_TEXT_ONLY_LOOKUP_OVERRIDES, "value", None)+ if overrides and model_type in overrides:+ return copy.deepcopy(overrides[model_type])+ return lookup(model_type, *args, **kwargs)++ get_checkpoint_conversion_mapping._unsloth_text_only_carry = True+ conversion_mapping.get_checkpoint_conversion_mapping = get_checkpoint_conversion_mapping++ @functools.wraps(original)+ def get_model_conversion_mapping(+ model,+ key_mapping = None,+ *args,+ **kwargs,+ ):+ text_model_type = getattr(getattr(model, "config", None), "model_type", None)+ parent_model_type = _TEXT_ONLY_PARENT_MODEL_TYPES.get(text_model_type)+ if (+ parent_model_type is None+ or not key_mapping+ or _TEXT_ONLY_PREFIX_RENAME not in key_mapping+ or lookup(type(model).__name__) is not None+ or lookup(text_model_type) is not None+ ):+ return original(model, key_mapping, *args, **kwargs)+ extra = _parent_conversions_for_text_only(parent_model_type)++ # Same list position as a native registration so the quantizer rewrites them too (FP8).+ previous = getattr(_TEXT_ONLY_LOOKUP_OVERRIDES, "value", None)+ _TEXT_ONLY_LOOKUP_OVERRIDES.value = {**(previous or {}), text_model_type: extra}+ try:+ return original(model, key_mapping, *args, **kwargs)+ finally:+ _TEXT_ONLY_LOOKUP_OVERRIDES.value = previous++ get_model_conversion_mapping._unsloth_text_only_carry = True+ modeling_utils.get_model_conversion_mapping = get_model_conversion_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)@@ -1204,6 +1348,15 @@ def _apply_text_only_key_mapping(kwargs, parent_config, text_config):returnuser_mapping = kwargs.get("key_mapping", None)kwargs["key_mapping"] = {**mapping, **user_mapping} if user_mapping else mapping+ parent_model_type = getattr(parent_config, "model_type", None)+ text_model_type = getattr(text_config, "model_type", None)+ if (+ parent_model_type+ and text_model_type+ and _parent_conversions_for_text_only(parent_model_type)+ ):+ _TEXT_ONLY_PARENT_MODEL_TYPES[text_model_type] = parent_model_type+ _install_text_only_conversion_carry()def _cast_text_only_prequantized_params(model, dtype):diff --git a/unsloth/models/loader.py b/unsloth/models/loader.pyindex 4ad564223da..8ab047c16f5 100644--- a/unsloth/models/loader.py+++ b/unsloth/models/loader.py@@ -224,8 +224,13 @@ def _config_uses_remote_code(config):auto_map = cfg.get("auto_map", auto_map)if not auto_map:return False+ config_is_native = (getattr(type(cfg), "__module__", "") or "").startswith("transformers.")# A custom tokenizer, processor or feature extractor is not code the compiler traces.- return any(str(k).startswith(("AutoModel", "AutoConfig")) for k in auto_map)+ return any(+ str(k).startswith("AutoModel")+ or (str(k).startswith("AutoConfig") and not config_is_native)+ for k in auto_map+ )# Sub-configs go beyond text/vision/audio (Qwen-Omni thinker_config, nested llm_config) and nest;# a remote child read as native puts the compiler on untraceable code, so walk every level.diff --git a/unsloth/models/vision.py b/unsloth/models/vision.pyindex 38d7716d050..9d54436ce91 100644--- a/unsloth/models/vision.py+++ b/unsloth/models/vision.py@@ -73,6 +73,9 @@ from ._utils import (importlib_version,_prepare_model_for_qat,resolve_model_class,+ resolve_remote_code_model_class,+ attention_class_for_load,+ _REMOTE_CLASS_HUB_OPTIONS,resolve_attention_implementation,_get_text_only_config,_is_family_text_decoder,@@ -1460,6 +1463,17 @@ class FastBaseModel:local_files_only = local_files_only,revision = _revision,)+ # Remote classes shadowing a native name can differ in attention flags.+ _builds_remote_class, _remote_class = resolve_remote_code_model_class(+ auto_model,+ auto_config,+ model_name,+ trust_remote_code = trust_remote_code,+ token = token,+ revision = _revision,+ local_files_only = local_files_only,+ **{k: kwargs.get(k, None) for k in _REMOTE_CLASS_HUB_OPTIONS},+ )model_class = resolve_model_class(auto_model, auto_config)# Forced float32 loads in bfloat16 then casts to float16. Resolved here, not at the load, because attention resolution and the device-map planner both size the same dtype.torch_dtype = dtype@@ -1467,11 +1481,14 @@ class FastBaseModel:torch_dtype = torch.bfloat16# What attention actually runs in, not the load dtype: the UNSLOTH_FORCE_CUSTOM_DTYPE families (csm, falcon_h1, nemotron_h) load float32 for Mamba precision then cast projections back to correct_dtype, so flash stays.attn_dtype = correct_dtype if correct_dtype is not None else torch_dtype+ _attn_class, _attn_supports_sdpa = attention_class_for_load(+ model_class, _builds_remote_class, _remote_class, supports_sdpa+ )attn_impl = resolve_attention_implementation(- model_class,+ _attn_class,auto_config,requested_attn_implementation = kwargs.get("attn_implementation", None),- supports_sdpa = supports_sdpa,+ supports_sdpa = _attn_supports_sdpa,dtype = attn_dtype,)