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: run MiniMax-H3's Diffusers INT8 path on 24 / 16 / 12 GB cards and near the host RAM floor (#12409)

Daniel Han5502355312de
diff --git a/studio/backend/core/inference/diffusion_pinned_arena.py b/studio/backend/core/inference/diffusion_pinned_arena.py
new file mode 100644
index 00000000000..0a32e849762
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_pinned_arena.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""One pinned host copy of a streamed module, packed into power-of-two slabs instead of one pin per tensor.
+
+torch's host allocator rounds each pin up to a power of two (H3's 19.45 GB int8 denoiser held 33.8 GB pinned), and the
+pageable source survived until each group's first onload. The slab copy replaces the parameter's storage on the spot.
+
+Kill switch: ``UNSLOTH_DIFFUSION_PIN_ARENA=0`` restores per-tensor ``pin_memory()``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from typing import Any, Iterator, Optional
+
+PIN_ARENA_ENV = "UNSLOTH_DIFFUSION_PIN_ARENA"
+DEFAULT_SLAB_BYTES = 1 << 30
+_ALIGN = 512
+
+
+def pin_arena_enabled() -> bool:
+ return str(os.environ.get(PIN_ARENA_ENV, "1")).strip().lower() not in (
+ "0",
+ "off",
+ "false",
+ "no",
+ )
+
+
+def _alloc_slab(nbytes: int) -> Any:
+ """One pinned slab. A power-of-two request, so torch's host allocator rounds nothing."""
+ import torch
+ return torch.empty(nbytes, dtype = torch.uint8, pin_memory = True)
+
+
+def _pow2_ceil(n: int) -> int:
+ return 1 << max(0, (int(n) - 1).bit_length())
+
+
+class PinnedArena:
+ """First-fit bump allocator over pinned uint8 slabs. Views keep their slab alive, so dropping the
+ last tensor that points into a slab returns it to torch's host cache like any pinned tensor."""
+
+ def __init__(self, slab_bytes: int = DEFAULT_SLAB_BYTES) -> None:
+ self.slab_bytes = _pow2_ceil(slab_bytes)
+ self._slabs: list[list[Any]] = [] # [slab tensor, used bytes]
+ self.payload_bytes = 0
+
+ @property
+ def reserved_bytes(self) -> int:
+ return sum(int(s.numel()) for s, _ in self._slabs)
+
+ def _take(self, nbytes: int) -> Any:
+ for entry in self._slabs:
+ slab, used = entry
+ start = (used + _ALIGN - 1) // _ALIGN * _ALIGN
+ if start + nbytes <= slab.numel():
+ entry[1] = start + nbytes
+ return slab[start : start + nbytes]
+ size = max(self.slab_bytes, _pow2_ceil(nbytes))
+ slab = _alloc_slab(size)
+ self._slabs.append([slab, nbytes])
+ return slab[:nbytes]
+
+ def pin_plain(self, tensor: Any) -> Any:
+ """A pinned copy of a plain CPU tensor, as a view into a slab. Falls back to ``pin_memory()``
+ for anything the packing cannot represent exactly."""
+ if (
+ tensor.device.type != "cpu"
+ or not tensor.is_contiguous()
+ or tensor.numel() == 0
+ or tensor.dtype.is_complex
+ ):
+ return tensor.pin_memory()
+ nbytes = tensor.numel() * tensor.element_size()
+ dst = self._take(nbytes).view(tensor.dtype).view(tensor.shape)
+ dst.copy_(tensor)
+ self.payload_bytes += nbytes
+ return dst
+
+ def pin(self, tensor: Any) -> Any:
+ """Pinned copy of ``tensor``. A traceable wrapper subclass (torchao Int8Tensor and friends) is
+ rebuilt from pinned inner tensors, which is what its own ``pin_memory()`` produces."""
+ from torch.utils._python_dispatch import is_traceable_wrapper_subclass
+
+ if is_traceable_wrapper_subclass(tensor):
+ names, ctx = tensor.__tensor_flatten__()
+ inner = {name: self.pin(getattr(tensor, name)) for name in names}
+ return type(tensor).__tensor_unflatten__(inner, ctx, tensor.size(), tensor.stride())
+ return self.pin_plain(tensor)
+
+
+def _repoint(param: Any, pinned: Any) -> None:
+ """Make ``param`` read the pinned copy now, so its pageable storage is freed during setup.
+ Group offloading's own offload does exactly this after every forward."""
+ from torch.utils._python_dispatch import is_traceable_wrapper_subclass
+ if is_traceable_wrapper_subclass(param):
+ names, _ = pinned.__tensor_flatten__()
+ for name in names:
+ setattr(param, name, getattr(pinned, name))
+ else:
+ param.data = pinned
+
+
+def pinned_arena_for_group_offload(
+ *, enabled: Optional[bool] = None, slab_bytes: int = DEFAULT_SLAB_BYTES
+) -> Iterator[Optional[PinnedArena]]:
+ """While active, diffusers' group offloading pins its up-front host copies through one arena.
+
+ Yields the arena (for its byte counts) or None when disabled or when this diffusers has no
+ ``ModuleGroup._to_cpu`` to route through; either way the caller's ``apply_group_offloading``
+ call runs unchanged."""
+ if enabled is None:
+ enabled = pin_arena_enabled()
+ if not enabled:
+ yield None
+ return
+ try:
+ from diffusers.hooks import group_offloading as go
+ except Exception: # noqa: BLE001 -- no group offloading in this diffusers
+ yield None
+ return
+ group_cls = getattr(go, "ModuleGroup", None)
+ original = group_cls.__dict__.get("_to_cpu") if group_cls is not None else None
+ if original is None:
+ yield None
+ return
+ arena = PinnedArena(slab_bytes)
+
+ def _to_cpu(tensor: Any, low_cpu_mem_usage: bool) -> Any:
+ if (
+ low_cpu_mem_usage
+ or getattr(tensor, "device", None) is None
+ or tensor.device.type != "cpu"
+ ):
+ return original.__func__(tensor, low_cpu_mem_usage)
+ try:
+ pinned = arena.pin(tensor)
+ except Exception: # noqa: BLE001 -- any surprise keeps the stock per-tensor pin
+ return original.__func__(tensor, low_cpu_mem_usage)
+ try:
+ _repoint(tensor, pinned)
+ except Exception: # noqa: BLE001 -- the stock path re-points at the first offload anyway
+ pass
+ return pinned
+
+ group_cls._to_cpu = staticmethod(_to_cpu)
+ try:
+ yield arena
+ finally:
+ group_cls._to_cpu = original
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 508b6c8869a..d22749586d1 100644
--- a/studio/backend/core/inference/diffusion_prequant.py
+++ b/studio/backend/core/inference/diffusion_prequant.py
@@ -2058,7 +2058,23 @@ def stream_prequantized_module(
tensor_payload_bytes(t) for t in chain(module.parameters(), module.buffers())
) // (1024 * 1024)
kwargs["low_cpu_mem_usage"] = not _streamed_pin_plan(payload_mib, 0, logger)[0]
- apply_group_offloading(module, **kwargs)
+ # A full up-front pin goes through one slab arena: per-tensor pin_memory() rounds every weight up to a power
+ # of two (19.45 GB of H3 int8 weights held 33.8 GB pinned) and kept the pageable source alive beside it.
+ from .diffusion_pinned_arena import pinned_arena_for_group_offload
+
+ with pinned_arena_for_group_offload(
+ enabled = None if use_stream and not kwargs.get("low_cpu_mem_usage") else False
+ ) as arena:
+ apply_group_offloading(module, **kwargs)
+ if arena is not None and arena.payload_bytes:
+ module._unsloth_pin_arena_bytes = (arena.payload_bytes, arena.reserved_bytes)
+ if logger is not None:
+ logger.info(
+ "diffusion.prequant: %s pinned once in %.2f GB of slabs (%.2f GB of weights)",
+ label,
+ arena.reserved_bytes / 1e9,
+ arena.payload_bytes / 1e9,
+ )
_move_groups_outside_inference_mode(module)
module.register_forward_pre_hook(_evict_rotation_hook(manager, onload))
except Exception as exc:
diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.py
index 3b61dda7258..196b3a21395 100644
--- a/studio/backend/core/inference/diffusion_speed.py
+++ b/studio/backend/core/inference/diffusion_speed.py
@@ -921,6 +921,12 @@ def _compile_repeated_blocks(
try:
transformer.compile_repeated_blocks(**dit_kwargs)
engaged = True
+ # Kept so a caller that moves the compile below an offload hook (MiniMax-H3's streamed denoiser) compiles
+ # with exactly these settings.
+ try:
+ transformer._unsloth_regional_compile_kwargs = dict(dit_kwargs)
+ except Exception: # noqa: BLE001 - not a settable module (tests/fakes)
+ pass
except Exception as exc: # noqa: BLE001 - optimisation only
_warn(logger, "compile_repeated_blocks", exc)
continue
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index b5660f9f983..3982160b4f2 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -1020,6 +1020,10 @@ class _VideoLoadState:
vram_decode_floor_mib: Optional[int] = None
# MiniMax-H3: the streamed denoiser also holds a full pinned host copy, which the host floor counts twice.
denoiser_host_copy: bool = False
+ # MiniMax-H3: conditioner streamed leaf by leaf (VRAM floor counts its streamed footprint).
+ te_streamed: bool = False
+ # MiniMax-H3: video_minimax_h3_residency.H3Residency of a streamed denoiser, re-fitted per request.
+ h3_residency: Any = None
resolved: Optional[dict] = None
@@ -1321,6 +1325,50 @@ def _h3_dense_denoiser_fits(sizes: Optional[tuple[int, int]], free_bytes: Option
return int(free_bytes) >= int(denoiser_bytes) + int(others_bytes)
+def _h3_residency_budget_bytes(
+ residency: Any,
+ device: str,
+ *,
+ width: int,
+ height: int,
+ frames: int,
+ te_streamed: bool,
+ te_scheme: Optional[str],
+ fragmentation: bool = True,
+ top_gb: float = 0.0,
+) -> int:
+ """Device bytes the resident set may occupy for this request: free + allocator cache + resident, minus the
+ request's largest phase. Negative = not even fully streamed fits. Unreadable is 0 (all streamed)."""
+ try:
+ import torch
+
+ from .video_minimax_h3 import H3_TEXT_ENCODER_BF16_GB
+ from .video_minimax_h3_residency import h3_phase_need_gb
+ from .video_minimax_h3_te import H3_TE_STREAMED_GB
+
+ free = _h3_free_device_bytes(device)
+ if free is None:
+ return 0
+ cached = int(torch.cuda.memory_reserved()) - int(torch.cuda.memory_allocated())
+ available = int(free) + max(0, cached) + int(residency.resident_bytes())
+ te_gb = (
+ H3_TE_STREAMED_GB
+ if te_streamed
+ else h3_te_resident_gb(te_scheme, bf16_gb = H3_TEXT_ENCODER_BF16_GB)
+ )
+ need = h3_phase_need_gb(
+ width,
+ height,
+ frames,
+ te_streamed_gb = te_gb,
+ fragmentation = fragmentation,
+ top_gb = top_gb,
+ )
+ return available - int(need * 1e9)
+ except Exception: # noqa: BLE001
+ return 0
+
+
def _h3_placement_tier(
*,
quantised: bool,
@@ -6881,6 +6929,9 @@ class VideoBackend:
offload_policy = "none"
denoiser_pinned = False
denoiser_streamed: Optional[str] = None
+ denoiser_single_host_copy = False
+ te_streamed: Optional[str] = None
+ residency = None
# load_components just spent minutes building ~145 GB of components, and everything below this line either moves
# weights onto the card or mutates process-wide backend flags. The conventional placement path fences on the
# token for exactly that reason; without the same fence here a cancelled or superseded worker resumes into a GPU
@@ -6963,6 +7014,13 @@ class VideoBackend:
stream_prequantized_module,
)
+ if text_encoder_quant_engaged is not None:
+ # Stream the conditioner instead of rotating it on whole; the denoiser tier below is still sized
+ # with it rotating, so pinning is unchanged. None keeps the rotation.
+ from .video_minimax_h3_te import stream_h3_text_encoder
+ te_streamed = stream_h3_text_encoder(
+ manager, getattr(pipe, "text_encoder", None), device, logger = logger
+ )
pinned_sizes = _h3_dense_denoiser_resident_bytes(
fam,
denoiser = denoiser,
@@ -6997,6 +7055,9 @@ class VideoBackend:
if placed in _H3_STREAM_MODES:
# offload_policy stays "model": the post-generation host reclaim keys on it.
denoiser_streamed = placed
+ denoiser_single_host_copy = (
+ getattr(denoiser, "_unsloth_pin_arena_bytes", None) is not None
+ )
logger.info(
"video.h3_placement: %.1f GB free is under the %.1f GB a pinned %s "
"denoiser plus the larger rotating component need, so it streams "
@@ -7005,6 +7066,51 @@ class VideoBackend:
sum(pinned_sizes) / 1e9,
transformer_quant_engaged,
)
+ # Residency sized for the largest preset at the default length; re-fitted per request.
+ from .video_minimax_h3_residency import (
+ H3Residency,
+ h3_dit_resident_enabled,
+ )
+
+ if denoiser_streamed in ("stream", "stream_lazy"):
+ from .video_minimax_h3_residency import pin_streamed_top_level_group
+ try:
+ pin_streamed_top_level_group(denoiser, logger = logger)
+ except Exception as exc: # noqa: BLE001 -- a speed-up only
+ logger.warning("video.h3_top_group: %s", exc)
+ if h3_dit_resident_enabled() and denoiser_streamed in (
+ "stream",
+ "stream_lazy",
+ ):
+ try:
+ residency = H3Residency(denoiser, device, logger = logger)
+ if residency.usable:
+ big_w, big_h = max(
+ fam.resolution_presets, key = lambda wh: wh[0] * wh[1]
+ )
+ residency.fit(
+ _h3_residency_budget_bytes(
+ residency,
+ device,
+ width = big_w,
+ height = big_h,
+ frames = fam.default_num_frames,
+ te_streamed = bool(te_streamed),
+ te_scheme = text_encoder_quant_engaged,
+ ),
+ initial = True,
+ )
+ else:
+ residency = None
+ except Exception as exc: # noqa: BLE001 -- residency is a speed-up, stay streamed
+ logger.warning(
+ "video.h3_residency: staying fully streamed: %s", exc
+ )
+ if residency is not None:
+ # A partial fit left resident groups no controller would ever demote.
+ from .video_minimax_h3_residency import release_all
+ release_all(residency, logger = logger)
+ residency = None
else:
denoiser_pinned = pin_prequantized_module(
manager, denoiser, device, logger = logger
@@ -7120,6 +7226,11 @@ class VideoBackend:
logger = logger,
)
speed_optims = tuple(k for k, v in applied.items() if v)
+ if denoiser_streamed and "compiled" in speed_optims:
+ from .video_minimax_h3_residency import compile_blocks_below_offload_hooks
+ compile_blocks_below_offload_hooks(
+ getattr(pipe, denoiser_component, None), logger = logger
+ )
except Exception as exc: # noqa: BLE001 -- optimisation only, never fail a load
logger.warning("video.h3_speed_optims failed, continuing unoptimised: %s", exc)
# nothing here compiles, so it follows the REQUESTED tier, not the denoiser's eager downgrade above
@@ -7142,6 +7253,16 @@ class VideoBackend:
except Exception as exc: # noqa: BLE001 -- optimisation only, never fail a load
logger.warning("video.h3_audio_vae: keeping the stock audio VAE: %s", exc)
+ if offload_policy != "none" and (te_streamed or denoiser_streamed):
+ # Only the VAEs rotate now, evicting each other every render. Installed last: the levers above replace weights.
+ from .video_minimax_h3_residency import install_pinned_swap
+ for vae_name in ("vae", "audio_vae"):
+ try:
+ install_pinned_swap(
+ getattr(pipe, vae_name, None), logger = logger, label = vae_name
+ )
+ except Exception as exc: # noqa: BLE001 -- stock moves
+ logger.warning("video.h3_pinned_swap: %s: %s", vae_name, exc)
resolved = build_resolved_record(
{
"family_override": _family_override_resolved(family_override, fam),
@@ -7154,6 +7275,11 @@ class VideoBackend:
"; the pre-quantized denoiser streams block by block (group offload)"
if denoiser_streamed
else ""
+ )
+ + (
+ "; the quantized conditioner streams leaf by leaf (group offload)"
+ if te_streamed
+ else ""
),
),
"speed_mode": (
@@ -7257,7 +7383,10 @@ class VideoBackend:
text_encoder_quant = text_encoder_quant_engaged,
denoiser_pinned = denoiser_pinned,
denoiser_streamed = bool(denoiser_streamed),
- denoiser_host_copy = denoiser_streamed == "stream",
+ # A slab-arena pin released the pageable source, so the pinned copy is the only one.
+ denoiser_host_copy = denoiser_streamed == "stream" and not denoiser_single_host_copy,
+ te_streamed = bool(te_streamed),
+ h3_residency = residency,
resolved = resolved,
)
self._precommit_globals = None
@@ -7889,7 +8018,6 @@ class VideoBackend:
if state.engine == "diffusers" and fam.modular_workflow and state.device != "cpu":
from .video_minimax_h3 import (
H3_TEXT_ENCODER_BF16_GB,
- estimate_h3_diffusers_host_ram_gb,
estimate_h3_diffusers_vram_gb,
)
@@ -7920,7 +8048,36 @@ class VideoBackend:
transformer_gb = h3_transformer_resident_gb(state.transformer_quant),
transformer_pinned = bool(getattr(state, "denoiser_pinned", False)),
transformer_streamed = bool(getattr(state, "denoiser_streamed", False)),
+ text_encoder_streamed = bool(getattr(state, "te_streamed", False)),
)
+ residency = getattr(state, "h3_residency", None)
+ if residency is not None and getattr(state, "denoiser_streamed", False):
+ # Resident blocks are demotable, so they count as available. The floor omits the
+ # fragmentation slack (a fully streamed render fits as before); the resident set keeps it.
+ fit_kwargs = dict(
+ width = width,
+ height = height,
+ frames = frames,
+ te_streamed = bool(getattr(state, "te_streamed", False)),
+ te_scheme = state.text_encoder_quant,
+ )
+ floor_room = _h3_residency_budget_bytes(
+ residency,
+ state.device,
+ fragmentation = False,
+ top_gb = residency.top_bytes / 1_000_000_000,
+ **fit_kwargs,
+ )
+ available_vram_gb += residency.resident_bytes() / 1_000_000_000
+ required_vram_gb = available_vram_gb - floor_room / 1_000_000_000
+ residency.fit(
+ max(
+ 0,
+ _h3_residency_budget_bytes(
+ residency, state.device, **fit_kwargs
+ ),
+ )
+ )
if available_vram_gb + 0.25 < required_vram_gb:
raise RuntimeError(
f"MiniMax-H3 needs about {required_vram_gb:.1f} GB available "
@@ -7929,29 +8086,22 @@ class VideoBackend:
"or duration, or load the GGUF artifact."
)
- import psutil
+ from .video_minimax_h3 import h3_host_ram_shortfall
- process_rss = psutil.Process().memory_info().rss
- host_capacity_gb = (
- psutil.virtual_memory().available + process_rss
- ) / 1_000_000_000
# Same engaged components as the VRAM floor above. Sizing one from what the load holds and the
# other from the released pair refuses exactly the configuration the quantized components exist
# for.
- required_host_gb = estimate_h3_diffusers_host_ram_gb(
+ shortfall = h3_host_ram_shortfall(
available_vram_gb,
text_encoder_gb = h3_te_resident_gb(
state.text_encoder_quant, bf16_gb = H3_TEXT_ENCODER_BF16_GB
),
transformer_gb = h3_transformer_resident_gb(state.transformer_quant),
transformer_streamed = bool(getattr(state, "denoiser_host_copy", False)),
+ text_encoder_streamed = bool(getattr(state, "te_streamed", False)),
)
- if host_capacity_gb + 0.5 < required_host_gb:
- raise RuntimeError(
- f"MiniMax-H3 needs about {required_host_gb:.0f} GB available "
- f"system RAM at this VRAM tier; {host_capacity_gb:.1f} GB is "
- "available. Load the GGUF artifact instead."
- )
+ if shortfall is not None:
+ raise RuntimeError(shortfall)
elif (
state.engine == "diffusers"
and not fam.modular_workflow
diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.py
index db45efafccf..5a13d7f1480 100644
--- a/studio/backend/core/inference/video_families.py
+++ b/studio/backend/core/inference/video_families.py
@@ -17,6 +17,7 @@ base repo, exactly like the image GGUF path.
from __future__ import annotations
+import os
import re
from dataclasses import dataclass, field
from typing import Optional
@@ -136,6 +137,17 @@ class VideoFamily:
supports_cfg: bool = True
+# MiniMax-H3 at ComfyUI's template default (ResolutionSelector 16:9, 0.4 MP, multiple 32 -> 864x480). Both sides are
+# multiples of 32 (VAE spatial compression 16 x patch 2), the only spatial rule the diffusers modular pipeline and
+# stable-diffusion.cpp (align_image_size, multiple = vae_scale_factor 16 * down_factor 2) enforce, and 864/480 = 1.8 sits
+# inside the trained 1:4..4:1 range. UNSLOTH_VIDEO_H3_480P=0 withdraws the pair.
+def _h3_480p_presets() -> tuple[tuple[int, int], ...]:
+ flag = os.environ.get("UNSLOTH_VIDEO_H3_480P", "1").strip().lower()
+ if flag in ("0", "false", "no", "off"):
+ return ()
+ return ((864, 480), (480, 864)) # fastest
+
+
_FAMILIES: tuple[VideoFamily, ...] = (
VideoFamily(
name = "minimax-h3",
@@ -165,7 +177,8 @@ _FAMILIES: tuple[VideoFamily, ...] = (
(768, 1344),
(960, 544), # faster
(544, 960), # faster
- ),
+ )
+ + _h3_480p_presets(),
duration_presets = (5.0, 10.0, 14.4),
# Decimal GB resident estimates: transformer, Qwen3-VL conditioner, video+audio VAEs.
bf16_components_gb = (66.3, 66.8, 11.1),
diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.py
index f559b8f6be6..c1a7bcf050b 100644
--- a/studio/backend/core/inference/video_minimax_h3.py
+++ b/studio/backend/core/inference/video_minimax_h3.py
@@ -104,6 +104,7 @@ def estimate_h3_diffusers_vram_gb(
transformer_gb: Optional[float] = None,
transformer_pinned: bool = False,
transformer_streamed: bool = False,
+ text_encoder_streamed: bool = False,
) -> float:
"""Measured available-VRAM floor for an H3 Diffusers generation.
@@ -112,6 +113,20 @@ def estimate_h3_diffusers_vram_gb(
keeps the released-bfloat16 floor this shipped with.
``transformer_streamed``: no two large components are ever resident together."""
volume_mpixel_frames = width * height * num_frames / 1_000_000
+ if text_encoder_streamed:
+ from .video_minimax_h3_te import H3_TE_STREAMED_GB
+ text_encoder_gb = H3_TE_STREAMED_GB
+ if transformer_streamed:
+ # Nothing big is resident: the largest phase plus the top-level group.
+ from .video_minimax_h3_residency import H3_TOP_LEVEL_GB, h3_phase_need_gb
+ return h3_phase_need_gb(
+ width,
+ height,
+ num_frames,
+ te_streamed_gb = H3_TE_STREAMED_GB,
+ fragmentation = False,
+ top_gb = H3_TOP_LEVEL_GB,
+ )
if transformer_streamed:
text_encoder = (
H3_TEXT_ENCODER_BF16_GB if text_encoder_gb is None else float(text_encoder_gb)
@@ -142,12 +157,53 @@ H3_DIFFUSERS_HOST_RAM_HIGH_VRAM_GB = 85.0
H3_DIFFUSERS_HOST_RAM_HEADROOM_GB = 5.9
+# Kill switch for the held-memory accounting below; "0" restores MemAvailable + whole RSS.
+H3_HOST_GUARD_HELD_ENV = "UNSLOTH_H3_HOST_GUARD_HELD"
+
+
+def _proc_status_kb(fields: tuple[str, ...]) -> Optional[dict[str, int]]:
+ """``/proc/self/status`` fields in kB, or None off Linux / when unreadable."""
+ try:
+ with open("/proc/self/status", encoding = "utf-8") as handle:
+ found = {}
+ for line in handle:
+ key, _, value = line.partition(":")
+ if key in fields:
+ found[key] = int(value.split()[0])
+ except (OSError, ValueError, IndexError):
+ return None
+ return found if len(found) == len(fields) else None
+
+
+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."""
+ import psutil
+
+ fields = _proc_status_kb(("RssAnon", "RssShmem"))
+ if fields is None or str(os.environ.get(H3_HOST_GUARD_HELD_ENV, "1")).strip() == "0":
+ return int(psutil.Process().memory_info().rss)
+ return (fields["RssAnon"] + fields["RssShmem"]) * 1024
+
+
+def h3_host_capacity_bytes() -> int:
+ """What the system can still hand out plus what this process already holds and the render reuses."""
+ import psutil
+ return int(psutil.virtual_memory().available) + h3_process_held_host_bytes()
+
+
+# Host floor while the int8 conditioner streams too: measured ~66 GB process peak on a Colab G4 (12 / 16 / 24 GB
+# budgets), above the 64.5 GB component sum; 70 keeps ~4 GB of margin.
+H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB = 70.0
+
+
def estimate_h3_diffusers_host_ram_gb(
available_vram_gb: float,
*,
text_encoder_gb: Optional[float] = None,
transformer_gb: Optional[float] = None,
transformer_streamed: bool = False,
+ text_encoder_streamed: bool = False,
) -> float:
"""Host-RAM floor for the offload tier selected at the available VRAM.
@@ -163,7 +219,8 @@ def estimate_h3_diffusers_host_ram_gb(
A pinned denoiser is still counted here. It lives on the device during the generation, but it
was built on the host to get there, and keeping it in the sum errs toward refusing a load that
would have fitted rather than admitting one that will not.
- A streamed denoiser counts twice (pinned staging copy; measured 80.2 GB peak vs 64.5 GB single count)."""
+ ``transformer_streamed``: the streamed denoiser keeps a pageable source beside its pinned copy and counts twice
+ (80.2 GB measured peak). A slab-arena pin holds one copy and passes False."""
# A streamed load keeps its staging copy even when free VRAM later climbs past the tier.
if available_vram_gb >= H3_DIFFUSERS_HOST_RAM_TIER_VRAM_GB and not transformer_streamed:
return H3_DIFFUSERS_HOST_RAM_HIGH_VRAM_GB
@@ -171,7 +228,107 @@ def estimate_h3_diffusers_host_ram_gb(
transformer = H3_TRANSFORMER_BF16_GB if transformer_gb is None else float(transformer_gb)
if transformer_streamed:
transformer *= 2
- return text_encoder + transformer + H3_VAE_RESIDENT_GB + H3_DIFFUSERS_HOST_RAM_HEADROOM_GB
+ total = text_encoder + transformer + H3_VAE_RESIDENT_GB + H3_DIFFUSERS_HOST_RAM_HEADROOM_GB
+ if text_encoder_streamed:
+ total = max(total, H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB)
+ return total
+
+
+def h3_host_ram_shortfall(
+ available_vram_gb: float,
+ *,
+ text_encoder_gb: Optional[float] = None,
+ transformer_gb: Optional[float] = None,
+ transformer_streamed: bool = False,
+ text_encoder_streamed: bool = False,
+) -> Optional[str]:
+ """The refusal message when the host-RAM floor exceeds ``h3_host_capacity_bytes`` (free + already held), else
+ None."""
+ required_host_gb = estimate_h3_diffusers_host_ram_gb(
+ available_vram_gb,
+ text_encoder_gb = text_encoder_gb,
+ transformer_gb = transformer_gb,
+ transformer_streamed = transformer_streamed,
+ text_encoder_streamed = text_encoder_streamed,
+ )
+ host_capacity_gb = h3_host_capacity_bytes() / 1_000_000_000
+ if host_capacity_gb + 0.5 < required_host_gb:
+ return (
+ f"MiniMax-H3 needs about {required_host_gb:.0f} GB available "
+ f"system RAM at this VRAM tier; {host_capacity_gb:.1f} GB is "
+ "available. Load the GGUF artifact instead."
+ )
+ return None
+
+
+# Extra picker tiers for the H3 Diffusers row, published on /api/system and unioned with the catalog's (widen only).
+# Picker units: total VRAM GiB, available RAM GiB. Each follows the kill switch of the behaviour it relies on:
+# - VRAM (UNSLOTH_H3_TE_STREAM): the generate guard's floor for the page's default request, so the selected row
+# renders it; 960x544 still renders on 12 GB when chosen. Without it, the catalog's 30.
+# - RAM (UNSLOTH_DIFFUSION_PIN_ARENA): the single-copy host floor (64.5 GB, or 70 GB with the conditioner streamed).
+# Without it, the catalog's 80.
+H3_DIFFUSERS_FIT_TIERS_ENV = "UNSLOTH_H3_DIFFUSERS_WIDE_TIERS"
+H3_DIFFUSERS_CATALOG_TIER_GPU_GIB = 30.0
+H3_DIFFUSERS_CATALOG_TIER_RAM_GIB = 80.0
+
+
+def _h3_streamed_default_request_gpu_gib() -> float:
+ from .video_families import detect_video_family
+
+ fam = detect_video_family("MiniMaxAI/MiniMax-H3")
+ width, height = fam.resolution_presets[0]
+ floor_gb = estimate_h3_diffusers_vram_gb(
+ width,
+ height,
+ fam.default_num_frames,
+ transformer_streamed = True,
+ text_encoder_streamed = True,
+ )
+ # Total VRAM in GiB, rounded up to half a GiB.
+ return math.ceil(floor_gb * 1e9 / 2**30 * 2) / 2
+
+
+def _h3_streamed_host_floor_gib(
+ single_host_copy: bool, text_encoder_streamed: bool = False
+) -> float:
+ from .video_minimax_h3_te import H3_TE_QUANT_RESIDENT_GB
+ floor_gb = estimate_h3_diffusers_host_ram_gb(
+ 0.0,
+ text_encoder_gb = H3_TE_QUANT_RESIDENT_GB["int8"],
+ transformer_gb = H3_TRANSFORMER_PREQUANT_GB["int8"],
+ transformer_streamed = not single_host_copy,
+ text_encoder_streamed = text_encoder_streamed,
+ )
+ # The picker reads available RAM in GiB; round up to the next whole GiB.
+ return float(math.ceil(floor_gb * 1e9 / 2**30))
+
+
+def h3_diffusers_fit_tiers() -> list[dict]:
+ """The extra picker tiers this backend admits for the H3 Diffusers row, or [] when
+ ``UNSLOTH_H3_DIFFUSERS_WIDE_TIERS=0`` turns them off, or when neither widening behaviour is
+ active (the picker then keeps the catalog's own tiers, i.e. today's routing). Torch-free: read
+ on the polled /api/system route."""
+ import os
+
+ flag = os.environ.get(H3_DIFFUSERS_FIT_TIERS_ENV, "1").strip().lower()
+ if flag in ("0", "false", "no", "off"):
+ return []
+ from .diffusion_pinned_arena import pin_arena_enabled
+ from .video_minimax_h3_te import h3_te_stream_enabled
+
+ te_streamed = h3_te_stream_enabled()
+ single_copy = pin_arena_enabled()
+ if not te_streamed and not single_copy:
+ return []
+ gpu_gib = (
+ _h3_streamed_default_request_gpu_gib() if te_streamed else H3_DIFFUSERS_CATALOG_TIER_GPU_GIB
+ )
+ ram_gib = (
+ _h3_streamed_host_floor_gib(True, text_encoder_streamed = te_streamed)
+ if single_copy
+ else H3_DIFFUSERS_CATALOG_TIER_RAM_GIB
+ )
+ return [{"gpu_gb": gpu_gib, "system_ram_gb": ram_gib, "requires_quantised_streaming": True}]
# torch.autocast casts the weight and bias of these module types to the autocast dtype on entry. Norms sit on
diff --git a/studio/backend/core/inference/video_minimax_h3_residency.py b/studio/backend/core/inference/video_minimax_h3_residency.py
new file mode 100644
index 00000000000..bc8d855cad4
--- /dev/null
+++ b/studio/backend/core/inference/video_minimax_h3_residency.py
@@ -0,0 +1,523 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Keep as much of a streamed MiniMax-H3 denoiser on the device as the card allows: the top-level group first, then a
+prefix of its block groups, re-fitted per request. Resident groups keep their pinned host copy, so demoting is free.
+
+``UNSLOTH_H3_DIT_RESIDENT=0`` keeps everything streamed.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+H3_DIT_RESIDENT_ENV = "UNSLOTH_H3_DIT_RESIDENT"
+
+# Decimal GB each phase of an H3 render needs on top of the resident set (B200 peaks at 12 / 16 / 24 / 40 GB caps).
+# running block + prefetched next block + compiled workspace
+H3_STREAM_WINDOW_GB = 1.5
+# per million pixel-frames
+H3_ACTIVATION_GB_PER_MPIXEL_FRAME = 0.08
+# fraction of the activations: 1-2 GB MLP buffers fragment the caching allocator (OOM at 1344x768x124 without it)
+H3_FRAGMENTATION_FRACTION = 0.5
+H3_VAE_DECODE_GB = 6.0
+H3_PHASE_OVERHEAD_GB = 1.8
+# top-level group: 0.81 GB int8
+H3_TOP_LEVEL_GB = 1.0
+
+
+def h3_dit_resident_enabled() -> bool:
+ return str(os.environ.get(H3_DIT_RESIDENT_ENV, "")).strip().lower() not in (
+ "0",
+ "off",
+ "false",
+ "no",
+ )
+
+
+def h3_phase_need_gb(
+ width: int,
+ height: int,
+ num_frames: int,
+ *,
+ te_streamed_gb: float,
+ fragmentation: bool = True,
+ top_gb: float = 0.0,
+) -> float:
+ """Device GB a request needs beyond the resident set: its largest phase. ``fragmentation`` is slack only the
+ residency plan keeps; the refusal floor leaves it out so residency never refuses what the streamed tier admitted."""
+ activations = H3_ACTIVATION_GB_PER_MPIXEL_FRAME * width * height * num_frames / 1_000_000
+ slack = H3_FRAGMENTATION_FRACTION if fragmentation else 0.0
+ denoise = H3_STREAM_WINDOW_GB + top_gb + activations * (1.0 + slack)
+ return max(te_streamed_gb, denoise, H3_VAE_DECODE_GB) + H3_PHASE_OVERHEAD_GB
+
+
+def _tensor_bytes(tensor: Any) -> int:
+ try:
+ from .diffusion_prequant import tensor_payload_bytes
+ return int(tensor_payload_bytes(tensor))
+ except Exception: # noqa: BLE001
+ return int(tensor.numel()) * int(tensor.element_size())
+
+
+def _group_tensors(group: Any) -> list:
+ out: list = []
+ seen: set = set()
+ for module in getattr(group, "modules", None) or ():
+ for tensor in list(module.parameters()) + list(module.buffers()):
+ if id(tensor) not in seen:
+ seen.add(id(tensor))
+ out.append(tensor)
+ for tensor in list(getattr(group, "parameters", None) or ()) + list(
+ getattr(group, "buffers", None) or ()
+ ):
+ if id(tensor) not in seen:
+ seen.add(id(tensor))
+ out.append(tensor)
+ return out
+
+
+def group_payload_bytes(group: Any) -> int:
+ return sum(_tensor_bytes(t) for t in _group_tensors(group))
+
+
+def _group_hook(module: Any) -> Any:
+ try:
+ from diffusers.hooks import group_offloading as go
+
+ registry = getattr(module, "_diffusers_hook", None)
+ if registry is None:
+ return None
+ return registry.get_hook(getattr(go, "_GROUP_OFFLOADING", "group_offloading"))
+ except Exception: # noqa: BLE001
+ return None
+
+
+def h3_offload_groups(transformer: Any) -> tuple[Optional[Any], list]:
+ """(top-level group, block groups in execution order) of a block-streamed H3 denoiser; (None, []) if not streamed."""
+ top_hook = _group_hook(transformer)
+ top = getattr(top_hook, "group", None)
+ blocks: list = []
+ seen: set = set()
+ for block in getattr(transformer, "transformer_blocks", None) or ():
+ group = getattr(_group_hook(block), "group", None)
+ if group is not None and id(group) not in seen:
+ seen.add(id(group))
+ blocks.append(group)
+ return top, blocks
+
+
+def _noop() -> None:
+ return None
+
+
+def is_resident(group: Any) -> bool:
+ return bool(getattr(group, "_unsloth_resident", False))
+
+
+def make_resident(group: Any) -> None:
+ """Onload ``group`` once and make its hooks' onload / offload no-ops, so it stays on the device."""
+ import torch
+
+ if is_resident(group):
+ return
+ # The instance attribute, not the class method: an instance override (pinned top group) is an onload path too.
+ group.onload_()
+ stream = getattr(group, "stream", None)
+ if stream is not None:
+ stream.synchronize()
+ if torch.cuda.is_available():
+ torch.cuda.current_stream().synchronize()
+ group._unsloth_saved_io = (group.__dict__.get("onload_"), group.__dict__.get("offload_"))
+ group.onload_ = _noop
+ group.offload_ = _noop
+ group._unsloth_resident = True
+
+
+def demote(group: Any) -> None:
+ """Undo ``make_resident``: restore the streaming onload / offload and move the weights back to the host copy."""
+ import torch
+
+ if not is_resident(group):
+ return
+ saved_on, saved_off = getattr(group, "_unsloth_saved_io", (None, None))
+ for name, saved in (("onload_", saved_on), ("offload_", saved_off)):
+ if saved is not None:
+ setattr(group, name, saved)
+ else:
+ group.__dict__.pop(name, None)
+ group._unsloth_resident = False
+ if torch.cuda.is_available():
+ torch.cuda.current_stream().synchronize()
+ group.offload_()
+
+
+class H3Residency:
+ """The resident set of one streamed H3 denoiser: the top-level group and a prefix of its block groups."""
+
+ def __init__(
+ self,
+ transformer: Any,
+ device: Any,
+ *,
+ logger: Any = None,
+ ) -> None:
+ self.top, self.blocks = h3_offload_groups(transformer)
+ self.device = device
+ self.logger = logger
+ self.top_bytes = group_payload_bytes(self.top) if self.top is not None else 0
+ self.block_bytes = [group_payload_bytes(g) for g in self.blocks]
+ self.max_blocks = 0
+
+ @property
+ def usable(self) -> bool:
+ return bool(self.blocks)
+
+ def resident_blocks(self) -> int:
+ n = 0
+ for group in self.blocks:
+ if not is_resident(group):
+ break
+ n += 1
+ return n
+
+ def resident_bytes(self) -> int:
+ total = self.top_bytes if (self.top is not None and is_resident(self.top)) else 0
+ return total + sum(b for g, b in zip(self.blocks, self.block_bytes) if is_resident(g))
+
+ def plan(
+ self,
+ budget_bytes: int,
+ *,
+ cap: Optional[int] = None,
+ ) -> tuple[bool, int]:
+ """(top resident, number of resident blocks) that fit ``budget_bytes``; top first, then the block prefix."""
+ if budget_bytes <= 0 or self.top is None and not self.blocks:
+ return False, 0
+ top = self.top is not None and self.top_bytes <= budget_bytes
+ left = budget_bytes - (self.top_bytes if top else 0)
+ n = 0
+ limit = len(self.blocks) if cap is None else min(cap, len(self.blocks))
+ while n < limit and self.block_bytes[n] <= left:
+ left -= self.block_bytes[n]
+ n += 1
+ return top, n
+
+ def apply(self, top: bool, n: int) -> None:
+ """Demote first (frees the device), then promote."""
+ import torch
+
+ for i in range(len(self.blocks) - 1, n - 1, -1):
+ demote(self.blocks[i])
+ if self.top is not None and not top:
+ demote(self.top)
+ if torch.cuda.is_available():
+ torch.cuda.empty_cache()
+ if self.top is not None and top:
+ make_resident(self.top)
+ for i in range(n):
+ make_resident(self.blocks[i])
+
+ def fit(
+ self,
+ budget_bytes: int,
+ *,
+ initial: bool = False,
+ ) -> tuple[bool, int]:
+ """Re-fit the resident set to ``budget_bytes`` (the device bytes the resident set may occupy)."""
+ top, n = self.plan(budget_bytes)
+ self.apply(top, n)
+ if initial:
+ self.max_blocks = n
+ if self.logger is not None:
+ self.logger.info(
+ "video.h3_residency: %d of %d denoiser blocks resident (+ top-level %s), %.2f GB on the device, "
+ "budget %.2f GB",
+ n,
+ len(self.blocks),
+ "resident" if top else "streamed",
+ self.resident_bytes() / 1e9,
+ budget_bytes / 1e9,
+ )
+ return top, n
+
+
+def release_all(residency: "H3Residency", *, logger: Any = None) -> None:
+ """Return every group of ``residency`` to streaming, including one whose onload failed partway. Never raises."""
+ import torch
+
+ groups = list(reversed(residency.blocks))
+ if residency.top is not None:
+ groups.append(residency.top)
+ for group in groups:
+ try:
+ if is_resident(group):
+ demote(group)
+ else:
+ group.offload_()
+ except Exception as exc: # noqa: BLE001
+ if logger is not None:
+ logger.warning("video.h3_residency: could not release a group: %s", exc)
+ if torch.cuda.is_available():
+ torch.cuda.empty_cache()
+
+
+def h3_held_host_bytes(*modules: Any) -> dict[str, int]:
+ """Host bytes the given components hold (tensors and group-offload host copies), pinned vs pageable, de-duplicated
+ by storage; pinned bytes rounded up to a power of two as torch's host allocator reserves them."""
+ seen: set = set()
+ pinned = 0
+ pageable = 0
+
+ def _add(tensor: Any) -> None:
+ nonlocal pinned, pageable
+ flatten = getattr(tensor, "__tensor_flatten__", None)
+ if callable(flatten) and type(tensor).__name__ not in ("Tensor", "Parameter"):
+ try:
+ for name in flatten()[0]:
+ _add(getattr(tensor, name))
+ return
+ except Exception: # noqa: BLE001
+ pass
+ try:
+ if tensor.device.type != "cpu":
+ return
+ storage = tensor.untyped_storage()
+ key = storage.data_ptr()
+ if key in seen or storage.nbytes() == 0:
+ return
+ seen.add(key)
+ nbytes = int(storage.nbytes())
+ if tensor.is_pinned():
+ pinned += 1 << (nbytes - 1).bit_length()
+ else:
+ pageable += nbytes
+ except Exception: # noqa: BLE001
+ return
+
+ for module in modules:
+ if module is None:
+ continue
+ try:
+ for tensor in list(module.parameters()) + list(module.buffers()):
+ _add(tensor)
+ for sub in module.modules():
+ group = getattr(_group_hook(sub), "group", None)
+ for tensor in (getattr(group, "cpu_param_dict", None) or {}).values():
+ _add(tensor)
+ except Exception: # noqa: BLE001
+ continue
+ return {"pinned": pinned, "pageable": pageable}
+
+
+H3_COMPILE_BELOW_HOOKS_ENV = "UNSLOTH_H3_COMPILE_BELOW_HOOKS"
+
+
+def _is_original_forward(fn: Any, module: Any) -> bool:
+ return getattr(fn, "__self__", None) is module and getattr(fn, "__func__", None) is getattr(
+ type(module), "forward", None
+ )
+
+
+def compile_blocks_below_offload_hooks(transformer: Any, logger: Any = None) -> int:
+ """Compile each streamed block's own ``forward`` instead of ``_call_impl``, so the group-offload hooks stay eager.
+
+ Traced hooks put residency and prefetch state into the guards: 40 graphs on the first render at 24 GB and more on
+ every resident-set change. ``UNSLOTH_H3_COMPILE_BELOW_HOOKS=0`` keeps the old placement."""
+ if str(os.environ.get(H3_COMPILE_BELOW_HOOKS_ENV, "")).strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ ):
+ return 0
+ kwargs = getattr(transformer, "_unsloth_regional_compile_kwargs", None)
+ if not isinstance(kwargs, dict):
+ return 0
+ import torch
+
+ guard = getattr(transformer, "_unsloth_compile_guard", None)
+ moved = 0
+ for module in list(transformer.modules()):
+ if getattr(module, "_compiled_call_impl", None) is None or _group_hook(module) is None:
+ continue
+ registry = getattr(module, "_diffusers_hook", None)
+ fn_refs = list(getattr(registry, "_fn_refs", None) or ())
+ target = next(
+ (ref for ref in fn_refs if _is_original_forward(getattr(ref, "forward", None), module)),
+ None,
+ )
+ if target is None:
+ continue
+ original = target.forward
+ compiled = torch.compile(original, **kwargs)
+ if guard is not None and callable(getattr(guard, "wrap", None)):
+ target.forward = guard.wrap(compiled, original, transformer)
+ guard.restores.append(lambda ref = target, fn = original: setattr(ref, "forward", fn))
+ else:
+ target.forward = compiled
+ module._compiled_call_impl = None
+ moved += 1
+ if moved and logger is not None:
+ logger.info(
+ "video.h3_compile: %d streamed denoiser blocks compile below their offload hooks", moved
+ )
+ return moved
+
+
+H3_TOP_GROUP_PIN_ENV = "UNSLOTH_H3_TOP_GROUP_PIN"
+
+
+def pin_streamed_top_level_group(transformer: Any, logger: Any = None) -> bool:
+ """Give a block-streamed denoiser's top-level group a pinned host copy and the blocks' copy stream.
+
+ diffusers builds it without a stream, so every forward uploads it from pageable memory and copies it back (0.45 s
+ of a 1.5 s step at 12 GB). #12389's top-level pin skips torchao weights, which this checkpoint has.
+ ``UNSLOTH_H3_TOP_GROUP_PIN=0`` keeps diffusers' group."""
+ if str(os.environ.get(H3_TOP_GROUP_PIN_ENV, "")).strip().lower() in ("0", "off", "false", "no"):
+ return False
+ from .video_minimax_h3_te import h3_te_pin_allowed
+
+ top, blocks = h3_offload_groups(transformer)
+ if not h3_te_pin_allowed(group_payload_bytes(top) if top is not None else 0):
+ if logger is not None:
+ logger.info(
+ "video.h3_top_group: left as diffusers built it (pinning not allowed on this host)"
+ )
+ return False
+ stream = next(
+ (getattr(g, "stream", None) for g in blocks if getattr(g, "stream", None) is not None), None
+ )
+ why = None
+ if top is None:
+ why = "no top-level group"
+ elif stream is None:
+ why = "the blocks have no copy stream"
+ elif getattr(top, "stream", None) is not None:
+ why = "the top-level group already streams"
+ elif getattr(top, "offload_to_disk_path", None) or not callable(
+ getattr(top, "_init_cpu_param_dict", None)
+ ):
+ why = "disk offload / unknown diffusers group"
+ elif getattr(top, "_unsloth_pinned_top", False) or is_resident(top):
+ why = "another path already pinned or holds it"
+ if why is not None:
+ if logger is not None:
+ logger.info("video.h3_top_group: left as diffusers built it (%s)", why)
+ return False
+ saved = (
+ top.stream,
+ top.low_cpu_mem_usage,
+ top.record_stream,
+ top.non_blocking,
+ top.cpu_param_dict,
+ )
+ try:
+ from .diffusion_pinned_arena import pinned_arena_for_group_offload
+
+ top.stream = stream
+ top.low_cpu_mem_usage = False
+ top.record_stream = True
+ # Blocking: nothing prefetches the top-level group.
+ top.non_blocking = False
+ with pinned_arena_for_group_offload():
+ top.cpu_param_dict = top._init_cpu_param_dict()
+ except Exception as exc: # noqa: BLE001 -- keep diffusers' group as it was
+ (
+ top.stream,
+ top.low_cpu_mem_usage,
+ top.record_stream,
+ top.non_blocking,
+ top.cpu_param_dict,
+ ) = saved
+ if logger is not None:
+ logger.warning(
+ "video.h3_top_group: pinned copy refused, keeping the pageable group: %s", exc
+ )
+ return False
+ if logger is not None:
+ logger.info(
+ "video.h3_top_group: the streamed denoiser's top-level group (%.2f GB) onloads from a pinned copy",
+ group_payload_bytes(top) / 1e9,
+ )
+ return True
+
+
+H3_VAE_PINNED_SWAP_ENV = "UNSLOTH_H3_VAE_PINNED_SWAP"
+
+
+def install_pinned_swap(
+ module: Any,
+ *,
+ logger: Any = None,
+ label: str = "component",
+) -> bool:
+ """Make a ComponentsManager-rotated module (H3's VAEs) move by re-pointing at a pinned in-place host copy.
+
+ Stock rotation uploads from pageable memory and copies back every park (3.0 s per VAE decode at 24 GB). A device
+ move uploads from the pinned copy, a CPU move only re-points; dtype changes or mismatched tensors take stock
+ ``nn.Module.to``. ``UNSLOTH_H3_VAE_PINNED_SWAP=0`` keeps stock moves."""
+ if str(os.environ.get(H3_VAE_PINNED_SWAP_ENV, "")).strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ ):
+ return False
+ if module is None or getattr(module, "_unsloth_pinned_swap", None) is not None:
+ return False
+ import torch
+
+ from .video_minimax_h3_te import _module_payload_bytes, h3_te_pin_allowed, pin_module_in_place
+
+ if not torch.cuda.is_available() or not h3_te_pin_allowed(_module_payload_bytes(module)):
+ return False
+ tensors = list(module.parameters()) + list(module.buffers())
+ if not tensors or any(t.device.type != "cpu" for t in tensors):
+ return False
+ if any(type(t.data) is not torch.Tensor for t in tensors):
+ return False
+ try:
+ pin_module_in_place(module, repoint = True)
+ except Exception as exc: # noqa: BLE001 -- stock moves
+ if logger is not None:
+ logger.warning("video.h3_pinned_swap: %s not pinned (%s)", label, exc)
+ return False
+ host: dict[int, Any] = {}
+ for tensor in list(module.parameters()) + list(module.buffers()):
+ if tensor.device.type == "cpu" and tensor.is_pinned():
+ host[id(tensor)] = tensor.data
+ stock_to = module.to
+
+ def _swap_to(*args: Any, **kwargs: Any) -> Any:
+ try:
+ device, dtype, _non_blocking, memory_format = torch._C._nn._parse_to(*args, **kwargs)
+ except Exception: # noqa: BLE001
+ return stock_to(*args, **kwargs)
+ if device is None or dtype is not None or memory_format is not None:
+ return stock_to(*args, **kwargs)
+ device = torch.device(device)
+ fallback = False
+ for tensor in list(module.parameters()) + list(module.buffers()):
+ pinned = host.get(id(tensor))
+ if pinned is None or pinned.dtype != tensor.dtype or pinned.shape != tensor.shape:
+ fallback = True
+ continue
+ if device.type == "cpu":
+ tensor.data = pinned
+ elif tensor.device != device:
+ tensor.data = pinned.to(device, non_blocking = True)
+ if fallback:
+ return stock_to(*args, **kwargs)
+ return module
+
+ module.to = _swap_to
+ module._unsloth_pinned_swap = host
+ if logger is not None:
+ logger.info(
+ "video.h3_pinned_swap: %s moves by re-pointing at a pinned host copy (%.2f GB)",
+ label,
+ sum(t.numel() * t.element_size() for t in host.values()) / 1e9,
+ )
+ return True
diff --git a/studio/backend/core/inference/video_minimax_h3_te.py b/studio/backend/core/inference/video_minimax_h3_te.py
index 386579f02b9..d18ef95f6bb 100644
--- a/studio/backend/core/inference/video_minimax_h3_te.py
+++ b/studio/backend/core/inference/video_minimax_h3_te.py
@@ -499,3 +499,211 @@ def _meta_tensor_names(module: Any) -> list[str]:
for name, tensor in chain(module.named_parameters(), module.named_buffers())
if getattr(tensor, "is_meta", False)
]
+
+
+# Streaming the conditioner: under enable_auto_cpu_offload the 27.2 GB int8 conditioner moved onto the device whole
+# (the ~29 GB floor); group offloading pages it in leaf by leaf with a prefetching copy stream.
+H3_TE_STREAM_ENV = "UNSLOTH_H3_TE_STREAM"
+# Encode footprint: the 1.56 GB embedding table + the prefetched leaf + activations (B200, 12 / 16 / 24 GB caps).
+H3_TE_STREAMED_GB = 3.0
+# Power-of-two arenas: torch's pinned allocator rounds each allocation up (13% extra pinned one by one).
+_PIN_ARENA_BYTES = 1 << 31
+_PIN_ALIGN = 512
+
+
+def h3_te_stream_enabled() -> bool:
+ """``UNSLOTH_H3_TE_STREAM=0`` keeps the conditioner in the CPU-offload rotation."""
+ import os
+ return str(os.environ.get(H3_TE_STREAM_ENV, "")).strip().lower() not in (
+ "0",
+ "off",
+ "false",
+ "no",
+ )
+
+
+def h3_te_pin_allowed(payload_bytes: int = 0) -> bool:
+ """Whether ``payload_bytes`` (at least one arena) may be pinned. The full payload, not one arena: the hosted
+ weights are mmap views already counted as available, so pinning them takes that much. Honours the group offload
+ pin switch and the ~1 GiB pinned cap of Windows / WSL. Never raises."""
+ try:
+ import os
+
+ from .diffusion_memory import GROUP_OFFLOAD_PIN_ENV, _pin_budget_mib, _pinned_memory_capped
+
+ forced = str(os.environ.get(GROUP_OFFLOAD_PIN_ENV, "")).strip().lower()
+ if forced in ("0", "off", "false", "no"):
+ return False
+ if forced in ("1", "on", "true", "yes"):
+ return True
+ if _pinned_memory_capped():
+ return False
+ budget = _pin_budget_mib()
+ return budget is not None and budget >= max(_PIN_ARENA_BYTES, int(payload_bytes)) >> 20
+ except Exception: # noqa: BLE001 -- unanswerable: stream unpinned
+ return False
+
+
+def _module_payload_bytes(module: Any) -> int:
+ seen: set = set()
+ total = 0
+ for tensor in list(module.parameters()) + list(module.buffers()):
+ if id(tensor) not in seen and tensor.device.type == "cpu":
+ seen.add(id(tensor))
+ total += tensor.numel() * tensor.element_size()
+ return total
+
+
+def _round_up(value: int, multiple: int) -> int:
+ return (value + multiple - 1) // multiple * multiple
+
+
+def pin_module_in_place(
+ module: Any,
+ *,
+ arena_bytes: int = _PIN_ARENA_BYTES,
+ _arena_factory: Any = None,
+ repoint: bool = False,
+) -> int:
+ """Move every CPU parameter / buffer of ``module`` into pinned host arenas, in place; returns pinned bytes.
+
+ Tensors are REPLACED in ``_parameters`` / ``_buffers``, not re-pointed via ``.data``: the hosted safetensors
+ tensors are views of one mmap, and ``.data =`` keeps the view's ``_base`` alive (27 GB of the mapping stayed
+ resident). Pinned, non-CPU and subclass tensors are left alone; tied tensors stay tied."""
+ import torch
+
+ slots: dict[int, list] = {} # id(tensor) -> [tensor, [(owner dict, name, is_param)]]
+ for sub in module.modules():
+ for table, is_param in ((sub._parameters, True), (sub._buffers, False)):
+ for name, tensor in list(table.items()):
+ if tensor is None:
+ continue
+ entry = slots.setdefault(id(tensor), [tensor, []])
+ entry[1].append((table, name, is_param))
+ todo = []
+ for tensor, owners in slots.values():
+ if tensor.device.type != "cpu" or type(tensor.data) is not torch.Tensor:
+ continue
+ if tensor.numel() == 0 or (_arena_factory is None and tensor.is_pinned()):
+ continue
+ todo.append((tensor, owners))
+ # Largest first, first fit.
+ todo.sort(key = lambda item: item[0].numel() * item[0].element_size(), reverse = True)
+ arenas: list[list] = [] # [arena tensor, used bytes]
+ pinned = 0
+ for tensor, owners in todo:
+ nbytes = tensor.numel() * tensor.element_size()
+ need = _round_up(nbytes, _PIN_ALIGN)
+ slot = next((a for a in arenas if a[0].numel() - a[1] >= need), None)
+ if slot is None:
+ size = max(int(arena_bytes), 1 << (need - 1).bit_length())
+ arena = (
+ _arena_factory(size)
+ if _arena_factory is not None
+ else torch.empty(size, dtype = torch.uint8, pin_memory = True)
+ )
+ slot = [arena, 0]
+ arenas.append(slot)
+ offset = slot[1]
+ view = slot[0][offset : offset + nbytes].view(tensor.dtype).view(tensor.shape)
+ view.copy_(tensor.detach())
+ if repoint:
+ # Only when the old storage is not an mmap view (weights the loader already copied or cast).
+ tensor.data = view
+ else:
+ replacement = (
+ torch.nn.Parameter(view, requires_grad = tensor.requires_grad)
+ if isinstance(tensor, torch.nn.Parameter)
+ else view
+ )
+ for table, name, _is_param in owners:
+ table[name] = replacement
+ slot[1] = offset + need
+ pinned += nbytes
+ return pinned
+
+
+def stream_h3_text_encoder(
+ manager: Any,
+ text_encoder: Any,
+ device: Any,
+ *,
+ pin: Optional[bool] = None,
+ logger: Any = None,
+) -> Optional[str]:
+ """Stream MiniMax-H3's conditioner leaf by leaf via group offloading, outside the ComponentsManager rotation.
+
+ Hooks go on ``text_encoder.model``, which the H3 encode step calls directly. ``pin=None`` decides from
+ ``h3_te_pin_allowed``. Returns ``"stream"`` (pinned) / ``"stream_lazy"``, or None with nothing changed."""
+ import torch
+
+ onload = torch.device(device)
+ target = getattr(text_encoder, "model", None)
+ if onload.type != "cuda" or target is None or not h3_te_stream_enabled():
+ return None
+ try:
+ import inspect
+
+ from diffusers.hooks import apply_group_offloading
+ except Exception: # noqa: BLE001 -- no group offloading in this diffusers
+ return None
+ from .diffusion_memory import (
+ _pin_vision_embedding_device,
+ _remove_group_offload_hooks,
+ install_group_offload_buffer_restore,
+ )
+ from .diffusion_prequant import _evict_rotation_hook, _unhook_from_manager
+
+ params = inspect.signature(apply_group_offloading).parameters
+ if pin is None:
+ pin = h3_te_pin_allowed(_module_payload_bytes(text_encoder))
+ if pin:
+ try:
+ pin_module_in_place(text_encoder)
+ except Exception as exc: # noqa: BLE001 -- pinned host RAM refused: stream unpinned
+ if logger is not None:
+ logger.warning("video.h3_te_stream: pinning failed, streaming unpinned: %s", exc)
+ pin = False
+ kwargs: dict[str, Any] = {
+ "onload_device": onload,
+ "offload_device": torch.device("cpu"),
+ "offload_type": "leaf_level",
+ "use_stream": True,
+ }
+ if "non_blocking" in params:
+ kwargs["non_blocking"] = True
+ if "record_stream" in params:
+ kwargs["record_stream"] = True
+ if "low_cpu_mem_usage" in params:
+ # Already pinned in place, so diffusers' pin_memory() returns the same tensor: no second host copy.
+ kwargs["low_cpu_mem_usage"] = not pin
+ elif not pin:
+ return None
+ try:
+ text_encoder.requires_grad_(False)
+ # The int8 weights are buffers, which stock diffusers leaves on the device after offload.
+ install_group_offload_buffer_restore()
+ apply_group_offloading(target, **kwargs)
+ # Image prompts: Qwen3-VL's position interpolation reads the offloaded embedding's CPU device (transformers 5.5).
+ _pin_vision_embedding_device(target)
+ except Exception as exc: # noqa: BLE001 -- keep the rotation
+ _remove_group_offload_hooks(target)
+ if logger is not None:
+ logger.warning(
+ "video.h3_te_stream: group offloading refused, keeping the rotation: %s", exc
+ )
+ return None
+ if not _unhook_from_manager(manager, text_encoder, logger = logger, what = "te_stream:hook"):
+ # Still in the rotation: its pre_forward would move the whole module under the group hooks.
+ _remove_group_offload_hooks(target)
+ return None
+ # The manager only evicts inside a managed pre_forward; else the last decode's VAE sits beside the encode.
+ target.register_forward_pre_hook(_evict_rotation_hook(manager, onload))
+ mode = "stream" if pin else "stream_lazy"
+ if logger is not None:
+ logger.info(
+ "video.h3_te_stream: conditioner streamed leaf by leaf on %s (%s host copy)",
+ device,
+ "pinned" if pin else "pageable",
+ )
+ return mode
diff --git a/studio/backend/main.py b/studio/backend/main.py
index faf48bb2e61..ace7b4e5d03 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -2460,6 +2460,17 @@ def _quantised_streaming() -> bool:
return bool(_quantised_streaming_capability)
+def _diffusers_offload_tiers() -> dict:
+ """Extra picker fit tiers per curated Diffusers repo (lower-cased id), in the picker's GiB units.
+ Torch-free; the picker unions them with the catalog's own tiers, so they can only widen."""
+ try:
+ from core.inference.video_minimax_h3 import h3_diffusers_fit_tiers
+ tiers = h3_diffusers_fit_tiers()
+ except Exception: # noqa: BLE001 -- a picker hint must never break the polled route
+ return {}
+ return {"minimaxai/minimax-h3": tiers} if tiers else {}
+
+
def _nvfp4_diffusion_enabled() -> bool:
"""Whether image and video generation may offer NVFP4 (``UNSLOTH_NVFP4_DIFFUSION``)."""
try:
@@ -2577,6 +2588,8 @@ def get_system_info(
"dense_quant_schemes": _dense_quant_schemes(),
# The streamed MiniMax-H3 tier needs group offload that swaps torchao weights.
"quantised_streaming": _quantised_streaming(),
+ # Backend-measured offload tiers the picker unions with the catalog's. Additive key.
+ "diffusers_offload_tiers": _diffusers_offload_tiers(),
# Torch-free env read, safe on this polled route.
"nvfp4_diffusion": _nvfp4_diffusion_enabled(),
}
diff --git a/studio/backend/tests/test_h3_host_ram_guard.py b/studio/backend/tests/test_h3_host_ram_guard.py
new file mode 100644
index 00000000000..ea0bb0590c5
--- /dev/null
+++ b/studio/backend/tests/test_h3_host_ram_guard.py
@@ -0,0 +1,214 @@
+# 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 host-RAM guard and the streamed denoiser's host footprint. CPU only, no weights.
+
+The reported failure: on a 94 GB host the Diffusers INT8 path rendered once and then refused the second
+render ("needs about 85 GB available system RAM ... 82.5 GB is available"). Measured on a 48 GB tier:
+the streamed int8 denoiser's 19.45 GB of weights held 33.8 GB of pinned host memory (torch's host
+allocator rounds every pin up to a power of two), and the guard priced the denoiser twice."""
+
+import types
+
+import pytest
+import torch
+
+from core.inference import video_minimax_h3 as vmh3
+
+
+def _arena_mod():
+ # Imported per test so each one reports on a tree that lacks the module, rather than one collection error.
+ from core.inference import diffusion_pinned_arena
+ return diffusion_pinned_arena
+
+
+def unpinned_slabs(monkeypatch):
+ """Slabs from pageable memory (no CUDA here); records every slab request."""
+ arena_mod = _arena_mod()
+ requests = []
+
+ def alloc(nbytes):
+ requests.append(nbytes)
+ return torch.empty(nbytes, dtype = torch.uint8)
+
+ monkeypatch.setattr(arena_mod, "_alloc_slab", alloc)
+ return requests
+
+
+def _storage_ptrs(tensors):
+ return {t.untyped_storage().data_ptr() for t in tensors}
+
+
+def test_arena_packs_weights_without_power_of_two_rounding(unpinned_slabs):
+ arena_mod = _arena_mod()
+ arena = arena_mod.PinnedArena(slab_bytes = 1 << 20)
+ # 200 tensors of ~30 KB: per-tensor pinning would round each to 32 KiB.
+ weights = [torch.randn(7_500 + i) for i in range(200)]
+ pinned = [arena.pin(w) for w in weights]
+ payload = sum(w.numel() * w.element_size() for w in weights)
+ per_tensor = sum(arena_mod._pow2_ceil(w.numel() * w.element_size()) for w in weights)
+ assert arena.payload_bytes == payload
+ assert all(n & (n - 1) == 0 for n in unpinned_slabs) # every slab request is a power of two
+ assert arena.reserved_bytes <= payload * 1.05 + (1 << 20)
+ assert arena.reserved_bytes < per_tensor
+ assert len(_storage_ptrs(pinned)) == len(unpinned_slabs) < len(weights)
+ for w, p in zip(weights, pinned):
+ assert p.dtype == w.dtype and p.shape == w.shape and torch.equal(p, w)
+
+
+def test_arena_rebuilds_a_torchao_weight_from_its_inner_tensors(unpinned_slabs):
+ arena_mod = _arena_mod()
+ pytest.importorskip("torchao")
+ try:
+ from torchao.quantization.granularity import PerRow
+ from torchao.quantization.quantize_.workflows import Int8Tensor
+ except ImportError:
+ pytest.skip("this torchao has no Int8Tensor")
+ src = Int8Tensor.from_hp(torch.randn(64, 32, dtype = torch.bfloat16), granularity = PerRow())
+ arena = arena_mod.PinnedArena(slab_bytes = 1 << 20)
+ out = arena.pin(src)
+ assert type(out) is type(src)
+ names, _ = src.__tensor_flatten__()
+ for name in names:
+ assert torch.equal(getattr(out, name), getattr(src, name))
+ assert _storage_ptrs([getattr(out, n) for n in names]) == _storage_ptrs(
+ [s for s, _ in arena._slabs]
+ )
+
+
+def test_group_offload_pins_through_the_arena_and_drops_the_pageable_source(unpinned_slabs):
+ arena_mod = _arena_mod()
+ go = pytest.importorskip("diffusers.hooks.group_offloading")
+ stock = go.ModuleGroup.__dict__["_to_cpu"]
+ lin = torch.nn.Linear(256, 256)
+ source_ptr = lin.weight.data_ptr()
+ with arena_mod.pinned_arena_for_group_offload(enabled = True) as arena:
+ assert arena is not None
+ copy = go.ModuleGroup._to_cpu(lin.weight, False)
+ # The parameter now reads the single copy: the pageable source is no longer referenced by it.
+ assert lin.weight.data_ptr() == copy.data_ptr() != source_ptr
+ assert arena.payload_bytes == 256 * 256 * 4
+ assert go.ModuleGroup.__dict__["_to_cpu"] is stock
+
+
+def test_pin_arena_kill_switch_leaves_group_offload_untouched(monkeypatch):
+ arena_mod = _arena_mod()
+ go = pytest.importorskip("diffusers.hooks.group_offloading")
+ stock = go.ModuleGroup.__dict__["_to_cpu"]
+ monkeypatch.setenv(arena_mod.PIN_ARENA_ENV, "0")
+ with arena_mod.pinned_arena_for_group_offload() as arena:
+ assert arena is None
+ assert go.ModuleGroup.__dict__["_to_cpu"] is stock
+
+
+def test_streamed_prequant_denoiser_keeps_one_host_copy(monkeypatch, unpinned_slabs):
+ pytest.importorskip("diffusers.hooks.group_offloading")
+ import diffusers.hooks as hooks
+
+ from core.inference import diffusion_memory as dm
+ from core.inference import diffusion_prequant as dp
+
+ monkeypatch.setattr(dp, "torchao_group_offload_supported", lambda: True)
+ monkeypatch.setattr(dp, "_unhook_from_manager", lambda *a, **k: True)
+ monkeypatch.setattr(dp, "_weights_pinnable", lambda m: True)
+ monkeypatch.setattr(dp, "_move_groups_outside_inference_mode", lambda m: None)
+ monkeypatch.setattr(dp, "_evict_rotation_hook", lambda *a: (lambda m, a: None))
+ monkeypatch.setattr(dm, "install_group_offload_buffer_restore", lambda: None)
+ monkeypatch.setattr(dm, "_streamed_pin_plan", lambda *a, **k: (True, True))
+
+ from diffusers.hooks import group_offloading as go
+
+ def fake_apply(
+ module,
+ *,
+ onload_device,
+ offload_device,
+ offload_type,
+ num_blocks_per_group,
+ use_stream,
+ non_blocking = False,
+ record_stream = False,
+ low_cpu_mem_usage = False,
+ ):
+ # What diffusers does up front with use_stream: one host copy per tensor through ModuleGroup._to_cpu.
+ module._fake_cpu_param_dict = {
+ p: go.ModuleGroup._to_cpu(p, low_cpu_mem_usage) for p in module.parameters()
+ }
+
+ monkeypatch.setattr(hooks, "apply_group_offloading", fake_apply)
+ net = torch.nn.Sequential(torch.nn.Linear(128, 128), torch.nn.Linear(128, 64))
+ mode = dp.stream_prequantized_module(object(), net, "cuda")
+ assert mode == "stream"
+ payload = sum(p.numel() * p.element_size() for p in net.parameters())
+ assert net._unsloth_pin_arena_bytes[0] == payload
+ for p, copy in net._fake_cpu_param_dict.items():
+ assert p.data_ptr() == copy.data_ptr()
+
+
+def _host(
+ monkeypatch,
+ *,
+ available_gb,
+ anon_gb,
+ shmem_gb,
+ file_gb = 0.0,
+):
+ gb = 1_000_000_000
+ monkeypatch.setattr(
+ vmh3,
+ "_proc_status_kb",
+ lambda fields: {"RssAnon": int(anon_gb * gb / 1024), "RssShmem": int(shmem_gb * gb / 1024)},
+ )
+ import psutil
+
+ monkeypatch.setattr(
+ psutil, "virtual_memory", lambda: types.SimpleNamespace(available = int(available_gb * gb))
+ )
+ monkeypatch.setattr(
+ psutil,
+ "Process",
+ lambda: types.SimpleNamespace(
+ memory_info = lambda: types.SimpleNamespace(rss = int((anon_gb + shmem_gb + file_gb) * gb))
+ ),
+ )
+
+
+def test_capacity_counts_held_memory_once_and_not_mmapped_page_cache(monkeypatch):
+ # A checkpoint still mmap'd is in MemAvailable as page cache AND in RSS as RssFile: count it once.
+ _host(monkeypatch, available_gb = 30.0, anon_gb = 36.0, shmem_gb = 20.0, file_gb = 10.8)
+ assert vmh3.h3_host_capacity_bytes() / 1e9 == pytest.approx(86.0, abs = 0.01)
+ monkeypatch.setenv(vmh3.H3_HOST_GUARD_HELD_ENV, "0")
+ assert vmh3.h3_host_capacity_bytes() / 1e9 == pytest.approx(96.8, abs = 0.01)
+
+
+def test_repeat_render_on_the_reported_94gb_host_is_admitted_with_one_host_copy(monkeypatch):
+ # The reported second render: 82.5 GB capacity at a 47 GB VRAM tier, int8 conditioner + int8 denoiser.
+ _host(monkeypatch, available_gb = 25.6, anon_gb = 36.7, shmem_gb = 20.2)
+ sizes = dict(text_encoder_gb = 27.2, transformer_gb = 20.3)
+ assert vmh3.h3_host_ram_shortfall(47.2, transformer_streamed = False, **sizes) is None
+ # The same host with the denoiser priced twice (pageable source + pinned copy) is what refused it.
+ message = vmh3.h3_host_ram_shortfall(47.2, transformer_streamed = True, **sizes)
+ assert message is not None and "85 GB" in message
+
+
+def test_a_real_host_shortfall_is_still_refused(monkeypatch):
+ _host(monkeypatch, available_gb = 3.0, anon_gb = 36.7, shmem_gb = 20.2)
+ message = vmh3.h3_host_ram_shortfall(
+ 47.2, text_encoder_gb = 27.2, transformer_gb = 20.3, transformer_streamed = False
+ )
+ assert message is not None
+ assert "Load the GGUF artifact instead" in message
+
+
+def test_the_load_records_a_single_host_copy_for_an_arena_pinned_denoiser():
+ import inspect
+
+ from core.inference import video as vid
+
+ load = inspect.getsource(vid)
+ assert (
+ 'denoiser_host_copy = denoiser_streamed == "stream" and not denoiser_single_host_copy'
+ in load
+ )
+ assert '"_unsloth_pin_arena_bytes"' in load
diff --git a/studio/backend/tests/test_h3_low_vram_stream.py b/studio/backend/tests/test_h3_low_vram_stream.py
new file mode 100644
index 00000000000..19b6f53d127
--- /dev/null
+++ b/studio/backend/tests/test_h3_low_vram_stream.py
@@ -0,0 +1,351 @@
+# 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 on 24 / 16 / 12 GB cards: the int8 conditioner streams instead of rotating onto the card whole, and a
+streamed denoiser keeps as many blocks resident as each request leaves room for."""
+
+from __future__ import annotations
+
+import gc
+import types
+import weakref
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+
+def _h3_family():
+ from core.inference.video_families import detect_video_family
+ return detect_video_family("minimax-h3")
+
+
+# ── VRAM floors ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+
[email protected]("budget_gb", [24.0, 16.0, 12.0])
+def test_a_streamed_conditioner_and_denoiser_floor_fits_small_cards(budget_gb):
+ """The old floor was the 27.2 GB conditioner + 1.8 = 29.0 GB at every size: 24 / 16 / 12 GB were all refused.
+ Usable free memory on such a card is its size minus the CUDA context and desktop (bench: 11.7 GB on a 12 GB card)."""
+ from core.inference.video_minimax_h3 import estimate_h3_diffusers_vram_gb
+
+ floor = estimate_h3_diffusers_vram_gb(
+ 960,
+ 544,
+ 124,
+ text_encoder_gb = 27.2,
+ transformer_gb = 20.3,
+ transformer_streamed = True,
+ text_encoder_streamed = True,
+ )
+ assert floor <= budget_gb - 0.6
+
+
+def test_the_rotating_conditioner_keeps_its_old_floor():
+ """Kill switch / unstreamable conditioner: the floor is exactly what it was."""
+ from core.inference.video_minimax_h3 import estimate_h3_diffusers_vram_gb
+
+ floor = estimate_h3_diffusers_vram_gb(
+ 960, 544, 124, text_encoder_gb = 27.2, transformer_gb = 20.3, transformer_streamed = True
+ )
+ assert floor == pytest.approx(29.0)
+
+
+def test_the_floor_still_grows_with_the_clip():
+ """A long, large clip must still be refused on a small card rather than run out of memory mid-render."""
+ from core.inference.video_minimax_h3 import estimate_h3_diffusers_vram_gb
+
+ def floor(w, h, f):
+ return estimate_h3_diffusers_vram_gb(
+ w,
+ h,
+ f,
+ text_encoder_gb = 27.2,
+ transformer_gb = 20.3,
+ transformer_streamed = True,
+ text_encoder_streamed = True,
+ )
+
+ assert floor(1344, 768, 345) > floor(1344, 768, 124) > floor(960, 544, 124)
+ assert floor(1344, 768, 345) > 24.0
+
+
+# ── conditioner streaming ───────────────────────────────────────────────────────────────────────────────────────────
+
+
+def test_the_conditioner_stream_kill_switch(monkeypatch):
+ from core.inference.video_minimax_h3_te import h3_te_stream_enabled, stream_h3_text_encoder
+
+ monkeypatch.setenv("UNSLOTH_H3_TE_STREAM", "0")
+ assert not h3_te_stream_enabled()
+ te = types.SimpleNamespace(model = torch.nn.Linear(2, 2))
+ assert stream_h3_text_encoder(object(), te, "cuda") is None
+ monkeypatch.delenv("UNSLOTH_H3_TE_STREAM")
+ assert h3_te_stream_enabled()
+
+
+def test_the_conditioner_never_streams_off_cuda():
+ from core.inference.video_minimax_h3_te import stream_h3_text_encoder
+ te = types.SimpleNamespace(model = torch.nn.Linear(2, 2))
+ assert stream_h3_text_encoder(object(), te, "cpu") is None
+
+
+def test_pinning_in_place_replaces_tensors_and_releases_the_originals():
+ """``.data =`` kept each view's base alive, so the conditioner's 27 GB memory-mapped file stayed resident beside
+ the pinned copy. The tensors must be REPLACED: originals released, values kept, ties kept, arenas shared."""
+ from core.inference.video_minimax_h3_te import pin_module_in_place
+
+ class M(torch.nn.Module):
+ def __init__(self):
+ super().__init__()
+ self.a = torch.nn.Linear(8, 16)
+ self.b = torch.nn.Linear(16, 8, bias = False)
+ self.register_buffer("q", torch.arange(64, dtype = torch.int8).view(8, 8))
+ self.c = torch.nn.Linear(16, 8, bias = False)
+ self.c.weight = self.b.weight # tied
+
+ m = M()
+ # Views of one flat base, like safetensors tensors over a single mapping.
+ base = torch.randn(16 * 8 + 16)
+ m.a.weight = torch.nn.Parameter(base[: 16 * 8].view(16, 8))
+ m.a.bias = torch.nn.Parameter(base[16 * 8 :])
+ expect = {k: v.detach().clone() for k, v in m.state_dict().items()}
+ base_ref = weakref.ref(base)
+ del base
+ arenas = []
+
+ def factory(size):
+ arenas.append(torch.zeros(size, dtype = torch.uint8))
+ return arenas[-1]
+
+ n = pin_module_in_place(m, arena_bytes = 4096, _arena_factory = factory)
+ gc.collect()
+ assert base_ref() is None, "the original base is still referenced"
+ assert n == sum(t.numel() * t.element_size() for t in (m.a.weight, m.a.bias, m.b.weight, m.q))
+ for k, v in m.state_dict().items():
+ assert torch.equal(v, expect[k]), k
+ assert m.c.weight is m.b.weight
+ assert len(arenas) == 1
+ ptrs = [t.untyped_storage().data_ptr() for t in (m.a.weight, m.a.bias, m.b.weight, m.q)]
+ assert set(ptrs) == {arenas[0].untyped_storage().data_ptr()}
+ assert isinstance(m.a.weight, torch.nn.Parameter) and not isinstance(m.q, torch.nn.Parameter)
+
+
+# ── denoiser residency ──────────────────────────────────────────────────────────────────────────────────────────────
+
+
+class _Group:
+ def __init__(self, nbytes):
+ self.modules = [
+ torch.nn.Linear(1, nbytes // 4, bias = False)
+ ] # nbytes/4 fp32 weights -> nbytes
+ self.parameters = []
+ self.buffers = []
+ self.stream = None
+ self.on = 0
+ self.off = 0
+ self.where = "cpu"
+
+ def onload_(self):
+ self.on += 1
+ self.where = "cuda"
+
+ def offload_(self):
+ self.off += 1
+ self.where = "cpu"
+
+
+def _residency(top_bytes, block_bytes):
+ from core.inference.video_minimax_h3_residency import H3Residency, group_payload_bytes
+
+ r = H3Residency.__new__(H3Residency)
+ r.top = _Group(top_bytes) if top_bytes else None
+ r.blocks = [_Group(b) for b in block_bytes]
+ r.device = "cuda"
+ r.logger = None
+ r.top_bytes = group_payload_bytes(r.top) if r.top is not None else 0
+ r.block_bytes = [group_payload_bytes(g) for g in r.blocks]
+ r.max_blocks = 0
+ return r
+
+
+def test_residency_spends_the_budget_on_the_top_level_then_a_block_prefix():
+ r = _residency(400, [100] * 10)
+ assert r.plan(0) == (False, 0)
+ assert r.plan(399) == (False, 3) # the top does not fit; blocks still use what is there
+ assert r.plan(400) == (True, 0)
+ assert r.plan(750) == (True, 3)
+ assert r.plan(10_000) == (True, 10)
+
+
+def test_residency_demotes_the_tail_for_a_bigger_request_and_promotes_it_back(monkeypatch):
+ from core.inference import video_minimax_h3_residency as res
+
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ r = _residency(400, [100] * 10)
+ r.fit(1000, initial = True)
+ assert r.resident_blocks() == 6 and res.is_resident(r.top)
+ assert [g.where for g in r.blocks] == ["cuda"] * 6 + ["cpu"] * 4
+ # A resident group's hooks are no-ops: the streaming hook cannot move it.
+ r.blocks[0].offload_()
+ assert r.blocks[0].where == "cuda"
+ r.fit(600)
+ assert r.resident_blocks() == 2
+ assert [g.where for g in r.blocks] == ["cuda"] * 2 + ["cpu"] * 8
+ # demoted groups stream again
+ r.blocks[3].onload_()
+ assert r.blocks[3].where == "cuda"
+ r.blocks[3].offload_()
+ r.fit(1000)
+ assert r.resident_blocks() == 6
+ r.fit(0)
+ assert (
+ r.resident_bytes() == 0 and all(g.where == "cpu" for g in r.blocks) and r.top.where == "cpu"
+ )
+
+
+def test_a_fit_that_fails_partway_releases_what_it_promoted(monkeypatch):
+ """An allocation failure on the third promotion must not leave the top and two blocks resident with no-op hooks
+ and no controller (the load then claims to be fully streamed)."""
+ from core.inference import video_minimax_h3_residency as res
+
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ r = _residency(400, [100] * 10)
+
+ def oom():
+ r.blocks[2].where = "cuda" # partly onloaded
+ raise RuntimeError("CUDA out of memory")
+
+ r.blocks[2].onload_ = oom
+ with pytest.raises(RuntimeError):
+ r.fit(10_000, initial = True)
+ assert res.is_resident(r.top) and r.resident_blocks() == 2
+ res.release_all(r)
+ assert r.resident_bytes() == 0
+ assert r.top.where == "cpu" and all(g.where == "cpu" for g in r.blocks)
+ # streaming hooks are live again
+ r.blocks[0].onload_()
+ assert r.blocks[0].where == "cuda"
+
+
+def test_residency_kill_switch(monkeypatch):
+ from core.inference.video_minimax_h3_residency import h3_dit_resident_enabled
+
+ monkeypatch.setenv("UNSLOTH_H3_DIT_RESIDENT", "0")
+ assert not h3_dit_resident_enabled()
+ monkeypatch.delenv("UNSLOTH_H3_DIT_RESIDENT")
+ assert h3_dit_resident_enabled()
+
+
+def test_the_phase_need_leaves_room_on_a_12gb_card():
+ from core.inference.video_minimax_h3_residency import h3_phase_need_gb
+ from core.inference.video_minimax_h3_te import H3_TE_STREAMED_GB
+
+ floor = h3_phase_need_gb(960, 544, 124, te_streamed_gb = H3_TE_STREAMED_GB, fragmentation = False)
+ assert floor < 11.0
+ assert h3_phase_need_gb(1344, 768, 345, te_streamed_gb = H3_TE_STREAMED_GB) > 24.0
+ # The residency plan keeps fragmentation slack free; the refusal floor does not ask for it.
+ assert h3_phase_need_gb(1344, 768, 124, te_streamed_gb = H3_TE_STREAMED_GB) > h3_phase_need_gb(
+ 1344, 768, 124, te_streamed_gb = H3_TE_STREAMED_GB, fragmentation = False
+ )
+
+
+def test_held_host_bytes_dedupes_storage():
+ from core.inference.video_minimax_h3_residency import h3_held_host_bytes
+
+ base = torch.zeros(1000)
+ m = torch.nn.Module()
+ m.register_buffer("a", base[:500])
+ m.register_buffer("b", base[500:])
+ held = h3_held_host_bytes(m, None)
+ assert held == {"pinned": 0, "pageable": 4000}
+
+
+def _tiny_qwen3_vl():
+ transformers = pytest.importorskip("transformers")
+ config_cls = getattr(transformers, "Qwen3VLConfig", None)
+ model_cls = getattr(transformers, "Qwen3VLForConditionalGeneration", None)
+ if config_cls is None or model_cls is None:
+ pytest.skip("this transformers has no Qwen3-VL (the H3 conditioner's architecture)")
+ config = config_cls(
+ text_config = dict(
+ vocab_size = 256,
+ hidden_size = 16,
+ intermediate_size = 32,
+ num_hidden_layers = 2,
+ num_attention_heads = 4,
+ num_key_value_heads = 2,
+ ),
+ vision_config = dict(
+ depth = 2,
+ hidden_size = 16,
+ intermediate_size = 32,
+ num_heads = 4,
+ out_hidden_size = 16,
+ deepstack_visual_indexes = [1],
+ ),
+ image_token_id = 250,
+ vision_start_token_id = 251,
+ vision_end_token_id = 252,
+ )
+ torch.manual_seed(0)
+ return model_cls(config).eval()
+
+
+def test_an_image_prompt_encodes_through_the_streamed_conditioner(monkeypatch):
+ """Keyframe / reference prompts run the Qwen3-VL vision tower inside the streamed conditioner. Its position
+ interpolation reads the offloaded embedding's device (CPU under group offload; transformers 5.5), which raised a
+ cuda / cpu device mismatch. The streamed encode must match the whole-module one."""
+ import copy
+ import inspect
+
+ if not torch.cuda.is_available():
+ pytest.skip("group offload streams onto a CUDA device; nothing to stream onto here")
+ import core.inference.diffusion_prequant as prequant
+ from core.inference.video_minimax_h3_te import stream_h3_text_encoder
+
+ monkeypatch.setattr(prequant, "_unhook_from_manager", lambda *a, **k: True)
+ monkeypatch.setattr(
+ prequant, "_evict_rotation_hook", lambda manager, onload: (lambda *a, **k: None)
+ )
+ reference = _tiny_qwen3_vl()
+ streamed = copy.deepcopy(reference)
+ assert stream_h3_text_encoder(object(), streamed, "cuda", pin = False) == "stream_lazy"
+
+ vision = reference.config.vision_config
+ grid = torch.tensor([[1, 4, 4]])
+ patches = int(grid.prod())
+ pixels = torch.randn(
+ patches, vision.in_channels * vision.temporal_patch_size * vision.patch_size**2
+ )
+ image_tokens = patches // vision.spatial_merge_size**2
+ ids = torch.tensor([[1, 2, 3, 251] + [250] * image_tokens + [252, 4]])
+ kwargs = dict(
+ input_ids = ids, pixel_values = pixels, image_grid_thw = grid, output_hidden_states = True
+ )
+ if "mm_token_type_ids" in inspect.signature(type(reference.model).forward).parameters:
+ kwargs["mm_token_type_ids"] = (ids == 250).long()
+ with torch.inference_mode():
+ expected = reference.cuda().model(
+ **{k: v.cuda() if torch.is_tensor(v) else v for k, v in kwargs.items()}
+ )
+ got = streamed.model(
+ **{k: v.cuda() if torch.is_tensor(v) else v for k, v in kwargs.items()}
+ )
+ torch.testing.assert_close(got.hidden_states[-1], expected.hidden_states[-1])
+
+
+def test_pinning_is_budgeted_on_the_whole_payload_not_one_arena(monkeypatch):
+ """The hosted weights are mmap views already counted as available, so pinning them takes the full payload. A host
+ with room for one arena but not the 27 GB conditioner must stream it unpinned instead of exhausting RAM at load."""
+ import core.inference.diffusion_memory as dm
+ from core.inference.video_minimax_h3_te import h3_te_pin_allowed
+
+ monkeypatch.delenv(dm.GROUP_OFFLOAD_PIN_ENV, raising = False)
+ monkeypatch.setattr(dm, "_pinned_memory_capped", lambda: False)
+ monkeypatch.setattr(dm, "_pin_budget_mib", lambda: 20 * 1024)
+ assert h3_te_pin_allowed() # one arena fits
+ assert h3_te_pin_allowed(5 * 2**30) # the VAEs
+ assert not h3_te_pin_allowed(27 * 2**30) # the conditioner does not
+ monkeypatch.setenv(dm.GROUP_OFFLOAD_PIN_ENV, "1")
+ assert h3_te_pin_allowed(27 * 2**30)
diff --git a/studio/backend/tests/test_h3_stream_compile_and_top_group.py b/studio/backend/tests/test_h3_stream_compile_and_top_group.py
new file mode 100644
index 00000000000..c7c16c9baf0
--- /dev/null
+++ b/studio/backend/tests/test_h3_stream_compile_and_top_group.py
@@ -0,0 +1,301 @@
+# 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 streamed denoiser: the regional compile sits BELOW the group-offload hooks (no recompile when the hook
+state changes), and the top-level group onloads from a pinned copy on the blocks' stream."""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+pytest.importorskip("diffusers.hooks")
+
+
+class _Block(torch.nn.Module):
+ def __init__(self):
+ super().__init__()
+ self.lin = torch.nn.Linear(8, 8)
+
+ def forward(self, x):
+ return torch.relu(self.lin(x)) + 1
+
+
+class _DiT(torch.nn.Module):
+ _repeated_blocks = ["_Block"]
+
+ def __init__(self):
+ super().__init__()
+ self.proj_in = torch.nn.Linear(8, 8)
+ self.transformer_blocks = torch.nn.ModuleList([_Block() for _ in range(3)])
+
+ def forward(self, x):
+ x = self.proj_in(x)
+ for b in self.transformer_blocks:
+ x = b(x)
+ return x
+
+
+def _streamed_dit():
+ from diffusers.hooks import apply_group_offloading
+
+ torch.manual_seed(0)
+ dit = _DiT().eval()
+ apply_group_offloading(
+ dit,
+ onload_device = torch.device("cpu"),
+ offload_device = torch.device("cpu"),
+ offload_type = "block_level",
+ num_blocks_per_group = 1,
+ )
+ return dit
+
+
+def _graphs():
+ from torch._dynamo.utils import counters
+ return counters["stats"].get("unique_graphs", 0)
+
+
+def _flip_hook_state(dit):
+ """What the resident set does: replace a block group's onload / offload with no-ops."""
+ from core.inference.video_minimax_h3_residency import h3_offload_groups, make_resident
+
+ _top, blocks = h3_offload_groups(dit)
+ make_resident(blocks[0])
+
+
+def test_compiling_below_the_hooks_does_not_recompile_when_the_hook_state_changes(monkeypatch):
+ from core.inference.video_minimax_h3_residency import compile_blocks_below_offload_hooks
+
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ torch._dynamo.reset()
+ dit = _streamed_dit()
+ x = torch.randn(2, 8)
+ with torch.no_grad():
+ eager = dit(x)
+ kwargs = {"backend": "eager", "dynamic": False, "fullgraph": False}
+ for block in dit.transformer_blocks:
+ block.compile(**kwargs)
+ dit._unsloth_regional_compile_kwargs = kwargs
+ assert compile_blocks_below_offload_hooks(dit) == 3
+ assert all(b._compiled_call_impl is None for b in dit.transformer_blocks)
+ with torch.no_grad():
+ out = dit(x)
+ assert torch.equal(out, eager)
+ before = _graphs()
+ _flip_hook_state(dit)
+ with torch.no_grad():
+ assert torch.equal(dit(x), eager)
+ assert _graphs() == before, "a hook-state change recompiled the block"
+
+
+def test_the_old_placement_recompiles_on_the_same_change(monkeypatch):
+ """Control: Module.compile traces the hooks, so the same flip compiles new graphs (the 9 s first steps)."""
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ torch._dynamo.reset()
+ dit = _streamed_dit()
+ x = torch.randn(2, 8)
+ for block in dit.transformer_blocks:
+ block.compile(backend = "eager", dynamic = False, fullgraph = False)
+ with torch.no_grad():
+ dit(x)
+ before = _graphs()
+ _flip_hook_state(dit)
+ with torch.no_grad():
+ dit(x)
+ assert _graphs() > before
+
+
+def test_compile_below_hooks_kill_switch_and_missing_kwargs(monkeypatch):
+ from core.inference.video_minimax_h3_residency import compile_blocks_below_offload_hooks
+
+ dit = _streamed_dit()
+ for block in dit.transformer_blocks:
+ block.compile(backend = "eager")
+ assert compile_blocks_below_offload_hooks(dit) == 0 # no recorded kwargs
+ dit._unsloth_regional_compile_kwargs = {"backend": "eager"}
+ monkeypatch.setenv("UNSLOTH_H3_COMPILE_BELOW_HOOKS", "0")
+ assert compile_blocks_below_offload_hooks(dit) == 0
+ assert all(b._compiled_call_impl is not None for b in dit.transformer_blocks)
+
+
+def test_regional_compile_records_its_kwargs_for_the_streamed_path():
+ import inspect
+
+ from core.inference import diffusion_speed
+ assert "_unsloth_regional_compile_kwargs" in inspect.getsource(
+ diffusion_speed._compile_repeated_blocks
+ )
+
+
+class _FakeGroup:
+ def __init__(self, stream):
+ self.stream = stream
+ self.low_cpu_mem_usage = True
+ self.record_stream = False
+ self.non_blocking = True
+ self.cpu_param_dict = {}
+ self.offload_to_disk_path = None
+ self.modules = []
+ self.parameters = []
+ self.buffers = []
+
+ def _init_cpu_param_dict(self):
+ assert self.stream is not None and not self.low_cpu_mem_usage
+ return {"w": "pinned"}
+
+ def onload_(self):
+ pass
+
+ def offload_(self):
+ pass
+
+
+def test_the_top_level_group_gets_a_pinned_copy_and_the_block_stream(monkeypatch):
+ import core.inference.video_minimax_h3_residency as res
+ import core.inference.video_minimax_h3_te as te
+
+ monkeypatch.setattr(te, "h3_te_pin_allowed", lambda *a: True)
+
+ stream = object()
+ top, block = _FakeGroup(None), _FakeGroup(stream)
+ monkeypatch.setattr(res, "h3_offload_groups", lambda t: (top, [block]))
+ assert res.pin_streamed_top_level_group(object())
+ assert top.stream is stream and top.cpu_param_dict == {"w": "pinned"}
+ assert top.record_stream and not top.non_blocking and not top.low_cpu_mem_usage
+ # idempotent: a group that already has a stream is left alone
+ assert not res.pin_streamed_top_level_group(object())
+
+
+def test_the_top_level_pin_kill_switch_and_unstreamed_blocks(monkeypatch):
+ import core.inference.video_minimax_h3_residency as res
+ import core.inference.video_minimax_h3_te as te
+
+ monkeypatch.setattr(te, "h3_te_pin_allowed", lambda *a: True)
+
+ top = _FakeGroup(None)
+ monkeypatch.setattr(res, "h3_offload_groups", lambda t: (top, [_FakeGroup(None)]))
+ assert not res.pin_streamed_top_level_group(object()) # blocks have no stream (sync tier)
+ monkeypatch.setattr(res, "h3_offload_groups", lambda t: (top, [_FakeGroup(object())]))
+ monkeypatch.setenv("UNSLOTH_H3_TOP_GROUP_PIN", "0")
+ assert not res.pin_streamed_top_level_group(object())
+ assert top.stream is None and top.cpu_param_dict == {}
+
+
+def test_a_refused_pin_restores_the_group(monkeypatch):
+ import core.inference.video_minimax_h3_residency as res
+ import core.inference.video_minimax_h3_te as te
+
+ monkeypatch.setattr(te, "h3_te_pin_allowed", lambda *a: True)
+
+ top = _FakeGroup(None)
+
+ def boom():
+ raise RuntimeError("cudaHostAlloc failed")
+
+ top._init_cpu_param_dict = boom
+ monkeypatch.setattr(res, "h3_offload_groups", lambda t: (top, [_FakeGroup(object())]))
+ assert not res.pin_streamed_top_level_group(
+ object(), logger = types.SimpleNamespace(warning = lambda *a: None)
+ )
+ assert (
+ top.stream is None
+ and top.low_cpu_mem_usage
+ and top.non_blocking
+ and top.cpu_param_dict == {}
+ )
+
+
+def test_the_top_level_pin_honours_the_host_pin_policy(monkeypatch):
+ """The pin-nothing override and the Windows / WSL pinned cap leave the top-level group pageable."""
+ import core.inference.video_minimax_h3_residency as res
+ import core.inference.video_minimax_h3_te as te
+
+ top = _FakeGroup(None)
+ monkeypatch.setattr(res, "h3_offload_groups", lambda t: (top, [_FakeGroup(object())]))
+ monkeypatch.setattr(te, "h3_te_pin_allowed", lambda *a: False)
+ assert not res.pin_streamed_top_level_group(object())
+ assert top.stream is None and top.low_cpu_mem_usage and top.cpu_param_dict == {}
+
+
+def _swap_ready(monkeypatch):
+ import core.inference.video_minimax_h3_te as te
+
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
+ monkeypatch.setattr(te, "h3_te_pin_allowed", lambda *a: True)
+ real_pin = te.pin_module_in_place
+ monkeypatch.setattr(
+ te,
+ "pin_module_in_place",
+ lambda m, **k: real_pin(m, _arena_factory = lambda n: torch.zeros(n, dtype = torch.uint8), **k),
+ )
+ monkeypatch.setattr(torch.Tensor, "is_pinned", lambda self, *a, **k: self.device.type == "cpu")
+
+
+def test_a_rotating_vae_moves_by_repointing_at_its_pinned_copy(monkeypatch):
+ from core.inference.video_minimax_h3_residency import install_pinned_swap
+
+ _swap_ready(monkeypatch)
+ vae = torch.nn.Sequential(torch.nn.Conv2d(3, 4, 3), torch.nn.GroupNorm(2, 4))
+ weight = vae[0].weight
+ expect = {k: v.clone() for k, v in vae.state_dict().items()}
+ assert install_pinned_swap(vae)
+ assert vae[0].weight is weight # identity kept (code that captured it still sees it)
+ host_ptr = weight.data_ptr()
+ # A device copy stands in for the uploaded weight; the CPU move must re-point, not copy it back.
+ weight.data = weight.data.clone()
+ vae.to("cpu")
+ assert weight.data_ptr() == host_ptr, "the CPU move copied instead of re-pointing"
+ for k, v in vae.state_dict().items():
+ assert torch.equal(v, expect[k])
+
+
[email protected](not torch.cuda.is_available(), reason = "needs a CUDA device")
[email protected]("pin_capped", [False, True], ids = ["uncapped", "windows_wsl_pin_cap"])
+def test_a_pinned_swap_round_trip_on_cuda(monkeypatch, pin_capped):
+ import core.inference.diffusion_memory as mem
+ from core.inference.video_minimax_h3_residency import install_pinned_swap
+
+ # The round trip is under test, not the host pin policy: Windows / WSL cap pinned memory, so
+ # h3_te_pin_allowed() declines there by default. Opt in through the production override.
+ monkeypatch.setattr(mem, "_pinned_memory_capped", lambda: pin_capped)
+ monkeypatch.setenv(mem.GROUP_OFFLOAD_PIN_ENV, "1")
+ vae = torch.nn.Sequential(torch.nn.Conv2d(3, 4, 3), torch.nn.GroupNorm(2, 4))
+ expect = {k: v.clone() for k, v in vae.state_dict().items()}
+ assert install_pinned_swap(vae)
+ host_ptr = vae[0].weight.data_ptr()
+ vae.to("cuda")
+ assert all(t.is_cuda for t in vae.parameters())
+ x = torch.randn(1, 3, 8, 8, device = "cuda")
+ y = vae(x)
+ vae.to("cpu")
+ assert vae[0].weight.data_ptr() == host_ptr
+ for k, v in vae.state_dict().items():
+ assert torch.equal(v, expect[k])
+ assert torch.allclose(vae.cpu()(x.cpu()), y.cpu(), atol = 1e-5)
+
+
+def test_the_pinned_swap_falls_back_on_dtype_moves_and_honours_its_kill_switch(monkeypatch):
+ from core.inference.video_minimax_h3_residency import install_pinned_swap
+
+ _swap_ready(monkeypatch)
+ vae = torch.nn.Linear(4, 4)
+ assert install_pinned_swap(vae)
+ vae.to(torch.float16) # stock path
+ assert vae.weight.dtype is torch.float16
+ vae.to("meta") # pinned copy no longer matches: stock move, still correct
+ assert vae.weight.device.type == "meta" and vae.weight.dtype is torch.float16
+ other = torch.nn.Linear(4, 4)
+ monkeypatch.setenv("UNSLOTH_H3_VAE_PINNED_SWAP", "0")
+ assert not install_pinned_swap(other)
+ assert "to" not in other.__dict__
+
+
+def test_the_pinned_swap_only_installs_from_the_parked_state(monkeypatch):
+ from core.inference.video_minimax_h3_residency import install_pinned_swap
+
+ _swap_ready(monkeypatch)
+ vae = torch.nn.Linear(4, 4).to("meta")
+ assert not install_pinned_swap(vae)
diff --git a/studio/backend/tests/test_h3_vs_comfy_default_route.py b/studio/backend/tests/test_h3_vs_comfy_default_route.py
new file mode 100644
index 00000000000..0c732a82bb6
--- /dev/null
+++ b/studio/backend/tests/test_h3_vs_comfy_default_route.py
@@ -0,0 +1,222 @@
+# 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 routing and canvas gaps found against ComfyUI's H3 int8 template.
+
+* ``/api/system.diffusers_offload_tiers`` publishes the Diffusers tiers this backend can run, so the
+ picker stops sending 24-48 GB cards to the 2.5-3.2x slower GGUF (sd-cli) row. Off with
+ ``UNSLOTH_H3_DIFFUSERS_WIDE_TIERS=0``.
+* 864x480 (ComfyUI's template default, ResolutionSelector 16:9 at 0.4 MP, multiple 32) used to be
+ refused with 422. Off with ``UNSLOTH_VIDEO_H3_480P=0``.
+"""
+
+import ast
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parent.parent
+_MAIN = (_BACKEND / "main.py").read_text(encoding = "utf-8")
+
+
+def _src(name: str) -> str:
+ node = next(
+ n for n in ast.walk(ast.parse(_MAIN)) if isinstance(n, ast.FunctionDef) and n.name == name
+ )
+ return ast.get_source_segment(_MAIN, node)
+
+
+def test_the_tiers_are_published_on_the_system_route():
+ assert '"diffusers_offload_tiers": _diffusers_offload_tiers()' in _src("get_system_info")
+
+
+def test_the_route_reader_is_torch_free_and_keyed_by_lowercased_repo(monkeypatch):
+ for name in ("torch", "diffusers", "torchao"):
+ monkeypatch.setitem(sys.modules, name, None)
+ monkeypatch.delenv("UNSLOTH_H3_DIFFUSERS_WIDE_TIERS", raising = False)
+ namespace: dict = {}
+ exec(_src("_diffusers_offload_tiers"), namespace) # noqa: S102 -- the real body
+ tiers = namespace["_diffusers_offload_tiers"]()
+ assert list(tiers) == ["minimaxai/minimax-h3"]
+ for tier in tiers["minimaxai/minimax-h3"]:
+ assert set(tier) == {"gpu_gb", "system_ram_gb", "requires_quantised_streaming"}
+ assert tier["requires_quantised_streaming"] is True
+ # Strictly wider than the catalog's static 30 GiB / 80 GiB streamed tier somewhere.
+ assert any(
+ t["gpu_gb"] < 30.0 or t["system_ram_gb"] < 80.0 for t in tiers["minimaxai/minimax-h3"]
+ )
+
+
[email protected]("flag", ["0", "false", "off", " NO "])
+def test_the_kill_switch_withdraws_every_extra_tier(monkeypatch, flag):
+ monkeypatch.setenv("UNSLOTH_H3_DIFFUSERS_WIDE_TIERS", flag)
+ from core.inference.video_minimax_h3 import h3_diffusers_fit_tiers
+
+ assert h3_diffusers_fit_tiers() == []
+ namespace: dict = {}
+ exec(_src("_diffusers_offload_tiers"), namespace) # noqa: S102
+ assert namespace["_diffusers_offload_tiers"]() == {}
+
+
+def _reload_families(monkeypatch, flag):
+ if flag is None:
+ monkeypatch.delenv("UNSLOTH_VIDEO_H3_480P", raising = False)
+ else:
+ monkeypatch.setenv("UNSLOTH_VIDEO_H3_480P", flag)
+ import core.inference.video_families as vf
+ return importlib.reload(vf)
+
+
+def families(monkeypatch):
+ yield lambda flag = None: _reload_families(monkeypatch, flag)
+ monkeypatch.delenv("UNSLOTH_VIDEO_H3_480P", raising = False)
+ import core.inference.video_families as vf
+
+ importlib.reload(vf)
+
+
+def test_comfy_template_default_864x480_is_accepted(families):
+ vf = families()
+ fam = vf.detect_video_family("MiniMaxAI/MiniMax-H3")
+ for width, height in ((864, 480), (480, 864)):
+ vf.validate_video_request_shape(fam, width, height, 124)
+ assert width % 32 == 0 and height % 32 == 0
+ assert fam.resolution_presets[0] == (1344, 768), "16:9 1344x768 stays the default"
+
+
+def test_864x480_kill_switch_restores_the_422(families):
+ vf = families("0")
+ fam = vf.detect_video_family("MiniMaxAI/MiniMax-H3")
+ assert (864, 480) not in fam.resolution_presets
+ with pytest.raises(vf.VideoShapeError):
+ vf.validate_video_request_shape(fam, 864, 480, 124)
+
+
+def test_off_canvas_sizes_are_still_refused(families):
+ vf = families()
+ fam = vf.detect_video_family("MiniMaxAI/MiniMax-H3")
+ for width, height in ((848, 480), (864, 486), (512, 512)):
+ with pytest.raises(vf.VideoShapeError):
+ vf.validate_video_request_shape(fam, width, height, 124)
+
+
+def test_the_estimators_size_864x480_below_960x544(families):
+ families()
+ from core.inference.video_minimax_h3 import estimate_h3_diffusers_vram_gb
+ assert estimate_h3_diffusers_vram_gb(864, 480, 124) < estimate_h3_diffusers_vram_gb(
+ 960, 544, 124
+ )
+
+
+ "te_stream, arena, expected",
+ [
+ (
+ None,
+ None,
+ [{"gpu_gb": 14.0, "system_ram_gb": 66.0, "requires_quantised_streaming": True}],
+ ),
+ (
+ "0",
+ None,
+ [{"gpu_gb": 30.0, "system_ram_gb": 61.0, "requires_quantised_streaming": True}],
+ ),
+ (
+ None,
+ "0",
+ [{"gpu_gb": 14.0, "system_ram_gb": 80.0, "requires_quantised_streaming": True}],
+ ),
+ ("0", "0", []),
+ ],
+)
+def test_each_widening_follows_the_kill_switch_of_the_behaviour_it_relies_on(
+ monkeypatch, te_stream, arena, expected
+):
+ # The 14 GiB tier is only true while the conditioner streams, the 61 GiB RAM tier only while the streamed denoiser
+ # holds one host copy; turning either behaviour off must withdraw exactly the widening it made possible.
+ monkeypatch.delenv("UNSLOTH_H3_DIFFUSERS_WIDE_TIERS", raising = False)
+ for name, value in (
+ ("UNSLOTH_H3_TE_STREAM", te_stream),
+ ("UNSLOTH_DIFFUSION_PIN_ARENA", arena),
+ ):
+ if value is None:
+ monkeypatch.delenv(name, raising = False)
+ else:
+ monkeypatch.setenv(name, value)
+ from core.inference.video_minimax_h3 import h3_diffusers_fit_tiers
+
+ assert h3_diffusers_fit_tiers() == expected
+
+
+def test_the_ram_tier_is_the_single_count_host_floor_in_gib():
+ from core.inference.video_minimax_h3 import estimate_h3_diffusers_host_ram_gb
+
+ floor_gb = estimate_h3_diffusers_host_ram_gb(0.0, text_encoder_gb = 27.2, transformer_gb = 20.3)
+ assert floor_gb == pytest.approx(64.5)
+ assert 60.0 < floor_gb * 1e9 / 2**30 <= 61.0
+
+
+def test_a_streamed_conditioner_raises_the_host_floor_to_the_measured_peak():
+ # Colab G4 at 24 / 16 / 12 GB budgets: ~66 GB process peak with the conditioner streamed, above the 64.5 GB sum.
+ from core.inference.video_minimax_h3 import (
+ H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB,
+ estimate_h3_diffusers_host_ram_gb,
+ )
+
+ summed = estimate_h3_diffusers_host_ram_gb(30.0, text_encoder_gb = 27.2, transformer_gb = 20.3)
+ streamed = estimate_h3_diffusers_host_ram_gb(
+ 30.0, text_encoder_gb = 27.2, transformer_gb = 20.3, text_encoder_streamed = True
+ )
+ assert summed == pytest.approx(64.5)
+ assert streamed == H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB >= 66.0 + 3.0
+ # A double-counted denoiser is still larger than the streamed-set floor and wins.
+ assert estimate_h3_diffusers_host_ram_gb(
+ 30.0,
+ text_encoder_gb = 27.2,
+ transformer_gb = 20.3,
+ transformer_streamed = True,
+ text_encoder_streamed = True,
+ ) == pytest.approx(84.8)
+
+
+def test_the_guard_prices_a_streamed_conditioner_at_the_streamed_set_floor(monkeypatch):
+ import core.inference.video_minimax_h3 as h3
+
+ monkeypatch.setattr(h3, "h3_host_capacity_bytes", lambda: int(67e9))
+ kw = dict(text_encoder_gb = 27.2, transformer_gb = 20.3)
+ assert h3.h3_host_ram_shortfall(30.0, **kw) is None
+ message = h3.h3_host_ram_shortfall(30.0, text_encoder_streamed = True, **kw)
+ assert message is not None and "70 GB" in message
+
+
+def test_the_vram_tier_admits_only_cards_that_render_the_default_request(monkeypatch):
+ """The picker's VRAM tier is the generate guard's floor for the page's default request (first preset, default
+ length), so the row it selects is never refused on the first render. A 12 GB card keeps GGUF as its default."""
+ monkeypatch.delenv("UNSLOTH_H3_DIFFUSERS_WIDE_TIERS", raising = False)
+ monkeypatch.delenv("UNSLOTH_H3_TE_STREAM", raising = False)
+ from core.inference.video_families import detect_video_family
+ from core.inference.video_minimax_h3 import (
+ estimate_h3_diffusers_vram_gb,
+ h3_diffusers_fit_tiers,
+ )
+
+ fam = detect_video_family("MiniMaxAI/MiniMax-H3")
+ width, height = fam.resolution_presets[0]
+ floor_gib = (
+ estimate_h3_diffusers_vram_gb(
+ width,
+ height,
+ fam.default_num_frames,
+ transformer_streamed = True,
+ text_encoder_streamed = True,
+ )
+ * 1e9
+ / 2**30
+ )
+ (tier,) = h3_diffusers_fit_tiers()
+ assert floor_gib <= tier["gpu_gb"] < floor_gib + 0.5
+ assert tier["gpu_gb"] > 12.0 # a 12 GB card keeps GGUF
+ assert tier["gpu_gb"] <= 15.99 # a 16 GB card still routes to the Diffusers row
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index 395aebbb812..48dd341b192 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -1115,6 +1115,21 @@ export interface DeviceBudget {
denseQuantSchemes?: readonly string[];
/** Group offload can stream torchao weights; absent = unknown, so streamed tiers are not offered. */
quantisedStreaming?: boolean;
+ /** Backend-reported extra offload tiers per lower-cased repo id (`/api/system.diffusers_offload_tiers`).
+ * Unioned with an artifact's own `offloadFitTiers`, so they can only widen; ignored for artifacts
+ * without catalog tiers, whose size rule they must not replace. */
+ extraOffloadFitTiers?: Readonly<Record<string, readonly OffloadFitTier[]>>;
+}
+
+/** The artifact's catalog tiers plus any the backend reports for it. Empty when the catalog has none. */
+function artifactOffloadTiers(
+ artifact: ModelArtifact,
+ budget: DeviceBudget,
+): readonly OffloadFitTier[] {
+ const own = artifact.offloadFitTiers ?? [];
+ if (!own.length) return own;
+ const extra = budget.extraOffloadFitTiers?.[artifact.repoId.trim().toLowerCase()];
+ return extra?.length ? [...own, ...extra] : own;
}
/** GGUF fit, delegated to the one formula the Hub badge already uses. Its old private rule
@@ -1307,7 +1322,7 @@ function fitsArtifactBudget(
budget: DeviceBudget,
): boolean {
if (artifact.offloadFitTiers?.length) {
- return artifact.offloadFitTiers.some(
+ return artifactOffloadTiers(artifact, budget).some(
(tier) => offloadTierMet(tier, budget),
);
}
@@ -1428,7 +1443,7 @@ export function catalogGroupFitsDevice(
// matching pickDefaultArtifact.
if (a.format === "gguf") return true;
if (a.offloadFitTiers?.length) {
- return a.offloadFitTiers.some(
+ return artifactOffloadTiers(a, budget).some(
(tier) => offloadTierMet(tier, budget),
);
}
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
index e8186ce2da0..1f46ae89030 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
@@ -960,6 +960,7 @@ function artifactBudget(gpu: {
systemRamAvailableGb: number;
denseQuantSchemes?: readonly string[];
quantisedStreaming?: boolean;
+ extraOffloadFitTiers?: DeviceBudget["extraOffloadFitTiers"];
}): DeviceBudget {
return {
gpuGb: gpu.memoryTotalGb,
@@ -967,6 +968,7 @@ function artifactBudget(gpu: {
// Judges a pre-quantised row by that checkpoint's size, not the bf16 shards it replaces.
denseQuantSchemes: gpu.denseQuantSchemes,
quantisedStreaming: gpu.quantisedStreaming,
+ extraOffloadFitTiers: gpu.extraOffloadFitTiers,
};
}
diff --git a/studio/frontend/src/hooks/use-gpu-info.ts b/studio/frontend/src/hooks/use-gpu-info.ts
index ef6cbe1b32e..c38132f0b44 100644
--- a/studio/frontend/src/hooks/use-gpu-info.ts
+++ b/studio/frontend/src/hooks/use-gpu-info.ts
@@ -3,6 +3,10 @@
import { useEffect, useMemo, useState } from "react";
import { normalizeDenseQuantSchemes } from "@/lib/dense-quant-schemes";
+import {
+ type ReportedOffloadFitTier,
+ normalizeReportedOffloadFitTiers,
+} from "@/lib/offload-fit-tiers";
import {
type GpuIndexKind,
type PinnableGpuContext,
@@ -56,6 +60,10 @@ export interface GpuInfo {
nvfp4Diffusion: boolean;
/** Group offload can stream torchao weights. Absent or false until resolved and on older backends. */
quantisedStreaming?: boolean;
+ /** Backend-reported extra Diffusers offload tiers per lower-cased repo id. Empty on older backends. */
+ extraOffloadFitTiers?: Readonly<
+ Record<string, readonly ReportedOffloadFitTier[]>
+ >;
name: string;
memoryTotalGb: number;
memorySharedGb: number;
@@ -124,6 +132,9 @@ function toGpuInfo(
denseQuantSchemes: normalizeDenseQuantSchemes(data?.dense_quant_schemes),
nvfp4Diffusion: data?.nvfp4_diffusion === true,
quantisedStreaming: data?.quantised_streaming === true,
+ extraOffloadFitTiers: normalizeReportedOffloadFitTiers(
+ data?.diffusers_offload_tiers,
+ ),
cpuCore: data?.cpu?.physical_count ?? 0,
cpuThread: data?.cpu?.logical_count ?? 0,
systemRamAvailableGb: data?.memory?.available_gb ?? 0,
diff --git a/studio/frontend/src/hooks/use-system.ts b/studio/frontend/src/hooks/use-system.ts
index cd4e68b6e70..98beb786922 100644
--- a/studio/frontend/src/hooks/use-system.ts
+++ b/studio/frontend/src/hooks/use-system.ts
@@ -63,6 +63,15 @@ export interface SystemInfoResponse {
nvfp4_diffusion?: boolean;
/** Whether group offload can stream torchao weights. Absent on older backends. */
quantised_streaming?: boolean;
+ /** Extra Diffusers offload fit tiers per lower-cased repo id, GiB VRAM / GiB available RAM. Absent on older backends. */
+ diffusers_offload_tiers?: Record<
+ string,
+ Array<{
+ gpu_gb: number;
+ system_ram_gb: number;
+ requires_quantised_streaming?: boolean;
+ }>
+ >;
uptime_seconds: number | null;
cpu: {
logical_count: number;
diff --git a/studio/frontend/src/lib/offload-fit-tiers.ts b/studio/frontend/src/lib/offload-fit-tiers.ts
new file mode 100644
index 00000000000..1f9c3bec962
--- /dev/null
+++ b/studio/frontend/src/lib/offload-fit-tiers.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/** One backend-reported offload fit tier in the picker's units: total VRAM of the load device in
+ * GiB and AVAILABLE system RAM in GiB. Same shape as the catalog's `OffloadFitTier`. */
+export interface ReportedOffloadFitTier {
+ gpuGb: number;
+ systemRamGb: number;
+ requiresQuantisedStreaming?: boolean;
+}
+
+/** `/api/system.diffusers_offload_tiers` as lower-cased repo id -> tiers. Anything malformed is
+ * dropped, never coerced: a tier the picker cannot read must not admit a load. A tier missing
+ * `requires_quantised_streaming` is treated as requiring it, the conservative reading. */
+export function normalizeReportedOffloadFitTiers(
+ raw: unknown,
+): Record<string, ReportedOffloadFitTier[]> {
+ const out: Record<string, ReportedOffloadFitTier[]> = {};
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+ for (const [repoId, tiers] of Object.entries(
+ raw as Record<string, unknown>,
+ )) {
+ if (!Array.isArray(tiers)) continue;
+ const kept: ReportedOffloadFitTier[] = [];
+ for (const tier of tiers) {
+ if (!tier || typeof tier !== "object") continue;
+ const t = tier as Record<string, unknown>;
+ const gpuGb = t.gpu_gb;
+ const systemRamGb = t.system_ram_gb;
+ if (
+ typeof gpuGb !== "number" ||
+ typeof systemRamGb !== "number" ||
+ !Number.isFinite(gpuGb) ||
+ !Number.isFinite(systemRamGb) ||
+ gpuGb <= 0 ||
+ systemRamGb < 0
+ )
+ continue;
+ kept.push({
+ gpuGb,
+ systemRamGb,
+ requiresQuantisedStreaming: t.requires_quantised_streaming !== false,
+ });
+ }
+ if (kept.length) out[repoId.trim().toLowerCase()] = kept;
+ }
+ return out;
+}
diff --git a/studio/frontend/tests/dense-quant-schemes-identity.test.ts b/studio/frontend/tests/dense-quant-schemes-identity.test.ts
index e91d109ec63..311db91e03b 100644
--- a/studio/frontend/tests/dense-quant-schemes-identity.test.ts
+++ b/studio/frontend/tests/dense-quant-schemes-identity.test.ts
@@ -10,6 +10,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import type * as GpuHooks from "../src/hooks/use-gpu-info.ts";
import { normalizeDenseQuantSchemes } from "../src/lib/dense-quant-schemes.ts";
+import { normalizeReportedOffloadFitTiers } from "../src/lib/offload-fit-tiers.ts";
import { loadWithStubs } from "./helpers/module-stubs.ts";
const hooks = loadWithStubs<typeof GpuHooks>(
@@ -25,6 +26,7 @@ const hooks = loadWithStubs<typeof GpuHooks>(
},
"./use-system": { getCachedSystemInfo: () => null },
"@/lib/dense-quant-schemes": { normalizeDenseQuantSchemes },
+ "@/lib/offload-fit-tiers": { normalizeReportedOffloadFitTiers },
},
{ relativePassthrough: true },
);
diff --git a/studio/frontend/tests/h3-diffusers-default-route.test.ts b/studio/frontend/tests/h3-diffusers-default-route.test.ts
new file mode 100644
index 00000000000..6bbf7643c0d
--- /dev/null
+++ b/studio/frontend/tests/h3-diffusers-default-route.test.ts
@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// MiniMax-H3's Diffusers INT8 row versus its GGUF (stable-diffusion.cpp) row. The catalog's static
+// tiers send a 48 GB card with ~77 GiB available RAM to the GGUF row, which measured 3.2x slower than
+// the INT8 path. The backend now reports the tiers it can actually run (`/api/system.diffusers_offload_tiers`);
+// the picker unions them with the catalog's, so they widen and never narrow.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ IMAGE_CATALOG,
+ VIDEO_CATALOG,
+ catalogGroupFitsDevice,
+ curatedArtifactFitsDevice,
+ groupForRepoId,
+ pickDefaultArtifact,
+} from "../src/features/model-picker/components/model-selector/model-catalog.ts";
+
+const H3 = "MiniMaxAI/MiniMax-H3";
+const h3Group = groupForRepoId(H3, VIDEO_CATALOG);
+if (!h3Group)
+ throw new Error("MiniMax-H3 group missing from the video catalog");
+const h3 = h3Group;
+const notDownloaded = () => false;
+// The shape /api/system reports, after normalisation. Values mirror the backend table.
+const EXTRA = {
+ "minimaxai/minimax-h3": [
+ { gpuGb: 14, systemRamGb: 66, requiresQuantisedStreaming: true },
+ ],
+};
+
+// GiB as the picker sees them: nvidia-smi MiB / 1024, psutil available / 1024**3.
+const HOSTS = {
+ ada48: { gpuGb: 47.99, systemRamGb: 77 },
+ rtx3090: { gpuGb: 24, systemRamGb: 80 },
+ a100_40: { gpuGb: 39.39, systemRamGb: 72 },
+ g4: { gpuGb: 95.59, systemRamGb: 160 },
+ // 16 / 12 GB cards on a 96 GB RAM desktop (~88 GiB available).
+ card16: { gpuGb: 15.99, systemRamGb: 88 },
+ card12: { gpuGb: 12, systemRamGb: 88 },
+};
+
+test("without backend tiers every listed consumer host still lands on GGUF (base routing)", () => {
+ for (const [name, host] of Object.entries(HOSTS)) {
+ if (name === "g4") continue;
+ const pick = pickDefaultArtifact(h3, {
+ ...host,
+ quantisedStreaming: true,
+ isDownloaded: notDownloaded,
+ });
+ assert.equal(pick.format, "gguf", name);
+ }
+});
+
+test("backend tiers make the Diffusers INT8 row the default where it runs", () => {
+ for (const name of [
+ "ada48",
+ "rtx3090",
+ "a100_40",
+ "g4",
+ "card16",
+ ] as const) {
+ const budget = {
+ ...HOSTS[name],
+ quantisedStreaming: true,
+ extraOffloadFitTiers: EXTRA,
+ };
+ assert.equal(
+ pickDefaultArtifact(h3, { ...budget, isDownloaded: notDownloaded })
+ .format,
+ "bf16",
+ name,
+ );
+ assert.equal(
+ curatedArtifactFitsDevice(H3, VIDEO_CATALOG, budget),
+ true,
+ name,
+ );
+ assert.equal(catalogGroupFitsDevice(h3, budget, notDownloaded), true, name);
+ }
+});
+
+test("GGUF stays the fallback when RAM, VRAM or streaming cannot fit", () => {
+ const cases = [
+ { gpuGb: 8, systemRamGb: 120, quantisedStreaming: true },
+ { gpuGb: 48, systemRamGb: 40, quantisedStreaming: true },
+ // The page's default request (1344x768, default length) needs ~13.5 GiB, so a 12 GB card keeps GGUF as its
+ // default; the Diffusers row still renders 960x544 there when chosen.
+ { gpuGb: 12, systemRamGb: 88, quantisedStreaming: true },
+ // A 64 GB RAM desktop (~58 GiB available) is under the measured 70 GB streamed-set floor.
+ { gpuGb: 12, systemRamGb: 58, quantisedStreaming: true },
+ { gpuGb: 24, systemRamGb: 58, quantisedStreaming: true },
+ { gpuGb: 48, systemRamGb: 120, quantisedStreaming: false },
+ { gpuGb: 48, systemRamGb: 120, quantisedStreaming: undefined },
+ ];
+ for (const c of cases) {
+ const pick = pickDefaultArtifact(h3, {
+ ...c,
+ extraOffloadFitTiers: EXTRA,
+ isDownloaded: notDownloaded,
+ });
+ assert.equal(pick.format, "gguf", JSON.stringify(c));
+ }
+});
+
+test("backend tiers only widen: a host the catalog admits stays admitted with none reported", () => {
+ const g4 = { ...HOSTS.g4, quantisedStreaming: true };
+ assert.equal(curatedArtifactFitsDevice(H3, VIDEO_CATALOG, g4), true);
+ assert.equal(
+ curatedArtifactFitsDevice(H3, VIDEO_CATALOG, {
+ ...g4,
+ extraOffloadFitTiers: {},
+ }),
+ true,
+ );
+});
+
+test("backend tiers never replace the size rule of an artifact without catalog tiers", () => {
+ const id = "Qwen/Qwen-Image-2512";
+ const budget = { gpuGb: 24, systemRamGb: 64, quantisedStreaming: true };
+ const before = curatedArtifactFitsDevice(id, IMAGE_CATALOG, budget);
+ assert.equal(before, false);
+ assert.equal(
+ curatedArtifactFitsDevice(id, IMAGE_CATALOG, {
+ ...budget,
+ extraOffloadFitTiers: {
+ [id.toLowerCase()]: [{ gpuGb: 1, systemRamGb: 1 }],
+ },
+ }),
+ before,
+ );
+});
diff --git a/studio/frontend/tests/memory-probe-known.test.ts b/studio/frontend/tests/memory-probe-known.test.ts
index ea1a8730f26..5bf2a3502a7 100644
--- a/studio/frontend/tests/memory-probe-known.test.ts
+++ b/studio/frontend/tests/memory-probe-known.test.ts
@@ -6,6 +6,7 @@ import test from "node:test";
import type * as GpuHooks from "../src/hooks/use-gpu-info.ts";
import type * as SystemHooks from "../src/hooks/use-system.ts";
import { normalizeDenseQuantSchemes } from "../src/lib/dense-quant-schemes.ts";
+import { normalizeReportedOffloadFitTiers } from "../src/lib/offload-fit-tiers.ts";
import { loadWithStubs } from "./helpers/module-stubs.ts";
let snapshot: unknown = null;
@@ -24,6 +25,7 @@ const hooks = loadWithStubs<typeof GpuHooks>(
// Aliased, so the passthrough above cannot resolve it. The real implementation, since a
// hand-written normaliser would answer for the source rather than from it.
"@/lib/dense-quant-schemes": { normalizeDenseQuantSchemes },
+ "@/lib/offload-fit-tiers": { normalizeReportedOffloadFitTiers },
},
{ relativePassthrough: true },
);
diff --git a/studio/frontend/tests/offload-fit-tiers.test.ts b/studio/frontend/tests/offload-fit-tiers.test.ts
new file mode 100644
index 00000000000..d54cf4666b9
--- /dev/null
+++ b/studio/frontend/tests/offload-fit-tiers.test.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeReportedOffloadFitTiers } from "../src/lib/offload-fit-tiers.ts";
+
+test("normalises /api/system.diffusers_offload_tiers and drops malformed tiers", () => {
+ assert.deepEqual(normalizeReportedOffloadFitTiers(undefined), {});
+ assert.deepEqual(normalizeReportedOffloadFitTiers([]), {});
+ assert.deepEqual(normalizeReportedOffloadFitTiers({ X: "no" }), {});
+ assert.deepEqual(
+ normalizeReportedOffloadFitTiers({
+ "MiniMaxAI/MiniMax-H3": [
+ { gpu_gb: 11, system_ram_gb: 60, requires_quantised_streaming: true },
+ { gpu_gb: 30, system_ram_gb: 60 },
+ { gpu_gb: 24, system_ram_gb: 40, requires_quantised_streaming: false },
+ { gpu_gb: "12", system_ram_gb: 60 },
+ { gpu_gb: 0, system_ram_gb: 60 },
+ { gpu_gb: Number.NaN, system_ram_gb: 60 },
+ null,
+ ],
+ }),
+ {
+ "minimaxai/minimax-h3": [
+ { gpuGb: 11, systemRamGb: 60, requiresQuantisedStreaming: true },
+ // Missing flag reads as "requires streaming", the conservative side.
+ { gpuGb: 30, systemRamGb: 60, requiresQuantisedStreaming: true },
+ { gpuGb: 24, systemRamGb: 40, requiresQuantisedStreaming: false },
+ ],
+ },
+ );
+});