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 video: MiniMax-H3 conditioner pin yields to a streamed denoiser on a small host (#15955)

Daniel Han2a7e3a553ea3
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index b5ef411cca6..0f9971f67c6 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -10803,12 +10803,6 @@ class VideoBackend:
stream_prequantized_module,
)
- if text_encoder_quant_engaged is not None:
- # Stream the conditioner, not rotate it; denoiser sizing assumes rotation; None keeps 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,
@@ -10827,6 +10821,19 @@ class VideoBackend:
)
== "stream"
)
+ if text_encoder_quant_engaged is not None:
+ # Stream the conditioner, not rotate it; denoiser sizing assumes rotation; None keeps rotation.
+ from .video_minimax_h3_te import h3_te_pin_yields, stream_h3_text_encoder
+ te_module = getattr(pipe, "text_encoder", None)
+ te_streamed = stream_h3_text_encoder(
+ manager,
+ te_module,
+ device,
+ pin = h3_te_pin_yields(
+ te_module, denoiser if stream else None, device, logger = logger
+ ),
+ logger = logger,
+ )
placed = (
stream_prequantized_module(manager, denoiser, device, logger = logger)
if stream
diff --git a/studio/backend/core/inference/video_minimax_h3_te.py b/studio/backend/core/inference/video_minimax_h3_te.py
index eb364670a4b..f2a364e7688 100644
--- a/studio/backend/core/inference/video_minimax_h3_te.py
+++ b/studio/backend/core/inference/video_minimax_h3_te.py
@@ -412,6 +412,63 @@ def h3_te_pin_allowed(payload_bytes: int = 0, device: Any = None) -> bool:
return False
+H3_TE_PIN_YIELD_ENV = "UNSLOTH_H3_TE_PIN_YIELD"
+
+
+def h3_te_pin_yields(
+ text_encoder: Any,
+ streamed_denoiser: Any,
+ device: Any = None,
+ logger: Any = None,
+) -> Optional[bool]:
+ """False when the conditioner alone fits the pin budget but not beside the denoiser that will stream: the
+ denoiser's blocks are read every step, the conditioner once per prompt, so the denoiser keeps the budget. None
+ leaves the decision to ``stream_h3_text_encoder``. ``UNSLOTH_H3_TE_PIN_YIELD=0`` turns it off. Never raises."""
+ try:
+ import os
+
+ if str(os.environ.get(H3_TE_PIN_YIELD_ENV, "")).strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ ):
+ return None
+ if text_encoder is None or streamed_denoiser is None:
+ return None
+ te_bytes = _module_payload_bytes(text_encoder)
+ dit_bytes = _host_payload_bytes(streamed_denoiser)
+ if dit_bytes <= 0 or not h3_te_pin_allowed(te_bytes, device):
+ return None
+ if h3_te_pin_allowed(te_bytes + dit_bytes, device):
+ return None
+ if logger is not None:
+ from .diffusion_memory import _pin_budget_mib
+ logger.info(
+ "video.h3_te_stream: the conditioner (%.1f GB) streams from pageable memory so the streamed "
+ "denoiser (%.1f GB) can pin first (%s MiB pinnable)",
+ te_bytes / 1e9,
+ dit_bytes / 1e9,
+ _pin_budget_mib(),
+ )
+ return False
+ except Exception: # noqa: BLE001 -- keep the stock decision
+ return None
+
+
+def _host_payload_bytes(module: Any) -> int:
+ """Host bytes of ``module``'s CPU tensors, torchao subclasses at their inner (int8) size, not their bf16 shape."""
+ from .diffusion_prequant import tensor_payload_bytes
+
+ 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_payload_bytes(tensor)
+ return total
+
+
def _module_payload_bytes(module: Any) -> int:
seen: set = set()
total = 0
diff --git a/studio/backend/tests/test_video_h3_te_quant.py b/studio/backend/tests/test_video_h3_te_quant.py
index 0809ec2a054..04ff6ea1d2f 100644
--- a/studio/backend/tests/test_video_h3_te_quant.py
+++ b/studio/backend/tests/test_video_h3_te_quant.py
@@ -681,3 +681,64 @@ def test_a_projection_left_dense_is_refused_not_budgeted():
assert _dense_names(nn.ModuleList([_Layer(False), _Layer(False)])) == []
assert _dense_names(nn.ModuleList([_Layer(False), _Layer(True)])) == ["1.self_attn.q_proj"]
assert not isinstance(quantized_cls(8, 8, False, 256), nn.Linear)
+
+
+def _pin_world(monkeypatch, budget_bytes):
+ from core.inference import video_minimax_h3_te as te
+
+ sizes = {}
+ monkeypatch.setattr(te, "_module_payload_bytes", lambda m: sizes[id(m)])
+ monkeypatch.setattr(te, "_host_payload_bytes", lambda m: sizes[id(m)])
+ monkeypatch.setattr(
+ te, "h3_te_pin_allowed", lambda payload = 0, device = None: payload <= budget_bytes
+ )
+ return te, sizes
+
+
+ "budget,te_gb,dit_gb,expected",
+ [
+ (60, 27, 20, None),
+ (40, 27, 20, False),
+ (20, 27, 20, None),
+ (15, 10, 20, False),
+ ],
+)
+def test_conditioner_pin_yields_to_a_streamed_denoiser(
+ monkeypatch, budget, te_gb, dit_gb, expected
+):
+ te, sizes = _pin_world(monkeypatch, budget * 10**9)
+ enc, dit = object(), object()
+ sizes[id(enc)], sizes[id(dit)] = te_gb * 10**9, dit_gb * 10**9
+ assert te.h3_te_pin_yields(enc, dit) is expected
+
+
+def test_conditioner_pin_yield_needs_a_streamed_denoiser_and_has_a_kill_switch(monkeypatch):
+ te, sizes = _pin_world(monkeypatch, 40 * 10**9)
+ enc, dit = object(), object()
+ sizes[id(enc)], sizes[id(dit)] = 27 * 10**9, 20 * 10**9
+ assert te.h3_te_pin_yields(enc, None) is None
+ monkeypatch.setenv(te.H3_TE_PIN_YIELD_ENV, "0")
+ assert te.h3_te_pin_yields(enc, dit) is None
+
+
+def test_h3_placement_sizes_the_stream_before_it_pins_the_conditioner():
+ import inspect
+
+ from core.inference.video import VideoBackend
+
+ src = inspect.getsource(VideoBackend)
+ call = src.index("pin = h3_te_pin_yields(")
+ assert call - src.rindex("_h3_placement_tier(", 0, call) < 1500
+
+
+def test_streamed_denoiser_is_priced_at_its_int8_payload():
+ import torch
+ from torchao.quantization import Int8DynamicActivationInt8WeightConfig, quantize_
+
+ from core.inference import video_minimax_h3_te as te
+
+ lin = torch.nn.Linear(256, 512, bias = False).to(torch.bfloat16)
+ quantize_(lin, Int8DynamicActivationInt8WeightConfig())
+ payload = te._host_payload_bytes(lin)
+ assert 512 * 256 <= payload < 512 * 256 * 2