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
Preserve repo id case when resolving a model name (#8058)
BardiaKoopahaa36c8d10cc7
diff --git a/studio/backend/tests/test_training_gated_upstream.py b/studio/backend/tests/test_training_gated_upstream.pyindex 3bcbe6ca8d3..90d9bbe094d 100644--- a/studio/backend/tests/test_training_gated_upstream.py+++ b/studio/backend/tests/test_training_gated_upstream.py@@ -755,7 +755,7 @@ def test_the_security_scan_imports_nothing_heavy():("unsloth/gemma-3-270m-it-unsloth-bnb-4bit", False, "unsloth/gemma-3-270m-it"),# ...while a 4-bit load keeps it, so the tables resolve nothing and BAD_MAPPINGS is# applied to the input name instead, landing on a DIFFERENT repo.- ("unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit", True, "unsloth/qwen3-30b-a3b"),+ ("unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit", True, "unsloth/Qwen3-30B-A3B"),# An id the loader really does leave alone still answers None.("unsloth/gemma-3-270m-it-unsloth-bnb-4bit", True, None),("unsloth/gemma-3-270m-it", False, None),diff --git a/studio/backend/utils/models/unsloth_mirror.py b/studio/backend/utils/models/unsloth_mirror.pyindex bc393fa253a..40344ec6271 100644--- a/studio/backend/utils/models/unsloth_mirror.py+++ b/studio/backend/utils/models/unsloth_mirror.py@@ -47,7 +47,7 @@ def _mapper_tables() -> Optional[tuple[dict, dict, dict]]:def _string_literal(node) -> Optional[str]:"""``"Repo".lower()`` and ``"Repo"`` as data. BAD_MAPPINGS is written with ``.lower()``- calls on both sides, so ast.literal_eval alone cannot read it."""+ calls on its keys, so ast.literal_eval alone cannot read it."""if isinstance(node, ast.Constant) and isinstance(node.value, str):return node.valueif (@@ -126,7 +126,7 @@ def unsloth_public_mirror(model_name: Optional[str], load_in_4bit: bool = True)# resolves through INT_TO_FLOAT_MAPPER (unsloth/gemma-3-270m-it-unsloth-bnb-4bit -># unsloth/gemma-3-270m-it), and BAD_MAPPINGS is applied to the INPUT name when the tables# resolve nothing (loader_utils.py:1014-1016), which is how a 4-bit- # unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit becomes unsloth/qwen3-30b-a3b. Both were verified+ # unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit becomes unsloth/Qwen3-30B-A3B. Both were verified# against get_model_name. Returning None for these let the security scan check a repo the# loader never fetches while the one it does fetch, and any custom code in it, went# unscanned. Identity results are still dropped at the end.diff --git a/tests/python/test_loader_resolution_reporting.py b/tests/python/test_loader_resolution_reporting.pyindex 025809d6ef7..21fac8709b0 100644--- a/tests/python/test_loader_resolution_reporting.py+++ b/tests/python/test_loader_resolution_reporting.py@@ -54,9 +54,11 @@ def test_reports_actual_repo_after_mapping_and_capability_normalization(cls, exaget_model_name = mapper,ALLOW_PREQUANTIZED_MODELS = prequant,_strip_unsloth_bnb_4bit_suffix = lambda name: name.removesuffix("-unsloth-bnb-4bit"),+ _prefer_legacy_lowercase_cache = lambda name, *a: name,on_model_resolved = reports.append,os = os,kwargs = {},+ revision = None,quantization_config = None,)module = ast.Module(body = function.body[start:end], type_ignores = [])@@ -96,7 +98,9 @@ def test_adapter_base_resolution_updates_report_before_base_config_load(cls):trust_remote_code = False,ALLOW_PREQUANTIZED_MODELS = True,get_model_name = lambda *a, **k: "org/base-unsloth-bnb-4bit",+ _prefer_legacy_lowercase_cache = lambda name, *a: name,on_model_resolved = reports.append,+ kwargs = {},)module = ast.Module(body = block.body[:end], type_ignores = [])exec(compile(ast.fix_missing_locations(module), str(LOADER), "exec"), scope)@@ -141,3 +145,39 @@ def test_training_forwards_observer_through_each_loader_and_retry():k.arg == "on_model_resolved" and ast.unparse(k.value) == "on_model_resolved"for k in call.keywords)++[email protected]("cls", ["FastLanguageModel", "FastModel"])+def test_stripped_prequant_base_can_use_the_legacy_lowercase_cache(cls):+ function = _loader(cls)+ start = next(+ i for i, n in enumerate(function.body) if ast.unparse(n) == "old_model_name = model_name"+ )+ end = next(+ i+ for i in range(start, len(function.body))+ if "USE_MODELSCOPE" in ast.unparse(function.body[i])+ )+ reports = []+ scope = dict(+ model_name = "Org/Requested",+ use_exact_model_name = False,+ load_in_4bit = True,+ load_in_8bit = False,+ load_in_16bit = False,+ load_in_fp8 = False,+ token = None,+ trust_remote_code = False,+ get_model_name = lambda name, **k: "Org/Resolved-unsloth-bnb-4bit",+ ALLOW_PREQUANTIZED_MODELS = False,+ _strip_unsloth_bnb_4bit_suffix = lambda name: name.removesuffix("-unsloth-bnb-4bit"),+ _prefer_legacy_lowercase_cache = lambda name, *a: name.lower(),+ on_model_resolved = reports.append,+ os = os,+ kwargs = {"local_files_only": True},+ revision = None,+ quantization_config = None,+ )+ module = ast.Module(body = function.body[start:end], type_ignores = [])+ exec(compile(ast.fix_missing_locations(module), str(LOADER), "exec"), scope)+ assert reports == ["org/resolved"]diff --git a/tests/python/test_revision_forwarding.py b/tests/python/test_revision_forwarding.pyindex 2538b27cf47..8d78b8235b8 100644--- a/tests/python/test_revision_forwarding.py+++ b/tests/python/test_revision_forwarding.py@@ -174,6 +174,10 @@ def test_revision_survives_when_the_repo_is_unchanged():assert gate("my-branch", "myorg/my-ft", "myorg/my-ft") == "my-branch"+def test_revision_survives_a_spelling_only_change():+ assert _load_gate()("release", "unsloth/Qwen3-30B-A3B", "unsloth/qwen3-30b-a3b") == "release"++@pytest.mark.parametrize("model_name, old_model_name",[@@ -464,6 +468,12 @@ def test_a_remapped_plain_load_drops_the_tokenizer_pin_too():assert gate("org/model", "unsloth/model-bnb-4bit", "org/model", "v2", None) is None+def test_a_case_only_tokenizer_name_keeps_the_model_ref():+ gate = _load_tokenizer_gate()+ requested, resolved = "unsloth/qwen3-30b-a3b", "unsloth/Qwen3-30B-A3B"+ assert gate(requested, resolved, requested, "v2", "v2") == "v2"++def test_a_plain_load_gives_the_tokenizer_the_model_ref():gate = _load_tokenizer_gate()assert gate(None, "org/model", "org/model", "v2", "v2") == "v2"diff --git a/tests/test_bad_mappings_redirect.py b/tests/test_bad_mappings_redirect.pyindex 7ae9ddbb4fe..bf0d27578d0 100644--- a/tests/test_bad_mappings_redirect.py+++ b/tests/test_bad_mappings_redirect.py@@ -25,10 +25,15 @@ def _load_get_model_name():namespace = dict(mapper_ns)namespace["SUPPORTS_FOURBIT"] = True- namespace["_env_says_offline"] = lambda: True+ namespace["_env_says_offline"] = lambda: Falsenamespace["_get_new_mapper"] = lambda: ({}, {}, {}, {}, {})- wanted = {"__get_model_name", "_resolve_with_mappers", "get_model_name"}+ wanted = {+ "__get_model_name",+ "_resolve_with_mappers",+ "_prefer_legacy_lowercase_cache",+ "get_model_name",+ }for node in tree.body:if isinstance(node, ast.Assign) and any(getattr(target, "id", None) == "BAD_MAPPINGS" for target in node.targets@@ -45,3 +50,9 @@ def test_bad_mappings_redirect_every_listed_name():assert bad_mappings, "BAD_MAPPINGS should not be empty"for name, expected in bad_mappings.items():assert get_model_name(name, load_in_4bit = True) == expected, name+++def test_bad_mapping_redirects_keep_canonical_repo_case():+ get_model_name, _ = _load_get_model_name()+ assert get_model_name("Qwen/Qwen3-32B", load_in_4bit = True) == "unsloth/Qwen3-32B-bnb-4bit"+ assert get_model_name("Qwen/Qwen3-30B-A3B", load_in_4bit = True) == "unsloth/Qwen3-30B-A3B"diff --git a/tests/test_get_model_name.py b/tests/test_get_model_name.pyindex 60b840abc33..d016d93e24a 100644--- a/tests/test_get_model_name.py+++ b/tests/test_get_model_name.py@@ -150,19 +150,125 @@ class TestGetModelName(unittest.TestCase):with self.subTest(model_name = model_name, load_in_4bit = load_in_4bit):self._assert_mapping(model_name, load_in_4bit, expected, should_change)+ @patch.object(loader_utils, "_get_new_mapper", _no_remote_mapper)+ def test_artifactory_report_preserves_repo_id_case(self):+ self.assertEqual(+ get_model_name("unsloth/Meta-Llama-3.1-8B-Instruct", load_in_4bit = True),+ "unsloth/Meta-Llama-3.1-8B-Instruct-unsloth-bnb-4bit",+ )++ @patch.object(loader_utils, "_get_new_mapper", _no_remote_mapper)+ def test_offline_reuses_legacy_lowercase_cache(self):+ canonical = "unsloth/Meta-Llama-3.1-8B-Instruct-unsloth-bnb-4bit"+ for cached, expected in (+ ({canonical.lower()}, canonical.lower()),+ ({canonical, canonical.lower()}, canonical),+ (set(), canonical),+ ):+ fake = lambda repo_id, filename, cache_dir = None, revision = None: (+ "/cache/config.json" if repo_id in cached else None+ )+ for offline_kwargs, env in (+ ({"local_files_only": True}, {}),+ ({}, {"HF_HUB_OFFLINE": "1"}),+ ):+ with (+ self.subTest(cached = cached, env = env),+ patch("huggingface_hub.try_to_load_from_cache", fake),+ patch.dict("os.environ", env),+ ):+ self.assertEqual(+ get_model_name(+ "unsloth/Meta-Llama-3.1-8B-Instruct",+ load_in_4bit = True,+ **offline_kwargs,+ ),+ expected,+ )+ files = {+ (canonical, "config.json"),+ (canonical.lower(), "config.json"),+ (canonical.lower(), "model.safetensors"),+ }+ with (+ patch(+ "huggingface_hub.try_to_load_from_cache",+ lambda repo_id, filename, cache_dir = None, revision = None: (+ "/cache/f" if (repo_id, filename) in files else None+ ),+ ),+ patch.dict("os.environ", {"HF_HUB_OFFLINE": "1"}),+ ):+ self.assertEqual(+ get_model_name("unsloth/Meta-Llama-3.1-8B-Instruct", load_in_4bit = True),+ canonical.lower(),+ )+ files = {+ (canonical, "model.safetensors"),+ (canonical.lower(), "config.json"),+ (canonical.lower(), "model.safetensors"),+ }+ self.assertEqual(+ get_model_name("unsloth/Meta-Llama-3.1-8B-Instruct", load_in_4bit = True),+ canonical.lower(),+ )+ files = {("unsloth/qwen3-30b-a3b", "config.json")}+ self.assertEqual(+ get_model_name("unsloth/Qwen3-30B-A3B", load_in_4bit = True),+ "unsloth/qwen3-30b-a3b",+ )+ with (+ patch(+ "huggingface_hub.try_to_load_from_cache",+ lambda repo_id, filename, cache_dir = None, revision = None: (+ "/cache/f"+ if repo_id == "unsloth/qwen3-30b-a3b" and revision == "release"+ else None+ ),+ ),+ patch.dict("os.environ", {"HF_HUB_OFFLINE": "1"}),+ ):+ self.assertEqual(+ get_model_name("unsloth/qwen3-30b-a3b", load_in_4bit = True, revision = "release"),+ "unsloth/qwen3-30b-a3b",+ )+ with (+ patch(+ "huggingface_hub.try_to_load_from_cache",+ lambda repo_id, filename, cache_dir = None, revision = None: (+ "/cache/f" if repo_id == canonical.lower() and revision is None else None+ ),+ ),+ patch.dict("os.environ", {"HF_HUB_OFFLINE": "1"}),+ ):+ self.assertEqual(+ get_model_name(+ "meta-llama/Meta-Llama-3.1-8B-Instruct", load_in_4bit = True, revision = "abc"+ ),+ canonical.lower(),+ )+ with (+ patch("huggingface_hub.try_to_load_from_cache", side_effect = AssertionError),+ patch.dict("os.environ", {"HF_HUB_OFFLINE": "0", "TRANSFORMERS_OFFLINE": "0"}),+ ):+ self.assertEqual(+ get_model_name("unsloth/Meta-Llama-3.1-8B-Instruct", load_in_4bit = True),+ canonical,+ )+def test_static_mapper_contract(self):contracts = [- ("qwen/qwen3-8b", "unsloth/qwen3-8b-unsloth-bnb-4bit"),- ("qwen/qwen3-8b-fp8", "unsloth/qwen3-8b-unsloth-bnb-4bit"),+ ("qwen/qwen3-8b", "unsloth/Qwen3-8B-unsloth-bnb-4bit"),+ ("qwen/qwen3-8b-fp8", "unsloth/Qwen3-8B-unsloth-bnb-4bit"),("mistralai/ministral-3-3b-instruct-2512",- "unsloth/ministral-3-3b-instruct-2512-unsloth-bnb-4bit",+ "unsloth/Ministral-3-3B-Instruct-2512-unsloth-bnb-4bit",),("allenai/olmo-3-7b-instruct",- "unsloth/olmo-3-7b-instruct-unsloth-bnb-4bit",+ "unsloth/Olmo-3-7B-Instruct-unsloth-bnb-4bit",),- ("unsloth/kimi-k2-instruct", "unsloth/kimi-k2-instruct-bf16"),+ ("unsloth/kimi-k2-instruct", "unsloth/Kimi-K2-Instruct-BF16"),]for src, expected in contracts:with self.subTest(src = src):diff --git a/tests/test_mapper_preserves_repo_id_case.py b/tests/test_mapper_preserves_repo_id_case.pynew file mode 100644index 00000000000..cba92e4ee40--- /dev/null+++ b/tests/test_mapper_preserves_repo_id_case.py@@ -0,0 +1,88 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Lowercased mapper keys must resolve to exact-case repo ids (#2506). mapper.py is loaded by+path because importing the unsloth package needs an accelerator."""++import importlib.util+import os++MAPPER_PATH = os.path.join(os.path.dirname(__file__), os.pardir, "unsloth", "models", "mapper.py")+++def _load_mapper():+ spec = importlib.util.spec_from_file_location("_unsloth_mapper", MAPPER_PATH)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def _case_mismatches(mapping):+ exact_by_lower = {}+ for key in mapping:+ if key != key.lower():+ exact_by_lower.setdefault(key.lower(), key)++ mismatches = []+ for lowered, exact in exact_by_lower.items():+ if lowered in mapping and mapping[lowered] != mapping[exact]:+ mismatches.append((lowered, mapping[lowered], mapping[exact]))+ return mismatches+++def test_int_to_float_mapper_preserves_case():+ mapper = _load_mapper()+ mismatches = _case_mismatches(mapper.INT_TO_FLOAT_MAPPER)+ assert not mismatches, (+ "A lowercased key must resolve to the same repo id as its exact-case "+ "counterpart; a lowercased value only resolves on huggingface.co. "+ f"{len(mismatches)} mismatch(es), first 5: {mismatches[:5]}"+ )+++def test_float_to_int_mapper_preserves_case():+ mapper = _load_mapper()+ mismatches = _case_mismatches(mapper.FLOAT_TO_INT_MAPPER)+ assert not mismatches, (+ "A lowercased key must resolve to the same repo id as its exact-case "+ f"counterpart. {len(mismatches)} mismatch(es), first 5: {mismatches[:5]}"+ )+++def test_lowercase_lookup_returns_upstream_casing():+ mapper = _load_mapper()+ resolved = mapper.INT_TO_FLOAT_MAPPER.get("unsloth/gemma-4-e2b-unsloth-bnb-4bit")+ assert resolved == "unsloth/gemma-4-E2B", resolved+++def test_case_insensitive_lookup_still_works():+ mapper = _load_mapper()+ for mapping in (mapper.INT_TO_FLOAT_MAPPER, mapper.FLOAT_TO_INT_MAPPER):+ lowered = [key for key in mapping if key == key.lower()]+ assert len(lowered) > 100, len(lowered)+ assert "unsloth/gemma-4-e2b-unsloth-bnb-4bit" in mapper.INT_TO_FLOAT_MAPPER+++def _declared_repo_ids(mapper):+ registry = getattr(mapper, "__INT_TO_FLOAT_MAPPER")+ declared = set()+ for key, values in registry.items():+ declared.add(key)+ groups = values.values() if isinstance(values, dict) else (values,)+ for group in groups:+ declared.update(value for value in group if value)+ return declared+++def test_every_resolved_value_is_a_declared_repo_id():+ mapper = _load_mapper()+ declared = _declared_repo_ids(mapper)+ for name in ("INT_TO_FLOAT_MAPPER", "FLOAT_TO_INT_MAPPER"):+ undeclared = sorted(+ value for value in set(getattr(mapper, name).values()) if value not in declared+ )+ assert not undeclared, (+ f"{name} resolves to {len(undeclared)} id(s) that are not written "+ f"anywhere in the registry, so they were transformed in transit: "+ f"{undeclared[:5]}"+ )diff --git a/tests/test_new_mapper_fetched_fp8.py b/tests/test_new_mapper_fetched_fp8.pyindex 3dee8377bbc..5cf40a2ef8f 100644--- a/tests/test_new_mapper_fetched_fp8.py+++ b/tests/test_new_mapper_fetched_fp8.py@@ -18,7 +18,13 @@ import types_MODELS = os.path.join(os.path.dirname(__file__), os.pardir, "unsloth", "models")-_WANTED = {"__get_model_name", "_resolve_with_mappers", "_get_new_mapper", "get_model_name"}+_WANTED = {+ "__get_model_name",+ "_resolve_with_mappers",+ "_get_new_mapper",+ "_prefer_legacy_lowercase_cache",+ "get_model_name",+}# An fp8 ("8") model, spliced into the FETCHED mapper only._NEW_KEY = "unsloth/Zeta-9B-Only-On-Main"diff --git a/unsloth/models/loader.py b/unsloth/models/loader.pyindex c01d8c2649f..303e8a3c1d7 100644--- a/unsloth/models/loader.py+++ b/unsloth/models/loader.py@@ -49,6 +49,7 @@ from .loader_utils import (_offline_quantize_to_fp8,_tag_model_with_fp8_torchao_config,get_model_name,+ _prefer_legacy_lowercase_cache,is_distributed,is_automatic_device_map,prepare_device_map,@@ -176,7 +177,8 @@ def _revision_for_resolved_repo(mapper_moved_name = False,):"""Drop `revision` once the requested repo has been remapped to another one. A revision names a branch/tag/SHA on the repo the caller asked for, but from_pretrained may resolve model_name to a different repo (a pre-quantized mirror, an fp8 temp dir, a ModelScope snapshot, a -bnb-4bit strip), where that ref does not exist. Only the mapper substitution answers to use_exact_model_name, so only suggest it when it would help."""- if revision is None or model_name == old_model_name:+ # Hub repo ids are case-insensitive, so a spelling-only change is still the same repo.+ if revision is None or str(model_name).lower() == str(old_model_name).lower():return revisionremedy = (" Pass `use_exact_model_name = True` to load your repo as-is." if mapper_moved_name else ""@@ -197,10 +199,10 @@ def _revision_for_tokenizer_repo(is_peft = False,):"""Pick the revision for whichever repo the tokenizer is actually read from. It is not always the base model's: an adapter-hosted tokenizer is a separate repo with its own history, so it keeps the caller's ref even though the base model does not, while an unset tokenizer_name follows the resolved model_name. On a plain load the tokenizer belongs to the same model as the weights, so it follows model_revision even when the caller named its repo directly: a remap has already dropped the pin off the weights, and a pinned tokenizer beside a mirror's default-branch weights is the ref mismatch this gate exists to avoid."""- repo = tokenizer_name if tokenizer_name else model_name- if is_peft and repo == old_model_name:+ repo = str(tokenizer_name if tokenizer_name else model_name).lower()+ if is_peft and repo == str(old_model_name).lower():return revision- if repo == model_name:+ if repo == str(model_name).lower():return model_revisionreturn None@@ -925,6 +927,9 @@ class FastLanguageModel(FastLlamaModel):load_in_fp8 = load_in_fp8,token = token,trust_remote_code = trust_remote_code,+ local_files_only = kwargs.get("local_files_only", False),+ cache_dir = kwargs.get("cache_dir", None),+ revision = revision,)if new_model_name is None and load_in_fp8 != False:fp8_mode = _get_fp8_mode_and_check_settings(@@ -953,6 +958,10 @@ class FastLanguageModel(FastLlamaModel):("-unsloth-bnb-4bit", "-bnb-4bit")):model_name = _strip_unsloth_bnb_4bit_suffix(model_name)+ # Stripping is a remap (revision dropped); the base may only be cached under its old lowercased id.+ model_name = _prefer_legacy_lowercase_cache(+ model_name, kwargs.get("local_files_only", False), kwargs.get("cache_dir", None)+ )# Report the loader decision before fetching this repo, including adapter bases.if on_model_resolved is not None:on_model_resolved(model_name)@@ -1154,12 +1163,17 @@ class FastLanguageModel(FastLlamaModel):load_in_fp8 = load_in_fp8,token = token,trust_remote_code = trust_remote_code,+ local_files_only = kwargs.get("local_files_only", False),+ cache_dir = kwargs.get("cache_dir", None),)# Pre-quantized models allowed? AMD Instinct GPUs need blocksize = 128 on bitsandbytes < 0.49.2, and our pre-quants use 64.if not ALLOW_PREQUANTIZED_MODELS and model_name.lower().endswith(("-unsloth-bnb-4bit", "-bnb-4bit")):model_name = _strip_unsloth_bnb_4bit_suffix(model_name)+ model_name = _prefer_legacy_lowercase_cache(+ model_name, kwargs.get("local_files_only", False), kwargs.get("cache_dir", None)+ )# Report the loader decision before fetching this repo, including adapter bases.if on_model_resolved is not None:on_model_resolved(model_name)@@ -1755,7 +1769,12 @@ class FastModel(FastBaseModel):fp8_mode = Noneif not use_exact_model_name:new_model_name = get_model_name(- model_name, load_in_4bit = load_in_4bit, load_in_fp8 = load_in_fp8+ model_name,+ load_in_4bit = load_in_4bit,+ load_in_fp8 = load_in_fp8,+ local_files_only = kwargs.get("local_files_only", False),+ cache_dir = kwargs.get("cache_dir", None),+ revision = revision,)if new_model_name is None and load_in_fp8 != False:fp8_mode = _get_fp8_mode_and_check_settings(@@ -1784,6 +1803,9 @@ class FastModel(FastBaseModel):("-unsloth-bnb-4bit", "-bnb-4bit")):model_name = _strip_unsloth_bnb_4bit_suffix(model_name)+ model_name = _prefer_legacy_lowercase_cache(+ model_name, kwargs.get("local_files_only", False), kwargs.get("cache_dir", None)+ )# Report the loader decision before fetching this repo, including adapter bases.if on_model_resolved is not None:on_model_resolved(model_name)@@ -2135,12 +2157,20 @@ class FastModel(FastBaseModel):if is_peft:model_name = peft_config.base_model_name_or_pathif not use_exact_model_name:- model_name = get_model_name(model_name, load_in_4bit)+ model_name = get_model_name(+ model_name,+ load_in_4bit,+ local_files_only = kwargs.get("local_files_only", False),+ cache_dir = kwargs.get("cache_dir", None),+ )# Pre-quantized models allowed? AMD Instinct GPUs need blocksize = 128 on bitsandbytes < 0.49.2, and our pre-quants use 64.if not ALLOW_PREQUANTIZED_MODELS and model_name.lower().endswith(("-unsloth-bnb-4bit", "-bnb-4bit")):model_name = _strip_unsloth_bnb_4bit_suffix(model_name)+ model_name = _prefer_legacy_lowercase_cache(+ model_name, kwargs.get("local_files_only", False), kwargs.get("cache_dir", None)+ )# Report the loader decision before fetching this repo, including adapter bases.if on_model_resolved is not None:on_model_resolved(model_name)diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.pyindex 668f4fd69e4..47c4d191aaf 100644--- a/unsloth/models/loader_utils.py+++ b/unsloth/models/loader_utils.py@@ -53,11 +53,11 @@ WORLD_SIZE_KEYS = ("WORLD_SIZE",)LOCAL_RANK_ONLY_KEYS = ("LOCAL_RANK",)BAD_MAPPINGS = {- "unsloth/Qwen3-32B-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-32B-bnb-4bit".lower(), # 32B dynamic quant is way too big- "unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B".lower(), # HF loads MoEs too slowly- "unsloth/Qwen3-30B-A3B-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B".lower(), # We rather do it on the fly- "unsloth/Qwen3-30B-A3B-Base-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B-Base".lower(), # HF loads MoEs too slowly- "unsloth/Qwen3-30B-A3B-Base-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B-Base".lower(), # We rather do it on the fly+ "unsloth/Qwen3-32B-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-32B-bnb-4bit", # 32B dynamic quant is way too big+ "unsloth/Qwen3-30B-A3B-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B", # HF loads MoEs too slowly+ "unsloth/Qwen3-30B-A3B-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B", # We rather do it on the fly+ "unsloth/Qwen3-30B-A3B-Base-unsloth-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B-Base", # HF loads MoEs too slowly+ "unsloth/Qwen3-30B-A3B-Base-bnb-4bit".lower(): "unsloth/Qwen3-30B-A3B-Base", # We rather do it on the fly}@@ -1234,12 +1234,60 @@ def _resolve_with_mappers()+def _prefer_legacy_lowercase_cache(+ repo_id,+ local_files_only = False,+ cache_dir = None,+ revision = None,+):+ # The mapper returned lowercased ids before #2506, so an offline cache may only hold that spelling.+ if not (local_files_only or _env_says_offline()) or not isinstance(repo_id, str):+ return repo_id+ legacy = repo_id.lower()+ if legacy == repo_id:+ return repo_id+ try:+ from huggingface_hub import try_to_load_from_cache++ if cache_dir is None:+ # transformers 4.x still honours TRANSFORMERS_CACHE, which can differ from HF_HUB_CACHE.+ from transformers.utils import hub as _tf_hub+ cache_dir = getattr(_tf_hub, "TRANSFORMERS_CACHE", None)++ def cached(repo, files):+ return any(+ isinstance(+ try_to_load_from_cache(repo, f, cache_dir = cache_dir, revision = revision), str+ )+ for f in files+ )++ # A config-only canonical snapshot must not hide a legacy one that also has weights.+ weights = (+ "model.safetensors",+ "model.safetensors.index.json",+ "pytorch_model.bin",+ "pytorch_model.bin.index.json",+ )+ for files in (weights, ("config.json",)):+ if cached(repo_id, files) and cached(repo_id, ("config.json",)):+ return repo_id+ if cached(legacy, files) and cached(legacy, ("config.json",)):+ return legacy+ except Exception:+ pass+ return repo_id++def get_model_name(model_name,load_in_4bit = True,load_in_fp8 = False,token = None,trust_remote_code = False,+ local_files_only = False,+ cache_dir = None,+ revision = None,):assert load_in_fp8 in (True, False, "block")new_model_name = _resolve_with_mappers(@@ -1294,6 +1342,13 @@ def get_model_name(if new_model_name is None:new_model_name = model_name+ else:+ # Also when the result equals the input: main returned it lowercased, so that is what is cached.+ # The loader drops the revision on a real remap (_revision_for_resolved_repo), so probe main then.+ same_repo = new_model_name.lower() == str(model_name).lower()+ new_model_name = _prefer_legacy_lowercase_cache(+ new_model_name, local_files_only, cache_dir, revision if same_repo else None+ )return new_model_namediff --git a/unsloth/models/mapper.py b/unsloth/models/mapper.pyindex c3898e442d8..4210e754230 100644--- a/unsloth/models/mapper.py+++ b/unsloth/models/mapper.py@@ -1444,7 +1444,7 @@ def build_mappers(__INT_TO_FLOAT_MAPPER):for value in float8_values:if value is not None:FLOAT_TO_INT_MAPPER[value] = key- FLOAT_TO_INT_MAPPER[value.lower()] = key.lower()+ FLOAT_TO_INT_MAPPER[value.lower()] = keyvalues = float16_valuesINT_TO_FLOAT_MAPPER[key] = values[0]@@ -1466,11 +1466,11 @@ def build_mappers(__INT_TO_FLOAT_MAPPER):_add_with_lower(MAP_TO_UNSLOTH_16bit, row, values[0])pass- lowered_key = key.lower()- INT_TO_FLOAT_MAPPER[lowered_key] = values[0].lower()+ # Lowercased keys, exact-case values: HF_ENDPOINT mirrors and case-sensitive caches reject a lowercased repo id (#2506).+ INT_TO_FLOAT_MAPPER[key.lower()] = values[0]for value in values:- FLOAT_TO_INT_MAPPER[value.lower()] = lowered_key+ FLOAT_TO_INT_MAPPER[value.lower()] = key_add_with_lower(MAP_TO_UNSLOTH_16bit, "google/gemma-4-26B-A4B", "unsloth/gemma-4-26B-A4B")_add_with_lower(MAP_TO_UNSLOTH_16bit, "LiquidAI/LFM2.5-1.2B-Instruct", "unsloth/LFM2.5-1.2B-Instruct")