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.

10.9 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

"""Tests for ``diffusion_flux2_rope.py``: the fused FLUX.2 RoPE engages only for an fp16 FLUX.2 load (bf16 GPUs keep the
stock function), honours its kill switch, restores cleanly, and is bit-identical to stock (CUDA tests)."""

from __future__ import annotations

import ast
from pathlib import Path

import pytest

from core.inference import diffusion_flux2_rope as fr

torch = pytest.importorskip("torch")
from torch.torch_version import TorchVersion  # noqa: E402

fmod = pytest.importorskip("diffusers.models.transformers.transformer_flux2")
from diffusers.models.embeddings import apply_rotary_emb as stock_rope  # noqa: E402

# A CUDA build's version tag: Studio reads ROCm from the "+rocm" tag too (AMD SDK / Radeon wheels leave
# torch.version.hip unset), so a test that fakes NVIDIA clears both.
_CUDA_TORCH_VERSION = TorchVersion(str(torch.__version__).split("+")[0] + "+cu130")

needs_cuda = pytest.mark.skipif(
    not torch.cuda.is_available()
    or bool(getattr(torch.version, "hip", None))
    or fr._kernel() is None,
    reason = "needs CUDA (not ROCm) and Triton",
)


class _Flux2Like:
    """A pipe whose transformer reports the FLUX.2 module, without building the model."""

    def __init__(self, module = fr._MODULE):
        self.transformer = type("Flux2Transformer2DModel", (), {"__module__": module})()


@pytest.fixture(autouse = True)
def _restore(monkeypatch):
    monkeypatch.delenv(fr.FLUX2_FUSED_ROPE_ENV, raising = False)
    fr.uninstall()
    yield
    fr.uninstall()
    assert fmod.apply_rotary_emb is stock_rope


@pytest.fixture
def fake_kernel(monkeypatch):
    """Gate tests run without a GPU: pretend Triton built the kernel on a CUDA (non-ROCm) torch."""
    monkeypatch.setattr(fr, "_kernel", lambda: (lambda x, cos, sin: None))
    monkeypatch.setattr(torch.version, "hip", None, raising = False)
    monkeypatch.setattr(torch, "__version__", _CUDA_TORCH_VERSION, raising = False)


def test_stock_symbol_is_the_one_flux2_calls():
    assert fmod.apply_rotary_emb is stock_rope
    src = Path(fmod.__file__).read_text(encoding = "utf-8")
    assert "apply_rotary_emb(query, image_rotary_emb, sequence_dim=1)" in src


def test_fp16_flux2_load_installs(fake_kernel):
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    assert fr.is_installed()
    assert fmod.apply_rotary_emb is fr._fused_apply_rotary_emb


@pytest.mark.parametrize("dtype", ["bfloat16", "float32"])
def test_bf16_and_fp32_loads_keep_stock(fake_kernel, dtype):
    assert not fr.install_for_pipe(_Flux2Like(), getattr(torch, dtype), "cuda")
    assert not fr.is_installed()
    assert fmod.apply_rotary_emb is stock_rope


def test_fp16_load_after_bf16_load_and_back(fake_kernel):
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    assert not fr.install_for_pipe(_Flux2Like(), torch.bfloat16, "cuda")
    assert fmod.apply_rotary_emb is stock_rope


@pytest.mark.parametrize("device", ["cpu", "mps", "xpu"])
def test_non_cuda_devices_keep_stock(fake_kernel, device):
    assert not fr.install_for_pipe(_Flux2Like(), torch.float16, device)
    assert fmod.apply_rotary_emb is stock_rope


def test_rocm_keeps_stock(fake_kernel, monkeypatch):
    monkeypatch.setattr(torch.version, "hip", "6.4", raising = False)
    assert not fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")


def test_other_families_keep_stock(fake_kernel):
    pipe = _Flux2Like(module = "diffusers.models.transformers.transformer_flux")
    assert not fr.install_for_pipe(pipe, torch.float16, "cuda")
    assert fmod.apply_rotary_emb is stock_rope


