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.

13.5 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

"""The diffusion training menu must never offer nvfp4 or fp8_dynamic, which have no training path."""

from __future__ import annotations

import re
from pathlib import Path
from typing import get_args

import pytest

import core.training.diffusion_train_common as common
from core.inference.diffusion_lora import _DIFFUSERS_LORA_BLOCKED_QUANT
from core.inference.diffusion_precision import TE_QUANT_MODES, TE_QUANT_NVFP4
from core.training.diffusion_train_common import DiffusionLoraConfig, train_precision_modes
from models.inference import DiffusionLoadRequest, VideoLoadRequest
from models.training import DiffusionTrainingStartRequest

_BACKEND = Path(__file__).resolve().parent.parent
_FRONTEND = _BACKEND.parent / "frontend" / "src"

# The base_precision wire contract: anything outside this is a 422 before a GPU is touched.
_TRAIN_PRECISIONS: frozenset[str] = frozenset(
    get_args(DiffusionTrainingStartRequest.model_fields["base_precision"].annotation)
)

# "off"/"none"/"auto" are request sentinels, not schemes; strip them before diffing the two vocabularies.
_SENTINELS: frozenset[str] = frozenset({"auto", "none", "off"})


def _literal_names(model, field: str) -> frozenset[str]:
    """The Literal member names of an ``Optional[Literal[...]]`` field."""
    annotation = model.model_fields[field].annotation
    names = {a for a in get_args(annotation) if isinstance(a, str)}
    for arg in get_args(annotation):
        names |= {a for a in get_args(arg) if isinstance(a, str)}
    return frozenset(names)


_INFERENCE_SCHEMES: frozenset[str] = (
    _literal_names(DiffusionLoadRequest, "transformer_quant")
    | _literal_names(DiffusionLoadRequest, "text_encoder_quant")
    | frozenset(TE_QUANT_MODES)
) - _SENTINELS

# Derived so new inference-only schemes are covered; nvfp4 is pinned below so it cannot vanish.
_INFERENCE_ONLY: frozenset[str] = _INFERENCE_SCHEMES - _TRAIN_PRECISIONS

_CAPABILITIES = ((7, 5), (8, 0), (8, 6), (8, 9), (9, 0), (10, 0), (12, 0))


def _probe(
    monkeypatch,
    capability,
    *,
    cuda = True,
    torchao = True,
) -> tuple[list[str], str]:
    """Returns the recommendation too, since the Train panel seeds its base precision from it."""
    import torch

    monkeypatch.setattr(torch.cuda, "is_available", lambda: cuda)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: capability)
    monkeypatch.setattr(common, "has_functional_torchao", lambda: torchao)
    return train_precision_modes()


def _every_advertisable_mode(monkeypatch) -> frozenset[str]:
    """Union of every mode the probe can show over the GPU x torchao matrix; UI shows a subset."""
    seen: set[str] = set()
    for capability in _CAPABILITIES:
        for torchao in (True, False):
            seen.update(_probe(monkeypatch, capability, torchao = torchao)[0])
    seen.update(_probe(monkeypatch, (10, 0), cuda = False)[0])
    return frozenset(seen)


def test_nvfp4_is_a_real_inference_scheme_and_not_a_training_one():
    """Anchors the rest of the file: nvfp4 must exist on the inference side, or every
    "nvfp4 is absent" assertion below would pass for the wrong reason."""
    assert TE_QUANT_NVFP4 == "nvfp4"
    assert TE_QUANT_NVFP4 in TE_QUANT_MODES
    assert "nvfp4" in _literal_names(DiffusionLoadRequest, "transformer_quant")
    assert "nvfp4" in _literal_names(DiffusionLoadRequest, "text_encoder_quant")
    # It is also the scheme the diffusers LoRA path refuses to attach to, so it is genuinely live.
    assert "nvfp4" in _DIFFUSERS_LORA_BLOCKED_QUANT
    assert "nvfp4" in _INFERENCE_ONLY
    assert "nvfp4" not in _TRAIN_PRECISIONS


@pytest.mark.parametrize("capability", _CAPABILITIES)
@pytest.mark.parametrize("torchao", (True, False))
def test_train_precision_modes_never_offers_an_inference_only_scheme(
    monkeypatch, capability, torchao
):
    modes, recommended = _probe(monkeypatch, capability, torchao = torchao)
    leaked = sorted(_INFERENCE_ONLY.intersection(modes))
    assert not leaked, (
        f"train_precision_modes() on sm{capability[0]}{capability[1]} (torchao={torchao}) "
        f"advertises inference-only scheme(s) {leaked}; the DiT trainer has no path for them, "
        "so /diffusion/info would offer a start that evicts resident models and then fails"
    )
    # Anything advertised must also clear the request schema, or the UI offers a guaranteed 422.
    assert set(modes) <= _TRAIN_PRECISIONS, sorted(set(modes) - _TRAIN_PRECISIONS)
    assert "nf4" in modes
    # The recommendation seeds basePrecision, so it must be offered and schema-valid.
    assert recommended in modes, (
        f"the recommendation {recommended!r} is not in the modes reported for "
        f"sm{capability[0]}{capability[1]} (torchao={torchao}): {sorted(modes)}"
    )
    assert recommended in _TRAIN_PRECISIONS


