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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Stock tiles below the floor (tiles >= 32 latents, overlaps >= 16) go wide and edge-aligned."""
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
@pytest.fixture(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()
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)),
]
@pytest.mark.parametrize("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)
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__
@pytest.mark.parametrize(
"stock, length, ok",
[
((32, 8), 40, False),
((32, 8), 128, False),
((16, 4), 64, False),
((12, 3), 64, False),
((128, 32), 128, True),
((128, 32), 166, True),
((128, 32), 192, True),
((128, 32), 200, False), # 1600 px: an 8-latent last tile
((128, 32), 220, False),
((128, 32), 224, True),
((128, 32), 256, True),
((128, 32), 296, False), # 2368 px: 8 latents
((128, 32), 336, True),
],
)
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
if not ok:
assert vt.stock_layout_ok(stock, stock[0], length) is False
@pytest.mark.parametrize("tile, overlap", [(32, 16), (128, 32)])
@pytest.mark.parametrize("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
@pytest.mark.parametrize("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)
# Two 60-latent tiles per side: 120 latents in 2 calls, beating stock 64+52+4 in 3.
assert vae._unsloth_last_decode_tile[:2] == (60, 60)
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
@pytest.mark.parametrize("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
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
# bf16 decode peak per latent of tile area, (unfused, fused) MiB: one untiled ``_decode`` of a t x t latent, t = 8 to
# 128, on the real diffusers VAE weights (B200, diffusers 0.41.0.dev0, temp calibration run); the worst side per VAE.
_MEASURED_MIB_PER_LATENT = {
"AutoencoderKLQwenImage": (8, 0.270, 0.179), # Qwen-Image / Qwen-Image-Edit / Krea-2
"AutoencoderKLQwenImage21": (
16,
1.650,
0.425,
), # Qwen-Image-2.1 (the 8-latent fused side, 0.59, is never a tile)
"AutoencoderKLHunyuanImage": (32, 1.255, 1.255), # HunyuanImage-2.1, no fused path
"AutoencoderKL": (8, 0.166, 0.086), # FLUX.1 / Kontext / Z-Image / HiDream / Lumina 2 / SDXL
"AutoencoderKLFlux2": (8, 0.166, 0.086), # FLUX.2 / Ideogram 4
}
@pytest.mark.parametrize("cls", sorted(_MEASURED_MIB_PER_LATENT))
def test_calibrated_figures_bound_the_measured_peaks_and_are_tight(cls):
"""Not the old per-pixel scaling (6.8 MiB per latent at 32x, 5x HunyuanImage's peak; 0.43 at 8x, 2.9x
AutoencoderKL's): within 10% of each VAE's measured peak (Qwen-Image-2.1: #12696's 1.7), so the free VRAM buys
the largest tiles it really holds."""
ratio, unfused, fused = _MEASURED_MIB_PER_LATENT[cls]
assert unfused <= vt.decode_mib_per_latent(ratio, False, cls) <= 1.1 * unfused
assert fused <= vt.decode_mib_per_latent(ratio, True, cls) <= 1.1 * fused
# a class not measured takes the worst VAE of its ratio
worst = max(u for r, u, _ in _MEASURED_MIB_PER_LATENT.values() if r == ratio)
worst_fused = max(f for r, _, f in _MEASURED_MIB_PER_LATENT.values() if r == ratio)
assert vt.decode_mib_per_latent(ratio, False, "SomeFutureVAE") >= worst
assert vt.decode_mib_per_latent(ratio, True, "SomeFutureVAE") >= worst_fused
def test_calibrated_figures_other_ratios():
# Qwen-Image-2.1's unfused figure is #12696's
assert vt.decode_mib_per_latent(16) == 1.7
# an unmeasured ratio keeps the per-pixel scaling of the 16x figure
assert vt.decode_mib_per_latent(4) == pytest.approx(1.7 / 16)
@pytest.mark.parametrize("fused", [False, True])
def test_budget_uses_the_fused_figure_only_where_the_fused_kernels_are_installed(
monkeypatch, fused
):
vae = _hunyuan_image()
qi = _qwen_image()
monkeypatch.delenv(vt.MAX_TILE_ENV)
monkeypatch.setattr(vt, "_free_mib", lambda v, z, **k: (1000.0, 1.0))
for v in (vae, qi):
assert vt.install(v)
if fused:
v._unsloth_vae_fused_installed = 7
z = torch.zeros(1, 4, 1, 64, 64)
want = int(vt.FREE_FRACTION * 1000 / (0.18 if fused else 0.27))
assert vt.decode_tile_budget(qi, z) == want
assert vt.decode_tile_budget(vae, torch.zeros(1, 8, 64, 64)) == int(
vt.FREE_FRACTION * 1000 / 1.3
)
kl = _kl()
assert vt.install(kl)
if fused:
kl._unsloth_vae_fused_installed = 3
assert vt.decode_tile_budget(kl, torch.zeros(1, 4, 64, 64)) == int(
vt.FREE_FRACTION * 1000 / (0.09 if fused else 0.17)
)
qi._unsloth_vae_fused_failed = True
assert vt.decode_tile_budget(qi, z) == int(vt.FREE_FRACTION * 1000 / 0.27)
def test_only_large_stock_tile_vaes_size_past_the_floor_from_device_free_memory(monkeypatch):
"""AutoencoderKL and FLUX.2 grow tiles into device free memory, not the allocator's cache."""
monkeypatch.delenv(vt.MAX_TILE_ENV)
seen = {}
def free(
v,
z,
cached = True,
):
seen[type(v).__name__] = cached
return 1000.0 if cached else 100.0, 1.0
monkeypatch.setattr(vt, "_free_mib", free)
for build, z in (
(_kl, torch.zeros(1, 4, 64, 64)),
(lambda: _kl(cls = "AutoencoderKLFlux2"), torch.zeros(1, 4, 64, 64)),
(_qwen_image, torch.zeros(1, 4, 1, 64, 64)),
(_qwen_image_21, torch.zeros(1, 4, 1, 64, 64)),
(_hunyuan_image, torch.zeros(1, 8, 64, 64)),
):
vae = build()
assert vt.install(vae)
vt.decode_tile_budget(vae, z)
assert seen == {
"AutoencoderKL": False,
"AutoencoderKLFlux2": False,
"AutoencoderKLQwenImage": True,
"AutoencoderKLQwenImage21": True,
"AutoencoderKLHunyuanImage": True,
}
# and the floor-fit check (stock fallback) still counts the cache for every VAE
vae = _hunyuan_image()
assert vt.install(vae)
seen.clear()
vt.floor_shortfall(vae, torch.zeros(1, 8, 64, 64))
assert seen == {"AutoencoderKLHunyuanImage": True}
def _stock_decoded(length, tile, overlap):
"""Latents diffusers' stock loop decodes along one side (a tile every tile - overlap, the last one cut short)."""
if length <= tile:
return length
return sum(min(tile, length - s) for s in range(0, length, tile - overlap))
@pytest.mark.parametrize("length", list(range(129, 420)))
@pytest.mark.parametrize("max_area", [None, 23_200, 10**6])
def test_large_floor_tiles_never_decode_more_than_stock(length, max_area):
"""Large-floor tiles must never decode more latents than the stock loop, and leave no sliver."""
if vt.stock_layout_ok((128, 32), length, length):
return # no sliver: these sizes decode through the stock tiles
th, tw = vt.choose_tiles(length, length, max_area, 128, 32, 128)
assert th * tw <= max(max_area or 0, 128 * 128) and min(th, tw) >= vt.TILE_LATENTS
stock_calls = len(range(0, length, 96))
span = _stock_decoded(length, 128, 32)
for side in (th, tw):
starts = vt.tile_starts(length, side, 32)
assert starts[0] == 0 and starts[-1] + side == length or starts == [0]
assert all(b + 32 <= a + side for a, b in zip(starts, starts[1:]))
assert len(starts) < stock_calls
assert len(starts) * side <= span + len(starts) - 1
if length == 200:
assert (th, tw) == {None: (120, 120), 23_200: (116, 200), 10**6: (200, 200)}[max_area]
if max_area is None:
assert vt.tile_starts(200, 120, 32) == [0, 80]
def test_qwen_family_layout_ignores_the_large_stock_rule():
"""Only a VAE whose stock tile is the floor tile takes the stock-work rule; the 32-latent floor VAEs keep #12696's
fewest-latents choice whatever stock tile is passed."""
for length in (64, 100, 128, 166, 256):
for area in (None, 1500, 4000, 10**6):
assert vt.choose_tiles(length, length, area) == vt.choose_tiles(
length, length, area, 32, 16, 16
)
assert vt.choose_tiles(length, length, area) == vt.choose_tiles(
length, length, area, 32, 16, 32
)
@pytest.mark.parametrize("length", list(range(1, 400)))
@pytest.mark.parametrize("max_area", [None, 0, 1024])
def test_the_32_latent_floor_layout_is_unchanged(length, max_area):
"""Qwen-Image, Qwen-Image-2.1 and HunyuanImage at the floor: 32-latent tiles, as #12696 picks."""
assert vt.choose_tiles(length, length, max_area) == (min(32, length), min(32, length))
def _decode_with(vae, z):
with torch.no_grad():
vae.enable_tiling()
return vae.decode(z).sample
class _Log:
def __init__(self):
self.records = []
def info(self, *a):
pass
def debug(self, *a):
self.records.append(("debug", a[0] % a[1:]))
def warning(self, *a):
self.records.append(("warning", a[0] % a[1:]))
def test_floor_that_cannot_fit_decodes_in_the_stock_tiles_and_says_why(monkeypatch):
"""HunyuanImage's 32-latent floor tile peaks at ~1.3 GiB, its 12-latent stock tile at ~0.2: with less free than the
floor needs, OOM loses to a seam, so the decode takes the stock tiles and logs the reason (once per VAE)."""
vae = _hunyuan_image()
z = torch.randn(1, 8, 40, 40, generator = torch.Generator().manual_seed(1))
stock = _decode_with(vae, z)
log = _Log()
assert vt.install(vae, log)
monkeypatch.delenv(vt.MAX_TILE_ENV)
monkeypatch.setattr(
vt, "_free_mib", lambda v, zz, **k: (500.0, 1.0)
) # 32x32 x 1.3 MiB = 1,331 MiB needed
assert "floor tile needs about 1331 MiB" in vt.floor_shortfall(vae, z)
assert torch.equal(_decode_with(vae, z), stock)
assert _decode_with(vae, z).shape == stock.shape
assert [k for k, _ in log.records] == ["warning", "debug"]
assert "HunyuanImage" in log.records[0][1] and "stock tiles" in log.records[0][1]
# with room for the floor, the wide tiles again
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (2000.0, 1.0))
assert vt.floor_shortfall(vae, z) is None
assert not torch.equal(_decode_with(vae, z), stock)
# unknown free memory (CPU) and an explicit tile cap are never a shortfall
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: None)
assert vt.floor_shortfall(vae, z) is None
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (1.0, 1.0))
monkeypatch.setenv(vt.MAX_TILE_ENV, "32")
assert vt.floor_shortfall(vae, z) is None
@pytest.mark.parametrize("build", [_qwen_image, _kl, lambda: _kl(cls = "AutoencoderKLFlux2")])
def test_no_stock_fallback_where_the_stock_tile_is_as_large(monkeypatch, build):
"""Qwen-Image (32-latent stock tiles) and AutoencoderKL / FLUX.2 (128): the stock tiles need as much memory as the
floor, so a low free VRAM keeps the wide tiles (the FLUX.1 sliver fix held at 2 GiB free only after this)."""
vae = build()
assert vt.install(vae)
vae._unsloth_vae_fused_installed = 3
monkeypatch.delenv(vt.MAX_TILE_ENV)
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (1.0, 1.0))
z = (
torch.zeros(1, 4, 1, 200, 200)
if hasattr(vae, "tile_sample_stride_height")
else torch.zeros(1, 4, 200, 200)
)
assert vt.floor_shortfall(vae, z) is None
def test_floor_fit_uses_the_fused_peak_so_qwen_image_21_keeps_its_wide_floor(monkeypatch):
"""Qwen-Image-2.1's fused floor tile peaks at ~0.43 GiB: it stays on the wide floor down to that (where #12696
would OOM), not at the 1.7 GiB unfused figure."""
vae = _qwen_image_21()
assert vt.install(vae)
vae._unsloth_vae_fused_installed = 5
monkeypatch.delenv(vt.MAX_TILE_ENV)
z = torch.zeros(1, 4, 1, 64, 64)
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (500.0, 1.0))
assert vt.floor_shortfall(vae, z) is None
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (400.0, 1.0))
assert vt.floor_shortfall(vae, z)
vae._unsloth_vae_fused_failed = True
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (1500.0, 1.0))
assert vt.floor_shortfall(vae, z)
def test_oom_retries_at_the_floor_then_in_the_stock_tiles(monkeypatch):
vae = _qwen_image()
z = torch.randn(1, 4, 1, 64, 64, generator = torch.Generator().manual_seed(1))
stock = _decode_with(vae, z)
assert vt.install(vae, _Log())
floor = _decode_with(vae, z) # the autouse 1-latent cap: the floor tiles
real = vt.tiled_decode
calls = []
def flaky(
v,
zz,
return_dict = True,
max_area = "auto",
fail = ("auto",),
):
calls.append(max_area)
if max_area in fail:
v._unsloth_last_decode_tile = (48, 48, 2304) if max_area == "auto" else (32, 32, 0)
raise torch.OutOfMemoryError("CUDA out of memory. Tried to allocate 1 GiB")
return real(v, zz, return_dict = return_dict, max_area = max_area)
monkeypatch.setattr(vt, "tiled_decode", flaky)
assert torch.equal(_decode_with(vae, z), floor)
assert calls == ["auto", 0]
calls.clear()
monkeypatch.setattr(vt, "tiled_decode", lambda *a, **k: flaky(*a, **k, fail = ("auto", 0)))
assert torch.equal(_decode_with(vae, z), stock)
assert calls == ["auto", 0]
# an error that is not an OOM propagates
monkeypatch.setattr(
vt, "tiled_decode", lambda *a, **k: (_ for _ in ()).throw(ValueError("bad"))
)
with pytest.raises(ValueError):
_decode_with(vae, z)
def test_geometry_and_blend_weights_are_cached_per_vae(monkeypatch):
vae = _qwen_image()
assert vt.install(vae)
assert vae._unsloth_wide_geometry == (8, 32, 16)
built = []
real = vt.axis_weights
monkeypatch.setattr(vt, "axis_weights", lambda *a, **k: built.append(a[:3]) or real(*a, **k))
monkeypatch.setattr(vt, "compression_ratio", lambda v: pytest.fail("ratio re-read per decode"))
z = torch.randn(1, 4, 1, 48, 48, generator = torch.Generator().manual_seed(1))
first = _decode_with(vae, z)
assert len(built) == 1
second = _decode_with(vae, z)
assert len(built) == 1 and torch.equal(first, second)
vt.uninstall(vae)
assert (
"_unsloth_wide_weights" not in vae.__dict__ and "_unsloth_wide_geometry" not in vae.__dict__
)
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)):
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()
)
def test_stock_fallback_keeps_the_fused_batched_loop_on_the_wan_family(monkeypatch):
"""Under the wide tiles the fused VAE layer cannot take ``tiled_decode`` (they own it), so before this the stock
fallback (kill switch, or a floor that cannot fit) ran diffusers' one-tile-per-call loop, slower than main's
batched one. Now the batched loop backs the fallback, and is ``tiled_decode`` again after an uninstall."""
from core.inference import diffusion_vae_fused as fused
vae = _qwen_image_21()
assert vt.install(vae)
ours = vae.__dict__["tiled_decode"]
assert fused.install_wan_tile_batch(vae) is False
assert vae.__dict__["tiled_decode"] is ours
batched = vae.__dict__["_unsloth_wide_stock_decode"]
assert getattr(batched, "_unsloth_vae_fused", False)
calls = []
vae._unsloth_wide_stock_decode = lambda z, return_dict = True: calls.append(z.shape) or batched(
z, return_dict = return_dict
)
z = torch.randn(1, 4, 1, 48, 48, generator = torch.Generator().manual_seed(1))
with torch.no_grad():
vae.enable_tiling()
monkeypatch.setenv(vt.WIDE_TILES_ENV, "0")
killed = vae.decode(z).sample
monkeypatch.delenv(vt.WIDE_TILES_ENV)
monkeypatch.delenv(vt.MAX_TILE_ENV)
monkeypatch.setattr(vt, "_free_mib", lambda v, zz, **k: (1.0, 1.0))
short = vae.decode(z).sample
assert len(calls) == 2 and torch.equal(killed, short)
vae._unsloth_wide_stock_decode = batched
vt.uninstall(vae)
assert vae.__dict__.get("tiled_decode") is batched
# without the wide tiles the batched loop installs on ``tiled_decode`` as before
plain = _qwen_image_21()
assert fused.install_wan_tile_batch(plain)
assert getattr(plain.__dict__["tiled_decode"], "_unsloth_vae_fused", False)
assert "_unsloth_wide_stock_decode" not in plain.__dict__