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.

7.2 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Single-file entries diffusers lacks, needed for Qwen-Image-2.1 GGUF loads on GPU backends."""

from __future__ import annotations

import pytest
import torch

from core.inference import diffusion as studio

CLASS = "QwenImage21Transformer2DModel"
PREFIX = "model.diffusion_model."


def _sfm():
    try:
        import diffusers
        from diffusers.loaders import single_file_model as sfm
    except Exception as exc:  # noqa: BLE001 - an optional integration failing is an environment fact
        pytest.skip(f"diffusers is not importable here: {type(exc).__name__}")
    return diffusers, sfm


def test_the_fused_mlp_splits_gate_first_and_the_prefix_goes():
    """Fused gate_up splits gate first: upstream bf16 weights match diffusers only in that order."""
    gate = torch.arange(0, 6 * 4, dtype = torch.float32).reshape(6, 4)
    proj = -torch.arange(0, 6 * 4, dtype = torch.float32).reshape(6, 4)
    checkpoint = {
        PREFIX + "transformer_blocks.3.img_mlp.gate_up.weight": torch.cat([gate, proj]),
        PREFIX + "transformer_blocks.3.img_mlp.out.weight": torch.ones(4, 6),
        "img_in.weight": torch.zeros(2, 2),
    }
    out = studio._qwen_image_21_checkpoint_to_diffusers(checkpoint = checkpoint, config = {})

    assert set(out) == {
        "transformer_blocks.3.img_mlp.gate_layer.weight",
        "transformer_blocks.3.img_mlp.proj.weight",
        "transformer_blocks.3.img_mlp.out.weight",
        "img_in.weight",
    }
    assert torch.equal(out["transformer_blocks.3.img_mlp.gate_layer.weight"], gate)
    assert torch.equal(out["transformer_blocks.3.img_mlp.proj.weight"], proj)


def test_an_odd_fused_tensor_is_refused_rather_than_split_wrong():
    with pytest.raises(ValueError, match = "odd row count"):
        studio._qwen_image_21_checkpoint_to_diffusers(
            checkpoint = {"transformer_blocks.0.img_mlp.gate_up.weight": torch.zeros(5, 4)}
        )


def test_a_row_split_keeps_a_gguf_tensor_quantised():
    """GGML packs blocks along the input dimension, so a row slice is whole blocks and has to stay
    a ``GGUFParameter`` of the same quant type, with the logical shape halved."""
    try:
        import gguf
        from diffusers.quantizers.gguf.utils import GGUFParameter
    except Exception as exc:  # noqa: BLE001
        pytest.skip(f"gguf support is not importable here: {type(exc).__name__}")
    qtype = gguf.GGMLQuantizationType.Q4_K
    block_size, type_size = gguf.GGML_QUANT_SIZES[qtype]
    cols = 2 * block_size
    raw = torch.randint(0, 255, (8, cols // block_size * type_size), dtype = torch.uint8)
    fused = GGUFParameter(raw, quant_type = qtype)

    out = studio._qwen_image_21_checkpoint_to_diffusers(
        checkpoint = {"transformer_blocks.0.img_mlp.gate_up.weight": fused}
    )
    for name, rows in (("gate_layer", slice(0, 4)), ("proj", slice(4, 8))):
        half = out[f"transformer_blocks.0.img_mlp.{name}.weight"]
        assert isinstance(half, GGUFParameter), name
        assert half.quant_type == qtype, name
        assert tuple(half.quant_shape) == (4, cols), name
        assert torch.equal(half.as_tensor(), raw[rows]), name


@pytest.mark.parametrize("qtype_name", ["BF16", "Q8_0"])
def test_a_packed_norm_weight_comes_out_as_real_values(qtype_name):
    """diffusers dequantises only inside the Linear layers it swaps, and a norm reads self.weight
    directly. Measured: the public Q4_K_M keeps txt_in.text_norm in BF16 and the first step died on
    "size of tensor a (4096) must match ... b (8192)" -- the raw bytes, not the values."""
    try:
        import gguf
        from diffusers.quantizers.gguf.utils import GGUFParameter, dequantize_gguf_tensor
    except Exception as exc:  # noqa: BLE001
        pytest.skip(f"gguf support is not importable here: {type(exc).__name__}")
    qtype = getattr(gguf.GGMLQuantizationType, qtype_name)
    block_size, type_size = gguf.GGML_QUANT_SIZES[qtype]
    n = 4 * block_size
    raw = torch.randint(0, 255, (n // block_size * type_size,), dtype = torch.uint8)
    packed = GGUFParameter(raw, quant_type = qtype)
    expected = dequantize_gguf_tensor(GGUFParameter(raw.clone(), quant_type = qtype))

    out = studio._qwen_image_21_checkpoint_to_diffusers(
        checkpoint = {PREFIX + "txt_in.text_norm.weight": packed}
    )["txt_in.text_norm.weight"]
    assert not hasattr(out, "quant_type")
    assert tuple(out.shape) == (n,)
    assert torch.equal(out, expected)


def test_registration_fills_the_gap_and_the_real_call_stops_refusing(monkeypatch):
    diffusers, sfm = _sfm()
    if getattr(diffusers, CLASS, None) is None:
        pytest.skip(f"this diffusers does not ship {CLASS}")
    monkeypatch.setattr(sfm, "SINGLE_FILE_LOADABLE_CLASSES", dict(sfm.SINGLE_FILE_LOADABLE_CLASSES))
    sfm.SINGLE_FILE_LOADABLE_CLASSES.pop(CLASS, None)

    # Other classes of the table (Krea 2, HunyuanImage 2.1) may register alongside it.
    assert CLASS in studio._register_unregistered_single_file_classes()
    entry = sfm.SINGLE_FILE_LOADABLE_CLASSES[CLASS]
    assert entry["checkpoint_mapping_fn"] is studio._qwen_image_21_checkpoint_to_diffusers
    assert entry["default_subfolder"] == "transformer"
    assert sfm._get_single_file_loadable_mapping_class(getattr(diffusers, CLASS)) == CLASS
    assert studio._register_unregistered_single_file_classes() == ()


def test_registration_never_overwrites_diffusers_own_entry(monkeypatch):
    diffusers, sfm = _sfm()
    upstream = {"checkpoint_mapping_fn": lambda checkpoint, **kwargs: checkpoint}
    monkeypatch.setattr(
        sfm, "SINGLE_FILE_LOADABLE_CLASSES", {**sfm.SINGLE_FILE_LOADABLE_CLASSES, CLASS: upstream}
    )
    monkeypatch.setattr(diffusers, CLASS, type(CLASS, (), {}), raising = False)

    assert CLASS not in studio._register_unregistered_single_file_classes()
    assert sfm.SINGLE_FILE_LOADABLE_CLASSES[CLASS] is upstream


def test_a_class_this_diffusers_lacks_is_not_registered(monkeypatch):
    """Not tidiness: diffusers getattr()s every registry entry on each from_single_file call, so one
    missing class breaks all single-file loads."""
    diffusers, sfm = _sfm()
    monkeypatch.setattr(sfm, "SINGLE_FILE_LOADABLE_CLASSES", dict(sfm.SINGLE_FILE_LOADABLE_CLASSES))
    assert getattr(diffusers, "NotAClassThisDiffusersShips2DModel", None) is None
    monkeypatch.setattr(
        studio,
        "_UNREGISTERED_SINGLE_FILE_CLASSES",
        {"NotAClassThisDiffusersShips2DModel": studio._qwen_image_21_checkpoint_to_diffusers},
    )

    assert studio._register_unregistered_single_file_classes() == ()
    assert "NotAClassThisDiffusersShips2DModel" not in sfm.SINGLE_FILE_LOADABLE_CLASSES


def test_the_transformer_only_single_file_branch_registers_before_loading():
    """The call site, not just the helper: registration has to precede both the prefix shim (which
    wraps whatever entry it finds) and the from_single_file it exists for."""
    import inspect

    source = inspect.getsource(studio)
    register = source.index("_register_unregistered_single_file_classes(logger)")
    shim = source.index("_install_gguf_prefix_strip(transformer_cls, logger)")
    load = source.index("transformer = transformer_cls.from_single_file(")
    assert register < shim < load