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: decode the Wan VAE untiled or in the fewest tiles that fit, also when offloaded (#15148)

Daniel Hanae0b163c8f26
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index f982a6f92ad..f998777e351 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -9844,9 +9844,9 @@ class VideoBackend:
speed_optims += ("vae_wide_tiles",)
except Exception as exc: # noqa: BLE001 - keep the stock tiled decode
logger.warning("video.vae_wide_tiles: not installed: %s", exc)
- # Resident: decode untiled when it fits, tiled as fallback. Not on SPEED_OFF, which must stay bit-identical.
+ # Untiled when it fits (free memory read at decode time); not on SPEED_OFF (bit-identical) or sequential offload.
if (
- offload_policy == "none"
+ offload_policy in (OFFLOAD_NONE, OFFLOAD_MODEL, OFFLOAD_GROUP, OFFLOAD_STREAMING)
and target.device == "cuda"
and effective_speed != SPEED_OFF
):
diff --git a/studio/backend/core/inference/video_vae_untiled.py b/studio/backend/core/inference/video_vae_untiled.py
index 852986fe9bd..a99dda5a5b3 100644
--- a/studio/backend/core/inference/video_vae_untiled.py
+++ b/studio/backend/core/inference/video_vae_untiled.py
@@ -61,6 +61,68 @@ def untiled_decode_bytes(
return int(coef * itemsize / 2 * batch * height * width + output)
+# When untiled does not fit, decode the fewest tiles that fit at the stock overlap (stock Wan: 28 tiles at 1280x704).
+WIDE_TILES_ENV = "UNSLOTH_VIDEO_VAE_WAN_WIDE_TILES"
+_STOCK_TILE = (256, 192) # diffusers AutoencoderKLWan tile_sample_min / tile_sample_stride
+
+
+def _wide_tiles_enabled() -> bool:
+ return os.environ.get(WIDE_TILES_ENV, "").strip().lower() not in ("0", "false", "no", "off")
+
+
+def wide_tile_plan(
+ family: str,
+ latent_shape: tuple,
+ ratio: int,
+ free: int,
+ itemsize: int = 2,
+ max_tiles: int = 16,
+) -> Optional[tuple[int, int, int, int]]:
+ """(min_h, stride_h, min_w, stride_w) sample px, or None. A single-tile axis gets stride >= size: no blend there."""
+ coef = _BYTES_PER_LATENT_PIXEL.get(family)
+ if coef is None or len(latent_shape) != 5 or ratio <= 0:
+ return None
+ batch, _, latent_frames, height, width = (int(x) for x in latent_shape)
+ spatial, temporal = _OUTPUT_SCALE[family]
+ overlap = max(1, (_STOCK_TILE[0] - _STOCK_TILE[1]) // ratio)
+ frames = (max(1, latent_frames) - 1) * temporal + 1
+ itemsize = max(2, itemsize)
+ out_bytes = 2 * max(1, batch) * 3 * frames * height * spatial * width * spatial * itemsize
+ best = None
+ for n_h in range(1, height + 1):
+ for n_w in range(1, width + 1):
+ if n_h * n_w > max_tiles or (n_h == 1 and n_w == 1):
+ continue
+ stride_h = -(-height // n_h)
+ stride_w = -(-width // n_w)
+ tile_h = height if n_h == 1 else min(height, stride_h + overlap)
+ tile_w = width if n_w == 1 else min(width, stride_w + overlap)
+ need = coef * itemsize / 2 * max(1, batch) * tile_h * tile_w + out_bytes
+ if need * _MARGIN + _MARGIN_BYTES > free:
+ continue
+ area = (n_h * tile_h) * (n_w * tile_w)
+ key = (n_h * n_w, area)
+ if best is None or key < best[0]:
+ best = (
+ key,
+ (
+ tile_h,
+ stride_h if n_h > 1 else height,
+ tile_w,
+ stride_w if n_w > 1 else width,
+ ),
+ )
+ if best is None:
+ return None
+ tile_h, stride_h, tile_w, stride_w = best[1]
+ stock_tiles = len(range(0, height, _STOCK_TILE[1] // ratio)) * len(
+ range(0, width, _STOCK_TILE[1] // ratio)
+ )
+ if best[0][0] >= stock_tiles:
+ return None
+ return tile_h * ratio, stride_h * ratio, tile_w * ratio, stride_w * ratio
+
+
def _decoder_itemsize(vae: Any) -> int:
"""Decoder weight element size; 4 if unreadable."""
try:
@@ -132,9 +194,10 @@ def install_untiled_decode(
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.
+ stats = {"untiled": 0, "tiled": 0, "wide": 0, "oom_fallback": 0}
+ # Smallest estimates that OOMed, never retried (untiled / wide).
oom_need: list = []
+ oom_wide: list = []
def gated(z: Any, *args: Any, **kwargs: Any) -> Any:
if not getattr(vae, "use_tiling", False):
@@ -158,6 +221,72 @@ def install_untiled_decode(
)
if not fits:
stats["tiled"] += 1
+ wide = None
+ ratio = int(getattr(vae, "spatial_compression_ratio", 0) or 0)
+ if (
+ _wide_tiles_enabled()
+ and free is not None
+ and hasattr(vae, "tile_sample_min_height")
+ ):
+ wide = wide_tile_plan(
+ family,
+ tuple(getattr(z, "shape", ())),
+ ratio,
+ free,
+ itemsize = _decoder_itemsize(vae),
+ )
+ if wide is None or (oom_wide and need is not None and need >= oom_wide[0]):
+ return decode(z, *args, **kwargs)
+ stock = (
+ vae.tile_sample_min_height,
+ vae.tile_sample_stride_height,
+ vae.tile_sample_min_width,
+ vae.tile_sample_stride_width,
+ )
+ (
+ vae.tile_sample_min_height,
+ vae.tile_sample_stride_height,
+ vae.tile_sample_min_width,
+ vae.tile_sample_stride_width,
+ ) = wide
+ if logger is not None:
+ logger.info(
+ "video.vae_untiled: wide tiles %dx%d (stride %dx%d) instead of %dx%d",
+ wide[0],
+ wide[2],
+ wide[1],
+ wide[3],
+ stock[0],
+ stock[2],
+ )
+ import torch
+
+ from .diffusion_batched import is_oom_error
+
+ try:
+ out = decode(z, *args, **kwargs)
+ stats["wide"] += 1
+ return out
+ except Exception as exc: # noqa: BLE001
+ if not is_oom_error(exc):
+ raise
+ finally:
+ (
+ vae.tile_sample_min_height,
+ vae.tile_sample_stride_height,
+ vae.tile_sample_min_width,
+ vae.tile_sample_stride_width,
+ ) = stock
+ stats["oom_fallback"] += 1
+ oom_wide[:] = [min([need, *oom_wide])] if need is not None else oom_wide
+ from .diffusion_vae_oom import clear_partial_decode # noqa: PLC0415
+
+ clear_partial_decode(vae, z)
+ torch.cuda.empty_cache()
+ if logger is not None:
+ logger.warning(
+ "video.vae_untiled: wide tiles ran out of memory; decoding at the stock tile size"
+ )
return decode(z, *args, **kwargs)
import torch
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index d5838f31e42..063b91aebba 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -13332,12 +13332,19 @@ def _cuda_wan_load(monkeypatch, *, policy, speed_mode):
@pytest.mark.parametrize(
"policy,speed_mode,installed",
- [("none", "default", True), ("model", "default", False), ("none", "off", False)],
+ [
+ ("none", "default", True),
+ ("model", "default", True),
+ ("group", "default", True),
+ ("streaming", "default", True),
+ ("sequential", "default", False),
+ ("none", "off", False),
+ ("group", "off", False),
+ ],
)
def test_resident_wan_load_decodes_untiled_when_it_fits(
fake_runtime, monkeypatch, policy, speed_mode, installed
):
- # Tiling is forced on; resident CUDA loads also get untiled-when-it-fits decode.
from core.inference import video_vae_untiled
calls = []
diff --git a/studio/backend/tests/test_video_vae_untiled.py b/studio/backend/tests/test_video_vae_untiled.py
index 48f963437aa..d709b46a0de 100644
--- a/studio/backend/tests/test_video_vae_untiled.py
+++ b/studio/backend/tests/test_video_vae_untiled.py
@@ -52,7 +52,12 @@ def test_untiled_when_it_fits(monkeypatch):
assert U.install_untiled_decode(_pipe(vae), WAN)
assert vae.decode(Z, return_dict = False) == ("untiled",)
assert vae.use_tiling is True
- assert vae.decode._unsloth_untiled_stats == {"untiled": 1, "tiled": 0, "oom_fallback": 0}
+ assert vae.decode._unsloth_untiled_stats == {
+ "untiled": 1,
+ "tiled": 0,
+ "wide": 0,
+ "oom_fallback": 0,
+ }
def test_tiled_when_it_does_not_fit(monkeypatch):
diff --git a/studio/backend/tests/test_video_vae_wide_tiles.py b/studio/backend/tests/test_video_vae_wide_tiles.py
new file mode 100644
index 00000000000..9828e714d34
--- /dev/null
+++ b/studio/backend/tests/test_video_vae_wide_tiles.py
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Wide Wan VAE tiles: the fewest tiles whose estimate fits free memory, used only when the untiled decode does not."""
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import video_vae_untiled as U # noqa: E402
+
+GiB = 2**30
+FIVE_B = "wan2.2-ti2v-5b"
+WAN21 = "wan2.1-t2v-1.3b"
+
+
+def _tiles(height, width, ratio, plan):
+ min_h, stride_h, min_w, stride_w = plan
+ return (
+ len(range(0, height, stride_h // ratio)),
+ len(range(0, width, stride_w // ratio)),
+ min_h // ratio,
+ min_w // ratio,
+ )
+
+
+def test_plan_covers_the_frame_with_fewer_tiles_than_stock():
+ plan = U.wide_tile_plan(FIVE_B, (1, 48, 11, 44, 80), 16, 10 * GiB)
+ assert plan is not None
+ rows, cols, tile_h, tile_w = _tiles(44, 80, 16, plan)
+ assert rows * cols < 4 * 7 # stock 256 / 192 px tiles at 1280x704
+ min_h, stride_h, min_w, stride_w = plan
+ assert (rows - 1) * stride_h + min_h >= 704 and (cols - 1) * stride_w + min_w >= 1280
+ if cols > 1:
+ assert min_w - stride_w == 64
+ if rows == 1:
+ assert stride_h >= 704
+
+
+def test_plan_shrinks_tiles_with_free_memory_and_gives_up_below_one_fit():
+ big = U.wide_tile_plan(FIVE_B, (1, 48, 11, 44, 80), 16, 10 * GiB)
+ small = U.wide_tile_plan(FIVE_B, (1, 48, 11, 44, 80), 16, 6 * GiB)
+ assert big is not None and small is not None
+ assert small[0] * small[2] < big[0] * big[2]
+ assert U.wide_tile_plan(FIVE_B, (1, 48, 11, 44, 80), 16, int(2.5 * GiB)) is None
+ assert U.wide_tile_plan("unknown-family", (1, 48, 11, 44, 80), 16, 10 * GiB) is None
+
+
+def test_plan_respects_the_wan21_ratio():
+ plan = U.wide_tile_plan(WAN21, (1, 16, 21, 60, 104), 8, 6 * GiB)
+ assert plan is not None
+ assert all(v % 8 == 0 for v in plan)
+
+
+class _FakeVae(torch.nn.Module):
+ def __init__(self, oom_wide = False):
+ super().__init__()
+ self.decoder = torch.nn.Linear(2, 2).half()
+ self.use_tiling = True
+ self.spatial_compression_ratio = 16
+ self.tile_sample_min_height = self.tile_sample_min_width = 256
+ self.tile_sample_stride_height = self.tile_sample_stride_width = 192
+ self.seen = []
+ self.oom_wide = oom_wide
+
+ def decode(self, z, *args, **kwargs):
+ sizes = (self.tile_sample_min_height, self.tile_sample_min_width, self.use_tiling)
+ self.seen.append(sizes)
+ if self.oom_wide and self.use_tiling and sizes[0] != 256:
+ raise torch.cuda.OutOfMemoryError("CUDA out of memory")
+ return z
+
+
[email protected]("oom", [False, True])
+def test_gate_decodes_wide_when_untiled_does_not_fit(monkeypatch, oom):
+ vae = _FakeVae(oom_wide = oom)
+ pipe = types.SimpleNamespace(vae = vae)
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 10 * GiB)
+ monkeypatch.setattr(
+ "core.inference.diffusion_vae_oom.clear_partial_decode", lambda vae, z: None
+ )
+ monkeypatch.setattr(torch.cuda, "empty_cache", lambda: None)
+ assert U.install_untiled_decode(pipe, FIVE_B)
+ z = torch.zeros(1, 48, 11, 44, 80)
+ vae.decode(z)
+ assert vae.seen[0][2] is True and vae.seen[0][0] == 704
+ if oom:
+ assert vae.seen[-1][:2] == (256, 256) # the retry runs at the stock size
+ assert (vae.tile_sample_min_height, vae.tile_sample_stride_height) == (
+ 256,
+ 192,
+ ) # restored either way
+
+
+def test_kill_switch_keeps_stock_tiles(monkeypatch):
+ monkeypatch.setenv(U.WIDE_TILES_ENV, "0")
+ vae = _FakeVae()
+ monkeypatch.setattr(U, "_free_bytes", lambda device: 10 * GiB)
+ assert U.install_untiled_decode(types.SimpleNamespace(vae = vae), FIVE_B)
+ vae.decode(torch.zeros(1, 48, 11, 44, 80))
+ assert vae.seen == [(256, 256, True)]