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: 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.pyindex 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 = 32ENCODE_MARGIN_LATENTS = 8ENCODE_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 = 16FREE_FRACTION = 0.75MAX_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 floorbest, 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), costreturn best@@ -137,11 +161,14 @@ def decode_tile_budget(vae: Any, z: Any) -> Optional[int]:return Nonefree, _ = 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 * ratioelem = 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 budgetedreturn 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 torchfrom 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, Nonefor 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.dtypeout = 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 // ratiotile, overlap = ENCODE_TILE_LATENTS, ENCODE_OVERLAP_LATENTShs = 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 Falseconfig = 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 Falseif 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_decodestock_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 = ownvae.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_encodevae.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 * ratiovae._unsloth_wide_tiles = Trueif 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 Truediff --git a/studio/backend/tests/test_diffusion_vae_tiling_general.py b/studio/backend/tests/test_diffusion_vae_tiling_general.pynew file mode 100644index 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()+ )