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 tiled decode for every image VAE whose stock tiles fall under the floor (HunyuanImage-2.1 grid, Qwen-Image, slivers) (#12736)

Daniel Han32ee4bf593d2
diff --git a/studio/backend/core/inference/diffusion_vae_tiling.py b/studio/backend/core/inference/diffusion_vae_tiling.py
index 7da4c0c47dd..a8241c5e296 100644
--- a/studio/backend/core/inference/diffusion_vae_tiling.py
+++ b/studio/backend/core/inference/diffusion_vae_tiling.py
@@ -1,13 +1,15 @@
# 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``.
+"""Seam-free tiled VAE decode / encode for every image VAE whose stock tiles fall under a floor.
+
+Low-VRAM tiers tile the VAE with diffusers' stock geometry, which draws seams where tiles are under 32 latents or
+blends under 16 (Qwen-Image-2.1 16x, HunyuanImage-2.1 32x, Qwen-Image 8x) or the last tile is a sliver (AutoencoderKL,
+FLUX.2 at e.g. 1600 px). The rule is read off the VAE (``stock_tiles``, ``compression_ratio``): stock tiles that meet
+the floor stay bit-identical to diffusers; otherwise tiles are >= 32 latents (larger when free VRAM allows), overlap
+>= 16, edge-aligned, with a normalised blend giving no weight near shared edges. Wan-family 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
@@ -29,8 +31,6 @@ 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")
@@ -93,33 +93,57 @@ def _decode_tile(vae: Any, z: Any) -> Any:
vae.use_tiling = prev
-# Unfused bf16 decode peak per latent of tile area (measured 1,697 MiB at 32x32, 6,717 MiB at 64x64).
+# Unfused bf16 decode peak per latent of tile area at 16x (1,697 MiB at 32x32); other ratios scale by tile pixels.
DECODE_MIB_PER_LATENT = 1.7
+DECODE_MIB_RATIO = 16
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."""
+def _axis_tiles(
+ length: int,
+ count: int,
+ tile: int = TILE_LATENTS,
+ overlap: int = OVERLAP_LATENTS,
+) -> Optional[int]:
+ """Smallest tile side (>= ``tile`` latents) that covers ``length`` in ``count`` tiles with ``overlap`` overlaps."""
if count == 1:
return length
- side = max(TILE_LATENTS, -(-(length + (count - 1) * OVERLAP_LATENTS) // count))
+ side = max(tile, -(-(length + (count - 1) * overlap) // 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))
+def choose_tiles(
+ height: int,
+ width: int,
+ max_area: Optional[int],
+ tile: int = TILE_LATENTS,
+ overlap: int = OVERLAP_LATENTS,
+) -> tuple[int, int]:
+ """Tile (height, width) in latents decoding the fewest latents (overlaps counted) within ``max_area``; ``tile`` floor."""
+ floor = (min(tile, height), min(tile, 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:
+ sides_h = [
+ _axis_tiles(height, n, tile, overlap)
+ for n in range(1, len(tile_starts(height, tile, overlap)) + 1)
+ ]
+ sides_w = [
+ _axis_tiles(width, n, tile, overlap)
+ for n in range(1, len(tile_starts(width, tile, overlap)) + 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)
+ cost = (
+ len(tile_starts(height, th, overlap))
+ * th
+ * len(tile_starts(width, tw, overlap))
+ * tw,
+ th * tw,
+ )
if best_cost is None or cost < best_cost:
best, best_cost = (th, tw), cost
return best
@@ -137,11 +161,14 @@ def decode_tile_budget(vae: Any, z: Any) -> Optional[int]:
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
+ ratio = compression_ratio(vae)
+ frames = z.shape[2] if z.dim() == 5 else 1
+ # fp32 accumulator
+ out_bytes = 4 * 4 * z.shape[0] * frames * 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)))
+ per_latent = DECODE_MIB_PER_LATENT * (ratio / DECODE_MIB_RATIO) ** 2
+ return max(0, int(mib / (per_latent * elem / 2)))
except Exception: # noqa: BLE001 - unknown budget: the 32-latent tiles the planner budgeted
return None
@@ -152,18 +179,19 @@ def tiled_decode(
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."""
+ """Decode ``z`` (5-D or 4-D) in evenly spread floor-sized tiles, 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)
+ height, width = z.shape[-2], z.shape[-1]
+ ratio = compression_ratio(vae)
+ tile, overlap = floor_tiles(vae)
if max_area == "auto":
max_area = decode_tile_budget(vae, z)
- th, tw = choose_tiles(height, width, max_area)
+ th, tw = choose_tiles(height, width, max_area, tile, overlap)
vae._unsloth_last_decode_tile = (th, tw, max_area)
- hs = tile_starts(height, th)
- ws = tile_starts(width, tw)
+ hs = tile_starts(height, th, overlap)
+ ws = tile_starts(width, tw, overlap)
if len(hs) == 1 and len(ws) == 1:
dec = _decode_tile(vae, z)
else:
@@ -172,11 +200,11 @@ def tiled_decode(
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])
+ 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),
+ (*tile.shape[:-2], height * ratio, width * ratio),
dtype = torch.float32,
device = tile.device,
)
@@ -206,8 +234,8 @@ 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_px, width_px = x.shape[-2], x.shape[-1]
+ ratio = compression_ratio(vae)
height, width = height_px // ratio, width_px // ratio
tile, overlap = ENCODE_TILE_LATENTS, ENCODE_OVERLAP_LATENTS
hs = tile_starts(height, tile, overlap)
@@ -238,22 +266,100 @@ def tiled_encode(vae: Any, x: Any) -> Any:
return out.to(dtype)
+def compression_ratio(vae: Any) -> int:
+ """Pixels per latent: ``spatial_compression_ratio`` (attribute or config), else pixel / latent tile sides."""
+ if "spatial_compression_ratio" in getattr(vae, "__dict__", {}) or hasattr(
+ type(vae), "spatial_compression_ratio"
+ ):
+ return int(vae.spatial_compression_ratio)
+ ratio = getattr(getattr(vae, "config", None), "spatial_compression_ratio", None)
+ if ratio is not None:
+ return int(ratio)
+ sample = getattr(vae, "tile_sample_min_size", None)
+ latent = getattr(vae, "tile_latent_min_size", None)
+ if isinstance(sample, int) and isinstance(latent, int) and latent > 0 and sample % latent == 0:
+ return sample // latent
+ raise ValueError(f"{type(vae).__name__} has no readable spatial compression ratio")
+
+
+def stock_tiles(vae: Any) -> Optional[tuple[int, int]]:
+ """diffusers' stock (tile, overlap) in latents for ``vae``, or None when unreadable. The overlap is the blend width."""
+ try:
+ ratio = compression_ratio(vae)
+ if hasattr(vae, "tile_sample_stride_height"):
+ sides = (
+ (int(vae.tile_sample_min_height), int(vae.tile_sample_stride_height)),
+ (int(vae.tile_sample_min_width), int(vae.tile_sample_stride_width)),
+ )
+ tile = min(t // ratio for t, _ in sides)
+ overlap = min((t - st) // ratio for t, st in sides)
+ elif hasattr(vae, "tile_latent_min_size") and hasattr(vae, "tile_overlap_factor"):
+ tile = int(vae.tile_latent_min_size)
+ overlap = tile - int(tile * (1 - float(vae.tile_overlap_factor)))
+ else:
+ return None
+ except (AttributeError, TypeError, ValueError):
+ return None
+ if tile <= 0 or overlap < 0 or overlap >= tile:
+ return None
+ return tile, overlap
+
+
+def stock_layout_ok(stock: tuple[int, int], height: int, width: int) -> bool:
+ """Whether every stock tile is >= 32 latents and every overlap >= 16. diffusers starts a tile every ``tile -
+ overlap`` latents until the canvas ends, so the last tile can be a sliver (8 latents on a 200-latent side)."""
+ tile, overlap = stock
+ if tile < TILE_LATENTS or overlap < OVERLAP_LATENTS:
+ return False
+ stride = tile - overlap
+ for length in (int(height), int(width)):
+ if length <= tile:
+ continue
+ if any(length - s < TILE_LATENTS for s in range(stride, length, stride)):
+ return False
+ return True
+
+
+def floor_tiles(vae: Any) -> tuple[int, int]:
+ """Wide-path minimum (tile, overlap): 32 / 16, or the stock values when larger."""
+ stock = stock_tiles(vae) or (0, 0)
+ return max(TILE_LATENTS, stock[0]), max(OVERLAP_LATENTS, stock[1])
+
+
+# Class name -> measured reason to keep diffusers' tiles. Empty: every covered VAE measured better or identical.
+KEEP_STOCK: dict[str, str] = {}
+
+
def _wants_wide_tiles(vae: Any) -> bool:
- if vae is None or type(vae).__name__ not in _VAE_CLASSES:
+ if vae is None or type(vae).__name__ in KEEP_STOCK:
return False
config = getattr(vae, "config", None)
- if getattr(config, "patch_size", None) is not None:
+ # Patchified Wan VAEs blend in patch space; FLUX.2's patch_size is pipeline packing its decode never sees.
+ if getattr(config, "patch_size", None) is not None and hasattr(
+ vae, "tile_sample_stride_height"
+ ):
return False
- try:
- ratio = int(vae.spatial_compression_ratio)
- except (AttributeError, TypeError, ValueError):
+ if stock_tiles(vae) is None:
return False
- return ratio >= 16 and callable(getattr(vae, "_decode", None)) and hasattr(vae, "use_tiling")
+ return (
+ callable(getattr(vae, "_decode", None))
+ and callable(getattr(vae, "tiled_decode", None))
+ and hasattr(vae, "use_tiling")
+ )
+
+
+def _wide_encode(vae: Any) -> bool:
+ """Wan family only: AutoencoderKL-style VAEs tile their encode in a private ``_tiled_encode``."""
+ return (
+ hasattr(vae, "tile_sample_stride_height")
+ and callable(getattr(vae, "tiled_encode", None))
+ and callable(getattr(vae, "_encode", None))
+ )
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."""
+ """Route ``vae``'s tiled decode / encode through the wide tiles where stock falls under the floor. 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):
@@ -262,37 +368,43 @@ def install(vae: Any, logger: Any = None) -> bool:
own_encode = vae.__dict__.get("tiled_encode")
stock = vae.tiled_decode
stock_encode = getattr(vae, "tiled_encode", None)
+ geometry = stock_tiles(vae)
+ ratio = compression_ratio(vae)
def _tiled_decode(
self: Any,
z: Any,
return_dict: bool = True,
) -> Any:
- if wide_tiles_disabled():
+ if wide_tiles_disabled() or stock_layout_ok(geometry, z.shape[-2], z.shape[-1]):
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():
+ if wide_tiles_disabled() or stock_layout_ok(
+ geometry, x.shape[-2] // ratio, x.shape[-1] // ratio
+ ):
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)):
+ if _wide_encode(vae):
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)
+ tile, overlap = floor_tiles(vae)
+ vae._unsloth_decode_tile_side = tile * 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",
+ "diffusion.vae_tiling: %s (%dx, stock %d-latent tiles with %d-latent overlaps) decodes in %d-latent "
+ "tiles with %d-latent overlaps, the last tile edge-aligned, whenever the stock tiles fall under that",
type(vae).__name__,
- TILE_LATENTS,
- OVERLAP_LATENTS,
- ENCODE_TILE_LATENTS,
- ENCODE_OVERLAP_LATENTS,
+ ratio,
+ geometry[0],
+ geometry[1],
+ tile,
+ overlap,
)
return True
diff --git a/studio/backend/tests/test_diffusion_vae_tiling_general.py b/studio/backend/tests/test_diffusion_vae_tiling_general.py
new file mode 100644
index 00000000000..4d964d632fc
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_vae_tiling_general.py
@@ -0,0 +1,384 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The wide, edge-aligned tiled VAE decode for every image VAE whose stock tiles fall under the floor.
+
+diffusion_vae_tiling reads each VAE's own tile geometry (diffusers' tile and overlap, in latents) and its compression
+ratio, and per decode keeps the stock tiles when they meet the floor (every tile >= 32 latents, every overlap >= 16)
+and takes the wide tiles when they do not. These pin the rule for 8x, 16x and 32x VAEs."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+
+import pytest
+
+torch = pytest.importorskip("torch")
+diffusers = pytest.importorskip("diffusers")
+
+from core.inference import diffusion_memory as dm # noqa: E402
+from core.inference import diffusion_vae_tiling as vt # noqa: E402
+
+
[email protected](autouse = True)
+def _fixed_decode_tiles(monkeypatch):
+ """CPU decodes use the floor tiles anyway; pin it so a CUDA box runs the same geometry."""
+ monkeypatch.delenv(vt.WIDE_TILES_ENV, raising = False)
+ monkeypatch.setenv(vt.MAX_TILE_ENV, "1")
+
+
+def _need(name):
+ cls = getattr(diffusers, name, None)
+ if cls is None:
+ pytest.skip(f"diffusers without {name}")
+ return cls
+
+
+def _qwen_image():
+ """Qwen-Image / Qwen-Image-Edit / Krea-2's VAE class, 8x: stock 32-latent tiles with 8-latent blends."""
+ torch.manual_seed(0)
+ return _need("AutoencoderKLQwenImage")(
+ base_dim = 8,
+ z_dim = 4,
+ dim_mult = [1, 2, 4, 4],
+ num_res_blocks = 1,
+ attn_scales = [],
+ temperal_downsample = [False, True, True],
+ latents_mean = [0.0] * 4,
+ latents_std = [1.0] * 4,
+ ).eval()
+
+
+def _qwen_image_21():
+ torch.manual_seed(0)
+ return _need("AutoencoderKLQwenImage21")(
+ 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 _kl(sample_size = 1024, cls = "AutoencoderKL"):
+ """FLUX.1 / Z-Image / HiDream / Lumina / SDXL (AutoencoderKL) or FLUX.2 / Ideogram 4 (AutoencoderKLFlux2), 8x."""
+ torch.manual_seed(0)
+ return _need(cls)(
+ in_channels = 3,
+ out_channels = 3,
+ down_block_types = ("DownEncoderBlock2D",) * 4,
+ up_block_types = ("UpDecoderBlock2D",) * 4,
+ block_out_channels = (8, 8, 8, 8),
+ layers_per_block = 1,
+ latent_channels = 4,
+ norm_num_groups = 4,
+ sample_size = sample_size,
+ ).eval()
+
+
+def _hunyuan_image():
+ """HunyuanImage-2.1's VAE, 32x: stock 12-latent (384 px) tiles with 3-latent blends."""
+ torch.manual_seed(0)
+ return _need("AutoencoderKLHunyuanImage")(
+ in_channels = 3,
+ out_channels = 3,
+ latent_channels = 8,
+ block_out_channels = (32,) * 6,
+ layers_per_block = 1,
+ spatial_compression_ratio = 32,
+ sample_size = 384,
+ ).eval()
+
+
+# (builder, ratio, stock (tile, overlap), floor (tile, overlap)) with each VAE's real tile settings
+GEOMETRY = [
+ (_qwen_image, 8, (32, 8), (32, 16)),
+ (_qwen_image_21, 16, (16, 4), (32, 16)),
+ (_hunyuan_image, 32, (12, 3), (32, 16)),
+ (_kl, 8, (128, 32), (128, 32)),
+ (lambda: _kl(cls = "AutoencoderKLFlux2"), 8, (128, 32), (128, 32)),
+]
+
+
[email protected]("build, ratio, stock, floor", GEOMETRY)
+def test_geometry_is_read_off_each_vae(build, ratio, stock, floor):
+ vae = build()
+ assert vt.compression_ratio(vae) == ratio
+ assert vt.stock_tiles(vae) == stock
+ assert vt.floor_tiles(vae) == floor
+ assert vt.install(vae)
+ # the memory estimates see the wide floor tile; it never shrinks below the stock tile
+ assert vae._unsloth_decode_tile_side == floor[0] * ratio
+ assert dm.vae_tile_side(vae) == floor[0] * ratio
+ vt.uninstall(vae)
+ assert "tiled_decode" not in vae.__dict__
+
+
+ "stock, length, ok",
+ [
+ # Qwen-Image (8x), Qwen-Image-2.1 (16x), HunyuanImage-2.1 (32x): blends under 16 latents, every size
+ ((32, 8), 40, False),
+ ((32, 8), 128, False),
+ ((16, 4), 64, False),
+ ((12, 3), 64, False),
+ # AutoencoderKL / FLUX.2 (8x, 1024 px tiles, 768 px stride): fine unless the last tile is a sliver
+ ((128, 32), 128, True),
+ ((128, 32), 166, True), # 1328 px
+ ((128, 32), 192, True), # 1536 px
+ ((128, 32), 200, False), # 1600 px: an 8-latent last tile
+ ((128, 32), 220, False), # 1760 px: 28 latents
+ ((128, 32), 224, True), # 1792 px: 32 latents
+ ((128, 32), 256, True), # 2048 px
+ ((128, 32), 296, False), # 2368 px: 8 latents
+ ((128, 32), 336, True), # 2688 px
+ ],
+)
+def test_stock_layout_floor(stock, length, ok):
+ assert vt.stock_layout_ok(stock, length, length) is ok
+ assert vt.stock_layout_ok(stock, min(length, stock[0]), length) is ok
+ # one tiled axis is enough to fail
+ if not ok:
+ assert vt.stock_layout_ok(stock, stock[0], length) is False
+
+
[email protected]("tile, overlap", [(32, 16), (128, 32)])
[email protected]("length", list(range(1, 400, 3)))
+def test_wide_tiles_are_full_and_edge_aligned_for_every_floor(tile, overlap, length):
+ starts = vt.tile_starts(length, tile, overlap)
+ if length <= tile:
+ assert starts == [0]
+ return
+ assert starts[0] == 0 and starts[-1] + tile == length
+ assert all(b + overlap <= a + tile for a, b in zip(starts, starts[1:]))
+ for ratio in (8, 16, 32):
+ weights = vt.axis_weights(starts, tile, length, ratio, torch, "cpu")
+ total = torch.zeros(length * ratio)
+ for s, w in zip(starts, weights):
+ total[s * ratio : s * ratio + w.numel()] += w
+ torch.testing.assert_close(total, torch.ones_like(total))
+
+
+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]
+ if d.dim() == 3:
+ d = d[0]
+ return max(float(d.mean(0).max()), float(d.mean(1).max()))
+
+
+def _decode_three_ways(vae, z):
+ 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
+ return untiled, stock, wide
+
+
[email protected]("latents", [40, 64])
+def test_qwen_image_tiled_decode_has_no_seam_lines(latents):
+ """Fails before this change: the Qwen-Image VAE kept diffusers' 32-latent tiles with 8-latent blends."""
+ vae = _qwen_image()
+ z = torch.randn(1, 4, 1, latents, latents, generator = torch.Generator().manual_seed(1))
+ untiled, stock, wide = _decode_three_ways(vae, z)
+ stock_err, wide_err = _line_error(stock, untiled), _line_error(wide, untiled)
+ assert stock_err > 0.02
+ assert wide_err < stock_err / 2, (stock_err, wide_err)
+ assert vae._unsloth_last_decode_tile[:2] == (32, 32)
+
+
+def test_hunyuan_image_tiled_decode_has_no_seam_lines():
+ """32x: stock 12-latent tiles with 3-latent blends; the floor is 32-latent tiles with 16-latent overlaps."""
+ vae = _hunyuan_image()
+ z = torch.randn(1, 8, 40, 40, generator = torch.Generator().manual_seed(1))
+ untiled, stock, wide = _decode_three_ways(vae, z)
+ stock_err, wide_err = _line_error(stock, untiled), _line_error(wide, untiled)
+ assert stock_err > 0.02
+ assert wide_err < stock_err / 4, (stock_err, wide_err)
+ assert wide.shape == untiled.shape
+
+
+def test_kl_vae_keeps_the_stock_tiles_where_they_meet_the_floor():
+ """AutoencoderKL with 512 px tiles (64 latents, 16-latent blends): bit-identical to stock on an 80-latent canvas."""
+ vae = _kl(sample_size = 512)
+ assert vt.stock_tiles(vae) == (64, 16)
+ z = torch.randn(1, 4, 80, 80, generator = torch.Generator().manual_seed(2))
+ _, stock, wide = _decode_three_ways(vae, z)
+ assert torch.equal(wide, stock)
+
+
+def test_kl_vae_takes_the_wide_tiles_for_an_edge_sliver():
+ """A 100-latent side leaves stock a 4-latent last tile; the wide tiles end at the edge at full size."""
+ vae = _kl(sample_size = 512)
+ z = torch.randn(1, 4, 100, 100, generator = torch.Generator().manual_seed(2))
+ untiled, stock, wide = _decode_three_ways(vae, z)
+ assert vt.stock_layout_ok(vt.stock_tiles(vae), 100, 100) is False
+ stock_err, wide_err = _line_error(stock, untiled), _line_error(wide, untiled)
+ assert wide_err < stock_err / 3, (stock_err, wide_err)
+ assert vae._unsloth_last_decode_tile[:2] == (64, 64)
+
+
+def test_kl_encode_is_untouched_and_qwen_image_encode_is_wide():
+ """AutoencoderKL tiles its encode privately (``_tiled_encode``, 1024 px tiles); the Wan family routes ``_encode``
+ through ``tiled_encode`` with the stock 8-latent blends."""
+ kl = _kl()
+ assert vt.install(kl)
+ assert "tiled_encode" not in kl.__dict__
+ qi = _qwen_image()
+ assert vt.install(qi)
+ assert "tiled_encode" in qi.__dict__
+
+
+def test_qwen_image_tiled_encode_is_closer_to_untiled():
+ vae = _qwen_image()
+ g = torch.Generator().manual_seed(4)
+ x = torch.nn.functional.interpolate(
+ torch.rand(1, 3, 8, 8, generator = g) * 2 - 1, size = (640, 640), mode = "bicubic"
+ ).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
+ assert (wide - untiled).abs().mean() < (stock - untiled).abs().mean() / 2
+
+
[email protected]("build, ratio, stock, floor", GEOMETRY)
+def test_kill_switch_keeps_every_stock_decode(monkeypatch, build, ratio, stock, floor):
+ vae = build()
+ side = max(floor[0] + 8, stock[0] + 8)
+ shape = (
+ (1, 4, side, side)
+ if not hasattr(vae, "tile_sample_stride_height")
+ else (1, 4, 1, side, side)
+ )
+ if ratio == 32:
+ shape = (1, 8, side, side)
+ if ratio * side > 1300:
+ pytest.skip("too large a CPU decode")
+ z = torch.randn(*shape, generator = torch.Generator().manual_seed(3))
+ with torch.no_grad():
+ vae.enable_tiling()
+ before = vae.decode(z).sample
+ assert vt.install(vae)
+ monkeypatch.setenv(vt.WIDE_TILES_ENV, "0")
+ killed = vae.decode(z).sample
+ assert torch.equal(killed, before)
+
+
+def test_keep_stock_list_skips_the_install(monkeypatch):
+ monkeypatch.setitem(vt.KEEP_STOCK, "AutoencoderKLQwenImage", "test")
+ vae = _qwen_image()
+ assert vt.install(vae) is False
+ assert "tiled_decode" not in vae.__dict__
+ for reason in vt.KEEP_STOCK.values():
+ assert reason # every kept class states its measured reason
+
+
+def test_unreadable_geometry_keeps_the_stock_decode():
+ cls = type(
+ "SomeFutureVAE", (), {"_decode": lambda self: None, "tiled_decode": lambda self: None}
+ )
+ vae = cls()
+ vae.use_tiling, vae.spatial_compression_ratio = False, 16
+ assert vt.stock_tiles(vae) is None
+ assert vt.install(vae) is False
+
+
[email protected]("ratio", [8, 16, 32])
+def test_decode_budget_scales_with_the_tile_pixels(ratio):
+ """1.7 MiB per latent at 16x, the per-pixel figure for every ratio, so Qwen-Image-2.1's budget is unchanged."""
+ per_latent = vt.DECODE_MIB_PER_LATENT * (ratio / vt.DECODE_MIB_RATIO) ** 2
+ assert per_latent / ratio**2 == pytest.approx(1.7 / 256)
+ if ratio == 16:
+ assert per_latent == vt.DECODE_MIB_PER_LATENT
+
+
+# Unfused bf16 decode peak over the weights with floor tiles, real diffusers VAE weights on a B200, worst over 1024 to
+# 2048 px canvases (fp32 output accumulator included): the per-pixel budget figure must bound each covered VAE.
+_MEASURED_FLOOR_TILE_PEAK_MIB = {
+ (8, 32): 314, # Qwen-Image / Qwen-Image-Edit / Krea-2 (AutoencoderKLQwenImage)
+ (16, 32): 1_697, # Qwen-Image-2.1 (AutoencoderKLQwenImage21, #12696)
+ (32, 32): 1_332, # HunyuanImage-2.1 (AutoencoderKLHunyuanImage)
+ (
+ 8,
+ 128,
+ ): 2_486, # FLUX.1 / FLUX.2 / SDXL (AutoencoderKL, AutoencoderKLFlux2) at an edge-sliver size
+}
+
+
+def test_budget_figure_bounds_the_measured_floor_tile_peaks():
+ for (ratio, tile), peak in _MEASURED_FLOOR_TILE_PEAK_MIB.items():
+ budget = vt.DECODE_MIB_PER_LATENT * (ratio / vt.DECODE_MIB_RATIO) ** 2 * tile * tile
+ assert budget >= peak, (ratio, tile, budget, peak)
+
+
+def _image_family_vae_classes():
+ """Every image family's VAE class, from the diffusers pipeline's own ``vae`` annotation."""
+ from core.inference.diffusion_families import _FAMILIES
+
+ out = {}
+ for fam in _FAMILIES:
+ pipe = getattr(diffusers, fam.pipeline_class, None)
+ if pipe is None:
+ continue
+ ann = inspect.signature(pipe.__init__).parameters.get("vae")
+ if ann is None:
+ continue
+ hint = ann.annotation
+ name = hint if isinstance(hint, str) else getattr(hint, "__name__", str(hint))
+ out[fam.name] = name.split(".")[-1].split("|")[0].strip()
+ return out
+
+
+def test_every_image_family_vae_is_covered_or_kept_stock_on_purpose():
+ """A new image family (or a diffusers that renames a VAE) must land on a VAE whose tile geometry the rule reads,
+ or be listed in KEEP_STOCK with the measured reason: a VAE the rule cannot read keeps stock tiles silently."""
+ readable = {
+ "AutoencoderKL",
+ "AutoencoderKLFlux2",
+ "AutoencoderKLQwenImage",
+ "AutoencoderKLQwenImage21",
+ "AutoencoderKLHunyuanImage",
+ }
+ found = _image_family_vae_classes()
+ assert found, "no image family resolved its VAE class"
+ for fam, cls in found.items():
+ assert cls in readable or cls in vt.KEEP_STOCK, (fam, cls)
+
+
+def test_load_installs_for_every_image_family():
+ """The load path installs unconditionally (the rule decides per VAE), not behind a family check."""
+ from core.inference import diffusion
+
+ src = textwrap.dedent(
+ inspect.getsource(inspect.unwrap(diffusion.DiffusionBackend.load_pipeline))
+ )
+ calls = [
+ node
+ for node in ast.walk(ast.parse(src))
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id == "install_wide_vae_tiles"
+ ]
+ assert calls
+ for node in ast.walk(ast.parse(src)):
+ # not nested under an `if` on the family / VAE class
+ if isinstance(node, ast.If) and any(c in ast.walk(node) for c in calls):
+ assert (
+ "fam" not in ast.unparse(node.test) and "vae" not in ast.unparse(node.test).lower()
+ )