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
"""Fake torch.xpu must be a bare namespace; MagicMock invents attributes and hides missing APIs."""
from __future__ import annotations
import random
import types
import pytest
import torch
import core.training.diffusion_train_common as common
from core.training import diffusion_dit_trainer as dit
from core.training import diffusion_h3_trainer as h3
from core.training.diffusion_train_common import (
DiffusionLoraConfig,
effective_mixed_precision,
native_bf16_supported_xpu,
resolve_train_device,
)
def _fake_xpu(**attrs):
return types.SimpleNamespace(**attrs)
@pytest.fixture
def host(monkeypatch):
def _set(*, cuda: bool, xpu = None):
monkeypatch.setattr(torch.cuda, "is_available", lambda: cuda)
if xpu is None:
monkeypatch.delattr(torch, "xpu", raising = False)
else:
monkeypatch.setattr(torch, "xpu", xpu, raising = False)
return _set
def test_cuda_still_wins_on_a_box_that_has_both(host):
host(cuda = True, xpu = _fake_xpu(is_available = lambda: True))
assert resolve_train_device() == "cuda"
def test_an_xpu_box_resolves_to_xpu_not_cpu(host):
"""#9524: the bnb quantizer already placed the transformer on xpu:0, so "cpu" here split them."""
host(cuda = False, xpu = _fake_xpu(is_available = lambda: True))
assert resolve_train_device() == "xpu"
@pytest.mark.parametrize(
"xpu",
[
None,
_fake_xpu(),
_fake_xpu(is_available = True),
_fake_xpu(is_available = lambda: False),
],
ids = ["absent", "no-probe", "non-callable", "unavailable"],
)
def test_a_host_without_a_usable_xpu_stays_on_cpu(host, xpu):
host(cuda = False, xpu = xpu)
assert resolve_train_device() == "cpu"
def test_an_uninitialised_xpu_driver_falls_through_instead_of_killing_the_run(host):
"""A raising probe must degrade to CPU like dit_accelerator_missing_reason, not crash."""
def _boom():
raise RuntimeError("driver not initialised")
host(cuda = False, xpu = _fake_xpu(is_available = _boom))
assert resolve_train_device() == "cpu"
def test_an_emulation_only_xpu_is_refused(host):
"""is_bf16_supported() defaults including_emulation=True and short-circuits, so the bare call
answers True for every available XPU: not a capability check."""
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: bool(including_emulation),
),
)
assert torch.xpu.is_bf16_supported() is True
assert native_bf16_supported_xpu() is False
def test_a_native_bf16_xpu_is_accepted(host):
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: True,
),
)
assert native_bf16_supported_xpu() is True
def test_a_torch_predating_the_emulation_flag_still_answers(host):
"""On a torch predating including_emulation the no-argument answer is the only one there is."""
host(cuda = False, xpu = _fake_xpu(is_available = lambda: True, is_bf16_supported = lambda: True))
assert native_bf16_supported_xpu() is True
@pytest.mark.parametrize(
"probe",
[None, True],
ids = ["absent", "non-callable"],
)
def test_an_xpu_without_a_usable_bf16_probe_is_refused(host, probe):
attrs = {"is_available": lambda: True}
if probe is not None:
attrs["is_bf16_supported"] = probe
host(cuda = False, xpu = _fake_xpu(**attrs))
assert native_bf16_supported_xpu() is False
def _xpu_without_ocloc(**props):
"""has_bfloat16_conversions is False on every device when libocloc is missing (real driver)."""
return _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: bool(including_emulation),
get_device_properties = lambda *a: types.SimpleNamespace(**props),
)
@pytest.mark.parametrize(
"device_id",
[0x56A0, 0x56C0, 0xE20B, 0xE211, 0x0BD5, 0x64A0, 0xB080],
ids = ["A770", "Flex170", "B580", "B60", "Max1550", "LNL", "PTL"],
)
def test_an_arc_or_data_center_xpu_is_native_without_libocloc(host, device_id):
from core.training.diffusion_train_common import bf16_unsupported_reason
host(cuda = False, xpu = _xpu_without_ocloc(device_id = device_id, name = "Intel(R) Graphics"))
assert native_bf16_supported_xpu() is True
assert bf16_unsupported_reason("krea-2") is None
@pytest.mark.parametrize(
"device_id",
[0x4905, 0x7DD5, 0x9A49],
ids = ["DG1", "MTL-non-Arc", "TGL"],
)
def test_a_non_arc_xpu_without_libocloc_is_still_refused(host, device_id):
host(cuda = False, xpu = _xpu_without_ocloc(device_id = device_id, name = "Intel(R) Arc(TM) A770"))
assert native_bf16_supported_xpu() is False
@pytest.mark.parametrize(
("name", "native"),
[
("Intel(R) Arc(TM) B580 Graphics", True),
("Intel(R) Data Center GPU Max 1550", True),
("Intel(R) Iris(R) Xe Graphics", False),
("Intel(R) Graphics [0xe20b]", False),
],
)
def test_a_torch_without_device_id_falls_back_to_the_name(host, name, native):
host(cuda = False, xpu = _xpu_without_ocloc(name = name))
assert native_bf16_supported_xpu() is native
def test_unreadable_device_properties_keep_the_strict_answer(host):
def _raise(*a):
raise RuntimeError("no device")
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: bool(including_emulation),
get_device_properties = _raise,
),
)
assert native_bf16_supported_xpu() is False
def _dit_cfg():
return DiffusionLoraConfig(
base_model = "black-forest-labs/FLUX.1-dev",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
mixed_precision = "bf16",
)
def _h3_cfg():
return DiffusionLoraConfig(
base_model = "MiniMaxAI/MiniMax-H3",
data_dir = "/tmp/clips",
output_dir = "/tmp/out",
mixed_precision = "bf16",
resolution = 768,
)
class _Cut(Exception):
pass
def _decide(monkeypatch, module, entry, cfg):
"""Reads (device, weight_dtype) from the live frame, cut before any download or training runs."""
def _cut(*_a, **_k):
raise _Cut()
monkeypatch.setattr(module, "_assert_trusted_base_model", _cut)
# manual_seed fans out to torch.xpu.manual_seed_all, which the fake lacks
monkeypatch.setattr(torch, "manual_seed", lambda *_a, **_k: None)
try:
entry(cfg)
except _Cut as exc:
frame = None
tb = exc.__traceback__
while tb is not None:
if tb.tb_frame.f_code.co_name in ("run_dit_lora_training", "run_h3_lora_training"):
frame = tb.tb_frame
tb = tb.tb_next
return frame.f_locals["device"], frame.f_locals["weight_dtype"]
raise AssertionError("the run did not reach the cut")
@pytest.mark.parametrize(
("module", "entry", "cfg"),
[(dit, dit.run_dit_lora_training, _dit_cfg()), (h3, h3.run_h3_lora_training, _h3_cfg())],
ids = ["dit", "h3"],
)
def test_both_flow_trainers_run_an_xpu_box_in_bf16_on_the_xpu(
monkeypatch, host, module, entry, cfg
):
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: True,
),
)
assert _decide(monkeypatch, module, entry, cfg) == ("xpu", torch.bfloat16)
@pytest.mark.parametrize(
("module", "entry", "cfg"),
[(dit, dit.run_dit_lora_training, _dit_cfg()), (h3, h3.run_h3_lora_training, _h3_cfg())],
ids = ["dit", "h3"],
)
def test_both_flow_trainers_refuse_an_emulation_only_xpu(monkeypatch, host, module, entry, cfg):
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: bool(including_emulation),
),
)
with pytest.raises(ValueError, match = "bfloat16-capable"):
_decide(monkeypatch, module, entry, cfg)
@pytest.mark.parametrize("module", [dit, h3], ids = ["dit", "h3"])
def test_every_phase_boundary_frees_the_selected_accelerator(module):
"""Both boundaries free the text encoders and VAE right before the multi-GB transformer load,
so a CUDA-only clear leaves that memory resident for it on an XPU box."""
import inspect
src = inspect.getsource(module)
cuda_frees = src.count("torch.cuda.empty_cache()")
xpu_frees = src.count("torch.xpu.empty_cache()")
assert cuda_frees > 0
assert xpu_frees == cuda_frees
def test_an_emulation_only_xpu_is_refused_before_the_route_evicts_anything(host):
"""The route calls this BEFORE teardown; dit_accelerator_missing_reason accepts any available
XPU, so a child-only guard evicted the user's models and then failed."""
from core.training.diffusion_train_common import bf16_unsupported_reason
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: bool(including_emulation),
),
)
reason = bf16_unsupported_reason("krea-2")
assert reason and "bf16 natively" in reason
host(
cuda = False,
xpu = _fake_xpu(
is_available = lambda: True,
is_bf16_supported = lambda including_emulation = True: True,
),
)
assert bf16_unsupported_reason("krea-2") is None
def test_an_unprobeable_xpu_is_left_to_the_child_not_refused_up_front(host):
"""An undeterminable XPU capability must fail open: collapsing it to unsupported refused nf4 on
every such host."""
from core.training.diffusion_train_common import (
bf16_unsupported_reason,
native_bf16_supported_xpu,
xpu_native_bf16_probe,
)
def _unprobeable(including_emulation = True):
raise RuntimeError("no device properties")
host(cuda = False, xpu = _fake_xpu(is_available = lambda: True, is_bf16_supported = _unprobeable))
assert xpu_native_bf16_probe() is None
assert bf16_unsupported_reason("krea-2") is None
assert native_bf16_supported_xpu() is False
def test_an_xpu_run_captures_and_restores_its_own_noise_generator(host, monkeypatch):
"""The loops draw randn_like on the training device, so an XPU run's per-step noise lives in the
XPU generator; capturing only torch_cpu resumed it from a fresh seed."""
from core.training.diffusion_checkpoint import capture_rng_state, restore_rng_state
seen = {"set": []}
states = [torch.tensor([7, 7, 7], dtype = torch.uint8)]
fake = _fake_xpu(
is_available = lambda: True,
device_count = lambda: 1,
get_rng_state_all = lambda: states,
set_rng_state = lambda st, i: seen["set"].append((i, st.tolist())),
)
host(cuda = False, xpu = fake)
captured = capture_rng_state()
assert "torch_xpu_0" in captured["tensors"]
restore_rng_state(captured["json"], captured["tensors"])
assert seen["set"] == [(0, [7, 7, 7])]
def test_a_checkpoint_cannot_silently_resume_across_accelerator_backends(host, tmp_path):
"""Refuse a CUDA checkpoint on XPU at preflight: resume would silently reseed the generator."""
from pathlib import Path
from core.training.diffusion_checkpoint import (
ResumeError,
_assert_required_state,
capture_rng_state,
)
complete = {
"kind": "image",
"sampler": {"pos": 0},
"files": {k: f"{k}.pt" for k in ("adapter", "optimizer", "scheduler", "rng")},
}
written_here = capture_rng_state({"loop": random.Random(1), "variant": random.Random(2)})[
"json"
]
assert written_here["accelerator"] in ("cuda", "xpu", "cpu")
_assert_required_state(Path("ckpt"), {**complete, "rng": written_here})
other = "xpu" if written_here["accelerator"] != "xpu" else "cuda"
with pytest.raises(ResumeError, match = "this accelerator"):
_assert_required_state(
Path("ckpt"), {**complete, "rng": {**written_here, "accelerator": other}}
)
# a bundle predating the field must still resume: unknown is not a mismatch
legacy = {k: v for k, v in written_here.items() if k != "accelerator"}
_assert_required_state(Path("ckpt"), {**complete, "rng": legacy})
def test_an_xpu_flow_run_records_the_bf16_it_actually_trains_in(host):
"""identity_for_config stores this and a resume is refused when it disagrees, so a CUDA-only
rule would record "no" for a run the loop trained in bf16."""
cfg = _dit_cfg().normalized()
host(cuda = False, xpu = _fake_xpu(is_available = lambda: True))
assert effective_mixed_precision(cfg) == "bf16"
host(cuda = False, xpu = None)
assert effective_mixed_precision(cfg) == "no"
assert common.resolve_train_device() == "cpu"