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
"""Unit tests for the sd-cli command builder: argv construction and the policy-to-flag mappings only."""
from __future__ import annotations
import pytest
from core.inference.diffusion_memory import (
OFFLOAD_GROUP,
OFFLOAD_MODEL,
OFFLOAD_NONE,
OFFLOAD_SEQUENTIAL,
)
from core.inference.sd_cpp_args import (
CPU_BACKEND_FLAGS,
SdCppGenParams,
SdCppModelFiles,
SdCppUpscaleParams,
SdCppVideoGenParams,
build_img_gen_request,
build_sd_cpp_command,
build_sd_cpp_server_command,
build_sd_cpp_upscale_command,
build_sd_cpp_video_command,
device_backend_flags,
is_ggml_unsupported_op_abort,
metal_text_encoder_flags,
native_speed_flags,
offload_flags,
text_encoder_flags_for_family,
)
def _pair(cmd: list[str], flag: str):
"""Value following ``flag`` in ``cmd``, or None if the flag is absent."""
return cmd[cmd.index(flag) + 1] if flag in cmd else None
def test_te_flags_by_family():
assert text_encoder_flags_for_family("z-image") == ("--llm",)
assert text_encoder_flags_for_family("qwen-image") == ("--qwen2vl",)
assert text_encoder_flags_for_family("flux.1") == ("--clip_l", "--t5xxl")
assert text_encoder_flags_for_family("flux.2-klein") == ("--llm",)
# Not --qwen2vl: 2.1 conditions on Qwen3-VL and the qwen2vl path adds Qwen2-VL preprocessing.
assert text_encoder_flags_for_family("qwen-image-2.1") == ("--llm",)
assert text_encoder_flags_for_family("unknown") == ()
# ── Metal text-encoder placement ────────────────────────────────────────────
import core.inference.sd_cpp_args as _sd_cpp_args_module
_REAL_PARAVIRTUAL_PROBE = _sd_cpp_args_module.metal_is_paravirtual
@pytest.fixture(autouse = True)
def _physical_metal(monkeypatch):
# The paravirtual probe shells out on darwin; every test here runs as physical Apple Silicon unless it says so.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
# Commands are built for a Linux host unless a test sets the platform, so a Mac runner gets the same
# commands as Linux (Metal drops direct conv and adds --clip-on-cpu).
monkeypatch.setattr("sys.platform", "linux")
# The real probe is cached and reads sysctl; follow the patched platform.machine() instead.
import platform
monkeypatch.setattr(
sd_cpp_args,
"apple_silicon_machine",
lambda: platform.machine().lower() in ("arm64", "aarch64"),
)
def test_metal_keeps_the_text_encoder_off_the_gpu(monkeypatch):
# ggml Metal aborts on non-contiguous RMS_NORM with no CPU fallback (exits -6 on macOS).
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
monkeypatch.setattr("sys.platform", "darwin")
assert metal_text_encoder_flags() == ["--clip-on-cpu"]
for other in ("linux", "win32"):
monkeypatch.setattr("sys.platform", other)
assert metal_text_encoder_flags() == []
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", "1")
assert metal_text_encoder_flags() == []
def test_metal_text_encoder_flag_reaches_both_command_builders(monkeypatch):
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
monkeypatch.setattr("sys.platform", "darwin")
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
server = build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
)
cli = build_sd_cpp_command(
binary = "sd-cli",
files = files,
params = SdCppGenParams(prompt = "x"),
output_path = "/o/x.png",
)
video = build_sd_cpp_video_command(
binary = "sd-cli",
files = SdCppModelFiles(
diffusion_model = "/m/h3.gguf",
vae = "/m/video.safetensors",
llm = "/m/qwen.gguf",
),
params = SdCppVideoGenParams(prompt = "x", width = 960, height = 544, num_frames = 124),
output_path = "/o/x.webm",
)
assert server.count("--clip-on-cpu") == 1
assert cli.count("--clip-on-cpu") == 1
assert video.count("--clip-on-cpu") == 1
dual = build_sd_cpp_server_command(
binary = "sd-server",
files = files,
host = "127.0.0.1",
port = 1234,
offload = offload_flags("model"),
)
assert dual.count("--clip-on-cpu") == 1
monkeypatch.setattr("sys.platform", "linux")
assert "--clip-on-cpu" not in build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
)
def test_paravirtual_metal_runs_the_whole_graph_on_the_cpu_backend(monkeypatch):
# The bundled ggml segfaults on a paravirtual Metal GPU, so a VM gets --backend cpu.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
assert metal_text_encoder_flags() == ["--backend", "cpu"]
# The encoder kill switch does not put a VM back on its GPU.
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", "1")
assert metal_text_encoder_flags() == ["--backend", "cpu"]
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU")
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
server = build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
)
cli = build_sd_cpp_command(
binary = "sd-cli", files = files, params = SdCppGenParams(prompt = "x"), output_path = "/o/x.png"
)
for argv in (server, cli):
i = argv.index("--backend")
assert argv[i + 1] == "cpu"
assert argv.count("--backend") == 1
assert "--clip-on-cpu" not in argv
# A low_vram policy that already offloads keeps its flags and still gets the CPU backend exactly once.
model = build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, offload = offload_flags("model")
)
assert model.count("--backend") == 1 and model[model.index("--backend") + 1] == "cpu"
# An explicit --backend pin in the offload flags wins; no dangling "cpu" argument is appended.
pinned = sd_cpp_args.metal_placement_flags(["--backend", "diffusion=MTL0,te=cpu,vae=MTL0"])
assert pinned == []
monkeypatch.setattr("sys.platform", "linux")
assert metal_text_encoder_flags() == []
def test_paravirtual_probe_is_darwin_only_and_survives_a_missing_probe(monkeypatch):
import builtins
import core.inference.sd_cpp_args as sd_cpp_args
probe = _REAL_PARAVIRTUAL_PROBE
probe.cache_clear()
monkeypatch.setattr("sys.platform", "linux")
assert probe() is False
probe.cache_clear()
monkeypatch.setattr("sys.platform", "darwin")
orig_import = builtins.__import__
def _no_llama(name, *args, **kwargs):
if name == "core.inference.llama_cpp":
raise ImportError("probe unavailable")
return orig_import(name, *args, **kwargs)
monkeypatch.setattr(builtins, "__import__", _no_llama)
assert probe() is False
probe.cache_clear()
assert sd_cpp_args.metal_is_paravirtual is not probe
# ── offload policy -> sd-cli flags ──────────────────────────────────────────
def test_native_speed_on_apple_metal_drops_direct_conv(monkeypatch):
# ggml-metal's direct CONV_2D trips the GPU watchdog; flash attention stays.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
assert native_speed_flags("default") == ["--diffusion-fa"]
assert native_speed_flags("max") == ["--diffusion-fa"]
assert native_speed_flags("off") == []
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
server = build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, native_speed = "default"
)
assert "--diffusion-fa" in server and "--diffusion-conv-direct" not in server
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
# Intel Macs ship a CPU-only build.
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
monkeypatch.setattr("platform.machine", lambda: "x86_64")
assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
def test_native_speed_keeps_direct_conv_on_a_forced_cpu_backend(monkeypatch):
# The CPU-backend restart and an explicit --backend cpu run on the CPU, where direct conv is the profile's win.
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
full = ["--diffusion-fa", "--diffusion-conv-direct"]
assert native_speed_flags("default", ["--backend", "cpu"]) == full
assert native_speed_flags("default", ["--backend", "diffusion=MTL0"]) == ["--diffusion-fa"]
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
restart = build_sd_cpp_server_command(
binary = "sd-server",
files = files,
host = "127.0.0.1",
port = 1234,
native_speed = "default",
extra_args = ["--backend", "cpu"],
)
assert "--diffusion-conv-direct" in restart
def test_engine_generate_keeps_direct_conv_on_a_forced_cpu_backend(monkeypatch):
from core.inference.sd_cpp_engine import SdCppEngine
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
captured = {}
eng = SdCppEngine(binary = "/x/sd-cli")
monkeypatch.setattr(eng, "_require_binary", lambda: "/x/sd-cli")
monkeypatch.setattr(eng, "_prepare_out", lambda p: p)
monkeypatch.setattr(eng, "_run", lambda cmd, *a, **k: captured.setdefault("cmd", cmd))
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
eng.generate(
files,
SdCppGenParams(prompt = "x"),
output_path = "/o/x.png",
native_speed = "default",
extra_args = ["--backend", "cpu"],
)
assert "--diffusion-conv-direct" in captured["cmd"]
def test_native_speed_honours_an_explicit_metal_pin_on_a_paravirtual_gpu(monkeypatch):
# An offload --backend pin suppresses the paravirtual CPU placement, so the graph is on Metal again.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
pin = ["--backend", "diffusion=MTL0,te=cpu,vae=MTL0"]
assert native_speed_flags("default", pin) == ["--diffusion-fa"]
assert native_speed_flags("default", ["--backend", "diffusion=cpu,te=cpu,vae=cpu"]) == [
"--diffusion-fa",
"--diffusion-conv-direct",
]
files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
server = build_sd_cpp_server_command(
binary = "sd-server",
files = files,
host = "127.0.0.1",
port = 1234,
offload = pin,
native_speed = "default",
)
assert "--diffusion-conv-direct" not in server
unpinned = build_sd_cpp_server_command(
binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, native_speed = "default"
)
assert "--diffusion-conv-direct" in unpinned
def test_metal_detection_does_not_trust_the_python_architecture(monkeypatch):
# An x86_64 Python under Rosetta on Apple Silicon still drives the Metal GPU.
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "x86_64")
monkeypatch.setattr(sd_cpp_args, "apple_silicon_machine", lambda: True)
assert native_speed_flags("default") == ["--diffusion-fa"]
# An explicit Metal pin is Metal whatever the machine reports.
monkeypatch.setattr(sd_cpp_args, "apple_silicon_machine", lambda: False)
assert native_speed_flags("default", ["--backend", "diffusion=MTL0"]) == ["--diffusion-fa"]
assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
def test_video_load_route_skips_the_video_claim_for_a_forced_cpu_h3_load():
import inspect
import routes.video as video_routes
source = inspect.getsource(video_routes)
guard = source.index("await asyncio.to_thread(forces_cpu_backend, device)")
branch = source.index("if forced_cpu:", guard)
# Neither acquires nor releases VIDEO: an old MPS model keeps its claim until the worker tears it down.
assert source[branch : source.index('elif device != "cpu":', branch)].strip() == (
"if forced_cpu:\n status_dict = await asyncio.to_thread(begin)"
)
# ``begin`` only re-checks the Always media gate under the arbiter lock; it takes no GPU claim.
begin_def = source.rindex("def begin():", 0, branch)
assert source[begin_def : source.index("\n\n", begin_def)].strip() == (
"def begin():\n"
" return begin_media_load(VIDEO, multi_model_mode, media_names, _begin_load)"
)
assert branch < source.index("return acquire_for_request(\n VIDEO,")
def test_partial_backend_specs_leave_the_diffusion_model_on_metal(monkeypatch):
# sd.cpp auto-fits unassigned modules, so te=cpu / vae=cpu alone still runs the denoiser on Metal.
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
fa_only = ["--diffusion-fa"]
full = ["--diffusion-fa", "--diffusion-conv-direct"]
assert native_speed_flags("default", ["--backend", "te=cpu"]) == fa_only
assert native_speed_flags("default", ["--backend", "vae=cpu,te=cpu"]) == fa_only
assert native_speed_flags("default", ["--backend", "diffusion=cpu"]) == full
# An explicit diffusion entry beats the bare default, as in sd.cpp.
assert (
native_speed_flags("default", ["--backend", "cpu", "--backend", "diffusion=MTL0"])
== fa_only
)
assert native_speed_flags("default", ["--backend", "MTL0,diffusion=cpu"]) == full
def test_forces_cpu_backend_only_for_a_paravirtual_mps_device(monkeypatch):
import core.inference.sd_cpp_args as sd_cpp_args
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
assert sd_cpp_args.forces_cpu_backend("mps") is True
assert sd_cpp_args.forces_cpu_backend("cuda") is False
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
assert sd_cpp_args.forces_cpu_backend("mps") is False
def test_image_load_route_skips_the_diffusion_claim_for_a_forced_cpu_native_load():
import inspect
import routes.inference as inference_routes
source = inspect.getsource(inference_routes)
start = source.index("off_torch = await asyncio.to_thread(off_torch_sd_cpp_device)")
window = source[start : start + 25000]
# Off the event loop: the paravirtual probe can shell out to sysctl / system_profiler.
guard = window.index("await asyncio.to_thread(forces_cpu_backend, device)")
assert window.index("activated = active_engine_name()") < guard < window.index("if needs_gpu:")
assert "needs_gpu = False" in window[guard : guard + 200]
def test_upscale_on_paravirtual_metal_runs_on_the_cpu_backend(monkeypatch):
import core.inference.sd_cpp_args as sd_cpp_args
params = SdCppUpscaleParams(input_image = "/i/in.png", upscale_model = "/m/esrgan.pth")
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
cmd = build_sd_cpp_upscale_command("sd-cli", params, output_path = "/o/out.png")
assert cmd.count("--backend") == 1 and cmd[cmd.index("--backend") + 1] == "cpu"
# An explicit caller --backend wins: no second, concatenated spec.
pinned = build_sd_cpp_upscale_command(
"sd-cli", params, output_path = "/o/out.png", extra_args = ["--backend", "MTL0"]
)
assert pinned.count("--backend") == 1 and pinned[-1] == "MTL0"
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
assert "--backend" not in build_sd_cpp_upscale_command(
"sd-cli", params, output_path = "/o/out.png"
)
def test_native_speed_flags():
assert native_speed_flags(None) == []
assert native_speed_flags("off") == []
assert native_speed_flags("") == []
# conv-direct: ~9% faster CPU sampling at identical RSS.
assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
assert native_speed_flags("max") == ["--diffusion-fa", "--diffusion-conv-direct"]
with pytest.raises(ValueError):
native_speed_flags("ludicrous")
def test_native_speed_flags_drop_conv_direct_on_vulkan_and_rocm(monkeypatch):
monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
monkeypatch.setattr(_sd_cpp_args_module, "_runs_on_apple_metal", lambda *_a, **_k: False)
fa_only = ["--diffusion-fa"]
full = ["--diffusion-fa", "--diffusion-conv-direct"]
for accel in ("vulkan", "rocm", "ROCm"):
assert native_speed_flags("default", [], accel) == fa_only
assert native_speed_flags("max", [], accel) == fa_only
for accel in ("cuda", "cpu", None):
assert native_speed_flags("default", [], accel) == full
assert (
native_speed_flags("default", ["--backend", "diffusion=Vulkan0,te=cpu"], "cuda") == fa_only
)
assert native_speed_flags("default", ["--backend", "diffusion=ROCm1"], None) == fa_only
assert native_speed_flags("default", ["--backend", "diffusion=CUDA0"], "vulkan") == full
assert native_speed_flags("default", ["--backend", "diffusion=cpu"], "vulkan") == full
monkeypatch.setenv("UNSLOTH_SD_CPP_CONV_DIRECT", "1")
assert native_speed_flags("default", [], "vulkan") == full
monkeypatch.setenv("UNSLOTH_SD_CPP_CONV_DIRECT", "0")
assert native_speed_flags("default", [], "cuda") == fa_only
def test_server_command_carries_accelerator(monkeypatch):
monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
monkeypatch.setattr(_sd_cpp_args_module, "_runs_on_apple_metal", lambda *_a, **_k: False)
files = SdCppModelFiles(diffusion_model = "/m/dit.gguf")
kw = dict(host = "127.0.0.1", port = 1, native_speed = "default")
assert "--diffusion-conv-direct" not in build_sd_cpp_server_command(
"sd-server", files, accelerator = "vulkan", **kw
)
assert "--diffusion-conv-direct" in build_sd_cpp_server_command(
"sd-server", files, accelerator = "cuda", **kw
)
def test_offload_none_is_empty():
assert offload_flags(OFFLOAD_NONE) == []
def test_offload_group_streams_with_flash_attention():
flags = offload_flags(OFFLOAD_GROUP)
assert "--offload-to-cpu" in flags
assert "--diffusion-fa" in flags
assert "--clip-on-cpu" not in flags
assert "--vae-on-cpu" not in flags
def test_offload_model_pushes_everything_to_cpu_and_tiles():
flags = offload_flags(OFFLOAD_MODEL)
for expected in (
"--offload-to-cpu",
"--clip-on-cpu",
"--vae-on-cpu",
"--vae-tiling",
"--diffusion-fa",
):
assert expected in flags
assert offload_flags(OFFLOAD_SEQUENTIAL) == flags
def test_offload_can_keep_the_vae_off_the_cpu_path():
"""H3 audio VAE asserts F16 on the CPU path, so only --vae-on-cpu is dropped under low_vram."""
for policy in (OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
flags = offload_flags(policy, vae_on_cpu = False)
assert "--vae-on-cpu" not in flags
for expected in ("--offload-to-cpu", "--clip-on-cpu", "--vae-tiling", "--diffusion-fa"):
assert expected in flags, f"{policy}: {expected} should survive"
assert "--vae-on-cpu" in offload_flags(OFFLOAD_MODEL)
assert offload_flags(OFFLOAD_GROUP, vae_on_cpu = False) == offload_flags(OFFLOAD_GROUP)
def test_offload_forced_flags_dedup():
flags = offload_flags(OFFLOAD_MODEL, vae_tiling = True, diffusion_fa = True)
assert flags.count("--vae-tiling") == 1
assert flags.count("--diffusion-fa") == 1
none_forced = offload_flags(OFFLOAD_NONE, vae_tiling = True, diffusion_fa = True)
assert none_forced == ["--diffusion-fa", "--vae-tiling"]
def test_build_zimage_command_minimal():
files = SdCppModelFiles(
diffusion_model = "/m/z.gguf",
vae = "/m/ae.sft",
llm = "/m/qwen3.gguf",
)
params = SdCppGenParams(prompt = "a cat", width = 512, height = 768, steps = 8, cfg_scale = 1.0, seed = 42)
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/out/x.png")
assert cmd[0] == "/bin/sd-cli"
assert _pair(cmd, "--mode") == "img_gen"
assert _pair(cmd, "--diffusion-model") == "/m/z.gguf"
assert _pair(cmd, "--vae") == "/m/ae.sft"
assert _pair(cmd, "--llm") == "/m/qwen3.gguf"
assert _pair(cmd, "--prompt") == "a cat"
assert _pair(cmd, "--width") == "512"
assert _pair(cmd, "--height") == "768"
assert _pair(cmd, "--steps") == "8"
assert _pair(cmd, "--cfg-scale") == "1"
assert _pair(cmd, "--seed") == "42"
assert _pair(cmd, "--output") == "/out/x.png"
assert "--t5xxl" not in cmd
assert "--qwen2vl" not in cmd
def test_build_flux1_dual_text_encoders():
files = SdCppModelFiles(
diffusion_model = "/m/flux.gguf",
vae = "/m/ae.sft",
clip_l = "/m/clip_l.sft",
t5xxl = "/m/t5.gguf",
)
params = SdCppGenParams(prompt = "x", guidance = 3.5)
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
assert _pair(cmd, "--clip_l") == "/m/clip_l.sft"
assert _pair(cmd, "--t5xxl") == "/m/t5.gguf"
assert _pair(cmd, "--guidance") == "3.5"
assert "--llm" not in cmd
def test_build_appends_offload_and_extra_args_last():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(prompt = "x")
off = offload_flags(OFFLOAD_GROUP)
cmd = build_sd_cpp_command(
"/bin/sd-cli",
files,
params,
output_path = "/o.png",
offload = off,
threads = 8,
verbose = True,
extra_args = ["--rng", "cuda"],
)
assert "--offload-to-cpu" in cmd
assert _pair(cmd, "--threads") == "8"
assert "-v" in cmd
assert cmd[-2:] == ["--rng", "cuda"]
def test_build_negative_prompt_and_batch():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(prompt = "x", negative_prompt = "blurry")
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
assert _pair(cmd, "--negative-prompt") == "blurry"
# The runner collects only the literal --output path, so a CLI batch would drop images.
with pytest.raises(ValueError, match = "single-image"):
build_sd_cpp_command(
"/bin/sd-cli",
files,
SdCppGenParams(prompt = "x", batch_count = 3),
output_path = "/o.png",
)
def test_build_omits_unset_optional_params():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(prompt = "x")
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
for flag in (
"--steps",
"--cfg-scale",
"--guidance",
"--seed",
"--sampling-method",
"--batch-count",
"--threads",
"-v",
):
assert flag not in cmd
def test_build_requires_diffusion_model_and_prompt():
with pytest.raises(ValueError):
build_sd_cpp_command(
"/bin/sd-cli",
SdCppModelFiles(diffusion_model = ""),
SdCppGenParams(prompt = "x"),
output_path = "/o.png",
)
with pytest.raises(ValueError):
build_sd_cpp_command(
"/bin/sd-cli",
SdCppModelFiles(diffusion_model = "/m/z.gguf"),
SdCppGenParams(prompt = " "),
output_path = "/o.png",
)
def test_build_img2img_adds_init_and_strength():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/ae.sft", llm = "/m/q.gguf")
params = SdCppGenParams(prompt = "make it autumn", init_img = "/in/src.png", strength = 0.6)
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
assert _pair(cmd, "--init-img") == "/in/src.png"
assert _pair(cmd, "--strength") == "0.6"
assert _pair(cmd, "--mode") == "img_gen"
def test_build_inpaint_adds_mask():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(prompt = "x", init_img = "/in/src.png", mask = "/in/mask.png", strength = 0.8)
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
assert _pair(cmd, "--mask") == "/in/mask.png"
assert _pair(cmd, "--init-img") == "/in/src.png"
def test_build_inpaint_mask_without_init_img_rejected():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(prompt = "x", mask = "/in/mask.png")
with pytest.raises(ValueError, match = "init_img is required"):
build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
def test_build_rejects_none_prompt():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
with pytest.raises(ValueError, match = "prompt is required"):
build_sd_cpp_command(
"/bin/sd-cli", files, SdCppGenParams(prompt = None), output_path = "/o.png"
)
def test_build_edit_repeats_ref_image():
files = SdCppModelFiles(diffusion_model = "/m/flux.gguf")
params = SdCppGenParams(prompt = "add a hat", ref_images = ("/r/a.png", "/r/b.png"))
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
idxs = [i for i, t in enumerate(cmd) if t == "--ref-image"]
assert len(idxs) == 2
assert [cmd[i + 1] for i in idxs] == ["/r/a.png", "/r/b.png"]
def test_img2img_unset_dims_lets_sdcpp_derive_from_source():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_command(
"/bin/sd-cli",
files,
SdCppGenParams(prompt = "x", init_img = "/in/src.png"),
output_path = "/o.png",
)
assert "--width" not in cmd and "--height" not in cmd
cmd2 = build_sd_cpp_command(
"/bin/sd-cli",
files,
SdCppGenParams(prompt = "x", ref_images = ("/r/a.png",)),
output_path = "/o.png",
)
assert "--width" not in cmd2 and "--height" not in cmd2
def test_img2img_explicit_dims_are_emitted():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_command(
"/bin/sd-cli",
files,
SdCppGenParams(prompt = "x", init_img = "/in/src.png", width = 768, height = 512),
output_path = "/o.png",
)
assert _pair(cmd, "--width") == "768" and _pair(cmd, "--height") == "512"
def test_txt2img_unset_dims_keep_1024_default():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_command(
"/bin/sd-cli", files, SdCppGenParams(prompt = "x"), output_path = "/o.png"
)
assert _pair(cmd, "--width") == "1024" and _pair(cmd, "--height") == "1024"
def test_build_lora_dir_and_apply_mode():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
params = SdCppGenParams(
prompt = "a portrait <lora:mystyle:0.8>",
lora_dir = "/loras",
lora_apply_mode = "at_runtime",
)
cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
assert _pair(cmd, "--lora-model-dir") == "/loras"
assert _pair(cmd, "--lora-apply-mode") == "at_runtime"
assert _pair(cmd, "--prompt") == "a portrait <lora:mystyle:0.8>"
def test_txt2img_omits_image_conditioning_flags():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_command(
"/bin/sd-cli", files, SdCppGenParams(prompt = "x"), output_path = "/o.png"
)
for flag in ("--init-img", "--strength", "--mask", "--ref-image", "--lora-model-dir"):
assert flag not in cmd
def test_build_upscale_command():
params = SdCppUpscaleParams(
input_image = "/in/small.png", upscale_model = "/m/esrgan.pth", repeats = 2
)
cmd = build_sd_cpp_upscale_command("/bin/sd-cli", params, output_path = "/out/big.png")
assert _pair(cmd, "--mode") == "upscale"
assert _pair(cmd, "--init-img") == "/in/small.png"
assert _pair(cmd, "--upscale-model") == "/m/esrgan.pth"
assert _pair(cmd, "--upscale-repeats") == "2"
assert _pair(cmd, "--output") == "/out/big.png"
assert "--prompt" not in cmd and "--llm" not in cmd
def test_build_upscale_rejects_non_positive_repeats():
with pytest.raises(ValueError, match = "repeats"):
build_sd_cpp_upscale_command(
"/bin/sd-cli",
SdCppUpscaleParams(input_image = "/i.png", upscale_model = "/m/e.pth", repeats = 0),
output_path = "/o.png",
)
def test_build_upscale_default_repeats_omits_flag():
cmd = build_sd_cpp_upscale_command(
"/bin/sd-cli",
SdCppUpscaleParams(input_image = "/i.png", upscale_model = "/m/e.pth"),
output_path = "/o.png",
)
assert "--upscale-repeats" not in cmd
def test_build_upscale_requires_input_and_model():
with pytest.raises(ValueError):
build_sd_cpp_upscale_command(
"/bin/sd-cli",
SdCppUpscaleParams(input_image = "", upscale_model = "/m/e.pth"),
output_path = "/o.png",
)
with pytest.raises(ValueError):
build_sd_cpp_upscale_command(
"/bin/sd-cli",
SdCppUpscaleParams(input_image = "/i.png", upscale_model = ""),
output_path = "/o.png",
)
def test_server_command_has_model_and_listen_but_no_request_params():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/ae.sft", llm = "/m/q.gguf")
cmd = build_sd_cpp_server_command(
"/bin/sd-server", files, host = "127.0.0.1", port = 5678, vae_format = "flux2"
)
assert _pair(cmd, "--diffusion-model") == "/m/z.gguf"
assert _pair(cmd, "--vae") == "/m/ae.sft"
assert _pair(cmd, "--llm") == "/m/q.gguf"
assert _pair(cmd, "--vae-format") == "flux2"
assert _pair(cmd, "--listen-ip") == "127.0.0.1"
assert _pair(cmd, "--listen-port") == "5678"
for flag in (
"--prompt",
"--seed",
"--steps",
"--cfg-scale",
"--guidance",
"--width",
"--height",
"--batch-count",
):
assert flag not in cmd
def test_server_command_maps_offload_and_speed_and_dedupes():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_server_command(
"/bin/sd-server",
files,
host = "127.0.0.1",
port = 1,
offload = ["--offload-to-cpu", "--diffusion-fa"],
native_speed = "default",
threads = 8,
)
assert _pair(cmd, "--threads") == "8"
assert cmd.count("--diffusion-fa") == 1
assert "--offload-to-cpu" in cmd
def test_server_command_scratch_dir_expands_to_lora_upscaler_embd():
files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
cmd = build_sd_cpp_server_command(
"/bin/sd-server", files, host = "127.0.0.1", port = 1, scratch_dir = "/tmp/scratch"
)
assert _pair(cmd, "--lora-model-dir") == "/tmp/scratch"
assert _pair(cmd, "--hires-upscalers-dir") == "/tmp/scratch"
assert _pair(cmd, "--embd-dir") == "/tmp/scratch"
bare = build_sd_cpp_server_command("/bin/sd-server", files, host = "127.0.0.1", port = 1)
assert "--lora-model-dir" not in bare and "--hires-upscalers-dir" not in bare
def test_server_command_requires_diffusion_model():
with pytest.raises(ValueError):
build_sd_cpp_server_command(
"/bin/sd-server", SdCppModelFiles(diffusion_model = ""), host = "127.0.0.1", port = 1
)
def test_img_gen_request_maps_core_fields():
req = build_img_gen_request(
prompt = "a fox",
negative_prompt = "blurry",
width = 512,
height = 768,
steps = 8,
seed = 42,
batch_count = 3,
sample_method = "euler",
cfg_scale = 4.0,
)
assert req["prompt"] == "a fox" and req["negative_prompt"] == "blurry"
assert req["width"] == 512 and req["height"] == 768
assert req["seed"] == 42 and req["batch_count"] == 3
assert req["sample_params"]["sample_steps"] == 8
assert req["sample_params"]["sample_method"] == "euler"
assert req["sample_params"]["guidance"]["txt_cfg"] == 4.0
assert req["output_format"] == "png"
def test_img_gen_request_flux_uses_distilled_guidance():
req = build_img_gen_request(prompt = "x", steps = 4, distilled_guidance = 3.5, flow_shift = 3.0)
g = req["sample_params"]["guidance"]
assert g["distilled_guidance"] == 3.5
assert "txt_cfg" not in g
assert req["sample_params"]["flow_shift"] == 3.0
def test_img_gen_request_requires_prompt():
with pytest.raises(ValueError):
build_img_gen_request(prompt = " ", steps = 4)
def test_ggml_unsupported_op_abort_is_recognised_only_with_both_markers():
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"
)
assert is_ggml_unsupported_op_abort(abort) is True
assert (
is_ggml_unsupported_op_abort("error: unsupported op 'RMS_NORM'\nggml_abort + 156") is True
)
assert is_ggml_unsupported_op_abort("unsupported op 'MUL_MAT'") is False
assert is_ggml_unsupported_op_abort("ggml_abort + 156") is False
assert is_ggml_unsupported_op_abort("process exited, code -9") is False
assert is_ggml_unsupported_op_abort("") is False
def test_server_command_appends_extra_args_last():
# The abort rescue passes --backend cpu as extra_args and sd.cpp is last-wins.
cmd = build_sd_cpp_server_command(
"/x/sd-server",
SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/vae.sft"),
host = "127.0.0.1",
port = 1234,
native_speed = "default",
extra_args = list(CPU_BACKEND_FLAGS),
)
assert cmd[-2:] == ["--backend", "cpu"]
assert cmd[0] == "/x/sd-server"
def test_minimax_h3_video_command_has_all_joint_av_components():
files = SdCppModelFiles(
diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
vae = "/m/video.safetensors",
audio_vae = "/m/audio.safetensors",
llm = "/m/qwen.gguf",
)
cmd = build_sd_cpp_video_command(
"/bin/sd-cli",
files,
SdCppVideoGenParams(
prompt = "a fox runs through snow",
width = 960,
height = 544,
num_frames = 124,
fps = 24,
steps = 30,
seed = 42,
),
output_path = "/out/result.webm",
offload = ["--diffusion-fa", "--offload-to-cpu"],
)
assert _pair(cmd, "--mode") == "vid_gen"
assert _pair(cmd, "--audio-vae") == "/m/audio.safetensors"
assert _pair(cmd, "--llm") == "/m/qwen.gguf"
assert _pair(cmd, "--video-frames") == "124"
assert _pair(cmd, "--fps") == "24"
assert _pair(cmd, "--cfg-scale") == "1"
assert "--rng" in cmd and _pair(cmd, "--rng") == "cpu"
assert cmd[-2:] == ["--diffusion-fa", "--offload-to-cpu"]
def test_video_build_appends_extra_args_verbatim_and_last():
"""Video build appends extra_args verbatim and last, so --rng cuda overrides the builder's default."""
files = SdCppModelFiles(
diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
vae = "/m/video.safetensors",
audio_vae = "/m/audio.safetensors",
llm = "/m/qwen.gguf",
)
cmd = build_sd_cpp_video_command(
"/bin/sd-cli",
files,
SdCppVideoGenParams(
prompt = "a fox runs through snow",
width = 960,
height = 544,
num_frames = 124,
fps = 24,
seed = 1,
),
output_path = "/o.webm",
extra_args = ["--rng", "cuda"],
)
assert cmd[-2:] == ["--rng", "cuda"]
assert cmd[-1] != "cuda" or cmd[-2] == "--rng"
assert cmd.count("--rng") == 2
def _h3_video_cmd(**params):
return build_sd_cpp_video_command(
"/bin/sd-cli",
SdCppModelFiles(
diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
vae = "/m/video.safetensors",
audio_vae = "/m/audio.safetensors",
llm = "/m/qwen.gguf",
),
SdCppVideoGenParams(
prompt = "a fox runs through snow",
width = 960,
height = 544,
num_frames = 124,
**params,
),
output_path = "/out/result.webm",
)
def test_minimax_h3_video_command_omits_keyframe_flags_for_text_only():
cmd = _h3_video_cmd()
assert "--init-img" not in cmd
assert "--end-img" not in cmd
def test_minimax_h3_video_command_carries_each_keyframe():
assert _pair(_h3_video_cmd(init_img = "/k/first.png"), "--init-img") == "/k/first.png"
assert "--end-img" not in _h3_video_cmd(init_img = "/k/first.png")
end_only = _h3_video_cmd(end_img = "/k/last.png")
assert _pair(end_only, "--end-img") == "/k/last.png"
assert "--init-img" not in end_only
both = _h3_video_cmd(init_img = "/k/first.png", end_img = "/k/last.png")
assert _pair(both, "--init-img") == "/k/first.png"
assert _pair(both, "--end-img") == "/k/last.png"
def test_minimax_h3_video_command_packs_references_in_reading_order():
cmd = _h3_video_cmd(
ref_images = ("/r/cat.png", "/r/style.png"),
ref_videos = ("/r/motion", "/r/orbit"),
ref_video_audios = ("/r/motion.wav",),
ref_audios = ("/r/voice.wav",),
)
assert [c for c in cmd if c.startswith("--ref")] == [
"--ref-image",
"--ref-image",
"--ref-video",
"--ref-video",
"--ref-video-audio",
"--ref-audio",
]
assert cmd[cmd.index("--ref-image") + 1] == "/r/cat.png"
assert cmd[cmd.index("--ref-video") + 1] == "/r/motion"
assert cmd[cmd.index("--ref-audio") + 1] == "/r/voice.wav"
def test_minimax_h3_video_command_refuses_keyframes_with_references():
with pytest.raises(ValueError, match = "different denoiser partitions"):
_h3_video_cmd(init_img = "/k/first.png", ref_images = ("/r/cat.png",))
with pytest.raises(ValueError, match = "different denoiser partitions"):
_h3_video_cmd(end_img = "/k/last.png", ref_audios = ("/r/voice.wav",))
def test_minimax_h3_video_command_refuses_an_unpairable_soundtrack():
with pytest.raises(ValueError, match = "reference video to pair with"):
_h3_video_cmd(ref_videos = ("/r/motion",), ref_video_audios = ("/r/a.wav", "/r/b.wav"))
def test_minimax_h3_video_command_carries_the_video_flow_shift():
# sd.cpp derives the audio schedule against a hardcoded 3.0, so only the video shift is a flag.
assert "--flow-shift" not in _h3_video_cmd()
assert _pair(_h3_video_cmd(flow_shift = 8.5), "--flow-shift") == "8.5"
assert _pair(_h3_video_cmd(flow_shift = 12.0), "--flow-shift") == "12"
def test_device_backend_flags_pin_all_three_graphs():
# sd.cpp defaults to ordinal 0 unless told otherwise, so a selection only takes effect through --backend.
assert device_backend_flags("CUDA1") == ["--backend", "diffusion=CUDA1,te=CUDA1,vae=CUDA1"]
assert device_backend_flags(None) == []
assert device_backend_flags("") == []
def test_device_backend_flags_leave_the_offloaded_modules_on_the_cpu():
# --clip-on-cpu / --vae-on-cpu ARE te=cpu / vae=cpu and the parser is last-wins, so pinning them would undo low_vram.
low_vram = offload_flags(OFFLOAD_MODEL)
assert "--clip-on-cpu" in low_vram and "--vae-on-cpu" in low_vram
assert device_backend_flags("CUDA1", low_vram) == [
"--backend",
"diffusion=CUDA1,te=cpu,vae=cpu",
]
assert device_backend_flags("CUDA1", offload_flags(OFFLOAD_GROUP)) == [
"--backend",
"diffusion=CUDA1,te=CUDA1,vae=CUDA1",
]
def test_device_backend_flags_are_appended_not_folded_into_the_policy():
# The policy list must stay unchanged: a deferred install can replace the build later.
policy = offload_flags(OFFLOAD_GROUP)
before = list(policy)
device_backend_flags("CUDA1", policy)
assert policy == before
def test_conv_direct_force_on_reaches_apple_metal(monkeypatch):
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("platform.machine", lambda: "arm64")
monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
assert native_speed_flags("default") == ["--diffusion-fa"]
monkeypatch.setenv(
"UNSLOTH_SD_CPP_CONV_DIRECT", "1"
) # an explicit force beats the Metal default
assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
# ── Metal mmap (leejet/stable-diffusion.cpp#2037) ───────────────────────────
def _managed_install(tmp_path, tag):
import json
root = tmp_path / "stable-diffusion.cpp"
(root / "bin").mkdir(parents = True)
binary = root / "bin" / "sd-cli"
binary.write_text("")
(root / ".unsloth-sd-cpp-install.json").write_text(
json.dumps({"tag": tag, "accelerator": "cpu"})
)
_sd_cpp_args_module._installed_sd_cpp_tag.cache_clear()
return str(binary)
def _all_builders(binary, extra_args = None):
files = SdCppModelFiles(
diffusion_model = "/m/model.gguf", vae = "/m/vae.safetensors", llm = "/m/te.gguf"
)
yield build_sd_cpp_command(
binary, files, SdCppGenParams(prompt = "a cat"), output_path = "/o.png", extra_args = extra_args
)
yield build_sd_cpp_video_command(
binary,
files,
SdCppVideoGenParams(prompt = "a cat", width = 256, height = 256, num_frames = 5),
output_path = "/o.webm",
extra_args = extra_args,
)
yield build_sd_cpp_server_command(
binary, files, host = "127.0.0.1", port = 1, extra_args = extra_args
)
@pytest.mark.parametrize(
"tag, expected",
[
("master-982-0518b34-u67cba2c", True), # the pinned bundle
("master-982-0518b34-ueb0e729", True), # the previous pin
("master-982-0518b34-uba6ac30", True), # an older pin
("master-982-0518b34-uaba3a1c", True), # an older pin
("master-982-0518b34-ud331c66", True), # an older pin
("master-968-8cd731e-ubdb47d1", True), # the pin before it
("master-951-f89d9b1-uafac7a7", True), # an older pin
("master-907-500ef5f", True), # the build that merged #2037
("master-906-abcdef0", False), # --mmap there hands Metal an unaddressable CPU buffer
("master-813-bfbef5b-u6321a69", False),
("b1234", False), # undatable: fail closed
],
)
def test_mmap_rides_every_macos_builder_from_the_metal_mmap_build(
monkeypatch, tmp_path, tag, expected
):
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
monkeypatch.setattr("sys.platform", "darwin")
binary = _managed_install(tmp_path, tag)
for cmd in _all_builders(binary):
assert ("--mmap" in cmd) is expected
assert cmd.count("--mmap") <= 1
def test_mmap_is_macos_only_and_never_on_an_unrecorded_binary(monkeypatch, tmp_path):
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
binary = _managed_install(tmp_path, "master-951-f89d9b1-uafac7a7")
for other in ("linux", "win32"):
monkeypatch.setattr("sys.platform", other)
assert all("--mmap" not in cmd for cmd in _all_builders(binary))
monkeypatch.setattr("sys.platform", "darwin")
stray = tmp_path / "elsewhere" / "sd-cli"
stray.parent.mkdir()
stray.write_text("")
assert all("--mmap" not in cmd for cmd in _all_builders(str(stray)))
def test_mmap_env_override_and_no_duplicate(monkeypatch, tmp_path):
monkeypatch.setattr("sys.platform", "darwin")
new = _managed_install(tmp_path, "master-951-f89d9b1-uafac7a7")
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")
assert all("--mmap" not in cmd for cmd in _all_builders(new))
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")
assert all("--mmap" in cmd for cmd in _all_builders("/usr/local/bin/sd-cli"))
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP")
for cmd in _all_builders(new, extra_args = ["--mmap"]):
assert cmd.count("--mmap") == 1
# ── CPU mmap (repack-aware builds) ──────────────────────────────────────────
_REPACK_HELP = " --mmap whether to memory-map model (CPU: weights the CPU repacks are still loaded and repacked)\n"
_OLD_HELP = " --mmap whether to memory-map model\n"
def _cpu_install(
tmp_path,
monkeypatch,
help_text,
accelerator = "cpu",
):
import json
import core.inference.sd_cpp_backend as backend
root = tmp_path / f"sd-{accelerator}-{abs(hash(help_text)) % 10**6}"
(root / "bin").mkdir(parents = True)
binary = root / "bin" / "sd-cli"
binary.write_text("")
(root / ".unsloth-sd-cpp-install.json").write_text(
json.dumps({"tag": "master-982-0518b34-u67cba2c", "accelerator": accelerator})
)
for fn in (
_sd_cpp_args_module._installed_sd_cpp_tag,
_sd_cpp_args_module._installed_sd_cpp_accelerator,
_sd_cpp_args_module._cpu_mmap_repack_in_help,
):
fn.cache_clear()
monkeypatch.setattr(backend, "_sd_cpp_probe_output", lambda b, *a, **k: help_text)
return str(binary)
@pytest.mark.parametrize("platform", ["linux", "win32"])
def test_cpu_mmap_on_repack_aware_cpu_builds_only(monkeypatch, tmp_path, platform):
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
monkeypatch.setattr("sys.platform", platform)
new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
for cmd in _all_builders(new):
assert cmd.count("--mmap") == 1
# The pinned build maps repackable weights and runs them unrepacked: never sent there.
old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
assert all("--mmap" not in cmd for cmd in _all_builders(old))
for accel in ("cuda", "vulkan", "rocm"):
gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = accel)
assert all("--mmap" not in cmd for cmd in _all_builders(gpu))
def test_cpu_mmap_follows_an_explicit_backend(monkeypatch, tmp_path):
from core.inference.sd_cpp_args import mmap_flags
monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
monkeypatch.setattr("sys.platform", "linux")
gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = "vulkan")
assert mmap_flags(gpu, None, ["--backend", "cpu"]) == ["--mmap"]
cpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
assert mmap_flags(cpu, None, ["--backend", "diffusion=vulkan0"]) == []
assert mmap_flags(cpu, ["--mmap"], None) == []
assert mmap_flags(None, None, None) == []
# an unreadable / unprobeable binary fails closed
assert (
_cpu_install(tmp_path, monkeypatch, None)
and mmap_flags(str(tmp_path / "missing" / "sd-cli")) == []
)
def test_cpu_mmap_env_override(monkeypatch, tmp_path):
from core.inference.sd_cpp_args import mmap_flags
monkeypatch.setattr("sys.platform", "linux")
new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")
assert mmap_flags(new) == []
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")
old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
assert mmap_flags(old) == ["--mmap"]
@pytest.mark.parametrize(
"ccs,expected",
[
([(8, 0)], "1024"), # A100
([(9, 0)], "1024"), # H100
([(10, 0)], "1024"), # B200
([(10, 3)], "1024"),
([(12, 0)], "4096"), # RTX PRO 6000 / RTX 50
([(8, 9)], None), # L4 / RTX 40: MMQ stays faster
([(8, 6)], None),
([(8, 7)], None),
([(7, 5)], None),
([(11, 0)], None),
([(8, 0), (10, 0)], "1024"),
([(8, 0), (8, 9)], None), # sd.cpp may land on either card
([(10, 0), (12, 0)], None),
([], None),
],
)
def test_quant_cublas_env_follows_the_measured_architectures(ccs, expected):
env = _sd_cpp_args_module.quant_cublas_env(ccs, environ = {}, weight_types = frozenset({"Q8_0"}))
assert env == ({} if expected is None else {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": expected})
@pytest.mark.parametrize("user_value", ["0", "512"])
def test_quant_cublas_env_never_overrides_the_user(user_value):
environ = {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": user_value}
assert (
_sd_cpp_args_module.quant_cublas_env(
[(10, 0)], environ = environ, weight_types = frozenset({"Q8_0"})
)
== {}
)
@pytest.mark.parametrize(
"weight_types,expected",
[
(frozenset({"Q8_0"}), "1024"),
(frozenset({"Q4_K"}), None), # k-quants keep MMQ
(frozenset({"Q4_K", "Q5_K"}), None),
(frozenset({"Q8_0", "Q4_K"}), None), # a mixed file would route its k-quants too
(frozenset({"Q4_0"}), None),
(frozenset(), None), # unquantized: nothing to route
(None, None), # unknown (safetensors, unreadable)
],
)
def test_quant_cublas_env_only_for_q8_0_diffusion_ggufs(weight_types, expected):
env = _sd_cpp_args_module.quant_cublas_env([(10, 0)], environ = {}, weight_types = weight_types)
assert env == ({} if expected is None else {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": expected})
def test_gguf_quantized_weight_types_reads_the_tensor_table(tmp_path):
gguf = pytest.importorskip("gguf")
import numpy as np
def write(name, tensors):
path = tmp_path / name
w = gguf.GGUFWriter(str(path), "test")
for tname, arr, qtype in tensors:
if qtype is None:
w.add_tensor(tname, arr)
elif arr is None: # gguf-py cannot quantize k-quants: write zeroed blocks of that type
blocks = np.zeros((4, gguf.GGML_QUANT_SIZES[qtype][1]), dtype = np.uint8)
w.add_tensor(tname, blocks, raw_dtype = qtype)
else:
w.add_tensor(tname, gguf.quants.quantize(arr, qtype), raw_dtype = qtype)
w.write_header_to_file()
w.write_kv_data_to_file()
w.write_tensors_to_file()
w.close()
return str(path)
x = np.ones((4, 256), dtype = np.float32)
q8 = write(
"q8.gguf",
[("a", x, gguf.GGMLQuantizationType.Q8_0), ("n", np.ones(4, dtype = np.float32), None)],
)
mixed = write(
"mixed.gguf",
[("a", x, gguf.GGMLQuantizationType.Q8_0), ("b", x, gguf.GGMLQuantizationType.Q4_0)],
)
types_of = _sd_cpp_args_module.gguf_quantized_weight_types
assert types_of(q8) == frozenset({"Q8_0"})
assert types_of(mixed) == frozenset({"Q8_0", "Q4_0"})
assert types_of(str(tmp_path / "missing.gguf")) is None
assert types_of(str(tmp_path / "model.safetensors")) is None
assert types_of(None) is None
k_quant = write("te_q4k.gguf", [("w", None, gguf.GGMLQuantizationType.Q4_K)])
assert types_of(k_quant) == frozenset({"Q4_K"})
def route(path):
return _sd_cpp_args_module.quant_cublas_env(
[(10, 0)], environ = {}, weight_types = types_of(path)
)
assert route(q8) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
assert route(mixed) == {}
assert route(k_quant) == {}
assert route(str(tmp_path / "missing.gguf")) == {}