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.

19.7 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 H3 preflight must refuse every host before the four-file download, CPU fallback included."""

from __future__ import annotations

import threading
import types
from pathlib import Path

import pytest

from core.inference.video import VideoBackend, _detect_load_family
from core.inference.video_families import VIDEO_CANCELLED_MSG


def _shared_setup_1(backend, device, h3_host, platform):
    from core.inference import sd_cpp_backend

    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)

    swapped = {"done": False}
    real_probe = sd_cpp_backend._sd_cpp_probe_output
    return host, real_probe, sd_cpp_backend, swapped


H3_REPO = "leejet/MiniMax-H3-GGUF"
H3_FILE = "minimax_h3_fl2va-Q4_K_M.gguf"

_BANNER = "stable-diffusion.cpp version unknown, commit unknown\n"
_H3_HELP = _BANNER + "  --ref-video   MiniMax-H3 Ref2VA reference video frame directory\n"
_PRE_H3_HELP = _BANNER + "  -M, --mode    run mode, one of [img_gen, vid_gen, upscale]\n"
# Debian/Ubuntu's find-and-replace `sd`, and Homebrew ships the same tool on macOS.
_UNRELATED_HELP = "sd 1.0.0\nFind & replace CLI\n\nUSAGE:\n    sd <find> <replace-with>\n"

# (label, DiffusionDeviceTarget.backend, .device)
HARDWARE = [
    ("nvidia", "cuda", "cuda"),
    ("amd", "rocm", "cuda"),
    ("apple", "mps", "mps"),
    ("cpu", "cpu", "cpu"),
]
# WSL is the linux platform string; listed separately because PATH can reach a Windows install.
PLATFORMS = ["linux", "wsl", "darwin", "win32"]


class _PlanInfo:
    def __init__(self, siblings) -> None:
        self.siblings = siblings


class _Engine:
    def __init__(self, binary) -> None:
        self.binary = binary

    def version(self):
        return "stub-version"


@pytest.fixture
def h3_host(monkeypatch, tmp_path):
    """Drive `_run_load_h3_native` on a chosen host with a chosen binary, recording downloads."""
    from core.inference import video as video_mod
    from core.inference import sd_cpp_backend, sd_cpp_engine

    def _setup(
        *,
        platform: str,
        backend: str,
        device: str,
        help_text: str | None,
        managed: bool = False,
        lists_accelerator: bool = True,
        paravirtual: bool = False,
    ):
        monkeypatch.setattr(
            sd_cpp_engine.sys, "platform", "linux" if platform == "wsl" else platform
        )
        monkeypatch.setattr(
            video_mod,
            "resolve_diffusion_device_target",
            lambda: types.SimpleNamespace(backend = backend, device = device, dtype = None),
        )
        from core.inference import sd_cpp_args

        monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: paravirtual)
        monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
        monkeypatch.setattr(sd_cpp_backend, "is_managed_binary", lambda _b: managed)
        monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)

        binary = None if help_text is None else "/opt/sd/sd-cli"
        monkeypatch.setattr(sd_cpp_backend, "ensure_sd_cpp_binary", lambda **_kwargs: binary)

        device_probes: list[str] = []

        def _probe(_binary, *args):
            if args == ("--list-devices",):
                device_probes.append(_binary)
                if lists_accelerator:
                    return "CUDA0\tNVIDIA H100 PCIe\nCPU\tIntel(R) Xeon(R)\n"
                return "CPU\tIntel(R) Xeon(R)\n"
            return help_text

        monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)

        asset_calls: list[str] = []

        class _Api:
            def __init__(self, **_kwargs):
                pass

            def model_info(self, repo, *_args, **_kwargs):
                asset_calls.append(repo)
                return _PlanInfo([])

        monkeypatch.setattr("huggingface_hub.HfApi", _Api)

        downloads: list[str] = []

        def _download(_repo, wanted, *_args, **_kwargs):
            downloads.append(wanted)
            path = tmp_path / Path(wanted).name
            path.write_bytes(b"x")
            return str(path)

        monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)

        def run(cancel_event: threading.Event | None = None):
            fam = _detect_load_family(H3_REPO, None, "minimax-h3")
            assert fam is not None
            backend_obj = VideoBackend()
            backend_obj._run_load_h3_native(
                fam = fam,
                token = None,
                cancel_event = cancel_event or threading.Event(),
                repo_id = H3_REPO,
                gguf_filename = H3_FILE,
            )
            return backend_obj

        return types.SimpleNamespace(
            run = run,
            downloads = downloads,
            asset_calls = asset_calls,
            device_probes = device_probes,
        )

    return _setup


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
@pytest.mark.parametrize(
    "state,help_text,expected",
    [
        ("unrelated_binary", _UNRELATED_HELP, "is not stable-diffusion.cpp"),
        ("pre_h3_binary", _PRE_H3_HELP, "does not advertise MiniMax-H3"),
        ("no_binary", None, "could not be installed or started"),
    ],
)
def test_h3_preflight_refuses_before_downloading(
    h3_host, platform, hw_label, backend, device, state, help_text, expected
):
    """Every refusal costs zero downloads, since the bundle is tens of GB and must not be fetched first."""
    host = h3_host(platform = platform, backend = backend, device = device, help_text = help_text)
    with pytest.raises(RuntimeError, match = expected):
        host.run()
    assert host.downloads == []


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_preflight_admits_a_capable_build_and_downloads_once(
    h3_host, platform, hw_label, backend, device
):
    """The other direction: a genuine H3 build is not refused anywhere, and the load proceeds to
    fetch exactly the four files. Guards against an identity check that is too strict."""
    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
    backend_obj = host.run()
    assert len(host.downloads) == 4
    assert backend_obj._state is not None
    assert backend_obj._state.device == device


def test_h3_on_a_paravirtual_mac_commits_cpu_and_drops_the_video_claim(h3_host, monkeypatch):
    # sd.cpp runs a paravirtual Metal GPU on the CPU backend, so the load must not keep the VIDEO claim.
    from core.inference import gpu_arbiter

    released = []
    monkeypatch.setattr(
        gpu_arbiter, "release_if", lambda owner, pred: released.append(owner) or pred()
    )
    host = h3_host(
        platform = "darwin", backend = "mps", device = "mps", help_text = _H3_HELP, paravirtual = True
    )
    backend_obj = host.run()
    assert backend_obj._state is not None and backend_obj._state.device == "cpu"
    assert released == [gpu_arbiter.VIDEO]


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
    "hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_gpu_host_falls_back_to_the_cpu_build(h3_host, platform, hw_label, backend, device):
    """Upstream publishes no Linux CUDA archive, so a GPU host routinely ends up on the CPU
    prebuilt. It must still load, committed on the CPU rather than on a GPU it never ran on."""
    host = h3_host(
        platform = platform,
        backend = backend,
        device = device,
        help_text = _H3_HELP,
        lists_accelerator = False,
    )
    backend_obj = host.run()
    assert len(host.downloads) == 4
    assert backend_obj._state is not None
    assert backend_obj._state.device == "cpu"


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_cancellation_during_the_preflight_stops_before_the_asset_calls(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """The ensure takes no cancel_event and can spend minutes installing the prebuilt, so a cancel
    arriving during it is already late. It must not then cost four more model_info round trips."""
    from core.inference import sd_cpp_backend

    cancelled = threading.Event()
    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
    original = sd_cpp_backend.ensure_h3_sd_cpp_binary

    def _cancel_midway(**kwargs):
        cancelled.set()
        return original(**kwargs)

    monkeypatch.setattr(sd_cpp_backend, "ensure_h3_sd_cpp_binary", _cancel_midway)

    with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
        host.run(cancel_event = cancelled)
    assert host.downloads == []
    # A cancelled load must stop before the four sequential size-estimate round trips.
    assert host.asset_calls == []


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_revets_a_user_supplied_binary_swapped_during_the_download(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """User-supplied binaries are re-vetted after the download, so a mid-fetch swap is caught."""
    from core.inference import sd_cpp_backend

    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)

    swapped = {"done": False}
    real_probe = sd_cpp_backend._sd_cpp_probe_output

    def _probe(binary, *args):
        if args == ("--help",) and swapped["done"]:
            return _PRE_H3_HELP
        return real_probe(binary, *args)

    def _download(*args, **kwargs):
        swapped["done"] = True
        return _real_download(*args, **kwargs)

    _real_download = None
    import utils.hf_xet_fallback as xet

    _real_download = xet.hf_hub_download_with_xet_fallback
    monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    with pytest.raises(RuntimeError, match = "changed while this model was loading"):
        host.run()
    assert len(host.downloads) == 4


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_revet_checks_identity_not_just_the_h3_marker(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """The re-vet checks binary identity too, since --ref-video is a plain option other tools expose."""
    host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)

    def _probe(binary, *args):
        if args == ("--help",) and swapped["done"]:
            return "reference-video-cli 2.1\n  --ref-video PATH   reference clip\n"
        return real_probe(binary, *args)

    import utils.hf_xet_fallback as xet

    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(*args, **kwargs):
        swapped["done"] = True
        return real_download(*args, **kwargs)

    monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    with pytest.raises(RuntimeError, match = "changed while this model was loading"):
        host.run()
    assert len(host.downloads) == 4


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
    "hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_revet_catches_a_user_binary_whose_accelerator_changed(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """The device list is re-probed at commit, since a GPU device committed around a CPU binary is wrong."""
    host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)

    def _probe(binary, *args):
        # Identity and capability pass; only the device list changed, which the H3 re-vet cannot see.
        if args == ("--list-devices",) and swapped["done"]:
            return "CPU\tIntel(R) Xeon(R)\n"
        return real_probe(binary, *args)

    import utils.hf_xet_fallback as xet

    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(*args, **kwargs):
        swapped["done"] = True
        return real_download(*args, **kwargs)

    monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    with pytest.raises(RuntimeError, match = "built for a different accelerator"):
        host.run()


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
    "hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_revet_tolerates_an_unreadable_accelerator_reprobe(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """ "Could not tell" is not "it changed". sd_cpp_lists_accelerator_device folds an unreadable
    probe into True, so comparing THAT against a recorded False would refuse the CPU fallback that
    recorded it -- the load must proceed on the reading it already has."""
    host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)

    def _probe(binary, *args):
        if args == ("--list-devices",) and swapped["done"]:
            return None
        return real_probe(binary, *args)

    import utils.hf_xet_fallback as xet

    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(*args, **kwargs):
        swapped["done"] = True
        return real_download(*args, **kwargs)

    monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    backend_obj = host.run()
    assert backend_obj._state is not None
    assert backend_obj._state.device == device


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_probes_devices_only_where_the_answer_is_used(
    h3_host, platform, hw_label, backend, device
):
    """--list-devices is probed only on GPU targets, since CPU and MPS never use the answer."""
    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
    host.run()
    expected = 2 if backend not in ("cpu", "mps") else 0
    assert len(host.device_probes) == expected


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_cancellation_precedes_the_binary_install(h3_host, platform, hw_label, backend, device):
    """A preflight download has no cancel_event, so a load cancelled early must not reach it."""
    from core.inference import sd_cpp_backend

    host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
    ensures: list[str] = []
    original = sd_cpp_backend.ensure_h3_sd_cpp_binary

    def _spy(**kwargs):
        ensures.append("called")
        return original(**kwargs)

    sd_cpp_backend.ensure_h3_sd_cpp_binary = _spy
    try:
        cancelled = threading.Event()
        cancelled.set()
        with pytest.raises(RuntimeError):
            host.run(cancel_event = cancelled)
    finally:
        sd_cpp_backend.ensure_h3_sd_cpp_binary = original
    assert ensures == []
    assert host.downloads == []


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", [h for h in HARDWARE if h[1] == "rocm"])
def test_h3_revet_catches_a_managed_tree_rebuilt_for_another_accelerator(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """A ROCm build installed over the tree mid-download answers the boolean re-vet exactly as the Vulkan rung did."""
    host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)

    def _accelerator_of(binary):
        return "rocm" if swapped["done"] else "vulkan"

    import utils.hf_xet_fallback as xet

    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(*args, **kwargs):
        swapped["done"] = True
        return real_download(*args, **kwargs)

    monkeypatch.setattr(sd_cpp_backend, "_installed_accelerator_of", _accelerator_of)
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    with pytest.raises(RuntimeError, match = "built for a different accelerator"):
        host.run()


@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", [h for h in HARDWARE if h[1] == "rocm"])
def test_h3_revet_does_not_invent_a_change_for_an_unrecorded_tree(
    h3_host, platform, hw_label, backend, device, monkeypatch
):
    """None is "cannot tell", not "it changed"; refusing on it would refuse every SD_CLI_PATH build."""
    host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)

    import utils.hf_xet_fallback as xet

    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(*args, **kwargs):
        swapped["done"] = True
        return real_download(*args, **kwargs)

    monkeypatch.setattr(
        sd_cpp_backend,
        "_installed_accelerator_of",
        lambda binary: None if swapped["done"] else "vulkan",
    )
    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    host.run()


def _h3_load_with_vae_fetch(monkeypatch, h3_host, error, *, local_files_only):
    """Run a native H3 load whose video VAE fetch raises ``error``; the other files resolve."""
    from core.inference.video_minimax_h3 import H3_VIDEO_VAE
    import utils.hf_xet_fallback as xet

    h3_host(platform = "linux", backend = "cpu", device = "cpu", help_text = _H3_HELP)
    real_download = xet.hf_hub_download_with_xet_fallback

    def _download(repo, wanted, *args, **kwargs):
        if wanted == H3_VIDEO_VAE:
            raise error
        return real_download(repo, wanted, *args, **kwargs)

    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
    fam = _detect_load_family(H3_REPO, None, "minimax-h3")
    VideoBackend()._run_load_h3_native(
        fam = fam,
        token = None,
        cancel_event = threading.Event(),
        repo_id = H3_REPO,
        gguf_filename = H3_FILE,
        local_files_only = local_files_only,
    )


def test_h3_cache_only_load_names_the_missing_vae_and_the_fix(h3_host, monkeypatch):
    """VAEs cached before the vae/official/ move miss on a cache-only load; say which file and how to fetch it."""
    from huggingface_hub.errors import LocalEntryNotFoundError

    from core.inference.video_minimax_h3 import H3_VIDEO_VAE
    from hub.utils.hf_errors import modelscope_missing
    from utils.native_path_leases import redact_native_paths

    with pytest.raises(RuntimeError) as caught:
        _h3_load_with_vae_fetch(
            monkeypatch, h3_host, LocalEntryNotFoundError("cannot find"), local_files_only = True
        )
    text = str(caught.value)
    assert f"video VAE ({H3_VIDEO_VAE})" in text
    assert "Load MiniMax-H3 once while online (or reconnect)" in text
    assert isinstance(caught.value.__cause__, LocalEntryNotFoundError)
    # The load worker stores exactly this as the progress error the UI and API read.
    assert (modelscope_missing(caught.value) or redact_native_paths(text)) == text


def test_h3_online_load_miss_is_unchanged(h3_host, monkeypatch):
    from huggingface_hub.errors import LocalEntryNotFoundError

    error = LocalEntryNotFoundError("hub unreachable")
    with pytest.raises(LocalEntryNotFoundError) as caught:
        _h3_load_with_vae_fetch(monkeypatch, h3_host, error, local_files_only = False)
    assert caught.value is error


def test_h3_cache_only_load_keeps_an_unrelated_error(h3_host, monkeypatch):
    error = OSError("disk full")
    with pytest.raises(OSError) as caught:
        _h3_load_with_vae_fetch(monkeypatch, h3_host, error, local_files_only = True)
    assert caught.value is error