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: decode a resident Wan2.2-TI2V-5B VAE untiled when it fits (#12603)

Daniel Han037c518f79b1
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index ca60e99c5ff..ef73841f874 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -6484,6 +6484,15 @@ class VideoBackend:
vae_tiling = True
except Exception as exc: # noqa: BLE001 -- tiling is an optimisation only
logger.warning("video.vae_tiling_failed: %s", exc)
+ # Resident: decode untiled when it fits, tiled as fallback. Not on SPEED_OFF, which must stay bit-identical.
+ if (
+ offload_policy == "none"
+ and target.device == "cuda"
+ and effective_speed != SPEED_OFF
+ ):
+ from .video_vae_untiled import install_untiled_decode
+ if install_untiled_decode(pipe, fam.name, logger = logger):
+ speed_optims += ("vae_untiled_when_fits",)
# Wan's decode also grows within a single tile, which tiling alone cannot bound.
install_decoder_sync(pipe, target, logger = logger)
diff --git a/studio/backend/core/inference/video_vae_untiled.py b/studio/backend/core/inference/video_vae_untiled.py
new file mode 100644
index 00000000000..115af1578fb
--- /dev/null
+++ b/studio/backend/core/inference/video_vae_untiled.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Decode a resident video VAE untiled per call when its estimated peak fits in free memory; tiled otherwise or on OOM."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+UNTILED_ENV = "UNSLOTH_VIDEO_VAE_UNTILED"
+
+# Untiled fp16 decode peak per latent pixel (h x w), measured on a B200; frame count does not enter (Wan's causal cache
+# decodes one latent frame at a time). Scaled by the decoder's element size: fp32 peaked at 21.1 GiB vs fp16 9.6 GiB.
+_BYTES_PER_LATENT_PIXEL = {
+ "wan2.2-ti2v-5b": 2.5 * 2**20,
+}
+# (spatial, temporal) upsampling to the RGB output, which Wan's decode holds about twice (per-frame torch.cat, then
+# clamp) and which grows with frames: 1021 frames at 1280x704 is 5.2 GiB per fp16 copy.
+_OUTPUT_SCALE = {
+ "wan2.2-ti2v-5b": (16, 4),
+}
+_MARGIN = 1.25
+_MARGIN_BYTES = 2 * 2**30
+
+
+def _enabled() -> bool:
+ return os.environ.get(UNTILED_ENV, "").strip().lower() not in ("0", "false", "no", "off")
+
+
+def untiled_decode_bytes(
+ family: str,
+ latent_shape: tuple,
+ itemsize: int = 2,
+) -> Optional[int]:
+ """Extra bytes of an untiled decode of ``latent_shape`` (B, C, T, h, w), or None if unmeasured."""
+ coef = _BYTES_PER_LATENT_PIXEL.get(family)
+ if coef is None or len(latent_shape) != 5:
+ return None
+ batch, _, latent_frames, height, width = (int(x) for x in latent_shape)
+ batch, itemsize = max(1, batch), max(2, itemsize)
+ spatial, temporal = _OUTPUT_SCALE[family]
+ frames = (max(1, latent_frames) - 1) * temporal + 1
+ output = 2 * batch * 3 * frames * height * spatial * width * spatial * itemsize
+ return int(coef * itemsize / 2 * batch * height * width + output)
+
+
+def _decoder_itemsize(vae: Any) -> int:
+ """Decoder weight element size; 4 if unreadable."""
+ try:
+ for param in vae.decoder.parameters():
+ if param.is_floating_point():
+ return int(param.element_size())
+ except Exception: # noqa: BLE001
+ pass
+ return 4
+
+
+def _free_bytes(device: Any) -> Optional[int]:
+ """Device free memory plus torch's unused cache."""
+ try:
+ import torch
+
+ free, _ = torch.cuda.mem_get_info(device)
+ cached = torch.cuda.memory_reserved(device) - torch.cuda.memory_allocated(device)
+ return int(free) + max(0, int(cached))
+ except Exception: # noqa: BLE001
+ return None
+
+
+def install_untiled_decode(
+ pipe: Any,
+ family: str,
+ *,
+ logger: Any = None,
+) -> bool:
+ """Wrap ``pipe.vae.decode`` to decode untiled when it fits; the caller gates on placement and speed tier."""
+ vae = getattr(pipe, "vae", None)
+ decode = getattr(vae, "decode", None)
+ if not _enabled() or vae is None or not callable(decode):
+ return False
+ if family not in _BYTES_PER_LATENT_PIXEL or not getattr(vae, "use_tiling", False):
+ return False
+ if getattr(decode, "_unsloth_untiled_decode", False):
+ return True
+ stats = {"untiled": 0, "tiled": 0, "oom_fallback": 0}
+ # Smallest estimate that ran out of memory; never retried untiled.
+ oom_need: list = []
+
+ def gated(z: Any, *args: Any, **kwargs: Any) -> Any:
+ if not getattr(vae, "use_tiling", False):
+ return decode(z, *args, **kwargs)
+ need = untiled_decode_bytes(
+ family, tuple(getattr(z, "shape", ())), itemsize = _decoder_itemsize(vae)
+ )
+ free = _free_bytes(getattr(z, "device", None))
+ fits = (
+ need is not None
+ and free is not None
+ and need * _MARGIN + _MARGIN_BYTES <= free
+ and not (oom_need and need >= oom_need[0])
+ )
+ if logger is not None:
+ logger.info(
+ "video.vae_untiled: decode %s (untiled needs ~%s MiB with margin, %s MiB free)",
+ "untiled" if fits else "tiled",
+ "?" if need is None else int((need * _MARGIN + _MARGIN_BYTES) / 2**20),
+ "?" if free is None else int(free / 2**20),
+ )
+ if not fits:
+ stats["tiled"] += 1
+ return decode(z, *args, **kwargs)
+ import torch
+
+ from .diffusion_batched import is_oom_error
+
+ vae.use_tiling = False
+ try:
+ out = decode(z, *args, **kwargs)
+ stats["untiled"] += 1
+ return out
+ except Exception as exc: # noqa: BLE001
+ if not is_oom_error(exc):
+ raise
+ finally:
+ vae.use_tiling = True
+ # Retried outside the handler so the failed attempt's tensors (held by the traceback) are gone first.
+ stats["oom_fallback"] += 1
+ oom_need[:] = [min([need, *oom_need])]
+ torch.cuda.empty_cache()
+ if logger is not None:
+ logger.warning("video.vae_untiled: untiled decode ran out of memory; decoding tiled")
+ return decode(z, *args, **kwargs)
+
+ def untiled_when_fits(*args: Any, **kwargs: Any) -> Any:
+ try:
+ return gated(*args, **kwargs)
+ finally:
+ # A failed VAE compile restores its eager decode into this slot; the guarded inner call already runs eager.
+ if vae.__dict__.get("decode") is not untiled_when_fits:
+ vae.decode = untiled_when_fits
+
+ untiled_when_fits._unsloth_untiled_decode = True
+ untiled_when_fits._unsloth_untiled_stats = stats
+ vae.decode = untiled_when_fits
+ if logger is not None:
+ logger.info("video.vae_untiled: resident %s VAE decodes untiled when it fits", family)
+ return True
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index f428f87d01f..c2399aa5ffc 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -12638,3 +12638,57 @@ def test_ltx23_reads_the_checkpoint_onto_the_card_only_for_a_resident_dit(
assert seen["text_encoder_device"] is (sentinel if te_direct else None)
assert bool(asked) is direct
backend.unload()
+
+
+def _cuda_wan_load(monkeypatch, *, policy, speed_mode):
+ """Load Wan2.2-TI2V-5B on a stubbed CUDA target with ``apply_memory_plan`` returning ``policy``."""
+ torch = sys.modules["torch"]
+ monkeypatch.setattr(
+ torch,
+ "cuda",
+ types.SimpleNamespace(is_available = lambda: False, synchronize = lambda: None),
+ raising = False,
+ )
+ monkeypatch.setattr(
+ "core.inference.video.resolve_diffusion_device_target",
+ lambda: DiffusionDeviceTarget(
+ device = "cuda",
+ dtype = torch.bfloat16,
+ backend = "cuda",
+ vendor = None,
+ supports_model_cpu_offload = False,
+ supports_default_torch_compile = False,
+ supports_pinned_transfer = False,
+ ),
+ )
+ monkeypatch.setattr(
+ "core.inference.video.settled_snapshot_device_memory", _fits_in_memory_snapshot("cuda")
+ )
+ _stub_apply_memory_plan(monkeypatch, video_module, policy = policy, vae_tiling = True)
+ backend = VideoBackend()
+ return backend.load_pipeline(
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = speed_mode
+ )
+
+
+ "policy,speed_mode,installed",
+ [("none", "default", True), ("model", "default", False), ("none", "off", False)],
+)
+def test_resident_wan_load_decodes_untiled_when_it_fits(
+ fake_runtime, monkeypatch, policy, speed_mode, installed
+):
+ # Tiling is forced on for every conventional video load; a resident CUDA pipeline additionally gets the
+ # untiled-when-it-fits decode (reported in speed_optims). Offloaded and SPEED_OFF loads keep the plain tiled decode.
+ from core.inference import video_vae_untiled
+
+ calls = []
+ monkeypatch.setattr(
+ video_vae_untiled,
+ "install_untiled_decode",
+ lambda pipe, family, logger = None: calls.append(family) or True,
+ )
+ status = _cuda_wan_load(monkeypatch, policy = policy, speed_mode = speed_mode)
+ assert status["loaded"] is True
+ assert calls == (["wan2.2-ti2v-5b"] if installed else [])
+ assert ("vae_untiled_when_fits" in status["speed_optims"]) is installed
diff --git a/studio/backend/tests/test_video_vae_untiled.py b/studio/backend/tests/test_video_vae_untiled.py
new file mode 100644
index 00000000000..110ffc7fe76
--- /dev/null
+++ b/studio/backend/tests/test_video_vae_untiled.py
@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Resident video VAE decodes untiled when it fits, tiled otherwise, and falls back to tiled on OOM."""
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import video_vae_untiled as U
+
+
+class FakeVAE:
+ def __init__(
+ self,
+ oom_untiled = False,
+ dtype = torch.float16,
+ error = None,
+ ):
+ self.error = error
+ self.decoder = torch.nn.Conv3d(1, 1, 1).to(dtype)
+ self.use_tiling = True
+ self.calls = []
+ self.oom_untiled = oom_untiled
+
+ def decode(
+ self,
+ z,
+ return_dict = False,
+ ):
+ self.calls.append(self.use_tiling)
+ if not self.use_tiling and self.error is not None:
+ raise self.error
+ if not self.use_tiling and self.oom_untiled:
+ raise torch.cuda.OutOfMemoryError("fake")
+ return ("tiled" if self.use_tiling else "untiled",)
+
+
+def _pipe(vae):
+ return types.SimpleNamespace(vae = vae)
+
+
+WAN = "wan2.2-ti2v-5b"
+Z = torch.zeros(1, 48, 31, 44, 80)
+
+
+def test_untiled_when_it_fits(monkeypatch):
+ vae = FakeVAE()
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ assert U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z, return_dict = False) == ("untiled",)
+ assert vae.use_tiling is True # restored after the call
+ assert vae.decode._unsloth_untiled_stats == {"untiled": 1, "tiled": 0, "oom_fallback": 0}
+
+
+def test_tiled_when_it_does_not_fit(monkeypatch):
+ vae = FakeVAE()
+ need = U.untiled_decode_bytes(WAN, tuple(Z.shape))
+ monkeypatch.setattr(U, "_free_bytes", lambda device: need) # below estimate x margin
+ assert U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z) == ("tiled",)
+ assert vae.calls == [True]
+
+
+def test_tiled_when_memory_unreadable(monkeypatch):
+ vae = FakeVAE()
+ monkeypatch.setattr(U, "_free_bytes", lambda device: None)
+ U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z) == ("tiled",)
+
+
+def test_oom_falls_back_to_tiled(monkeypatch):
+ vae = FakeVAE(oom_untiled = True)
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ monkeypatch.setattr(torch.cuda, "empty_cache", lambda: None)
+ U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z) == ("tiled",)
+ assert vae.calls == [False, True]
+ assert vae.use_tiling is True
+ assert vae.decode._unsloth_untiled_stats["oom_fallback"] == 1
+
+
+def test_not_installed_for_unmeasured_family_or_untiled_vae_or_env(monkeypatch):
+ assert not U.install_untiled_decode(_pipe(FakeVAE()), "hunyuanvideo-1.5")
+ vae = FakeVAE()
+ vae.use_tiling = False
+ assert not U.install_untiled_decode(_pipe(vae), WAN)
+ monkeypatch.setenv(U.UNTILED_ENV, "0")
+ assert not U.install_untiled_decode(_pipe(FakeVAE()), WAN)
+
+
+def test_install_is_idempotent(monkeypatch):
+ vae = FakeVAE()
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ assert U.install_untiled_decode(_pipe(vae), WAN)
+ first = vae.decode
+ assert U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode is first
+
+
+def test_estimate_scales_with_latent_area_and_output_frames():
+ a = U.untiled_decode_bytes(WAN, (1, 48, 31, 44, 80))
+ b = U.untiled_decode_bytes(WAN, (1, 48, 5, 44, 80))
+ c = U.untiled_decode_bytes(WAN, (1, 48, 31, 88, 80))
+ assert c == 2 * a
+ # 121 -> 17 frames: only the RGB output (held twice) shrinks.
+ assert a - b == 2 * 3 * (121 - 17) * 704 * 1280 * 2
+ # 1021 frames at 1280x704 holds ~10 GiB of fp16 output on top of the per-frame peak.
+ long = U.untiled_decode_bytes(WAN, (1, 48, 256, 44, 80))
+ assert long - b >= 10 * 2**30 - 2 * 3 * 17 * 704 * 1280 * 2
+ assert U.untiled_decode_bytes("nope", (1, 48, 31, 44, 80)) is None
+
+
+def test_fp32_decoder_needs_twice_the_fp16_estimate(monkeypatch):
+ # Wan's untiled fp32 decode peaked at 21.1 GiB against 9.6 GiB fp16 (1280x704): a gate sized for fp16 must not
+ # send an fp32 decoder untiled.
+ fp16_gate = U.untiled_decode_bytes(WAN, tuple(Z.shape)) * U._MARGIN + U._MARGIN_BYTES
+ monkeypatch.setattr(U, "_free_bytes", lambda device: int(fp16_gate) + 1)
+ half, full = FakeVAE(), FakeVAE(dtype = torch.float32)
+ U.install_untiled_decode(_pipe(half), WAN)
+ U.install_untiled_decode(_pipe(full), WAN)
+ assert half.decode(Z) == ("untiled",)
+ assert full.decode(Z) == ("tiled",)
+ assert U.untiled_decode_bytes(WAN, tuple(Z.shape), itemsize = 4) == 2 * U.untiled_decode_bytes(
+ WAN, tuple(Z.shape)
+ )
+
+
+ "error",
+ [
+ RuntimeError("HIP out of memory. Tried to allocate 2.00 GiB"),
+ RuntimeError("compile failed"),
+ ],
+)
+def test_wrapped_or_backend_oom_falls_back_other_errors_raise(monkeypatch, error):
+ if error.args[0] == "compile failed":
+ error.__cause__ = torch.cuda.OutOfMemoryError("inner")
+ vae = FakeVAE(error = error)
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ monkeypatch.setattr(torch.cuda, "empty_cache", lambda: None)
+ U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z) == ("tiled",)
+ assert vae.use_tiling is True
+
+
+def test_non_oom_error_raises_and_restores_tiling(monkeypatch):
+ vae = FakeVAE(error = ValueError("bad latent"))
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ U.install_untiled_decode(_pipe(vae), WAN)
+ with pytest.raises(ValueError):
+ vae.decode(Z)
+ assert vae.use_tiling is True
+
+
+def test_estimate_that_ran_out_of_memory_is_not_retried_untiled(monkeypatch):
+ vae = FakeVAE(oom_untiled = True)
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ monkeypatch.setattr(torch.cuda, "empty_cache", lambda: None)
+ U.install_untiled_decode(_pipe(vae), WAN)
+ assert vae.decode(Z) == ("tiled",)
+ assert vae.decode(Z) == ("tiled",)
+ assert vae.calls == [False, True, True]
+ assert vae.decode._unsloth_untiled_stats["oom_fallback"] == 1
+ # a smaller clip still tries untiled
+ vae.decode(torch.zeros(1, 48, 2, 44, 80))
+ assert vae.calls[-2:] == [False, True]
+
+
+def test_wrapper_survives_a_compile_fallback_replacing_the_slot(monkeypatch):
+ # _guard_compiled_decode writes its eager decode back into vae.decode when the compile fails mid-call.
+ vae = FakeVAE()
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 100 * 2**30)
+ eager = vae.decode
+
+ def compiled_then_fails(z, *args, **kwargs):
+ vae.decode = eager
+ return eager(z, *args, **kwargs)
+
+ vae.decode = compiled_then_fails
+ U.install_untiled_decode(_pipe(vae), WAN)
+ wrapper = vae.decode
+ assert wrapper(Z) == ("untiled",)
+ assert vae.decode is wrapper
+ assert vae.decode(Z) == ("untiled",)