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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 = Trueexcept Exception as exc: # noqa: BLE001 -- tiling is an optimisation onlylogger.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.pynew file mode 100644index 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 Truediff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.pyindex 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 directbackend.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 installeddiff --git a/studio/backend/tests/test_video_vae_untiled.py b/studio/backend/tests/test_video_vae_untiled.pynew file mode 100644index 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",)