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: seam-free VAE tiles for Qwen-Image-2.1 on low-VRAM tiers (fixes thin horizontal / vertical lines) (#12696)

Daniel Han3161553fc033
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 6a25c0140af..d7555c68f8e 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -188,6 +188,7 @@ from .diffusion_speed import (
vae_decode_compile_allowed,
)
from .diffusion_vae_fp16 import enable_fp16_vae_decode
+from .diffusion_vae_tiling import install as install_wide_vae_tiles
from .diffusion_attention import (
apply_attention_backend,
normalize_attention_backend,
@@ -7088,6 +7089,11 @@ class DiffusionBackend:
apply_comfy_flow_shift(
pipe, comfy_flow_shift_for(fam, gguf_filename, repo_id, base), logger
)
+ # Before the speed optims, so the fused batched tile decode does not replace it.
+ try:
+ install_wide_vae_tiles(getattr(pipe, "vae", None), logger)
+ except Exception as exc: # noqa: BLE001 - keep the stock tiled decode
+ logger.warning("diffusion.vae_tiling: not installed: %s", exc)
# Before the speed optims so their decode compile lands inside the non-finite check; `off` keeps fp32.
vae_fp16 = str(
speed_mode or ""
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index c95dc49c421..a387fb68ab7 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -1046,7 +1046,8 @@ _MEASURED_IMAGE_ACTIVATION_MIB: dict[
str, tuple[tuple[int, int, int, int, int], tuple[int, int, int, int, int]]
] = {
# text encoder, denoise, untiled decode, tiled decode (all at 1024x1024), max(denoise, tiled decode) at 2048x2048
- "qwen-image-2.1": ((1_849, 666, 7_648, 449, 2_479), (1_849, 2_489, 7_648, 449, 9_602)),
+ # Qwen-Image-2.1 tiled decode: one 512 px tile (diffusion_vae_tiling), unfused bf16, the worst case.
+ "qwen-image-2.1": ((1_849, 666, 7_648, 1_697, 2_479), (1_849, 2_489, 7_648, 1_697, 9_602)),
"flux.1": ((288, 892, 2_666, 2_456, 2_674), (288, 892, 2_666, 2_456, 2_674)),
"flux.2-klein": ((1_516, 1_160, 2_645, 2_456, 3_876), (1_516, 1_205, 2_677, 2_456, 3_924)),
"z-image": ((744, 1_199, 2_666, 2_456, 4_327), (744, 1_271, 2_669, 2_456, 4_327)),
@@ -4099,6 +4100,10 @@ def vae_tile_side(vae: Any) -> Optional[int]:
"""The pixel side a VAE tiles at, or None when it cannot tile at all."""
if vae is None or not callable(getattr(vae, "enable_tiling", None)):
return None
+ decode_side = getattr(vae, "_unsloth_decode_tile_side", None)
+ if isinstance(decode_side, int) and not isinstance(decode_side, bool) and decode_side > 0:
+ # diffusion_vae_tiling decodes in wider tiles than the attributes
+ return max(64, min(4096, decode_side))
sides: list[int] = []
for attr in ("tile_sample_min_size", "tile_sample_min_height", "tile_sample_min_width"):
value = getattr(vae, attr, None)
diff --git a/studio/backend/core/inference/diffusion_vae_tiling.py b/studio/backend/core/inference/diffusion_vae_tiling.py
new file mode 100644
index 00000000000..7da4c0c47dd
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_vae_tiling.py
@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Seam-free tiled decode / encode for the Qwen-Image-2.1 VAE.
+
+diffusers gives AutoencoderKLQwenImage21 the Wan VAE's pixel tile geometry, but this VAE compresses 16x: tiles are 16
+latents with 4-latent blends and a sliver last tile, too little context, so tiled tiers draw thin seam lines. Here
+tiles are >= 32 latents (larger when free VRAM allows), overlap >= 16, edge-aligned, with a normalised blend that
+gives no weight near shared edges. Encode tiles are 64 latents: the encoder attends over the whole tile, so small
+tiles shift the condition latent everywhere. Kill switch ``UNSLOTH_DIFFUSION_VAE_WIDE_TILES=0``.
+"""
+
+from __future__ import annotations
+
+import os
+import types
+from typing import Any, Optional
+
+WIDE_TILES_ENV = "UNSLOTH_DIFFUSION_VAE_WIDE_TILES"
+
+TILE_LATENTS = 32
+OVERLAP_LATENTS = 16
+# Blend: a tile gets no weight within MARGIN latents of an edge it shares, then ramps to full over RAMP latents.
+MARGIN_LATENTS = 4
+RAMP_LATENTS = 8
+# Encode: a 1024 px reference image (Studio's default) is one tile, bit-identical to the untiled encode.
+ENCODE_TILE_LATENTS = 64
+ENCODE_OVERLAP_LATENTS = 32
+ENCODE_MARGIN_LATENTS = 8
+ENCODE_RAMP_LATENTS = 16
+
+_VAE_CLASSES = frozenset({"AutoencoderKLQwenImage21"})
+
+
+def wide_tiles_disabled() -> bool:
+ return (os.environ.get(WIDE_TILES_ENV) or "").strip().lower() in ("0", "off", "false", "no")
+
+
+def tile_starts(
+ length: int,
+ tile: int = TILE_LATENTS,
+ overlap: int = OVERLAP_LATENTS,
+) -> list[int]:
+ """Starts of the fewest full-size tiles covering ``length`` with overlaps >= ``overlap``, first at 0, last at the end."""
+ length, tile, overlap = int(length), int(tile), int(overlap)
+ if length <= tile:
+ return [0]
+ if tile <= overlap or overlap < 0:
+ raise ValueError(f"tile {tile} must exceed overlap {overlap}")
+ step = tile - overlap
+ count = -(-(length - overlap) // step)
+ span = length - tile
+ return [(i * span) // (count - 1) for i in range(count)]
+
+
+def axis_weights(
+ starts: list[int],
+ tile: int,
+ length: int,
+ scale: int,
+ torch: Any,
+ device: Any,
+ margin: int = MARGIN_LATENTS,
+ ramp: int = RAMP_LATENTS,
+) -> list:
+ """Per-tile fp32 blend weights along one axis, summing to 1 at every pixel: 0 within ``margin`` latents of a
+ shared edge, linear over the next ``ramp``. Overlaps >= 16 put every pixel >= 8 latents inside some tile, so a
+ margin under 8 keeps the sum positive."""
+ size = min(tile, length) * scale
+ pos = (torch.arange(size, dtype = torch.float64, device = device) + 0.5) / scale
+ total = torch.zeros(length * scale, dtype = torch.float64, device = device)
+ weights = []
+ for s in starts:
+ w = torch.ones(size, dtype = torch.float64, device = device)
+ if s > 0:
+ w = torch.minimum(w, ((pos - margin) / ramp).clamp(0, 1))
+ if s + tile < length:
+ w = torch.minimum(w, ((min(tile, length) - pos - margin) / ramp).clamp(0, 1))
+ total[s * scale : s * scale + size] += w
+ weights.append(w)
+ if float(total.min()) <= 0.0:
+ raise ValueError(f"tiles {starts} leave pixels without weight on a {length}-latent axis")
+ return [(w / total[s * scale : s * scale + size]).float() for w, s in zip(weights, starts)]
+
+
+def _decode_tile(vae: Any, z: Any) -> Any:
+ """The VAE's own untiled decode of one tile (fused / compiled forwards still apply)."""
+ prev = vae.use_tiling
+ vae.use_tiling = False
+ try:
+ return vae._decode(z, return_dict = False)[0]
+ finally:
+ vae.use_tiling = prev
+
+
+# Unfused bf16 decode peak per latent of tile area (measured 1,697 MiB at 32x32, 6,717 MiB at 64x64).
+DECODE_MIB_PER_LATENT = 1.7
+FREE_FRACTION = 0.75
+MAX_TILE_ENV = "UNSLOTH_DIFFUSION_VAE_MAX_TILE"
+
+
+def _axis_tiles(length: int, count: int) -> Optional[int]:
+ """Smallest tile side (>= 32 latents) that covers ``length`` in ``count`` tiles with 16-latent overlaps."""
+ if count == 1:
+ return length
+ side = max(TILE_LATENTS, -(-(length + (count - 1) * OVERLAP_LATENTS) // count))
+ return side if side < length else None
+
+
+def choose_tiles(height: int, width: int, max_area: Optional[int]) -> tuple[int, int]:
+ """Tile (height, width) in latents decoding the fewest latents (overlaps counted) within ``max_area``; 32x32 floor."""
+ floor = (min(TILE_LATENTS, height), min(TILE_LATENTS, width))
+ if max_area is None or max_area <= floor[0] * floor[1]:
+ return floor
+ best, best_cost = floor, None
+ sides_h = [(n, _axis_tiles(height, n)) for n in range(1, len(tile_starts(height)) + 1)]
+ sides_w = [(n, _axis_tiles(width, n)) for n in range(1, len(tile_starts(width)) + 1)]
+ for _, th in sides_h:
+ for _, tw in sides_w:
+ if th is None or tw is None or th * tw > max_area:
+ continue
+ cost = (len(tile_starts(height, th)) * th * len(tile_starts(width, tw)) * tw, th * tw)
+ if best_cost is None or cost < best_cost:
+ best, best_cost = (th, tw), cost
+ return best
+
+
+def decode_tile_budget(vae: Any, z: Any) -> Optional[int]:
+ """Largest decode tile area (latents) that fits ``FREE_FRACTION`` of the free VRAM now; None off CUDA."""
+ raw = (os.environ.get(MAX_TILE_ENV) or "").strip()
+ if raw.isdigit() and int(raw) > 0:
+ return int(raw) ** 2
+ try:
+ import torch
+
+ if getattr(z, "device", None) is None or z.device.type != "cuda":
+ return None
+ free, _ = torch.cuda.mem_get_info(z.device)
+ free += torch.cuda.memory_reserved(z.device) - torch.cuda.memory_allocated(z.device)
+ ratio = int(vae.spatial_compression_ratio)
+ out_bytes = 4 * 4 * z.shape[0] * z.shape[2] * z.shape[-2] * z.shape[-1] * ratio * ratio
+ elem = next(vae.decoder.parameters()).element_size()
+ mib = FREE_FRACTION * (free - out_bytes) / 2**20
+ return max(0, int(mib / (DECODE_MIB_PER_LATENT * elem / 2)))
+ except Exception: # noqa: BLE001 - unknown budget: the 32-latent tiles the planner budgeted
+ return None
+
+
+def tiled_decode(
+ vae: Any,
+ z: Any,
+ return_dict: bool = True,
+ max_area: Any = "auto",
+) -> Any:
+ """Decode ``z`` (B, C, T, H, W) in evenly spread tiles, 32x32 latents or larger when free VRAM allows."""
+ import torch
+ from diffusers.models.autoencoders.vae import DecoderOutput
+
+ _, _, _, height, width = z.shape
+ ratio = int(vae.spatial_compression_ratio)
+ if max_area == "auto":
+ max_area = decode_tile_budget(vae, z)
+ th, tw = choose_tiles(height, width, max_area)
+ vae._unsloth_last_decode_tile = (th, tw, max_area)
+ hs = tile_starts(height, th)
+ ws = tile_starts(width, tw)
+ if len(hs) == 1 and len(ws) == 1:
+ dec = _decode_tile(vae, z)
+ else:
+ wy = axis_weights(hs, th, height, ratio, torch, z.device)
+ wx = axis_weights(ws, tw, width, ratio, torch, z.device)
+ out, dtype = None, None
+ for i, y in enumerate(hs):
+ for j, x in enumerate(ws):
+ tile = _decode_tile(vae, z[:, :, :, y : y + th, x : x + tw])
+ if out is None:
+ dtype = tile.dtype
+ out = torch.zeros(
+ (*tile.shape[:3], height * ratio, width * ratio),
+ dtype = torch.float32,
+ device = tile.device,
+ )
+ w = wy[i].view(-1, 1) * wx[j].view(1, -1)
+ out[..., y * ratio : (y + th) * ratio, x * ratio : (x + tw) * ratio].add_(
+ tile.float() * w
+ )
+ del tile
+ dec = out.to(dtype)
+ del out
+ if not return_dict:
+ return (dec,)
+ return DecoderOutput(sample = dec)
+
+
+def _encode_tile(vae: Any, x: Any) -> Any:
+ """The VAE's own untiled ``_encode`` of one pixel tile: the (mean, logvar) moments, not a sample."""
+ prev = vae.use_tiling
+ vae.use_tiling = False
+ try:
+ return vae._encode(x)
+ finally:
+ vae.use_tiling = prev
+
+
+def tiled_encode(vae: Any, x: Any) -> Any:
+ """Encode ``x`` (B, C, T, H, W pixels) to moments in 64-latent tiles, blended in latent space."""
+ import torch
+
+ _, _, _, height_px, width_px = x.shape
+ ratio = int(vae.spatial_compression_ratio)
+ height, width = height_px // ratio, width_px // ratio
+ tile, overlap = ENCODE_TILE_LATENTS, ENCODE_OVERLAP_LATENTS
+ hs = tile_starts(height, tile, overlap)
+ ws = tile_starts(width, tile, overlap)
+ th, tw = min(tile, height), min(tile, width)
+ if len(hs) == 1 and len(ws) == 1:
+ return _encode_tile(vae, x)
+ margin, ramp = ENCODE_MARGIN_LATENTS, ENCODE_RAMP_LATENTS
+ wy = axis_weights(hs, tile, height, 1, torch, x.device, margin, ramp)
+ wx = axis_weights(ws, tile, width, 1, torch, x.device, margin, ramp)
+ out, dtype = None, None
+ for i, y in enumerate(hs):
+ for j, xs in enumerate(ws):
+ tile_out = _encode_tile(
+ vae, x[:, :, :, y * ratio : (y + th) * ratio, xs * ratio : (xs + tw) * ratio]
+ )
+ if out is None:
+ dtype = tile_out.dtype
+ out = torch.zeros(
+ (*tile_out.shape[:3], height, width),
+ dtype = torch.float32,
+ device = tile_out.device,
+ )
+ out[..., y : y + th, xs : xs + tw].add_(
+ tile_out.float() * (wy[i].view(-1, 1) * wx[j].view(1, -1))
+ )
+ del tile_out
+ return out.to(dtype)
+
+
+def _wants_wide_tiles(vae: Any) -> bool:
+ if vae is None or type(vae).__name__ not in _VAE_CLASSES:
+ return False
+ config = getattr(vae, "config", None)
+ if getattr(config, "patch_size", None) is not None:
+ return False
+ try:
+ ratio = int(vae.spatial_compression_ratio)
+ except (AttributeError, TypeError, ValueError):
+ return False
+ return ratio >= 16 and callable(getattr(vae, "_decode", None)) and hasattr(vae, "use_tiling")
+
+
+def install(vae: Any, logger: Any = None) -> bool:
+ """Route ``vae``'s tiled decode / encode through the wide tiles. Idempotent; False when not covered.
+ ``_unsloth_decode_tile_side`` carries the real decode tile side for the memory estimates."""
+ if not _wants_wide_tiles(vae) or wide_tiles_disabled():
+ return False
+ if getattr(vae, "_unsloth_wide_tiles", False):
+ return True
+ own = vae.__dict__.get("tiled_decode")
+ own_encode = vae.__dict__.get("tiled_encode")
+ stock = vae.tiled_decode
+ stock_encode = getattr(vae, "tiled_encode", None)
+
+ def _tiled_decode(
+ self: Any,
+ z: Any,
+ return_dict: bool = True,
+ ) -> Any:
+ if wide_tiles_disabled():
+ return stock(z, return_dict = return_dict)
+ return tiled_decode(self, z, return_dict = return_dict)
+
+ def _tiled_encode(self: Any, x: Any) -> Any:
+ if wide_tiles_disabled():
+ return stock_encode(x)
+ return tiled_encode(self, x)
+
+ vae._unsloth_wide_tiles_own = own
+ vae.tiled_decode = types.MethodType(_tiled_decode, vae)
+ if callable(stock_encode) and callable(getattr(vae, "_encode", None)):
+ vae._unsloth_wide_tiles_own_encode = own_encode
+ vae.tiled_encode = types.MethodType(_tiled_encode, vae)
+ vae._unsloth_decode_tile_side = TILE_LATENTS * int(vae.spatial_compression_ratio)
+ vae._unsloth_wide_tiles = True
+ if logger is not None:
+ logger.info(
+ "diffusion.vae_tiling: %s decodes in %d-latent tiles with %d-latent overlaps and encodes in %d-latent "
+ "tiles with %d-latent overlaps, the last tile edge-aligned",
+ type(vae).__name__,
+ TILE_LATENTS,
+ OVERLAP_LATENTS,
+ ENCODE_TILE_LATENTS,
+ ENCODE_OVERLAP_LATENTS,
+ )
+ return True
+
+
+def uninstall(vae: Any) -> None:
+ if not getattr(vae, "_unsloth_wide_tiles", False):
+ return
+ for attr, saved in (
+ ("tiled_decode", "_unsloth_wide_tiles_own"),
+ ("tiled_encode", "_unsloth_wide_tiles_own_encode"),
+ ):
+ if saved not in vae.__dict__ and attr == "tiled_encode":
+ continue
+ own: Optional[Any] = vae.__dict__.get(saved)
+ if own is None:
+ vae.__dict__.pop(attr, None)
+ else:
+ setattr(vae, attr, own)
+ for name in (
+ "_unsloth_wide_tiles_own",
+ "_unsloth_wide_tiles_own_encode",
+ "_unsloth_decode_tile_side",
+ ):
+ vae.__dict__.pop(name, None)
+ vae._unsloth_wide_tiles = False
diff --git a/studio/backend/tests/test_diffusion_vae_tiling.py b/studio/backend/tests/test_diffusion_vae_tiling.py
new file mode 100644
index 00000000000..6df653de432
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_vae_tiling.py
@@ -0,0 +1,414 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Qwen-Image-2.1 tiled VAE decode without seam lines (diffusion_vae_tiling).
+
+The stock geometry tiles this 16x VAE in 16-latent tiles with 4-latent blends and a 4-latent sliver at the right /
+bottom edge, which draws thin vertical / horizontal lines on every tiled (low-VRAM) decode."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import math
+import textwrap
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import diffusion_memory as dm # noqa: E402
+from core.inference import diffusion_vae_tiling as vt # noqa: E402
+
+
[email protected]("length", list(range(1, 200)) + [256, 257, 333])
+def test_tile_starts_are_full_edge_aligned_tiles_with_wide_overlaps(length):
+ starts = vt.tile_starts(length)
+ tile, overlap = vt.TILE_LATENTS, vt.OVERLAP_LATENTS
+ assert starts[0] == 0
+ assert starts == sorted(set(starts))
+ if length <= tile:
+ assert starts == [0]
+ return
+ assert starts[-1] + tile == length # the last tile ends at the edge at full size: no sliver
+ assert all(b - a <= tile - overlap for a, b in zip(starts, starts[1:]))
+ assert len(starts) == math.ceil((length - overlap) / (tile - overlap))
+
+
+# Every size the Images page offers for Qwen-Image-2.1, plus custom off-preset sizes.
+UI_SIZES = [
+ (1024, 1024),
+ (1024, 672),
+ (672, 1024),
+ (1024, 768),
+ (768, 1024),
+ (1024, 576),
+ (576, 1024),
+ (1024, 448),
+ (448, 1024),
+ (2048, 2048),
+ (2400, 1792),
+ (1792, 2400),
+ (2528, 1696),
+ (1696, 2528),
+ (2752, 1536),
+ (1536, 2752),
+ (1344, 1344),
+ (1312, 1312),
+ (1184, 864),
+ (512, 1536),
+ (256, 256),
+ (256, 2752),
+ (2752, 2752),
+]
+UI_LENGTHS = sorted({side // 16 for size in UI_SIZES for side in size} | set(range(16, 173, 2)))
+
+
[email protected]("length", UI_LENGTHS + [33, 47, 65, 83])
+def test_axis_weights_partition_unity_and_skip_shared_edges(length):
+ starts = vt.tile_starts(length)
+ tile, scale = vt.TILE_LATENTS, 16
+ size = min(tile, length)
+ weights = vt.axis_weights(starts, tile, length, scale, torch, "cpu")
+ total = torch.zeros(length * scale)
+ covered = torch.zeros(length * scale, dtype = torch.bool)
+ for s, w in zip(starts, weights):
+ assert w.shape == (size * scale,)
+ assert float(w.min()) >= 0.0 and float(w.max()) <= 1.0 + 1e-6
+ total[s * scale : s * scale + w.numel()] += w
+ covered[s * scale : s * scale + w.numel()] = True
+ edge = vt.MARGIN_LATENTS * scale
+ if s > 0:
+ assert float(w[:edge].abs().max()) == 0.0
+ if s + tile < length:
+ assert float(w[-edge:].abs().max()) == 0.0
+ assert bool(covered.all())
+ torch.testing.assert_close(total, torch.ones_like(total))
+
+
[email protected]("width, height", UI_SIZES)
+def test_every_ui_size_tiles_without_slivers(width, height):
+ for side in (width, height):
+ length = side // 16
+ starts = vt.tile_starts(length)
+ if length <= vt.TILE_LATENTS:
+ assert starts == [0]
+ continue
+ assert starts[0] == 0 and starts[-1] + vt.TILE_LATENTS == length
+ assert all(
+ b + vt.OVERLAP_LATENTS <= a + vt.TILE_LATENTS for a, b in zip(starts, starts[1:])
+ )
+
+
[email protected](autouse = True)
+def _fixed_decode_tiles(monkeypatch):
+ """CPU decodes use 32x32 tiles anyway; pin it so a CUDA box runs the same geometry."""
+ monkeypatch.setenv(vt.MAX_TILE_ENV, str(vt.TILE_LATENTS))
+
+
+def _diffusers_vae():
+ diffusers = pytest.importorskip("diffusers")
+ cls = getattr(diffusers, "AutoencoderKLQwenImage21", None)
+ if cls is None:
+ pytest.skip(
+ reason = "needs diffusers >= 0.41 (AutoencoderKLQwenImage21); the 0.40.0 pin predates it"
+ )
+ torch.manual_seed(0)
+ return cls(
+ base_dim = 8,
+ decoder_base_dim = 8,
+ z_dim = 4,
+ dim_mult = [1, 2, 4, 4, 4],
+ num_res_blocks = 1,
+ attn_scales = [],
+ temperal_downsample = [False, True, True, True],
+ in_channels = 3,
+ out_channels = 3,
+ latents_mean = [0.0] * 4,
+ latents_std = [1.0] * 4,
+ ).eval()
+
+
+def _line_error(x, ref):
+ """Worst full-height column / full-width row mean |x - ref|: what a seam line looks like."""
+ d = (x - ref).abs().mean(1)[0, 0]
+ return max(float(d.mean(0).max()), float(d.mean(1).max()))
+
+
[email protected]("latents", [40, 64])
+def test_tiled_decode_has_no_seam_lines(latents):
+ vae = _diffusers_vae()
+ assert vae.spatial_compression_ratio == 16
+ z = torch.randn(1, 4, 1, latents, latents, generator = torch.Generator().manual_seed(1))
+ with torch.no_grad():
+ vae.use_tiling = False
+ untiled = vae.decode(z).sample
+ vae.enable_tiling()
+ stock = vae.decode(z).sample
+ assert vt.install(vae)
+ wide = vae.decode(z).sample
+ stock_err, wide_err = _line_error(stock, untiled), _line_error(wide, untiled)
+ assert stock_err > 0.05 # the stock geometry's seams, so this test can see the defect
+ assert wide_err < stock_err / 4, (stock_err, wide_err)
+
+
+def test_canvas_within_one_tile_decodes_untiled_bit_identical():
+ vae = _diffusers_vae()
+ z = torch.randn(1, 4, 1, 32, 24, generator = torch.Generator().manual_seed(2))
+ with torch.no_grad():
+ vae.use_tiling = False
+ untiled = vae.decode(z).sample
+ vae.enable_tiling()
+ assert vt.install(vae)
+ tiled = vae.decode(z).sample
+ assert torch.equal(tiled, untiled)
+ assert vae.use_tiling is True
+
+
+def test_kill_switch_keeps_the_stock_tiled_decode(monkeypatch):
+ vae = _diffusers_vae()
+ z = torch.randn(1, 4, 1, 40, 40, generator = torch.Generator().manual_seed(3))
+ with torch.no_grad():
+ vae.enable_tiling()
+ stock = vae.decode(z).sample
+ assert vt.install(vae)
+ monkeypatch.setenv(vt.WIDE_TILES_ENV, "0")
+ killed = vae.decode(z).sample
+ assert torch.equal(killed, stock)
+
+
+def test_install_is_idempotent_and_uninstall_restores():
+ vae = _diffusers_vae()
+ before = (vae.tile_sample_min_height, vae.tile_sample_stride_height, dm.vae_tile_side(vae))
+ assert vt.install(vae) and vt.install(vae)
+ assert "tiled_decode" in vae.__dict__ and "tiled_encode" in vae.__dict__
+ assert (vae.tile_sample_min_height, vae.tile_sample_stride_height) == before[:2]
+ assert dm.vae_tile_side(vae) == vt.TILE_LATENTS * 16
+ vt.uninstall(vae)
+ assert "tiled_decode" not in vae.__dict__ and "tiled_encode" not in vae.__dict__
+ assert dm.vae_tile_side(vae) == before[2]
+
+
[email protected]("name", ["AutoencoderKLWan", "AutoencoderKLQwenImage", "AutoencoderKL"])
+def test_other_vaes_keep_the_stock_tiles(name):
+ vae = type(
+ name,
+ (),
+ {"spatial_compression_ratio": 16, "use_tiling": False, "_decode": lambda self: None},
+ )()
+ vae.config = types.SimpleNamespace(patch_size = None)
+ assert vt.install(vae) is False
+ assert "tiled_decode" not in vae.__dict__
+
+
+def test_patchified_variant_keeps_the_stock_tiles():
+ cls = type("AutoencoderKLQwenImage21", (), {"_decode": lambda self: None})
+ vae = cls()
+ vae.spatial_compression_ratio, vae.use_tiling = 16, False
+ vae.config = types.SimpleNamespace(patch_size = 2)
+ assert vt.install(vae) is False
+
+
+def test_load_installs_the_wide_tiles_before_the_speed_optims():
+ """The fused batched tile decode only installs on a VAE without its own tiled_decode, so order matters."""
+ from core.inference import diffusion
+
+ src = inspect.getsource(inspect.unwrap(diffusion.DiffusionBackend.load_pipeline))
+ tree = ast.parse(textwrap.dedent(src))
+ calls = [
+ (node.lineno, node.func.id)
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id in ("install_wide_vae_tiles", "apply_speed_optims")
+ ]
+ install = [ln for ln, name in calls if name == "install_wide_vae_tiles"]
+ speed = [ln for ln, name in calls if name == "apply_speed_optims"]
+ assert install and speed and min(install) < min(speed)
+
+
+def test_fused_batched_tile_decode_does_not_replace_the_wide_tiles():
+ from core.inference import diffusion_vae_fused
+
+ vae = _diffusers_vae()
+ assert vt.install(vae)
+ ours = vae.__dict__["tiled_decode"]
+ assert diffusion_vae_fused.install_wan_tile_batch(vae) is False
+ assert vae.__dict__["tiled_decode"] is ours
+
+
+def test_kill_switch_at_load_skips_the_install(monkeypatch):
+ monkeypatch.setenv(vt.WIDE_TILES_ENV, "0")
+ vae = _diffusers_vae()
+ assert vt.install(vae) is False
+ assert "tiled_decode" not in vae.__dict__
+
+
[email protected]("width, height", UI_SIZES)
+def test_per_call_guard_budgets_one_wide_tile_at_every_ui_size(width, height):
+ """The tiled-decode estimate charges one 512 px tile whatever the canvas, and that covers the measured
+ worst case of one wide tile (1,697 MiB unfused bf16 on top of the weights)."""
+ vae = _diffusers_vae()
+ assert vt.install(vae)
+ side = dm.vae_tile_side(vae)
+ assert side == vt.TILE_LATENTS * 16
+ tiled = dm.estimate_tiled_image_runtime_mib(
+ width = width, height = height, family = "qwen-image-2.1", tile_side = side, vae_sliced = True
+ )
+ one_tile = dm.estimate_image_runtime_mib(width = side, height = side, family = "qwen-image-2.1")
+ assert one_tile >= 1_697
+ assert tiled >= one_tile
+ act = dm.calibrated_image_activation("qwen-image-2.1")
+ assert act.tiled_decode_mib >= 1_697
+
+
+# Extra peak of one encode tile over the weights, unfused bf16 diffusers VAE on a B200: a 512 px input is one
+# 32-latent tile, 1024 px and up encode in 64-latent tiles (one tile at 1024, 2,322 MiB worst at 2048 / 2752).
+_MEASURED_ENCODE_TILE_MIB = {512: 590, 1024: 2_322, 2048: 2_322}
+
+
[email protected]("width, height", UI_SIZES)
+def test_per_call_guard_covers_the_encode_tile_at_every_reference_size(width, height):
+ """Qwen-Image-2.1 only encodes edit inputs, at the reference resolution, and the guard charges those as weighted
+ condition pixels. The tiled estimate must still cover one 64-latent encode tile at every output size."""
+ from core.inference.diffusion_families import detect_family
+
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ assert (
+ fam.img2img_pipeline_class is None
+ ) # no plain img2img: every encode is a conditioned edit
+ for ref in fam.reference_resolutions:
+ cond = int(ref * ref * getattr(fam, "condition_pixel_weight", 1.0))
+ tiled = dm.estimate_tiled_image_runtime_mib(
+ width = width,
+ height = height,
+ family = fam.name,
+ condition_pixels = cond,
+ tile_side = vt.TILE_LATENTS * 16,
+ vae_sliced = True,
+ )
+ assert tiled >= _MEASURED_ENCODE_TILE_MIB[ref], (ref, tiled)
+ assert vt.ENCODE_TILE_LATENTS * 16 == 1024
+
+
+def _line_error_latent(x, ref):
+ d = (x - ref).abs().mean(1)[0, 0]
+ return max(float(d.mean(0).max()), float(d.mean(1).max()))
+
+
[email protected]("height, width", [(640, 640), (256, 1088), (1088, 256)])
+def test_tiled_encode_has_no_seam_lines(height, width):
+ vae = _diffusers_vae()
+ g = torch.Generator().manual_seed(4)
+ x = torch.nn.functional.interpolate(
+ torch.rand(1, 3, 8, 8, generator = g) * 2 - 1, size = (height, width), mode = "bicubic"
+ )
+ x = x.clamp(-1, 1)[:, :, None]
+ with torch.no_grad():
+ vae.use_tiling = False
+ untiled = vae._encode(x)
+ vae.enable_tiling()
+ stock = vae._encode(x)
+ assert vt.install(vae)
+ wide = vae._encode(x)
+ assert wide.shape == untiled.shape == stock.shape
+ stock_err, wide_err = _line_error_latent(stock, untiled), _line_error_latent(wide, untiled)
+ assert stock_err > 0
+ if max(height, width) <= vt.ENCODE_TILE_LATENTS * 16:
+ # up to 1024 px a side (Studio's default reference resolution): one tile, the untiled encode exactly
+ assert torch.equal(wide, untiled)
+ else:
+ assert stock_err > 2 * wide_err, (stock_err, wide_err)
+
+
+def test_encode_tiles_are_wider_than_decode_tiles():
+ assert vt.ENCODE_TILE_LATENTS == 2 * vt.TILE_LATENTS
+ assert vt.ENCODE_OVERLAP_LATENTS >= vt.ENCODE_TILE_LATENTS // 2
+ for length in range(1, 200):
+ starts = vt.tile_starts(length, vt.ENCODE_TILE_LATENTS, vt.ENCODE_OVERLAP_LATENTS)
+ w = vt.axis_weights(
+ starts,
+ vt.ENCODE_TILE_LATENTS,
+ length,
+ 1,
+ torch,
+ "cpu",
+ vt.ENCODE_MARGIN_LATENTS,
+ vt.ENCODE_RAMP_LATENTS,
+ )
+ total = torch.zeros(length)
+ for s, wi in zip(starts, w):
+ total[s : s + wi.numel()] += wi
+ assert torch.allclose(total, torch.ones(length), atol = 1e-6)
+
+
+def test_encode_within_one_tile_is_untiled_and_kill_switch_keeps_stock(monkeypatch):
+ vae = _diffusers_vae()
+ x = torch.rand(1, 3, 1, 512, 384, generator = torch.Generator().manual_seed(5)) * 2 - 1
+ big = torch.rand(1, 3, 1, 640, 640, generator = torch.Generator().manual_seed(6)) * 2 - 1
+ with torch.no_grad():
+ vae.use_tiling = False
+ untiled = vae._encode(x)
+ vae.enable_tiling()
+ stock_big = vae._encode(big)
+ assert vt.install(vae)
+ assert torch.equal(vae._encode(x), untiled)
+ monkeypatch.setenv(vt.WIDE_TILES_ENV, "0")
+ assert torch.equal(vae._encode(big), stock_big)
+ vt.uninstall(vae)
+ assert "tiled_encode" not in vae.__dict__
+
+
+def _decoded_latents(height, width, th, tw):
+ return len(vt.tile_starts(height, th)) * th * len(vt.tile_starts(width, tw)) * tw
+
+
[email protected]("width, height", UI_SIZES)
[email protected]("max_area", [None, 0, 1023, 1024, 1300, 1700, 2600, 5000, 10**6])
+def test_budget_sized_tiles_keep_the_invariants_and_never_decode_more(width, height, max_area):
+ h, w = height // 16, width // 16
+ th, tw = vt.choose_tiles(h, w, max_area)
+ floor = (min(vt.TILE_LATENTS, h), min(vt.TILE_LATENTS, w))
+ if max_area is None or max_area <= floor[0] * floor[1]:
+ assert (th, tw) == floor # no room: the 32x32 tiles the planner budgets
+ else:
+ assert th * tw <= max_area
+ assert _decoded_latents(h, w, th, tw) <= _decoded_latents(h, w, *floor)
+ if max_area is not None and max_area >= h * w:
+ assert (th, tw) == (h, w) # the whole canvas fits: untiled
+ for length, side in ((h, th), (w, tw)):
+ assert side >= min(vt.TILE_LATENTS, length) and side <= length
+ starts = vt.tile_starts(length, side)
+ assert starts[0] == 0 and starts[-1] + side == length or starts == [0]
+ assert all(b + vt.OVERLAP_LATENTS <= a + side for a, b in zip(starts, starts[1:]))
+ weights = vt.axis_weights(starts, side, length, 2, torch, "cpu")
+ total = torch.zeros(length * 2)
+ for s, wgt in zip(starts, weights):
+ total[s * 2 : s * 2 + wgt.numel()] += wgt
+ torch.testing.assert_close(total, torch.ones_like(total))
+
+
+def test_budget_comes_from_free_vram_and_the_env_caps_it(monkeypatch):
+ vae = _diffusers_vae()
+ z = torch.zeros(1, 4, 1, 64, 64)
+ assert vt.decode_tile_budget(vae, z) == vt.TILE_LATENTS**2
+ monkeypatch.delenv(vt.MAX_TILE_ENV)
+ assert vt.decode_tile_budget(vae, z) is None # CPU: no budget, 32x32 tiles
+ assert vt.choose_tiles(64, 64, None) == (32, 32)
+
+
+def test_larger_tiles_decode_like_untiled_when_the_budget_allows():
+ vae = _diffusers_vae()
+ z = torch.randn(1, 4, 1, 40, 64, generator = torch.Generator().manual_seed(7))
+ with torch.no_grad():
+ vae.use_tiling = False
+ untiled = vae.decode(z).sample
+ assert vt.install(vae)
+ whole = vt.tiled_decode(vae, z, return_dict = False, max_area = 40 * 64)[0]
+ two = vt.tiled_decode(vae, z, return_dict = False, max_area = 40 * 40)[0]
+ small = vt.tiled_decode(vae, z, return_dict = False, max_area = 32 * 32)[0]
+ assert torch.equal(whole, untiled)
+ assert vae._unsloth_last_decode_tile == (32, 32, 32 * 32)
+ assert _line_error(two, untiled) <= _line_error(small, untiled)