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: faster MiniMax-H3 GGUF renders (resident under memory auto, sd.cpp pin upgrade, speed_mode=max kernels) (#12405)

Daniel Hanc85ee3700c8a
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 35d27b7ced4..b25261c2204 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -343,6 +343,14 @@ def sd_cpp_supports_graph_cut(binary: Optional[str]) -> bool:
return all(marker in text for marker in _GRAPH_CUT_HELP_MARKERS)
+def sd_cpp_supports_sage_attn(binary: Optional[str]) -> bool:
+ """Fails closed: sd-cli exits non-zero on an unknown option (u13b9d92 predates --sage-attn)."""
+ if not binary:
+ return False
+ text = _sd_cpp_probe_output(binary, "--help")
+ return text is not None and "--sage-attn" in text
+
+
def sd_cpp_lists_accelerator_device(binary: Optional[str]) -> bool:
"""True unless ``binary`` demonstrably enumerates the CPU ggml device and nothing else.
@@ -804,6 +812,48 @@ def _installer_module():
_failed_accelerator_upgrades: set[str] = set()
+# (pin, accelerator class) upgrades that failed this process: keep the old bundle instead of retrying every load.
+_failed_pin_upgrades: set[tuple[str, str]] = set()
+_PIN_UPGRADE_ENV = "UNSLOTH_SD_CPP_AUTO_UPGRADE"
+
+
+def _pin_upgrade_disabled() -> bool:
+ return os.environ.get(_PIN_UPGRADE_ENV, "").strip().lower() in ("0", "false", "no", "off")
+
+
+def _pin_moved(binary: str, accelerator: str) -> bool:
+ """True when ``binary`` is a managed install made for an older pin. Unknown answers False."""
+ if _pin_upgrade_disabled():
+ return False
+ root = owning_managed_root(binary)
+ if root is None:
+ return False
+ if _managed_tree_in_use():
+ return False
+ try:
+ mod = _installer_module()
+ want = mod._pinned_tag()
+ if not want or (want, mod.accelerator_class(accelerator)) in _failed_pin_upgrades:
+ return False
+ return bool(mod.install_is_stale(root))
+ except Exception: # noqa: BLE001 -- cannot tell -> keep the existing binary
+ return False
+
+
+def _note_failed_pin_upgrade(accelerator: str) -> None:
+ try:
+ mod = _installer_module()
+ want = mod._pinned_tag()
+ if want:
+ _failed_pin_upgrades.add((want, mod.accelerator_class(accelerator)))
+ except Exception: # noqa: BLE001
+ pass
+
+
+def _needs_reinstall(binary: str, accelerator: str) -> bool:
+ return _accelerator_changed(binary, accelerator) or _pin_moved(binary, accelerator)
+
+
def _note_failed_upgrade(accelerator: str) -> None:
"""Stop retrying an accelerator upgrade that just failed while a usable binary is kept."""
try:
@@ -1590,7 +1640,15 @@ def _superseded_legacy_server(binary: Optional[str], accelerator: str) -> bool:
try:
mod = _installer_module()
want = mod.accelerator_class(accelerator)
- if not _record_mismatch(mod, root, want) or _record_mismatch(mod, current, want):
+ # Superseded = built for another accelerator, or (with the pin upgrade on) for an older pin.
+ legacy_stale = _record_mismatch(mod, root, want) or (
+ not _pin_upgrade_disabled() and mod.install_is_stale(root)
+ )
+ if (
+ not legacy_stale
+ or _record_mismatch(mod, current, want)
+ or mod.install_is_stale(current)
+ ):
return False
return mod.installed_ships_server(current) is False
except Exception: # noqa: BLE001 -- cannot tell
@@ -1827,14 +1885,14 @@ def ensure_sd_cpp_binary(*, allow_install: bool = True, accelerator: str = "cpu"
diffusers."""
found = find_sd_cpp_binary()
usable = bool(found) and _usable_or_discard_managed(found)
- if usable and not _accelerator_changed(found, accelerator):
+ if usable and not _needs_reinstall(found, accelerator):
return found
if not allow_install:
return found
with _install_lock:
found = find_sd_cpp_binary()
usable = bool(found) and _usable_or_discard_managed(found)
- if usable and not _accelerator_changed(found, accelerator):
+ if usable and not _needs_reinstall(found, accelerator):
return found
# A usable binary of the wrong accelerator is still better than none, so an install that cannot deliver the
# right one (no such asset for this host, no network) keeps it.
@@ -1867,6 +1925,7 @@ def ensure_sd_cpp_binary(*, allow_install: bool = True, accelerator: str = "cpu"
return refound if refound and _usable_or_discard_managed(refound) else None
if fallback is not None:
_note_failed_upgrade(accelerator)
+ _note_failed_pin_upgrade(accelerator)
return fallback
@@ -1886,7 +1945,7 @@ def ensure_sd_server_binary(
# not downloaded again on every later load.
if usable and _superseded_legacy_server(found, accelerator):
return None
- if usable and not _accelerator_changed(found, accelerator):
+ if usable and not _needs_reinstall(found, accelerator):
return found
if not allow_install:
return found
@@ -1895,7 +1954,7 @@ def ensure_sd_server_binary(
usable = bool(found) and _usable_or_discard_managed(found)
if usable and _superseded_legacy_server(found, accelerator):
return None
- if usable and not _accelerator_changed(found, accelerator):
+ if usable and not _needs_reinstall(found, accelerator):
return found
# Keep a usable wrong-accelerator server if the matching one cannot be fetched
fallback = found if usable else None
@@ -1921,6 +1980,7 @@ def ensure_sd_server_binary(
return refound if refound and _usable_or_discard_managed(refound) else None
if fallback is not None or find_sd_cpp_binary() is not None:
_note_failed_upgrade(accelerator)
+ _note_failed_pin_upgrade(accelerator)
return fallback
installed = find_sd_server_binary()
# The finder also probes the tree an older build left beside the Unsloth home, so when the bundle just
@@ -1928,7 +1988,7 @@ def ensure_sd_server_binary(
# None, not the fallback: an install just completed, so the router's next step resolves the sd-cli it landed,
# and a one-shot run on the right build beats a resident server on the wrong one. The fallback stays for the
# failure path above, where no matching binary was fetched at all.
- if installed and _accelerator_changed(installed, accelerator):
+ if installed and _needs_reinstall(installed, accelerator):
return None
return installed or fallback
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index e5f690ef4aa..b5660f9f983 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -1268,6 +1268,29 @@ def _h3_free_device_bytes(device: str) -> Optional[int]:
return None
+def _h3_card_free_bytes(device: Optional[str], ordinal: Optional[int]) -> Optional[int]:
+ """Live free VRAM via nvidia-smi / amd-smi (no CUDA context here), or None. No pin = sd.cpp's ordinal 0."""
+ if device != "cuda":
+ return None
+ try:
+ from utils.hardware import get_visible_gpu_utilization, gpu_query
+
+ with gpu_query.fresh_reads():
+ devices = get_visible_gpu_utilization().get("devices", [])
+ want = 0 if ordinal is None else int(ordinal)
+ for entry in devices:
+ if entry.get("visible_ordinal") != want:
+ continue
+ total = entry.get("vram_total_gb")
+ used = entry.get("vram_used_gb")
+ if total is None or used is None:
+ return None
+ return max(0, int((float(total) - float(used)) * 1024**3))
+ except Exception: # noqa: BLE001 -- an unreadable card decides nothing
+ return None
+ return None
+
+
def _h3_device_capacity_bytes(device: str) -> Optional[int]:
"""TOTAL VRAM on the card, or None when it cannot be read.
@@ -3018,6 +3041,7 @@ class VideoBackend:
gpu_ordinal: Optional[int] = None,
# NAMED so a static step-skip ask can be recorded as declined: sd.cpp runs every step itself.
transformer_cache: Optional[str] = None,
+ speed_mode: Optional[str] = None,
# NAMED, not left to the ``**_`` swallow below: an API-initiated load hands this in through _run_load's kwargs,
# and swallowed it meant the four-file bundle, the sizing metadata and the sd-cli install were all fetched by a
# load that promised no downloads.
@@ -3053,6 +3077,7 @@ class VideoBackend:
sd_cpp_accelerator_device_verdict,
sd_cpp_device_name_for_ordinal,
sd_cpp_supports_graph_cut,
+ sd_cpp_supports_sage_attn,
)
from .sd_cpp_engine import SdCppEngine
from .video_minimax_h3 import (
@@ -3335,6 +3360,14 @@ class VideoBackend:
# Under the claim like every other probe here; None on the CPU fallback, which has no card to choose
# between.
supports_graph_cut = native_device != "cpu" and sd_cpp_supports_graph_cut(binary)
+ # Lossy (INT8 QK^T), so only on an explicit speed_mode="max".
+ h3_sage = (
+ native_device != "cpu"
+ and str(speed_mode or "").strip().lower() == "max"
+ and os.environ.get("UNSLOTH_H3_SAGE_ATTN", "").strip().lower()
+ not in ("0", "false", "no", "off")
+ and sd_cpp_supports_sage_attn(binary)
+ )
# Dropped with the accelerator: the CPU fallback runs on no card, so a recorded ordinal would outlive the
# decision and be committed against a runtime that never used it.
native_ordinal = None if native_device == "cpu" else gpu_ordinal
@@ -3382,6 +3415,13 @@ class VideoBackend:
native_offload += GRAPH_CUT_VRAM_FLAGS
if "--offload-to-cpu" in native_offload:
native_offload += GRAPH_CUT_STREAM_FLAGS
+ native_env: tuple[tuple[str, str], ...] = ()
+ if h3_sage:
+ native_offload += ("--sage-attn",)
+ # Same opt-in takes the fork's BF16 cuBLAS path; a user-exported value (0 included) wins.
+ from .video_minimax_h3 import H3_QUANT_CUBLAS_ENV, H3_QUANT_CUBLAS_MIN_BATCH
+ if H3_QUANT_CUBLAS_ENV not in os.environ:
+ native_env += ((H3_QUANT_CUBLAS_ENV, H3_QUANT_CUBLAS_MIN_BATCH),)
# After the policy, so the pin can see which modules it left on the CPU; without it sd.cpp uses ordinal 0
# whatever was selected.
native_offload += tuple(device_backend_flags(native_device_name, list(native_offload)))
@@ -3400,6 +3440,7 @@ class VideoBackend:
audio_vae = str(resolved[3]),
),
offload_flags = native_offload,
+ env = native_env,
)
with self._lock:
@@ -3433,15 +3474,25 @@ class VideoBackend:
offload_policy = policy,
vae_tiling = False,
memory_mode = requested_mode,
- attention_backend = "flash",
+ attention_backend = "sage" if h3_sage else "flash",
+ speed_mode = SPEED_MAX if h3_sage else SPEED_OFF,
resolved = build_resolved_record(
{
"family_override": _family_override_resolved(family_override, fam),
"memory_mode": (memory_mode, policy, "native model offload"),
+ "speed_mode": (
+ speed_mode,
+ SPEED_MAX if h3_sage else SPEED_OFF,
+ "sd.cpp SageAttention + BF16 cuBLAS"
+ if h3_sage
+ else "sd.cpp exact kernels",
+ ),
"attention_backend": (
None,
- "flash",
- "sd.cpp diffusion flash attention",
+ "sage" if h3_sage else "flash",
+ "sd.cpp SageAttention (speed_mode=max)"
+ if h3_sage
+ else "sd.cpp diffusion flash attention",
),
**(
{
@@ -5159,6 +5210,7 @@ class VideoBackend:
# would let an offline load fetch the four-file bundle.
local_files_only = local_files_only,
transformer_cache = transformer_cache,
+ speed_mode = speed_mode,
)
return self.status()
@@ -8528,12 +8580,33 @@ class VideoBackend:
from .sd_cpp_args import SdCppVideoGenParams
from .sd_cpp_engine import SdCppCancelled
from .video_minimax_h3 import (
+ h3_native_render_flags,
+ h3_native_resident_bytes,
inspect_video,
stage_h3_references,
transcode_video_to_mp4,
)
runtime = state.pipe
+ render_flags = list(runtime.offload_flags)
+ render_resident = False
+ if "--offload-to-cpu" in render_flags and state.memory_mode in (None, "auto"):
+ try:
+ files = runtime.files
+ file_bytes = sum(
+ os.path.getsize(p)
+ for p in (files.diffusion_model, files.llm, files.vae, files.audio_vae)
+ if p
+ )
+ need = h3_native_resident_bytes(file_bytes, width, height, frames)
+ except Exception: # noqa: BLE001 -- unknown size keeps the committed offload
+ need = None
+ render_flags, render_resident = h3_native_render_flags(
+ runtime.offload_flags,
+ memory_mode = state.memory_mode,
+ free_bytes = _h3_card_free_bytes(state.device, state.gpu_ordinal) if need else None,
+ need_bytes = need,
+ )
if seed is None:
seed = random.SystemRandom().randrange(0, 2**53)
started = time.monotonic()
@@ -8644,7 +8717,8 @@ class VideoBackend:
flow_shift = flow_shift,
),
output_path = str(output_path),
- offload = list(runtime.offload_flags),
+ offload = render_flags,
+ env = dict(runtime.env) or None,
on_log = on_log,
cancel_event = cancel,
)
@@ -8692,7 +8766,7 @@ class VideoBackend:
"transformer_quant": state.transformer_quant,
"text_encoder_quant": state.text_encoder_quant,
"memory_mode": state.memory_mode,
- "offload_policy": state.offload_policy,
+ "offload_policy": "none" if render_resident else state.offload_policy,
}
finally:
output_path.unlink(missing_ok = True)
diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.py
index 20f8e802d8c..f559b8f6be6 100644
--- a/studio/backend/core/inference/video_minimax_h3.py
+++ b/studio/backend/core/inference/video_minimax_h3.py
@@ -6,6 +6,7 @@
from __future__ import annotations
import math
+import os
import tempfile
from dataclasses import dataclass
from pathlib import Path
@@ -1102,6 +1103,48 @@ def h3_component_metadata_repo(repo_id: str) -> str:
return H3_COMPONENT_REPO if repo_id == H3_LEGACY_COMPONENT_REPO else repo_id
+# Resident peak is the four files plus ~1 GiB (sd.cpp frees the text encoder before the denoiser's compute buffer);
+# the estimate still adds that buffer on top of every file, plus a margin.
+H3_NATIVE_RESIDENT_ENV = "UNSLOTH_H3_NATIVE_RESIDENT"
+# Unsloth sd.cpp fork: quantized matmuls with >= this many rows run BF16 cuBLAS instead of int8 MMQ. Unset/0 = MMQ.
+H3_QUANT_CUBLAS_ENV = "GGML_CUDA_QUANT_CUBLAS_MIN_BATCH"
+H3_QUANT_CUBLAS_MIN_BATCH = "1024"
+# Denoiser compute buffer at 960x544x124, from sd-cli's log; scaled by pixel volume.
+H3_NATIVE_DIT_COMPUTE_BYTES_H1 = int(5.4 * 1024**3)
+H3_NATIVE_H1_PIXEL_VOLUME = 960 * 544 * 124
+H3_NATIVE_RESIDENT_MARGIN_BYTES = 2 * 1024**3
+_H3_STREAM_ONLY_FLAGS = ("--offload-to-cpu", "--stream-layers")
+
+
+def h3_native_resident_bytes(file_bytes: int, width: int, height: int, frames: int) -> int:
+ volume = max(1, int(width)) * max(1, int(height)) * max(1, int(frames))
+ compute = math.ceil(
+ H3_NATIVE_DIT_COMPUTE_BYTES_H1 * max(1.0, volume / H3_NATIVE_H1_PIXEL_VOLUME)
+ )
+ return int(file_bytes) + compute + H3_NATIVE_RESIDENT_MARGIN_BYTES
+
+
+def h3_native_render_flags(
+ offload_flags: "tuple[str, ...] | list[str]",
+ *,
+ memory_mode: Optional[str],
+ free_bytes: Optional[int],
+ need_bytes: Optional[int],
+ env: Optional[dict] = None,
+) -> tuple[list[str], bool]:
+ """Flags for one render and whether it runs resident: only memory auto, only when the live free VRAM covers
+ the estimate; anything unknown keeps the committed flags."""
+ flags = list(offload_flags)
+ environ = env if env is not None else os.environ
+ if str(environ.get(H3_NATIVE_RESIDENT_ENV, "")).strip().lower() in ("0", "false", "no", "off"):
+ return flags, False
+ if (memory_mode or "auto") != "auto" or "--offload-to-cpu" not in flags:
+ return flags, False
+ if free_bytes is None or need_bytes is None or int(free_bytes) < int(need_bytes):
+ return flags, False
+ return [f for f in flags if f not in _H3_STREAM_ONLY_FLAGS], True
+
+
def h3_native_hub_files(transformer_filename: str) -> tuple[tuple[str, str], ...]:
validate_h3_transformer_filename(transformer_filename)
return (
@@ -1125,6 +1168,7 @@ class MiniMaxH3NativeRuntime:
binary_identity: Optional[tuple[int, int]] = None
# The card the load resolved, kept for failure records: re-resolving at failure time can read None.
selected_card: Optional[str] = None
+ env: tuple[tuple[str, str], ...] = ()
def transcode_video_to_mp4(source: Path, *, fps: int) -> bytes:
diff --git a/studio/backend/tests/test_h3_native_resident.py b/studio/backend/tests/test_h3_native_resident.py
new file mode 100644
index 00000000000..e7bc41dd07d
--- /dev/null
+++ b/studio/backend/tests/test_h3_native_resident.py
@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Memory auto runs a MiniMax-H3 sd-cli render resident when the card holds the whole bundle.
+
+The native runtime commits --offload-to-cpu for memory auto, so a 96 GB card still pinned the 17 GB text
+encoder in host RAM and paged every weight in on each render (Colab G4: peak 16.5 GiB used of 96). The
+per-render check below drops only the streaming flags, only for memory auto, and only when the live free
+VRAM covers a conservative resident estimate.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parents[1]
+if str(_BACKEND) not in sys.path:
+ sys.path.insert(0, str(_BACKEND))
+
+from core.inference import video_minimax_h3 as h3 # noqa: E402
+
+GIB = 1024**3
+AUTO_FLAGS = (
+ "--offload-to-cpu",
+ "--diffusion-fa",
+ "--max-vram",
+ "-1",
+ "--stream-layers",
+ "--backend",
+ "diffusion=CUDA0,te=CUDA0,vae=CUDA0",
+)
+# The four Hub files of the UD-Q3_K_XL and Q8_0 bundles (bytes on disk).
+Q3_FILES = int((8.90 + 16.97 + 4.85 + 0.56) * GIB)
+Q8_FILES = int((19.97 + 16.97 + 4.85 + 0.56) * GIB)
+
+
+def test_auto_runs_resident_when_the_card_holds_the_bundle():
+ need = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)
+ flags, resident = h3.h3_native_render_flags(
+ AUTO_FLAGS, memory_mode = "auto", free_bytes = need, need_bytes = need, env = {}
+ )
+ assert resident is True
+ assert "--offload-to-cpu" not in flags and "--stream-layers" not in flags
+ # Everything else the load committed is kept, in order: flash attention, the graph-cut budget, the device pin.
+ assert flags == [
+ "--diffusion-fa",
+ "--max-vram",
+ "-1",
+ "--backend",
+ "diffusion=CUDA0,te=CUDA0,vae=CUDA0",
+ ]
+
+
+def test_auto_keeps_offload_when_the_card_is_one_byte_short():
+ need = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)
+ flags, resident = h3.h3_native_render_flags(
+ AUTO_FLAGS, memory_mode = "auto", free_bytes = need - 1, need_bytes = need, env = {}
+ )
+ assert resident is False and flags == list(AUTO_FLAGS)
+
+
[email protected]("free, need", [(None, 10 * GIB), (90 * GIB, None), (None, None)])
+def test_an_unreadable_card_or_size_keeps_offload(free, need):
+ flags, resident = h3.h3_native_render_flags(
+ AUTO_FLAGS, memory_mode = "auto", free_bytes = free, need_bytes = need, env = {}
+ )
+ assert resident is False and flags == list(AUTO_FLAGS)
+
+
[email protected]("mode", ["balanced", "low_vram"])
+def test_an_explicit_offload_mode_is_left_as_asked(mode):
+ flags, resident = h3.h3_native_render_flags(
+ AUTO_FLAGS, memory_mode = mode, free_bytes = 500 * GIB, need_bytes = GIB, env = {}
+ )
+ assert resident is False and flags == list(AUTO_FLAGS)
+
+
+def test_flags_that_do_not_offload_are_untouched():
+ fast = ("--diffusion-fa",)
+ flags, resident = h3.h3_native_render_flags(
+ fast, memory_mode = "auto", free_bytes = 500 * GIB, need_bytes = GIB, env = {}
+ )
+ assert resident is False and flags == ["--diffusion-fa"]
+
+
[email protected]("value", ["0", "false", "off", "no"])
+def test_kill_switch(value):
+ flags, resident = h3.h3_native_render_flags(
+ AUTO_FLAGS,
+ memory_mode = "auto",
+ free_bytes = 500 * GIB,
+ need_bytes = GIB,
+ env = {h3.H3_NATIVE_RESIDENT_ENV: value},
+ )
+ assert resident is False and flags == list(AUTO_FLAGS)
+
+
+def test_estimate_covers_the_measured_resident_peaks():
+ # Resident peaks measured with nvidia-smi on a B200, 960x544x124, pinned u1d02858: 33030 MiB (q3), 44318 MiB (q8).
+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) > 33030 * 1024**2
+ assert h3.h3_native_resident_bytes(Q8_FILES, 960, 544, 124) > 44318 * 1024**2
+ # A 48 GB card (the RTX 6000 Ada this was reported on) holds the q3 bundle resident; a 24 GB card does not.
+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) < 47 * GIB
+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) > 23 * GIB
+
+
+def test_estimate_grows_with_the_clip_and_never_shrinks_below_h1():
+ h1 = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)
+ assert h3.h3_native_resident_bytes(Q3_FILES, 1280, 720, 241) > h1
+ assert h3.h3_native_resident_bytes(Q3_FILES, 640, 384, 25) == h1
+
+
+def _video_backend_tests():
+ # The H3 generate fixture lives there; loaded by path because `tests` can resolve to the repo-root package.
+ import importlib.util
+
+ name = "_studio_test_video_backend"
+ if name not in sys.modules:
+ spec = importlib.util.spec_from_file_location(
+ name, Path(__file__).with_name("test_video_backend.py")
+ )
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[name] = module
+ spec.loader.exec_module(module)
+ return sys.modules[name]
+
+
+def _backend_with_files(monkeypatch, tmp_path, calls, *, memory_mode, flags):
+ backend = _video_backend_tests()._h3_native_backend(monkeypatch, calls)
+ paths = {}
+ sizes = {}
+ for name, size in (("diffusion_model", 9), ("llm", 17), ("vae", 5), ("audio_vae", 1)):
+ p = tmp_path / f"{name}.bin"
+ p.write_bytes(b"")
+ paths[name] = str(p)
+ sizes[str(p)] = size * GIB
+ # Not truncate(): NTFS allocates the full 32 GiB per test, which fills a Windows runner's disk.
+ real_getsize = os.path.getsize
+ monkeypatch.setattr(os.path, "getsize", lambda p: sizes.get(str(p)) or real_getsize(p))
+ import dataclasses
+
+ state = backend._state
+ backend._state = dataclasses.replace(
+ state,
+ pipe = h3.MiniMaxH3NativeRuntime(
+ engine = state.pipe.engine, files = SimpleNamespace(**paths), offload_flags = tuple(flags)
+ ),
+ memory_mode = memory_mode,
+ offload_policy = "group",
+ )
+ return backend
+
+
+def test_generate_drops_offload_on_a_card_that_fits(monkeypatch, tmp_path):
+ import core.inference.video as video
+
+ calls: list = []
+ backend = _backend_with_files(
+ monkeypatch, tmp_path, calls, memory_mode = "auto", flags = AUTO_FLAGS
+ )
+ seen = []
+ monkeypatch.setattr(
+ video,
+ "_h3_card_free_bytes",
+ lambda device, ordinal: seen.append((device, ordinal)) or 90 * GIB,
+ )
+ result = backend.generate(prompt = "a fox", width = 960, height = 544)
+ assert seen == [("cuda", None)]
+ assert "--offload-to-cpu" not in calls[0]["offload"] and "--diffusion-fa" in calls[0]["offload"]
+ assert result["offload_policy"] == "none"
+ assert result["memory_mode"] == "auto"
+
+
+def test_generate_keeps_offload_on_a_card_that_does_not(monkeypatch, tmp_path):
+ import core.inference.video as video
+
+ calls: list = []
+ backend = _backend_with_files(
+ monkeypatch, tmp_path, calls, memory_mode = "auto", flags = AUTO_FLAGS
+ )
+ monkeypatch.setattr(video, "_h3_card_free_bytes", lambda device, ordinal: 20 * GIB)
+ result = backend.generate(prompt = "a fox", width = 960, height = 544)
+ assert calls[0]["offload"] == list(AUTO_FLAGS)
+ assert result["offload_policy"] == "group"
+
+
+def test_generate_does_not_probe_the_card_for_balanced(monkeypatch, tmp_path):
+ import core.inference.video as video
+
+ calls: list = []
+ backend = _backend_with_files(
+ monkeypatch, tmp_path, calls, memory_mode = "balanced", flags = AUTO_FLAGS
+ )
+ monkeypatch.setattr(
+ video, "_h3_card_free_bytes", lambda *_a: (_ for _ in ()).throw(AssertionError("probed"))
+ )
+ backend.generate(prompt = "a fox", width = 960, height = 544)
+ assert calls[0]["offload"] == list(AUTO_FLAGS)
diff --git a/studio/backend/tests/test_sd_cpp_install.py b/studio/backend/tests/test_sd_cpp_install.py
index 8ec69bda239..202e6e12860 100644
--- a/studio/backend/tests/test_sd_cpp_install.py
+++ b/studio/backend/tests/test_sd_cpp_install.py
@@ -3112,6 +3112,45 @@ def test_a_serverless_install_is_not_downloaded_again_on_every_later_load(tmp_pa
assert installs == []
+def test_an_old_pin_legacy_server_is_not_reinstalled_over_a_serverless_current_pin(
+ tmp_path, monkeypatch
+):
+ """A legacy server for the RIGHT accelerator but an older pin is superseded once the current root holds the
+ current pin's serverless bundle: not handed back after the upgrade, and not reinstalled on every later load."""
+ bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
+ monkeypatch.delenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", raising = False)
+ old_server = legacy / "sd-bin" / _SERVER
+ old_server.write_bytes(b"old-pin-build")
+ (legacy / sdmod.INSTALL_RECORD).write_text(
+ json.dumps({"accelerator": "cuda", "repo": "r", "tag": "master-1-0000000-u0000000"}),
+ encoding = "utf-8",
+ )
+ current = home / "stable-diffusion.cpp"
+ current.mkdir()
+ (current / ".unsloth-studio-owned").touch()
+ sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
+ sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()
+
+ installs: list[dict] = []
+
+ def _install(**kw):
+ installs.append(kw)
+ sdmod._write_install_record(
+ current, accelerator = "cuda", repo = "r", tag = "t", ships_server = False
+ )
+
+ monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))
+ monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
+ monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
+ monkeypatch.setattr(bk, "_failed_pin_upgrades", set())
+ monkeypatch.setattr(sdmod, "install", _install)
+
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
+ assert len(installs) == 1
+
+
def test_a_matching_legacy_server_is_still_preferred_over_the_one_shot_cli(tmp_path, monkeypatch):
"""The serverless guard must fire only on a MISMATCHED legacy server. One built for the
accelerator being asked for is a working resident server, and dropping to the one-shot CLI
diff --git a/studio/backend/tests/test_sd_cpp_pin_upgrade.py b/studio/backend/tests/test_sd_cpp_pin_upgrade.py
new file mode 100644
index 00000000000..da8c6270813
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_pin_upgrade.py
@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A managed sd.cpp install made for an older pin is upgraded to the pin this Studio ships.
+
+Before this, ensure_sd_cpp_binary / ensure_sd_server_binary reinstalled only a missing, unrunnable or
+wrong-accelerator binary, so moving DEFAULT_TAG reached new installs only: a host that installed the
+2026-08-09 u13b9d92 bundle kept running it after the pin moved to u1d02858 (observed on a benchmark
+host whose Studio pinned u1d02858 while ~/.unsloth/stable-diffusion.cpp still held u13b9d92).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_STUDIO = Path(__file__).resolve().parents[2]
+if str(_STUDIO) not in sys.path:
+ sys.path.insert(0, str(_STUDIO))
+
+import install_sd_cpp_prebuilt as sdmod # noqa: E402
+
+_CLI = "sd-cli.exe" if sys.platform == "win32" else "sd-cli"
+_SERVER = "sd-server.exe" if sys.platform == "win32" else "sd-server"
+
+
+def _tree(tmp_path, monkeypatch, record):
+ import core.inference.sd_cpp_backend as bk
+
+ root = tmp_path / "sd-home" / "stable-diffusion.cpp"
+ (root / "sd-bin").mkdir(parents = True)
+ (root / ".unsloth-studio-owned").touch()
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
+ monkeypatch.delenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", raising = False)
+ if record is not None:
+ (root / sdmod.INSTALL_RECORD).write_text(json.dumps(record), encoding = "utf-8")
+ sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
+ sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()
+ cli = root / "sd-bin" / _CLI
+ cli.write_bytes(b"old-build")
+ server = root / "sd-bin" / _SERVER
+ server.write_bytes(b"old-build")
+ monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
+ monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
+ monkeypatch.setattr(bk, "_usable_or_discard_managed", lambda *_a, **_k: True)
+ monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
+ monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
+ monkeypatch.setattr(bk, "_failed_pin_upgrades", set())
+ return bk, root, cli, server
+
+
+def _recording_install(root, cli, server, installs):
+ def _install(**kwargs):
+ installs.append(kwargs)
+ cli.write_bytes(b"new-build")
+ server.write_bytes(b"new-build")
+ sdmod._write_install_record(
+ root, accelerator = kwargs["accelerator"], repo = "r", tag = sdmod.DEFAULT_TAG
+ )
+ return cli
+
+ return _install
+
+
+OLD = "master-813-bfbef5b-u13b9d92"
+
+
+def test_an_install_for_an_older_pin_is_upgraded_once(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ assert OLD != sdmod.DEFAULT_TAG
+ installs: list = []
+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))
+
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert [k["accelerator"] for k in installs] == ["cuda"]
+ assert cli.read_bytes() == b"new-build"
+ # The record now names the shipped pin: the next load reuses it.
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+ assert len(installs) == 1
+
+
+def test_an_unwritable_record_does_not_redownload_on_every_load(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ import builtins
+
+ def _open(
+ path,
+ mode = "r",
+ *args,
+ **kwargs,
+ ):
+ if "w" in mode and Path(path).name == sdmod.INSTALL_RECORD:
+ raise PermissionError("record held by another writer")
+ return builtins.open(path, mode, *args, **kwargs)
+
+ monkeypatch.setattr(sdmod, "open", _open, raising = False)
+ installs: list = []
+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))
+ for _ in range(3):
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+ assert len(installs) == 1
+ assert OLD in (root / sdmod.INSTALL_RECORD).read_text(encoding = "utf-8")
+
+
+def test_the_server_resolver_upgrades_an_old_pin_too(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ installs: list = []
+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+ assert server.read_bytes() == b"new-build"
+ assert len(installs) == 1
+
+
+def test_the_current_pin_is_never_reinstalled(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(tmp_path, monkeypatch, None)
+ sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = sdmod.DEFAULT_TAG)
+
+ def _install(**_kwargs):
+ raise AssertionError("the shipped pin must not be reinstalled")
+
+ monkeypatch.setattr(sdmod, "install", _install)
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+
+
+ "record",
+ [
+ None, # predates the record
+ {"accelerator": "cuda", "repo": "r"}, # no tag
+ {"accelerator": "cuda", "repo": "r", "tag": ""},
+ ],
+)
+def test_an_install_that_cannot_say_its_pin_is_left_alone(tmp_path, monkeypatch, record):
+ bk, root, cli, server = _tree(tmp_path, monkeypatch, record)
+
+ def _install(**_kwargs):
+ raise AssertionError("unknown is not stale")
+
+ monkeypatch.setattr(sdmod, "install", _install)
+ # cpu: an unrecorded install is not an accelerator mismatch either, so only the pin check could fire.
+ assert bk.ensure_sd_cpp_binary(accelerator = "cpu") == str(cli)
+
+
+def test_a_fallback_install_for_the_current_pin_is_not_redownloaded(tmp_path, monkeypatch):
+ """A host the mirror does not build gets the upstream release (or latest), whose tag can never equal the pin.
+ requested_tag records what the install was FOR, so it is not re-fetched on every load."""
+ bk, root, cli, server = _tree(
+ tmp_path,
+ monkeypatch,
+ {
+ "accelerator": "vulkan",
+ "repo": "leejet/stable-diffusion.cpp",
+ "tag": "master-999-abcdef0",
+ "requested_tag": sdmod.DEFAULT_TAG,
+ },
+ )
+
+ def _install(**_kwargs):
+ raise AssertionError("a fallback install for the current pin is current")
+
+ monkeypatch.setattr(sdmod, "install", _install)
+ assert bk.ensure_sd_cpp_binary(accelerator = "vulkan") == str(cli)
+
+
+def test_an_old_record_holding_the_upstream_form_of_the_pin_is_current(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path,
+ monkeypatch,
+ {"accelerator": "vulkan", "repo": "r", "tag": sdmod.upstream_tag_for(sdmod.DEFAULT_TAG)},
+ )
+ monkeypatch.setattr(
+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("current"))
+ )
+ assert bk.ensure_sd_cpp_binary(accelerator = "vulkan") == str(cli)
+
+
+def test_kill_switch_keeps_the_installed_bundle(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ monkeypatch.setenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", "0")
+ monkeypatch.setattr(
+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("kill switch"))
+ )
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+
+
+def test_tracking_latest_never_counts_as_a_moved_pin(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "")
+ monkeypatch.setattr(
+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("latest"))
+ )
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+
+
+def test_a_failed_pin_upgrade_keeps_the_old_binary_and_stops_retrying(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ attempts: list = []
+
+ def _install(**kwargs):
+ attempts.append(kwargs)
+ raise RuntimeError("offline")
+
+ monkeypatch.setattr(sdmod, "install", _install)
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
+ assert len(attempts) == 1, "a hopeless upgrade is attempted once per process, not once per load"
+ assert cli.read_bytes() == b"old-build"
+
+
+def test_a_failed_upgrade_for_one_accelerator_still_lets_another_upgrade_the_pin(
+ tmp_path, monkeypatch
+):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cpu", "repo": "r", "tag": OLD}
+ )
+ installs: list = []
+ ok = _recording_install(root, cli, server, installs)
+
+ def _install(**kwargs):
+ if kwargs["accelerator"] == "cuda":
+ installs.append(kwargs)
+ raise RuntimeError("no CUDA asset for this host")
+ return ok(**kwargs)
+
+ monkeypatch.setattr(sdmod, "install", _install)
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+ assert cli.read_bytes() == b"old-build"
+ assert bk.ensure_sd_cpp_binary(accelerator = "cpu") == str(cli)
+ assert [k["accelerator"] for k in installs] == ["cuda", "cpu"]
+ assert cli.read_bytes() == b"new-build"
+
+
+def test_no_upgrade_while_the_managed_tree_is_in_use(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
+ monkeypatch.setattr(
+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("in use"))
+ )
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+
+
+def test_a_user_supplied_binary_is_never_upgraded(tmp_path, monkeypatch):
+ bk, root, cli, server = _tree(
+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}
+ )
+ (root / ".unsloth-studio-owned").unlink()
+ monkeypatch.setattr(
+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("not ours"))
+ )
+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
+
+
+def test_new_records_carry_the_pin_they_were_made_for(tmp_path, monkeypatch):
+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
+ sdmod._write_install_record(tmp_path, accelerator = "cuda", repo = "r", tag = "whatever-it-got")
+ rec = sdmod.read_install_record(tmp_path)
+ assert rec["requested_tag"] == sdmod.DEFAULT_TAG
+ assert sdmod.install_is_stale(tmp_path) is False
+ monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "master-999-0000000-u0000000")
+ assert sdmod.install_is_stale(tmp_path) is True
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 75319e82518..ac7a2b69c9c 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -3649,6 +3649,21 @@ def test_direct_h3_native_load_uses_sd_cpp_path(monkeypatch):
assert calls[0]["gguf_filename"] == "minimax_h3_fl2va-Q4_K_M.gguf"
+def test_direct_h3_native_load_hands_speed_mode_to_the_sd_cpp_path(monkeypatch):
+ backend = VideoBackend()
+ calls = []
+ monkeypatch.setattr("core.inference.video._ensure_mp4_encoder_available", lambda: None)
+ monkeypatch.setattr(backend, "_run_load_h3_native", lambda **kwargs: calls.append(kwargs))
+ backend.load_pipeline(
+ "leejet/MiniMax-H3-GGUF",
+ gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
+ family_override = "minimax-h3",
+ model_kind = "gguf",
+ speed_mode = "max",
+ )
+ assert calls and calls[0]["speed_mode"] == "max"
+
+
def test_h3_native_load_claims_the_companion_repos_before_the_preflight(monkeypatch, tmp_path):
# asset_repos stops the delete-cached guard dropping the H3 companion repos mid-load, and the
# preflight can spend minutes installing the sd-cli prebuilt. A delete admitted in that window
@@ -4017,6 +4032,7 @@ def _load_h3_native_offload(
help_text,
accelerator = True,
memory_mode = None,
+ speed_mode = None,
):
"""Run the native H3 load against a stubbed sd-cli and hand back its committed offload flags.
@@ -4074,6 +4090,7 @@ def _load_h3_native_offload(
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
memory_mode = memory_mode,
+ speed_mode = speed_mode,
)
assert backend._state is not None
return backend._state, list(backend._state.pipe.offload_flags)
@@ -4117,6 +4134,97 @@ def test_h3_native_drops_stream_layers_without_cpu_offload(monkeypatch, tmp_path
assert "--stream-layers" not in offload
+_SAGE_HELP = _GRAPH_CUT_HELP + " --sage-attn use native CUDA SageAttention\n"
+
+
+def test_h3_native_sage_attention_only_on_speed_max(monkeypatch, tmp_path):
+ """SageAttention is lossy (INT8 QK^T), so it rides only on an explicit speed_mode="max"."""
+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
+ state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
+ )
+ assert offload[-1] == "--sage-attn"
+ assert state.attention_backend == "sage"
+ assert state.speed_mode == "max" and state.resolved["speed_mode"]["value"] == "max"
+ for mode in (None, "default", "off"):
+ state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode
+ )
+ assert "--sage-attn" not in offload, mode
+ assert state.attention_backend == "flash"
+ assert state.speed_mode == "off"
+
+
+def test_h3_native_sage_attention_needs_the_flag_and_honours_the_veto(monkeypatch, tmp_path):
+ """An older prebuilt (u13b9d92) has no --sage-attn, and sd-cli exits on an unknown option."""
+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
+ _state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, speed_mode = "max"
+ )
+ assert "--sage-attn" not in offload
+ monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")
+ _state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
+ )
+ assert "--sage-attn" not in offload
+
+
+def test_h3_native_speed_max_takes_the_bf16_cublas_path(monkeypatch, tmp_path):
+ """speed_mode=max also hands sd-cli GGML_CUDA_QUANT_CUBLAS_MIN_BATCH; every other mode launches with no extra env."""
+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
+ monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
+ state, _offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
+ )
+ assert dict(state.pipe.env) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
+ for mode in (None, "default", "off"):
+ state, _offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode
+ )
+ assert state.pipe.env == (), mode
+ # The veto that drops sage drops this too, and a value the user exported (0 included) is never overridden.
+ monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")
+ state, _offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
+ )
+ assert state.pipe.env == ()
+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
+ monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")
+ state, _offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
+ )
+ assert state.pipe.env == ()
+
+
+def test_h3_native_generate_hands_the_runtime_env_to_sd_cli(monkeypatch):
+ import dataclasses
+
+ calls: list = []
+ backend = _h3_native_backend(monkeypatch, calls)
+ backend._state = dataclasses.replace(
+ backend._state,
+ pipe = dataclasses.replace(
+ backend._state.pipe, env = (("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "1024"),)
+ ),
+ )
+ backend.generate(prompt = "a fox", width = 960, height = 544)
+ assert calls[0]["env"] == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
+ calls.clear()
+ backend._state = dataclasses.replace(
+ backend._state, pipe = dataclasses.replace(backend._state.pipe, env = ())
+ )
+ backend.generate(prompt = "a fox", width = 960, height = 544)
+ assert calls[0]["env"] is None
+
+
+def test_h3_native_sage_attention_never_on_the_cpu_build(monkeypatch, tmp_path):
+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
+ _state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _SAGE_HELP, accelerator = False, speed_mode = "max"
+ )
+ assert "--sage-attn" not in offload
+
+
def test_h3_native_skips_the_graph_cut_flags_on_an_older_build(monkeypatch, tmp_path):
"""sd-cli exits non-zero on an option it does not know, so emitting these unconditionally
would break every generation on a build that predates the executor."""
diff --git a/studio/install_sd_cpp_prebuilt.py b/studio/install_sd_cpp_prebuilt.py
index 0a2a99369be..7ab25ecaf29 100644
--- a/studio/install_sd_cpp_prebuilt.py
+++ b/studio/install_sd_cpp_prebuilt.py
@@ -100,6 +100,8 @@ def _raw_install_record(root: Path) -> Optional[str]:
# The same, for the bundle's sd-server capability. Memoised alongside the accelerator or not at all: with only half of it remembered, an unwritable record leaves a serverless install looking server-capable, and the load that finds a mismatched legacy server keeps reinstalling.
_INSTALLED_SHIPS_SERVER_MEMO: dict[str, bool] = {}
+# The same for the pin: an unwritable record still names the old one, which re-downloads on every load.
+_INSTALLED_PIN_MEMO: dict[str, tuple[Optional[str], Optional[str]]] = {}
def installed_ships_server(root: Path) -> Optional[bool]:
@@ -119,7 +121,8 @@ def _write_install_record(
) -> None:
"""Record what this install is, so a later ensure_* can tell a CPU bundle from a GPU one. The write itself stays best-effort (a metadata failure must not throw away binaries that extracted correctly) but the answer is memoised either way, so this process never re-installs what it just installed."""
klass = accelerator_class(accelerator)
- rec: dict = {"accelerator": klass, "repo": repo, "tag": tag}
+ # The pin this install was FOR: a fallback (upstream / latest) tag never equals it.
+ rec: dict = {"accelerator": klass, "repo": repo, "tag": tag, "requested_tag": _pinned_tag()}
if ships_server is not None:
rec["ships_server"] = ships_server
_INSTALLED_SHIPS_SERVER_MEMO[str(root)] = ships_server
@@ -130,7 +133,9 @@ def _write_install_record(
with open(root / INSTALL_RECORD, "w", encoding = "utf-8") as f:
json.dump(rec, f)
except OSError as exc:
- _INSTALLED_ACCELERATOR_MEMO[str(root)] = (klass, _raw_install_record(root))
+ snapshot = _raw_install_record(root)
+ _INSTALLED_ACCELERATOR_MEMO[str(root)] = (klass, snapshot)
+ _INSTALLED_PIN_MEMO[str(root)] = (rec["requested_tag"], snapshot)
print(
f"sd-cli: WARNING could not write the install record in {root}: {exc}; "
f"remembering {klass} for this process only",
@@ -138,6 +143,7 @@ def _write_install_record(
)
else:
_INSTALLED_ACCELERATOR_MEMO.pop(str(root), None)
+ _INSTALLED_PIN_MEMO.pop(str(root), None)
def _repo() -> str:
@@ -150,6 +156,28 @@ def _pinned_tag() -> Optional[str]:
return val or None
+def install_is_stale(root: Path) -> bool:
+ """True when ``root`` was installed for another pin. Unknown (no record / tag, tracking latest) is not stale."""
+ want = _pinned_tag()
+ if not want:
+ return False
+ memo = _INSTALLED_PIN_MEMO.get(str(root))
+ if memo is not None:
+ raw = _raw_install_record(root)
+ if raw is None or raw == memo[1]:
+ return memo[0] != want
+ _INSTALLED_PIN_MEMO.pop(str(root), None)
+ rec = read_install_record(root)
+ requested = rec.get("requested_tag")
+ if isinstance(requested, str) and requested:
+ return requested != want
+ have = rec.get("tag")
+ if not isinstance(have, str) or not have:
+ return False
+ # Pre-requested_tag records: the mirror tag, or its upstream release on hosts the mirror does not build.
+ return have not in (want, upstream_tag_for(want))
+
+
def is_mirror_only_tag(tag: Optional[str]) -> bool:
"""True for a ``<upstream tag>-u<id>`` tag, which only the Unsloth mirror can serve: the mirror publishes such a tag when it builds the upstream tree plus the patch set in its ``patches/`` directory, so by construction upstream has no release under that name."""
return bool(tag) and bool(_MIRROR_ONLY_TAG_RE.match(tag))