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
gpt-oss: read config.transformers_weights before the standard filenames when probing the expert layout (#15386)
Daniel Han029a596d244d
diff --git a/tests/test_gpt_oss_transformers_weights_layout.py b/tests/test_gpt_oss_transformers_weights_layout.pynew file mode 100644index 00000000000..254efff5f78--- /dev/null+++ b/tests/test_gpt_oss_transformers_weights_layout.py@@ -0,0 +1,121 @@+# Unsloth Zoo - Utilities for Unsloth+# Copyright 2023-present Daniel Han-Chen, Michael Han-Chen & the Unsloth team. All rights reserved.+#+# This program is free software: you can redistribute it and/or modify+# it under the terms of the GNU Affero General Public License as published+# by the Free Software Foundation, either version 3 of the License, or+# (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU Affero General Public License for more details.+#+# You should have received a copy of the GNU Affero General Public License+# along with this program. If not, see <https://www.gnu.org/licenses/>.++"""`config.transformers_weights` wins over standard filenames, as in transformers' `_get_resolved_checkpoint_files`."""++import json+from types import SimpleNamespace++import pytest+import torch+from safetensors.torch import save_file++import unsloth # noqa: F401 (patches before transformers)+from unsloth.models import loader_utils++BNB_QC = {"quant_method": "bitsandbytes", "load_in_4bit": True}+P = "model.layers.0.mlp"+SPLIT = [f"{P}.experts.gate_up_projs.0.weight", f"{P}.experts.down_projs.0.weight"]+FUSED = [f"{P}.experts.gate_up_proj", f"{P}.experts.down_proj", f"{P}.router.weight"]+++def _save(path, names):+ save_file({n: torch.zeros(2, 2, dtype = torch.bfloat16) for n in names}, str(path))+++def _cfg(transformers_weights = None):+ cfg = SimpleNamespace(quantization_config = BNB_QC)+ if transformers_weights is not None:+ cfg.transformers_weights = transformers_weights+ return cfg+++def _repo(+ tmp_path,+ standard,+ chosen,+ chosen_name = "chosen.safetensors",+):+ d = tmp_path / "ckpt"+ d.mkdir()+ _save(d / "model.safetensors", standard)+ _save(d / chosen_name, chosen)+ return str(d)+++ "standard, chosen, expected",+ [(SPLIT, FUSED, True), (FUSED, SPLIT, False)],+ ids = ["split_standard_fused_chosen", "fused_standard_split_chosen"],+)+def test_explicit_file_decides_the_layout(tmp_path, standard, chosen, expected):+ path = _repo(tmp_path, standard, chosen)+ probe = loader_utils.gpt_oss_checkpoint_has_fused_experts+ assert probe(_cfg("chosen.safetensors"), path) is expected+ assert probe(_cfg(), path) is (not expected)+++def test_explicit_index_decides_the_layout(tmp_path):+ d = tmp_path / "ckpt"+ d.mkdir()+ _save(d / "model.safetensors", SPLIT)+ _save(d / "chosen-00001.safetensors", FUSED)+ (d / "chosen.safetensors.index.json").write_text(+ json.dumps({"weight_map": {n: "chosen-00001.safetensors" for n in FUSED}})+ )+ cfg = _cfg("chosen.safetensors.index.json")+ assert loader_utils.gpt_oss_checkpoint_has_fused_experts(cfg, str(d)) is True+++def test_explicit_file_ignores_variant_and_use_safetensors(tmp_path):+ path = _repo(tmp_path, SPLIT, FUSED)+ _save(tmp_path / "ckpt" / "model.fp16.safetensors", SPLIT)+ dtypes = loader_utils._checkpoint_tensor_dtypes(+ path, variant = "fp16", use_safetensors = False, transformers_weights = "chosen.safetensors"+ )+ assert loader_utils._gpt_oss_bnb_checkpoint_expert_layout(dtypes) == "fused"+++def test_invalid_or_escaping_explicit_names_never_read_other_files(tmp_path):+ path = _repo(tmp_path, SPLIT, FUSED)+ assert loader_utils.gpt_oss_checkpoint_has_fused_experts(_cfg("chosen.bin"), path) is False+ _save(tmp_path / "outside.safetensors", FUSED)+ dtypes = loader_utils._checkpoint_tensor_dtypes(+ path, transformers_weights = "../outside.safetensors"+ )+ assert dtypes is None+++def test_hub_probe_reads_the_explicit_file(monkeypatch, tmp_path):+ import huggingface_hub++ _save(tmp_path / "model.safetensors", SPLIT)+ _save(tmp_path / "chosen.safetensors", FUSED)+ asked = []++ def download(repo, filename, **kwargs):+ asked.append(filename)+ return str(tmp_path / filename)++ def no_metadata(*args, **kwargs):+ raise AssertionError("standard-name metadata must not decide an explicit file")++ monkeypatch.setattr(huggingface_hub, "hf_hub_download", download)+ monkeypatch.setattr(huggingface_hub, "get_safetensors_metadata", no_metadata)+ monkeypatch.setattr(loader_utils, "_hub_live_commit", lambda *a, **k: None)+ cfg = _cfg("chosen.safetensors")+ assert loader_utils.gpt_oss_checkpoint_has_fused_experts(cfg, "org/repo") is True+ assert asked == ["chosen.safetensors"]diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.pyindex 5e445773e54..d7c7c5df60e 100644--- a/unsloth/models/loader_utils.py+++ b/unsloth/models/loader_utils.py@@ -4174,6 +4174,26 @@ def _hub_live_commit(return None+_ESCAPING_WEIGHTS_FILENAME = object()+++def _explicit_weights_filename(transformers_weights):+ """File transformers loads instead of standard names; None if unused, sentinel if it escapes the model dir."""+ if not isinstance(transformers_weights, str) or not transformers_weights.endswith(+ (".safetensors", ".safetensors.index.json")+ ):+ return None+ base = os.path.abspath("model_dir")+ try:+ contained = (+ os.path.commonpath([base, os.path.abspath(os.path.join(base, transformers_weights))])+ == base+ )+ except ValueError:+ contained = False+ return transformers_weights if contained else _ESCAPING_WEIGHTS_FILENAME++def _checkpoint_tensor_dtypes(model_name,token = None,@@ -4183,11 +4203,15 @@ def _checkpoint_tensor_dtypes(local_files_only = False,variant = None,use_safetensors = None,+ transformers_weights = None,):"""{tensor name: dtype} (dtype only for fused experts) without downloading weights; mirrors transformers'- file order, `variant` and `use_safetensors`. Raises _UnreadableCheckpointNames for an unreadable lone .bin."""+ file order, `variant`, `use_safetensors` and `transformers_weights`. Raises _UnreadableCheckpointNames for an unreadable lone .bin."""if not isinstance(model_name, str) or not model_name:return None+ explicit = _explicit_weights_filename(transformers_weights)+ if explicit is _ESCAPING_WEIGHTS_FILENAME:+ return Nonest_index, st_single = (_with_variant(f, variant) for f in ("model.safetensors.index.json", "model.safetensors"))@@ -4198,6 +4222,13 @@ def _checkpoint_tensor_dtypes(st_index = st_single = Noneelif use_safetensors:bin_index = bin_single = None+ if explicit is not None:+ # Loaded verbatim (no variant / use_safetensors) with no fallback to standard names.+ bin_index = bin_single = None+ if explicit.endswith(".safetensors.index.json"):+ st_index, st_single = explicit, None+ else:+ st_index, st_single = None, explicitindex_files = [f for f in (st_index, bin_index) if f]def _local_shard_dtypes(path, names):@@ -4242,7 +4273,13 @@ def _checkpoint_tensor_dtypes(raise _UnreadableCheckpointNames(path)return None- if not local_files_only and not subfolder and not variant and st_single:+ if (+ not local_files_only+ and not subfolder+ and not variant+ and st_single+ and explicit is None+ ):try:from huggingface_hub import get_safetensors_metadata@@ -4376,6 +4413,7 @@ def gpt_oss_checkpoint_has_fused_experts(quant_method = getattr(quant_method, "value", quant_method)if str(quant_method).lower() != "bitsandbytes":return False+ hub_kwargs.setdefault("transformers_weights", getattr(config, "transformers_weights", None))try:dtypes = _checkpoint_tensor_dtypes(model_name, **hub_kwargs)except _UnreadableCheckpointNames as exc: