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
Studio: sd.cpp on Macs, CPU backend on a paravirtual GPU and no direct conv on Metal (#13369)
Daniel Han0464be9dade0
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.pyindex 4734552bfbb..3548fda6687 100644--- a/studio/backend/core/inference/sd_cpp_args.py+++ b/studio/backend/core/inference/sd_cpp_args.py@@ -13,6 +13,7 @@ one knob drives both engines. Ref: sd.cpp ``examples/cli`` and ``docs/z_image.mdfrom __future__ import annotations+import functoolsfrom collections.abc import Sequencefrom dataclasses import dataclass, fieldfrom typing import Optional@@ -136,52 +137,141 @@ class SdCppUpscaleParams:# Native (sd.cpp) speed profiles, the engine-side analogue of diffusion_speed. off: nothing. default: --diffusion-fa +-# --diffusion-conv-direct (numerically exact; direct conv took z-image Q8_0 sampling 56.1 -> 51.3 s). max keeps it-# (profiles chain).+# --diffusion-conv-direct (numerically exact), except Apple Metal keeps only --diffusion-fa. max keeps it (profiles chain).NATIVE_SPEED_OFF = "off"NATIVE_SPEED_DEFAULT = "default"NATIVE_SPEED_MAX = "max"NATIVE_SPEED_MODES = (NATIVE_SPEED_OFF, NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX)-def native_speed_flags(speed_mode: Optional[str]) -> list[str]:+def native_speed_flags(+ speed_mode: Optional[str], backend_args: Optional[Sequence[str]] = None+) -> list[str]:"""sd-cli speed flags for a native speed mode (empty for off / None). Separate from offload:- ``--diffusion-fa`` is a win in its own right. De-duplicated against offload at the call site."""+ ``--diffusion-fa`` is a win in its own right. De-duplicated against offload at the call site.+ ``backend_args``: the other argv flags, whose ``--backend`` decides whether the graph runs on Metal."""mode = (speed_mode or NATIVE_SPEED_OFF).strip().lower()if mode in ("", NATIVE_SPEED_OFF):return []if mode in (NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX):+ if _runs_on_apple_metal(backend_args or ()):+ return ["--diffusion-fa"]return ["--diffusion-fa", "--diffusion-conv-direct"]raise ValueError(f"native speed_mode must be one of {NATIVE_SPEED_MODES}, got '{speed_mode}'")+def _diffusion_backend(specs: Sequence[str]) -> Optional[str]:+ """The backend the diffusion module gets from ``--backend`` specs: ``diffusion=`` beats a bare default; None = auto-fit."""+ explicit = default = None+ for spec in specs:+ for part in str(spec).split(","):+ key, sep, value = part.strip().partition("=")+ if not sep:+ default = key or default+ elif key.strip().lower() == "diffusion":+ explicit = value.strip()+ return explicit or default+++def _runs_on_apple_metal(backend_args: Sequence[str] = ()) -> bool:+ """True when sd.cpp runs the diffusion model on Apple Metal (macOS; an explicit ``--backend`` for it decides,+ else an Apple Silicon machine whose GPU is not paravirtual).++ Direct conv is not used there: ggml-metal's CONV_2D trips the GPU watchdog on an SD1.5 UNet."""+ import sys++ if sys.platform != "darwin":+ return False+ args = list(backend_args)+ target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])+ if target is not None:+ return target.lower() != "cpu"+ return apple_silicon_machine() and not metal_is_paravirtual()++[email protected]_cache(maxsize = 1)+def apple_silicon_machine() -> bool:+ """True on an Apple Silicon Mac, including an x86_64 Python under Rosetta (``hw.optional.arm64``, as install.sh)."""+ import platform+ import sys++ if sys.platform != "darwin":+ return False+ if platform.machine().lower() in ("arm64", "aarch64"):+ return True+ try:+ import ctypes+ import ctypes.util++ libc = ctypes.CDLL(ctypes.util.find_library("c"))+ value = ctypes.c_int(0)+ size = ctypes.c_size_t(ctypes.sizeof(value))+ if (+ libc.sysctlbyname(+ b"hw.optional.arm64", ctypes.byref(value), ctypes.byref(size), None, 0+ )+ == 0+ ):+ return value.value == 1+ except Exception: # noqa: BLE001 -- no answer means an Intel Mac+ pass+ return False+++def forces_cpu_backend(device: Optional[str]) -> bool:+ """True when an sd.cpp run on resolved ``device`` is placed on the CPU backend (a paravirtual Mac GPU)."""+ return device == "mps" and metal_is_paravirtual()++# Kill switch for the Metal text-encoder placement below (1/true keeps the encoder on Metal)._METAL_TE_ON_GPU_ENV = "UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU"[email protected]_cache(maxsize = 1)+def metal_is_paravirtual() -> bool:+ """True when this Mac's Metal device is Apple's paravirtual GPU (a macOS VM). Reuses the llama.cpp probe."""+ import sys++ if sys.platform != "darwin":+ return False+ try:+ from core.inference.llama_cpp import _metal_device_is_paravirtual+ except Exception: # noqa: BLE001 -- no probe means no evidence of a VM+ return False+ try:+ return bool(_metal_device_is_paravirtual())+ except Exception: # noqa: BLE001+ return False++def metal_text_encoder_flags() -> list[str]:- """Keep the TEXT ENCODER on CPU when sd.cpp runs on Apple Metal, else nothing.-- ggml's Metal backend gates RMS_NORM on contiguous rows and calls ``GGML_ABORT`` when that does- not hold, with no per-op CPU fallback, so an LLM text encoder (Qwen3 for FLUX.2 / Z-Image, T5- for FLUX.1) takes the whole sd-server process down mid-generation:- ggml_metal_op_encode_impl: error: unsupported op 'RMS_NORM' -> ggml_abort- LLMEmbedder::encode_prompt -> LLMRunner::compute -> GGMLRunner::compute-- Observed on macos-14 arm64 with FLUX.2-klein-4B Q2_K: the model loads on ``mps`` and the first- generation dies with exit code -6. The encoder runs once per prompt while the DiT runs every- step, so pinning only the encoder keeps Metal for the part that matters. Set- ``UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU=1`` to opt back in once ggml grows the kernel."""+ """Placement flags for sd.cpp on Apple Metal, else nothing.++ A paravirtual GPU gets ``--backend cpu``: the bundled ggml segfaults there on CPU-fallback buffers. Otherwise the+ text encoder stays on the CPU (``--clip-on-cpu``) since ggml-metal can abort an LLM encoder;+ ``UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU=1`` keeps it on Metal."""import osimport sysif sys.platform != "darwin":return []+ if metal_is_paravirtual():+ return list(CPU_BACKEND_FLAGS)if os.environ.get(_METAL_TE_ON_GPU_ENV, "").strip().lower() in ("1", "true", "yes", "on"):return []return ["--clip-on-cpu"]+def metal_placement_flags(offload: Sequence[str]) -> list[str]:+ """``metal_text_encoder_flags()`` minus what ``offload`` already says.++ ``--backend cpu`` is a flag pair: per-item filtering would leave a dangling ``cpu``, so an explicit pin drops it."""+ flags = metal_text_encoder_flags()+ if flags == list(CPU_BACKEND_FLAGS):+ return [] if "--backend" in offload else flags+ return [f for f in flags if f not in offload]++# Everything on the CPU backend. sd.cpp prefers GPU -> integrated GPU -> CPU and only `--backend` changes which# backend EXECUTES the graph (`--offload-to-cpu` moves parameters, not compute), so this is the one flag that removes# ggml-metal entirely.@@ -392,7 +482,7 @@ def build_sd_cpp_command(offload = list(offload or [])if offload:cmd += offload- cmd += [f for f in metal_text_encoder_flags() if f not in offload]+ cmd += metal_placement_flags(offload)if verbose:cmd += ["-v"]if extra_args:@@ -484,7 +574,7 @@ def build_sd_cpp_video_command(offload = list(offload or [])if offload:cmd += offload- cmd += [f for f in metal_text_encoder_flags() if f not in offload]+ cmd += metal_placement_flags(offload)if verbose:cmd.append("-v")if extra_args:@@ -523,6 +613,9 @@ def build_sd_cpp_upscale_command(if params.tile_size is not None:cmd += ["--upscale-tile-size", str(int(params.tile_size))]cmd += ["--output", output_path]+ # Same paravirtual-GPU CPU placement as generation; an explicit --backend in extra_args wins.+ if metal_is_paravirtual() and "--backend" not in (extra_args or ()):+ cmd += list(CPU_BACKEND_FLAGS)if verbose:cmd += ["-v"]if extra_args:@@ -589,8 +682,10 @@ def build_sd_cpp_server_command(if offload:cmd += offload# De-dup speed flags against offload (may already include --diffusion-fa).- cmd += [f for f in native_speed_flags(native_speed) if f not in offload]- cmd += [f for f in metal_text_encoder_flags() if f not in offload]+ placement = metal_placement_flags(offload)+ backend_args = [*offload, *placement, *(extra_args or ())]+ cmd += [f for f in native_speed_flags(native_speed, backend_args) if f not in offload]+ cmd += placementif verbose:cmd += ["-v"]if extra_args:diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.pyindex 855f1776b19..32c3ddd7f71 100644--- a/studio/backend/core/inference/sd_cpp_backend.py+++ b/studio/backend/core/inference/sd_cpp_backend.py@@ -69,6 +69,7 @@ from core.inference.diffusion_memory import (OFFLOAD_NONE,OFFLOAD_SEQUENTIAL,)+from core.inference import sd_cpp_args as sd_cpp_args_modfrom core.inference.sd_cpp_args import (CPU_BACKEND_FLAGS,SdCppGenParams,@@ -3045,6 +3046,9 @@ class SdCppDiffusionBackend:if off_torch is not Noneelse resolve_diffusion_device_target().device)+ # A paravirtual Mac GPU runs sd.cpp on the CPU backend (see metal_text_encoder_flags), so record that.+ if sd_cpp_args_mod.forces_cpu_backend(device):+ device = "cpu"spawn_env = off_torch.child_env() if off_torch is not None else None# Honor speed everywhere; offload only off-CPU (on CPU weights are resident, so the flags are no-ops)offload: tuple[str, ...] = ()diff --git a/studio/backend/core/inference/sd_cpp_engine.py b/studio/backend/core/inference/sd_cpp_engine.pyindex 5e3317ec0d8..fbf501003e9 100644--- a/studio/backend/core/inference/sd_cpp_engine.py+++ b/studio/backend/core/inference/sd_cpp_engine.py@@ -743,7 +743,11 @@ class SdCppEngine:process tree and raises ``SdCppCancelled``."""offload = list(offload or [])- speed = [f for f in native_speed_flags(native_speed) if f not in offload]+ speed = [+ f+ for f in native_speed_flags(native_speed, [*offload, *(extra_args or ())])+ if f not in offload+ ]merged_extra = speed + list(extra_args or [])cmd = build_sd_cpp_command(self._require_binary(),diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex f27257f8851..820c7abdb41 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -3436,6 +3436,7 @@ class VideoBackend:prebuilt install, and every file resolved from the cache."""from huggingface_hub import HfApi+ from . import sd_cpp_args as sd_cpp_args_modfrom .sd_cpp_args import (GRAPH_CUT_STREAM_FLAGS,GRAPH_CUT_VRAM_FLAGS,@@ -3512,6 +3513,9 @@ class VideoBackend:selected_card,)native_device = target.device+ # sd.cpp runs a paravirtual Mac GPU on the CPU backend: CPU policy, and no VIDEO claim held.+ if sd_cpp_args_mod.forces_cpu_backend(native_device):+ native_device = "cpu"# What the accelerator decision below was made on, or None when it was never asked (a CPU or MPS target never# consults it). Re-checked under the reader claim, so a replacement that arrives mid-load cannot silently change# the answer this device choice rests on.diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex d401c2e36e9..09b087415a7 100644--- a/studio/backend/routes/inference.py+++ b/studio/backend/routes/inference.py@@ -46517,6 +46517,7 @@ async def load_diffusion_model_gated()from core.inference.media_keepwarm import note_load_origin as note_media_load_originfrom hub.utils.gguf import extract_quant_token+ from core.inference.sd_cpp_args import forces_cpu_backendfrom core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_SD_CPPfrom utils.native_path_leases import redact_native_paths@@ -46700,6 +46701,13 @@ async def load_diffusion_model_gated(needs_gpu = Falseelse:_guard_diffusion_load_against_training()+ # sd.cpp runs a paravirtual Mac GPU on the CPU backend, so it takes no DIFFUSION claim.+ if (+ activated == ENGINE_SD_CPP+ and device == "mps"+ and await asyncio.to_thread(forces_cpu_backend, device)+ ):+ needs_gpu = Falsedef _start_engine_load():# Recorded HERE for the reason the video route gives: inside the admitted callback,diff --git a/studio/backend/routes/video.py b/studio/backend/routes/video.pyindex d837593c0b8..b5d53a72219 100644--- a/studio/backend/routes/video.py+++ b/studio/backend/routes/video.py@@ -458,6 +458,7 @@ async def load_video_model_gated(# begin_load signals whatever generation is running, so guard on every device.require_no_foreign_generations()+ from core.inference.sd_cpp_args import forces_cpu_backendfrom core.inference.video_minimax_h3 import is_h3_nativeif is_h3_native(fam, kind):@@ -466,7 +467,16 @@ async def load_video_model_gated(if getattr(images, "runs_off_torch_device", False) is True:# No arbiter owner evicts it, yet it holds the one managed sd.cpp tree H3 installs into.await asyncio.to_thread(images.unload)- if device != "cpu":+ # sd.cpp runs a paravirtual Mac GPU on the CPU backend: take no VIDEO claim, but keep any existing one until the+ # worker tears the old model down and releases it.+ forced_cpu = (+ is_h3_native(fam, kind)+ and device == "mps"+ and await asyncio.to_thread(forces_cpu_backend, device)+ )+ if forced_cpu:+ status_dict = await asyncio.to_thread(_begin_load)+ elif device != "cpu":# Register the in-flight load UNDER the arbiter lock: otherwise a competing acquire in that gap evicts VIDEO# before the load is marked, finds nothing to cancel, and both allocate at once. The training admission wraps# the same span.diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.pyindex 8d102b684bd..9efcabb01a1 100644--- a/studio/backend/tests/test_sd_cpp_args.py+++ b/studio/backend/tests/test_sd_cpp_args.py@@ -59,6 +59,27 @@ def test_te_flags_by_family():# ── 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++[email protected](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)+ # 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's Metal backend aborts the process on RMS_NORM with non-contiguous rows and has no per-op CPU fallback, so an LLM# text encoder killed sd-server mid-generation on macOS (macos-14, FLUX.2-klein-4B Q2_K: loads on mps, first generation exits -6).@@ -115,9 +136,248 @@ def test_metal_text_encoder_flag_reaches_both_command_builders(monkeypatch):)+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_load)"+ )+ assert branch < source.index("return acquire_for_request(VIDEO, _begin_load)")+++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") == []diff --git a/studio/backend/tests/test_sd_cpp_backend.py b/studio/backend/tests/test_sd_cpp_backend.pyindex f2c93417cfb..744adb5ed08 100644--- a/studio/backend/tests/test_sd_cpp_backend.py+++ b/studio/backend/tests/test_sd_cpp_backend.py@@ -1553,6 +1553,29 @@ def _run_server_load()+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"++def test_server_load_spawns_once_and_status_reports_mode(monkeypatch):b = SdCppDiffusionBackend()servers: list = []diff --git a/studio/backend/tests/test_sd_cpp_h3_matrix.py b/studio/backend/tests/test_sd_cpp_h3_matrix.pyindex c9d31c9d8fa..a773a0c930c 100644--- a/studio/backend/tests/test_sd_cpp_h3_matrix.py+++ b/studio/backend/tests/test_sd_cpp_h3_matrix.py@@ -83,6 +83,7 @@ def h3_host(monkeypatch, tmp_path):help_text: str | None,managed: bool = False,lists_accelerator: bool = True,+ paravirtual: bool = False,):monkeypatch.setattr(sd_cpp_engine.sys, "platform", "linux" if platform == "wsl" else platform@@ -92,6 +93,9 @@ def h3_host(monkeypatch, tmp_path):"resolve_diffusion_device_target",lambda: types.SimpleNamespace(backend = backend, device = device, dtype = None),)+ from core.inference import sd_cpp_args++ monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: paravirtual)monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)monkeypatch.setattr(sd_cpp_backend, "is_managed_binary", lambda _b: managed)monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)@@ -196,6 +200,22 @@ def test_h3_preflight_admits_a_capable_build_and_downloads_once(assert backend_obj._state.device == device+def test_h3_on_a_paravirtual_mac_commits_cpu_and_drops_the_video_claim(h3_host, monkeypatch):+ # sd.cpp runs a paravirtual Metal GPU on the CPU backend, so the load must not keep the VIDEO claim.+ from core.inference import gpu_arbiter++ released = []+ monkeypatch.setattr(+ gpu_arbiter, "release_if", lambda owner, pred: released.append(owner) or pred()+ )+ host = h3_host(+ platform = "darwin", backend = "mps", device = "mps", help_text = _H3_HELP, paravirtual = True+ )+ backend_obj = host.run()+ assert backend_obj._state is not None and backend_obj._state.device == "cpu"+ assert released == [gpu_arbiter.VIDEO]++@pytest.mark.parametrize("platform", PLATFORMS)@pytest.mark.parametrize("hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]