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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""CPU-only base_precision tests for config validation, auto policy and the fp8 filter; no model load."""
from __future__ import annotations
import pytest
import torch.nn as nn
import core.training.diffusion_train_common as common
from core.training import diffusion_dit_trainer as dit
from core.training.diffusion_train_common import (
DiffusionLoraConfig,
_config_from_dict,
repo_is_prequantized,
train_precision_modes,
)
from models.training import DiffusionTrainingStartRequest
_FLUX_DENSE = "black-forest-labs/FLUX.1-dev"
_Z_PREQUANT = "unsloth/Z-Image-Turbo-unsloth-bnb-4bit"
_SDXL_PREQUANT_NAME = "some/sdxl-model-bnb-4bit"
_QWEN_DENSE = "Qwen/Qwen-Image"
def _cfg(base_model = _FLUX_DENSE, **kw) -> DiffusionLoraConfig:
return DiffusionLoraConfig(base_model = base_model, data_dir = "d", output_dir = "o", **kw)
@pytest.fixture(autouse = True)
def _not_rocm(monkeypatch):
"""Pin the ROCm gate off: these cases simulate NVIDIA tiers, which an AMD host would leak."""
for _mod in (common, dit):
monkeypatch.setattr(_mod, "torch_is_rocm", lambda: False)
def test_base_precision_validation():
assert _cfg().normalized().base_precision == "nf4"
with pytest.raises(ValueError, match = "base_precision"):
_cfg(base_precision = "banana").normalized()
norm = _cfg(base_precision = " FP8 ", mixed_precision = "bf16").normalized()
assert norm.base_precision == "fp8"
with pytest.raises(ValueError, match = "dense base repo"):
_cfg(base_model = _Z_PREQUANT, base_precision = "bf16").normalized()
with pytest.raises(ValueError, match = "bf16 compute"):
_cfg(base_precision = "int8", mixed_precision = "fp16").normalized()
assert _cfg(base_model = _Z_PREQUANT, base_precision = "auto").normalized().base_precision == "auto"
def test_normalized_config_keeps_the_canonical_base_and_pins_its_fetch_mirror(monkeypatch):
from core.inference import diffusion_families
upstream = "black-forest-labs/FLUX.2-klein-base-9B"
mirror = "unsloth/FLUX.2-klein-base-9B"
seen = []
def _prefer(base, token = None):
seen.append((base, token))
return mirror
monkeypatch.setattr(diffusion_families, "prefer_ungated_mirror", _prefer)
norm = _cfg(base_model = upstream, hf_token = " token ").normalized()
assert norm.base_model == upstream
assert norm.fetch_base_model == mirror
assert norm.hf_token == "token"
assert seen == [(upstream, "token")]
sdxl = _cfg(base_model = "stabilityai/stable-diffusion-xl-base-1.0").normalized()
assert sdxl.fetch_base_model == sdxl.base_model
assert seen == [(upstream, "token")]
def test_base_precision_denies_fp8_for_corrupted_family():
with pytest.raises(ValueError, match = "fp8"):
_cfg(base_model = _QWEN_DENSE, base_precision = "fp8", mixed_precision = "bf16").normalized()
for mode in ("nf4", "bf16", "int8", "auto"):
norm = _cfg(
base_model = _QWEN_DENSE, base_precision = mode, mixed_precision = "bf16"
).normalized()
assert norm.resolved_family == "qwen-image"
assert norm.base_precision == mode
flux = _cfg(base_model = _FLUX_DENSE, base_precision = "fp8", mixed_precision = "bf16").normalized()
assert flux.resolved_family == "flux.1"
assert flux.base_precision == "fp8"
def test_family_train_infos_drops_denied_fp8_for_qwen(monkeypatch, dit_train_host):
monkeypatch.setattr(
common, "train_precision_modes", lambda: (["nf4", "bf16", "int8", "fp8", "auto"], "auto")
)
monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: None)
infos = {i["name"]: i for i in common.family_train_infos()}
assert "fp8" not in infos["qwen-image"]["precision_modes"]
assert "int8" in infos["qwen-image"]["precision_modes"]
assert "fp8" in infos["flux.1"]["precision_modes"]
def test_resolve_base_precision_explicit_int8_gates_on_torchao(monkeypatch):
spec = dit._SPECS["flux.1"]
cfg = _cfg(base_precision = "int8")
monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
with pytest.raises(ValueError, match = "torchao"):
dit._resolve_base_precision(cfg, spec, "cuda")
monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"
# The gate is int8-specific: explicit bf16/fp8 pass through regardless of torchao (fp8 on an sm89 GPU).
import torch
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 9))
monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
assert dit._resolve_base_precision(_cfg(base_precision = "bf16"), spec, "cuda") == "bf16"
assert dit._resolve_base_precision(_cfg(base_precision = "fp8"), spec, "cuda") == "fp8"
def test_bf16_unsupported_reason(monkeypatch):
import torch
from core.training.diffusion_train_common import bf16_unsupported_reason
assert bf16_unsupported_reason("sdxl") is None
assert bf16_unsupported_reason("") is None
# Pre-Ampere cards emulate bf16 and report is_bf16_supported() True, so the gate is SM >= 8.
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
assert "bfloat16" in (bf16_unsupported_reason("flux.1") or "")
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 0))
assert bf16_unsupported_reason("qwen-image") is None
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
assert bf16_unsupported_reason("z-image") is None
def test_native_bf16_supported_gates_on_capability(monkeypatch):
import torch
from core.training.diffusion_train_common import native_bf16_supported
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
assert native_bf16_supported() is False
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 0))
assert native_bf16_supported() is True
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
assert native_bf16_supported() is False
def test_training_precision_preflight_error(monkeypatch):
import torch
from core.training.diffusion_train_common import training_precision_preflight_error
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 6))
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
assert "bfloat16" in (training_precision_preflight_error("flux.1", "int8") or "")
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 6))
monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
reason = training_precision_preflight_error("qwen-image", "int8")
assert reason is not None and "int8" in reason and "torchao" in reason
monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
assert training_precision_preflight_error("qwen-image", "int8") is None
monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
assert training_precision_preflight_error("flux.1", "nf4") is None
assert training_precision_preflight_error("flux.1", "auto") is None
assert training_precision_preflight_error("sdxl", "int8") is None
assert training_precision_preflight_error("", "int8") is None
monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
monkeypatch.setattr(torch.xpu, "is_available", lambda: False)
monkeypatch.setattr(torch.mps, "is_available", lambda: False)
for dense in ("bf16", "int8", "fp8", "mxfp8"):
reason = training_precision_preflight_error("flux.1", dense)
assert reason is not None and "CUDA" in reason
for mode in ("nf4", "auto"):
reason = training_precision_preflight_error("flux.1", mode)
assert reason is not None and "GPU" in reason
assert training_precision_preflight_error("sdxl", "bf16") is None
monkeypatch.setattr(torch.xpu, "is_available", lambda: True)
assert training_precision_preflight_error("flux.1", "nf4") is None
assert training_precision_preflight_error("flux.1", "auto") is None
assert training_precision_preflight_error("flux.1", "bf16") is not None
monkeypatch.setattr(torch.xpu, "is_available", lambda: False)
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (9, 0))
reason = training_precision_preflight_error("flux.1", "mxfp8")
assert reason is not None and "Blackwell" in reason
assert training_precision_preflight_error("flux.1", "bf16") is None
assert training_precision_preflight_error("flux.1", "fp8") is None
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (10, 0))
assert training_precision_preflight_error("flux.1", "mxfp8") is None
assert training_precision_preflight_error("sdxl", "mxfp8") is None
def test_family_train_infos_empties_dit_modes_on_non_bf16(monkeypatch):
from core.training.diffusion_train_common import _DIT_TRAIN_FAMILIES, family_train_infos
monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: "no bfloat16 on this GPU")
infos = {info["name"]: info for info in family_train_infos()}
dit_seen = False
for name, info in infos.items():
if name in _DIT_TRAIN_FAMILIES:
dit_seen = True
assert info["precision_modes"] == []
assert info["vram_note"] == "no bfloat16 on this GPU"
assert info["recommended_precision"] == "nf4"
assert info["supports_compile"] is False
assert dit_seen
def test_family_train_infos_drops_base_specs_on_a_dit_block(monkeypatch, dit_train_host):
# FamilyFacts renders vram_note only with no chips, so per-base chips must be cleared too.
from core.training.diffusion_train_common import _DIT_TRAIN_FAMILIES, family_train_infos
unblocked = {info["name"]: info for info in family_train_infos()}
assert any(unblocked[n]["base_specs"] for n in _DIT_TRAIN_FAMILIES if n in unblocked)
monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: "no bfloat16 on this GPU")
for name, info in (
(n, i)
for n, i in ((i["name"], i) for i in family_train_infos())
if n in _DIT_TRAIN_FAMILIES
):
assert info["base_specs"] == {}, name
assert info["vram_note"] == "no bfloat16 on this GPU", name
def test_base_precision_gates_skip_sdxl():
norm = _cfg(base_model = _SDXL_PREQUANT_NAME, base_precision = "bf16").normalized()
assert norm.resolved_family == "sdxl"
assert norm.base_precision == "bf16"
norm2 = _cfg(
base_model = "stabilityai/stable-diffusion-xl-base-1.0",
base_precision = "int8",
mixed_precision = "fp16",
).normalized()
assert norm2.resolved_family == "sdxl"
with pytest.raises(ValueError, match = "base_precision"):
_cfg(base_model = _SDXL_PREQUANT_NAME, base_precision = "banana").normalized()
with pytest.raises(ValueError, match = "dense base repo"):
_cfg(base_model = _Z_PREQUANT, base_precision = "bf16").normalized()
@pytest.mark.parametrize(
"repo, expected",
[
("unsloth/Qwen-Image-2512-unsloth-bnb-4bit", True),
("some/model-4bit", True),
("some/model-int4", True),
("some/model-nf4", True),
("black-forest-labs/FLUX.1-dev", False),
("Tongyi-MAI/Z-Image-Turbo", False),
],
)
def test_repo_is_prequantized_cases(repo, expected):
assert repo_is_prequantized(repo) is expected
def test_repo_is_prequantized_alias_is_same_object():
assert dit._repo_is_prequantized is repo_is_prequantized
def test_pick_auto_precision_policy_table():
p = dit._pick_auto_precision
assert p(True, "cuda", 140, 23.8, (10, 0), True) == "nf4"
assert p(False, "cpu", 140, 23.8, (10, 0), True) == "nf4"
assert p(False, "cuda", None, 23.8, (10, 0), True) == "nf4"
# Compiled bf16 measured faster than torchao float8 at LoRA shapes.
assert p(False, "cuda", 140, 23.8, (10, 0), True) == "bf16"
assert p(False, "cuda", 140, 23.8, (8, 0), True) == "bf16"
assert p(False, "cuda", 140, 23.8, (10, 0), False) == "bf16"
# 30 > 23.8 * 1.15 (int8 band) but not > 23.8 * 1.5 (bf16 band).
assert p(False, "cuda", 30, 23.8, (10, 0), True) == "int8"
assert p(False, "cuda", 30, 23.8, (10, 0), True, False) == "nf4"
assert p(False, "cuda", 140, 23.8, (10, 0), True, False) == "bf16"
assert p(False, "cuda", 25, 23.8, (10, 0), True) == "nf4"
assert p(False, "cuda", 10, 23.8, (10, 0), True) == "nf4"
def test_resolve_base_precision_passes_explicit_through():
spec = dit._SPECS["flux.1"]
cfg = _cfg(base_precision = "bf16")
assert dit._resolve_base_precision(cfg, spec, "cuda") == "bf16"
with pytest.raises(ValueError, match = "CUDA"):
dit._resolve_base_precision(cfg, spec, "cpu")
assert dit._resolve_base_precision(_cfg(base_precision = "nf4"), spec, "cpu") == "nf4"
def test_resolve_auto_requires_bf16_compute():
spec = dit._SPECS["flux.1"]
cfg = _cfg(base_precision = "auto", mixed_precision = "fp16")
assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"
def test_resolve_auto_int8_band_gates_on_torchao(monkeypatch):
import torch
spec = dit._SPECS["flux.1"]
cfg = _cfg(base_precision = "auto", mixed_precision = "bf16")
class _FakeCuda:
@staticmethod
def mem_get_info():
return (int(30 * 1e9), int(80 * 1e9))
@staticmethod
def get_device_capability():
return (10, 0)
monkeypatch.setattr(torch, "cuda", _FakeCuda)
monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"
monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"
def test_resolve_auto_uses_klein_variant_size(monkeypatch):
import torch
spec = dit._SPECS["flux.2-klein"]
class _FakeCuda:
@staticmethod
def mem_get_info():
return (int(20 * 1e9), int(24 * 1e9))
@staticmethod
def get_device_capability():
return (10, 0)
monkeypatch.setattr(torch, "cuda", _FakeCuda)
monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
four_b = _cfg(
base_model = "black-forest-labs/FLUX.2-klein-base-4B",
base_precision = "auto",
mixed_precision = "bf16",
)
nine_b = _cfg(
base_model = "unsloth/FLUX.2-klein-base-9B",
base_precision = "auto",
mixed_precision = "bf16",
)
assert dit._resolve_base_precision(four_b, spec, "cuda") == "bf16"
assert dit._resolve_base_precision(nine_b, spec, "cuda") == "nf4"
def test_resolve_auto_int8_band_treats_stub_as_absent(monkeypatch):
# Windows-ROCm torchao stub (find_spec ok, quantize_ no-op): the int8 band must fall to nf4.
import torch
spec = dit._SPECS["flux.1"]
cfg = _cfg(base_precision = "auto", mixed_precision = "bf16")
class _FakeCuda:
@staticmethod
def mem_get_info():
return (int(30 * 1e9), int(80 * 1e9))
@staticmethod
def get_device_capability():
return (10, 0)
monkeypatch.setattr(torch, "cuda", _FakeCuda)
monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"
def _fake_cuda_with_free_gb(monkeypatch, free_gb: float):
"""Point torch.cuda at a GPU reporting ``free_gb`` free, so the auto pick is deterministic."""
import torch
class _FakeCuda:
@staticmethod
def mem_get_info():
return (int(free_gb * 1e9), int(80 * 1e9))
@staticmethod
def get_device_capability():
return (10, 0)
monkeypatch.setattr(torch, "cuda", _FakeCuda)
monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
@pytest.mark.parametrize(
"base_model",
[
"black-forest-labs/FLUX.2-klein-9B",
"black-forest-labs/FLUX.2-klein-base-9B",
"unsloth/FLUX.2-klein-9B",
"unsloth/FLUX.2-klein-base-9B",
],
)
def test_auto_sizes_flux2_klein_9b_off_its_own_weights(monkeypatch, base_model):
# Family dense_bf16_gb (8.1) is the 4B; 9B dense is 18.2 GB, so 20 GB free must pick nf4.
spec = dit._SPECS["flux.2-klein"]
_fake_cuda_with_free_gb(monkeypatch, 20.0)
cfg = _cfg(base_model = base_model, base_precision = "auto", mixed_precision = "bf16")
assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"
assert dit._dense_bf16_gb(spec, base_model) > 2 * spec.dense_bf16_gb
def test_auto_still_picks_bf16_for_the_klein_4b_default(monkeypatch):
spec = dit._SPECS["flux.2-klein"]
_fake_cuda_with_free_gb(monkeypatch, 20.0)
cfg = _cfg(
base_model = "black-forest-labs/FLUX.2-klein-4B",
base_precision = "auto",
mixed_precision = "bf16",
)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "bf16"
def test_the_klein_4b_bf16_band_edge_does_not_move(monkeypatch):
# Band edge is dense_gb * 1.5: 8.1 -> 12.15 keeps int8; 7.8 -> 11.70 would flip to bf16.
spec = dit._SPECS["flux.2-klein"]
_fake_cuda_with_free_gb(monkeypatch, 12.0)
cfg = _cfg(
base_model = "black-forest-labs/FLUX.2-klein-4B",
base_precision = "auto",
mixed_precision = "bf16",
)
assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"
def test_dense_bf16_gb_keeps_every_base_without_an_override_exactly_where_it_was():
# Only klein 9B is overridden; the shared family table differs (7.8 vs 8.1), never read through.
for name in ("flux.1", "qwen-image", "z-image", "krea-2", "flux.2-dev", "flux.2-klein"):
spec = dit._SPECS[name]
for base in ("some/unknown-base", spec.family, ""):
assert dit._dense_bf16_gb(spec, base) == spec.dense_bf16_gb
klein = dit._SPECS["flux.2-klein"]
for base in (
"black-forest-labs/FLUX.2-klein-4B",
"black-forest-labs/FLUX.2-klein-base-4B",
"unsloth/FLUX.2-klein-4B",
):
assert dit._dense_bf16_gb(klein, base) == klein.dense_bf16_gb
def test_dense_bf16_gb_survives_a_broken_lookup(monkeypatch):
import core.inference.diffusion_auto_policy as ap
def _boom(*_a, **_kw):
raise RuntimeError("table unavailable")
monkeypatch.setattr(ap, "base_repo_bf16_components_gb", _boom)
spec = dit._SPECS["flux.2-klein"]
assert dit._dense_bf16_gb(spec, "unsloth/FLUX.2-klein-base-9B") == pytest.approx(
spec.dense_bf16_gb
)
def test_has_functional_torchao_rejects_stub(monkeypatch):
import importlib
import types
from core._torchao_stub import _STUB_SENTINEL
real_import_module = importlib.import_module
stub_quant = types.ModuleType("torchao.quantization")
stub_quant._unsloth_stub = _STUB_SENTINEL
def _fake_import(name, *args, **kwargs):
if name == "torchao.quantization":
return stub_quant
return real_import_module(name, *args, **kwargs)
monkeypatch.setattr(importlib, "import_module", _fake_import)
assert common.has_functional_torchao() is False
real_like = types.ModuleType("torchao.quantization")
real_like.Int8WeightOnlyConfig = object
real_like.quantize_ = lambda *a, **k: None
def _fake_import_real(name, *args, **kwargs):
if name == "torchao.quantization":
return real_like
return real_import_module(name, *args, **kwargs)
monkeypatch.setattr(importlib, "import_module", _fake_import_real)
assert common.has_functional_torchao() is True
def test_fp8_module_filter():
lin = nn.Linear(64, 64)
assert dit._fp8_module_filter(lin, "transformer_blocks.0.ff.net.0") is True
assert dit._fp8_module_filter(lin, "transformer_blocks.0.attn.to_q.lora_A.default") is False
assert dit._fp8_module_filter(lin, "proj_out") is False
assert dit._fp8_module_filter(nn.Linear(30, 64), "transformer_blocks.0.ff.net.0") is False
assert dit._fp8_module_filter(nn.LayerNorm(64), "transformer_blocks.0.norm") is False
def _real_cuda():
import torch
# Other suites in a worker can leave torch.cuda.is_available() spoofed True; the C call asks the driver.
return torch.cuda.is_available() and getattr(torch._C, "_cuda_getDeviceCount", lambda: 0)() > 0
def _block_model(bias = False):
import torch
class Block(nn.Module):
def __init__(self):
super().__init__()
self.ff = nn.Linear(64, 64, bias = bias)
self.norm1 = nn.Module()
self.norm1.linear = nn.Linear(64, 64 * 6, bias = True) # AdaLN: M = batch rows
class Model(nn.Module):
_repeated_blocks = ["Block"]
def __init__(self):
super().__init__()
self.time_mod_proj = nn.Linear(64, 64 * 6, bias = False)
self.blocks = nn.ModuleList([Block(), Block()])
self.final_layer = nn.Module()
self.final_layer.linear = nn.Linear(64, 64)
return Model().to(torch.bfloat16)
def test_float8_filters_stay_inside_the_repeated_blocks():
m = _block_model()
for base in (dit._fp8_module_filter, dit._mx_module_filter):
f = dit._in_repeated_blocks(m, base)
assert f(m.blocks[1].ff, "blocks.1.ff") is True
assert f(m.time_mod_proj, "time_mod_proj") is False
assert f(m.blocks[0].ff, "blocks.0.ff.lora_A.default") is False
assert (
dit._in_repeated_blocks(nn.Linear(64, 64), dit._fp8_module_filter) is dit._fp8_module_filter
)
@pytest.mark.parametrize(
"family, fqn, kept",
[
("flux.1", "transformer_blocks.0.attn.to_q", True),
("flux.1", "transformer_blocks.0.ff.net.0.proj", True),
("flux.1", "transformer_blocks.0.norm1.linear", False),
("flux.1", "transformer_blocks.0.norm1_context.linear", False),
("flux.1", "single_transformer_blocks.0.norm.linear", False),
("flux.1", "single_transformer_blocks.0.proj_mlp", True),
("flux.2-klein", "single_transformer_blocks.0.attn.to_qkv_mlp_proj", True),
("flux.2-klein", "double_stream_modulation_img.linear", False),
("z-image", "layers.0.feed_forward.w1", True),
("z-image", "layers.0.adaLN_modulation.0", False),
("z-image", "noise_refiner.0.adaLN_modulation.0", False),
("krea-2", "transformer_blocks.0.ff.gate", True),
("krea-2", "time_mod_proj", False),
("krea-2", "final_layer.linear", False),
("ltx-2", "transformer_blocks.0.attn1.to_q", True),
("ltx-2", "transformer_blocks.0.audio_attn1.to_q", False),
("ltx-2", "transformer_blocks.0.audio_ff.net.0.proj", False),
("ltx-2", "transformer_blocks.0.video_to_audio_attn.to_k", False),
],
)
def test_lowp_filters_skip_small_m_linears(family, fqn, kept):
import torch
lin = nn.Linear(3072, 3072, bias = True).to(torch.bfloat16)
tokens = dit._lowp_exclude_tokens(family)
assert dit._fp8_module_filter(lin, fqn, tokens) is kept
assert dit._mx_module_filter(lin, fqn, tokens) is kept
def test_lowp_exclusions_extend_the_int8_small_m_list():
from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
for family in (None, "flux.1", "ltx-2", "krea-2"):
tokens = dit._lowp_exclude_tokens(family)
assert set(exclude_tokens_for_scheme("int8", family)) <= set(tokens)
assert "final_layer" in tokens
assert "audio" in dit._lowp_exclude_tokens("ltx-2")
assert "audio" not in dit._lowp_exclude_tokens("flux.1")
def test_mx_input_hook_mirrors_autocast():
import torch
x = torch.ones(2, 4)
assert dit._autocast_mx_input(None, (x,)) is None # CPU / no autocast: untouched
if not _real_cuda():
pytest.skip("needs CUDA autocast")
xc = x.cuda()
assert dit._autocast_mx_input(None, (xc,)) is None
with torch.autocast("cuda", dtype = torch.bfloat16):
(out,) = dit._autocast_mx_input(None, (xc,))
assert out.dtype == torch.bfloat16
assert dit._autocast_mx_input(None, (xc.bfloat16(),)) is None
@pytest.mark.parametrize("mode", ["mxfp8"])
def test_lowp_apply_without_torchao_is_a_noop_with_warning(monkeypatch, mode):
import sys
for name in (
"torchao",
"torchao.float8",
"torchao.quantization",
"torchao.prototype.mx_formats",
"torchao.prototype.moe_training.config",
):
monkeypatch.setitem(sys.modules, name, None)
m = _block_model()
before = [type(x) for x in m.modules()]
events = []
apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
assert apply(m, events.append, "flux.1") is False
assert [type(x) for x in m.modules()] == before
assert [e["type"] for e in events] == ["warning"] and mode in events[0]["message"]
def _fake_mx_backend(monkeypatch, *, with_linear_cls = True):
"""A torchao 0.18-shaped MX API without the GPU: records the swaps."""
import sys
from types import SimpleNamespace
class _Op:
wgrad_with_hp = True
kernel_preference = "auto"
scale_calculation_mode = "rceil"
class _Recipe:
MXFP8_RCEIL_WGRAD_WITH_HP = "hp"
class MXFP8Linear(nn.Linear):
pass
quantized = []
monkeypatch.setitem(sys.modules, "torchao.prototype.mx_formats", None)
cfg_mod = SimpleNamespace(
MXFP8TrainingOpConfig = SimpleNamespace(from_recipe = lambda r: _Op()),
MXFP8TrainingRecipe = _Recipe,
)
monkeypatch.setitem(sys.modules, "torchao.prototype.moe_training.config", cfg_mod)
monkeypatch.setitem(
sys.modules,
"torchao.prototype.moe_training.mxfp8_linear",
SimpleNamespace(MXFP8Linear = MXFP8Linear) if with_linear_cls else None,
)
def quantize_(model, config, filter_fn):
for fqn, mod in model.named_modules():
if filter_fn(mod, fqn):
quantized.append(fqn)
monkeypatch.setitem(sys.modules, "torchao.quantization", SimpleNamespace(quantize_ = quantize_))
return MXFP8Linear, quantized
def test_mxfp8_swaps_biased_and_unbiased_block_linears_once(monkeypatch):
linear_cls, quantized = _fake_mx_backend(monkeypatch)
m = _block_model(bias = True)
params = [id(p) for p in m.parameters()]
assert dit._apply_mxfp8_training(m, None, "flux.1") is True
swapped = sorted(n for n, x in m.named_modules() if type(x) is linear_cls)
# Biased block linears included; AdaLN (norm1.linear), top-level and final_layer stay bf16.
assert swapped == ["blocks.0.ff", "blocks.1.ff"]
assert m.blocks[0].ff.wgrad_with_hp is True and quantized == []
assert [id(p) for p in m.parameters()] == params # the Parameters stay
hooks = len(m.blocks[0].ff._forward_pre_hooks)
assert dit._apply_mxfp8_training(m, None, "flux.1") is True
assert len(m.blocks[0].ff._forward_pre_hooks) == hooks == 1
def test_mxfp8_torchao_0_17_keeps_biased_linears_dense(monkeypatch):
# Without MXFP8Linear the quantize_ weight wrapper is the only path, and it drops F.linear's bias (pytorch/ao#4846).
_, quantized = _fake_mx_backend(monkeypatch, with_linear_cls = False)
m = _block_model(bias = True)
events = []
assert dit._apply_mxfp8_training(m, events.append, "flux.1") is False
assert quantized == [] and "no eligible linear layers" in events[0]["message"]
m2 = _block_model(bias = False)
assert dit._apply_mxfp8_training(m2, None, "flux.1") is True
assert quantized == ["blocks.0.ff", "blocks.1.ff"]
def test_fp8_quantizes_each_frozen_base_weight_once():
import torch
from core.training.diffusion_frozen_fp8 import FrozenFp8Linear
m = _block_model(bias = True).requires_grad_(False)
ref = {
fqn: mod.weight.float().clone()
for fqn, mod in m.named_modules()
if isinstance(mod, nn.Linear)
}
assert dit._convert_fp8(m, "flux.1") is True
swapped = {fqn: mod for fqn, mod in m.named_modules() if isinstance(mod, FrozenFp8Linear)}
# Only the repeated blocks' big linears; the AdaLN rows stay bf16 like the int8 / MX paths.
assert sorted(swapped) == ["blocks.0.ff", "blocks.1.ff"]
for fqn, mod in swapped.items():
assert mod.weight.dtype == torch.float8_e4m3fn and not isinstance(mod.weight, nn.Parameter)
assert mod._studio_lowp == "fp8" and mod.bias is not None and not mod.bias.requires_grad
deq = mod.weight.float() * mod.weight_scale.t()
assert ((deq - ref[fqn]).norm() / ref[fqn].norm()).item() < 0.04
# The bf16 weight is gone: no frozen base Parameter left on a converted path, so its memory is freed.
assert not any(n.endswith("ff.weight") for n, _ in m.named_parameters())
def test_fp8_layer_that_fails_stays_bf16_and_the_rest_convert(monkeypatch):
import core.training.diffusion_frozen_fp8 as ff
real = ff._quantize_weight
calls = []
def flaky(w, rows = 2048):
calls.append(1)
if len(calls) == 1:
raise RuntimeError("CUDA out of memory")
return real(w, rows)
monkeypatch.setattr(ff, "_quantize_weight", flaky)
m = _block_model().requires_grad_(False)
events = []
assert dit._apply_fp8_training(m, events.append, "flux.1") is True
kinds = sorted(type(b.ff).__name__ for b in m.blocks)
assert kinds == ["FrozenFp8Linear", "Linear"]
assert any("1 layer(s)" in e.get("message", "") for e in events)
def test_fp8_chunked_quantization_matches_one_shot():
import torch
from core.training.diffusion_frozen_fp8 import _quantize_weight, _rowwise_quant
w = (
torch.randn(300, 64, dtype = torch.bfloat16)
* torch.logspace(-3, 3, 300).unsqueeze(1).bfloat16()
)
q1, s1 = _rowwise_quant(w)
q2, s2 = _quantize_weight(w, rows = 64)
assert torch.equal(q1.view(torch.uint8), q2.view(torch.uint8)) and torch.equal(s1, s2)
def test_fp8_conversion_needs_no_torchao(monkeypatch):
import sys
for name in ("torchao", "torchao.float8", "torchao.quantization"):
monkeypatch.setitem(sys.modules, name, None)
m = _block_model().requires_grad_(False)
assert dit._apply_fp8_training(m, lambda e: None, "flux.1") is True
def _lowp_gpu_ready(mode):
import torch
if not _real_cuda():
return False
need = (8, 9) if mode == "fp8" else (10, 0)
return torch.cuda.get_device_capability() >= need
@pytest.mark.parametrize("mode", ["fp8", "mxfp8"])
@pytest.mark.parametrize("compiled", [False, True])
def test_lowp_backward_on_odd_token_counts(mode, compiled):
"""Token counts not divisible by 16 / 32 (LTX-2 192x320 = 60) raised in the frozen grad_weight GEMM."""
import torch
if not _lowp_gpu_ready(mode):
pytest.skip(f"{mode} needs a capable CUDA GPU")
pytest.importorskip("torchao")
class Block(nn.Module):
def __init__(self):
super().__init__()
self.ff = nn.Linear(256, 512, bias = True)
def forward(self, x):
return self.ff(x)
class Model(nn.Module):
_repeated_blocks = ["Block"]
def __init__(self):
super().__init__()
self.blocks = nn.ModuleList([Block()])
def forward(self, x):
return self.blocks[0](x)
torch.manual_seed(0)
ref = Model().to("cuda", torch.bfloat16).requires_grad_(False)
m = Model().to("cuda", torch.bfloat16).requires_grad_(False)
m.load_state_dict(ref.state_dict())
apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
events = []
applied = apply(m, events.append, "flux.1")
# torchao 0.17 on torch 2.11 (the installer's pairing) refuses MX training on any GPU; the fallback is the test.
if not applied and mode == "mxfp8" and any("unavailable" in str(e) for e in events):
pytest.skip(f"this torch / torchao cannot run mxfp8 training: {events}")
assert applied is True, events
assert type(m.blocks[0].ff) is not nn.Linear
run = torch.compile(m, fullgraph = True, dynamic = True) if compiled else m
for tokens in (60, 240, 1008, 1024):
x = torch.randn(1, tokens, 256, device = "cuda", requires_grad = True)
xr = x.detach().clone().requires_grad_(True)
with torch.autocast("cuda", dtype = torch.bfloat16):
y = run(x)
yr = ref(xr)
g = torch.randn_like(yr)
y.backward(g)
yr.backward(g)
rel = lambda a, b: float((a.float() - b.float()).norm() / b.float().norm()) # noqa: E731
assert rel(y, yr) < 0.1 and rel(x.grad, xr.grad) < 0.1, (
tokens,
rel(y, yr),
rel(x.grad, xr.grad),
)
assert m.blocks[0].ff.weight.grad is None
# ── _should_compile fp8 branch ────────────────────────────────────────────────
def test_should_compile_fp8_branch():
cfg = _cfg(compile_transformer = "auto")
assert dit._should_compile(cfg, False, "cuda", "fp8") is True
assert dit._should_compile(cfg, True, "cuda", "fp8") is True
assert dit._should_compile(_cfg(compile_transformer = "off"), False, "cuda", "fp8") is False
def test_train_precision_modes_no_cuda(monkeypatch):
import torch
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
assert train_precision_modes() == (["nf4"], "nf4")
def test_train_precision_modes_gates_int8_fp8_on_torchao(monkeypatch):
# int8/mxfp8 are only advertised when torchao is FUNCTIONAL: their explicit paths import it with no fallback.
# fp8 runs on torch's own _scaled_mm, so only the GPU decides.
import torch
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda: True)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda: (10, 0))
monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
modes, recommended = train_precision_modes()
assert modes == ["nf4", "bf16", "fp8", "auto"]
assert recommended == "auto"
monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
modes2, _ = train_precision_modes()
assert modes2 == ["nf4", "bf16", "int8", "fp8", "mxfp8", "auto"]
def test_train_precision_modes_gates_dense_on_bf16_support(monkeypatch):
import torch
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda: False)
monkeypatch.setattr(torch.cuda, "get_device_capability", lambda: (7, 5))
monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
modes, recommended = train_precision_modes()
assert modes == ["nf4"]
assert recommended == "nf4"
def test_family_train_infos_carries_precision_fields(monkeypatch, dit_train_host):
monkeypatch.setattr(common, "train_precision_modes", lambda: (["nf4", "bf16"], "auto"))
monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: None)
infos = {i["name"]: i for i in common.family_train_infos()}
flux = infos["flux.1"]
assert flux["precision_modes"] == ["nf4", "bf16"]
assert flux["recommended_precision"] == "auto"
assert flux["supports_compile"] is True
sdxl = infos["sdxl"]
assert sdxl["precision_modes"] == []
assert sdxl["recommended_precision"] == "nf4"
assert sdxl["supports_compile"] is True
def test_request_model_base_precision():
req = DiffusionTrainingStartRequest(base_model = "x", data_dir = "d", output_dir = "o")
assert req.base_precision == "nf4"
assert (
DiffusionTrainingStartRequest(
base_model = "x", data_dir = "d", output_dir = "o", base_precision = "fp8"
).base_precision
== "fp8"
)
with pytest.raises(Exception):
DiffusionTrainingStartRequest(
base_model = "x", data_dir = "d", output_dir = "o", base_precision = "int4"
)
cfg = _config_from_dict(
{
"base_model": _FLUX_DENSE,
"data_dir": "d",
"output_dir": "o",
"base_precision": "bf16",
}
)
assert cfg.base_precision == "bf16"
def test_assert_trusted_base_model_rejects_local_non_pipeline(tmp_path):
bad = tmp_path / "bare-base"
bad.mkdir()
with pytest.raises(ValueError, match = "model_index.json"):
common._assert_trusted_base_model(str(bad))
manifest = (
'{"_class_name":"DiffusionPipeline","transformer":["diffusers","Transformer2DModel"]}'
)
(bad / "model_index.json").write_text(manifest)
(bad / "transformer").mkdir()
(bad / "transformer" / "config.json").write_text("{}")
(bad / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
common._assert_trusted_base_model(str(bad))
with pytest.raises(ValueError, match = "untrusted"):
common._assert_trusted_base_model("evil/base")
def test_quoted_local_base_is_unquoted_before_the_trust_gate(tmp_path):
# #9605: Windows "Copy as path" quotes the folder.
base = tmp_path / "my sdxl"
base.mkdir()
(base / "model_index.json").write_text(
'{"_class_name":"DiffusionPipeline","transformer":["diffusers","Transformer2DModel"]}'
)
(base / "transformer").mkdir()
(base / "transformer" / "config.json").write_text("{}")
(base / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
for pasted in (f'"{base}"', f"'{base}'", f' "{base}" '):
req = DiffusionTrainingStartRequest(base_model = pasted, data_dir = "d", output_dir = "o")
assert req.base_model == str(base)
common._assert_trusted_base_model(req.base_model) # no raise
for written in ("unsloth/sdxl-base", str(base), '"half', 'a"b"', "\"x'"):
req = DiffusionTrainingStartRequest(base_model = written, data_dir = "d", output_dir = "o")
assert req.base_model == written
def test_single_file_training_base_names_the_checkpoint(tmp_path):
# #9605: still refused, but the refusal says why, echoing only the caller's own path.
models = tmp_path / "stable-diffusion"
models.mkdir()
ckpt = models / "sd_xl_base_1.0.safetensors"
ckpt.write_bytes(b"x")
for base, what in (
(models, "holds single-file checkpoints"),
(ckpt, "is a single-file checkpoint"),
):
with pytest.raises(ValueError, match = what) as err:
common._assert_trusted_base_model(str(base))
assert f"'{base}' {what}" in str(err.value)
with pytest.raises(ValueError) as err:
common._assert_trusted_base_model(str(models))
assert ckpt.name not in str(err.value)
# A macOS AppleDouble sidecar is not a checkpoint.
sidecar = tmp_path / "sidecar-only"
sidecar.mkdir()
(sidecar / "._sd_xl.safetensors").write_bytes(b"\x00\x05\x16\x07" + b"\x00" * 28)
# Only the wrapper goes: a name that really ends in a space keeps it.
req = DiffusionTrainingStartRequest(base_model = f'"{models} "', data_dir = "d", output_dir = "o")
assert req.base_model == f"{models} "
# The SDXL repo ships a root checkpoint beside model_index.json.
component = tmp_path / "unet"
component.mkdir()
(component / "config.json").write_text("{}")
(component / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
partial = tmp_path / "partial-sdxl"
partial.mkdir()
(partial / "model_index.json").write_text(
'{"_class_name":"StableDiffusionXLPipeline","unet":["diffusers","UNet2DConditionModel"]}'
)
(partial / "sd_xl_base_1.0.safetensors").write_bytes(b"x")
lora = tmp_path / "my_lora"
lora.mkdir()
(lora / "pytorch_lora_weights.safetensors").write_bytes(b"x")
for base in (component, partial, lora, sidecar, tmp_path / "empty"):
base.mkdir(exist_ok = True)
with pytest.raises(ValueError, match = "not a diffusers pipeline directory"):
common._assert_trusted_base_model(str(base))
def test_dit_accelerator_missing_reason_and_info_hide_train_without_a_gpu(monkeypatch):
import torch
from core.training.diffusion_train_common import (
_DIT_TRAIN_FAMILIES,
dit_accelerator_missing_reason,
family_train_infos,
)
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
monkeypatch.setattr(torch.xpu, "is_available", lambda: False)
monkeypatch.setattr(torch.backends.mps, "is_available", lambda: False)
assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")
assert dit_accelerator_missing_reason("sdxl") is None
assert dit_accelerator_missing_reason("") is None
infos = {info["name"]: info for info in family_train_infos()}
for name, info in infos.items():
if name in _DIT_TRAIN_FAMILIES:
assert info["precision_modes"] == []
assert "GPU" in info["vram_note"]
assert info["supports_compile"] is False
else:
assert info["precision_modes"] != [] or name not in _DIT_TRAIN_FAMILIES
# MPS alone does not clear it: the trainer would run on the CPU, where the 4-bit load refuses.
monkeypatch.setattr(torch.backends.mps, "is_available", lambda: True)
assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")
monkeypatch.setattr(torch.xpu, "is_available", lambda: True)
assert dit_accelerator_missing_reason("flux.1") is None
def test_dit_accelerator_gate_survives_a_torch_without_every_probe(monkeypatch):
"""torch.mps.is_available() is absent before torch 2.5 but the floor is 2.4; a shared try/except
would turn that AttributeError into no block, letting CPU-only hosts pass."""
import torch
from core.training.diffusion_train_common import dit_accelerator_missing_reason
class _Missing:
"""A torch.mps that predates is_available()."""
class _Raising:
@staticmethod
def is_available():
raise RuntimeError("driver not initialised")
monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
monkeypatch.setattr(torch, "xpu", _Raising)
monkeypatch.setattr(torch.backends, "mps", _Missing)
assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")
monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
assert dit_accelerator_missing_reason("flux.1") is None
@pytest.mark.parametrize("mode", ["fp8", "mxfp8"])
def test_lowp_probe_failure_falls_back_before_touching_the_model(monkeypatch, mode):
# An arch whose float8 / MX GEMM fails (unverified sm89 / sm120 paths) must fall back to bf16 at load, not mid-run.
def broken_probe(convert, transformer):
raise RuntimeError("CUBLAS_STATUS_NOT_SUPPORTED")
monkeypatch.setattr(dit, "_probe_lowp", broken_probe)
m = _block_model()
before = [type(x) for x in m.modules()]
events = []
apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
assert apply(m, events.append, "flux.1") is False
assert [type(x) for x in m.modules()] == before
assert not any(getattr(x, "_studio_lowp", None) for x in m.modules())
assert "CUBLAS_STATUS_NOT_SUPPORTED" in events[0]["message"] and mode in events[0]["message"]
def test_lowp_probe_skips_off_cuda_and_raises_on_a_failing_gemm():
import torch
calls = []
dit._probe_lowp(lambda probe: calls.append(probe), _block_model()) # CPU model: no probe
assert calls == []
if not _real_cuda():
pytest.skip("needs CUDA")
def failing_convert(probe):
probe.ff.forward = lambda x: (_ for _ in ()).throw(RuntimeError("scaled_mm unsupported"))
with pytest.raises(RuntimeError, match = "scaled_mm unsupported"):
dit._probe_lowp(failing_convert, _block_model().cuda())
model = _block_model().cuda()
cpu_state, cuda_state = torch.get_rng_state(), torch.cuda.get_rng_state()
dit._probe_lowp(lambda probe: None, model) # a working GEMM passes
# The seed is set before conversion: the probe must not move the training draws.
assert torch.equal(torch.get_rng_state(), cpu_state)
assert torch.equal(torch.cuda.get_rng_state(), cuda_state)
@pytest.mark.parametrize(
"vendor",
[
"black-forest-labs/FLUX.1-dev",
"black-forest-labs/FLUX.2-dev",
"black-forest-labs/FLUX.2-klein-base-9B",
],
)
def test_training_access_facts_follow_no_token_mirror_with_cached_vendor_shard(
monkeypatch, tmp_path, vendor
):
from core.inference import diffusion_families as families
from utils import hf_cache_settings
monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
snapshot = (
tmp_path / ("models--" + vendor.replace("/", "--")) / "snapshots" / "rev" / "transformer"
)
snapshot.mkdir(parents = True)
(snapshot / "diffusion_pytorch_model-00001-of-00003.safetensors").write_bytes(b"x")
monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(tmp_path))
assert families._upstream_is_cached(vendor)
mirror = families.mirror_repo(vendor)
facts = common._training_mirror_access_specs(vendor)[vendor]
fetched = _cfg(base_model = vendor, hf_token = "").normalized().fetch_base_model
assert fetched == mirror
assert facts["gated"] is False
assert mirror in facts["note"]