Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

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.py
index 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.md
from __future__ import annotations
+import functools
from collections.abc import Sequence
from dataclasses import dataclass, field
from 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 os
import sys
if 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 += placement
if 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.py
index 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_mod
from core.inference.sd_cpp_args import (
CPU_BACKEND_FLAGS,
SdCppGenParams,
@@ -3045,6 +3046,9 @@ class SdCppDiffusionBackend:
if off_torch is not None
else 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.py
index 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.py
index 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_mod
from .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.py
index 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_origin
from hub.utils.gguf import extract_quant_token
+ from core.inference.sd_cpp_args import forces_cpu_backend
from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_SD_CPP
from utils.native_path_leases import redact_native_paths
@@ -46700,6 +46701,13 @@ async def load_diffusion_model_gated(
needs_gpu = False
else:
_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 = False
def _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.py
index 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_backend
from core.inference.video_minimax_h3 import is_h3_native
if 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.py
index 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.py
index 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.py
index 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")]