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: pass --conv-direct off when Studio's policy keeps direct convolution off (#14859)

Daniel Han5dd51546a285
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 08dcded3990..aa771145548 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -200,20 +200,66 @@ def native_speed_flags(
speed_mode: Optional[str],
backend_args: Optional[Sequence[str]] = None,
accelerator: Optional[str] = None,
+ binary: 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 (``--backend`` picks the device); ``accelerator``: build class or None."""
+ ``backend_args``: the other argv flags (``--backend`` picks the device); ``accelerator``: build class or None.
+ ``binary``: on builds listing ``--conv-direct`` (master-963+) a rejected direct conv is sent as ``--conv-direct off``,
+ since an omitted flag means auto there (direct conv on for HIP MMA / Vulkan regardless of this policy)."""
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 not conv_direct_wanted(backend_args or (), accelerator):
+ args = backend_args or ()
+ if not conv_direct_wanted(args, accelerator):
+ user_set = any(f in _CONV_DIRECT_FLAGS for f in args)
+ if not user_set and binary and sd_cpp_supports_conv_direct_mode(binary):
+ return ["--diffusion-fa", "--conv-direct", "off"]
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}'")
+# Flags that already decide direct conv; a user-supplied one wins over the policy.
+_CONV_DIRECT_FLAGS = ("--conv-direct", "--diffusion-conv-direct", "--vae-conv-direct")
+_VALUED_SPEED_FLAGS = ("--conv-direct",)
+
+
+def speed_flags_without(speed: Sequence[str], offload: Sequence[str]) -> list[str]:
+ """``speed`` minus flags already in ``offload``, keeping a valued flag and its value together."""
+ out: list[str] = []
+ i = 0
+ while i < len(speed):
+ flag = speed[i]
+ width = 2 if flag in _VALUED_SPEED_FLAGS and i + 1 < len(speed) else 1
+ if flag not in offload:
+ out += list(speed[i : i + width])
+ i += width
+ return out
+
+
+def sd_cpp_supports_conv_direct_mode(binary: str) -> bool:
+ """True when ``binary --help`` lists ``--conv-direct``. Fails closed (older builds reject the unknown flag)."""
+ import os
+
+ try:
+ st = os.stat(binary)
+ except OSError:
+ return False
+ return _conv_direct_in_help(str(binary), st.st_size, st.st_mtime_ns)
+
+
[email protected]_cache(maxsize = 16)
+def _conv_direct_in_help(binary: str, size: int, mtime_ns: int) -> bool:
+ import re
+
+ from core.inference.sd_cpp_backend import _sd_cpp_probe_output
+
+ text = _sd_cpp_probe_output(binary, "--help")
+ return text is not None and re.search(r"(?<![\w-])--conv-direct\b", text) is not None
+
+
# 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")
@@ -983,9 +1029,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, accelerator) if f not in offload
- ]
+ cmd += speed_flags_without(
+ native_speed_flags(native_speed, backend_args, accelerator, binary), 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 c58b218d1b4..81a42abfe75 100644
--- a/studio/backend/core/inference/sd_cpp_engine.py
+++ b/studio/backend/core/inference/sd_cpp_engine.py
@@ -45,6 +45,7 @@ from core.inference.sd_cpp_args import (
build_sd_cpp_upscale_command,
build_sd_cpp_video_command,
native_speed_flags,
+ speed_flags_without,
sd_cli_output_paths,
)
@@ -823,13 +824,12 @@ class SdCppEngine:
"""
offload = list(offload or [])
binary = self._require_binary()
- speed = [
- f
- for f in native_speed_flags(
- native_speed, [*offload, *(extra_args or ())], binary_accelerator(binary)
- )
- if f not in offload
- ]
+ speed = speed_flags_without(
+ native_speed_flags(
+ native_speed, [*offload, *(extra_args or ())], binary_accelerator(binary), binary
+ ),
+ offload,
+ )
merged_extra = speed + list(extra_args or [])
cmd = build_sd_cpp_command(
binary,
diff --git a/studio/backend/tests/test_sd_cpp_conv_direct_off.py b/studio/backend/tests/test_sd_cpp_conv_direct_off.py
new file mode 100644
index 00000000000..0b79ec60dbe
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_conv_direct_off.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Direct conv rejected by Studio's policy must reach sd.cpp as an explicit ``--conv-direct off``.
+
+sd.cpp master-963+ reads an omitted ``--conv-direct`` as auto, and auto turns direct conv on for implicit-GEMM
+backends (HIP MMA; Vulkan when its timing probe wins), so leaving the legacy flag out no longer means off."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+
+import pytest
+
+import core.inference.sd_cpp_args as sd_cpp_args
+from core.inference.sd_cpp_args import (
+ SdCppGenParams,
+ SdCppModelFiles,
+ build_sd_cpp_server_command,
+ native_speed_flags,
+ speed_flags_without,
+)
+
+pytestmark = pytest.mark.skipif(
+ sys.platform == "win32", reason = "fake sd.cpp binaries are shell scripts"
+)
+
+_NEW_HELP = (
+ " --diffusion-conv-direct deprecated; use --conv-direct auto,diffusion=on,controlnet=on\n"
+ " --conv-direct on|off|auto or diffusion/vae/controlnet assignments (default: auto)\n"
+)
+_OLD_HELP = " --diffusion-conv-direct use ggml_conv2d_direct in the diffusion model\n"
+
+
+def _fake_binary(tmp_path, name, help_text):
+ path = tmp_path / name
+ path.write_text("#!/bin/sh\ncat <<'EOF'\n" + help_text + "EOF\n")
+ path.chmod(path.stat().st_mode | stat.S_IXUSR)
+ return str(path)
+
+
[email protected](autouse = True)
+def _clean(monkeypatch):
+ monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
+ monkeypatch.setattr("sys.platform", "linux")
+ sd_cpp_args._conv_direct_in_help.cache_clear()
+ yield
+ sd_cpp_args._conv_direct_in_help.cache_clear()
+
+
+def _pair(cmd, flag):
+ return cmd[cmd.index(flag) + 1] if flag in cmd else None
+
+
[email protected]("accelerator", ["rocm", "vulkan", "hip"])
+def test_rejected_backend_sends_explicit_off_to_an_auto_build(tmp_path, accelerator):
+ binary = _fake_binary(tmp_path, "sd-server", _NEW_HELP)
+ cmd = build_sd_cpp_server_command(
+ binary = binary,
+ files = SdCppModelFiles(diffusion_model = "/m/x.gguf"),
+ host = "127.0.0.1",
+ port = 1234,
+ native_speed = "default",
+ accelerator = accelerator,
+ )
+ assert "--diffusion-fa" in cmd
+ assert _pair(cmd, "--conv-direct") == "off"
+ assert "--diffusion-conv-direct" not in cmd
+
+
+def test_force_off_override_is_explicit_on_cuda(tmp_path, monkeypatch):
+ binary = _fake_binary(tmp_path, "sd-cli", _NEW_HELP)
+ assert native_speed_flags("max", [], "cuda", binary) == [
+ "--diffusion-fa",
+ "--diffusion-conv-direct",
+ ]
+ monkeypatch.setenv("UNSLOTH_SD_CPP_CONV_DIRECT", "0")
+ assert native_speed_flags("max", [], "cuda", binary) == [
+ "--diffusion-fa",
+ "--conv-direct",
+ "off",
+ ]
+
+
+def test_older_build_without_the_flag_keeps_the_omission(tmp_path):
+ # Pre-963 builds reject an unknown flag; there an omitted legacy flag already means off.
+ binary = _fake_binary(tmp_path, "sd-cli", _OLD_HELP)
+ assert native_speed_flags("default", [], "rocm", binary) == ["--diffusion-fa"]
+ assert native_speed_flags("default", [], "rocm", str(tmp_path / "missing")) == [
+ "--diffusion-fa"
+ ]
+ assert native_speed_flags("default", [], "rocm") == ["--diffusion-fa"]
+
+
[email protected]("user_flag", [["--conv-direct", "on"], ["--diffusion-conv-direct"]])
+def test_a_user_conv_direct_flag_wins(tmp_path, user_flag):
+ binary = _fake_binary(tmp_path, "sd-cli", _NEW_HELP)
+ assert native_speed_flags("default", user_flag, "rocm", binary) == ["--diffusion-fa"]
+
+
+def test_speed_off_adds_nothing(tmp_path):
+ binary = _fake_binary(tmp_path, "sd-cli", _NEW_HELP)
+ assert native_speed_flags("off", [], "rocm", binary) == []
+
+
+def test_dedupe_keeps_the_flag_and_value_together():
+ speed = ["--diffusion-fa", "--conv-direct", "off"]
+ # A bare "off" elsewhere in the offload argv must not strip the value from its flag.
+ assert speed_flags_without(speed, ["--flash-attn", "off"]) == speed
+ assert speed_flags_without(speed, ["--diffusion-fa"]) == ["--conv-direct", "off"]
+ assert speed_flags_without(speed, ["--conv-direct", "auto"]) == ["--diffusion-fa"]
+
+
+def test_engine_generate_sends_explicit_off(tmp_path, monkeypatch):
+ import core.inference.sd_cpp_engine as sd_cpp_engine
+ from core.inference.sd_cpp_engine import SdCppEngine
+
+ binary = _fake_binary(tmp_path, "sd-cli", _NEW_HELP)
+ monkeypatch.setattr(sd_cpp_engine, "binary_accelerator", lambda b: "rocm")
+ captured = {}
+ eng = SdCppEngine(binary = binary)
+ monkeypatch.setattr(eng, "_require_binary", lambda: binary)
+ monkeypatch.setattr(eng, "_prepare_out", lambda p: p)
+ monkeypatch.setattr(eng, "_run", lambda cmd, *a, **k: captured.setdefault("cmd", cmd))
+ eng.generate(
+ SdCppModelFiles(diffusion_model = "/m/x.gguf"),
+ SdCppGenParams(prompt = "x"),
+ output_path = str(tmp_path / "x.png"),
+ native_speed = "default",
+ )
+ assert _pair(captured["cmd"], "--conv-direct") == "off"
+ assert "--diffusion-conv-direct" not in captured["cmd"]