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
Put back the dimensions GGUF trims, so a GGUF pick with Precision Off loads (#11107)
Daniel Hane43b2baea540
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex 3d68a8b81a2..16e410cf2bf 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -1045,6 +1045,68 @@ def _install_gguf_prefix_strip(transformer_cls: Any, logger: Any) -> None:logger.warning("diffusion.gguf: prefix-strip shim not installed: %s", exc)+def _restore_gguf_trimmed_dims(model: Any, state_dict: Any) -> Any:+ """Put back the leading size-1 dimensions GGUF drops when it stores a tensor.++ GGUF records a shape with no leading singleton axes, so a parameter declared+ ``nn.Parameter(torch.zeros((1, dim)))`` comes back as ``(dim,)``. diffusers compares shapes+ exactly and refuses the load. Z-Image is the case in hand: ``cap_pad_token`` and+ ``x_pad_token`` are the only two tensors of 453 that disagree, both ``(1, 3840)`` against+ ``(3840,)``.++ Deliberately narrow. A tensor is reshaped only when it is a prefix-match: same element count,+ and the expected shape is the stored shape with 1s in front. That is exactly what the format+ drops and nothing else, so this cannot silently re-interpret a genuinely wrong tensor -- a+ transposed or mis-sized weight fails the element count or the suffix check and still raises.+ """+ expected = model.state_dict()+ for name, want in expected.items():+ have = state_dict.get(name)+ if have is None or tuple(have.shape) == tuple(want.shape):+ continue+ want_shape, have_shape = tuple(want.shape), tuple(have.shape)+ if have.numel() != want.numel() or len(want_shape) <= len(have_shape):+ continue+ pad = len(want_shape) - len(have_shape)+ if want_shape[:pad] != (1,) * pad or want_shape[pad:] != have_shape:+ continue+ state_dict[name] = have.reshape(want_shape)+ return state_dict+++def _install_gguf_dim_restore(logger: Any) -> None:+ """Wrap diffusers' meta loader so a GGUF's trimmed dimensions are restored before its shape+ check. Patched here rather than in the mapping fn because a GGUF whose tensor names already+ match diffusers skips conversion entirely (``_should_convert_state_dict_to_diffusers``), so the+ mapping fn never runs for it -- which is precisely the Z-Image case.++ Both names are rebound, and the second one is the one that matters: ``single_file_model``+ imports the function at MODULE level (under ``if is_accelerate_available()``), so it holds its+ own reference and patching only the defining module leaves the real call site untouched.+ Idempotent and best-effort."""+ try:+ from diffusers.loaders import single_file_model as sfm+ from diffusers.models import model_loading_utils as mlu++ original = mlu.load_model_dict_into_meta+ if getattr(original, "_unsloth_dim_restore", False):+ return++ def _restoring_loader(model, state_dict, *args: Any, **kwargs: Any):+ try:+ state_dict = _restore_gguf_trimmed_dims(model, state_dict)+ except Exception: # noqa: BLE001 - never turn a load failure into a different one+ pass+ return original(model, state_dict, *args, **kwargs)++ _restoring_loader._unsloth_dim_restore = True+ mlu.load_model_dict_into_meta = _restoring_loader+ if getattr(sfm, "load_model_dict_into_meta", None) is not None:+ sfm.load_model_dict_into_meta = _restoring_loader+ except Exception as exc: # noqa: BLE001 - loader-compat shim only, never fail the load+ logger.warning("diffusion.gguf: dim-restore shim not installed: %s", exc)++@functools.lru_cache(maxsize = None)def _no_recast_pipeline_class(pipe_cls: Any) -> Any:"""``pipe_cls`` with the dtype half of ``.to()`` dropped; device moves still work. Pipelines@@ -4953,6 +5015,7 @@ class DiffusionBackend:# sd.cpp GGUFs prefix tensors with model.diffusion_model.; the FLUX.2 / Qwen converters# choke._install_gguf_prefix_strip(transformer_cls, logger)+ _install_gguf_dim_restore(logger)# A safetensors single-file (fp8) carries its own dtype: no GGUF dequant config.transformer = transformer_cls.from_single_file(single_file_path, **sf_kwargsdiff --git a/studio/backend/tests/test_diffusion_gguf_compile.py b/studio/backend/tests/test_diffusion_gguf_compile.pyindex e345cb93a58..b0699643519 100644--- a/studio/backend/tests/test_diffusion_gguf_compile.py+++ b/studio/backend/tests/test_diffusion_gguf_compile.py@@ -10,6 +10,8 @@ on-by-default behaviour. Runs on CPU -- patching the module attribute is lazyfrom __future__ import annotations+import logging+import pytesttorch = pytest.importorskip("torch")@@ -70,3 +72,88 @@ def test_uninstall_all(monkeypatch):gc.uninstall_all()assert gc.is_installed() is Falseassert gguf_utils.dequantize_gguf_tensor is orig+++class TestGgufTrimmedDimsAreRestored:+ """GGUF stores no leading size-1 axes, so ``nn.Parameter(torch.zeros((1, dim)))`` comes back as+ ``(dim,)`` and diffusers' exact shape check refuses the load. Z-Image is the live case: a GGUF+ pick with Precision = Off died with ``cap_pad_token expected shape torch.Size([1, 3840]), but+ got torch.Size([3840])``.+ """++ @staticmethod+ def _model():+ import torch+ class _M(torch.nn.Module):+ def __init__(self):+ super().__init__()+ self.cap_pad_token = torch.nn.Parameter(torch.zeros((1, 8)))+ self.proj = torch.nn.Linear(8, 4)++ return _M()++ def test_a_trimmed_leading_axis_is_put_back(self):+ import torch++ from core.inference.diffusion import _restore_gguf_trimmed_dims++ model = self._model()+ sd = {"cap_pad_token": torch.arange(8, dtype = torch.float32)}+ out = _restore_gguf_trimmed_dims(model, sd)+ assert tuple(out["cap_pad_token"].shape) == (1, 8)+ # The values must survive the reshape in order, or the pad token is silently scrambled.+ assert torch.equal(out["cap_pad_token"].flatten(), torch.arange(8, dtype = torch.float32))++ def test_a_tensor_of_the_wrong_size_is_left_alone(self):+ """The guard must not rescue a genuinely wrong tensor: element count has to match."""+ import torch++ from core.inference.diffusion import _restore_gguf_trimmed_dims++ model = self._model()+ sd = {"cap_pad_token": torch.zeros(7)}+ out = _restore_gguf_trimmed_dims(model, sd)+ assert tuple(out["cap_pad_token"].shape) == (7,)++ def test_a_transposed_tensor_is_left_alone(self):+ """Same element count, but the expected shape is not the stored shape with 1s in front, so+ this is a real mismatch and must still reach diffusers' error rather than be reshaped."""+ import torch++ from core.inference.diffusion import _restore_gguf_trimmed_dims++ model = self._model()+ sd = {"proj.weight": torch.zeros(8, 4)} # model wants (4, 8)+ out = _restore_gguf_trimmed_dims(model, sd)+ assert tuple(out["proj.weight"].shape) == (8, 4)++ def test_the_shim_reaches_the_name_single_file_model_actually_calls(self):+ """``single_file_model`` imports the loader at module level, so it holds its own reference.+ Patching only the defining module leaves the real call site bound to the original, which is+ exactly the way the first version of this fix silently did nothing on a live load."""+ import torch++ from diffusers.loaders import single_file_model as sfm+ from diffusers.models import model_loading_utils as mlu++ from core.inference.diffusion import _install_gguf_dim_restore++ originals = (mlu.load_model_dict_into_meta, sfm.load_model_dict_into_meta)+ seen: dict = {}++ def _fake(model, state_dict, *args, **kwargs):+ seen["shape"] = tuple(state_dict["cap_pad_token"].shape)+ return []++ mlu.load_model_dict_into_meta = _fake+ sfm.load_model_dict_into_meta = _fake+ try:+ _install_gguf_dim_restore(logging.getLogger("t"))+ first = sfm.load_model_dict_into_meta+ _install_gguf_dim_restore(logging.getLogger("t"))+ assert sfm.load_model_dict_into_meta is first, "shim wrapped itself twice"+ # Call through the module the loader really uses, not the one that defines it.+ sfm.load_model_dict_into_meta(self._model(), {"cap_pad_token": torch.zeros(8)})+ assert seen["shape"] == (1, 8)+ finally:+ mlu.load_model_dict_into_meta, sfm.load_model_dict_into_meta = originals