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: keep sd.cpp direct conv off on Vulkan and ROCm (#13773)

Daniel Han54e08ff3c604
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 86217373220..a744b9d072b 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -136,8 +136,7 @@ class SdCppUpscaleParams:
tile_size: Optional[int] = None
-# Native (sd.cpp) speed profiles, the engine-side analogue of diffusion_speed. off: nothing. default: --diffusion-fa +
-# --diffusion-conv-direct (numerically exact), except Apple Metal keeps only --diffusion-fa. max keeps it (profiles chain).
+# Native speed profiles. default/max: --diffusion-fa + --diffusion-conv-direct (exact); Metal/Vulkan/ROCm get fa only.
NATIVE_SPEED_OFF = "off"
NATIVE_SPEED_DEFAULT = "default"
NATIVE_SPEED_MAX = "max"
@@ -145,21 +144,45 @@ NATIVE_SPEED_MODES = (NATIVE_SPEED_OFF, NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX)
def native_speed_flags(
- speed_mode: Optional[str], backend_args: Optional[Sequence[str]] = None
+ speed_mode: Optional[str],
+ backend_args: Optional[Sequence[str]] = None,
+ accelerator: Optional[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.
- ``backend_args``: the other argv flags, whose ``--backend`` decides whether the graph runs on Metal."""
+ ``backend_args``: the other argv flags (``--backend`` picks the device); ``accelerator``: build class or None."""
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 ()):
+ if not conv_direct_wanted(backend_args or (), accelerator):
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}'")
+# Direct conv loses to im2col here: Vulkan (sd.cpp #2137, 10.9 -> 73.4 s) and HIP (#2085; gfx1151 never faster).
+_CONV_DIRECT_SLOW_BACKENDS = ("vulkan", "rocm", "hip")
+
+
+def conv_direct_wanted(backend_args: Sequence[str] = (), accelerator: Optional[str] = None) -> bool:
+ """``UNSLOTH_SD_CPP_CONV_DIRECT`` = 1/0 forces it (Metal too); else off on Metal, and a ``--backend diffusion=``
+ pin beats ``accelerator``."""
+ import os
+
+ forced = (os.environ.get("UNSLOTH_SD_CPP_CONV_DIRECT") or "").strip().lower()
+ if forced in ("1", "on", "true", "yes"):
+ return True
+ if forced in ("0", "off", "false", "no"):
+ return False
+ if _runs_on_apple_metal(backend_args):
+ return False
+ args = list(backend_args)
+ target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
+ name = (target or accelerator or "").strip().lower().rstrip("0123456789")
+ return name not in _CONV_DIRECT_SLOW_BACKENDS
+
+
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
@@ -697,6 +720,7 @@ def build_sd_cpp_server_command(
scratch_dir: Optional[str] = None,
verbose: bool = False,
extra_args: Optional[list[str]] = None,
+ accelerator: Optional[str] = None,
) -> list[str]:
"""Build the ``sd-server`` argv: model + hardware/server flags only.
@@ -745,7 +769,9 @@ def build_sd_cpp_server_command(
# De-dup speed flags against offload (may already include --diffusion-fa).
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 += [
+ f for f in native_speed_flags(native_speed, backend_args, accelerator) if f not in offload
+ ]
cmd += placement
cmd += mac_mmap_flags(binary, extra_args)
if verbose:
diff --git a/studio/backend/core/inference/sd_cpp_engine.py b/studio/backend/core/inference/sd_cpp_engine.py
index 17d83dedc4a..ecfdd23e1a8 100644
--- a/studio/backend/core/inference/sd_cpp_engine.py
+++ b/studio/backend/core/inference/sd_cpp_engine.py
@@ -298,6 +298,20 @@ def _terminate(proc: "subprocess.Popen") -> None:
pass
+def binary_accelerator(binary: Optional[str]) -> Optional[str]:
+ """Accelerator class from the install record, else a cached probe listing (no subprocess); None if unknown."""
+ if not binary:
+ return None
+ try:
+ from core.inference import sd_cpp_backend # noqa: PLC0415 - the backend imports this module
+ return (
+ sd_cpp_backend._installed_accelerator_of(binary)
+ or sd_cpp_backend.sd_cpp_listed_device(binary, probe = False)[0]
+ )
+ except Exception: # noqa: BLE001 - unknown keeps the default speed flags
+ return None
+
+
def _binary_name(stem: str) -> str:
return f"{stem}.exe" if sys.platform == "win32" else stem
@@ -808,14 +822,17 @@ class SdCppEngine:
process tree and raises ``SdCppCancelled``.
"""
offload = list(offload or [])
+ binary = self._require_binary()
speed = [
f
- for f in native_speed_flags(native_speed, [*offload, *(extra_args or ())])
+ for f in native_speed_flags(
+ native_speed, [*offload, *(extra_args or ())], binary_accelerator(binary)
+ )
if f not in offload
]
merged_extra = speed + list(extra_args or [])
cmd = build_sd_cpp_command(
- self._require_binary(),
+ binary,
files,
params,
output_path = str(self._prepare_out(output_path)),
diff --git a/studio/backend/core/inference/sd_cpp_server.py b/studio/backend/core/inference/sd_cpp_server.py
index bbc95a2633f..959d5841ac1 100644
--- a/studio/backend/core/inference/sd_cpp_server.py
+++ b/studio/backend/core/inference/sd_cpp_server.py
@@ -56,6 +56,7 @@ from core.inference.sd_cpp_engine import (
_sd_cpp_command_for_log,
_sd_cpp_command_summary,
_verbose_native_logs,
+ binary_accelerator,
runtime_env,
)
from utils.native_path_leases import child_env_without_native_path_secret
@@ -225,6 +226,7 @@ class SdCppServer:
scratch_dir = self._scratch_dir,
verbose = True, # sd-server prints the per-step sampling lines we parse
extra_args = list(extra_args or []),
+ accelerator = binary_accelerator(self.binary),
)
run_env = runtime_env(self.binary, child_env_without_native_path_secret())
if env:
diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.py
index 45d2678b0fa..92877cff1b9 100644
--- a/studio/backend/tests/test_sd_cpp_args.py
+++ b/studio/backend/tests/test_sd_cpp_args.py
@@ -389,6 +389,41 @@ def test_native_speed_flags():
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) == []
@@ -1039,6 +1074,17 @@ def test_device_backend_flags_are_appended_not_folded_into_the_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) ───────────────────────────