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.

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.py
index 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_kwargs
diff --git a/studio/backend/tests/test_diffusion_gguf_compile.py b/studio/backend/tests/test_diffusion_gguf_compile.py
index 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 lazy
from __future__ import annotations
+import logging
+
import pytest
torch = pytest.importorskip("torch")
@@ -70,3 +72,88 @@ def test_uninstall_all(monkeypatch):
gc.uninstall_all()
assert gc.is_installed() is False
assert 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