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: cache sd.cpp --help output per binary build (#17491)

Daniel Han192bce6dde18
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index a8c7f3240ec..4ea7c488c6a 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -573,10 +573,33 @@ def _usable_or_discard_managed(binary: str) -> bool:
return False
+# Successful ``--help`` text per (path, size, mtime_ns); a rewritten binary changes the key.
+_HELP_TEXT_CACHE: dict[tuple[str, int, int], str] = {}
+_HELP_TEXT_CACHE_MAX = 8
+_help_text_cache_lock = threading.Lock()
+
+
+def _help_cache_key(binary: str) -> Optional[tuple[str, int, int]]:
+ # A bare name is resolved by the spawn through PATH, not by stat; only explicit paths are cached.
+ if not os.path.dirname(binary):
+ return None
+ try:
+ st = os.stat(binary)
+ except (OSError, ValueError):
+ return None
+ return (os.path.abspath(binary), int(st.st_size), int(st.st_mtime_ns))
+
+
def _sd_cpp_probe_output(binary: str, *args: str) -> Optional[str]:
"""Identifying output settles it whatever the exit code (old builds exit 1); else only a clean exit is evidence, and rc 127 from the loader is not."""
import subprocess
+ cache_key = _help_cache_key(str(binary)) if args == ("--help",) else None
+ if cache_key is not None:
+ with _help_text_cache_lock:
+ cached = _HELP_TEXT_CACHE.get(cache_key)
+ if cached is not None:
+ return cached
try:
with windows_loader_error_boxes_suppressed():
proc = subprocess.run(
@@ -593,7 +616,16 @@ def _sd_cpp_probe_output(binary: str, *args: str) -> Optional[str]:
return None
if proc.returncode != 0:
return None
- return (proc.stdout or "") + (proc.stderr or "")
+ text = (proc.stdout or "") + (proc.stderr or "")
+ # Re-stat: a binary replaced while it ran must not leave this text under the old build's key.
+ if cache_key is not None and _help_cache_key(str(binary)) == cache_key:
+ with _help_text_cache_lock:
+ for stale in [k for k in _HELP_TEXT_CACHE if k[0] == cache_key[0]]:
+ del _HELP_TEXT_CACHE[stale]
+ while len(_HELP_TEXT_CACHE) >= _HELP_TEXT_CACHE_MAX:
+ del _HELP_TEXT_CACHE[next(iter(_HELP_TEXT_CACHE))]
+ _HELP_TEXT_CACHE[cache_key] = text
+ return text
# --ref-video arrived with H3 upstream; --version is "unknown" on release prebuilts.
diff --git a/studio/backend/tests/test_sd_cpp_help_probe_cache.py b/studio/backend/tests/test_sd_cpp_help_probe_cache.py
new file mode 100644
index 00000000000..cb9917ba3d1
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_help_probe_cache.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""``_sd_cpp_probe_output`` spawns ``--help`` once per build of a binary; failures and other probes are never cached."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import types
+
+import pytest
+
+from core.inference import sd_cpp_backend as bk
+
+
+def fake_run(monkeypatch):
+ """Records each spawn; ``state`` sets what the next spawn returns (``raise`` wins over ``rc``)."""
+ state = {"calls": [], "rc": 0, "stdout": "usage: sd-cli --ref-video --max-vram", "raise": None}
+
+ def _run(cmd, **kwargs):
+ state["calls"].append(list(cmd))
+ if state["raise"] is not None:
+ raise state["raise"]
+ return types.SimpleNamespace(returncode = state["rc"], stdout = state["stdout"], stderr = "")
+
+ monkeypatch.setattr(subprocess, "run", _run)
+ monkeypatch.setattr(bk, "_HELP_TEXT_CACHE", {}, raising = False)
+ return state
+
+
+def binary(tmp_path):
+ path = tmp_path / "sd-server"
+ path.write_bytes(b"\x7fELF build one")
+ return str(path)
+
+
+def test_repeated_help_spawns_once(fake_run, binary):
+ first = bk._sd_cpp_probe_output(binary, "--help")
+ fake_run["stdout"] = "a later spawn would see this"
+ assert [bk._sd_cpp_probe_output(binary, "--help") for _ in range(4)] == [first] * 4
+ assert first == "usage: sd-cli --ref-video --max-vram"
+ assert len(fake_run["calls"]) == 1
+ assert bk.sd_cpp_supports_minimax_h3(binary)
+ assert bk._layer_split_supported(binary) is False
+ assert len(fake_run["calls"]) == 1
+
+
[email protected]("failure", ["rc", "timeout", "oserror"])
+def test_failed_help_is_not_cached(fake_run, binary, failure):
+ if failure == "rc":
+ fake_run["rc"] = 1
+ elif failure == "timeout":
+ fake_run["raise"] = subprocess.TimeoutExpired(binary, 20)
+ else:
+ fake_run["raise"] = OSError("exec format error")
+ assert bk._sd_cpp_probe_output(binary, "--help") is None
+ assert bk._sd_cpp_probe_output(binary, "--help") is None
+ assert len(fake_run["calls"]) == 2
+ fake_run["rc"], fake_run["raise"] = 0, None
+ assert bk._sd_cpp_probe_output(binary, "--help") == fake_run["stdout"]
+ assert len(fake_run["calls"]) == 3
+
+
+def test_rewritten_binary_reprobes(fake_run, binary):
+ assert bk._sd_cpp_probe_output(binary, "--help") == "usage: sd-cli --ref-video --max-vram"
+ # Same size, new mtime.
+ with open(binary, "wb") as f:
+ f.write(b"\x7fELF build two")
+ st = os.stat(binary)
+ os.utime(binary, ns = (st.st_atime_ns, st.st_mtime_ns + 5_000_000_000))
+ fake_run["stdout"] = "usage: newer build"
+ assert bk._sd_cpp_probe_output(binary, "--help") == "usage: newer build"
+ # Different size, mtime pinned back.
+ with open(binary, "wb") as f:
+ f.write(b"\x7fELF build three, longer")
+ os.utime(binary, ns = (st.st_atime_ns, st.st_mtime_ns))
+ fake_run["stdout"] = "usage: third build"
+ assert bk._sd_cpp_probe_output(binary, "--help") == "usage: third build"
+ assert len(fake_run["calls"]) == 3
+ assert len(bk._HELP_TEXT_CACHE) == 1
+
+
+def test_list_devices_is_never_cached(fake_run, binary):
+ fake_run["stdout"] = "CUDA0: NVIDIA test card"
+ for _ in range(3):
+ assert bk._sd_cpp_probe_output(binary, "--list-devices") == "CUDA0: NVIDIA test card"
+ assert len(fake_run["calls"]) == 3
+ assert bk._HELP_TEXT_CACHE == {}
+
+
+def test_missing_binary_spawns_every_time(fake_run, tmp_path):
+ missing = str(tmp_path / "gone" / "sd-cli")
+ fake_run["raise"] = FileNotFoundError(missing)
+ assert bk._sd_cpp_probe_output(missing, "--help") is None
+ assert bk._sd_cpp_probe_output(missing, "--help") is None
+ assert len(fake_run["calls"]) == 2
+ # A stat failure with a spawn that answers still answers, uncached.
+ fake_run["raise"] = None
+ assert bk._sd_cpp_probe_output(missing, "--help") == fake_run["stdout"]
+ assert bk._sd_cpp_probe_output(missing, "--help") == fake_run["stdout"]
+ assert len(fake_run["calls"]) == 4
+ assert bk._HELP_TEXT_CACHE == {}
+
+
+def test_cache_stays_bounded(fake_run, tmp_path):
+ for i in range(bk._HELP_TEXT_CACHE_MAX + 5):
+ path = tmp_path / f"sd-cli-{i}"
+ path.write_bytes(b"x")
+ bk._sd_cpp_probe_output(str(path), "--help")
+ assert len(bk._HELP_TEXT_CACHE) == bk._HELP_TEXT_CACHE_MAX