def test_other_family_load_removes_a_previous_install(fake_kernel):
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    assert not fr.install_for_pipe(_Flux2Like(module = "x.y"), torch.float16, "cuda")
    assert fmod.apply_rotary_emb is stock_rope


@pytest.mark.parametrize("value", ["0", "off", "false", "no"])
def test_kill_switch(fake_kernel, monkeypatch, value):
    monkeypatch.setenv(fr.FLUX2_FUSED_ROPE_ENV, value)
    assert not fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    assert fmod.apply_rotary_emb is stock_rope


def test_no_triton_keeps_stock(monkeypatch):
    monkeypatch.setattr(fr, "_kernel", lambda: None)
    assert not fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")


def test_install_is_idempotent_and_uninstall_restores(fake_kernel):
    assert fr.install(torch.float16, "cuda") and fr.install(torch.float16, "cuda")
    fr.uninstall()
    fr.uninstall()
    assert fmod.apply_rotary_emb is stock_rope


def test_cpu_tensors_fall_through_to_stock(fake_kernel):
    assert fr.install(torch.float16, "cuda")
    x = torch.randn(1, 6, 2, 8, dtype = torch.float32)
    pos = torch.randn(6, 4, dtype = torch.float64)
    freqs = (pos.cos().repeat_interleave(2, -1).float(), pos.sin().repeat_interleave(2, -1).float())
    assert torch.equal(
        fmod.apply_rotary_emb(x, freqs, sequence_dim = 1), stock_rope(x, freqs, sequence_dim = 1)
    )


def test_teardown_and_load_wiring():
    src = (Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py").read_text(
        encoding = "utf-8"
    )
    tree = ast.parse(src)
    teardown = next(
        n
        for n in ast.walk(tree)
        if isinstance(n, ast.FunctionDef) and n.name == "_uninstall_fused_dit_patches"
    )
    # The teardown restores the registry's fused-DiT group, which carries the FLUX.2 RoPE spec ...
    assert "uninstall_group(GROUP_FUSED_DIT)" in ast.unparse(teardown)
    from core.inference.diffusion_autoopt import patches as ap

    spec = next(s for s in ap.specs(group = ap.GROUP_FUSED_DIT) if s.name == "flux2_rope")
    assert spec.stage == ap.STAGE_LOAD and spec.backends == ("image",)
    # ... and the load runs that stage for the pipe with its dtype / device / logger.
    load = next(
        n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name == "load_pipeline"
    )
    assert "autoopt.STAGE_LOAD," in ast.unparse(load)
    import types as _types

    seen = []
    orig_install, orig_uninstall = fr.install_for_pipe, fr.uninstall
    try:
        fr.install_for_pipe = lambda *a: seen.append(("install", a)) or False
        fr.uninstall = lambda: seen.append(("uninstall",))
        pipe = _types.SimpleNamespace(transformer = None)
        ap.install_stage(
            ap.STAGE_LOAD,
            ap.PatchContext(pipe = pipe, dtype = "fp16", device = "cuda", logger = "log", speed_mode = "off"),
        )
        from core.inference import diffusion

        diffusion._uninstall_fused_dit_patches()
    finally:
        fr.install_for_pipe, fr.uninstall = orig_install, orig_uninstall
    assert ("install", (pipe, "fp16", "cuda", "log")) in seen and ("uninstall",) in seen


