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.

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.py
index 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.py
index 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.value
if (
@@ -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.py
index 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, exa
get_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.py
index 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.py
index 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: False
namespace["_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.py
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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 revision
remedy = (
" 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_revision
return 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 = None
if 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_path
if 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.py
index 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_name
diff --git a/unsloth/models/mapper.py b/unsloth/models/mapper.py
index 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()] = key
values = float16_values
INT_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")