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: fit MiniMax-H3 GGUF to a Vulkan host's GTT pool before rendering (#13531)

Daniel Hancd8b2ed9bfa6
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index f90f755bf90..024449d6e39 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -529,7 +529,7 @@ def _remember_device_listing(binary: Optional[str], text: Optional[str]) -> None
if not binary:
return
if text is None:
- _LAST_DEVICE_LISTING.pop(binary, None)
+ # Keep the last good listing; readers check (size, mtime_ns), so a changed binary's listing is never served.
return
_LAST_DEVICE_LISTING[binary] = (_binary_stat_identity(binary), text)
@@ -1044,6 +1044,108 @@ def rocm_runtime_resolvable() -> Optional[bool]:
return True
+def rocm_runtime_missing_sonames() -> Optional[list[str]]:
+ """The ROCm runtime libraries the loader cannot open here: [] when all load, None when it cannot be asked
+ (Windows, macOS, no ctypes, an unexpected loader error), which says nothing either way."""
+ if os.name != "posix" or sys.platform == "darwin":
+ return None
+ try:
+ import ctypes
+ except Exception: # noqa: BLE001
+ return None
+ missing = []
+ for soname in _ROCM_RUNTIME_SONAMES:
+ try:
+ ctypes.CDLL(soname)
+ except OSError:
+ missing.append(soname)
+ except Exception: # noqa: BLE001 - an unexpected loader failure establishes nothing
+ return None
+ return missing
+
+
+ACCELERATOR_FALLBACK_CLEAR_HINT = (
+ "to retry the ROCm build after fixing that, clear the record with "
+ "DELETE /api/settings/diffusion-accelerator-fallback (or restart with "
+ "UNSLOTH_DIFFUSION_SD_CPP_VULKAN_FALLBACK=0 to never fall back)"
+)
+
+
+def accelerator_fallback_reason(accelerator: Optional[str]) -> str:
+ """Why the ``accelerator`` build is being replaced, in words a user can act on."""
+ if _accelerator_class_of(accelerator) != "rocm":
+ return "its build did not list a GPU"
+ if os.name == "nt":
+ # The loader cannot be asked ahead of time on Windows; a missing DLL is exit 0xC0000135 with no output.
+ return (
+ "the ROCm build needs the AMD HIP SDK 7.x runtime DLLs (amdhip64_7.dll, hipblas.dll, rocblas.dll) on "
+ "PATH; without them Windows stops it before it prints anything (exit 0xC0000135), or the card's gfx "
+ "target is missing from the prebuilt"
+ )
+ missing = rocm_runtime_missing_sonames()
+ if missing is None:
+ return (
+ "the ROCm build listed no GPU (whether the host ROCm 7 runtime loads could not be checked here, so "
+ "either it is missing or the card's gfx target is not in the prebuilt)"
+ )
+ if missing:
+ return (
+ "the ROCm build needs the host ROCm 7 runtime and the loader cannot find "
+ + ", ".join(missing)
+ + " (install ROCm 7.x userspace or add /opt/rocm/lib to the loader path)"
+ )
+ return (
+ "the ROCm build listed no GPU (the ROCm runtime loads, so the card's gfx target may be missing from the "
+ "prebuilt, or /dev/kfd is not accessible to this user)"
+ )
+
+
+# ggml device-name prefix -> accelerator class, for a build no install record describes.
+_LISTED_DEVICE_CLASSES: dict[str, str] = {
+ "VULKAN": "vulkan",
+ "ROCM": "rocm",
+ "CUDA": "cuda",
+ "SYCL": "sycl",
+ "METAL": "metal",
+ "OPENCL": "opencl",
+}
+
+
+def sd_cpp_listed_device(
+ binary: Optional[str],
+ device_name: Optional[str] = None,
+ *,
+ probe: bool = True,
+) -> "tuple[Optional[str], Optional[str]]":
+ """``(accelerator class, description)`` of the device ``binary`` renders on, from its own ``--list-devices``:
+ ``device_name`` when pinned, else the first non-CPU device (sd.cpp's own default). ``(None, None)`` when the
+ listing is unreadable or names no GPU. What an unowned build (SD_CLI_PATH / UNSLOTH_SD_CPP_PATH) is, since
+ no install record says. ``probe = False`` only reads the listing the last accelerator verdict took of this
+ file (no subprocess)."""
+ if not binary:
+ return None, None
+ text = None
+ seen = _LAST_DEVICE_LISTING.get(binary)
+ if seen is not None and seen[0] == _binary_stat_identity(binary):
+ text = seen[1]
+ elif probe:
+ text = _sd_cpp_probe_output(binary, "--list-devices")
+ if text is None:
+ return None, None
+ for line in text.splitlines():
+ parts = line.split("\t", 1)
+ if len(parts) != 2:
+ continue
+ name = parts[0].strip()
+ klass = _LISTED_DEVICE_CLASSES.get(name.rstrip("0123456789").upper())
+ if klass is None:
+ continue
+ if device_name is not None and name != device_name:
+ continue
+ return klass, parts[1].strip() or None
+ return None, None
+
+
def accelerator_probe_failure_is_decisive(accelerator: Optional[str]) -> bool:
"""Whether a NEGATIVE device probe for ``accelerator`` is explained, so one occurrence is enough.
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 604a78e92a8..ba364b9f96f 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -1381,6 +1381,130 @@ def _physical_card_name(ordinal: Optional[int]) -> "tuple[Optional[str], Optiona
return physical_card_name(ordinal)
+def _release_h3_server_slot(slot: Any, reason: str) -> str:
+ """Release an H3 sd-server slot without waiting on a render: "stopped" (memory freed now), "pending" (mid-render
+ or starting; stops at the render's end, nothing freed yet) or "none" (no server)."""
+ if slot is None:
+ return "none"
+ try:
+ if not slot.release(reason):
+ return "none"
+ return "pending" if slot.is_alive() else "stopped"
+ except Exception as exc: # noqa: BLE001 - a release failure leaves the reading as it was
+ logger.warning("video.h3_native_server_release_failed: %s", exc)
+ return "none"
+
+
+def _h3_offloaded_render_flags(
+ runtime: Any,
+ render_flags: "list[str]",
+ *,
+ render_resident: bool,
+ memory_mode: Optional[str],
+ reuse_live_server: bool = True,
+) -> list[str]:
+ """The flags an H3 native render runs with once Auto chose resident or offloaded. Every offloaded render is
+ re-fitted on live RAM, swap and GTT readings (file reads only) before a process starts, so pressure since the load
+ is caught and memory freed since lifts a refusal; Auto may move the encoder, an explicit mode is only refused. ``reuse_live_server``: a live offloaded sd-server the render will reuse already
+ holds its weights and keeps its own flags; pass False before launching any new process (the one-shot sd-cli),
+ which releases that server and fits afresh."""
+ from .video_minimax_h3 import (
+ H3_NATIVE_RENDER_RUNNING_HINT,
+ h3_native_offloaded_render_flags,
+ )
+
+ from .video_minimax_h3 import h3_native_fit_check_enabled
+
+ inputs = getattr(runtime, "fit_inputs", None)
+ if not h3_native_fit_check_enabled():
+ inputs = None # UNSLOTH_H3_NATIVE_FIT_CHECK=0: no reading, no release, the committed flags as they are
+ if render_resident or "--offload-to-cpu" not in render_flags or inputs is None:
+ if inputs is not None:
+ # A server with other flags is replaced by get() anyway: free it so its pinned RAM is not counted.
+ slot = getattr(runtime, "server_slot", None)
+ live = slot.alive_signature() if slot is not None else None
+ hint = ""
+ if live is not None and tuple(live[2]) != tuple(render_flags):
+ if _release_h3_server_slot(slot, "a resident render needs its memory") == "pending":
+ hint = H3_NATIVE_RENDER_RUNNING_HINT
+ _h3_check_render_overhead(hint)
+ return h3_native_offloaded_render_flags(
+ render_flags,
+ render_resident = render_resident,
+ offloaded_flags = getattr(runtime, "offloaded_flags", None),
+ offload_refusal = getattr(runtime, "offload_refusal", None),
+ )
+ slot = getattr(runtime, "server_slot", None)
+ live = slot.alive_signature() if slot is not None else None
+ if reuse_live_server and live is not None and "--offload-to-cpu" in live[2]:
+ # A reading now would count the server's own weights; check only the per-render host RAM.
+ _h3_check_render_overhead()
+ return list(live[2])
+ released = "none"
+ if live is not None:
+ # Free any server before the reading (a resident one is replaced by slot.get() anyway).
+ released = _release_h3_server_slot(slot, "an offloaded render needs its memory")
+ return _h3_launch_flags(
+ runtime,
+ render_flags,
+ memory_mode,
+ hint = H3_NATIVE_RENDER_RUNNING_HINT if released == "pending" else "",
+ )
+
+
+def _h3_check_render_overhead(hint: str = "") -> None:
+ from .video_minimax_h3 import H3NativeMemoryRefusal, h3_native_render_overhead_refusal
+ refusal = h3_native_render_overhead_refusal()
+ if refusal:
+ raise H3NativeMemoryRefusal(refusal + hint)
+
+
+def _h3_launch_flags(
+ runtime: Any,
+ render_flags: "list[str]",
+ memory_mode: Optional[str],
+ *,
+ hint: str = "",
+) -> list[str]:
+ """The live fit for one process launch, with no server-slot calls (it also runs under the slot's lock, from
+ ``H3NativeServerSlot.get``'s ``pre_spawn``). Auto may move the encoder; an explicit mode runs exactly its flags
+ or is refused. A resident render or a runtime without fit inputs passes through."""
+ from .sd_cpp_args import device_backend_flags
+ from .video_minimax_h3 import H3NativeMemoryRefusal, h3_native_live_fit
+
+ from .video_minimax_h3 import h3_native_fit_check_enabled
+
+ inputs = getattr(runtime, "fit_inputs", None)
+ if inputs is None or not h3_native_fit_check_enabled():
+ return list(render_flags)
+ if "--offload-to-cpu" not in render_flags:
+ # A resident start: its weights go to VRAM (judged by the resident choice), its per-render RAM is checked.
+ _h3_check_render_overhead(hint)
+ return list(render_flags)
+ mode = memory_mode or "auto"
+ fit = h3_native_live_fit(inputs, mode)
+ if fit.refusal:
+ raise H3NativeMemoryRefusal(fit.refusal + hint)
+ if fit.note:
+ logger.info("video.h3_native_memory_fit (launch): %s", fit.note)
+ if mode != "auto":
+ return list(render_flags)
+ flags = tuple(fit.flags)
+ return list(flags + tuple(device_backend_flags(inputs.device_name, list(flags))))
+
+
+def _torch_pci_slot(ordinal: Optional[int]) -> Optional[str]:
+ """``DDDD:BB:DD`` of the torch-visible card at *ordinal* (no function digit: torch does not report it)."""
+ if ordinal is None:
+ return None
+ try:
+ import torch
+ props = torch.cuda.get_device_properties(int(ordinal))
+ return f"{int(props.pci_domain_id):04x}:{int(props.pci_bus_id):02x}:{int(props.pci_device_id):02x}"
+ except Exception: # noqa: BLE001 - unknown means every amdgpu card is a candidate
+ return None
+
+
def _sd_cli_identity(binary: Optional[str]) -> Optional[tuple[int, int]]:
"""``(size, mtime_ns)`` of an sd.cpp binary, or None when it cannot be read.
@@ -2730,6 +2854,13 @@ _NATIVE_CRASH_NEEDLES = (
def video_failure_detail(exc: BaseException, request_shape: Optional[dict[str, Any]] = None) -> str:
"""A user-facing reason for a failed generation, built only from fixed text."""
try:
+ from .video_minimax_h3 import H3NativeMemoryRefusal
+
+ if isinstance(exc, H3NativeMemoryRefusal):
+ return f"{VIDEO_GENERATION_FAILED_MSG} {exc}"
+ native_memory = _native_memory_failure(exc)
+ if native_memory:
+ return f"{VIDEO_GENERATION_FAILED_MSG} {native_memory}"
if _is_out_of_memory(exc):
if (
request_shape is not None
@@ -2752,6 +2883,33 @@ def video_failure_detail(exc: BaseException, request_shape: Optional[dict[str, A
return VIDEO_GENERATION_FAILED_MSG
+# How a Vulkan (radv) device reports running out of memory.
+_NATIVE_DEVICE_LOST_NEEDLES = ("device lost", "errordevicelost", "error_device_lost")
+
+NATIVE_MEMORY_ADVICE = (
+ "Set Memory mode to Low VRAM, pick a smaller resolution (864x480 is the smallest preset), or load a "
+ "smaller quant."
+)
+
+
+def _native_memory_failure(exc: BaseException) -> Optional[str]:
+ """The advice for a native (sd.cpp) renderer that ran out of GPU or GPU-mapped memory, else None."""
+ text = str(exc)
+ lowered = text.lower()
+ if not any(n in lowered for n in ("sd-cli exited", "sd-server", "stable-diffusion.cpp")):
+ return None
+ from .sd_cpp_backend import output_shows_capacity_failure
+
+ if output_shows_capacity_failure(text):
+ return f"The native renderer ran out of GPU or system memory. {NATIVE_MEMORY_ADVICE}"
+ if any(n in lowered for n in _NATIVE_DEVICE_LOST_NEEDLES):
+ return (
+ "The GPU driver reset the device during the render, which usually means it ran out of GPU or "
+ f"GPU-mapped system memory. {NATIVE_MEMORY_ADVICE}"
+ )
+ return None
+
+
def _is_out_of_memory(exc: BaseException) -> bool:
"""Whether ``exc`` is an allocator failure, by name and text rather than by class: torch
raises ``torch.OutOfMemoryError`` on CUDA and a plain RuntimeError on some backends."""
@@ -3734,6 +3892,8 @@ class VideoBackend:
_accelerator_fingerprint,
_install_allowed,
_installed_accelerator_of,
+ ACCELERATOR_FALLBACK_CLEAR_HINT,
+ accelerator_fallback_reason,
accelerator_probe_failure_is_decisive,
accelerator_verdict_keeps_gpu,
usable_or_recorded_failure,
@@ -3745,6 +3905,7 @@ class VideoBackend:
sd_cpp_accelerator_device_verdict,
sd_cpp_device_name_for_ordinal,
sd_cpp_graph_cut_options,
+ sd_cpp_listed_device,
sd_cpp_supports_sage_attn,
)
from .sd_cpp_engine import SdCppEngine
@@ -3788,7 +3949,17 @@ class VideoBackend:
allow_install = _install_allowed() and not local_files_only
# Read back per card, as it is recorded, so one card's failure does not divert another.
selected_card = selected_card_identity(gpu_ordinal)
- accelerator = preferred_accelerator(_install_accelerator_for(target.backend), selected_card)
+ requested_accelerator = _install_accelerator_for(target.backend)
+ accelerator = preferred_accelerator(requested_accelerator, selected_card)
+ if accelerator != requested_accelerator:
+ logger.warning(
+ "video.sd_cpp_accelerator_recorded_fallback: using the %s stable-diffusion.cpp build, "
+ "not %s, because this host recorded the %s build as unable to run; %s",
+ accelerator,
+ requested_accelerator,
+ requested_accelerator,
+ ACCELERATOR_FALLBACK_CLEAR_HINT,
+ )
binary = usable_or_recorded_failure(
ensure_h3_sd_cpp_binary(
allow_install = allow_install,
@@ -3841,9 +4012,11 @@ class VideoBackend:
if fallback_verdict and fallback_class == fallback:
logger.warning(
"video.sd_cpp_accelerator_fallback: the %s stable-diffusion.cpp build "
- "does not run on this host, using the %s build instead",
+ "does not run on this host (%s), using the %s build instead; %s",
accelerator,
+ accelerator_fallback_reason(accelerator),
fallback,
+ ACCELERATOR_FALLBACK_CLEAR_HINT,
)
# Proven only when the own build answered: a timeout is not proof, and a bare
# "CPU only" is proof only when the runtime is provably unloadable here.
@@ -4064,6 +4237,12 @@ class VideoBackend:
if native_device != "cpu" and listed_accelerator is not None
else None
)
+ # What the executable itself renders on: an unowned build (SD_CLI_PATH) has no install record.
+ native_listed_class, native_listed_description = (
+ sd_cpp_listed_device(binary, native_device_name, probe = False)
+ if native_device != "cpu"
+ else (None, None)
+ )
requested_mode = normalize_memory_mode(memory_mode) or "auto"
policy = {
"auto": "none" if native_device == "cpu" else "group",
@@ -4129,9 +4308,111 @@ class VideoBackend:
.strip()
not in ("", "0")
)
+ # Before the pin, so a CPU-moved text encoder is pinned there; Auto commits nothing (a render may go resident).
+ native_fit_note: Optional[str] = None
+ native_fit_flags: Optional[tuple[str, ...]] = None
+ native_fit_refusal: Optional[str] = None
+ native_fit_inputs: Any = None
+ if native_device != "cpu":
+ from .video_minimax_h3 import (
+ H3_NATIVE_RENDER_RUNNING_HINT,
+ H3NativeFitInputs,
+ h3_native_live_fit,
+ h3_native_render_flags,
+ h3_native_resident_bytes,
+ vulkan_device_is_amd,
+ )
+
+ def _size(path: Any) -> int:
+ try:
+ return os.path.getsize(path) if path else 0
+ except OSError:
+ return 0
+
+ # The build's own listing first: the install record names only builds Studio installed.
+ fit_accelerator = (
+ native_listed_class
+ or (decided_accelerator if isinstance(decided_accelerator, str) else None)
+ or accelerator
+ )
+ check_gtt = fit_accelerator == "vulkan" and vulkan_device_is_amd(
+ native_listed_description
+ )
+ # Everything a re-fit needs, resolved now (the PCI reading included) so later readings are file reads.
+ native_fit_inputs = H3NativeFitInputs(
+ base_flags = tuple(native_offload),
+ accelerator = fit_accelerator,
+ check_gtt = check_gtt,
+ # The torch card is the Vulkan device only when the pin resolved; otherwise sd.cpp picks its own,
+ # so no slot is named and the tightest amdgpu card is read.
+ gtt_pci_slot = _torch_pci_slot(native_ordinal)
+ if check_gtt and native_device_name
+ else None,
+ dit_bytes = _size(resolved[0]),
+ te_bytes = _size(resolved[1]),
+ vae_bytes = _size(resolved[2]) + _size(resolved[3]),
+ device_name = native_device_name,
+ )
+ fit = h3_native_live_fit(native_fit_inputs, requested_mode)
+ release_pending = False
+ if fit.refusal or fit.note:
+ # Free the replaced model's idle sd-server (it respawns on demand) and re-measure.
+ released = self._release_native_server(
+ "a new MiniMax-H3 load is measuring host memory"
+ )
+ if released == "stopped":
+ fit = h3_native_live_fit(native_fit_inputs, requested_mode)
+ release_pending = released == "pending"
+ if fit.refusal and release_pending:
+ fit = dataclasses.replace(fit, refusal = fit.refusal + H3_NATIVE_RENDER_RUNNING_HINT)
+ # An outgoing diffusers model's memory is freed only at commit, so the pre-launch live fit decides, not this.
+ with self._lock:
+ outgoing = self._state
+ outgoing_in_process = (
+ outgoing is not None and getattr(outgoing, "engine", None) != "sd_cpp"
+ )
+ if fit.refusal and outgoing_in_process:
+ logger.warning(
+ "video.h3_native_memory_fit: deferred to the first render, after the outgoing in-process "
+ "model is unloaded: %s",
+ fit.refusal,
+ )
+ if requested_mode == "auto" and (fit.refusal or fit.note):
+ # Auto decides resident vs offloaded at render time; refuse only if even the smallest clip cannot fit.
+ fam_presets = [p for p in (fam.resolution_presets or ()) if len(p) == 2]
+ small_w, small_h = (
+ min(fam_presets, key = lambda p: p[0] * p[1]) if fam_presets else (864, 480)
+ )
+ small_frames = fam.min_num_frames or fam.default_num_frames or 1
+ resident_need = h3_native_resident_bytes(
+ sum(_size(p) for p in resolved[:4]), small_w, small_h, small_frames
+ )
+ _flags, could_be_resident = h3_native_render_flags(
+ native_offload,
+ memory_mode = requested_mode,
+ free_bytes = _h3_card_free_bytes(native_device, native_ordinal),
+ need_bytes = resident_need,
+ )
+ if fit.refusal and not could_be_resident and not outgoing_in_process:
+ raise RuntimeError(fit.refusal)
+ native_fit_refusal = fit.refusal
+ if fit.note:
+ native_fit_flags = tuple(fit.flags)
+ native_fit_note = f"{fit.note} (applied when a render is offloaded)"
+ else:
+ if fit.refusal and not outgoing_in_process:
+ raise RuntimeError(fit.refusal)
+ # An explicit mode's flags are never altered: the fit only refuses them.
+ native_fit_note = fit.note
+ if native_fit_note:
+ logger.warning("video.h3_native_memory_fit: %s", native_fit_note)
# 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)))
+ if native_fit_flags is not None:
+ native_fit_flags += tuple(
+ device_backend_flags(native_device_name, list(native_fit_flags))
+ )
from .video_minimax_h3 import (
H3NativeServerSlot,
MiniMaxH3NativeRuntime,
@@ -4154,6 +4435,9 @@ class VideoBackend:
selected_card = selected_card,
files = native_files,
offload_flags = native_offload,
+ offloaded_flags = native_fit_flags,
+ offload_refusal = native_fit_refusal,
+ fit_inputs = native_fit_inputs,
env = native_env,
cudnn = native_cudnn,
server_slot = (
@@ -4206,7 +4490,13 @@ class VideoBackend:
resolved = build_resolved_record(
{
"family_override": _family_override_resolved(family_override, fam),
- "memory_mode": (memory_mode, policy, "native model offload"),
+ "memory_mode": (
+ memory_mode,
+ policy,
+ f"native model offload; {native_fit_note}"
+ if native_fit_note
+ else "native model offload",
+ ),
"speed_mode": (
speed_mode,
SPEED_MAX if h3_sage else SPEED_OFF,
@@ -10733,9 +11023,10 @@ class VideoBackend:
cancel: threading.Event,
flags: Optional[list[str]] = None,
env: Optional[dict[str, str]] = None,
+ memory_mode: Optional[str] = None,
) -> Optional[Path]:
"""Render one MiniMax-H3 clip on the runtime's resident sd-server, spawned with this render's sd-cli ``flags`` /
- ``env``.
+ ``env``; a server that has to be started is fitted on live readings first (``memory_mode``).
Returns the written container, or None for the one-shot sd-cli: no slot, kill switch, reference video / audio,
or a server that cannot start, lacks vid_gen, or died (the runtime then stays one-shot). Every fallback first
@@ -10746,6 +11037,7 @@ class VideoBackend:
from .sd_cpp_args import build_vid_gen_request, h3_server_eligible
from .sd_cpp_engine import SdCppCancelled
from .sd_cpp_server import SdCppServerUnsupported
+ from .video_minimax_h3 import H3NativeMemoryRefusal
from .video_minimax_h3 import h3_native_server_enabled
slot = getattr(runtime, "server_slot", None)
@@ -10777,8 +11069,15 @@ class VideoBackend:
slot.begin_render()
try:
try:
- server = slot.get(render_flags, render_env, cancel_event = cancel)
- except SdCppCancelled:
+ server = slot.get(
+ render_flags,
+ render_env,
+ cancel_event = cancel,
+ pre_spawn = functools.partial(
+ _h3_launch_flags, runtime, render_flags, memory_mode
+ ),
+ )
+ except (SdCppCancelled, H3NativeMemoryRefusal):
raise
except Exception as exc: # noqa: BLE001 - any start failure leaves the one-shot path
if cancel.is_set():
@@ -10887,6 +11186,10 @@ class VideoBackend:
free_bytes = free,
need_bytes = need,
)
+ # The GTT fit the load prepared for an offloaded Auto render; a resident one never needed it.
+ render_flags = _h3_offloaded_render_flags(
+ runtime, render_flags, render_resident = render_resident, memory_mode = state.memory_mode
+ )
if seed is None:
seed = random.SystemRandom().randrange(0, 2**53)
started = time.monotonic()
@@ -11007,8 +11310,18 @@ class VideoBackend:
cancel = cancel,
flags = render_flags,
env = dict(runtime.env),
+ memory_mode = state.memory_mode,
)
if generated is None:
+ # A new process (reference video / audio, no server, or a server that could not serve):
+ # fit it on live readings, never on flags a live server was shortcut to.
+ render_flags = _h3_offloaded_render_flags(
+ runtime,
+ render_flags,
+ render_resident = render_resident,
+ memory_mode = state.memory_mode,
+ reuse_live_server = False,
+ )
generated = runtime.engine.generate_video(
runtime.files,
video_params,
@@ -11182,6 +11495,16 @@ class VideoBackend:
# ── teardown + status ────────────────────────────────────────────────────
+ def _release_native_server(self, reason: str) -> str:
+ """Stop the committed model's idle H3 sd-server, keeping the model itself loaded (the slot respawns on its
+ next render). "stopped" when its memory is freed now, "pending" when it is mid-render (or starting) and will
+ stop at the render's end, "none" when there was no server. Never waits on a render."""
+ with self._lock:
+ state = self._state
+ return _release_h3_server_slot(
+ getattr(getattr(state, "pipe", None), "server_slot", None), reason
+ )
+
def _teardown_state_locked(self) -> None:
"""Free the committed state. The caller holds _generate_lock (no generation
in flight) AND _lock, so the whole teardown is one atomic step: a generation
diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.py
index a2ab6120e24..5786faa39c2 100644
--- a/studio/backend/core/inference/video_minimax_h3.py
+++ b/studio/backend/core/inference/video_minimax_h3.py
@@ -176,6 +176,18 @@ def _proc_status_kb(fields: tuple[str, ...]) -> Optional[dict[str, int]]:
return found if len(found) == len(fields) else None
+def h3_native_host_available_bytes() -> int:
+ """Host RAM a native (sd-cli / sd-server) render can still take: available RAM, cgroup-capped. Unlike
+ ``h3_host_capacity_bytes`` nothing this process holds is added back: the render is a separate process and
+ reuses none of it."""
+ from utils import host_memory
+
+ usable_mib = host_memory.usable_host_ram_mib()
+ if usable_mib is None:
+ raise RuntimeError("available host RAM could not be read")
+ return max(int(usable_mib), 0) << 20
+
+
def h3_process_held_host_bytes() -> int:
"""Host bytes this process holds that a render reuses: RssAnon + RssShmem (pinned copies are shmem). File-backed
pages are left out: MemAvailable already counts them as reclaimable. Off Linux, the whole RSS."""
@@ -1355,6 +1367,364 @@ def h3_native_render_flags(
return [f for f in flags if f not in _H3_STREAM_ONLY_FLAGS], True
+# --offload-to-cpu pins GPU-run weights in the device host buffer (GTT on Vulkan/radv, capped by TTM pages_limit,
+# overflow = "device lost"); --clip-on-cpu modules use plain RAM. Measured Q4_K, 864x480x124: 31.35 vs 15.49 GiB pinned.
+H3_NATIVE_PINNED_MARGIN_BYTES = 1 << 30
+# sd-cli's own host use beyond the weights (CPU compute buffers, decoded frames, audio), and Studio itself.
+H3_NATIVE_HOST_OVERHEAD_BYTES = 3 << 30
+H3_NATIVE_FIT_ENV = "UNSLOTH_H3_NATIVE_FIT_CHECK"
+# Published sizes of the smallest pair (minimax_h3_fl2va_pruned-Q2_K + its Q2_K_M encoder), for the refusal text.
+H3_NATIVE_Q2_PAIR_BYTES = (int(6.26 * 1024**3), int(12.2 * 1024**3))
+
+
+def _sysfs_int(path: Path) -> Optional[int]:
+ try:
+ return int(path.read_text(encoding = "utf-8").strip(), 0)
+ except (OSError, ValueError):
+ return None
+
+
+def _sysfs_pci_slot(device_dir: Path) -> Optional[str]:
+ """``DDDD:BB:DD.F`` of a DRM card's PCI device, lower-cased, or None."""
+ try:
+ for line in (device_dir / "uevent").read_text(encoding = "utf-8").splitlines():
+ if line.startswith("PCI_SLOT_NAME="):
+ return line.split("=", 1)[1].strip().lower() or None
+ except OSError:
+ pass
+ try:
+ name = Path(os.path.realpath(device_dir)).name.lower()
+ except OSError:
+ return None
+ return name if name.count(":") == 2 else None
+
+
+def h3_native_fit_check_enabled(env: Optional[dict] = None) -> bool:
+ """The one kill switch for every H3 native memory guard (UNSLOTH_H3_NATIVE_FIT_CHECK=0 turns them all off)."""
+ environ = env if env is not None else os.environ
+ return str(environ.get(H3_NATIVE_FIT_ENV, "")).strip().lower() not in (
+ "0",
+ "false",
+ "no",
+ "off",
+ )
+
+
+def amdgpu_gtt_reading(
+ pci_slot: Optional[str] = None, sysfs_root: str = "/sys"
+) -> "tuple[Optional[int], bool]":
+ """``(free GTT, use known)`` from ONE pass over sysfs, so both halves describe the same reading.
+
+ TTM's page limit is shared by every amdgpu device, so what is left is the pool's size less the GTT used on ALL
+ amdgpu cards, not only on the selected one. The pool's size is the ``mem_info_gtt_total`` of the card at
+ ``pci_slot`` (``DDDD:BB:DD.F``, or ``DDDD:BB:DD`` for any function), or the smallest total when the slot is
+ unknown; that bound is never above the selected card's own ``total - used``. A card whose use cannot be read
+ makes ``use known`` False. ``(None, True)`` when no amdgpu card, or none at that slot, reports a total."""
+ want = pci_slot.lower() if pci_slot else None
+ selected_total: Optional[int] = None
+ smallest_total: Optional[int] = None
+ used_all = 0
+ known = True
+ for total_path in Path(sysfs_root, "class", "drm").glob("card*/device/mem_info_gtt_total"):
+ device = total_path.parent
+ if _sysfs_int(device / "vendor") != 0x1002:
+ continue
+ total = _sysfs_int(total_path)
+ if not total or total <= 0:
+ continue
+ used = _sysfs_int(device / "mem_info_gtt_used")
+ if used is None or used < 0:
+ known = False
+ used = 0
+ used_all += used
+ smallest_total = total if smallest_total is None else min(smallest_total, total)
+ if want is not None:
+ slot = _sysfs_pci_slot(device)
+ if slot == want or (slot or "").startswith(want + "."):
+ selected_total = total if selected_total is None else min(selected_total, total)
+ pool = selected_total if want is not None else smallest_total
+ if pool is None:
+ return None, True
+ return max(pool - used_all, 0), known
+
+
+def amdgpu_gtt_free_bytes(
+ pci_slot: Optional[str] = None, sysfs_root: str = "/sys"
+) -> Optional[int]:
+ return amdgpu_gtt_reading(pci_slot, sysfs_root)[0]
+
+
+def amdgpu_gtt_used_unknown(pci_slot: Optional[str] = None, sysfs_root: str = "/sys") -> bool:
+ return not amdgpu_gtt_reading(pci_slot, sysfs_root)[1]
+
+
+def vulkan_device_is_amd(description: Optional[str]) -> bool:
+ """Whether a ggml Vulkan device description names an AMD GPU (RADV, AMDVLK, or the Radeon marketing name)."""
+ text = (description or "").lower()
+ return any(token in text for token in ("radv", "amd", "radeon"))
+
+
+class H3NativeMemoryRefusal(RuntimeError):
+ """A render refused because it cannot fit; its message is built only from fixed text and sizes."""
+
+
+def h3_native_offloaded_render_flags(
+ render_flags: "list[str]",
+ *,
+ render_resident: bool,
+ offloaded_flags: Optional["tuple[str, ...]"],
+ offload_refusal: Optional[str],
+) -> list[str]:
+ """The flags a render runs with once Auto has chosen between resident and offloaded: a resident render keeps
+ its own, an offloaded one takes the GTT-fitted set the load prepared, or is refused when none fits."""
+ if render_resident or "--offload-to-cpu" not in render_flags:
+ return list(render_flags)
+ if offload_refusal:
+ raise H3NativeMemoryRefusal(offload_refusal)
+ return list(offloaded_flags) if offloaded_flags else list(render_flags)
+
+
+@dataclass(frozen = True)
+class H3NativeFit:
+ flags: tuple[str, ...]
+ # Why the flags changed, for the log and the resolved record; None when they did not.
+ note: Optional[str] = None
+ # A user-facing reason to refuse the load, or None.
+ refusal: Optional[str] = None
+
+
+def _gib(value: int) -> str:
+ return f"{value / 1024**3:.1f} GiB"
+
+
+def h3_native_memory_fit(
+ flags: "tuple[str, ...] | list[str]",
+ *,
+ accelerator: Optional[str],
+ memory_mode: Optional[str],
+ dit_bytes: int,
+ te_bytes: int,
+ vae_bytes: int,
+ pinned_free_bytes: Optional[int],
+ host_ram_bytes: Optional[int],
+ host_swap_bytes: int = 0,
+ pinned_used_unknown: bool = False,
+ env: Optional[dict] = None,
+) -> H3NativeFit:
+ """Fit offloaded sd-cli flags to the host: pinned weights must fit RAM alone (swap covers only CPU-run modules)
+ and ``pinned_free_bytes`` (free GTT, None skips). ``auto`` may move the text encoder to the CPU; else refuse."""
+ flags = tuple(flags)
+ if not h3_native_fit_check_enabled(env):
+ return H3NativeFit(flags)
+ if "--offload-to-cpu" not in flags:
+ return H3NativeFit(flags)
+ mode = memory_mode or "auto"
+ vae_on_cpu = "--vae-on-cpu" in flags
+ te_given = "--clip-on-cpu" in flags
+ total = dit_bytes + te_bytes + vae_bytes
+ overhead = H3_NATIVE_HOST_OVERHEAD_BYTES
+ swap = max(int(host_swap_bytes or 0), 0)
+ vulkan_gtt = (accelerator or "").strip().lower() == "vulkan" and pinned_free_bytes is not None
+ budget = int(pinned_free_bytes) - H3_NATIVE_PINNED_MARGIN_BYTES if vulkan_gtt else None
+
+ def pinned(te_on_cpu: bool) -> int:
+ return dit_bytes + (0 if te_on_cpu else te_bytes) + (0 if vae_on_cpu else vae_bytes)
+
+ def host_problem(te_on_cpu: bool) -> Optional[str]:
+ if host_ram_bytes is None:
+ return None
+ if pinned(te_on_cpu) + overhead > host_ram_bytes:
+ return "pinned"
+ if total + overhead > host_ram_bytes + swap:
+ return "total"
+ return None
+
+ def gtt_ok(te_on_cpu: bool) -> bool:
+ if budget is None:
+ return True
+ # Unreadable GTT use: the pool is only an upper bound, so admit only a user-chosen small set (Low VRAM).
+ return pinned(te_on_cpu) <= budget and (te_given or not pinned_used_unknown)
+
+ def ok(te_on_cpu: bool) -> bool:
+ return host_problem(te_on_cpu) is None and gtt_ok(te_on_cpu)
+
+ if ok(te_given):
+ return H3NativeFit(flags)
+ ram = _gib(int(host_ram_bytes)) if host_ram_bytes is not None else "unknown"
+ limit = _gib(int(pinned_free_bytes)) if vulkan_gtt else None
+ if (
+ pinned_used_unknown
+ and budget is not None
+ and not te_given
+ and host_problem(True) is None
+ and pinned(True) <= budget
+ ):
+ # Fail closed (Auto included) while the encoder stays on the GPU: free GTT is unknowable.
+ return H3NativeFit(
+ flags,
+ refusal = (
+ f"MiniMax-H3 GGUF could not read how much of this card's GPU-accessible system memory (GTT) is in "
+ f"use, so it cannot check that the {_gib(pinned(False))} it maps here fits the {limit} pool. Set "
+ f"Memory mode to Low VRAM, which runs the text encoder on the CPU ({_gib(pinned(True))})."
+ ),
+ )
+ if not te_given and ok(True):
+ if not gtt_ok(False):
+ note = (
+ f"text encoder on the CPU: the Vulkan build keeps GPU-run weights in GPU-mapped system memory "
+ f"(GTT), {_gib(pinned(False))} here against {limit} free"
+ )
+ refusal = (
+ f"MiniMax-H3 GGUF cannot run in this memory mode on the Vulkan build: it maps "
+ f"{_gib(pinned(False))} of weights into GPU-accessible system memory (GTT), and {limit} of it is "
+ f"free. Set Memory mode to Auto or Low VRAM, which runs the text encoder on the CPU "
+ f"({_gib(pinned(True))})."
+ )
+ else:
+ note = (
+ f"text encoder on the CPU: GPU-run weights are held in page-locked system RAM that cannot be "
+ f"swapped, {_gib(pinned(False) + overhead)} here against {ram} of RAM available"
+ )
+ refusal = (
+ f"MiniMax-H3 GGUF cannot run in this memory mode: it locks {_gib(pinned(False) + overhead)} of "
+ f"weights in system RAM, which cannot be swapped, and {ram} of RAM is available. Set Memory mode "
+ f"to Auto or Low VRAM, which runs the text encoder on the CPU ({_gib(pinned(True) + overhead)} "
+ f"locked)."
+ )
+ if mode == "auto":
+ return H3NativeFit(flags + ("--clip-on-cpu",), note = note)
+ return H3NativeFit(flags, refusal = refusal)
+ q2_dit, q2_te = H3_NATIVE_Q2_PAIR_BYTES
+ q2_pinned = q2_dit + (0 if vae_on_cpu else vae_bytes)
+ q2_total = q2_dit + q2_te + vae_bytes + overhead
+ problem = host_problem(True)
+ if problem == "total":
+ smaller = (
+ f" The Q2_K denoiser (with its Q2_K_M encoder) needs about {_gib(q2_total)}."
+ if q2_total < total + overhead
+ else ""
+ )
+ return H3NativeFit(
+ flags,
+ refusal = (
+ f"MiniMax-H3 GGUF keeps its denoiser, text encoder and VAEs in system RAM while it renders: about "
+ f"{_gib(total + overhead)} for this quant, and {ram} of RAM plus {_gib(swap)} of swap is "
+ f"available. Close other applications or load a smaller quant.{smaller}"
+ ),
+ )
+ if problem == "pinned":
+ smaller = (
+ f" The Q2_K denoiser locks about {_gib(q2_pinned + overhead)} with Memory mode Low VRAM."
+ if q2_pinned < pinned(True)
+ else ""
+ )
+ return H3NativeFit(
+ flags,
+ refusal = (
+ f"MiniMax-H3 GGUF locks the weights of its GPU-run parts in system RAM, which cannot be swapped: "
+ f"about {_gib(pinned(True) + overhead)} even with the text encoder on the CPU, and {ram} of RAM "
+ f"is available. Close other applications or load a smaller quant.{smaller}"
+ ),
+ )
+ smaller = (
+ f" The Q2_K denoiser needs about {_gib(q2_pinned)} with Memory mode Low VRAM."
+ if budget is not None and q2_pinned <= budget
+ else ""
+ )
+ return H3NativeFit(
+ flags,
+ refusal = (
+ f"MiniMax-H3 GGUF does not fit this system on the Vulkan build: even with the text encoder on the CPU it "
+ f"maps {_gib(pinned(True))} of weights into GPU-accessible system memory (GTT), and {limit} of it is free "
+ f"(the pool is half of system RAM by default; raise it with the ttm.pages_limit kernel parameter).{smaller}"
+ ),
+ )
+
+
+@dataclass(frozen = True)
+class H3NativeFitInputs:
+ """What ``h3_native_live_fit`` needs that does not change between renders, resolved once at load (the device
+ listing and torch PCI reading included), so a re-fit reads only files."""
+
+ base_flags: tuple[str, ...] # the committed offload flags BEFORE the device pin
+ accelerator: Optional[str]
+ check_gtt: bool
+ gtt_pci_slot: Optional[str]
+ dit_bytes: int
+ te_bytes: int
+ vae_bytes: int
+ device_name: Optional[str]
+
+
+def h3_native_host_budgets() -> "tuple[Optional[int], int]":
+ """(RAM, swap) a native render may still take: RAM cgroup-capped, without Studio's own RSS, and on cgroup v1 no
+ more than the RAM+swap (memsw) headroom; swap bounded by the cgroup against that RAM budget, so the two never
+ sum past what the cgroup can charge. (None, 0) only when RAM cannot be read; unreadable swap is 0 swap."""
+ try:
+ ram = h3_native_host_available_bytes()
+ except Exception: # noqa: BLE001 - an unreadable reading skips the host check
+ return None, 0
+ from utils.host_memory import cgroup_swap_allowance_bytes, cgroup_v1_memsw_headroom_bytes
+
+ try:
+ combined = cgroup_v1_memsw_headroom_bytes()
+ except Exception: # noqa: BLE001
+ combined = None
+ if combined is not None:
+ ram = min(ram, combined)
+ try:
+ import psutil
+ free_swap = int(psutil.swap_memory().free)
+ except Exception: # noqa: BLE001 - no swap reading: count none, keep the RAM check
+ free_swap = 0
+ try:
+ swap = cgroup_swap_allowance_bytes(free_swap, ram_budget = ram)
+ except Exception: # noqa: BLE001
+ swap = 0
+ return ram, swap
+
+
+def h3_native_live_fit(inputs: H3NativeFitInputs, memory_mode: Optional[str]) -> H3NativeFit:
+ """``h3_native_memory_fit`` on live RAM, swap and GTT readings: /proc, cgroup and sysfs files only."""
+ ram, swap = h3_native_host_budgets()
+ gtt_free, gtt_known = (
+ amdgpu_gtt_reading(inputs.gtt_pci_slot) if inputs.check_gtt else (None, True)
+ )
+ if inputs.check_gtt and gtt_free is None and inputs.gtt_pci_slot:
+ # The device is AMD but its slot matched no amdgpu card: read the tightest card rather than skip the check.
+ gtt_free, gtt_known = amdgpu_gtt_reading(None)
+ return h3_native_memory_fit(
+ inputs.base_flags,
+ accelerator = inputs.accelerator,
+ memory_mode = memory_mode,
+ dit_bytes = inputs.dit_bytes,
+ te_bytes = inputs.te_bytes,
+ vae_bytes = inputs.vae_bytes,
+ pinned_free_bytes = gtt_free,
+ pinned_used_unknown = not gtt_known,
+ host_ram_bytes = ram,
+ host_swap_bytes = swap,
+ )
+
+
+def h3_native_render_overhead_refusal() -> Optional[str]:
+ """Why a render that places no new weights (a reused server, or a resident render) cannot start: live
+ available RAM (``h3_native_host_budgets``) below the per-render host overhead. None when it fits or RAM cannot
+ be read. File reads only."""
+ if not h3_native_fit_check_enabled():
+ return None
+ ram, _swap = h3_native_host_budgets()
+ if ram is None or ram >= H3_NATIVE_HOST_OVERHEAD_BYTES:
+ return None
+ return (
+ f"A MiniMax-H3 render needs about {_gib(H3_NATIVE_HOST_OVERHEAD_BYTES)} of free system RAM for its frames, "
+ f"audio and CPU buffers, and {_gib(ram)} is available. Close other applications and try again."
+ )
+
+
+H3_NATIVE_RENDER_RUNNING_HINT = " A render on the model being replaced is still running and holds that memory; try again after it finishes."
+
+
def h3_native_hub_files(transformer_filename: str) -> tuple[tuple[str, str], ...]:
validate_h3_transformer_filename(transformer_filename)
return (
@@ -1383,6 +1753,11 @@ class MiniMaxH3NativeRuntime:
cudnn: Any = None
# H3NativeServerSlot, or None for one-shot sd-cli only.
server_slot: Any = None
+ # Auto only: the GTT-fitted flags an OFFLOADED render runs with, and the refusal when none fits.
+ offloaded_flags: Optional[tuple[str, ...]] = None
+ offload_refusal: Optional[str] = None
+ # Auto only: re-fit inputs, so an offloaded render is judged on live readings rather than the load's.
+ fit_inputs: Any = None
# 0 / false / off: every render on a fresh one-shot sd-cli.
@@ -1527,9 +1902,12 @@ class H3NativeServerSlot:
env: "Optional[dict[str, str] | tuple[tuple[str, str], ...]]" = None,
*,
cancel_event: Any = None,
+ pre_spawn: "Optional[Callable[[], Any]]" = None,
) -> Any:
"""The live server for this (flags, env), (re)spawning one if needed. ``cancel_event`` aborts a start: the
- render holds the generate lock through the model load, so unload and Cancel would otherwise wait it out."""
+ render holds the generate lock through the model load, so unload and Cancel would otherwise wait it out.
+ ``pre_spawn`` runs only when a process is about to start, under the slot lock and after any old server has
+ stopped: it returns the flags to start with (a live memory fit) or raises to refuse the start."""
import threading
from .sd_cpp_backend import register_tree_holder, unregister_tree_holder
@@ -1549,6 +1927,10 @@ class H3NativeServerSlot:
)
if cancel_event is not None and cancel_event.is_set():
raise SdCppCancelled("sd-server start was cancelled before launch.")
+ if pre_spawn is not None:
+ # Reuse was decided above, under this lock: from here a process starts, so it is fitted now.
+ flag_tuple = tuple(pre_spawn())
+ wanted = self._signature_for(flag_tuple, env_pairs)
server = SdCppServer(self.server_binary)
managed = is_managed_binary(self.server_binary)
self._server = server
diff --git a/studio/backend/tests/test_h3_native_memory_fit.py b/studio/backend/tests/test_h3_native_memory_fit.py
new file mode 100644
index 00000000000..ee50aa38fc7
--- /dev/null
+++ b/studio/backend/tests/test_h3_native_memory_fit.py
@@ -0,0 +1,833 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""MiniMax-H3 native (sd.cpp) memory fit: the Vulkan GTT pool, the host RAM floor, and the failure text."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference import sd_cpp_backend
+from core.inference.video import video_failure_detail
+from core.inference.video_minimax_h3 import (
+ H3_NATIVE_FIT_ENV,
+ H3NativeMemoryRefusal,
+ amdgpu_gtt_free_bytes,
+ h3_native_memory_fit,
+ h3_native_offloaded_render_flags,
+ vulkan_device_is_amd,
+)
+from utils.host_memory import cgroup_swap_allowance_bytes
+
+GIB = 1024**3
+# The published unsloth/MiniMax-H3-GGUF sizes: Q4_K denoiser, Q4_K_M encoder, video + audio VAE.
+Q4 = dict(dit_bytes = int(10.64 * GIB), te_bytes = int(16.97 * GIB), vae_bytes = int(5.41 * GIB))
+AUTO = ("--offload-to-cpu", "--diffusion-fa", "--max-vram", "-1")
+LOW_VRAM = (
+ "--offload-to-cpu",
+ "--clip-on-cpu",
+ "--diffusion-fa",
+ "--vae-tiling",
+ "--max-vram",
+ "-1",
+)
+# A 48 GiB host: TTM's default pages_limit is half of RAM.
+GTT_48 = 24 * GIB
+
+
+def _fit(
+ flags,
+ mode,
+ *,
+ accelerator = "vulkan",
+ gtt = GTT_48,
+ host = 40 * GIB,
+ sizes = Q4,
+ env = None,
+ swap = 0,
+):
+ return h3_native_memory_fit(
+ flags,
+ accelerator = accelerator,
+ memory_mode = mode,
+ pinned_free_bytes = gtt,
+ host_ram_bytes = host,
+ host_swap_bytes = swap,
+ env = env or {},
+ **sizes,
+ )
+
+
+def test_auto_on_a_48gb_radv_host_runs_the_encoder_on_the_cpu():
+ fit = _fit(AUTO, "auto")
+ assert fit.refusal is None
+ assert fit.flags == AUTO + ("--clip-on-cpu",)
+ assert "GTT" in fit.note and "33.0 GiB" in fit.note
+
+
[email protected]("mode", ["balanced", "fast"])
+def test_an_explicit_mode_that_overflows_gtt_is_refused_naming_the_one_that_fits(mode):
+ fit = _fit(AUTO, mode)
+ assert fit.flags == AUTO
+ assert "Low VRAM" in fit.refusal and "16.0 GiB" in fit.refusal
+
+
+def test_low_vram_fits_a_48gb_radv_host_unchanged():
+ fit = _fit(LOW_VRAM, "low_vram")
+ assert fit == type(fit)(LOW_VRAM)
+
+
+def test_a_pool_too_small_even_for_low_vram_names_the_smaller_quant_and_the_kernel_knob():
+ fit = _fit(LOW_VRAM, "low_vram", gtt = 16 * GIB)
+ assert "Q2_K" in fit.refusal and "ttm.pages_limit" in fit.refusal
+
+
+def test_a_large_pool_changes_nothing():
+ assert _fit(AUTO, "auto", gtt = 64 * GIB).flags == AUTO
+
+
[email protected]("accelerator", ["cuda", "rocm", "cpu", None])
+def test_the_gtt_pool_only_binds_a_vulkan_build(accelerator):
+ fit = _fit(AUTO, "auto", accelerator = accelerator)
+ assert fit.flags == AUTO and fit.refusal is None and fit.note is None
+
+
+def test_no_amdgpu_reading_changes_nothing():
+ assert _fit(AUTO, "auto", gtt = None).flags == AUTO
+
+
+def test_a_resident_render_is_not_judged():
+ resident = ("--diffusion-fa", "--max-vram", "-1")
+ assert _fit(resident, "fast", gtt = 1 * GIB, host = 1 * GIB).flags == resident
+
+
+def test_a_host_without_room_for_the_weights_is_refused_naming_q2():
+ fit = _fit(AUTO, "auto", accelerator = "cuda", host = 30 * GIB)
+ assert "system RAM" in fit.refusal and "Q2_K" in fit.refusal
+
+
+# Denoiser 10, encoder 4, VAEs 2 GiB: 12 GiB pinned with the encoder on the CPU, 15 with sd-cli's overhead.
+SMALL = dict(dit_bytes = 10 * GIB, te_bytes = 4 * GIB, vae_bytes = 2 * GIB)
+# Denoiser 10, encoder 17, VAEs 5 GiB: 15 GiB pinned with the encoder on the CPU, 32 with it on the GPU.
+BIG_TE = dict(dit_bytes = 10 * GIB, te_bytes = 17 * GIB, vae_bytes = 5 * GIB)
+
+
+def test_swap_never_covers_the_pinned_set():
+ """Page-locked host buffers cannot be swapped: 15 GiB locked against 12 GiB of RAM is refused however much swap
+ the cgroup allows."""
+ fit = _fit(LOW_VRAM, "low_vram", accelerator = "cuda", host = 12 * GIB, swap = 500 * GIB, sizes = SMALL)
+ assert "cannot be swapped" in fit.refusal and "12.0 GiB of RAM" in fit.refusal
+
+
+def test_swap_covers_the_pageable_cpu_run_encoder():
+ fit = _fit(AUTO, "auto", accelerator = "cuda", host = 25 * GIB, swap = 20 * GIB, sizes = BIG_TE)
+ assert fit.refusal is None
+ assert fit.flags == AUTO + ("--clip-on-cpu",)
+ assert "page-locked" in fit.note
+
+
+def test_an_explicit_mode_whose_locked_set_overflows_ram_names_low_vram():
+ fit = _fit(AUTO, "balanced", accelerator = "cuda", host = 25 * GIB, swap = 20 * GIB, sizes = BIG_TE)
+ assert "Low VRAM" in fit.refusal and "cannot be swapped" in fit.refusal
+
+
+def test_without_swap_the_whole_set_must_fit_ram():
+ fit = _fit(AUTO, "auto", accelerator = "cuda", host = 25 * GIB, swap = 0, sizes = BIG_TE)
+ assert "RAM plus 0.0 GiB of swap" in fit.refusal
+
+
+def test_the_16gb_card_48gb_host_decision_is_unchanged():
+ """About 42 GiB of a 48 GB host available, no swap, 23.4 GiB of GTT: the encoder still moves for GTT."""
+ fit = _fit(AUTO, "auto", gtt = int(23.4 * GIB), host = 42 * GIB, swap = 0)
+ assert fit.flags == AUTO + ("--clip-on-cpu",) and "GTT" in fit.note
+
+
+def test_the_kill_switch_restores_the_old_flags():
+ fit = _fit(AUTO, "auto", host = 1 * GIB, env = {H3_NATIVE_FIT_ENV: "0"})
+ assert fit.flags == AUTO and fit.refusal is None
+
+
+def _card(
+ root,
+ card,
+ slot,
+ *,
+ total,
+ used = None,
+ vendor = "0x1002",
+):
+ dev = root / "class" / "drm" / card / "device"
+ dev.mkdir(parents = True)
+ (dev / "vendor").write_text(vendor + "\n", encoding = "utf-8")
+ (dev / "uevent").write_text(f"DRIVER=amdgpu\nPCI_SLOT_NAME={slot}\n", encoding = "utf-8")
+ (dev / "mem_info_gtt_total").write_text(f"{total}\n", encoding = "utf-8")
+ if used is not None:
+ (dev / "mem_info_gtt_used").write_text(f"{used}\n", encoding = "utf-8")
+
+
+def test_the_gtt_reading_subtracts_what_is_already_used(tmp_path):
+ _card(tmp_path, "card0", "0000:03:00.0", total = 24 * GIB, used = 5 * GIB)
+ assert amdgpu_gtt_free_bytes(sysfs_root = str(tmp_path)) == 19 * GIB
+
+
+def test_the_gtt_reading_follows_the_selected_card(tmp_path):
+ _card(tmp_path, "card0", "0000:03:00.0", total = 24 * GIB, used = 1 * GIB)
+ _card(tmp_path, "card1", "0000:c5:00.0", total = 24 * GIB, used = 20 * GIB) # the APU
+ # TTM's page limit is shared, so the APU's 20 GiB counts against the selected card's pool too.
+ assert amdgpu_gtt_free_bytes("0000:03:00", sysfs_root = str(tmp_path)) == 3 * GIB
+ assert amdgpu_gtt_free_bytes("0000:03:00.0", sysfs_root = str(tmp_path)) == 3 * GIB
+ # Unknown slot: the smallest pool, less what every card uses.
+ assert amdgpu_gtt_free_bytes(sysfs_root = str(tmp_path)) == 3 * GIB
+ # A slot that is no amdgpu card (an NVIDIA or Intel device) has no pool.
+ assert amdgpu_gtt_free_bytes("0000:81:00", sysfs_root = str(tmp_path)) is None
+
+
+def test_gtt_used_on_another_amd_card_shrinks_the_selected_cards_pool(tmp_path):
+ """APU plus discrete card: TTM's page limit is one pool, so the APU's GTT use is not free for the dGPU."""
+ _card(tmp_path, "card0", "0000:03:00.0", total = 24 * GIB, used = 2 * GIB)
+ _card(tmp_path, "card1", "0000:c5:00.0", total = 24 * GIB, used = 12 * GIB)
+ assert amdgpu_gtt_free_bytes("0000:03:00", sysfs_root = str(tmp_path)) == 10 * GIB
+ # Only the selected card at work: the per-device bound still applies.
+ (tmp_path / "class" / "drm" / "card1" / "device" / "mem_info_gtt_used").write_text("0\n", encoding = "utf-8")
+ assert amdgpu_gtt_free_bytes("0000:03:00", sysfs_root = str(tmp_path)) == 22 * GIB
+
+
+def test_a_non_amd_drm_card_is_never_read(tmp_path):
+ _card(tmp_path, "card0", "0000:00:02.0", total = 8 * GIB, vendor = "0x8086")
+ assert amdgpu_gtt_free_bytes(sysfs_root = str(tmp_path)) is None
+ assert amdgpu_gtt_free_bytes(sysfs_root = str(tmp_path / "none")) is None
+
+
+ "description, amd",
+ [
+ ("AMD Radeon RX 7800 XT (RADV NAVI32)", True),
+ ("AMD Radeon(TM) Graphics (RADV GFX1151)", True),
+ ("Radeon RX 6800", True),
+ ("Intel(R) Arc(tm) A770 Graphics (DG2)", False),
+ ("NVIDIA GeForce RTX 4070 Ti", False),
+ ("llvmpipe (LLVM 17.0.6, 256 bits)", False),
+ (None, False),
+ ],
+)
+def test_only_an_amd_vulkan_device_is_bound_by_gtt(description, amd):
+ assert vulkan_device_is_amd(description) is amd
+
+
+OFFLOADED_FIT = AUTO + ("--clip-on-cpu", "--backend", "diffusion=Vulkan0,te=cpu,vae=Vulkan0")
+
+
+def test_a_resident_auto_render_drops_nothing_and_adds_no_encoder_move():
+ resident = ["--diffusion-fa", "--max-vram", "-1"]
+ assert (
+ h3_native_offloaded_render_flags(
+ resident, render_resident = True, offloaded_flags = OFFLOADED_FIT, offload_refusal = "no"
+ )
+ == resident
+ )
+
+
+def test_an_offloaded_auto_render_takes_the_fitted_flags():
+ assert h3_native_offloaded_render_flags(
+ list(AUTO), render_resident = False, offloaded_flags = OFFLOADED_FIT, offload_refusal = None
+ ) == list(OFFLOADED_FIT)
+ assert h3_native_offloaded_render_flags(
+ list(AUTO), render_resident = False, offloaded_flags = None, offload_refusal = None
+ ) == list(AUTO)
+
+
+def test_an_offloaded_auto_render_that_cannot_fit_is_refused_with_its_reason():
+ with pytest.raises(H3NativeMemoryRefusal) as caught:
+ h3_native_offloaded_render_flags(
+ list(AUTO),
+ render_resident = False,
+ offloaded_flags = None,
+ offload_refusal = "too big for GTT",
+ )
+ detail = video_failure_detail(caught.value)
+ assert detail.endswith("too big for GTT")
+
+
+def _cgroup(
+ tmp_path,
+ files,
+ proc = "0::/user.slice/app.scope\n",
+):
+ root = tmp_path / "cg"
+ for rel, value in files.items():
+ path = root / rel
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text(value + "\n", encoding = "utf-8")
+ root.mkdir(exist_ok = True)
+ (tmp_path / "self").write_text(proc, encoding = "utf-8")
+ return dict(cgroup_root = str(root), proc_self_cgroup = str(tmp_path / "self"))
+
+
+def test_swap_is_bounded_by_the_cgroup_swap_allowance(tmp_path):
+ paths = _cgroup(
+ tmp_path,
+ {
+ "user.slice/app.scope/memory.max": str(48 * GIB),
+ "user.slice/app.scope/memory.swap.max": str(4 * GIB),
+ "user.slice/app.scope/memory.swap.current": str(1 * GIB),
+ },
+ )
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == 3 * GIB
+
+
+def test_swap_max_zero_admits_no_swap(tmp_path):
+ paths = _cgroup(
+ tmp_path,
+ {
+ "user.slice/app.scope/memory.max": str(48 * GIB),
+ "user.slice/app.scope/memory.swap.max": "0",
+ "user.slice/app.scope/memory.swap.current": "0",
+ },
+ )
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == 0
+
+
+def test_an_unlimited_cgroup_keeps_host_free_swap(tmp_path):
+ paths = _cgroup(
+ tmp_path,
+ {"user.slice/app.scope/memory.max": "max", "user.slice/app.scope/memory.swap.max": "max"},
+ )
+ assert cgroup_swap_allowance_bytes(8 * GIB, **paths) == 8 * GIB
+
+
+def test_a_ram_limit_without_swap_accounting_admits_no_swap(tmp_path):
+ paths = _cgroup(tmp_path, {"user.slice/memory.max": str(48 * GIB)})
+ assert cgroup_swap_allowance_bytes(8 * GIB, **paths) == 0
+
+
+def test_cgroup_v1_memsw_headroom_bounds_swap(tmp_path):
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/docker/x/memory.limit_in_bytes": str(32 * GIB),
+ "memory/docker/x/memory.usage_in_bytes": str(10 * GIB),
+ "memory/docker/x/memory.memsw.limit_in_bytes": str(40 * GIB),
+ "memory/docker/x/memory.memsw.usage_in_bytes": str(12 * GIB),
+ },
+ proc = "4:memory:/docker/x\n",
+ )
+ # RAM+swap room 28 GiB minus RAM room 22 GiB.
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == 6 * GIB
+
+
+_RADV_TAIL = (
+ "sd-cli exited 1. Last output:\n"
+ "[V] model manager prepared params backend buffers (295.12 MB, 11 tensors, 1 blocks, RAM) on Vulkan_Host"
+ " --- model_manager.cpp:490\n"
+ "radv/amdgpu: Not enough memory for command submission.\n"
+ "[E] ggml: ggml_vulkan: device lost on Vulkan0\n"
+)
+
+
+def test_the_radv_failure_reads_as_memory_with_the_settings_that_help():
+ detail = video_failure_detail(RuntimeError(_RADV_TAIL))
+ assert "ran out of GPU or system memory" in detail
+ assert "Low VRAM" in detail and "864x480" in detail and "quant" in detail
+
+
+def test_a_bare_device_loss_is_explained_as_likely_memory():
+ detail = video_failure_detail(
+ RuntimeError("sd-cli exited 1. Last output:\nggml_vulkan: device lost")
+ )
+ assert "reset the device" in detail and "Low VRAM" in detail
+
+
+def test_an_unrelated_native_crash_keeps_its_old_text():
+ detail = video_failure_detail(
+ RuntimeError("sd-cli exited -11. Last output:\nSegmentation fault")
+ )
+ assert "renderer stopped unexpectedly" in detail
+
+
+def test_a_torch_oom_keeps_its_old_text():
+ detail = video_failure_detail(RuntimeError("CUDA out of memory. Tried to allocate 2.00 GiB"))
+ assert "smaller resolution, fewer frames, or fewer steps" in detail
+
+
+_V1_SWAP_ROOM = {
+ "memory/p/memory.limit_in_bytes": str(30 * GIB),
+ "memory/p/memory.usage_in_bytes": str(10 * GIB),
+ "memory/p/memory.memsw.limit_in_bytes": str(40 * GIB),
+ "memory/p/memory.memsw.usage_in_bytes": str(10 * GIB),
+}
+
+
+_ENFORCING_CHILD = {
+ "memory/p/c/memory.limit_in_bytes": str(28 * GIB),
+ "memory/p/c/memory.usage_in_bytes": str(8 * GIB),
+ "memory/p/c/memory.memsw.limit_in_bytes": str(100 * GIB),
+ "memory/p/c/memory.memsw.usage_in_bytes": str(8 * GIB),
+}
+
+
+ "swappiness, expected",
+ [
+ # The child sets no limit: its value is irrelevant; the enforcing parent reports none.
+ ({"memory/p/c/memory.swappiness": "0"}, 10 * GIB),
+ # The enforcing parent's 0 governs its own limit reclaim whatever the child says.
+ ({"memory/p/memory.swappiness": "0"}, 0),
+ ({"memory/p/c/memory.swappiness": "60", "memory/p/memory.swappiness": "0"}, 0),
+ ({"memory/p/c/memory.swappiness": "60", "memory/p/memory.swappiness": "60"}, 10 * GIB),
+ # The process's own cgroup counts once it enforces.
+ ({**_ENFORCING_CHILD, "memory/p/c/memory.swappiness": "0"}, 0),
+ ({**_ENFORCING_CHILD, "memory/p/c/memory.swappiness": "60"}, 10 * GIB),
+ ],
+)
+def test_cgroup_v1_swappiness_zero_on_an_enforcing_level_admits_no_swap(
+ tmp_path, swappiness, expected
+):
+ """https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/memory.html#swappiness: 0 keeps a level's limit
+ reclaim from swapping. Any level with a finite limit counts; one without a limit reclaims nothing."""
+ (tmp_path / "cg" / "memory" / "p" / "c").mkdir(parents = True)
+ paths = _cgroup(tmp_path, {**_V1_SWAP_ROOM, **swappiness}, proc = "4:memory:/p/c\n")
+ # RAM room 20 GiB, RAM+swap room 30 GiB: 10 GiB of swap unless swappiness forbids it.
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == expected
+
+
+ "limit, expected",
+ [(str(30 * GIB), 0), ("9223372036854771712", 64 * GIB)],
+)
+def test_cgroup_v1_swappiness_zero_on_a_namespaced_root_counts_when_it_enforces(
+ tmp_path, limit, expected
+):
+ """A v1 container sees its own cgroup as the mount root (/proc/self/cgroup reads "/"); its swappiness 0 counts
+ once that root enforces a limit, while an unlimited host root's value stays irrelevant."""
+ files = {
+ "memory/memory.limit_in_bytes": limit,
+ "memory/memory.usage_in_bytes": str(10 * GIB),
+ "memory/memory.memsw.limit_in_bytes": str(40 * GIB) if expected == 0 else limit,
+ "memory/memory.memsw.usage_in_bytes": str(10 * GIB),
+ "memory/memory.swappiness": "0",
+ }
+ paths = _cgroup(tmp_path, files, proc = "4:memory:/\n")
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == expected
+
+
+def test_the_kill_switch_turns_off_the_per_render_overhead_guard(monkeypatch):
+ from core.inference import video_minimax_h3
+
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (1 << 20, 0))
+ assert video_minimax_h3.h3_native_render_overhead_refusal()
+ monkeypatch.setenv(H3_NATIVE_FIT_ENV, "0")
+ assert video_minimax_h3.h3_native_render_overhead_refusal() is None
+ assert video_minimax_h3.h3_native_fit_check_enabled() is False
+
+
+def test_nested_cgroup_v1_pairs_the_tightest_combined_and_ram_headroom(tmp_path):
+ """Child: 2 GiB RAM room, 12 GiB RAM+swap room. Parent: 20 GiB RAM room, 21 GiB RAM+swap room. The process can
+ use min(12, 21) - min(2, 20) = 10 GiB of swap; per-level differences would say min(10, 1) = 1."""
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/p/memory.limit_in_bytes": str(30 * GIB),
+ "memory/p/memory.usage_in_bytes": str(10 * GIB),
+ "memory/p/memory.memsw.limit_in_bytes": str(40 * GIB),
+ "memory/p/memory.memsw.usage_in_bytes": str(19 * GIB),
+ "memory/p/c/memory.limit_in_bytes": str(8 * GIB),
+ "memory/p/c/memory.usage_in_bytes": str(6 * GIB),
+ "memory/p/c/memory.memsw.limit_in_bytes": str(20 * GIB),
+ "memory/p/c/memory.memsw.usage_in_bytes": str(8 * GIB),
+ },
+ proc = "4:memory:/p/c\n",
+ )
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == 10 * GIB
+
+
+def test_cgroup_v1_ram_only_levels_still_bound_the_ram_side(tmp_path):
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/p/memory.limit_in_bytes": str(4 * GIB),
+ "memory/p/memory.usage_in_bytes": str(1 * GIB),
+ "memory/p/memory.memsw.limit_in_bytes": str(1 << 62),
+ "memory/p/memory.memsw.usage_in_bytes": str(1 * GIB),
+ "memory/p/c/memory.limit_in_bytes": str(16 * GIB),
+ "memory/p/c/memory.usage_in_bytes": str(1 * GIB),
+ "memory/p/c/memory.memsw.limit_in_bytes": str(20 * GIB),
+ "memory/p/c/memory.memsw.usage_in_bytes": str(1 * GIB),
+ },
+ proc = "4:memory:/p/c\n",
+ )
+ # RAM room min(3, 15) = 3 GiB, combined room 19 GiB: 16 GiB of swap.
+ assert cgroup_swap_allowance_bytes(64 * GIB, **paths) == 16 * GIB
+
+
+def test_unreadable_membership_with_a_root_ram_limit_admits_no_swap(tmp_path):
+ root = tmp_path / "cg"
+ root.mkdir()
+ (root / "memory.max").write_text(str(48 * GIB) + "\n", encoding = "utf-8")
+ missing = str(tmp_path / "no-such-proc-self-cgroup")
+ assert (
+ cgroup_swap_allowance_bytes(64 * GIB, cgroup_root = str(root), proc_self_cgroup = missing) == 0
+ )
+
+
+def test_unreadable_membership_reads_the_root_swap_files(tmp_path):
+ root = tmp_path / "cg"
+ root.mkdir()
+ for name, value in (
+ ("memory.max", str(48 * GIB)),
+ ("memory.swap.max", str(8 * GIB)),
+ ("memory.swap.current", str(3 * GIB)),
+ ):
+ (root / name).write_text(value + "\n", encoding = "utf-8")
+ missing = str(tmp_path / "no-such-proc-self-cgroup")
+ assert (
+ cgroup_swap_allowance_bytes(64 * GIB, cgroup_root = str(root), proc_self_cgroup = missing)
+ == 5 * GIB
+ )
+
+
+def test_unreadable_membership_without_any_limit_keeps_host_swap(tmp_path):
+ root = tmp_path / "cg"
+ root.mkdir()
+ missing = str(tmp_path / "no-such-proc-self-cgroup")
+ assert (
+ cgroup_swap_allowance_bytes(8 * GIB, cgroup_root = str(root), proc_self_cgroup = missing)
+ == 8 * GIB
+ )
+
+
+def test_cgroup_v1_swap_is_measured_against_the_ram_the_fit_actually_budgets(tmp_path):
+ """40 GiB cgroup RAM room, 70 GiB RAM+swap room, but only 25 GiB MemAvailable: the fit budgets 25 GiB of RAM, so
+ 45 GiB of swap brings the charge to the 70 GiB the memsw limit allows (not 30 + 25 = 55)."""
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/x/memory.limit_in_bytes": str(50 * GIB),
+ "memory/x/memory.usage_in_bytes": str(10 * GIB),
+ "memory/x/memory.memsw.limit_in_bytes": str(80 * GIB),
+ "memory/x/memory.memsw.usage_in_bytes": str(10 * GIB),
+ },
+ proc = "4:memory:/x\n",
+ )
+ assert cgroup_swap_allowance_bytes(100 * GIB, **paths, ram_budget = 25 * GIB) == 45 * GIB
+ assert cgroup_swap_allowance_bytes(100 * GIB, **paths) == 30 * GIB
+
+
+def test_cgroup_v1_memsw_headroom_is_the_tightest_level(tmp_path):
+ from utils.host_memory import cgroup_v1_memsw_headroom_bytes
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/p/memory.memsw.limit_in_bytes": str(40 * GIB),
+ "memory/p/memory.memsw.usage_in_bytes": str(35 * GIB),
+ "memory/p/c/memory.memsw.limit_in_bytes": str(100 * GIB),
+ "memory/p/c/memory.memsw.usage_in_bytes": str(10 * GIB),
+ },
+ proc = "4:memory:/p/c\n",
+ )
+ assert cgroup_v1_memsw_headroom_bytes(**paths) == 5 * GIB
+
+
+def test_cgroup_v1_memsw_headroom_fails_closed_and_is_absent_without_a_limit(tmp_path):
+ from utils.host_memory import cgroup_v1_memsw_headroom_bytes
+
+ unreadable = _cgroup(
+ tmp_path / "a",
+ {"memory/x/memory.memsw.limit_in_bytes": str(40 * GIB)},
+ proc = "4:memory:/x\n",
+ )
+ assert cgroup_v1_memsw_headroom_bytes(**unreadable) == 0
+ (tmp_path / "b").mkdir()
+ v2_only = _cgroup(tmp_path / "b", {"user.slice/memory.max": "max"})
+ assert cgroup_v1_memsw_headroom_bytes(**v2_only) is None
+
+
+def test_ram_is_capped_by_the_v1_memsw_headroom(monkeypatch):
+ """80 GiB of RAM room but only 5 GiB RAM+swap room (the process swapped a lot): RAM and swap together may not
+ exceed the 5 GiB the cgroup can still charge."""
+ from core.inference import video_minimax_h3
+ from utils import host_memory
+
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_available_bytes", lambda: 80 * GIB)
+ monkeypatch.setattr(host_memory, "cgroup_v1_memsw_headroom_bytes", lambda *a, **k: 5 * GIB)
+ monkeypatch.setattr(
+ host_memory,
+ "cgroup_swap_allowance_bytes",
+ lambda free, *a, ram_budget = None, **k: min(free, max(5 * GIB - ram_budget, 0)),
+ )
+ ram, swap = video_minimax_h3.h3_native_host_budgets()
+ assert (ram, swap) == (5 * GIB, 0)
+
+
+def test_an_unreadable_swap_reading_keeps_the_ram_check(monkeypatch):
+ psutil = pytest.importorskip("psutil")
+
+ from core.inference import video_minimax_h3
+ from utils import host_memory
+
+ def broken():
+ raise OSError("no /proc/swaps")
+
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_available_bytes", lambda: 30 * GIB)
+ monkeypatch.setattr(host_memory, "cgroup_v1_memsw_headroom_bytes", lambda *a, **k: None)
+ monkeypatch.setattr(psutil, "swap_memory", broken)
+ assert video_minimax_h3.h3_native_host_budgets() == (30 * GIB, 0)
+
+
+def test_an_unreadable_gtt_use_is_reported(tmp_path):
+ from core.inference.video_minimax_h3 import amdgpu_gtt_used_unknown
+
+ _card(tmp_path, "card0", "0000:03:00.0", total = 24 * GIB)
+ _card(tmp_path, "card1", "0000:c5:00.0", total = 24 * GIB, used = 1 * GIB)
+ assert amdgpu_gtt_used_unknown("0000:03:00", sysfs_root = str(tmp_path)) is True
+ # The shared pool includes card0's unreadable use, so even the readable card's answer is unknown.
+ assert amdgpu_gtt_used_unknown("0000:c5:00", sysfs_root = str(tmp_path)) is True
+ assert amdgpu_gtt_used_unknown(sysfs_root = str(tmp_path)) is True
+ dev = tmp_path / "class" / "drm" / "card1" / "device"
+ (dev / "mem_info_gtt_used").write_text("garbage\n", encoding = "utf-8")
+ assert amdgpu_gtt_used_unknown("0000:c5:00", sysfs_root = str(tmp_path)) is True
+
+
+def test_one_gtt_pass_returns_free_and_readability_together(tmp_path):
+ from core.inference.video_minimax_h3 import amdgpu_gtt_reading
+
+ _card(tmp_path, "card0", "0000:03:00.0", total = 24 * GIB, used = 4 * GIB)
+ _card(tmp_path, "card1", "0000:c5:00.0", total = 16 * GIB)
+ assert amdgpu_gtt_reading("0000:03:00", sysfs_root = str(tmp_path)) == (20 * GIB, False)
+ assert amdgpu_gtt_reading("0000:c5:00", sysfs_root = str(tmp_path)) == (12 * GIB, False)
+ assert amdgpu_gtt_reading(sysfs_root = str(tmp_path)) == (12 * GIB, False)
+ assert amdgpu_gtt_reading("0000:81:00", sysfs_root = str(tmp_path)) == (None, True)
+
+
+def test_a_slot_matching_no_amdgpu_card_falls_back_to_the_tightest_card(monkeypatch):
+ from core.inference import video_minimax_h3
+ from core.inference.video_minimax_h3 import H3NativeFitInputs, h3_native_live_fit
+
+ def reading(
+ slot = None,
+ *a,
+ **k,
+ ):
+ return (None, True) if slot else (0, True)
+
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", reading)
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (1 << 50, 0))
+ inputs = H3NativeFitInputs(
+ base_flags = AUTO,
+ accelerator = "vulkan",
+ check_gtt = True,
+ gtt_pci_slot = "0000:81:00",
+ dit_bytes = GIB,
+ te_bytes = GIB,
+ vae_bytes = GIB,
+ device_name = "Vulkan0",
+ )
+ assert "GTT" in h3_native_live_fit(inputs, "auto").refusal
+
+
+class _FakeServer:
+ started: list = []
+
+ def __init__(self, binary):
+ self.alive = False
+
+ def start(
+ self,
+ files,
+ *,
+ offload,
+ env = None,
+ extra_args = None,
+ ):
+ self.started.append(tuple(offload))
+ self.alive = True
+
+ def is_alive(self):
+ return self.alive
+
+ def stop(self):
+ self.alive = False
+
+
+def fake_server(monkeypatch):
+ from core.inference import sd_cpp_server
+
+ _FakeServer.started = []
+ monkeypatch.setattr(sd_cpp_server, "SdCppServer", _FakeServer)
+ return _FakeServer
+
+
+def test_a_server_start_is_fitted_and_started_with_the_fitted_flags(fake_server):
+ from core.inference.video_minimax_h3 import H3NativeServerSlot
+
+ slot = H3NativeServerSlot("/x/sd-server", object())
+ calls = []
+
+ def fit():
+ calls.append(1)
+ return ("--offload-to-cpu", "--clip-on-cpu")
+
+ slot.get(("--offload-to-cpu",), (), pre_spawn = fit)
+ assert calls == [1] and fake_server.started == [("--offload-to-cpu", "--clip-on-cpu")]
+ # The live server is reused with no new fit.
+ slot.get(("--offload-to-cpu", "--clip-on-cpu"), (), pre_spawn = fit)
+ assert calls == [1] and len(fake_server.started) == 1
+
+
+def test_a_server_that_stopped_after_the_snapshot_is_fitted_again_and_can_be_refused(fake_server):
+ """alive_signature() said reuse, but the server exited before get(): the start is fitted, and refused."""
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal, H3NativeServerSlot
+
+ slot = H3NativeServerSlot("/x/sd-server", object())
+ slot.get(("--offload-to-cpu",), ())
+ slot._server.alive = False
+
+ def refuse():
+ raise H3NativeMemoryRefusal("no longer fits")
+
+ with pytest.raises(H3NativeMemoryRefusal):
+ slot.get(("--offload-to-cpu",), (), pre_spawn = refuse)
+ assert len(fake_server.started) == 1 and slot._server is None
+
+
+def test_a_refused_server_start_is_not_turned_into_a_disabled_slot():
+ import inspect
+
+ from core.inference import video as video_mod
+
+ source = inspect.getsource(video_mod.VideoBackend._h3_native_server_render)
+ assert "pre_spawn = functools.partial(" in source
+ assert "except (SdCppCancelled, H3NativeMemoryRefusal):" in source
+
+
+def test_cgroup_v1_usage_leaves_out_the_inactive_file_cache(tmp_path):
+ """https://docs.kernel.org/admin-guide/cgroup-v1/memory.html: usage counts page cache the kernel reclaims
+ first; total_inactive_file is subtracted, as for RAM."""
+ from utils.host_memory import cgroup_v1_memsw_headroom_bytes
+
+ paths = _cgroup(
+ tmp_path,
+ {
+ "memory/x/memory.limit_in_bytes": str(32 * GIB),
+ "memory/x/memory.usage_in_bytes": str(30 * GIB),
+ "memory/x/memory.memsw.limit_in_bytes": str(40 * GIB),
+ "memory/x/memory.memsw.usage_in_bytes": str(38 * GIB),
+ "memory/x/memory.stat": f"cache {20 * GIB}\ntotal_inactive_file {20 * GIB}\n",
+ },
+ proc = "4:memory:/x\n",
+ )
+ assert cgroup_v1_memsw_headroom_bytes(**paths) == 22 * GIB
+ # RAM room 22 GiB (32 - (30 - 20)), RAM+swap room 22 GiB: no swap beyond the RAM.
+ assert cgroup_swap_allowance_bytes(100 * GIB, **paths) == 0
+ assert cgroup_swap_allowance_bytes(100 * GIB, **paths, ram_budget = 10 * GIB) == 12 * GIB
+
+
+def _fit_unknown_use(flags, mode, *, gtt):
+ return h3_native_memory_fit(
+ flags,
+ accelerator = "vulkan",
+ memory_mode = mode,
+ pinned_free_bytes = gtt,
+ pinned_used_unknown = True,
+ host_ram_bytes = 60 * GIB,
+ env = {},
+ **Q4,
+ )
+
+
[email protected]("mode", ["auto", "balanced", "fast"])
+def test_unknown_gtt_use_fails_closed_unless_the_user_chose_low_vram(mode):
+ """A 24 GiB pool whose use cannot be read may have 12 GiB taken elsewhere: neither the 33 GiB set nor the 16 GiB
+ one is placed on it automatically. Low VRAM is the user's explicit choice and still runs."""
+ fit = _fit_unknown_use(AUTO, mode, gtt = 24 * GIB)
+ assert fit.flags == AUTO
+ assert "could not read how much" in fit.refusal and "Low VRAM" in fit.refusal
+
+
+def test_unknown_gtt_use_leaves_low_vram_alone_and_refuses_past_the_total():
+ assert _fit_unknown_use(LOW_VRAM, "low_vram", gtt = 64 * GIB).flags == LOW_VRAM
+ assert "ttm.pages_limit" in _fit_unknown_use(LOW_VRAM, "low_vram", gtt = 12 * GIB).refusal
+
+
+def test_a_transiently_unreadable_listing_keeps_the_last_good_one(tmp_path, monkeypatch):
+ import os
+
+ binary = tmp_path / "sd-cli"
+ binary.write_bytes(b"x")
+ monkeypatch.setattr(sd_cpp_backend, "_LAST_DEVICE_LISTING", {})
+ sd_cpp_backend._remember_device_listing(
+ str(binary), "Vulkan0\tAMD Radeon RX 7800 XT (RADV NAVI32)\n"
+ )
+ sd_cpp_backend._remember_device_listing(str(binary), None)
+ assert sd_cpp_backend.sd_cpp_listed_device(str(binary), probe = False) == (
+ "vulkan",
+ "AMD Radeon RX 7800 XT (RADV NAVI32)",
+ )
+ # A replaced binary is never answered from the old listing.
+ binary.write_bytes(b"replaced build")
+ os.utime(binary, ns = (1, 1))
+ assert sd_cpp_backend.sd_cpp_listed_device(str(binary), probe = False) == (None, None)
+
+
+def test_native_host_ram_does_not_add_back_what_studio_holds(monkeypatch):
+ from core.inference import video_minimax_h3
+ from utils import host_memory
+
+ monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda: 30 * 1024)
+ monkeypatch.setattr(video_minimax_h3, "h3_process_held_host_bytes", lambda: 40 * GIB)
+ assert video_minimax_h3.h3_native_host_available_bytes() == 30 * GIB
+
+
+def test_the_fallback_reason_names_the_missing_rocm_libraries(monkeypatch):
+ import ctypes
+
+ def fake_cdll(name, *a, **k):
+ if name == "libhipblas.so.3":
+ raise OSError(name)
+ return object()
+
+ monkeypatch.setattr(ctypes, "CDLL", fake_cdll)
+ monkeypatch.setattr(sd_cpp_backend.sys, "platform", "linux")
+ monkeypatch.setattr(sd_cpp_backend.os, "name", "posix")
+ assert sd_cpp_backend.rocm_runtime_missing_sonames() == ["libhipblas.so.3"]
+ reason = sd_cpp_backend.accelerator_fallback_reason("rocm")
+ assert "libhipblas.so.3" in reason and "ROCm 7" in reason
+ assert "diffusion-accelerator-fallback" in sd_cpp_backend.ACCELERATOR_FALLBACK_CLEAR_HINT
+
+
+def test_an_unaskable_rocm_runtime_is_not_read_as_loading(monkeypatch):
+ monkeypatch.setattr(sd_cpp_backend, "rocm_runtime_missing_sonames", lambda: None)
+ monkeypatch.setattr(sd_cpp_backend.os, "name", "posix")
+ reason = sd_cpp_backend.accelerator_fallback_reason("rocm")
+ assert "could not be checked" in reason and "/dev/kfd" not in reason
+
+
+def test_the_windows_fallback_reason_names_the_hip_dlls(monkeypatch):
+ monkeypatch.setattr(sd_cpp_backend.os, "name", "nt")
+ reason = sd_cpp_backend.accelerator_fallback_reason("rocm")
+ assert "amdhip64_7.dll" in reason and "0xC0000135" in reason and "/dev/kfd" not in reason
+
+
+def test_rocm_runtime_check_is_unknown_on_windows(monkeypatch):
+ monkeypatch.setattr(sd_cpp_backend.os, "name", "nt")
+ assert sd_cpp_backend.rocm_runtime_missing_sonames() is None
+
+
+def test_the_listed_device_names_an_unowned_build(monkeypatch):
+ listing = (
+ "CPU\tAMD Ryzen 9\nVulkan0\tAMD Radeon RX 7800 XT (RADV NAVI32)\nVulkan1\tIntel(R) UHD\n"
+ )
+ monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: listing)
+ assert sd_cpp_backend.sd_cpp_listed_device("/x/sd-cli") == (
+ "vulkan",
+ "AMD Radeon RX 7800 XT (RADV NAVI32)",
+ )
+ assert sd_cpp_backend.sd_cpp_listed_device("/x/sd-cli", "Vulkan1") == ("vulkan", "Intel(R) UHD")
+ monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: "CPU\tAMD Ryzen 9\n")
+ assert sd_cpp_backend.sd_cpp_listed_device("/x/sd-cli") == (None, None)
+
+
+def test_the_fallback_reason_without_missing_libraries_points_at_the_card(monkeypatch):
+ monkeypatch.setattr(sd_cpp_backend.os, "name", "posix")
+ monkeypatch.setattr(sd_cpp_backend, "rocm_runtime_missing_sonames", lambda: [])
+ assert "gfx target" in sd_cpp_backend.accelerator_fallback_reason("rocm")
diff --git a/studio/backend/tests/test_h3_native_server.py b/studio/backend/tests/test_h3_native_server.py
index 958c21ba93f..b116c5d9e79 100644
--- a/studio/backend/tests/test_h3_native_server.py
+++ b/studio/backend/tests/test_h3_native_server.py
@@ -237,10 +237,15 @@ class _FakeSlot:
env = None,
*,
cancel_event = None,
+ pre_spawn = None,
):
- self.got.append((flags, env))
if self.start_exc is not None:
+ self.got.append((flags, env))
raise self.start_exc
+ if pre_spawn is not None:
+ # The real slot fits a start under its lock and starts with the flags the fit returns.
+ flags = list(pre_spawn())
+ self.got.append((flags, env))
return self.server
def begin_render(self):
diff --git a/studio/backend/tests/test_sd_cpp_rocm_vulkan_fallback.py b/studio/backend/tests/test_sd_cpp_rocm_vulkan_fallback.py
index ee16a33feb1..71a447e3431 100644
--- a/studio/backend/tests/test_sd_cpp_rocm_vulkan_fallback.py
+++ b/studio/backend/tests/test_sd_cpp_rocm_vulkan_fallback.py
@@ -105,6 +105,14 @@ def fake_settings(monkeypatch):
return store
[email protected](autouse = True)
+def _roomy_host_ram(monkeypatch):
+ """Native H3 loads fit against the host's available RAM, which a CI runner may not have (macos-15: about 3 GiB).
+ Tests that need a tight host stub usable_host_ram_mib themselves, after this."""
+ from utils import host_memory
+ monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda *a, **k: 1 << 30)
+
+
@pytest.fixture(autouse = True)
def _clean_process_state(monkeypatch):
"""raising = False so these still report what they measured on a tree without the note."""
@@ -2467,7 +2475,8 @@ def test_the_h3_load_scopes_its_record_lookup_to_the_card_it_selected(fake_setti
source = inspect.getsource(video_mod)
load = source[source.index("allow_install = _install_allowed()") :]
assert "selected_card = selected_card_identity(gpu_ordinal)" in load
- assert "preferred_accelerator(_install_accelerator_for(target.backend), selected_card)" in load
+ assert "requested_accelerator = _install_accelerator_for(target.backend)" in load
+ assert "preferred_accelerator(requested_accelerator, selected_card)" in load
start = 0
guarded = 0
while True:
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index c218454bfbe..5ca089c6cd0 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -139,6 +139,14 @@ def _shared_setup_12(_download, monkeypatch):
return backend, fam
[email protected](autouse = True)
+def _roomy_host_ram(monkeypatch):
+ """Native H3 loads fit against the host's available RAM, which a CI runner may not have (macos-15: about 3 GiB).
+ Tests that need a tight host stub usable_host_ram_mib themselves, after this."""
+ from utils import host_memory
+ monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda *a, **k: 1 << 30)
+
+
@pytest.fixture(autouse = True)
def _assume_the_restricted_load_is_available(monkeypatch):
"""A checkpoint only deserializes where torchao is importable, which here it may not be. These
@@ -4134,6 +4142,8 @@ def _load_h3_native_offload(
memory_mode = None,
speed_mode = None,
devices = None,
+ installed_accelerator = None,
+ backend = None,
):
"""Run the native H3 load against a stubbed sd-cli and hand back its committed offload flags.
@@ -4164,6 +4174,10 @@ def _load_h3_native_offload(
if devices is None:
devices = "CUDA0\tNVIDIA GeForce RTX 4070 Ti\n" if accelerator else "CPU\tAMD Ryzen 9\n"
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: devices + help_text)
+ if installed_accelerator is not None:
+ monkeypatch.setattr(
+ sd_cpp_backend, "_installed_accelerator_of", lambda _binary: installed_accelerator
+ )
class _Engine:
def __init__(self, binary):
@@ -4182,7 +4196,7 @@ def _load_h3_native_offload(
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
monkeypatch.setattr(gpu_arbiter, "_owner", gpu_arbiter.VIDEO)
- backend = VideoBackend()
+ backend = backend or VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._run_load_h3_native(
@@ -4245,6 +4259,652 @@ def test_h3_native_drops_stream_layers_without_cpu_offload(monkeypatch, tmp_path
assert "--stream-layers" not in offload
+_AMD_VULKAN = "Vulkan0\tAMD Radeon RX 7800 XT (RADV NAVI32)\n"
+
+
+def _tiny_gtt(
+ monkeypatch,
+ *,
+ encoder_fits: bool,
+ free_vram = 1,
+):
+ """A GTT pool sized against the harness's one-byte files: denoiser 1 + VAEs 2 + encoder 1 bytes past the
+ 1 GiB margin. ``encoder_fits=False`` holds everything but the encoder. ``free_vram`` is what the card reports,
+ 1 byte by default so Auto can never render resident."""
+ from core.inference import video as video_mod
+ from core.inference import video_minimax_h3
+
+ limit = video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + (4 if encoder_fits else 3)
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (limit, True))
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: free_vram)
+
+
+def test_h3_native_auto_prepares_the_encoder_on_the_cpu_for_an_offloaded_render(
+ monkeypatch, tmp_path
+):
+ """radv keeps every GPU-run module of an offloaded H3 in GTT (31.35 GiB at Q4, measured), past half of a 48 GB
+ host: the render dies on "Not enough memory for command submission". Auto runs the encoder on the CPU, but
+ only for a render that is offloaded: the committed flags stay the ones a resident render is derived from."""
+ _tiny_gtt(monkeypatch, encoder_fits = False)
+ state, offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+ assert "--offload-to-cpu" in offload and "--clip-on-cpu" not in offload
+ fitted = list(state.pipe.offloaded_flags)
+ assert "--clip-on-cpu" in fitted and "te=Vulkan0" not in " ".join(fitted)
+ assert state.pipe.offload_refusal is None
+ assert "GTT" in state.resolved["memory_mode"]["reason"]
+
+
+def test_h3_native_detects_an_unowned_vulkan_build_from_its_device_listing(monkeypatch, tmp_path):
+ """SD_CLI_PATH at a user Vulkan build: no install record, and the request was not vulkan."""
+ _tiny_gtt(monkeypatch, encoder_fits = False)
+ state, _offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, devices = _AMD_VULKAN
+ )
+ assert "--clip-on-cpu" in state.pipe.offloaded_flags
+
+
+ "devices",
+ [
+ "Vulkan0\tIntel(R) Arc(tm) A770 Graphics (DG2)\n",
+ "Vulkan0\tNVIDIA GeForce RTX 4070 Ti\n",
+ ],
+)
+def test_h3_native_gtt_pool_binds_only_an_amd_vulkan_device(monkeypatch, tmp_path, devices):
+ """An unrelated AMD iGPU's GTT says nothing about an Intel or NVIDIA Vulkan device."""
+ _tiny_gtt(monkeypatch, encoder_fits = False)
+ state, offload = _load_h3_native_offload(
+ monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, devices = devices
+ )
+ assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
+
+
+def test_h3_native_leaves_a_vulkan_gtt_pool_that_fits_alone(monkeypatch, tmp_path):
+ _tiny_gtt(monkeypatch, encoder_fits = True)
+ state, offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+ assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
+
+
+def _no_gtt_room(monkeypatch, free_vram):
+ from core.inference import video as video_mod
+ from core.inference import video_minimax_h3
+
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0, True))
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: free_vram)
+
+
+def test_h3_native_auto_refuses_at_load_only_when_no_render_could_go_resident(
+ monkeypatch, tmp_path
+):
+ _no_gtt_room(monkeypatch, free_vram = 1)
+ with pytest.raises(RuntimeError, match = "GTT"):
+ _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+
+
+def test_h3_native_auto_defers_the_gtt_refusal_when_a_resident_render_fits(monkeypatch, tmp_path):
+ _no_gtt_room(monkeypatch, free_vram = 1 << 50)
+ state, offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+ assert "--clip-on-cpu" not in offload
+ assert "GTT" in state.pipe.offload_refusal
+
+
+def test_h3_native_refuses_balanced_on_an_overflowing_vulkan_gtt_pool(monkeypatch, tmp_path):
+ _tiny_gtt(monkeypatch, encoder_fits = False)
+ with pytest.raises(RuntimeError, match = "Low VRAM"):
+ _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ memory_mode = "balanced",
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+
+
+def test_h3_native_host_ram_check_ignores_studios_own_rss(monkeypatch, tmp_path):
+ """sd-cli is its own process: the diffusers guard's add-back of Studio's RssAnon / RssShmem must not admit it."""
+ from core.inference import video_minimax_h3
+ from utils import host_memory
+
+ _tiny_gtt(monkeypatch, encoder_fits = True)
+ monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda: 1)
+ monkeypatch.setattr(host_memory, "cgroup_swap_allowance_bytes", lambda *a, **k: 0)
+ monkeypatch.setattr(video_minimax_h3, "h3_process_held_host_bytes", lambda: 1 << 50)
+ with pytest.raises(RuntimeError, match = "system RAM"):
+ _load_h3_native_offload(monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP)
+
+
+def _loaded_with_slot(monkeypatch, tmp_path, slot):
+ """A backend holding a committed native H3 model whose sd-server slot is ``slot``."""
+ from core.inference import video_minimax_h3
+
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (1 << 50, True))
+ backend = VideoBackend()
+ _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ backend = backend,
+ )
+ backend._state = dataclasses.replace(
+ backend._state, pipe = dataclasses.replace(backend._state.pipe, server_slot = slot)
+ )
+ return backend
+
+
+class _ReleasableSlot:
+ def __init__(self):
+ self.released = []
+
+ def release(self, reason):
+ self.released.append(reason)
+ return True
+
+ def is_alive(self):
+ return self.busy
+
+ busy = False
+
+ def stop(self, reason = "stopped"):
+ pass
+
+
+def test_h3_native_replacement_frees_the_outgoing_idle_server_before_refusing(
+ monkeypatch, tmp_path
+):
+ """A cached H3 model's sd-server in its keepalive window holds the GTT this load measures; the teardown would free
+ it, so the load releases it and measures again instead of refusing until the idle timer fires."""
+ from core.inference import video as video_mod
+ from core.inference import video_minimax_h3
+
+ slot = _ReleasableSlot()
+ backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
+ roomy = video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 100
+ monkeypatch.setattr(
+ video_minimax_h3,
+ "amdgpu_gtt_reading",
+ lambda *a, **k: (roomy if slot.released else 0, True),
+ )
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
+ state, offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ backend = backend,
+ )
+ assert slot.released and "--clip-on-cpu" not in offload
+ assert state.pipe.offloaded_flags is None and state.pipe.offload_refusal is None
+
+
+def test_h3_native_a_busy_outgoing_server_is_not_counted_as_freed(monkeypatch, tmp_path):
+ """Mid-render the release is only pending: nothing is freed yet, so no fresh reading is taken, and the refusal
+ says a render is still running rather than blaming the host."""
+ from core.inference import video as video_mod
+ from core.inference import video_minimax_h3
+
+ slot = _ReleasableSlot()
+ backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
+ slot.busy = True
+ readings = []
+
+ def gtt(*_a, **_k):
+ readings.append(1)
+ return 0, True
+
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", gtt)
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
+ with pytest.raises(RuntimeError, match = "still running"):
+ _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ backend = backend,
+ )
+ assert slot.released and len(readings) == 1
+
+
+def _render_runtime(
+ *,
+ base = ("--offload-to-cpu", "--diffusion-fa"),
+ slot = None,
+ snapshot_refusal = None,
+):
+ from core.inference.video_minimax_h3 import H3NativeFitInputs
+ inputs = H3NativeFitInputs(
+ base_flags = base,
+ accelerator = "vulkan",
+ check_gtt = True,
+ gtt_pci_slot = "0000:03:00",
+ dit_bytes = 1,
+ te_bytes = 1,
+ vae_bytes = 2,
+ device_name = "Vulkan0",
+ )
+ return types.SimpleNamespace(
+ fit_inputs = inputs,
+ server_slot = slot,
+ offloaded_flags = None,
+ offload_refusal = snapshot_refusal,
+ )
+
+
+def _live_gtt(monkeypatch, value):
+ from core.inference import video_minimax_h3
+ from utils import host_memory
+
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (value, True))
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_available_bytes", lambda: 1 << 50)
+ monkeypatch.setattr(host_memory, "cgroup_swap_allowance_bytes", lambda *a, **k: 0)
+
+
+def test_an_offloaded_auto_render_catches_pressure_since_the_load(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ _live_gtt(monkeypatch, 0)
+ with pytest.raises(H3NativeMemoryRefusal, match = "GTT"):
+ _h3_offloaded_render_flags(
+ _render_runtime(),
+ ["--offload-to-cpu", "--diffusion-fa"],
+ render_resident = False,
+ memory_mode = "auto",
+ )
+
+
+def test_an_offloaded_auto_render_lifts_a_refusal_once_memory_is_free(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference import video_minimax_h3
+
+ # Room for everything but the encoder: the live fit moves it to the CPU and re-pins it there.
+ _live_gtt(monkeypatch, video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 3)
+ flags = _h3_offloaded_render_flags(
+ _render_runtime(snapshot_refusal = "refused at load"),
+ ["--offload-to-cpu", "--diffusion-fa"],
+ render_resident = False,
+ memory_mode = "auto",
+ )
+ assert "--clip-on-cpu" in flags
+ assert flags[-2:] == ["--backend", "diffusion=Vulkan0,te=cpu,vae=Vulkan0"]
+
+
+def test_a_live_offloaded_server_keeps_its_flags_without_a_reading(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference import video_minimax_h3
+
+ def boom(*_a, **_k):
+ raise AssertionError("must not re-read with the server's own weights placed")
+
+ monkeypatch.setattr(video_minimax_h3, "h3_native_live_fit", boom)
+ running = ("--offload-to-cpu", "--diffusion-fa", "--clip-on-cpu")
+ slot = types.SimpleNamespace(alive_signature = lambda: ("bin", (), running, ()))
+ assert _h3_offloaded_render_flags(
+ _render_runtime(slot = slot),
+ ["--offload-to-cpu", "--diffusion-fa"],
+ render_resident = False,
+ memory_mode = "auto",
+ ) == list(running)
+
+
+class _ResidentSlot:
+ """A live resident sd-server: ``busy`` keeps it alive through a release (it stops at its render's end)."""
+
+ def __init__(self, busy):
+ self.busy = busy
+ self.alive = True
+ self.released = []
+
+ def alive_signature(self):
+ return ("bin", (), ("--diffusion-fa", "--max-vram", "-1"), ()) if self.alive else None
+
+ def release(self, reason):
+ self.released.append(reason)
+ if not self.busy:
+ self.alive = False
+ return True
+
+ def is_alive(self):
+ return self.alive
+
+
+def test_an_offloaded_render_frees_an_idle_resident_server_before_its_reading(monkeypatch):
+ from core.inference import video_minimax_h3
+ from core.inference.video import _h3_offloaded_render_flags
+
+ slot = _ResidentSlot(busy = False)
+ _live_gtt(monkeypatch, 0)
+ roomy = 1 << 50
+ monkeypatch.setattr(
+ video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0 if slot.alive else roomy, True)
+ )
+ flags = _h3_offloaded_render_flags(
+ _render_runtime(slot = slot),
+ ["--offload-to-cpu", "--diffusion-fa"],
+ render_resident = False,
+ memory_mode = "auto",
+ )
+ assert slot.released and "--clip-on-cpu" not in flags
+
+
+def test_an_offloaded_render_behind_a_busy_resident_server_says_a_render_is_running(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ slot = _ResidentSlot(busy = True)
+ _live_gtt(monkeypatch, 0)
+ with pytest.raises(H3NativeMemoryRefusal, match = "still running"):
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot),
+ ["--offload-to-cpu", "--diffusion-fa"],
+ render_resident = False,
+ memory_mode = "auto",
+ )
+ assert slot.released
+
+
+def test_a_new_process_never_reuses_a_live_servers_unchecked_flags(monkeypatch):
+ """Reference video / audio (or a server that could not serve) runs a fresh sd-cli: the live offloaded server is
+ released and the launch is fitted on live readings."""
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ running = ("--offload-to-cpu", "--diffusion-fa")
+ state = {"alive": True}
+ slot = types.SimpleNamespace(
+ alive_signature = lambda: ("bin", (), running, ()) if state["alive"] else None,
+ release = lambda reason: state.update(alive = False) or True,
+ is_alive = lambda: state["alive"],
+ )
+ _live_gtt(monkeypatch, 0)
+ assert _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
+ ) == list(running)
+ with pytest.raises(H3NativeMemoryRefusal):
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot),
+ list(running),
+ render_resident = False,
+ memory_mode = "auto",
+ reuse_live_server = False,
+ )
+ assert state["alive"] is False
+
+
+def test_the_one_shot_sd_cli_launch_is_fitted_afresh():
+ from core.inference import video as video_mod
+
+ source = inspect.getsource(video_mod.VideoBackend._generate_h3_native)
+ fallback = source[source.index("if generated is None:") :]
+ assert fallback.index("reuse_live_server = False") < fallback.index(
+ "runtime.engine.generate_video("
+ )
+
+
+BALANCED_FLAGS = [
+ "--offload-to-cpu",
+ "--diffusion-fa",
+ "--backend",
+ "diffusion=Vulkan0,te=Vulkan0,vae=Vulkan0",
+]
+
+
+def test_an_explicit_mode_is_re_fitted_before_launch_and_never_altered(monkeypatch):
+ from core.inference import video_minimax_h3
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ runtime = _render_runtime()
+ _live_gtt(monkeypatch, 1 << 50)
+ assert (
+ _h3_offloaded_render_flags(
+ runtime, list(BALANCED_FLAGS), render_resident = False, memory_mode = "balanced"
+ )
+ == BALANCED_FLAGS
+ )
+ # Room for the encoder-on-CPU set only: Auto would move it, an explicit mode is refused instead.
+ _live_gtt(monkeypatch, video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 3)
+ with pytest.raises(H3NativeMemoryRefusal, match = "Low VRAM"):
+ _h3_offloaded_render_flags(
+ runtime, list(BALANCED_FLAGS), render_resident = False, memory_mode = "balanced"
+ )
+
+
+def _host_ram(monkeypatch, ram):
+ from core.inference import video_minimax_h3
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (ram, 1 << 50))
+
+
+def test_a_reused_server_still_needs_its_per_render_host_ram(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ running = ("--offload-to-cpu", "--diffusion-fa", "--clip-on-cpu")
+ slot = types.SimpleNamespace(alive_signature = lambda: ("bin", (), running, ()))
+ _host_ram(monkeypatch, 1 << 30)
+ with pytest.raises(H3NativeMemoryRefusal, match = "frames, audio and CPU buffers"):
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
+ )
+ # Swap does not count; enough RAM lets the reuse through without a full fit.
+ _host_ram(monkeypatch, 4 << 30)
+ assert _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
+ ) == list(running)
+
+
+def test_a_resident_render_and_a_resident_start_check_their_host_ram(monkeypatch):
+ from core.inference.video import _h3_launch_flags, _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ resident = ["--diffusion-fa", "--max-vram", "-1"]
+ _host_ram(monkeypatch, 1 << 30)
+ with pytest.raises(H3NativeMemoryRefusal):
+ _h3_offloaded_render_flags(
+ _render_runtime(), resident, render_resident = True, memory_mode = "auto"
+ )
+ with pytest.raises(H3NativeMemoryRefusal):
+ _h3_launch_flags(_render_runtime(), resident, "auto")
+ _host_ram(monkeypatch, 4 << 30)
+ assert _h3_launch_flags(_render_runtime(), resident, "auto") == resident
+
+
+class _OffloadedSlot:
+ def __init__(self, busy):
+ self.busy = busy
+ self.alive = True
+ self.released = []
+
+ def alive_signature(self):
+ return ("bin", (), ("--offload-to-cpu", "--diffusion-fa"), ()) if self.alive else None
+
+ def release(self, reason):
+ self.released.append(reason)
+ if not self.busy:
+ self.alive = False
+ return True
+
+ def is_alive(self):
+ return self.alive
+
+
+def test_a_resident_render_frees_an_idle_offloaded_server_before_its_ram_check(monkeypatch):
+ """get() would replace that server on the signature change; its pinned RAM must not refuse the render."""
+ from core.inference import video_minimax_h3
+ from core.inference.video import _h3_offloaded_render_flags
+
+ slot = _OffloadedSlot(busy = False)
+ monkeypatch.setattr(
+ video_minimax_h3,
+ "h3_native_host_budgets",
+ lambda: ((1 << 30) if slot.alive else (8 << 30), 0),
+ )
+ resident = ["--diffusion-fa", "--max-vram", "-1"]
+ assert (
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), resident, render_resident = True, memory_mode = "auto"
+ )
+ == resident
+ )
+ assert slot.released
+
+
+def test_a_resident_render_behind_a_busy_offloaded_server_says_a_render_is_running(monkeypatch):
+ from core.inference import video_minimax_h3
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
+
+ slot = _OffloadedSlot(busy = True)
+ monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (1 << 30, 0))
+ with pytest.raises(H3NativeMemoryRefusal, match = "still running"):
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), ["--diffusion-fa"], render_resident = True, memory_mode = "auto"
+ )
+
+
+def test_the_kill_switch_turns_off_every_render_time_guard(monkeypatch):
+ from core.inference.video import _h3_launch_flags, _h3_offloaded_render_flags
+
+ monkeypatch.setenv("UNSLOTH_H3_NATIVE_FIT_CHECK", "0")
+ _live_gtt(monkeypatch, 0)
+ monkeypatch.setattr(
+ "core.inference.video_minimax_h3.h3_native_host_budgets", lambda: (1 << 20, 0)
+ )
+ slot = _OffloadedSlot(busy = False)
+ offloaded = ["--offload-to-cpu", "--diffusion-fa"]
+ assert (
+ _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), list(offloaded), render_resident = False, memory_mode = "auto"
+ )
+ == offloaded
+ )
+ assert _h3_offloaded_render_flags(
+ _render_runtime(slot = slot), ["--diffusion-fa"], render_resident = True, memory_mode = "auto"
+ ) == ["--diffusion-fa"]
+ assert _h3_launch_flags(_render_runtime(), list(offloaded), "balanced") == offloaded
+ assert _h3_launch_flags(_render_runtime(), ["--diffusion-fa"], "auto") == ["--diffusion-fa"]
+ assert slot.released == []
+
+
+def test_a_resident_render_is_never_re_fitted(monkeypatch):
+ from core.inference.video import _h3_offloaded_render_flags
+ from core.inference import video_minimax_h3
+
+ monkeypatch.setattr(video_minimax_h3, "h3_native_live_fit", lambda *a, **k: 1 / 0)
+ resident = ["--diffusion-fa", "--max-vram", "-1"]
+ assert (
+ _h3_offloaded_render_flags(
+ _render_runtime(), resident, render_resident = True, memory_mode = "auto"
+ )
+ == resident
+ )
+
+
+def test_h3_native_keeps_the_outgoing_server_when_the_load_fits(monkeypatch, tmp_path):
+ from core.inference import video as video_mod
+
+ slot = _ReleasableSlot()
+ backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
+ _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ backend = backend,
+ )
+ assert slot.released == []
+
+
+def test_h3_native_explicit_modes_keep_their_fit_inputs(monkeypatch, tmp_path):
+ _tiny_gtt(monkeypatch, encoder_fits = True)
+ state, _offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ memory_mode = "balanced",
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+ assert state.pipe.fit_inputs is not None
+
+
+def test_h3_native_names_no_gtt_slot_when_the_vulkan_pin_did_not_resolve(monkeypatch, tmp_path):
+ """Unpinned, sd.cpp picks its own Vulkan device, so the torch card's slot may name another card."""
+ from core.inference import video as video_mod
+
+ _tiny_gtt(monkeypatch, encoder_fits = True)
+ monkeypatch.setattr(video_mod, "_torch_pci_slot", lambda *_a: "0000:03:00")
+ state, _offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ )
+ assert state.pipe.fit_inputs.device_name is None
+ assert state.pipe.fit_inputs.gtt_pci_slot is None
+
+
+def test_h3_native_replacing_an_in_process_model_defers_the_refusal_to_the_launch(
+ monkeypatch, tmp_path
+):
+ """The outgoing diffusers model's memory is freed by the commit's teardown, before any native process starts;
+ the load does not refuse on a reading that still counts it, and the pre-launch live fit decides."""
+ from core.inference import video as video_mod
+ from core.inference import video_minimax_h3
+
+ backend = _loaded_with_slot(monkeypatch, tmp_path, None)
+ backend._state = dataclasses.replace(backend._state, engine = "diffusers")
+ monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0, True))
+ monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
+ state, _offload = _load_h3_native_offload(
+ monkeypatch,
+ tmp_path,
+ help_text = _GRAPH_CUT_HELP,
+ memory_mode = "balanced",
+ devices = _AMD_VULKAN,
+ installed_accelerator = "vulkan",
+ backend = backend,
+ )
+ assert state.engine == "sd_cpp" and state.pipe.fit_inputs is not None
+
+
+def test_h3_native_gtt_pool_is_not_a_cuda_build_concern(monkeypatch, tmp_path):
+ _tiny_gtt(monkeypatch, encoder_fits = False)
+ state, offload = _load_h3_native_offload(monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP)
+ assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
+
+
_SAGE_HELP = _GRAPH_CUT_HELP + " --sage-attn use native CUDA SageAttention\n"
diff --git a/studio/backend/utils/host_memory.py b/studio/backend/utils/host_memory.py
index d711c493ffc..fe008e68fc4 100644
--- a/studio/backend/utils/host_memory.py
+++ b/studio/backend/utils/host_memory.py
@@ -122,6 +122,152 @@ def cgroup_memory_budgets(
return budgets
+def _v1_reclaimable_usage(directory: str, raw: Optional[int]) -> Optional[int]:
+ """A v1 ``*.usage_in_bytes`` reading less the level's inactive file cache (``total_inactive_file``, which the
+ kernel reclaims before it charges against the limit), as ``cgroup_memory_budgets`` reads RAM usage."""
+ if raw is None:
+ return None
+ inactive = _stat_integer(
+ os.path.join(directory, "memory.stat"), "total_inactive_file", "inactive_file"
+ )
+ return max(raw - inactive, 0)
+
+
+def cgroup_swap_allowance_bytes(
+ free_swap: int,
+ cgroup_root: Optional[str] = None,
+ proc_self_cgroup: Optional[str] = None,
+ *,
+ ram_budget: Optional[int] = None,
+) -> int:
+ """How much of the host's ``free_swap`` this process may still use: bounded by every enforcing cgroup swap
+ limit on this cgroup and its ancestors: v2 ``memory.swap.max`` minus ``memory.swap.current`` per level (a
+ swap-only counter, so the per-level minimum is exact); v1 the tightest ``memsw`` (RAM+swap) headroom minus the
+ RAM the caller actually budgets (``ram_budget``, e.g. min(MemAvailable, cgroup headroom)), else minus the
+ tightest cgroup RAM headroom. Unreadable cgroup membership is read as the namespace root, like
+ ``cgroup_memory_budgets``, so a root RAM limit without readable swap files still yields 0. 0 when a memory limit is enforced but its swap allowance cannot be read."""
+ free_swap = max(int(free_swap or 0), 0)
+ cgroup_root = CGROUP_ROOT if cgroup_root is None else cgroup_root
+ proc_self_cgroup = PROC_SELF_CGROUP if proc_self_cgroup is None else proc_self_cgroup
+ try:
+ with open(proc_self_cgroup, "r", encoding = "utf-8") as f:
+ lines = [line.strip() for line in f if line.strip()]
+ except (OSError, UnicodeDecodeError):
+ lines = []
+ allowance = free_swap
+ v2_relative = next((line[3:] for line in lines if line.startswith("0::")), None)
+ if not lines:
+ # Membership unknown: judge the namespace root (where cgroup_memory_budgets reads the RAM limit), fail closed.
+ v2_relative = "/"
+ if v2_relative is not None:
+ for directory in _directories(cgroup_root, v2_relative):
+ raw = _first_line(os.path.join(directory, "memory.swap.max"))
+ if raw is None:
+ # No swap accounting here: a RAM limit at this level makes the swap it leaves unknowable.
+ if (
+ _integer(_first_line(os.path.join(directory, "memory.max")), limit = True)
+ is not None
+ ):
+ return 0
+ continue
+ limit = _integer(raw, limit = True)
+ if limit is None:
+ if raw != "max":
+ return 0
+ continue
+ used = _integer(_first_line(os.path.join(directory, "memory.swap.current")))
+ if used is None:
+ return 0
+ allowance = min(allowance, max(limit - used, 0))
+ v1_relative = None if lines else "/"
+ for line in lines:
+ parts = line.split(":", 2)
+ if len(parts) == 3 and "memory" in parts[1].split(","):
+ v1_relative = parts[2]
+ break
+ if v1_relative is not None:
+ # v1 memsw is RAM+swap: swap = tightest combined headroom - tightest RAM headroom, never per-level differences.
+ v1_root = os.path.join(cgroup_root, "memory")
+ # swappiness 0 on an enforcing (limited) level means its reclaim never swaps; unlimited levels are irrelevant.
+ for directory in _directories(v1_root, v1_relative):
+ enforcing = any(
+ _integer(_first_line(os.path.join(directory, name)), limit = True) is not None
+ for name in ("memory.limit_in_bytes", "memory.memsw.limit_in_bytes")
+ )
+ if (
+ enforcing
+ and _integer(_first_line(os.path.join(directory, "memory.swappiness"))) == 0
+ ):
+ return 0
+ ram_room: Optional[int] = None
+ combined_room: Optional[int] = None
+ for directory in _directories(v1_root, v1_relative):
+ mem_limit = _integer(
+ _first_line(os.path.join(directory, "memory.limit_in_bytes")), limit = True
+ )
+ if mem_limit is None:
+ continue
+ mem_used = _v1_reclaimable_usage(
+ directory, _integer(_first_line(os.path.join(directory, "memory.usage_in_bytes")))
+ )
+ raw_memsw = _first_line(os.path.join(directory, "memory.memsw.limit_in_bytes"))
+ if raw_memsw is None or mem_used is None:
+ return 0 # a RAM limit without swap accounting (or usage): the swap it leaves is unknown
+ room = mem_limit - mem_used
+ ram_room = room if ram_room is None else min(ram_room, room)
+ memsw_limit = _integer(raw_memsw, limit = True)
+ if memsw_limit is None:
+ continue # RAM+swap unlimited at this level: it bounds RAM only
+ memsw_used = _v1_reclaimable_usage(
+ directory,
+ _integer(_first_line(os.path.join(directory, "memory.memsw.usage_in_bytes"))),
+ )
+ if memsw_used is None:
+ return 0
+ room = memsw_limit - memsw_used
+ combined_room = room if combined_room is None else min(combined_room, room)
+ if combined_room is not None:
+ ram_side = ram_room if ram_budget is None else ram_budget
+ allowance = min(allowance, max(combined_room - max(ram_side or 0, 0), 0))
+ return allowance
+
+
+def cgroup_v1_memsw_headroom_bytes(
+ cgroup_root: Optional[str] = None, proc_self_cgroup: Optional[str] = None
+) -> Optional[int]:
+ """The tightest cgroup v1 RAM+swap (``memsw``) headroom on this cgroup and its ancestors, the most RAM and swap
+ together this process can still charge; None without a finite memsw limit. Unreadable membership is read as
+ the namespace root; a finite limit whose usage cannot be read yields 0."""
+ cgroup_root = CGROUP_ROOT if cgroup_root is None else cgroup_root
+ proc_self_cgroup = PROC_SELF_CGROUP if proc_self_cgroup is None else proc_self_cgroup
+ try:
+ with open(proc_self_cgroup, "r", encoding = "utf-8") as f:
+ lines = [line.strip() for line in f if line.strip()]
+ except (OSError, UnicodeDecodeError):
+ lines = []
+ relative = None if lines else "/"
+ for line in lines:
+ parts = line.split(":", 2)
+ if len(parts) == 3 and "memory" in parts[1].split(","):
+ relative = parts[2]
+ break
+ if relative is None:
+ return None
+ best: Optional[int] = None
+ for directory in _directories(os.path.join(cgroup_root, "memory"), relative):
+ limit = _integer(
+ _first_line(os.path.join(directory, "memory.memsw.limit_in_bytes")), limit = True
+ )
+ if limit is None:
+ continue
+ used = _v1_reclaimable_usage(
+ directory, _integer(_first_line(os.path.join(directory, "memory.memsw.usage_in_bytes")))
+ )
+ room = 0 if used is None else max(limit - used, 0)
+ best = room if best is None else min(best, room)
+ return best
+
+
def cgroup_headroom_mib(budgets: Optional[list[tuple[int, int]]] = None) -> Optional[int]:
"""What an enforcing cgroup still lets this process charge (the tightest remainder), else None."""
budgets = cgroup_memory_budgets() if budgets is None else budgets