def _case(shape, layout, freq_dtype):
    B, S, H, D = shape
    g = torch.Generator("cuda").manual_seed(0)
    if layout == "qkv_chunk":
        x = (
            torch.randn(B, S, 3 * H * D, device = "cuda", dtype = torch.float16, generator = g) * 4
        ).chunk(3, -1)[1]
        x = x.unflatten(-1, (H, D))
    elif layout == "permuted":
        x = (
            torch.randn(B, H, S, D, device = "cuda", dtype = torch.float16, generator = g) * 4
        ).transpose(1, 2)
    else:
        x = torch.randn(B, S, H, D, device = "cuda", dtype = torch.float16, generator = g) * 4
    pos = torch.randn(S, D // 2, device = "cuda", dtype = torch.float64, generator = g) * 50
    return x, (
        pos.cos().repeat_interleave(2, -1).to(freq_dtype),
        pos.sin().repeat_interleave(2, -1).to(freq_dtype),
    )


@needs_cuda
@pytest.mark.parametrize(
    "shape,layout,freq_dtype",
    [
        (
            (1, 4608, 24, 128),
            "contiguous",
            "float32",
        ),  # klein-4B 1024px: 512 text + 4096 image tokens
        ((2, 1000, 24, 128), "qkv_chunk", "float32"),
        ((1, 333, 5, 64), "qkv_chunk", "float16"),
        ((1, 777, 24, 128), "permuted", "float32"),
    ],
)
def test_bit_identical_to_stock(shape, layout, freq_dtype):
    x, freqs = _case(shape, layout, getattr(torch, freq_dtype))
    ref = stock_rope(x, freqs, sequence_dim = 1)
    assert fr.install(torch.float16, "cuda")
    out = fmod.apply_rotary_emb(x, freqs, sequence_dim = 1)
    assert out.dtype == ref.dtype and out.stride() == ref.stride()
    assert torch.equal(out, ref)


@needs_cuda
def test_grad_and_bf16_calls_use_stock():
    assert fr.install(torch.float16, "cuda")
    x, freqs = _case((1, 16, 2, 8), "contiguous", torch.float32)
    xg = x.clone().requires_grad_(True)
    fmod.apply_rotary_emb(xg, freqs, sequence_dim = 1).float().sum().backward()
    assert xg.grad is not None
    xb = x.bfloat16()
    assert torch.equal(
        fmod.apply_rotary_emb(xb, freqs, sequence_dim = 1), stock_rope(xb, freqs, sequence_dim = 1)
    )


@needs_cuda
def test_compiled_block_has_no_graph_break():
    """Studio compiles FLUX.2 blocks on fp16 explicit tiers: the patch must trace as stock, never split the block."""
    assert fr.install(torch.float16, "cuda")
    x, freqs = _case((1, 64, 4, 32), "contiguous", torch.float32)
    torch._dynamo.reset()
    compiled = torch.compile(
        lambda t: fmod.apply_rotary_emb(t, freqs, sequence_dim = 1), fullgraph = True
    )
    ref = torch.compile(lambda t: stock_rope(t, freqs, sequence_dim = 1), fullgraph = True)
    assert torch.equal(compiled(x), ref(x))


def test_call_after_uninstall_reaches_stock(fake_kernel):
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    patched = fmod.apply_rotary_emb
    fr.uninstall()
    x = torch.randn(1, 4, 2, 8)
    freqs = (torch.ones(4, 8), torch.zeros(4, 8))
    assert torch.equal(patched(x, freqs, sequence_dim = 1), x)


def test_a_failed_launch_disables_the_fused_path_for_the_load(monkeypatch):
    calls = []

    def failing_launch(x, cos, sin):
        calls.append(1)
        raise RuntimeError("PTX JIT compilation failed")

    monkeypatch.setattr(fr, "_kernel", lambda: failing_launch)
    monkeypatch.setattr(fr, "_eligible", lambda *a, **k: True)
    monkeypatch.setattr(torch.version, "hip", None, raising = False)
    monkeypatch.setattr(torch, "__version__", _CUDA_TORCH_VERSION, raising = False)
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    x = torch.randn(1, 6, 2, 8)
    pos = torch.randn(6, 4, dtype = torch.float64)
    freqs = (pos.cos().repeat_interleave(2, -1).float(), pos.sin().repeat_interleave(2, -1).float())
    want = stock_rope(x, freqs, sequence_dim = 1)
    for _ in range(4):
        assert torch.equal(fmod.apply_rotary_emb(x, freqs, sequence_dim = 1), want)
    assert len(calls) == 1
    # The next load re-arms, whether or not the previous one was torn down first.
    assert fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    fmod.apply_rotary_emb(x, freqs, sequence_dim = 1)
    assert len(calls) == 2
    fr.uninstall()
    fr.install_for_pipe(_Flux2Like(), torch.float16, "cuda")
    fmod.apply_rotary_emb(x, freqs, sequence_dim = 1)
    assert len(calls) == 3