def test_the_advertisable_vocabulary_is_exactly_the_schema_vocabulary(monkeypatch):
    """Across every GPU the probe can meet, the modes it emits are exactly the request
    Literal -- no more (a 422 the UI could hit) and no fewer (a dead schema member)."""
    assert _every_advertisable_mode(monkeypatch) == _TRAIN_PRECISIONS


def test_family_train_infos_never_advertises_an_inference_only_scheme(monkeypatch, dit_train_host):
    """The /diffusion/info payload itself, on a Blackwell host where every scheme is live."""
    _probe(monkeypatch, (10, 0))
    for info in common.family_train_infos():
        modes = info["precision_modes"]
        assert not _INFERENCE_ONLY.intersection(
            modes
        ), f"family {info['name']!r} advertises {sorted(_INFERENCE_ONLY.intersection(modes))}"
        assert set(modes) <= _TRAIN_PRECISIONS
        assert info["recommended_precision"] in _TRAIN_PRECISIONS


@pytest.mark.parametrize("scheme", sorted(_INFERENCE_ONLY))
def test_the_start_request_rejects_an_inference_only_precision(scheme):
    with pytest.raises(Exception) as excinfo:
        DiffusionTrainingStartRequest(
            base_model = "black-forest-labs/FLUX.1-dev",
            data_dir = "d",
            output_dir = "o",
            base_precision = scheme,
        )
    assert "base_precision" in str(excinfo.value)


def test_the_trainer_accepts_exactly_what_the_schema_advertises():
    """The trainer's hardcoded tuple must match the schema, or runs fail after evicting the model."""
    accepted, refused = set(), {}
    for mode in sorted(_TRAIN_PRECISIONS):
        config = DiffusionLoraConfig(
            base_model = "black-forest-labs/FLUX.1-dev",
            data_dir = "d",
            output_dir = "o",
            base_precision = mode,
        )
        try:
            config.normalized()
        except Exception as exc:  # noqa: BLE001 - anything that stops a start counts as a refusal
            # Any refusal blocks the advertised mode, not just the mode-name message.
            refused[mode] = f"{type(exc).__name__}: {exc}"
            continue
        accepted.add(mode)

    assert not refused, (
        f"the request schema advertises {sorted(refused)}, which DiffusionLoraConfig.normalized() "
        "rejects; a start would evict the resident model and then fail"
    )
    assert accepted == set(_TRAIN_PRECISIONS)

    # An inference-only scheme must still bounce, so the tuple is not just permissive.
    for scheme in sorted(_INFERENCE_ONLY):
        bogus = DiffusionLoraConfig(
            base_model = "black-forest-labs/FLUX.1-dev",
            data_dir = "d",
            output_dir = "o",
            base_precision = scheme,
        )
        with pytest.raises(ValueError, match = "base_precision must be one of"):
            bogus.normalized()


def test_every_training_precision_is_accepted_by_the_start_request():
    for mode in sorted(_TRAIN_PRECISIONS):
        req = DiffusionTrainingStartRequest(
            base_model = "black-forest-labs/FLUX.1-dev",
            data_dir = "d",
            output_dir = "o",
            base_precision = mode,
        )
        assert req.base_precision == mode


def _precision_memo_block() -> str:
    """The body of ``diffusion-train-panel.tsx``'s ``precisionModes`` useMemo: the type
    annotation, the reported-mode filter, and the no-backend fallback array."""
    src = (_FRONTEND / "features" / "images" / "train" / "diffusion-train-panel.tsx").read_text(
        encoding = "utf-8"
    )
    start = src.index("const precisionModes = useMemo<")
    close = src.index("\n  }, [", start)
    block = src[start : src.index(");", close) + 2]
    # Guard the extraction itself: a refactor that moves the memo must not silently shrink this to nothing.
    assert "familyUntrainable" in block and "return [" in block, block
    return block


# Match any quoting: a single-quoted arm used to slip past (verified by mutation).
_STRING_LITERAL = re.compile(r"""["'`]([^"'`\\\n]*)["'`]""")
_M_EQUALS = re.compile(r"""m === ["'`]([^"'`]+)["'`]""")


