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
"""Tests for the native sd.cpp diffusion backend (the no-GPU engine)."""
from __future__ import annotations
import os
import shutil
import threading
import time
import types
from pathlib import Path
import pytest
from PIL import Image
from core.inference import sd_cpp_backend as bk
from core.inference.diffusion_families import (
_FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS,
detect_family,
)
from core.inference.sd_cpp_args import SdCppGenParams, SdCppModelFiles
from core.inference.sd_cpp_backend import (
SdCppDiffusionBackend,
_map_guidance,
ensure_sd_cpp_binary,
)
from core.inference.sd_cpp_engine import SdCppCancelled
def _shared_setup_1(b, fake, monkeypatch):
monkeypatch.setattr(b, "_resolve_engine", lambda: fake)
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
monkeypatch.setattr(
b,
"_fetch_assets",
lambda *a, **k: {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"},
)
monkeypatch.setattr(
bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
)
def _shared_setup_2(b, fam):
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 1,
)
def _shared_setup_3(monkeypatch, own):
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: _PRE_H3_HELP)
with pytest.raises(RuntimeError, match = "does not advertise MiniMax-H3") as excinfo:
bk.ensure_h3_sd_cpp_binary()
return excinfo
def _shared_setup_4(monkeypatch):
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: {})
)
return b
class _FakeEngine:
"""Stands in for SdCppEngine: writes a 1x1 PNG and records the args."""
def __init__(
self,
*,
fail = None,
cancel_on_call = False,
):
self.calls = []
self.fail = fail
self.cancel_on_call = cancel_on_call
def is_available(self):
return True
def version(self, **_):
return "fake sd-cli"
def generate(
self,
files,
params,
*,
output_path,
cancel_event = None,
**kw,
):
self.calls.append((files, params, output_path, kw))
if self.cancel_on_call and cancel_event is not None:
cancel_event.set()
if self.fail is not None:
raise self.fail
if cancel_event is not None and cancel_event.is_set():
raise SdCppCancelled("cancelled")
Image.new("RGB", (1, 1), (10, 20, 30)).save(output_path)
from pathlib import Path
return Path(output_path)
def _loaded_backend(fam_name = "z-image", engine = None):
b = SdCppDiffusionBackend(engine = engine or _FakeEngine())
fam = detect_family(fam_name)
b._state = bk._SdState(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
base_repo = fam.base_repo,
family = fam,
device = "cpu",
files = SdCppModelFiles(
diffusion_model = "/m/z.gguf", vae = "/m/vae.safetensors", llm = "/m/llm.safetensors"
),
vae_format = fam.sd_cpp_vae_format,
sampling_method = fam.sd_cpp_sampling_method,
flow_shift = fam.sd_cpp_flow_shift,
mode = "oneshot",
)
return b
def test_loaded_repo_ids_includes_native_companions():
# The one-shot engine re-reads companion files, so the delete guard must list VAE + encoder repos.
b = _loaded_backend("flux.1")
ids = set(b.loaded_repo_ids())
fam = detect_family("flux.1")
assert "unsloth/Z-Image-Turbo-GGUF" in ids
assert fam.base_repo in ids
assert fam.sd_cpp_vae[0] in ids
for terepo, _f, _k in fam.sd_cpp_text_encoders:
assert terepo in ids # black-forest-labs/FLUX.1-schnell (CLIP-L + sharded T5-XXL)
b._state = None
assert b.loaded_repo_ids() == ()
def test_native_status_preserves_the_logical_picker_identity():
import dataclasses
b = _loaded_backend()
b._state = dataclasses.replace(
b._state,
repo_id = "/cache/models--unsloth--Z-Image-Turbo-GGUF/snapshots/abc",
display_repo_id = "unsloth/Z-Image-Turbo-GGUF",
)
status = b.status()
assert status["repo_id"].endswith("/snapshots/abc")
assert status["display_repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
result = b.generate(prompt = "logical identity", steps = 1, seed = 1)
assert result["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
def test_loaded_repo_ids_tracks_variant_encoder_by_gguf_filename():
# A local GGUF carries the variant keyword only in the basename.
b = SdCppDiffusionBackend(engine = _FakeEngine())
fam = detect_family("flux.2-klein")
b._state = bk._SdState(
repo_id = "local/my-klein-checkpoints",
base_repo = fam.base_repo,
family = fam,
device = "cpu",
files = SdCppModelFiles(diffusion_model = "/m/FLUX.2-klein-9B-Q4_K_M.gguf"),
vae_format = fam.sd_cpp_vae_format,
sampling_method = fam.sd_cpp_sampling_method,
flow_shift = fam.sd_cpp_flow_shift,
mode = "oneshot",
gguf_filename = "FLUX.2-klein-9B-Q4_K_M.gguf",
)
ids = set(b.loaded_repo_ids())
nine_b = _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS[0][0]
four_b = fam.sd_cpp_text_encoders[0][0]
assert nine_b != four_b
assert nine_b in ids # the 8B encoder this load pulled (unsloth/Qwen3-8B-GGUF)
# The 4B default must not be protected instead.
assert four_b not in ids
class _FakeServer:
"""Stands in for SdCppServer: records the spawn + one img_gen per whole batch."""
def __init__(self, binary):
self.binary = binary
self.started = None
self.stopped = False
self.payloads = []
self.timeouts = []
self.alive = True
self.lora_dir = None
self.img_gen_error = None
def is_alive(self):
return self.alive and not self.stopped
def start(
self,
files,
*,
vae_format = None,
offload = None,
native_speed = None,
threads = None,
extra_args = None,
env = None,
):
self.env = env
self.started = dict(
files = files,
vae_format = vae_format,
offload = offload,
native_speed = native_speed,
threads = threads,
extra_args = list(extra_args or []),
)
def img_gen(
self,
payload,
*,
on_step = None,
cancel_event = None,
total_timeout = None,
):
import io as _io
self.payloads.append(payload)
self.timeouts.append(total_timeout)
if self.img_gen_error is not None:
err, self.img_gen_error = self.img_gen_error, None
self.alive = False
raise err
if on_step is not None:
steps = payload.get("sample_params", {}).get("sample_steps", 0)
on_step(f" {steps}/{steps}")
n = int(payload.get("batch_count", 1))
blobs = []
for i in range(n):
buf = _io.BytesIO()
Image.new("RGB", (1, 1), (i, i, i)).save(buf, format = "PNG")
blobs.append(buf.getvalue())
return blobs
def stop(self):
self.stopped = True
@pytest.mark.parametrize(
"fam_name,expect_kinds",
[
# The T5-XXL is sharded: the index is the t5xxl input, its shards ride along as t5xxl_shard.
("flux.1", {"diffusion_model", "vae", "clip_l", "t5xxl", "t5xxl_shard"}),
("z-image", {"diffusion_model", "vae", "llm"}),
("qwen-image", {"diffusion_model", "vae", "qwen2vl"}),
("flux.2-klein", {"diffusion_model", "vae", "llm"}),
],
)
def test_asset_specs_cover_required_files(fam_name, expect_kinds):
b = SdCppDiffusionBackend(engine = _FakeEngine())
fam = detect_family(fam_name)
specs = b._asset_specs("unsloth/x-GGUF", "x-Q4_K_M.gguf", fam)
kinds = {kind for _, _, kind in specs}
assert kinds == expect_kinds
assert all(repo and fn for repo, fn, _ in specs)
tr = [s for s in specs if s[2] == "diffusion_model"][0]
assert tr[0] == "unsloth/x-GGUF" and tr[1] == "x-Q4_K_M.gguf"
@pytest.fixture(autouse = True)
def _plan_sees_an_empty_cache(monkeypatch):
"""Plan tests describe their cache state, so a developer's real one cannot drop an entry."""
from core.inference.diffusion import DiffusionBackend
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: False),
)
_Z_IMAGE_KIND_BYTES = {"diffusion_model": 4_000, "vae": 300, "llm": 8_000}
def _z_image_native_assets(monkeypatch, b):
"""kind -> (fetch repo, file) and (fetch repo, file) -> size for a z-image GGUF pick, read off the family table
and the same fetch map the plan uses, so the test follows the table instead of naming its repos."""
monkeypatch.setattr(
"core.inference.diffusion_families._upstream_is_cached",
lambda repo_id, files = None, **kwargs: False,
)
monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
specs = b._asset_specs(
"unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", detect_family("z-image")
)
fetch = bk._fetch_repo_map(specs, None)
by_kind = {k: (fetch[r], f) for r, f, k in specs}
assert set(by_kind) == set(_Z_IMAGE_KIND_BYTES)
return by_kind, {by_kind[k]: n for k, n in _Z_IMAGE_KIND_BYTES.items()}
def test_download_plan_skips_assets_already_in_the_cache(monkeypatch):
# _fetch_assets resolves either cache root, so staging a readable file re-downloads it for nothing.
from core.inference.diffusion import DiffusionBackend
b = SdCppDiffusionBackend(engine = _FakeEngine())
by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
)
cached = {"z-image-turbo-Q4_K_M.gguf"}
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(
lambda repo_id, filename, revision = None, expected_size = None, **kwargs: (
filename in cached
)
),
)
plan = b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
cached.add(by_kind["vae"][1])
warming = b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
vae_repo, llm_repo = by_kind["vae"][0], by_kind["llm"][0]
assert vae_repo != llm_repo # the VAE and the encoder now come from separate repos
assert [e["repo_id"] for e in plan["entries"]] == [vae_repo, llm_repo]
# Once the VAE is cached its repo has nothing left to stage; the encoder entry is unchanged.
assert [e["repo_id"] for e in warming["entries"]] == [llm_repo]
assert plan["entries"][1]["files"] == warming["entries"][0]["files"]
assert plan["total_bytes"] == 8_300
assert warming["total_bytes"] == 8_000
assert plan["required_bytes"] == 12_300
assert plan["checkpoint_bytes"] == 4_000
def test_download_plan_does_not_label_same_repo_companions_as_checkpoint(monkeypatch):
import core.inference.sd_cpp_backend as module
from core.inference.diffusion import DiffusionBackend
repo = "unsloth/Z-Image-Turbo-GGUF"
checkpoint = "model-Q4_K_M.gguf"
companion = "vae/ae.safetensors"
backend = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(
backend,
"_asset_specs",
lambda *args, **kwargs: [
(repo, checkpoint, "diffusion_model"),
(repo, companion, "vae"),
],
)
monkeypatch.setattr(module, "_fetch_repo_map", lambda specs, token: {repo: repo})
monkeypatch.setattr(backend, "_preflight_companion_repos", lambda *args, **kwargs: None)
monkeypatch.setattr(
backend,
"_plan_file_sizes",
lambda by_repo, token: {(repo, checkpoint): 4_000, (repo, companion): 300},
)
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_loadable",
staticmethod(lambda _repo, filename, *_args, **_kwargs: filename == checkpoint),
)
plan = backend.download_plan(repo, gguf_filename = checkpoint, model_kind = "gguf")
assert plan["entries"][0]["bytes"] == 300
assert plan["entries"][0]["checkpoint"] is False
def test_download_plan_restages_a_native_asset_a_stale_live_copy_shadows(monkeypatch):
# reuse_other_cache_root switches only when the live lookup misses, so a stale live copy shadows.
from core.inference.diffusion import DiffusionBackend
shadowed = "split_files/vae/ae.safetensors"
def probe(
repo_id,
filename,
revision = None,
expected_size = None,
roots = None,
**kwargs,
):
asks_live = roots is not None and roots != (None,)
if filename == shadowed:
return expected_size is None if asks_live else True
return True
monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(probe))
assert not DiffusionBackend._hub_file_is_loadable("r", shadowed, None, 300)
assert DiffusionBackend._hub_file_is_loadable("r", "other.safetensors", None, 300)
def test_download_plan_restages_a_native_asset_that_changed_size(monkeypatch):
# Pass the declared size: a same-named republish is invisible from the ref alone.
from core.inference.diffusion import DiffusionBackend
b = SdCppDiffusionBackend(engine = _FakeEngine())
seen = {}
by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
)
def probe(
repo_id,
filename,
revision = None,
expected_size = None,
**kwargs,
):
seen[filename] = expected_size
return True
monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(probe))
b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
assert seen["z-image-turbo-Q4_K_M.gguf"] == 4_000
assert seen[by_kind["vae"][1]] == 300
assert seen[by_kind["llm"][1]] == 8_000
assert all(size for size in seen.values()), "an unsized probe trusts the local ref alone"
def test_download_plan_is_empty_when_every_native_asset_is_cached(monkeypatch):
from core.inference.diffusion import DiffusionBackend
b = _shared_setup_4(monkeypatch)
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: True),
)
plan = b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
assert plan["entries"] == [] and plan["total_bytes"] == 0
def test_download_plan_stages_exactly_what_sd_cli_opens(monkeypatch):
b = SdCppDiffusionBackend(engine = _FakeEngine())
by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
SdCppDiffusionBackend,
"_plan_file_sizes",
staticmethod(lambda by_repo, token: sizes),
)
plan = b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
transformer_quant = "int8",
memory_mode = "low_vram",
)
expected = set(by_kind.values()) # every asset spec, under the repo the fetch pulls it from
listed = {(e["repo_id"], f) for e in plan["entries"] for f in e["files"]}
assert listed == expected
assert plan["total_bytes"] == 12_300
assert plan["required_bytes"] == 12_300
assert plan["checkpoint_bytes"] == 4_000
# The transformer entry is the only one carrying the GGUF filename; the VAE and the encoder get one entry each.
tr = [e for e in plan["entries"] if e["gguf_filename"]]
assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
for kind in ("vae", "llm"):
assert len([e for e in plan["entries"] if e["repo_id"] == by_kind[kind][0]]) == 1, kind
def test_download_plan_merges_asset_repos_that_share_one_fetch_repo(monkeypatch):
# Two upstream repos can resolve to one fetch repo; keying by it drops whichever landed first.
import core.inference.sd_cpp_backend as S
b = SdCppDiffusionBackend(engine = _FakeEngine())
specs = [
("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf", "transformer"),
("unsloth/example-vae-mirror", "vae/ae.safetensors", "vae"),
("unsloth/example-encoder-mirror", "text_encoders/mistral.safetensors", "text_encoder"),
]
monkeypatch.setattr(SdCppDiffusionBackend, "_asset_specs", lambda *a, **k: specs)
monkeypatch.setattr(
S,
"_fetch_repo_map",
lambda assets, token: {
"unsloth/FLUX.2-dev-GGUF": "unsloth/FLUX.2-dev-GGUF",
"unsloth/example-vae-mirror": "some-org/example-repack",
"unsloth/example-encoder-mirror": "some-org/example-repack",
},
)
monkeypatch.setattr(SdCppDiffusionBackend, "_preflight_companion_repos", lambda *a, **k: None)
sizes = {
("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf"): 4_000,
("some-org/example-repack", "vae/ae.safetensors"): 300,
("some-org/example-repack", "text_encoders/mistral.safetensors"): 8_000,
}
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
)
from core.inference.diffusion import DiffusionBackend
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_loadable",
staticmethod(lambda *a, **k: False),
)
plan = b.download_plan(
"unsloth/FLUX.2-dev-GGUF", gguf_filename = "flux2-dev-Q4_K_M.gguf", model_kind = "gguf"
)
shared = next(e for e in plan["entries"] if e["repo_id"] == "some-org/example-repack")
assert sorted(shared["files"]) == [
"text_encoders/mistral.safetensors",
"vae/ae.safetensors",
], "neither collapsed repo's files may be dropped"
assert plan["required_bytes"] == 12_300
def test_download_plan_skips_a_local_transformer_but_still_stages_the_assets(monkeypatch, tmp_path):
b = SdCppDiffusionBackend(engine = _FakeEngine())
(tmp_path / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"gguf")
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: {})
)
plan = b.download_plan(
str(tmp_path), gguf_filename = "z-image-turbo-Q4_K_M.gguf", model_kind = "gguf"
)
by_kind, _sizes = _z_image_native_assets(monkeypatch, b)
assert str(tmp_path) not in {e["repo_id"] for e in plan["entries"]}
assert {e["repo_id"] for e in plan["entries"]} == {by_kind["vae"][0], by_kind["llm"][0]}
# An unreadable size understates the total; it must never fail the plan.
assert plan["total_bytes"] == 0
def _no_cache(monkeypatch):
"""Report every upstream as uncached, so a local cache cannot mask the mirror decision."""
monkeypatch.setattr(
"core.inference.diffusion_families._upstream_is_cached",
lambda repo_id, files = None, **kwargs: False,
)
monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
def test_download_plan_stages_the_mirrored_asset_repo(monkeypatch):
"""STAGED before the load runs, so a gated asset repo left here 401s an anonymous user and
_fetch_assets' swap is never reached. FLUX.1's VAE lives in the gated FLUX.1-schnell."""
_no_cache(monkeypatch)
b = _shared_setup_4(monkeypatch)
plan = b.download_plan(
"unsloth/FLUX.1-dev-GGUF", gguf_filename = "flux1-dev-Q4_K_M.gguf", model_kind = "gguf"
)
staged = {e["repo_id"] for e in plan["entries"]}
assert "unsloth/FLUX.1-schnell" in staged
assert "black-forest-labs/FLUX.1-schnell" not in staged
tr = [e for e in plan["entries"] if e["gguf_filename"]]
assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/FLUX.1-dev-GGUF"
def test_download_plan_and_fetch_assets_pick_the_same_repo(monkeypatch, tmp_path):
"""Staging one repo and then downloading from the other is the failure this feature removes,
so both sides take the decision from the same per-repo file list."""
import json
_no_cache(monkeypatch)
b = _shared_setup_4(monkeypatch)
pulled: list = []
def fake_download(repo, fn, tok, **k):
# Real files in one snapshot dir per repo: the load checks the T5-XXL index's shards sit beside it.
pulled.append((repo, fn))
path = tmp_path / repo.replace("/", "--") / fn
path.parent.mkdir(parents = True, exist_ok = True)
if fn.endswith(".safetensors.index.json"):
shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
else:
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)
fam = detect_family("flux.1")
specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
b._fetch_assets(specs, None)
plan = b.download_plan(
"unsloth/FLUX.1-dev-GGUF", gguf_filename = "flux1-dev-Q4_K_M.gguf", model_kind = "gguf"
)
assert {(e["repo_id"], f) for e in plan["entries"] for f in e["files"]} == set(pulled)
def test_delete_guard_covers_the_mirrored_asset_repos(monkeypatch):
"""The bytes land under whichever of the pair was fetched, so guarding only the upstream leaves
the mirror cache deletable under a one-shot sd-cli that re-reads it."""
b = _loaded_backend("flux.1")
ids = set(b.loaded_repo_ids())
assert "black-forest-labs/FLUX.1-schnell" in ids
assert "unsloth/FLUX.1-schnell" in ids
b._state = None
b._loading = bk._SdLoading(
repo_id = "unsloth/FLUX.1-dev-GGUF",
base_repo = "black-forest-labs/FLUX.1-dev",
asset_repos = ("black-forest-labs/FLUX.1-schnell",),
)
loading = set(b.loading_repo_ids())
assert {"black-forest-labs/FLUX.1-schnell", "unsloth/FLUX.1-schnell"} <= loading
assert {"black-forest-labs/FLUX.1-dev", "unsloth/FLUX.1-dev"} <= loading
def test_download_plan_refuses_a_pick_native_cannot_serve():
b = SdCppDiffusionBackend(engine = _FakeEngine())
with pytest.raises(ValueError, match = "gguf_filename is required"):
b.download_plan("unsloth/Z-Image-Turbo-GGUF", model_kind = "gguf")
with pytest.raises(ValueError, match = "native sd.cpp asset mapping"):
b.download_plan(
"stabilityai/sdxl-turbo", gguf_filename = "sdxl-Q4_K_M.gguf", model_kind = "gguf"
)
def test_asset_specs_flux2_klein_selects_encoder_by_variant():
# FLUX.2-klein 4B pairs with Qwen3-4B, 9B with Qwen3-8B, so the encoder must come from the load identity, not the family default.
b = SdCppDiffusionBackend(engine = _FakeEngine())
fam = detect_family("flux.2-klein")
specs_4b = b._asset_specs("unsloth/FLUX.2-klein-4B-GGUF", "FLUX.2-klein-4B-Q4_K_M.gguf", fam)
te_4b = [(r, f) for r, f, k in specs_4b if k == "llm"]
assert te_4b == [(r, f) for r, f, _k in fam.sd_cpp_text_encoders]
assert te_4b[0][0] == "unsloth/Qwen3-4B-GGUF"
specs_9b = b._asset_specs("unsloth/FLUX.2-klein-9B-GGUF", "FLUX.2-klein-9B-Q4_K_M.gguf", fam)
te_9b = [(r, f) for r, f, k in specs_9b if k == "llm"]
assert te_9b == [(r, f) for r, f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS]
assert te_9b[0][0] == "unsloth/Qwen3-8B-GGUF"
assert te_4b != te_9b
# Every community repack Unsloth depends on has a byte-identical unsloth mirror.
_REPACKER_ORGS = frozenset(
{"comfy-org", "comfyanonymous", "quantstack", "city96", "calcuis", "orabazes"}
)
def test_no_sd_cpp_asset_comes_from_a_community_repack():
from core.inference.diffusion_families import _FAMILIES
offenders = []
for fam in _FAMILIES:
specs = list(fam.sd_cpp_text_encoders)
if fam.sd_cpp_vae:
specs.append((*fam.sd_cpp_vae, "vae"))
specs.extend(_FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS)
for repo, _f, _k in specs:
if repo.split("/", 1)[0].lower() in _REPACKER_ORGS:
offenders.append((fam.name, repo))
assert offenders == []
def test_the_moved_sd_cpp_assets_keep_their_upstream_relative_paths():
# Image sd-cli assets are upstream files at their upstream path on the mirror, or an unsloth
# GGUF; a reorganised mirror would 404 sd-cli.
from core.inference.diffusion_families import _FLUX1_SD_CPP_TEXT_ENCODERS, mirror_repo
flux1 = [(r, f) for r, f, _k in _FLUX1_SD_CPP_TEXT_ENCODERS]
assert flux1 == [
("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors"),
("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model.safetensors.index.json"),
("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00001-of-00002.safetensors"),
("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00002-of-00002.safetensors"),
]
assert [k for _r, _f, k in _FLUX1_SD_CPP_TEXT_ENCODERS] == [
"clip_l",
"t5xxl",
"t5xxl_shard",
"t5xxl_shard",
]
for name in ("flux.1", "flux.1-kontext"):
assert detect_family(name).sd_cpp_text_encoders == _FLUX1_SD_CPP_TEXT_ENCODERS, name
assert detect_family(name).sd_cpp_vae == (
"black-forest-labs/FLUX.1-schnell",
"ae.safetensors",
)
# Klein 4B and Z-Image share one Qwen3-4B GGUF; FLUX.2-dev reads the Mistral-Small-3.2 GGUF.
for name in ("flux.2-klein", "z-image"):
[(repo, fn, kind)] = detect_family(name).sd_cpp_text_encoders
assert (repo, kind) == ("unsloth/Qwen3-4B-GGUF", "llm"), name
assert fn.startswith("Qwen3-4B-") and fn.endswith(".gguf"), name
[(repo, fn, kind)] = detect_family("flux.2-dev").sd_cpp_text_encoders
assert (repo, kind) == ("unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF", "llm")
assert fn.startswith("Mistral-Small-3.2-24B-Instruct-2506-") and fn.endswith(".gguf")
for name in ("qwen-image", "qwen-image-edit"):
assert detect_family(name).sd_cpp_vae == (
"Qwen/Qwen-Image",
"vae/diffusion_pytorch_model.safetensors",
), name
# Z-Image decodes with the FLUX.1 autoencoder.
assert detect_family("z-image").sd_cpp_vae == (
"black-forest-labs/FLUX.1-schnell",
"ae.safetensors",
)
for name in ("flux.2-klein", "flux.2-dev"):
assert detect_family(name).sd_cpp_vae == (
"black-forest-labs/FLUX.2-dev",
"vae/diffusion_pytorch_model.safetensors",
), name
# Each vendor VAE / encoder repo is reached through an unsloth mirror holding the same path.
for upstream in (
"black-forest-labs/FLUX.1-schnell",
"black-forest-labs/FLUX.2-dev",
"Qwen/Qwen-Image",
):
assert (mirror_repo(upstream) or "").startswith("unsloth/"), upstream
def test_map_guidance_flux_uses_distilled_guidance():
# cfg must be explicit: unset, sd.cpp applies its default 7.0 and FLUX.1 renders dark or burnt.
assert _map_guidance(detect_family("flux.1"), 3.5) == (1.0, 3.5)
assert _map_guidance(detect_family("flux.1"), 0.0) == (1.0, 0.0)
assert _map_guidance(detect_family("flux.1-kontext"), 2.5) == (1.0, 2.5)
assert _map_guidance(detect_family("flux.2-dev"), 4.0) == (1.0, 4.0)
assert _map_guidance(detect_family("flux.1"), None) == (1.0, None)
def test_map_guidance_flux2_klein_distilled_off_base_real_cfg():
assert _map_guidance(detect_family("flux.2-klein"), 1.0) == (1.0, None)
assert _map_guidance(detect_family("flux.2-klein"), 5.0) == (5.0, None)
assert _map_guidance(detect_family("flux.2-klein"), None) == (1.0, None)
_FLUX_DEFAULT_GUIDANCE_CASES = [
("unsloth/FLUX.1-dev-GGUF", "flux.1", 1.0, 3.5),
("unsloth/FLUX.1-schnell-GGUF", "flux.1", 1.0, 0.0),
("unsloth/FLUX.1-Kontext-dev-GGUF", "flux.1-kontext", 1.0, 2.5),
("unsloth/FLUX.2-dev-GGUF", "flux.2-dev", 1.0, 4.0),
("unsloth/FLUX.2-klein-4B-GGUF", "flux.2-klein", 1.0, None),
("unsloth/FLUX.2-klein-9B-GGUF", "flux.2-klein", 1.0, None),
("unsloth/FLUX.2-klein-base-4B-GGUF", "flux.2-klein", 5.0, None),
("unsloth/FLUX.2-klein-base-9B-GGUF", "flux.2-klein", 5.0, None),
]
def _edit_source(fam_name):
"""Kontext is edit-only on both engines: it renders from a source image, never from text alone."""
if detect_family(fam_name).edit:
import base64
import io
buf = io.BytesIO()
Image.new("RGB", (512, 512), (10, 20, 30)).save(buf, format = "PNG")
return {"init_image": base64.b64encode(buf.getvalue()).decode()}
return {}
@pytest.mark.parametrize("repo_id,fam_name,cfg,distilled", _FLUX_DEFAULT_GUIDANCE_CASES)
def test_flux_oneshot_argv_sends_explicit_cfg(repo_id, fam_name, cfg, distilled):
from core.inference.diffusion_families import default_generation_params
from core.inference.sd_cpp_args import build_sd_cpp_command
steps, guidance = default_generation_params(repo_id)
eng = _FakeEngine()
b = _loaded_backend(fam_name, engine = eng)
b.generate(prompt = "a fox", steps = steps, guidance = guidance, seed = 1, **_edit_source(fam_name))
files, params, out, _kw = eng.calls[-1]
argv = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = str(out))
assert float(argv[argv.index("--cfg-scale") + 1]) == cfg
if distilled is None:
assert "--guidance" not in argv
else:
assert float(argv[argv.index("--guidance") + 1]) == distilled
@pytest.mark.parametrize("repo_id,fam_name,cfg,distilled", _FLUX_DEFAULT_GUIDANCE_CASES)
def test_flux_server_request_sends_txt_cfg(repo_id, fam_name, cfg, distilled):
import dataclasses
from core.inference.diffusion_families import default_generation_params
steps, guidance = default_generation_params(repo_id)
b = _loaded_backend(fam_name)
server = _FakeServer("/bin/sd-server")
b._state = dataclasses.replace(b._state, mode = "server", server = server)
b.generate(prompt = "a fox", steps = steps, guidance = guidance, seed = 1, **_edit_source(fam_name))
g = server.payloads[-1]["sample_params"]["guidance"]
assert g["txt_cfg"] == cfg
assert g.get("distilled_guidance") == distilled
def test_map_guidance_cfg_family_off_when_distilled():
assert _map_guidance(detect_family("qwen-image"), 0.0) == (1.0, None)
assert _map_guidance(detect_family("qwen-image"), 4.0) == (4.0, None)
def test_map_guidance_z_image_converts_diffusers_g_to_standard_cfg():
# The shared default is diffusers' g = 3 (ComfyUI cfg 4); sd.cpp's standard CFG must get 4, Turbo's 0 stays off.
assert _map_guidance(detect_family("Tongyi-MAI/Z-Image"), 3.0) == (4.0, None)
assert _map_guidance(detect_family("Tongyi-MAI/Z-Image-Turbo"), 0.0) == (1.0, None)
def test_status_unloaded_reports_sd_cpp_engine():
b = SdCppDiffusionBackend(engine = _FakeEngine())
st = b.status()
assert st["loaded"] is False and st["engine"] == "sd_cpp"
def test_status_loaded_shape():
b = _loaded_backend()
st = b.status()
assert st["loaded"] is True
assert st["engine"] == "sd_cpp"
assert st["family"] == "z-image"
assert st["device"] == "cpu"
assert st["gguf_variant"] is None
for k in ("transformer_quant", "attention_backend", "transformer_cache", "text_encoder_quant"):
assert st[k] is None
assert st["supports_lora"] is True and st["lora_unavailable_reason"] is None
def test_status_names_why_a_native_family_has_no_lora():
st = _loaded_backend(fam_name = "qwen-image").status()
assert st["supports_lora"] is False
assert (
st["lora_unavailable_reason"]
== "The native sd.cpp engine cannot apply LoRAs to qwen-image."
)
def test_generate_returns_images_and_seed():
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, seed = 123, batch_size = 2)
assert out["seed"] == 123
assert out["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
assert len(out["images"]) == 2
assert all(isinstance(im, Image.Image) for im in out["images"])
assert len(eng.calls) == 2
seeds = [params.seed for _, params, _, _ in eng.calls]
assert seeds == [123, 124]
assert out["seeds"] == [123, 124]
def test_generate_qwen_passes_sampling_args():
eng = _FakeEngine()
b = _loaded_backend(fam_name = "qwen-image", engine = eng)
b.generate(prompt = "x", steps = 20, guidance = 4.0, seed = 1)
_, params, _, kw = eng.calls[0]
assert params.sampling_method == "euler"
assert "--flow-shift" in (kw.get("extra_args") or [])
def test_generate_refuses_a_snapshot_naming_another_model():
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
st = b.status()
loaded = bk.load_identity(st["repo_id"], st["base_repo"], st["family"])
with pytest.raises(bk.DiffusionModelReplacedError) as replaced:
stale = bk.load_identity("other/model", st["base_repo"], st["family"])
b.generate(prompt = "stale", expected_load = stale)
assert replaced.value.expected.repo_id == "other/model"
assert replaced.value.actual == loaded
assert eng.calls == []
assert b.generate(prompt = "x", steps = 4, expected_load = loaded)
assert b.generate(prompt = "x", steps = 4)
def test_generate_raises_when_not_loaded():
b = SdCppDiffusionBackend(engine = _FakeEngine())
with pytest.raises(RuntimeError, match = "No diffusion model is loaded"):
b.generate(prompt = "x")
def test_generate_passes_vae_format_for_flux2():
eng = _FakeEngine()
b = _loaded_backend(fam_name = "flux.2-klein", engine = eng)
b.generate(prompt = "x", steps = 4, seed = 1)
_, _, _, kw = eng.calls[0]
assert kw.get("extra_args") == ["--vae-format", "flux2"]
def test_oneshot_generate_refuses_a_binary_swapped_for_another_accelerator(monkeypatch):
# The one-shot path re-resolves sd-cli per image; a build for another accelerator must be refused.
import dataclasses
b = _loaded_backend()
b._state = dataclasses.replace(b._state, sd_accelerator = "cuda")
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda _binary: "cpu")
with pytest.raises(RuntimeError, match = "different accelerator"):
b.generate(prompt = "x", steps = 4, seed = 1)
def test_oneshot_generate_accepts_a_binary_for_the_same_accelerator(monkeypatch):
# Control: the guard must not fire when the re-resolved binary is the committed build.
import dataclasses
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
b._state = dataclasses.replace(b._state, sd_accelerator = "cuda")
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda _binary: "cuda")
b.generate(prompt = "x", steps = 4, seed = 1)
assert len(eng.calls) == 1
def test_generate_cancellation_raises_cancelled_not_failure():
eng = _FakeEngine(cancel_on_call = True)
b = _loaded_backend(engine = eng)
with pytest.raises(RuntimeError, match = "cancelled"):
b.generate(prompt = "x", steps = 8, seed = 5)
def test_cancel_generate_stops_a_running_native_run():
started = threading.Event()
b = None
class _BlockingEngine(_FakeEngine):
def generate(
self,
files,
params,
*,
output_path,
cancel_event = None,
**kw,
):
started.set()
assert cancel_event is not None and cancel_event.wait(5)
raise SdCppCancelled("cancelled")
b = _loaded_backend(engine = _BlockingEngine())
assert b.cancel_generate() is False
outcome: dict = {}
def _run():
try:
b.generate(prompt = "x", steps = 8, seed = 5)
except BaseException as exc: # noqa: BLE001 -- the assertion below pins the type
outcome["error"] = exc
worker = threading.Thread(target = _run, daemon = True)
worker.start()
assert started.wait(5)
assert b.cancel_generate() is True
worker.join(10)
assert isinstance(outcome["error"], RuntimeError)
assert b.cancel_generate() is False
def test_cancel_generate_is_a_no_op_when_idle():
assert SdCppDiffusionBackend(engine = _FakeEngine()).cancel_generate() is False
def test_generate_progress_tracks_parsed_steps():
b = _loaded_backend()
b._gen = bk._SdGen(total_steps = 8)
b._on_log(" sampling 4/8 done")
p = b.generate_progress()
assert p["active"] is True and p["step"] == 4 and p["total_steps"] == 8
b._on_log("loaded 1/3 tensors")
assert b.generate_progress()["step"] == 4
def test_generate_publishes_progress_before_lora_resolution(monkeypatch):
# LoRA resolution runs during pre-generate setup while _generate_lock is held, so a progress probe then must read ACTIVE.
from core.inference import diffusion_lora
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
monkeypatch.setattr(diffusion_lora, "supports_lora", lambda **_k: True)
seen: dict = {}
def _resolve(
active,
*,
family = None,
hf_token = None,
cancel_event = None,
):
seen["progress"] = b.generate_progress()
return []
monkeypatch.setattr(diffusion_lora, "resolve_specs", _resolve)
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, loras = [("some/lora", 1.0)])
assert out["images"]
assert seen["progress"]["active"] is True
assert seen["progress"]["total_steps"] == 8
def test_begin_load_rejects_unsupported_family(monkeypatch):
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(bk, "family_sd_cpp_supported", lambda fam: False)
with pytest.raises(ValueError, match = "no native sd.cpp asset mapping"):
b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")
def test_begin_load_requires_gguf_filename():
b = SdCppDiffusionBackend(engine = _FakeEngine())
with pytest.raises(ValueError, match = "gguf_filename is required"):
b.begin_load("unsloth/Z-Image-Turbo-GGUF")
def test_begin_load_resolves_family_from_filename_only(monkeypatch):
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)
b.begin_load("/models/gguf-store", gguf_filename = "Z-Image-Turbo-Q4_K_M.gguf")
assert b._loading is not None and b._loading.repo_id == "/models/gguf-store"
def test_each_load_owns_its_cancel_event(monkeypatch):
# A fresh Event per load: clearing one shared event would un-cancel the superseded worker.
b = SdCppDiffusionBackend(engine = _FakeEngine())
started = threading.Event()
seen: list[threading.Event] = []
def _capture(**kwargs):
seen.append(kwargs["_cancel_event"])
started.set()
monkeypatch.setattr(b, "_run_load", _capture)
b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")
assert started.wait(5)
first = seen[0]
b.unload()
assert first.is_set()
started.clear()
b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")
assert started.wait(5)
second = seen[1]
assert second is not first, "each load needs its own event, not a clear() of the shared one"
assert not second.is_set()
assert first.is_set(), "the superseded worker's event must stay set"
with pytest.raises(SdCppCancelled):
b._fetch_assets(
[("unsloth/Z-Image-Turbo-GGUF", "z.gguf", "diffusion_model")],
None,
cancel_event = first,
)
def test_ensure_binary_returns_found(monkeypatch):
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/usr/bin/sd-cli")
assert ensure_sd_cpp_binary() == "/usr/bin/sd-cli"
def test_ensure_binary_install_disabled_returns_none(monkeypatch):
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: None)
assert ensure_sd_cpp_binary(allow_install = False) is None
# Only the H3-only --ref-video separates a pre-H3 build from an H3 one.
_PRE_H3_HELP = (
# The banner separates a pre-H3 sd.cpp build from a program that is not sd.cpp.
"stable-diffusion.cpp version unknown, commit unknown\n"
" -M, --mode run mode, one of [img_gen, vid_gen, upscale, convert]\n"
" --audio-vae <string> path to standalone LTX audio vae model\n"
)
_H3_HELP = _PRE_H3_HELP + (
" --ref-video MiniMax-H3 Ref2VA reference video frame directory at 24 fps\n"
)
def test_h3_binary_gate_replaces_a_stale_managed_install(monkeypatch, tmp_path):
stale = tmp_path / "stale" / "sd-cli"
fresh = tmp_path / "fresh" / "sd-cli"
for p in (stale, fresh):
p.parent.mkdir()
p.write_text("binary")
found = [str(stale), str(fresh)]
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: found.pop(0))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda binary, *_args: _H3_HELP if binary == str(fresh) else _PRE_H3_HELP,
)
assert bk.ensure_h3_sd_cpp_binary() == str(fresh)
assert not stale.exists()
def test_h3_binary_gate_defers_while_a_generation_holds_the_tree(monkeypatch, tmp_path):
# Dropping the stale copy writes to the managed tree, so it takes install admission.
stale = tmp_path / "stale" / "sd-cli"
stale.parent.mkdir()
stale.write_text("binary")
ensures: list[bool] = []
monkeypatch.setattr(
bk,
"ensure_sd_cpp_binary",
lambda **kwargs: (ensures.append(kwargs.get("allow_install", True)), str(stale))[1],
)
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: _PRE_H3_HELP)
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
with bk._tree_reader(str(stale)):
assert bk.ensure_h3_sd_cpp_binary() is None
assert stale.exists()
assert ensures == [True]
def test_h3_binary_gate_refuses_but_keeps_a_user_supplied_build(monkeypatch, tmp_path):
# The user's own build is not ours to delete, so the load fails naming the binary.
own = tmp_path / "sd-cli"
own.write_text("binary")
excinfo = _shared_setup_3(monkeypatch, own)
assert own.exists()
# PATH discovery can hand this /usr/bin/sd, so the message must not say "remove".
assert "remove" not in str(excinfo.value)
assert str(own) in str(excinfo.value)
def test_h3_binary_gate_offers_to_clear_an_unmarked_install_directory(monkeypatch, tmp_path):
root = tmp_path / "studio" / "stable-diffusion.cpp"
own = root / "sd-cli"
root.mkdir(parents = True)
own.write_text("binary")
monkeypatch.setattr(bk, "managed_install_root", lambda: root)
excinfo = _shared_setup_3(monkeypatch, own)
assert f"move {root} aside" in str(excinfo.value)
assert "remove" not in str(excinfo.value)
assert own.exists()
def test_h3_binary_gate_never_offers_to_delete_the_in_tree_developer_build(monkeypatch, tmp_path):
# <repo_root>/stable-diffusion.cpp may be the user's git clone, so deletion is never offered.
root = tmp_path / "repo" / "stable-diffusion.cpp"
own = root / "build" / "bin" / "sd-cli"
own.parent.mkdir(parents = True)
own.write_text("binary")
# raising=False: the hint does not import it; the patch makes this a regression guard.
monkeypatch.setattr(bk, "in_tree_install_root", lambda: root, raising = False)
excinfo = _shared_setup_3(monkeypatch, own)
assert "remove" not in str(excinfo.value)
assert own.exists()
def test_h3_binary_gate_logs_the_real_fault_for_a_managed_non_sd_cpp_binary(
monkeypatch, tmp_path, capsys
):
own = tmp_path / "sd-cli"
own.write_text("binary")
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: "sd 1.0.0\nFind & replace CLI\n")
assert bk.ensure_h3_sd_cpp_binary(allow_install = False) is None
# capsys, not caplog: the backend logs through structlog, which writes to stdout.
logged = capsys.readouterr().out
assert "is not stable-diffusion.cpp" in logged
assert "MiniMax-H3" not in logged
assert own.exists()
def test_h3_binary_gate_names_a_binary_that_is_not_sd_cpp_at_all(monkeypatch, tmp_path):
# #8507: SD_CLI_PATH pointed at Debian's `sd` find-and-replace tool; identity is not capability.
own = tmp_path / "sd"
own.write_text("binary")
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda *_args: "sd 1.0.0\nFind & replace CLI\n\nUSAGE:\n sd <find> <replace-with>\n",
)
with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
bk.ensure_h3_sd_cpp_binary()
assert own.exists()
def test_h3_binary_gate_requires_identity_not_just_the_h3_marker(monkeypatch, tmp_path):
# --ref-video alone is not a signature: unrelated tools expose it too.
own = tmp_path / "reference-video-cli"
own.write_text("binary")
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda *_args: "reference-video-cli 2.1\n --ref-video PATH reference clip\n",
)
with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
bk.ensure_h3_sd_cpp_binary()
def test_h3_binary_gate_probes_help_once_for_both_questions(monkeypatch, tmp_path):
# Identity is read off the capability probe's output; a second spawn could read another build.
own = tmp_path / "sd-cli"
own.write_text("binary")
calls: list[tuple] = []
def _probe(binary, *args):
calls.append((binary, args))
return "sd 1.0.0\nFind & replace CLI\n"
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
monkeypatch.setattr(bk, "_sd_cpp_probe_output", _probe)
with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
bk.ensure_h3_sd_cpp_binary()
assert [args for _b, args in calls] == [("--help",)]
def test_h3_binary_gate_keeps_a_binary_it_cannot_probe(monkeypatch):
# An unreadable --help is "cannot tell", not "no H3".
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: "/usr/bin/sd-cli")
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: None)
assert bk.ensure_h3_sd_cpp_binary() == "/usr/bin/sd-cli"
def test_lists_accelerator_device_reads_the_ggml_device_list(monkeypatch):
# --list-devices is the only way to tell a reused CPU prebuilt from an accelerator build after
# the fact: the finder returns whichever binary is installed, whatever accelerator was asked for.
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "CPU\tIntel(R) Xeon(R) Platinum\n")
assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is False
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda *_a: "CUDA0\tNVIDIA GeForce RTX 4090\nCPU\tIntel(R) Xeon(R) Platinum\n",
)
assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is True
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is True
assert bk.sd_cpp_lists_accelerator_device(None) is False
def test_graph_cut_options_support_legacy_and_current_builds_and_fail_closed(monkeypatch):
# unknown flags fail closed because sd-cli rejects them.
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda *_a: " --max-vram budget\n --stream-layers residency\n",
)
assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == {"--max-vram", "--stream-layers"}
# current builds stream automatically and reject the removed --stream-layers flag.
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: " --max-vram budget\n")
assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == {"--max-vram"}
# --stream-layers requires --max-vram, so a partial advertisement emits neither.
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: " --stream-layers residency\n")
assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: _PRE_H3_HELP)
assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()
assert bk.sd_cpp_graph_cut_options(None) == frozenset()
def test_vulkan_uma_reads_ggml_vulkans_own_device_line(monkeypatch):
listing = (
"ggml_vulkan: Found 2 Vulkan devices:\n"
"ggml_vulkan: 0 = AMD Radeon RX 7900 XTX (RADV NAVI31) (radv) | uma: 0 | fp16: 1 | bf16: 0 |\n"
"ggml_vulkan: 1 = AMD Radeon Graphics (RADV RAPHAEL_MENDOCINO) (radv) | uma: 1 | fp16: 1 | bf16: 0 |\n"
"Vulkan0\tAMD Radeon RX 7900 XTX (RADV NAVI31)\nVulkan1\tAMD Radeon Graphics\nCPU\tAMD Ryzen 9 9900X\n"
)
monkeypatch.setattr(bk, "_LAST_DEVICE_LISTING", {})
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: listing)
assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", None) is False
assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "Vulkan1") is True
assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "Vulkan2") is None
assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "ROCm0") is None
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "Vulkan0\tAMD Radeon\n")
assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", None) is None
assert bk.sd_cpp_vulkan_device_is_uma(None, None) is None
def test_device_name_for_ordinal_reads_the_ggml_device_list(monkeypatch):
monkeypatch.setattr(
bk,
"_sd_cpp_probe_output",
lambda *_a: "CUDA0\tRTX 4070 Ti\nCUDA1\tRTX 5060 Ti\nCPU\tAMD Ryzen 9\n",
)
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) == "CUDA1"
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 0) == "CUDA0"
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 3) is None
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", None) is None
assert bk.sd_cpp_device_name_for_ordinal(None, 1) is None
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "ROCm1\tRadeon RX 7900\n")
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) == "ROCm1"
# Vulkan ordinals are another namespace, so they never match: pinning one would name a card the user did not choose.
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "Vulkan1\tRTX 5060 Ti\n")
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) is None
monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) is None
def test_offload_device_pin_is_probed_against_the_binary_it_is_given(monkeypatch):
# A deferred install swaps the build after the offload policy, so probe the binary given.
seen: list = []
def _probe(binary, *_args):
seen.append(binary)
return "CUDA0\tA\nCUDA1\tB\n" if binary == "/new/sd-cli" else "CPU\tRyzen\n"
monkeypatch.setattr(bk, "_sd_cpp_probe_output", _probe)
monkeypatch.setattr(bk, "physical_card_name", lambda ordinal: (None, None))
base = ["--offload-to-cpu"]
assert bk._offload_with_device_pin_impl(base, "/old/sd-cli", 1) == base
assert bk._offload_with_device_pin_impl(base, "/new/sd-cli", 1) == [
"--offload-to-cpu",
"--backend",
"diffusion=CUDA1,te=CUDA1,vae=CUDA1",
]
assert seen == ["/old/sd-cli", "/new/sd-cli"]
seen.clear()
assert bk._offload_with_device_pin_impl(base, "/new/sd-cli", None) == base
assert seen == []
def test_unload_clears_state_and_signals_cancel():
cancel = threading.Event()
b = _loaded_backend()
b._active_generate_cancel = cancel
st = b.unload()
assert st["loaded"] is False
assert cancel.is_set()
assert b._cancel_event.is_set()
def test_status_reports_offload_when_flags_active():
b = _loaded_backend()
assert b.status()["offload_policy"] == "none" and b.status()["cpu_offload"] is False
s = b._state
b._state = bk._SdState(
repo_id = s.repo_id,
base_repo = s.base_repo,
family = s.family,
device = "cuda",
files = s.files,
offload_flags = ("--vae-on-cpu", "--clip-on-cpu"),
)
st = b.status()
assert st["cpu_offload"] is True and st["offload_policy"] == "active"
def test_run_load_cancels_and_waits_for_inflight_generation(monkeypatch):
# _run_load must cancel an in-flight generation and wait on _generate_lock before committing.
b = SdCppDiffusionBackend(engine = _FakeEngine())
fam = detect_family("z-image")
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
monkeypatch.setattr(
b,
"_fetch_assets",
lambda *a, **k: {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"},
)
# Avoid importing torch from the worker thread (its first import deadlocks off the main thread); the device only needs to be CPU.
monkeypatch.setattr(
bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
)
b._load_token = 5
cancel = threading.Event()
b._active_generate_cancel = cancel
committed = threading.Event()
def _load():
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 5,
)
committed.set()
b._generate_lock.acquire()
try:
threading.Thread(target = _load, daemon = True).start()
assert not committed.wait(0.5)
assert b._state is None
assert cancel.is_set()
finally:
b._generate_lock.release()
assert committed.wait(5)
assert b._state is not None and b._state.repo_id == "unsloth/Z-Image-Turbo-GGUF"
def test_resolve_backend_prefers_server(monkeypatch):
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
mode, binary, engine = b._resolve_backend()
assert mode == "server" and binary == "/x/sd-server" and engine is None
def test_resolve_backend_injected_engine_forces_oneshot():
b = SdCppDiffusionBackend(engine = _FakeEngine())
mode, binary, engine = b._resolve_backend()
assert mode == "oneshot" and binary is None and engine is not None
def test_resolve_backend_falls_back_to_oneshot_without_server(monkeypatch):
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
monkeypatch.setattr(bk, "_install_allowed", lambda: False)
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/usr/bin/sd-cli")
mode, binary, engine = b._resolve_backend()
assert mode == "oneshot" and engine is not None
def test_resolve_backend_cached_fallback_engine_does_not_pin_oneshot(monkeypatch):
# A lazily cached fallback engine (NOT an explicit injection) must not force one-shot: a later load can use a server again.
b = SdCppDiffusionBackend()
b._engine = _FakeEngine()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
mode, binary, engine = b._resolve_backend()
assert mode == "server" and binary == "/x/sd-server" and engine is None
def _run_server_load(
monkeypatch,
b,
servers,
fam_name = "z-image",
device = "cpu",
gguf_filename = "z.gguf",
family_override = None,
gpu_ordinal = None,
asset_paths = None,
):
fam = detect_family(fam_name)
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
def _factory(binary):
s = _FakeServer(binary)
servers.append(s)
return s
monkeypatch.setattr(bk, "SdCppServer", _factory)
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
monkeypatch.setattr(
b,
"_fetch_assets",
lambda *a, **k: dict(
asset_paths
or {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}
),
)
monkeypatch.setattr(
bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = device)
)
b._load_token = 1
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = gguf_filename,
base = fam.base_repo,
fam = fam,
family_override = family_override,
hf_token = None,
_load_token = 1,
gpu_ordinal = gpu_ordinal,
)
def test_paravirtual_mac_load_records_the_cpu_device(monkeypatch):
# The command builders force --backend cpu on a paravirtual Metal GPU, so state/status must say cpu, not mps.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "mps")
assert b._state.device == "cpu" and b.status()["device"] == "cpu"
# A CPU-backend abort is then not retried as a GPU-placement problem.
assert (
b._restart_server_on_cpu_backend(
b._state, "unsupported op 'MUL_MAT' ggml_abort", threading.Event()
)
is None
)
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
b = SdCppDiffusionBackend()
_run_server_load(monkeypatch, b, [], device = "mps")
assert b._state.device == "mps"
@pytest.mark.parametrize("accelerator", ["vulkan", "auto"])
def test_cpu_torch_on_the_vulkan_build_offloads_by_default(monkeypatch, accelerator):
# #13666: the card's VRAM was never measured, so auto streams weights instead of assuming they fit.
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: accelerator)
b = SdCppDiffusionBackend()
_run_server_load(monkeypatch, b, [], device = "cpu")
if accelerator == "vulkan":
assert b._state.device == "vulkan"
assert "--offload-to-cpu" in b._state.offload_flags
else:
assert b._state.device == "cpu"
assert b._state.offload_flags == ()
@pytest.mark.parametrize("lands", [True, False])
def test_cpu_torch_placement_follows_a_deferred_vulkan_install(monkeypatch, lands):
# The deferred upgrade may land the Vulkan build or keep the resident CPU one; place for what runs.
installed = {"accelerator": "cpu"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed["accelerator"])
def _upgrade(self, server_binary, **_kw):
if lands:
installed["accelerator"] = "vulkan"
return server_binary
monkeypatch.setattr(SdCppDiffusionBackend, "_upgraded_or_refused", _upgrade)
monkeypatch.setattr(
SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "vulkan")
)
monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True) # a resident server defers it
b = SdCppDiffusionBackend()
_run_server_load(monkeypatch, b, [], device = "cpu")
assert b._state.device == ("vulkan" if lands else "cpu")
assert ("--offload-to-cpu" in b._state.offload_flags) is lands
@pytest.mark.parametrize("listed,expected", [("vulkan", "vulkan"), (None, "cpu")])
def test_an_unowned_build_on_cpu_torch_places_by_its_device_listing(monkeypatch, listed, expected):
# SD_SERVER_PATH builds carry no install record; their --list-devices says what they render on.
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: None)
monkeypatch.setattr(bk, "sd_cpp_listed_device", lambda binary, *a, **k: (listed, None))
monkeypatch.setattr(
SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "vulkan")
)
b = SdCppDiffusionBackend()
_run_server_load(monkeypatch, b, [], device = "cpu")
assert b._state.device == expected
@pytest.mark.parametrize("device,expected", [("cuda", "cpu"), ("xpu", "cpu"), ("mps", "mps")])
def test_the_cpu_build_on_a_gpu_torch_places_on_cpu(monkeypatch, device, expected):
# CUDA or XPU torch can land on the CPU build; macOS is recorded cpu but renders on Metal.
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: "cpu")
b = SdCppDiffusionBackend()
_run_server_load(monkeypatch, b, [], device = device)
assert b._state.device == expected
if expected == "cpu":
assert b._state.offload_flags == ()
def test_server_load_spawns_once_and_status_reports_mode(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
assert len(servers) == 1
assert servers[0].started is not None
assert b._state is not None and b._state.mode == "server" and b._state.server is servers[0]
assert b.status()["native_mode"] == "server"
def test_server_status_preserves_explicit_family_provenance(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, family_override = "z-image")
family = b.status()["resolved"]["family_override"]
assert (family["value"], family["requested"], family["source"]) == ("z-image",) * 2 + (
"explicit",
)
assert (family["status"], family["reason"]) == ("applied", "requested")
def test_server_status_reports_selected_gguf_quant(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, gguf_filename = "z-image-turbo-Q8_0.gguf")
assert b.status()["gguf_variant"] == "Q8_0"
def test_server_generate_uses_one_request_for_whole_batch(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, seed = 7, batch_size = 3)
assert len(out["images"]) == 3
assert all(isinstance(im, Image.Image) for im in out["images"])
assert len(servers[0].payloads) == 1
assert servers[0].payloads[0]["batch_count"] == 3
assert out["seed"] == 7 and out["seeds"] == [7, 8, 9]
assert b._gen is None
_GGML_ABORT = (
"sd-server connection lost during img_gen poll (process exited, code -6)\n"
"Last output:\n"
"[ERROR] ggml_extend.hpp:70 - ggml_metal_op_encode_impl: error: unsupported op 'MUL_MAT'\n"
"1 sd-server 0x00000001044f8df4 ggml_abort + 156\n"
"10 sd-server 0x00000001043f6ce8 StableDiffusionGGML::sample"
)
def test_server_generation_restarts_on_the_cpu_backend_after_a_ggml_abort(monkeypatch):
# ggml aborts on an unimplemented op with no CPU fallback, so the load restarts on --backend cpu.
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "mps")
servers[0].img_gen_error = RuntimeError(_GGML_ABORT)
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 3)
assert len(out["images"]) == 1
assert len(servers) == 2 and servers[0].stopped is True
assert servers[1].started["extra_args"] == ["--backend", "cpu"]
assert servers[1].started["files"] is servers[0].started["files"]
assert servers[1].started["native_speed"] == servers[0].started["native_speed"]
assert b._state is not None and b._state.server is servers[1]
def test_cpu_backend_restart_happens_once_per_load(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "mps")
servers[0].img_gen_error = RuntimeError(_GGML_ABORT)
b.generate(prompt = "x", steps = 4, seed = 1)
assert len(servers) == 2
servers[1].img_gen_error = RuntimeError(_GGML_ABORT)
with pytest.raises(RuntimeError, match = "unsupported op"):
b.generate(prompt = "x", steps = 4, seed = 1)
assert len(servers) == 2
def test_server_death_without_the_abort_signature_is_not_retried(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "mps")
servers[0].img_gen_error = RuntimeError(
"sd-server connection lost during img_gen poll (process exited, code -9)"
)
with pytest.raises(RuntimeError, match = "code -9"):
b.generate(prompt = "x", steps = 4, seed = 1)
assert len(servers) == 1
def test_cpu_device_does_not_restart_on_an_abort(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cpu")
servers[0].img_gen_error = RuntimeError(_GGML_ABORT)
with pytest.raises(RuntimeError, match = "unsupported op"):
b.generate(prompt = "x", steps = 4, seed = 1)
assert len(servers) == 1
def test_server_generate_splits_batches_above_server_limit(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
out = b.generate(prompt = "x", width = 256, height = 256, steps = 4, seed = 100, batch_size = 10)
assert len(out["images"]) == 10
counts = [p["batch_count"] for p in servers[0].payloads]
assert counts == [bk._MAX_SERVER_BATCH, 10 - bk._MAX_SERVER_BATCH]
# Chunks share one request deadline; the server only splits because it caps images per job.
assert servers[0].timeouts[0] <= bk.NATIVE_GENERATION_TIMEOUT_S
assert servers[0].timeouts[1] <= servers[0].timeouts[0]
assert servers[0].timeouts[-1] > 1800.0
assert out["seeds"] == list(range(100, 110))
assert servers[0].payloads[1]["seed"] == 108
def test_server_generate_masks_large_seed(monkeypatch):
# sd.cpp's image seed is signed int64, so a larger explicit seed must be masked before it reaches the server.
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
out = b.generate(prompt = "x", width = 256, height = 256, steps = 4, seed = 2**64 - 1, batch_size = 1)
assert servers[0].payloads[0]["seed"] <= (1 << 63) - 1
assert all(s <= (1 << 63) - 1 for s in out["seeds"])
def test_status_clears_when_server_died(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
assert b.status()["loaded"] is True
servers[0].alive = False
st = b.status()
assert st["loaded"] is False
assert b._state is None
def test_server_generate_progress_from_stdout(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
seen = {}
class _WatchServer(_FakeServer):
def img_gen(
self,
payload,
*,
on_step = None,
cancel_event = None,
total_timeout = None,
):
on_step(" 4/8")
seen["mid"] = b.generate_progress()
return super().img_gen(
payload, on_step = on_step, cancel_event = cancel_event, total_timeout = total_timeout
)
b._state = bk._SdState(
repo_id = b._state.repo_id,
base_repo = b._state.base_repo,
family = b._state.family,
device = b._state.device,
files = b._state.files,
vae_format = b._state.vae_format,
sampling_method = b._state.sampling_method,
flow_shift = b._state.flow_shift,
server = _WatchServer("/x/sd-server"),
mode = "server",
)
b.generate(prompt = "x", steps = 8, seed = 1)
assert seen["mid"]["step"] == 4 and seen["mid"]["total_steps"] == 8
def test_server_unload_stops_server(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
st = b.unload()
assert st["loaded"] is False
assert servers[0].stopped is True
assert b._state is None
def test_server_reload_stops_old_server_before_new(monkeypatch):
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
b._load_token = 2
fam = detect_family("z-image")
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 2,
)
assert len(servers) == 2
assert servers[0].stopped is True
assert b._state.server is servers[1] and servers[1].stopped is False
def test_a_cancel_during_server_revalidation_stops_before_the_process_spawns(monkeypatch):
# An unload during the ~20s binary probe must be seen under the same lock that publishes.
b = SdCppDiffusionBackend()
cancel = threading.Event()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
def _revalidate_then_cancel(*_a, **_k):
cancel.set()
return True
monkeypatch.setattr(bk, "_server_binary_runnable", _revalidate_then_cancel)
started: list[str] = []
class _RecordingServer:
def __init__(self, binary):
self.stopped = False
def start(self, *a, **k):
started.append("start")
def stop(self):
self.stopped = True
monkeypatch.setattr(bk, "SdCppServer", _RecordingServer)
fake = _FakeEngine()
_shared_setup_1(b, fake, monkeypatch)
fam = detect_family("z-image")
b._load_token = 1
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 1,
_cancel_event = cancel,
)
assert started == [], "a cancelled load must not spawn the server process"
# A leaked _pending_server reads as a busy managed tree and blocks later installs.
assert b._pending_server is None
assert bk._tree_in_use(b) is False
def test_server_start_failure_falls_back_to_oneshot(monkeypatch):
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
class _BadServer:
def __init__(self, binary):
self.stopped = False
def start(self, *a, **k):
raise RuntimeError("sd-server broken")
def stop(self):
self.stopped = True
monkeypatch.setattr(bk, "SdCppServer", _BadServer)
fake = _FakeEngine()
_shared_setup_1(b, fake, monkeypatch)
fam = detect_family("z-image")
b._load_token = 1
_shared_setup_2(b, fam)
assert b._state is not None and b._state.mode == "oneshot" and b._state.server is None
# A stale _pending_server would suppress every later accelerator install.
assert b._pending_server is None
assert bk._tree_in_use(b) is False
out = b.generate(prompt = "x", steps = 4, seed = 1)
assert len(out["images"]) == 1 and len(fake.calls) == 1
def test_server_start_failure_keeps_the_engine_the_fallback_resolved(monkeypatch):
# The fallback must record the accelerator of the sd-cli it resolved, not of None.
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
class _BadServer:
def __init__(self, binary):
pass
def start(self, *a, **k):
raise RuntimeError("sd-server broken")
def stop(self):
pass
monkeypatch.setattr(bk, "SdCppServer", _BadServer)
fake = _FakeEngine()
fake.binary = "/x/sd-cli"
_shared_setup_1(b, fake, monkeypatch)
# Keyed on the binary: a constant stub would pass whether or not the bug is fixed.
monkeypatch.setattr(
bk, "_installed_accelerator_of", lambda binary: "cuda" if binary == "/x/sd-cli" else None
)
fam = detect_family("z-image")
b._load_token = 1
_shared_setup_2(b, fam)
assert b._state is not None and b._state.mode == "oneshot"
assert b._state.sd_accelerator == "cuda"
out = b.generate(prompt = "x", steps = 4, seed = 1)
assert len(out["images"]) == 1 and len(fake.calls) == 1
def test_server_unusable_after_the_download_keeps_the_engine_the_fallback_resolved(monkeypatch):
# Server to one-shot fallback after the download: the pin must not be taken off an engine of None.
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
# Runnable up front so the pre-download fallback is not the path under test; unusable by the
# time the claim re-checks it, which is what sends the load to sd-cli after the download.
runnable = [True]
def _runnable(*_a, **_k):
answer = runnable[0]
runnable[0] = False
return answer
monkeypatch.setattr(bk, "_server_binary_runnable", _runnable)
monkeypatch.setattr(bk, "ensure_sd_server_binary", lambda **_k: "/x/sd-server")
fake = _FakeEngine()
fake.binary = "/x/sd-cli"
_shared_setup_1(b, fake, monkeypatch)
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: "cuda" if binary else None)
fam = detect_family("z-image")
b._load_token = 1
b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
_shared_setup_2(b, fam)
assert b._state is not None, f"the fallback was refused: {b.load_progress().get('error')}"
assert b._state.mode == "oneshot" and b._state.server is None
assert b._state.sd_accelerator == "cuda"
out = b.generate(prompt = "x", steps = 4, seed = 1)
assert len(out["images"]) == 1 and len(fake.calls) == 1
def test_a_oneshot_load_refuses_a_cli_swapped_during_the_asset_download(monkeypatch):
# The one-shot accelerator is pinned when the engine is vetted, not after the long download.
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
monkeypatch.setattr(bk, "_install_allowed", lambda: False)
fake = _FakeEngine()
fake.binary = "/x/sd-cli"
monkeypatch.setattr(b, "_resolve_engine", lambda: fake)
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
monkeypatch.setattr(
bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
)
installed = ["cuda"]
monkeypatch.setattr(
bk, "_installed_accelerator_of", lambda binary: installed[0] if binary else None
)
def _fetch(*a, **k):
installed[0] = "cpu"
return {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}
monkeypatch.setattr(b, "_fetch_assets", _fetch)
fam = detect_family("z-image")
b._load_token = 1
b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
_shared_setup_2(b, fam)
assert b._state is None
assert "different accelerator" in (b.load_progress()["error"] or "")
def test_run_load_redacts_paths_in_progress_error(monkeypatch):
from utils import native_path_leases as npl
secret_root = "/managed/native/root"
npl._remember_native_path_for_redaction(secret_root, "model dir")
try:
b = SdCppDiffusionBackend(engine = _FakeEngine())
fam = detect_family("z-image")
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
def _boom(*a, **k):
raise RuntimeError(f"failed to read {secret_root}/z.gguf")
monkeypatch.setattr(b, "_fetch_assets", _boom)
b._load_token = 1
b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 1,
)
err = b.load_progress()["error"]
assert err and secret_root not in err and "<native_path>" in err
finally:
with npl._REDACTION_LOCK:
if secret_root in npl._NATIVE_PATH_REDACTIONS:
npl._NATIVE_PATH_REDACTIONS.remove(secret_root)
def _fake_materialize(resolved, dest, **kwargs):
"""Stand-in for diffusion_lora.materialize_native_dir: write a stub file per adapter
into ``dest`` and return the resolved list pointing at the written paths (mirroring the
real helper's contract without touching the Hub / real weights)."""
from pathlib import Path as _P
from core.inference import diffusion_lora as dl
dest.mkdir(parents = True, exist_ok = True)
out = []
for r in resolved:
p = _P(dest) / f"{r.alias}.safetensors"
p.write_bytes(b"stub")
out.append(dl.ResolvedLora(r.id, r.alias, str(p), r.fmt, r.weight))
return out
def _patch_lora(
monkeypatch,
resolved,
supported = True,
):
from core.inference import diffusion_lora as dl
monkeypatch.setattr(dl, "supports_lora", lambda **k: supported)
monkeypatch.setattr(dl, "resolve_specs", lambda specs, **k: list(resolved))
monkeypatch.setattr(dl, "materialize_native_dir", _fake_materialize)
def test_generate_oneshot_applies_loras_via_prompt_tags(monkeypatch):
from core.inference import diffusion_lora as dl
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
_patch_lora(
monkeypatch, [dl.ResolvedLora("id1", "myalias", "/x/a.safetensors", "safetensors", 0.8)]
)
b.generate(prompt = "a fox", steps = 4, seed = 1, loras = [("id1", 0.8)])
_, params, _, _ = eng.calls[0]
assert params.lora_dir is not None and params.lora_apply_mode == "auto"
assert "<lora:myalias:0.8>" in params.prompt
def test_generate_server_stages_loras_and_sends_structured_field(monkeypatch, tmp_path):
# Server-mode LoRA rides the structured `lora` field (the sdcpp API ignores prompt tags): staged into --lora-model-dir and referenced by relative path.
from pathlib import Path as _P
from core.inference import diffusion_lora as dl
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
servers[0].lora_dir = str(tmp_path)
_patch_lora(
monkeypatch, [dl.ResolvedLora("id1", "myalias", "/x/a.safetensors", "safetensors", 0.7)]
)
b.generate(prompt = "x", steps = 4, seed = 1, batch_size = 1, loras = [("id1", 0.7)])
payload = servers[0].payloads[0]
assert "lora" in payload and len(payload["lora"]) == 1
assert payload["lora"][0]["multiplier"] == 0.7
assert payload["lora"][0]["path"].endswith("myalias.safetensors")
assert "<lora:" not in payload["prompt"]
assert not list(_P(tmp_path).glob("gen_*"))
def test_generate_server_stages_loras_as_real_files_inside_the_lora_dir(monkeypatch, tmp_path):
# sd-server (master-982+) canonicalizes every file under --lora-model-dir and skips one resolving outside it
# (examples/server/runtime.cpp refresh_lora_cache / get_lora_full_path), so a symlink into the cache is dropped.
import os
from core.inference import diffusion_lora as dl
cache = tmp_path / "cache"
cache.mkdir()
src = cache / "adapter.safetensors"
src.write_bytes(b"weights")
server_dir = tmp_path / "server_loras"
server_dir.mkdir()
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers)
servers[0].lora_dir = str(server_dir)
monkeypatch.setattr(dl, "supports_lora", lambda **k: True)
monkeypatch.setattr(
dl,
"resolve_specs",
lambda specs, **k: [dl.ResolvedLora("id1", "myalias", str(src), "safetensors", 0.7)],
)
real = dl.materialize_native_dir
seen = []
def _spy(resolved, dest, **kwargs):
out = real(resolved, dest, **kwargs)
for m in out:
seen.append(
(os.path.islink(m.path), os.path.realpath(m.path), Path(m.path).read_bytes())
)
return out
monkeypatch.setattr(dl, "materialize_native_dir", _spy)
b.generate(prompt = "x", steps = 4, seed = 1, batch_size = 1, loras = [("id1", 0.7)])
assert len(seen) == 1
is_link, resolved_path, data = seen[0]
assert not is_link
assert Path(resolved_path).is_relative_to(Path(os.path.realpath(server_dir)))
assert data == b"weights"
assert src.read_bytes() == b"weights"
assert not list(server_dir.glob("gen_*"))
def _server_lora_run(monkeypatch, tmp_path, *, fail_first):
import dataclasses
import io
from core.inference import diffusion_lora as dl
buf = io.BytesIO()
Image.new("RGB", (64, 64)).save(buf, format = "PNG")
png = buf.getvalue()
seen = []
class _Server:
def __init__(self, lora_dir, fail):
self.lora_dir, self.fail = str(lora_dir), fail
def img_gen(self, payload, **kw):
# What sd-server would resolve: every payload path must exist under THIS server's lora dir.
seen.append(
(
self.lora_dir,
[(Path(self.lora_dir) / e["path"]).is_file() for e in payload["lora"]],
)
)
if self.fail:
raise RuntimeError("ggml unsupported op abort")
return [png]
@dataclasses.dataclass(frozen = True)
class _State:
family: object
server: object
sampling_method: object = None
flow_shift: object = None
sample_sigmas: object = None
src = tmp_path / "cache" / "a.safetensors"
src.parent.mkdir()
src.write_bytes(b"w")
old_dir, new_dir = tmp_path / "old", tmp_path / "new"
old_dir.mkdir()
new_dir.mkdir()
b = SdCppDiffusionBackend()
monkeypatch.setattr(
b,
"_restart_server_on_cpu_backend",
lambda state, text, cancel, **kw: _Server(new_dir, False),
)
# Published like a real load: a restart hands over only while _state still holds the server it replaces.
b._state = _State(family = detect_family("flux.1"), server = _Server(old_dir, fail_first))
b._generate_server(
b._state,
prompt = "p",
negative_prompt = None,
width = 64,
height = 64,
steps = 4,
seed = 1,
batch_size = 1,
cfg_scale = None,
flux_guidance = None,
lora_resolved = [dl.ResolvedLora("id1", "a", str(src), "safetensors", 0.5)],
cancel = threading.Event(),
)
return seen, old_dir, new_dir
def test_server_cpu_restart_restages_loras_in_the_new_server_dir(monkeypatch, tmp_path):
seen, old_dir, new_dir = _server_lora_run(monkeypatch, tmp_path, fail_first = True)
assert seen == [(str(old_dir), [True]), (str(new_dir), [True])]
assert not list(old_dir.glob("gen_*")) and not list(new_dir.glob("gen_*"))
def test_server_lora_staging_failure_leaves_no_partial_stage(monkeypatch, tmp_path):
import shutil
from core.inference import diffusion_lora as dl
def _no_link(*a, **k):
raise OSError(18, "Invalid cross-device link")
def _partial_copy(src, dst, *a, **k):
Path(dst).write_bytes(b"part")
raise OSError(28, "No space left on device")
monkeypatch.setattr(dl.os, "link", _no_link)
monkeypatch.setattr(shutil, "copy2", _partial_copy)
with pytest.raises(OSError, match = "No space left"):
_server_lora_run(monkeypatch, tmp_path, fail_first = False)
assert not list((tmp_path / "old").iterdir())
def test_generate_rejects_loras_on_unsupported_family(monkeypatch):
b = _loaded_backend(engine = _FakeEngine())
_patch_lora(monkeypatch, [], supported = False)
with pytest.raises(ValueError, match = "LoRA is not supported"):
b.generate(prompt = "x", steps = 4, seed = 1, loras = [("id1", 1.0)])
def test_generate_zero_weight_loras_are_noop(monkeypatch):
# weight-0 rows are dropped BEFORE the support gate, so an only-disabled request stays a no-op even where native LoRA is unsupported.
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
_patch_lora(monkeypatch, [], supported = False)
b.generate(prompt = "x", steps = 4, seed = 1, loras = [("id1", 0.0)])
_, params, _, _ = eng.calls[0]
assert params.lora_dir is None
def test_generate_rejects_controlnet_on_native_engine():
b = _loaded_backend(engine = _FakeEngine())
with pytest.raises(ValueError, match = "ControlNet is not yet supported on the native"):
b.generate(prompt = "x", steps = 4, seed = 1, controlnet = ("id", "img", "canny", 1.0, 0.0, 1.0))
@pytest.mark.parametrize("cn_strength", [0, 0.0, None])
def test_generate_treats_zero_strength_controlnet_as_disabled(cn_strength):
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
out = b.generate(
prompt = "x",
steps = 4,
seed = 1,
controlnet = ("id", "img", "canny", cn_strength, 0.0, 1.0),
)
assert len(out["images"]) == 1
def test_generate_rejects_image_conditioned_on_native_engine():
# image-conditioned generation is diffusers-only; native calls must fail, not use txt2img.
b = _loaded_backend(engine = _FakeEngine())
with pytest.raises(ValueError, match = "not yet supported on the native"):
b.generate(prompt = "x", steps = 4, seed = 1, init_image = "data:image/png;base64,AAAA")
def test_status_native_reports_supports_controlnet_false():
b = _loaded_backend()
assert b.status()["supports_controlnet"] is False
def test_native_negative_prompt_reaches_sd_cli_only_when_cfg_runs():
klein = _loaded_backend("flux.2-klein")
assert klein.status()["supports_negative_prompt"] is True
kw = dict(prompt = "a fox", negative_prompt = "text", width = 256, height = 256, steps = 4, seed = 1)
out = klein.generate(guidance = 4.0, **kw)
assert klein._engine.calls[-1][1].negative_prompt == "text"
assert out["negative_prompt"] == "text"
out = klein.generate(guidance = 1.0, **kw)
assert klein._engine.calls[-1][1].negative_prompt is None
assert out["negative_prompt"] is None
flux = _loaded_backend("flux.1")
assert flux.status()["supports_negative_prompt"] is False
out = flux.generate(guidance = 3.5, **kw)
assert flux._engine.calls[-1][1].negative_prompt is None
assert out["negative_prompt"] is None
def _synthetic_legacy_row(monkeypatch):
"""(repack, mirror) after adding a made-up mirror -> community repack row to the legacy table."""
from core.inference import diffusion_families
repack, mirror = "some-org/example-repack", "unsloth/example-repack-mirror"
monkeypatch.setitem(diffusion_families._SD_CPP_LEGACY_SOURCES, mirror.lower(), repack)
return repack, mirror
def test_a_cached_community_repack_is_reused_instead_of_re_downloading_the_mirror(
monkeypatch, tmp_path
):
"""Legacy repo-id caches are reused, so a cached community repack avoids redownloads."""
from core.inference.diffusion_families import prefer_cached_legacy_source
from core.inference.sd_cpp_backend import _fetch_repo_map
repack, mirror = _synthetic_legacy_row(monkeypatch)
root = tmp_path / f"models--{repack.replace('/', '--')}"
snapshot = root / "snapshots" / ("d" * 40)
(snapshot / "split_files" / "vae").mkdir(parents = True)
(snapshot / "split_files" / "vae" / "ae.safetensors").write_bytes(b"x" * 64)
(root / "refs").mkdir(parents = True)
(root / "refs" / "main").write_text("d" * 40, encoding = "utf-8")
monkeypatch.setattr(
"utils.hf_cache_settings.active_hf_hub_cache", lambda: str(tmp_path), raising = False
)
assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
assert _fetch_repo_map(assets, None)[mirror] == repack
monkeypatch.setattr(
"utils.hf_cache_settings.active_hf_hub_cache",
lambda: str(tmp_path / "empty"),
raising = False,
)
assert _fetch_repo_map(assets, None)[mirror] == mirror
# And a repo that mirrors nothing is returned unchanged.
assert prefer_cached_legacy_source("unsloth/Qwen-Image", ["x"]) == "unsloth/Qwen-Image"
def test_a_repack_left_in_the_pre_change_cache_root_still_wins_over_the_mirror(
monkeypatch, tmp_path
):
"""A repack left in the old cache root must win over the mirror, or its bytes become unreachable."""
from core.inference.sd_cpp_backend import _fetch_repo_map
repack, mirror = _synthetic_legacy_row(monkeypatch)
other = tmp_path / "before_the_move"
root = other / f"models--{repack.replace('/', '--')}"
snapshot = root / "snapshots" / ("d" * 40)
(snapshot / "split_files" / "vae").mkdir(parents = True)
(snapshot / "split_files" / "vae" / "ae.safetensors").write_bytes(b"x" * 64)
(root / "refs").mkdir(parents = True)
(root / "refs" / "main").write_text("d" * 40, encoding = "utf-8")
monkeypatch.setattr(
"utils.hf_cache_settings.active_hf_hub_cache",
lambda: str(tmp_path / "after_the_move"),
raising = False,
)
monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(other))
assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
assert _fetch_repo_map(assets, None)[mirror] == repack
def test_the_delete_guard_names_the_repack_as_well_as_the_mirror(monkeypatch):
"""The bytes land in whichever of the three the load chose, and that is re-decided per load, so
a guard naming only one of them can delete a repo the next load needs."""
from core.inference.sd_cpp_backend import _with_mirrors
repack, mirror = _synthetic_legacy_row(monkeypatch)
protected = _with_mirrors([mirror])
assert mirror in protected
assert repack in protected
# No real row is left: the Wan GGUF no longer drags its old QuantStack repack along.
assert "QuantStack/Wan2.2-TI2V-5B-GGUF" not in _with_mirrors(["unsloth/Wan2.2-TI2V-5B-GGUF"])
def test_begin_load_answers_without_waiting_on_the_header_probe(monkeypatch):
"""begin_load must not wait on the network probe, which the worker repeats before any fetch."""
import time as _time
from core.inference import diffusion_compat
diffusion_compat._reset_inner_dim_cache()
probed: list[str] = []
class _Slow:
def get(
self,
url,
headers = None,
timeout = None,
stream = False,
):
probed.append(url)
_time.sleep(30)
raise AssertionError("unreachable")
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Slow())
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)
started = _time.monotonic()
b.begin_load("unsloth/FLUX.2-klein-4B-GGUF", gguf_filename = "flux-2-klein-4b-Q4_K_M.gguf")
elapsed = _time.monotonic() - started
assert probed == [], "begin_load must not range-read the header on the route thread"
assert elapsed < 5, f"begin_load blocked for {elapsed:.1f}s"
def test_the_worker_publishes_the_real_encoder_repos_before_fetching(monkeypatch):
# The delete-cached guard reads _loading.asset_repos, so it must be refreshed for FLUX.2 9B.
from core.inference import diffusion_compat
diffusion_compat._reset_inner_dim_cache()
nine_b = {repo for repo, _f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS}
# A name with no size: the string fallback answers 4B while the header says 9B.
repo, filename = "unsloth/FLUX.2-klein-GGUF", "flux-2-klein-Q4_K_M.gguf"
monkeypatch.setattr(
bk.SdCppDiffusionBackend,
"_flux2_inner_dim",
staticmethod(
lambda repo_id, fn, fam, tok, allow_network = True: 4096 if allow_network else None
),
)
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)
b.begin_load(repo, gguf_filename = filename)
token = b._load_token
assert not nine_b & set(
b.loading_repo_ids()
), "fixture is not discriminating: begin_load already guessed the 9B encoders"
monkeypatch.setattr(b, "_resolve_backend", lambda: ("oneshot", None, _FakeEngine()))
monkeypatch.setattr(b, "_preflight_companion_repos", lambda *a, **k: None)
monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
seen_at_fetch: list[tuple[str, ...]] = []
def _fetch(*_a, **_k):
seen_at_fetch.append(b.loading_repo_ids())
raise SdCppCancelled("stop here; the publish already had to happen")
monkeypatch.setattr(b, "_fetch_assets", _fetch)
bk.SdCppDiffusionBackend._run_load(
b,
repo_id = repo,
gguf_filename = filename,
base = "black-forest-labs/FLUX.2-klein-9B",
fam = detect_family(repo),
hf_token = None,
_load_token = token,
)
assert seen_at_fetch, "the fetch was never reached"
assert nine_b <= set(
seen_at_fetch[0]
), "the delete guard did not name the encoders this load is about to write"
def test_generate_reports_the_build_the_recipe_persists():
b = _loaded_backend()
s = b._state
b._state = bk._SdState(
repo_id = s.repo_id,
base_repo = s.base_repo,
family = s.family,
device = "cuda",
files = s.files,
vae_format = s.vae_format,
sampling_method = s.sampling_method,
flow_shift = s.flow_shift,
mode = s.mode,
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
offload_flags = ("--vae-on-cpu", "--clip-on-cpu"),
)
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
assert out["model_kind"] == "gguf"
assert out["gguf_filename"] == "z-image-turbo-Q4_K_M.gguf"
assert out["offload_policy"] == "active"
assert out["offload_policy"] == b.status()["offload_policy"]
assert out["transformer_quant"] is None and out["text_encoder_quant"] is None
assert out["memory_mode"] is None
assert out["cpu_offload"] is True and out["cpu_offload"] == b.status()["cpu_offload"]
assert out["speed_mode"] == b.status()["speed_mode"]
def test_a_completed_native_generation_stops_advertising_itself_as_cancellable(monkeypatch):
# Final check and deregistration share cancel_generate's lock: no Stop is true for a finished run.
b = _loaded_backend()
seen: list[bool] = []
real_oneshot = b._generate_oneshot
def _oneshot(*args, **kwargs):
out = real_oneshot(*args, **kwargs)
assert b.cancel_generate() is True
return out
monkeypatch.setattr(b, "_generate_oneshot", _oneshot)
with pytest.raises(RuntimeError, match = "cancelled"):
b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
b2 = _loaded_backend()
out = b2.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
assert out["images"]
seen.append(b2.cancel_generate())
assert seen == [False]
def _pinned_state(
b,
*,
policy_flags = (),
device = "cuda",
):
"""A resident native load whose argv carries the --backend device pin on top of `policy_flags`,
exactly as _run_load builds it once a card has been selected."""
from core.inference.sd_cpp_args import device_backend_flags
s = b._state
return bk._SdState(
repo_id = s.repo_id,
base_repo = s.base_repo,
family = s.family,
device = device,
files = s.files,
vae_format = s.vae_format,
sampling_method = s.sampling_method,
flow_shift = s.flow_shift,
mode = s.mode,
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
offload_flags = (
*policy_flags,
*device_backend_flags("CUDA1", list(policy_flags)),
),
)
def test_a_card_pick_is_not_reported_as_an_offload():
# The device pin shares the offload flag tuple; it must not make a "fast" load look offloaded.
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ())
assert b._state.offload_flags, "the fixture must actually carry the pin"
status = b.status()
assert status["cpu_offload"] is False
assert status["offload_policy"] == "none"
out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
assert out["offload_policy"] == "none"
def test_a_real_offload_still_reports_itself_when_a_card_is_pinned():
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu", "--diffusion-fa"))
assert b.status()["cpu_offload"] is True
assert b.status()["offload_policy"] == "active"
def test_the_cpu_backend_restart_drops_the_device_pin(monkeypatch):
# sd.cpp concatenates repeated --backend and per-module entries win, so the pin must be stripped.
started: dict = {}
class _FakeServer:
def __init__(self, binary):
self.binary = binary
def start(self, files, **kwargs):
started.update(kwargs)
def stop(self):
pass
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu", "--clip-on-cpu"))
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server")
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
server = b._restart_server_on_cpu_backend(
b._state,
"ggml_metal_op_encode_impl: unsupported op 'MUL_MAT' -> ggml_abort",
threading.Event(),
)
assert server is not None
argv = [*started["offload"], *started["extra_args"]]
backends = [argv[i + 1] for i, flag in enumerate(argv) if flag == "--backend"]
assert backends == ["cpu"]
assert "--offload-to-cpu" in argv and "--clip-on-cpu" in argv
def test_the_native_engine_resolves_a_bare_gpu_selection_itself(monkeypatch):
# A direct caller passes gpu_ids alone; native must re-rank like diffusers and video.
import core.inference.sd_cpp_backend as backend_module
seen: dict = {}
monkeypatch.setattr(
backend_module,
"resolve_diffusion_device_target",
lambda **kw: types.SimpleNamespace(device = "cuda"),
)
monkeypatch.setattr(
backend_module,
"resolve_selected_cuda_ordinal",
lambda ids: (seen.update(ids = list(ids)), 1)[1],
)
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_start_load_thread", lambda *a, **k: None, raising = False)
captured: dict = {}
def _fake_thread(
target = None,
kwargs = None,
**_,
):
captured.update(kwargs or {})
return types.SimpleNamespace(start = lambda: None, join = lambda *a, **k: None)
monkeypatch.setattr(backend_module.threading, "Thread", _fake_thread)
b.begin_load(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
gpu_ids = [3],
)
assert seen["ids"] == [3]
assert captured["gpu_ordinal"] == 1
def test_an_unresolvable_device_pin_says_so_and_still_loads(tmp_path, capsys):
# Older builds treat --list-devices as fatal, so an unresolved pick runs on the default device.
binary = tmp_path / "sd-cli-old"
binary.write_text("#!/usr/bin/env bash\nexit 1\n")
binary.chmod(0o755)
assert bk.sd_cpp_device_name_for_ordinal(str(binary), 1) is None
assert "device_pin_unresolved" in capsys.readouterr().out
assert bk.sd_cpp_device_name_for_ordinal(str(binary), None) is None
assert "device_pin_unresolved" not in capsys.readouterr().out
def test_generation_in_flight_tracks_a_generation(monkeypatch):
from core.inference import diffusion_lora
eng = _FakeEngine()
b = _loaded_backend(engine = eng)
monkeypatch.setattr(bk, "_sd_cpp_backend", b)
monkeypatch.setattr(diffusion_lora, "supports_lora", lambda **_k: True)
seen: dict = {}
def _resolve(
active,
*,
family = None,
hf_token = None,
cancel_event = None,
):
seen["in_flight"] = bk.generation_in_flight()
return []
monkeypatch.setattr(diffusion_lora, "resolve_specs", _resolve)
assert bk.generation_in_flight() is False
b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, loras = [("some/lora", 1.0)])
assert (
seen["in_flight"] is True
), "liveness cannot tell this backend from a dead one while the native engine renders"
assert bk.generation_in_flight() is False
def test_generation_in_flight_never_builds_a_backend(monkeypatch):
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
monkeypatch.setattr(
bk,
"SdCppDiffusionBackend",
lambda *a, **k: pytest.fail("liveness constructed a native diffusion backend"),
)
assert bk.generation_in_flight() is False
def test_the_marker_is_found_even_when_it_straddles_a_read_boundary(tmp_path):
# The scan reads 8 MiB blocks; the marker is placed across the seam.
marker = "qwen_image_2_1"
chunk = 8 << 20
path = tmp_path / "sd-cli"
body = bytearray(b"\0" * (chunk + len(marker) * 2))
body[chunk - len(marker) // 2 : chunk - len(marker) // 2 + len(marker)] = marker.encode()
path.write_bytes(bytes(body))
assert bk.binary_carries_marker(str(path), marker) is True
assert bk.binary_carries_marker(str(path), "wan_2_2_no_such_arch") is False
def test_an_unreadable_binary_and_an_unmarked_family_both_leave_the_route_alone(tmp_path):
# No marker, or an unreadable path, is no evidence, so neither may refuse.
present = tmp_path / "sd-cli"
present.write_bytes(b"nothing interesting")
assert bk.binary_carries_marker(str(present), None) is True
assert bk.binary_carries_marker(str(tmp_path / "missing"), "qwen_image_2_1") is True
assert bk.binary_carries_marker(None, "qwen_image_2_1") is False
assert bk.sd_cpp_binary_runs_family(str(present), detect_family("z-image")) is True
assert bk.sd_cpp_binary_runs_family(str(present), detect_family("qwen-image-2.1")) is False
def test_the_scan_is_redone_when_the_binary_on_that_path_changes(tmp_path):
# Memo keyed on size and mtime too: an upgrade writes a new build to the same path.
path = tmp_path / "sd-cli"
path.write_bytes(b"an old build")
assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is False
path.write_bytes(b"a new build with qwen_image_2_1 in it")
assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is True
def test_a_cached_engine_is_re_checked_against_the_family_now_loading(tmp_path):
# _engine is cached across loads, so it must be re-gated for the new family.
old = tmp_path / "sd-cli-old"
old.write_bytes(b"a build from before the family landed")
backend = SdCppDiffusionBackend.__new__(SdCppDiffusionBackend)
backend._engine = types.SimpleNamespace(binary = str(old), is_available = lambda: True)
backend._engine_injected = False
backend._loading_family = detect_family("z-image")
assert backend._resolve_engine() is backend._engine
backend._loading_family = detect_family("qwen-image-2.1")
with pytest.raises(RuntimeError, match = "predates qwen-image-2.1 support"):
backend._resolve_engine()
def test_a_rejected_concurrent_load_cannot_move_the_family_the_worker_validates_against():
# Take _lock before assigning the family, or a refused load replaces the family the worker checks.
backend = SdCppDiffusionBackend.__new__(SdCppDiffusionBackend)
worker_family = detect_family("qwen-image-2.1")
backend._loading_family = worker_family
seen = {}
started = threading.Event()
def _other_request():
backend._loading_family = detect_family("z-image")
started.set()
other = threading.Thread(target = _other_request)
other.start()
started.wait(timeout = 5)
other.join(timeout = 5)
seen["worker"] = backend._loading_family
assert seen["worker"] is worker_family, "another thread's family reached this worker"
def test_server_failure_drops_a_cached_sd_cli_of_the_failed_build(monkeypatch):
# An earlier one-shot load cached the Vulkan sd-cli; the Vulkan server now fails and the
# recorded failure moves the preferred build to CPU, so the fallback must not reuse the cache.
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
class _BadServer:
def __init__(self, binary):
pass
def start(self, *a, **k):
raise RuntimeError("ggml_vulkan: No devices found")
def stop(self):
pass
monkeypatch.setattr(bk, "SdCppServer", _BadServer)
fake = _FakeEngine()
fake.binary = "/vk/sd-cli"
_shared_setup_1(b, fake, monkeypatch)
monkeypatch.setattr(b, "_resolve_engine", SdCppDiffusionBackend._resolve_engine.__get__(b))
b._engine = fake
accelerators = {"/vk/sd-cli": "vulkan", "/cpu/sd-cli": "cpu"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: accelerators.get(binary))
monkeypatch.setattr(b, "_resolved_accelerator", lambda card = None: "cpu")
asked = []
def _ensure(**kwargs):
asked.append(kwargs.get("accelerator"))
return "/cpu/sd-cli"
monkeypatch.setattr(bk, "ensure_sd_cpp_binary", _ensure)
monkeypatch.setattr(b, "_refuse_incapable_build", lambda *_a, **_k: None)
class _CpuEngine(_FakeEngine):
def __init__(self, binary):
super().__init__()
self.binary = binary
monkeypatch.setattr(bk, "SdCppEngine", _CpuEngine)
fam = detect_family("z-image")
b._load_token = 1
_shared_setup_2(b, fam)
assert asked == ["cpu"]
assert b._state is not None and b._state.mode == "oneshot"
assert b._state.sd_accelerator == "cpu"
def test_a_deferred_cuda_upgrade_keeps_the_selected_card(monkeypatch):
# A CUDA load starts on the resident CPU bundle (placed on the CPU) and the deferred upgrade then
# lands the CUDA build: the server must still be pinned to the card the route selected.
b = SdCppDiffusionBackend()
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
monkeypatch.setattr(bk, "ensure_sd_server_binary", lambda **_k: "/x/sd-server")
started = []
class _Server:
def __init__(self, binary):
pass
def start(self, *a, **k):
started.append(k.get("offload"))
def stop(self):
pass
monkeypatch.setattr(bk, "SdCppServer", _Server)
fake = _FakeEngine()
_shared_setup_1(b, fake, monkeypatch)
monkeypatch.setattr(
bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cuda")
)
installed = {"/x/sd-server": "cpu"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed.get(binary))
def _upgrade(server_binary, **_k):
installed["/x/sd-server"] = "cuda"
return server_binary
monkeypatch.setattr(b, "_upgraded_or_refused", _upgrade)
monkeypatch.setattr(b, "_resolved_accelerator", lambda card = None: "cuda")
pins = []
monkeypatch.setattr(
bk,
"_offload_with_device_pin_impl",
lambda offload, binary, ordinal: pins.append(ordinal) or list(offload),
)
# The resident CPU bundle is in use, so _resolve_backend defers the upgrade to the teardown.
monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
fam = detect_family("z-image")
b._load_token = 1
b._run_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z.gguf",
base = fam.base_repo,
fam = fam,
hf_token = None,
_load_token = 1,
gpu_ordinal = 1,
)
assert started, "the server must start"
assert pins and all(p == 1 for p in pins), pins
assert b._state is not None and b._state.device == "cuda"
def test_the_arbiter_preflight_reads_the_cli_behind_an_unowned_server(monkeypatch):
# SD_SERVER_PATH is not installer-owned, so the managed sd-cli record is the answer.
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/custom/sd-server")
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/managed/sd-cli")
records = {"/managed/sd-cli": "vulkan"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: records.get(binary))
assert bk.managed_sd_cpp_accelerator() == "vulkan"
records["/custom/sd-server"] = "cpu"
assert bk.managed_sd_cpp_accelerator() == "cpu"
records.clear()
assert bk.managed_sd_cpp_accelerator() is None
def test_only_managed_cpu_binaries_count_as_cpu_only(monkeypatch):
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/custom/sd-server")
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/managed/sd-cli")
records = {"/managed/sd-cli": "cpu"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: records.get(binary))
# The unowned SD_SERVER_PATH build may render on a GPU.
assert bk.sd_cpp_binaries_all_cpu() is False
records["/custom/sd-server"] = "cpu"
assert bk.sd_cpp_binaries_all_cpu() is True
records["/managed/sd-cli"] = "vulkan"
assert bk.sd_cpp_binaries_all_cpu() is False
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: None)
assert bk.sd_cpp_binaries_all_cpu() is False
def test_a_t5_index_from_the_old_cache_root_gets_its_shards_beside_it(monkeypatch, tmp_path):
"""After a cache move the T5 index resolves from the old root; its shards are linked beside it,
since sd-cli reads them there rather than refusing a cache holding every file."""
import json
from pathlib import Path
_no_cache(monkeypatch)
b = _shared_setup_4(monkeypatch)
old_root, live_root = tmp_path / "old", tmp_path / "live"
def fake_download(repo, fn, tok, **k):
root = old_root if fn.endswith(".safetensors.index.json") else live_root
path = root / repo.replace("/", "--") / fn
path.parent.mkdir(parents = True, exist_ok = True)
if fn.endswith(".safetensors.index.json"):
shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
else:
path.write_bytes(b"shard:" + fn.encode())
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)
fam = detect_family("flux.1")
specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
shard_files = [f for _r, f, kind in specs if kind == "t5xxl_shard"]
assert len(shard_files) == 2
paths = b._fetch_assets(specs, None, local_files_only = True)
index = Path(paths["t5xxl"])
assert index.is_relative_to(old_root)
for fn in shard_files:
beside = index.parent / fn.rsplit("/", 1)[-1]
assert beside.read_bytes() == b"shard:" + fn.encode()
# Never a symlink into the other root: deleting or unmounting either root must not break the other.
assert not beside.is_symlink()
def test_a_cross_device_shard_copy_never_leaves_a_truncated_shard(monkeypatch, tmp_path):
"""A cut-off copy (full disk) must not leave a short file at the final name, since the existence
check accepts it; an earlier short file is replaced on next load."""
import json
import os
import shutil
from core.inference import sd_cpp_backend as mod
src = tmp_path / "live" / "model-00001-of-00001.safetensors"
src.parent.mkdir(parents = True)
src.write_bytes(b"x" * 4096)
index = tmp_path / "old" / "model.safetensors.index.json"
index.parent.mkdir(parents = True)
index.write_text(json.dumps({"weight_map": {"a": src.name}}))
target = index.parent / src.name
def no_link(*_a, **_k):
raise OSError("cross-device link")
def full_disk(a, b):
with open(b, "wb") as fh:
fh.write(b"x" * 100)
raise OSError("No space left on device")
real_copyfile = shutil.copyfile
monkeypatch.setattr(mod.os, "link", no_link)
monkeypatch.setattr(mod.shutil, "copyfile", full_disk)
mod._colocate_shards(str(index), {src.name: str(src)})
assert not target.exists()
assert os.listdir(index.parent) == [index.name]
# A short shard from an earlier, cut-off copy is replaced by a complete one.
target.write_bytes(b"x" * 100)
monkeypatch.setattr(mod.shutil, "copyfile", real_copyfile)
mod._colocate_shards(str(index), {src.name: str(src)})
assert target.read_bytes() == src.read_bytes()
assert sorted(os.listdir(index.parent)) == sorted([index.name, src.name])
def test_the_native_fetch_keeps_an_upstream_cached_only_in_the_pre_change_root(monkeypatch):
"""_fetch_assets resolves each file through either cache root, so FLUX.1's CLIP / T5 left in the previous root
serve the load. Deciding the mirror swap off the live root alone rewrote them to unsloth/FLUX.1-schnell, which a
cache-only load then could not find and an online one re-pulled (~10 GB)."""
monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
monkeypatch.setattr(
"core.inference.diffusion_families._upstream_is_cached",
lambda repo_id, files = None, *, other_root = False: other_root,
)
assets = [
("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
]
assert bk._fetch_repo_map(assets, None) == {
"black-forest-labs/FLUX.1-schnell": "black-forest-labs/FLUX.1-schnell"
}
def test_the_native_progress_total_is_sized_where_the_assets_are_fetched(monkeypatch):
"""An anonymous user gets nothing back from a gated vendor id, so sizing FLUX.1's CLIP / T5 there left them at 0
bytes and the bar finalizing while they downloaded. The total asks the repo _fetch_assets pulls from."""
from types import SimpleNamespace
from huggingface_hub import HfApi
_no_cache(monkeypatch)
asked = []
def get_paths_info(self, repo_id, paths, **kwargs):
asked.append(repo_id)
if not repo_id.startswith("unsloth/"):
raise PermissionError("gated")
return [SimpleNamespace(path = p, size = 1_000) for p in paths]
monkeypatch.setattr(HfApi, "get_paths_info", get_paths_info)
b = SdCppDiffusionBackend(engine = _FakeEngine())
b._loading = SimpleNamespace(expected_bytes = 0)
assets = [
("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
]
b._set_expected_bytes(assets, None)
assert asked == ["unsloth/FLUX.1-schnell", "unsloth/FLUX.1-schnell"]
assert b._loading.expected_bytes == 2_000
def _png_bytes():
import io
from PIL import Image
buf = io.BytesIO()
Image.new("RGB", (8, 8)).save(buf, format = "PNG")
return buf.getvalue()
@pytest.mark.parametrize("losses, recovers", [(1, True), (2, False)])
def test_a_lost_vulkan_device_restarts_the_resident_server(monkeypatch, losses, recovers):
# After VK_ERROR_DEVICE_LOST, restart the server on a fresh device and retry once; a second loss
# surfaces only where no CPU rung applies; no strike.
monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: False)
events: list = []
remaining = {"losses": losses}
class _FakeServer:
def __init__(self, binary):
self.binary = binary
events.append(("new", binary))
def start(self, files, **kwargs):
events.append(("start", kwargs.get("offload")))
def stop(self):
events.append(("stop", self.binary))
def img_gen(self, payload, **_kw):
if remaining["losses"]:
remaining["losses"] -= 1
raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
return [_png_bytes()]
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",), device = "vulkan")
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server-cpu")
bk._accelerator_runtime_failures.clear()
kwargs = dict(
prompt = "a fox",
negative_prompt = None,
width = 64,
height = 64,
steps = 2,
seed = 1,
batch_size = 1,
cfg_scale = None,
flux_guidance = None,
lora_resolved = [],
cancel = threading.Event(),
)
if recovers:
images, _seeds = b._generate_server(b._state, **kwargs)
assert len(images) == 1
else:
with pytest.raises(RuntimeError, match = "ErrorDeviceLost"):
b._generate_server(b._state, **kwargs)
# The same build, with the load's own flags (device pin included), not the CPU backend.
assert ("new", "/bin/sd-server-vulkan") in events[1:]
assert ("start", b._state.offload_flags) in events or any(
e[0] == "start" and "--offload-to-cpu" in (e[1] or ()) for e in events
)
assert not bk._accelerator_runtime_failures
def _repeated_device_loss_backend(
monkeypatch,
*,
losses,
gpu_explicit = False,
):
"""A CPU-torch Vulkan load whose first ``losses`` jobs lose the device, on whichever server runs them."""
events: list = []
remaining = {"losses": losses}
persisted: list = []
class _FakeServer:
lora_dir = None
def __init__(self, binary):
self.binary = binary
def start(self, files, **kwargs):
events.append(("start", self.binary, tuple(kwargs.get("extra_args") or ())))
def stop(self):
events.append(("stop", self.binary))
def is_alive(self):
return True
def img_gen(self, payload, **_kw):
if remaining["losses"]:
remaining["losses"] -= 1
raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
return [_png_bytes()]
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",), device = "vulkan")
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
object.__setattr__(b._state, "mode", "server")
object.__setattr__(b._state, "gpu_explicit", gpu_explicit)
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server-vulkan")
monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: True)
monkeypatch.setattr(
bk, "fallback_accelerator_for", lambda acc: "cpu" if acc == "vulkan" else None
)
monkeypatch.setattr(
bk, "_persist_accelerator_runtime_failures", lambda records: persisted.append(records)
)
monkeypatch.setattr(bk, "_stored_accelerator_runtime_failures", lambda: {})
bk._accelerator_runtime_failures.clear()
return b, events, persisted
def test_a_vulkan_device_lost_again_after_the_respawn_renders_this_load_on_cpu(monkeypatch):
# A driver that resets the card on every render (Windows TDR) must not fail every request; if
# the respawn also loses the device, only this load moves to CPU; nothing is persisted.
b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = 2)
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
starts = [e for e in events if e[0] == "start"]
# First the same-build respawn on Vulkan, then the CPU backend.
assert [s[2] for s in starts] == [(), ("--backend", "cpu")]
assert b._cpu_backend_forced is True
# The published state follows the server to CPU: status() no longer reports a Vulkan renderer, and the flags are
# the ones the CPU server got (the Vulkan device pin dropped).
assert b._state.device == "cpu"
assert b._state.physical_gpu_id is None
assert "--backend" not in b._state.offload_flags
assert b._state.offload_flags == ("--offload-to-cpu",)
assert b.status()["device"] == "cpu"
assert not persisted and not bk._accelerator_runtime_failures
# The failure text is not a strike either, and the next load still prefers Vulkan.
bk.note_accelerator_failure_from_output(
"/bin/sd-server-vulkan", "sd-server job failed: vk::Queue::submit: ErrorDeviceLost"
)
assert not persisted and not bk._accelerator_runtime_failures
assert bk.preferred_accelerator("vulkan") == "vulkan"
# Later requests on this load keep the CPU server without another restart.
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert len([e for e in events if e[0] == "start"]) == 2
def test_a_single_vulkan_device_loss_stays_on_vulkan(monkeypatch):
b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = 1)
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert [e[2] for e in events if e[0] == "start"] == [()]
assert b._cpu_backend_forced is False
assert b._state.device == "vulkan"
assert not persisted
_VRAM_REFUSAL = (
"sd-server generation failed: generation_failed: generate_image returned no results\n"
"Last output:\n"
"[E] MOSS-Image segment 1/43 (moss_image.layers.0) failed during weight preparation --- ggml_runner.cpp:934\n"
"[E] diffusion model compute failed --- diffusion_engine.cpp:2729\n"
"[E] Diffusion model sampling failed --- diffusion_engine.cpp:2976\n"
"[E] sampling for image 1/1 failed after 0.09s --- image.cpp:1007"
)
_ALLOCATION_FAILURE = (
"sd-server generation failed: generation_failed: generate_image returned no results\n"
"Last output:\n"
"[E] ggml: ggml_backend_cuda_buffer_type_alloc_buffer: allocating 210.08 MiB on device 0: "
"cudaMalloc failed: out of memory\n"
"[E] ggml: alloc_tensor_range: failed to allocate CUDA0 buffer of size 220288512\n"
"[E] MOSS-Image segment 12/43 (moss_image.layers.11) failed during {stage} --- ggml_runner.cpp:934\n"
"[E] diffusion model compute failed --- diffusion_engine.cpp:2729"
)
def _vram_refusal_backend(
monkeypatch,
*,
refusals,
planned_free_mib = None,
restarted_plans = (),
error = _VRAM_REFUSAL,
max_vram_supported = True,
per_device_supported = True,
policy_flags = (),
device = "cuda",
):
"""CUDA load pinned to CUDA1 whose first ``refusals`` jobs fail with ``error``; ``restarted_plans`` are the
free-VRAM plans each replacement server reads in turn."""
events: list = []
remaining = {"refusals": refusals}
planned = {"CUDA1": 6666} if planned_free_mib is None else planned_free_mib
plans = [planned, *restarted_plans]
class _FakeServer:
lora_dir = None
def __init__(self, binary):
self.binary = binary
self.planned_free_vram_mib = dict(plans.pop(0) if len(plans) > 1 else plans[0])
def start(self, files, **kwargs):
events.append(
("start", tuple(kwargs.get("extra_args") or ()), tuple(kwargs.get("offload") or ()))
)
def stop(self):
events.append(("stop",))
def is_alive(self):
return True
def img_gen(self, payload, **_kw):
if remaining["refusals"]:
remaining["refusals"] -= 1
raise RuntimeError(error)
return [_png_bytes()]
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = policy_flags, device = device)
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
object.__setattr__(b._state, "mode", "server")
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
monkeypatch.setattr(
bk,
"sd_cpp_graph_cut_options",
lambda binary: frozenset({"--max-vram"}) if max_vram_supported else frozenset(),
)
monkeypatch.setattr(bk, "_layer_split_supported", lambda binary: per_device_supported)
return b, events
def test_a_vram_refusal_restarts_once_under_half_the_planned_free_vram(monkeypatch):
b, events = _vram_refusal_backend(monkeypatch, refusals = 1)
flags = b._state.offload_flags
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
# Half of 6666 MiB, rounded down to 0.01 GiB.
assert [e for e in events if e[0] == "start"] == [("start", ("--max-vram", "3.25"), flags)]
assert b._state.vram_budget == "3.25"
assert b._state.device == "cuda" and b._state.offload_flags == flags
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert len([e for e in events if e[0] == "start"]) == 1
def test_a_vram_refusal_budgets_each_visible_card_from_its_own_free_vram(monkeypatch):
b, events = _vram_refusal_backend(
monkeypatch, refusals = 1, planned_free_mib = {"CUDA0": 45979, "CUDA1": 5771}
)
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "CUDA0=22.45,CUDA1=2.81")]
def test_a_vram_refusal_leaves_a_full_bystander_card_to_sd_cpp(monkeypatch):
b, events = _vram_refusal_backend(
monkeypatch, refusals = 1, planned_free_mib = {"CUDA0": 1800, "CUDA1": 6666}
)
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "CUDA1=3.25")]
def test_a_second_vram_refusal_in_the_same_request_is_surfaced(monkeypatch):
b, events = _vram_refusal_backend(monkeypatch, refusals = 2)
with pytest.raises(RuntimeError, match = "failed during weight preparation"):
b._generate_server(b._state, **_gen_kwargs())
assert len([e for e in events if e[0] == "start"]) == 1
def test_a_load_recovers_once_another_application_frees_the_card(monkeypatch):
# The restart planned while the card was busy (466 MiB); the next request restarts under the first plan's budget.
b, events = _vram_refusal_backend(
monkeypatch,
refusals = 3,
restarted_plans = ({"CUDA1": 466}, {"CUDA1": 6666}),
)
with pytest.raises(RuntimeError, match = "failed during weight preparation"):
b._generate_server(b._state, **_gen_kwargs())
assert b._state.vram_budget == "3.25"
assert b._state.server.planned_free_vram_mib == {"CUDA1": 466}
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1
assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "3.25")] * 2
@pytest.mark.parametrize(
"kwargs",
[
{"planned_free_mib": {}},
{"planned_free_mib": {"CUDA1": 1800}},
{"planned_free_mib": {"CUDA0": 45979, "CUDA1": 1800}},
{"planned_free_mib": {"CUDA0": 6666}},
{"max_vram_supported": False},
{"planned_free_mib": {"CUDA0": 45979, "CUDA1": 5771}, "per_device_supported": False},
{"device": "cpu"},
{"error": "sd-server generation failed: generation_failed: invalid sampler"},
{"error": _ALLOCATION_FAILURE.format(stage = "workspace allocation")},
{"error": _ALLOCATION_FAILURE.format(stage = "weight preparation")},
{
"error": _VRAM_REFUSAL.replace(
"Last output:\n",
"Last output:\n[E] ggml: ggml_backend_cpu_buffer_type_alloc_buffer: failed to allocate buffer of "
"size 220288512\n",
)
},
],
ids = [
"no_plan",
"below_floor",
"render_card_below_floor",
"render_card_not_planned",
"no_max_vram",
"no_per_device_budgets",
"cpu",
"other_error",
"workspace_allocation_failure",
"weight_staging_allocation_failure",
"host_allocation_failure",
],
)
def test_a_vram_refusal_without_a_usable_budget_is_surfaced_unchanged(monkeypatch, kwargs):
b, events = _vram_refusal_backend(monkeypatch, refusals = 1, **kwargs)
with pytest.raises(RuntimeError):
b._generate_server(b._state, **_gen_kwargs())
assert not [e for e in events if e[0] in ("start", "stop")]
assert b._state.vram_budget is None
def test_a_device_loss_respawn_keeps_the_reduced_vram_budget(monkeypatch):
b, events = _vram_refusal_backend(monkeypatch, refusals = 0, device = "vulkan")
object.__setattr__(b._state, "vram_budget", "3.25")
server = b._respawn_server_after_device_loss(
b._state, "sd-server job failed: vk::Queue::submit: ErrorDeviceLost", threading.Event()
)
assert server is not None
assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "3.25")]
@pytest.mark.parametrize("why", ["explicit_gpu", "no_cpu_rung", "fallback_disabled"])
def test_a_repeated_vulkan_device_loss_without_a_cpu_rung_errors_with_a_hint(monkeypatch, why):
# A user-picked GPU is never moved to CPU behind their back, and an Arc / ROCm host (no CPU rung) or a disabled
# Vulkan fallback keeps Vulkan: the second loss surfaces, with what to try.
b, events, persisted = _repeated_device_loss_backend(
monkeypatch, losses = 2, gpu_explicit = why == "explicit_gpu"
)
if why == "no_cpu_rung":
monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: False)
if why == "fallback_disabled":
monkeypatch.setattr(bk, "fallback_accelerator_for", lambda acc: None)
with pytest.raises(RuntimeError, match = "ErrorDeviceLost") as info:
b._generate_server(b._state, **_gen_kwargs())
assert "twice in a row" in str(info.value)
assert not bk.output_shows_accelerator_failure(str(info.value))
assert all(e[2] != ("--backend", "cpu") for e in events if e[0] == "start")
assert b._cpu_backend_forced is False
assert not persisted
@pytest.mark.parametrize("losses, device", [(1, "vulkan"), (2, "cpu")])
def test_a_device_loss_replacement_restages_the_hires_upscaler(
monkeypatch, tmp_path, losses, device
):
# Every replacement server (the same-build respawn after one lost device, the CPU backend after a second) has its
# own scratch dir, and the old server's stop removed the upscaler staged in its own: the retry must stage the model
# upscaler again under the server that runs it, or sd.cpp cannot find the hires upscaler file.
from core.inference import diffusion_hires as hires
b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = losses)
server_cls = type(b._state.server)
dirs: dict = {}
seen: list = []
def _lora_dir(self):
if id(self) not in dirs:
dirs[id(self)] = tmp_path / f"srv{len(dirs)}"
dirs[id(self)].mkdir()
return str(dirs[id(self)])
real_img_gen = server_cls.img_gen
def _img_gen(self, payload, **kw):
seen.append((self.lora_dir, dict(payload["hires"])))
return real_img_gen(self, payload, **kw)
monkeypatch.setattr(server_cls, "lora_dir", property(_lora_dir), raising = False)
monkeypatch.setattr(server_cls, "img_gen", _img_gen)
staged: list = []
def _stage(
upscaler_id,
scratch_dir,
*,
cancel = None,
):
dest = Path(scratch_dir) / "hires_x.pth"
dest.write_bytes(b"w")
staged.append(dest)
return "hires_x", dest
monkeypatch.setattr(hires, "stage_sd_cpp_upscaler", _stage)
plan = hires.SdCppHiresPlan(
params = hires.HiresParams(upscaler = "realesrgan_x4plus"),
base_width = 64,
base_height = 64,
target = (96, 96),
refine_steps = 2,
)
images, _seeds = b._generate_server(b._state, hires_plan = plan, **_gen_kwargs())
assert len(images) == 1
assert b._state.device == device
assert not persisted
# One server per attempt, each sent the upscaler staged in its own dir.
assert len(seen) == losses + 1
assert len({d for d, _ in seen}) == losses + 1
assert all(h["upscaler"] == "hires_x" for _, h in seen)
assert [str(p.parent) for p in staged] == [d for d, _ in seen]
assert b._state.server.lora_dir == seen[-1][0]
assert not any(p.exists() for p in staged)
def test_an_explicit_gpu_pool_marks_the_native_load_explicit(monkeypatch):
seen: dict = {}
monkeypatch.setattr(
"core.inference.diffusion_engine_router.off_torch_sd_cpp_device", lambda *a, **k: None
)
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_run_load", lambda **kw: seen.update(kw))
monkeypatch.setattr(bk, "resolve_selected_cuda_ordinal", lambda ids: None, raising = False)
b.begin_load(
repo_id = "unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z-image-turbo-Q4_K_M.gguf", gpu_ids = [0]
)
deadline = time.monotonic() + 5
while "gpu_explicit" not in seen and time.monotonic() < deadline:
time.sleep(0.01)
assert seen.get("gpu_explicit") is True
def _device_loss_backend(
monkeypatch,
tmp_path,
*,
on_start = None,
):
"""A loaded backend whose first job loses its Vulkan device; each server gets its own lora dir."""
servers: list = []
payloads: list = []
class _FakeServer:
def __init__(self, binary):
self.binary = binary
self.lora_dir = str(tmp_path / f"srv{len(servers)}")
os.makedirs(self.lora_dir, exist_ok = True)
self.stopped = False
servers.append(self)
def start(self, files, **kwargs):
if on_start is not None:
on_start(self)
def stop(self):
self.stopped = True
shutil.rmtree(self.lora_dir, ignore_errors = True)
def is_alive(self):
return not self.stopped
def img_gen(self, payload, **_kw):
payloads.append((self, dict(payload)))
if len(payloads) == 1:
raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
return [_png_bytes()]
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = (), device = "vulkan")
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
object.__setattr__(b._state, "mode", "server")
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
bk._accelerator_runtime_failures.clear()
return b, servers, payloads
def _gen_kwargs(lora_resolved = ()):
return dict(
prompt = "a fox",
negative_prompt = None,
width = 64,
height = 64,
steps = 2,
seed = 1,
batch_size = 1,
cfg_scale = None,
flux_guidance = None,
lora_resolved = list(lora_resolved),
cancel = threading.Event(),
)
def test_a_device_loss_retry_restages_the_loras_under_the_new_server(monkeypatch, tmp_path):
# The old server's stop removes its scratch dir and the staged adapters: the retry must stage them again.
from core.inference import diffusion_lora
def _materialize(
resolved,
stage,
real_files = False,
):
os.makedirs(stage, exist_ok = True)
(Path(stage) / "adapter.gguf").write_bytes(b"x")
return [types.SimpleNamespace(path = str(Path(stage) / "adapter.gguf"), weight = 0.8)]
monkeypatch.setattr(diffusion_lora, "materialize_native_dir", _materialize)
b, servers, payloads = _device_loss_backend(monkeypatch, tmp_path)
images, _seeds = b._generate_server(b._state, **_gen_kwargs(lora_resolved = ["adapter"]))
assert len(images) == 1 and len(servers) == 2
retry_server, retry_payload = payloads[-1]
assert retry_server is servers[1]
(entry,) = retry_payload["lora"]
# Staged under the replacement's own lora dir (the file exists there when the retry runs).
assert entry["path"] != payloads[0][1]["lora"][0]["path"]
assert entry["multiplier"] == 0.8
def test_an_unload_during_the_respawn_leaves_no_live_server(monkeypatch, tmp_path):
# unload() racing the restart must find the replacement (pending) or the handover must stop it.
holder: dict = {}
def _unload_mid_start(server):
holder["backend"].unload()
b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _unload_mid_start)
holder["backend"] = b
monkeypatch.setattr(b, "status", lambda: {})
with pytest.raises(SdCppCancelled):
b._generate_server(b._state, **_gen_kwargs())
assert len(servers) == 2
assert all(s.stopped for s in servers)
assert b._state is None and b._pending_server is None
def test_a_status_poll_during_the_respawn_keeps_the_replacement(monkeypatch, tmp_path):
# The UI polls /images/status while the respawn runs. The old server is already stopped then, and the idle-crash
# reap used to clear _state, so the handover read an unload and killed the healthy replacement.
holder: dict = {}
polls: list = []
def _poll_mid_start(server):
polls.append(holder["backend"].status()["loaded"])
b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _poll_mid_start)
holder["backend"] = b
images, _seeds = b._generate_server(b._state, **_gen_kwargs())
assert len(images) == 1 and len(servers) == 2
assert polls == [True]
assert b._state is not None and b._state.server is servers[1]
assert not servers[1].stopped and b._replacing_server is None
# Once the generation is done, a server that really died is reaped again.
servers[1].stopped = True
assert b.status()["loaded"] is False
def test_a_status_poll_during_the_cpu_backend_restart_keeps_the_load(monkeypatch):
import dataclasses
class _FakeServer:
def __init__(self, binary):
self.binary = binary
self.stopped = False
def start(self, files, **kwargs):
polls.append(b.status()["loaded"])
def stop(self):
self.stopped = True
def is_alive(self):
return not self.stopped
polls: list = []
b = _loaded_backend()
b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",))
object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
object.__setattr__(b._state, "mode", "server")
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server")
monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
state = b._state
server = b._restart_server_on_cpu_backend(
state,
"ggml_metal_op_encode_impl: unsupported op 'MUL_MAT' -> ggml_abort",
threading.Event(),
)
assert server is not None and polls == [True] and b._state is state
b._hand_over_replacement(dataclasses.replace(state, server = server), server, state.server)
assert b._state.server is server and not server.stopped
def test_a_superseding_load_during_the_respawn_is_not_overwritten(monkeypatch, tmp_path):
# A newer load that commits while the replacement starts owns _state: the handover must not publish the old
# model's replacement over it, and the replacement must not be left running untracked.
import dataclasses
holder: dict = {}
def _supersede_mid_start(server):
b = holder["backend"]
newer = _FakeNewer("/bin/sd-server-newer")
holder["newer"] = newer
with b._lock:
b._state = dataclasses.replace(b._state, server = newer)
class _FakeNewer:
def __init__(self, binary):
self.binary = binary
self.stopped = False
def stop(self):
self.stopped = True
def is_alive(self):
return not self.stopped
b, servers, payloads = _device_loss_backend(
monkeypatch, tmp_path, on_start = _supersede_mid_start
)
holder["backend"] = b
monkeypatch.setattr(b, "status", lambda: {})
with pytest.raises(SdCppCancelled):
b._generate_server(b._state, **_gen_kwargs())
assert len(servers) == 2 and servers[1].stopped # the stale replacement is stopped
assert b._state.server is holder["newer"] and not holder["newer"].stopped
assert len(payloads) == 1 and b._pending_server is None
def test_a_cancel_during_the_respawn_stops_the_replacement_start(monkeypatch, tmp_path):
# cancel_generate() (or a superseding load) only sets the generation's event; the replacement start blocks for the
# model load while _generate_lock is held, so it must notice and bail instead of loading for the full timeout.
kwargs = _gen_kwargs()
cancel = kwargs["cancel"]
def _cancel_mid_start(server):
cancel.set()
deadline = time.monotonic() + 5.0
while time.monotonic() < deadline:
if server.stopped:
raise RuntimeError("sd-server startup aborted before ready")
time.sleep(0.01)
b, servers, payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _cancel_mid_start)
monkeypatch.setattr(b, "status", lambda: {})
started = time.monotonic()
with pytest.raises(SdCppCancelled):
b._generate_server(b._state, **kwargs)
assert time.monotonic() - started < 4.0
assert len(servers) == 2 and all(s.stopped for s in servers)
assert len(payloads) == 1 # no retry job was posted
assert b._pending_server is None and b._replacing_server is None
def test_an_unload_before_the_respawn_starts_skips_it(monkeypatch, tmp_path):
# unload() wins outright when it lands first: no replacement is started at all.
b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path)
state = b._state
monkeypatch.setattr(b, "status", lambda: {})
b.unload()
assert (
b._respawn_server_after_device_loss(
state, "vk::Queue::submit: ErrorDeviceLost", threading.Event()
)
is None
)
assert len(servers) == 1 and b._replacing_server is None
@pytest.mark.parametrize(
"device,ccs,expected",
[
("cuda", [(10, 0)], {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}),
("cuda", [(8, 9)], None),
("cuda", [], None),
("cpu", [(10, 0)], None),
],
)
def test_cuda_sd_server_gets_the_bf16_cublas_route_by_compute_capability(
monkeypatch, device, ccs, expected
):
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: list(ccs))
monkeypatch.setattr(
bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = device)
assert servers and servers[-1].env == expected
assert dict(b._state.child_env) == (expected or {})
@pytest.mark.parametrize(
"weight_types", [frozenset({"Q4_K", "Q5_K"}), frozenset({"Q8_0", "Q4_K"}), None]
)
def test_a_k_quant_diffusion_gguf_keeps_mmq(monkeypatch, weight_types):
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
seen: list = []
monkeypatch.setattr(
bk.sd_cpp_args_mod,
"gguf_quantized_weight_types",
lambda path: seen.append(path) or weight_types,
)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cuda")
assert seen == ["/m/z.gguf"]
assert servers[-1].env is None
assert dict(b._state.child_env) == {}
@pytest.mark.parametrize(
"companions",
[
{"llm": ("/m/llm.gguf", frozenset({"Q4_K", "Q6_K"}))},
{"llm": ("/m/llm.gguf", frozenset({"Q8_0"})), "vae": ("/m/vae.gguf", frozenset({"Q5_K"}))},
{"llm": ("/m/llm.gguf", None)},
{"qwen2vl": ("/m/te.gguf", frozenset({"Q4_K"})), "llm_vision": ("/m/mm.gguf", frozenset())},
],
)
def test_a_q8_0_diffusion_gguf_takes_the_route_whatever_its_companions_hold(
monkeypatch, companions
):
# The route follows the diffusion GGUF: a k-quant / unreadable encoder or VAE GGUF no longer keeps it on MMQ.
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
types_by_path = {"/m/z.gguf": frozenset({"Q8_0"})}
types_by_path.update(dict(companions.values()))
seen: list = []
monkeypatch.setattr(
bk.sd_cpp_args_mod,
"gguf_quantized_weight_types",
lambda path: seen.append(path) or types_by_path[path],
)
paths = {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}
paths.update({kind: path for kind, (path, _types) in companions.items()})
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cuda", asset_paths = paths)
want = {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
assert servers[-1].env == want
assert dict(b._state.child_env) == want
assert seen == ["/m/z.gguf"]
def test_a_user_quant_cublas_value_reaches_sd_server_unchanged(monkeypatch):
monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
monkeypatch.setattr(
bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cuda")
assert servers[-1].env is None
def test_the_capability_probe_is_bounded_when_the_driver_stalls(monkeypatch):
import sys
import time
release = threading.Event()
cuda = types.SimpleNamespace(is_available = lambda: release.wait(30) or True)
fake_torch = types.SimpleNamespace(version = types.SimpleNamespace(hip = None), cuda = cuda)
monkeypatch.setitem(sys.modules, "torch", fake_torch)
start = time.monotonic()
try:
assert bk._torch_cuda_capabilities(None, timeout_s = 0.2) == []
finally:
release.set()
assert time.monotonic() - start < 5
def test_the_cublas_route_follows_a_deferred_install_onto_cuda(monkeypatch):
# Placed on the CPU bundle first; the deferred upgrade lands the CUDA build, so the committed env must follow.
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
monkeypatch.setattr(
bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
)
installed = {"accelerator": "cpu"}
monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed["accelerator"])
def _upgrade(self, server_binary, **_kw):
installed["accelerator"] = "cuda"
return server_binary
monkeypatch.setattr(SdCppDiffusionBackend, "_upgraded_or_refused", _upgrade)
monkeypatch.setattr(
SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "cuda")
)
monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cuda")
assert b._state.device == "cuda"
assert servers[-1].env == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
assert dict(b._state.child_env) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
@pytest.mark.parametrize(
"resolved,expected", [("CUDA1", {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}), (None, None)]
)
def test_an_unresolved_pin_judges_every_visible_card(monkeypatch, resolved, expected):
# Card 1 is an A100, card 0 (sd.cpp's default) an Ada card. Without the pin sd.cpp runs on card 0.
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
caps = {None: [(8, 9), (8, 0)], 0: [(8, 9)], 1: [(8, 0)]}
monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: list(caps[ordinal]))
monkeypatch.setattr(
bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
)
monkeypatch.setattr(bk, "sd_cpp_device_name_for_ordinal", lambda binary, ordinal: resolved)
monkeypatch.setattr(bk, "physical_card_name", lambda ordinal: (None, None))
monkeypatch.setattr(bk, "sd_cpp_device_named", lambda binary, name, position = None: None)
b = SdCppDiffusionBackend()
servers: list = []
_run_server_load(monkeypatch, b, servers, device = "cuda", gpu_ordinal = 1)
assert servers[-1].env == expected
assert dict(b._state.child_env) == (expected or {})