def _strip_comments(block: str) -> str:
    """Line and block comments removed, so a scheme merely NAMED in prose is not read as an
    offered option (and, the other way round, so a commented-out arm cannot mask a real one)."""
    return re.sub(r"//[^\n]*", "", re.sub(r"/\*.*?\*/", "", block, flags = re.S))


def _memo_string_literals(block: str) -> list[str]:
    return _STRING_LITERAL.findall(_strip_comments(block))


def test_the_precision_selector_names_only_training_precisions():
    """Every string literal inside the memo -- the TS union, the runtime filter whitelist and
    the fallback array -- must be a real training precision. This is the assertion that
    reddens if someone drops "nvfp4" anywhere into the Train panel's precision list."""
    literals = set(_memo_string_literals(_precision_memo_block()))
    assert literals, "parsed no string literals out of the precisionModes memo"
    assert literals <= _TRAIN_PRECISIONS, (
        f"the Train precision selector names {sorted(literals - _TRAIN_PRECISIONS)}, which "
        f"{'is' if len(literals - _TRAIN_PRECISIONS) == 1 else 'are'} not accepted by "
        "DiffusionTrainingStartRequest.base_precision"
    )
    assert not _INFERENCE_ONLY.intersection(literals)


def test_the_precision_selector_fallback_is_a_subset_of_what_the_backend_can_report(monkeypatch):
    """With no /diffusion/info report the panel falls back to a hardcoded array. It must stay
    inside what the backend could actually have said, or the first paint offers a dead option."""
    returns = re.findall(r"return\s*\[([^\]]*)\]", _strip_comments(_precision_memo_block()))
    fallback = _STRING_LITERAL.findall(returns[-1])
    assert len(fallback) >= 2, f"failed to parse the fallback array: {returns[-1]!r}"
    advertisable = _every_advertisable_mode(monkeypatch)
    assert set(fallback) <= advertisable, (
        f"the Train panel's offline fallback offers {sorted(set(fallback) - advertisable)}, "
        "which train_precision_modes() never reports on any GPU"
    )
    assert not _INFERENCE_ONLY.intersection(fallback)


def test_the_reported_mode_filter_is_a_subset_of_what_the_backend_can_report(monkeypatch):
    """The panel narrows the backend's list through an explicit ``m === "..."`` whitelist.
    Every arm of it must be a mode the backend can actually emit."""
    block = _strip_comments(_precision_memo_block())
    predicate = block[block.index(".filter(") : block.index("return [", block.index(".filter("))]
    whitelist = set(_M_EQUALS.findall(predicate))
    assert whitelist, f"parsed no whitelist arms out of {predicate!r}"
    advertisable = _every_advertisable_mode(monkeypatch)
    # Equality, not containment: a deleted arm silently drops a reported mode.
    assert whitelist == advertisable - _SENTINELS, (
        f"the panel filters to {sorted(whitelist)} but the backend can report "
        f'{sorted(advertisable - _SENTINELS)}; "auto" is prepended separately, so the filter '
        "has to name every other advertisable mode exactly"
    )
    assert not _INFERENCE_ONLY.intersection(whitelist)
    # Subtracting Auto above is sound only while every non-empty return leads with "auto".
    returns = [
        line
        for line in block.splitlines()
        if "return [" in line
        and line.strip() not in ("return [];", "if (familyUntrainable) return [];")
    ]
    assert returns, f"parsed no return arrays out of the memo: {block!r}"
    for line in returns:
        assert '"auto"' in line, f"the memo returns a list with no Auto option: {line.strip()!r}"


def test_inference_still_offers_nvfp4_end_to_end():
    """The training guard must not be "fixed" by deleting NVFP4 from inference, where it is a
    legitimate Blackwell option on both the image and the video load forms."""
    req = DiffusionLoadRequest(
        model_path = "unsloth/Z-Image-Turbo-GGUF",
        transformer_quant = "nvfp4",
        text_encoder_quant = "nvfp4",
    )
    assert req.transformer_quant == "nvfp4" and req.text_encoder_quant == "nvfp4"

    # Through the schema: video-page.tsx could keep offering NVFP4 after the schema dropped it.
    video = VideoLoadRequest(model_path = "unsloth/Wan2.2-TI2V-5B", transformer_quant = "nvfp4")
    assert video.transformer_quant == "nvfp4"

    for rel in (
        ("features", "images", "images-page.tsx"),
        ("features", "video", "video-page.tsx"),
    ):
        src = (_FRONTEND.joinpath(*rel)).read_text(encoding = "utf-8")
        assert '["nvfp4", "NVFP4 (Blackwell)"]' in src, f"{rel[-1]} no longer offers NVFP4"
    exports = (_FRONTEND / "features" / "export" / "constants.ts").read_text(encoding = "utf-8")
    assert 'value: "nvfp4"' in exports