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
"""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
import os
import types
from typing import Any, Optional
from .diffusion_device import float64_device
from .diffusion_vae_oom import clear_partial_decode
from .diffusion_vae_oom import free_first as oom_free_first
from .rocm_bf16 import is_rocm_torch
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 is one tile (bit-identical); the encoder attends over the whole tile.
ENCODE_TILE_LATENTS = 64
ENCODE_OVERLAP_LATENTS = 32
ENCODE_MARGIN_LATENTS = 8
ENCODE_RAMP_LATENTS = 16
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
build = float64_device(device)
pos = (torch.arange(size, dtype = torch.float64, device = build) + 0.5) / scale
total = torch.zeros(length * scale, dtype = torch.float64, device = build)
weights = []
for s in starts:
w = torch.ones(size, dtype = torch.float64, device = build)
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().to(device)
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
# bf16 decode peak MiB per latent of tile area, (unfused, fused): worst measured tile side 8 to 128, real weights.
# Per class (VAEs of one ratio differ 2x); an unmeasured class takes its ratio's worst.
DECODE_MIB_PER_LATENT_BY_CLASS = {
"AutoencoderKLQwenImage": (0.27, 0.18),
"AutoencoderKLQwenImage21": (1.7, 0.43),
"AutoencoderKLHunyuanImage": (1.3, 1.3),
"AutoencoderKL": (0.17, 0.09),
"AutoencoderKLFlux2": (0.17, 0.09),
}
DECODE_MIB_PER_LATENT_BY_RATIO = {8: (0.27, 0.18), 16: (1.7, 0.43), 32: (1.3, 1.3)}
# Strip decode 16-bit peak = slope MiB per latent + four strip buffers; bounds measured tiles 48-256 (L4, A100, T4).
DECODE_STRIPS_MIB_PER_LATENT_BY_CLASS = {"AutoencoderKLFlux2": 0.048}
DECODE_MIB_PER_LATENT = 1.7
DECODE_MIB_RATIO = 16
FREE_FRACTION = 0.75
MAX_TILE_ENV = "UNSLOTH_DIFFUSION_VAE_MAX_TILE"
# "0" keeps CPU / MPS decodes at the floor tile (no memory reading), as before the host budget.
HOST_BUDGET_ENV = "UNSLOTH_DIFFUSION_VAE_HOST_BUDGET"
def decode_mib_per_latent(
ratio: int,
fused: bool = False,
cls: Optional[str] = None,
) -> float:
"""bf16 decode peak MiB per latent: by class, else ratio, else the 16x figure scaled by tile pixels."""
known = DECODE_MIB_PER_LATENT_BY_CLASS.get(cls or "") or DECODE_MIB_PER_LATENT_BY_RATIO.get(
int(ratio)
)
if known is not None:
return known[1] if fused else known[0]
return DECODE_MIB_PER_LATENT * (int(ratio) / DECODE_MIB_RATIO) ** 2
# bf16 untiled encode peak MiB per latent of the encoded frame, (unfused, fused): B200, real weights, 512 to 1536 px
# (linear in area: Qwen-Image-2.1 0.565 / 0.283, Qwen-Image 0.165 / 0.121), rounded up.
ENCODE_MIB_PER_LATENT_BY_CLASS = {
"AutoencoderKLQwenImage": (0.17, 0.13),
"AutoencoderKLQwenImage21": (0.6, 0.3),
}
def encode_mib_per_latent(
ratio: int,
fused: bool = False,
cls: Optional[str] = None,
) -> Optional[float]:
"""bf16 untiled encode peak MiB per latent: measured, else the decode figure (an upper bound), else None."""
known = (
ENCODE_MIB_PER_LATENT_BY_CLASS.get(cls or "")
or DECODE_MIB_PER_LATENT_BY_CLASS.get(cls or "")
or DECODE_MIB_PER_LATENT_BY_RATIO.get(int(ratio))
)
if known is None:
return None
return known[1] if fused else known[0]
def _geometry(vae: Any) -> tuple[int, int, int]:
"""(ratio, floor tile, floor overlap), cached on the VAE at install."""
cached = getattr(vae, "__dict__", {}).get("_unsloth_wide_geometry")
if cached is not None:
return cached
ratio = compression_ratio(vae)
tile, overlap = floor_tiles(vae)
return ratio, tile, overlap
def _cached_axis_weights(
vae: Any,
starts: list[int],
tile: int,
length: int,
ratio: int,
torch: Any,
device: Any,
margin: int = MARGIN_LATENTS,
ramp: int = RAMP_LATENTS,
):
"""``axis_weights`` memoised per VAE (a repeat decode or encode syncs no device)."""
cache = vae.__dict__.setdefault("_unsloth_wide_weights", {}) if hasattr(vae, "__dict__") else {}
key = (tuple(starts), int(tile), int(length), int(ratio), str(device), int(margin), int(ramp))
hit = cache.get(key)
if hit is None:
if len(cache) >= 64:
cache.clear()
hit = cache[key] = axis_weights(starts, tile, length, ratio, torch, device, margin, ramp)
return hit
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, -(-(length + (count - 1) * overlap) // count))
return side if side < length else None
def _stock_span(length: int, tile: int, overlap: int) -> int:
"""Latents diffusers' stock loop decodes along one side: a tile every ``tile - overlap``, the last cut short."""
if length <= tile:
return length
return sum(min(tile, length - s) for s in range(0, length, tile - overlap))
def _large_stock_sides(length: int, tile: int, overlap: int) -> list[int]:
"""Per tile count, the smallest covering side and the widest decoding no more latents than the stock loop."""
if length <= tile:
return [length]
span = _stock_span(length, tile, overlap)
out = {length}
for n in range(2, len(tile_starts(length, tile, overlap)) + 1):
low = _axis_tiles(length, n, TILE_LATENTS, overlap)
if low is None:
continue
out.add(low)
for side in range(min(span // n, length - 1), low, -1):
if len(tile_starts(length, side, overlap)) * side <= span:
out.add(side)
break
return sorted(out)
def choose_tiles(
height: int,
width: int,
max_area: Optional[int],
tile: int = TILE_LATENTS,
overlap: int = OVERLAP_LATENTS,
stock_tile: int = 0,
) -> tuple[int, int]:
"""Tile (height, width) in latents within ``max_area`` (at least the floor tile). Stock tiles under the floor:
fewest decoded latents. Stock tile == floor (AutoencoderKL, FLUX.2 edge sliver): fewest calls, then largest
tile, never decoding more latents per side than stock (1600 px: two 120-latent tiles, not 128 + 104 + 8)."""
floor = (min(tile, height), min(tile, width))
if max_area is None or max_area <= floor[0] * floor[1]:
max_area = floor[0] * floor[1]
if stock_tile >= tile > TILE_LATENTS:
best, best_key = None, None
for th in _large_stock_sides(height, tile, overlap):
for tw in _large_stock_sides(width, tile, overlap):
if th * tw > max_area:
continue
key = (
len(tile_starts(height, th, overlap)) * len(tile_starts(width, tw, overlap)),
-th * tw,
)
if best_key is None or key < best_key:
best, best_key = (th, tw), key
if best is not None:
return best
side_min = min(tile, TILE_LATENTS)
best, best_cost = floor, None
sides_h = [
_axis_tiles(height, n, side_min, overlap)
for n in range(1, len(tile_starts(height, tile, overlap)) + 1)
]
sides_w = [
_axis_tiles(width, n, side_min, 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, 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
def _free_mib(
vae: Any,
z: Any,
cached: bool = True,
) -> Optional[tuple[float, float]]:
"""(free MiB after the fp32 output accumulator, decoder bytes per param / 2); None off CUDA."""
import torch
from .diffusion_memory import cuda_reusable_cache_bytes, user_budget_reserve_bytes
if getattr(z, "device", None) is None or z.device.type != "cuda":
return None
free, total = torch.cuda.mem_get_info(z.device)
if cached:
free += cuda_reusable_cache_bytes(z.device)
free -= user_budget_reserve_bytes(z.device, total)
ratio = _geometry(vae)[0]
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()
return (free - out_bytes) / 2**20, elem / 2
def host_budget_disabled() -> bool:
return (os.environ.get(HOST_BUDGET_ENV) or "").strip().lower() in ("0", "off", "false", "no")
def _host_free_mib(vae: Any, z: Any) -> Optional[tuple[float, float]]:
"""``_free_mib`` for a CPU / MPS decode: the planner's safe budget of the live reading (MPS: available RAM and
Metal's working set less what Metal holds; CPU: available RAM; each less the planner reserve), after the fp32
output accumulator. None elsewhere, under the kill switch, or with no reading."""
kind = getattr(getattr(z, "device", None), "type", None)
if kind not in ("cpu", "mps") or host_budget_disabled():
return None
from .diffusion_memory import (
DeviceMemory,
_available_system_memory_mib,
_host_ram_capacity_mib,
_safe_device_budget_mib,
_windows_commit_headroom_mib,
snapshot_device_memory,
)
if kind == "cpu":
# An enforcing cgroup kills the process past its limit (no OOM to retry on), and Windows fails on commit.
free = _available_system_memory_mib()
commit = _windows_commit_headroom_mib()
if free is not None and commit is not None:
free = min(free, commit)
memory = DeviceMemory("cpu", "cpu", "system_memory", free, _host_ram_capacity_mib())
else:
memory = snapshot_device_memory(types.SimpleNamespace(device = kind, backend = kind))
budget = _safe_device_budget_mib(memory)
if budget is None:
return None
ratio = _geometry(vae)[0]
frames = z.shape[2] if z.dim() == 5 else 1
out_bytes = 4 * 4 * z.shape[0] * frames * z.shape[-2] * z.shape[-1] * ratio * ratio
elem = next(vae.decoder.parameters()).element_size()
return budget - out_bytes / 2**20, elem / 2
def _fused(vae: Any) -> bool:
return (
bool(getattr(vae, "_unsloth_vae_fused_installed", 0))
and not getattr(vae, "_unsloth_vae_fused_failed", False)
and not getattr(vae, "_unsloth_vae_fused_structural", False)
)
def _strips(vae: Any) -> bool:
"""The fused decode runs in row strips (diffusion_vae_strips)."""
if not _fused(vae) or type(vae).__name__ not in DECODE_STRIPS_MIB_PER_LATENT_BY_CLASS:
return False
try:
from .diffusion_vae_strips import engaged
return engaged(vae)
except Exception: # noqa: BLE001
return False
def strips_decode_mib(vae: Any, z: Any, height: int, width: int) -> Optional[float]:
"""16-bit peak MiB of the strip decode of a (height, width) latent tile, or None when that decode would not take
the strip path (not engaged, fp32, or a tile small enough that its largest pass fits in one strip)."""
try:
if not _strips(vae) or next(vae.decoder.parameters()).element_size() != 2:
return None
from .diffusion_vae_strips import largest_pass_elems, strip_elems
strip = strip_elems(z.device)
if largest_pass_elems(vae.decoder, height, width) < 2 * strip:
return None
slope = DECODE_STRIPS_MIB_PER_LATENT_BY_CLASS[type(vae).__name__]
return slope * int(height) * int(width) + 4 * strip * 2 / 2**20
except Exception: # noqa: BLE001
return None
def _strips_tile_area(vae: Any, z: Any, budget_mib: float) -> Optional[int]:
"""Largest square-ish tile area the strip decode fits in ``budget_mib``, else None."""
try:
if not _strips(vae) or next(vae.decoder.parameters()).element_size() != 2:
return None
from .diffusion_vae_strips import strip_elems
const = 4 * strip_elems(z.device) * 2 / 2**20
area = int((budget_mib - const) / DECODE_STRIPS_MIB_PER_LATENT_BY_CLASS[type(vae).__name__])
side = int(area**0.5)
return area if area > 0 and strips_decode_mib(vae, z, side, side) is not None else None
except Exception: # noqa: BLE001
return None
def decode_platform_cap(vae: Any, z: Any) -> Optional[int]:
"""The decode tile area (latents) a platform pins regardless of free memory, else None."""
# CUDA-calibrated coefficients under-predict Qwen-Image-2.1 decode on ROCm (40x40, 64x32 and 96x56 OOM at
# 17/19 GiB limits): start at the tested 32x32 floor rather than retrying an oversized tile on every image.
import torch
if (
getattr(getattr(z, "device", None), "type", None) == "cuda"
and is_rocm_torch(torch)
and type(vae).__name__ == "AutoencoderKLQwenImage21"
):
return TILE_LATENTS**2
return None
def decode_tile_budget(vae: Any, z: Any) -> Optional[int]:
"""Largest decode tile area (latents) that fits ``FREE_FRACTION`` of the free VRAM now (CPU / MPS: of the safe
host budget, ``UNSLOTH_DIFFUSION_VAE_HOST_BUDGET=0`` = None); None on other devices or with no reading."""
raw = (os.environ.get(MAX_TILE_ENV) or "").strip()
if raw.isdigit() and int(raw) > 0:
return int(raw) ** 2
cap = decode_platform_cap(vae, z)
if cap is not None:
return cap
try:
_, tile, _ = _geometry(vae)
# Stock tile == floor: grow only into device-free memory; decoding out of the allocator cache stalled on
# flushes (FLUX.1 1600 px, 8 GB tier: 0.21 s vs stock 0.08).
stock_tile = vae.__dict__.get("_unsloth_wide_stock_tile") or (stock_tiles(vae) or (0, 0))[0]
large_stock = stock_tile >= tile > TILE_LATENTS
free = _free_mib(vae, z, cached = not large_stock)
if free is None:
# CPU / MPS: one pool, nothing cached to stall on, so the stock-tile rule above does not apply.
free = _host_free_mib(vae, z)
if free is None:
return None
mib, scale = free
per_latent = (
decode_mib_per_latent(_geometry(vae)[0], _fused(vae), type(vae).__name__) * scale
)
area = max(0, int(FREE_FRACTION * mib / per_latent))
strips = _strips_tile_area(vae, z, FREE_FRACTION * mib)
return max(area, strips) if strips is not None else area
except Exception: # noqa: BLE001 - unknown budget: the 32-latent tiles the planner budgeted
return None
def floor_shortfall(vae: Any, z: Any) -> Optional[str]:
"""Why even the floor tile cannot fit the free VRAM now, else None (also for unknown memory or an explicit
max tile). Only VAEs whose stock tile is under the floor can fall short."""
if (os.environ.get(MAX_TILE_ENV) or "").strip():
return None
try:
free = _free_mib(vae, z)
if free is None:
return None
mib, scale = free
ratio, tile, _ = _geometry(vae)
stock = vae.__dict__.get("_unsloth_wide_stock_tile") or (stock_tiles(vae) or (0, 0))[0]
if stock >= tile:
return None
area = min(tile, z.shape[-2]) * min(tile, z.shape[-1])
need = area * decode_mib_per_latent(ratio, _fused(vae), type(vae).__name__) * scale
except Exception: # noqa: BLE001
return None
if need <= mib:
return None
return (
f"a {tile}-latent floor tile needs about {need:.0f} MiB and {max(0.0, mib):.0f} MiB is free"
)
def tiled_decode(
vae: Any,
z: Any,
return_dict: bool = True,
max_area: Any = "auto",
) -> Any:
"""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[-2], z.shape[-1]
ratio, tile, overlap = _geometry(vae)
if max_area == "auto":
max_area = decode_tile_budget(vae, z)
stock_tile = vae.__dict__.get("_unsloth_wide_stock_tile") or (stock_tiles(vae) or (0, 0))[0]
th, tw = choose_tiles(height, width, max_area, tile, overlap, stock_tile)
vae._unsloth_last_decode_tile = (th, tw, max_area)
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:
wy = _cached_axis_weights(vae, hs, th, height, ratio, torch, z.device)
wx = _cached_axis_weights(vae, 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[:-2], 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[-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)
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 = _cached_axis_weights(vae, hs, tile, height, 1, torch, x.device, margin, ramp)
wx = _cached_axis_weights(vae, 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 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__ in KEEP_STOCK:
return False
config = getattr(vae, "config", 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
if stock_tiles(vae) is None:
return False
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 _is_oom(exc: BaseException) -> bool:
try:
import torch
oom = getattr(torch, "OutOfMemoryError", None) or getattr(
torch.cuda, "OutOfMemoryError", None
)
if oom is not None and isinstance(exc, oom):
return True
except Exception: # noqa: BLE001
pass
return isinstance(exc, RuntimeError) and "out of memory" in str(exc).lower()
def _release_cache(z: Any) -> None:
try:
import torch
if getattr(z, "device", None) is not None and z.device.type == "cuda":
torch.cuda.empty_cache()
except Exception: # noqa: BLE001
pass
def _clear_partial(vae: Any, z: Any) -> None:
clear_partial_decode(vae, z)
def _log_stock_fallback(vae: Any, reason: str) -> None:
logger = vae.__dict__.get("_unsloth_wide_logger")
seen = vae.__dict__.setdefault("_unsloth_wide_fallback_logged", set())
kind = reason.split(" ", 3)[:3]
key = " ".join(kind)
msg = "diffusion.vae_tiling: %s decodes in its stock tiles (seams possible): %s"
if logger is None:
return
if key in seen:
logger.debug(msg, type(vae).__name__, reason)
else:
seen.add(key)
logger.warning(msg, type(vae).__name__, reason)
def install(vae: Any, logger: Any = None) -> bool:
"""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):
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)
geometry = stock_tiles(vae)
ratio = compression_ratio(vae)
def _stock(z: Any, return_dict: bool) -> Any:
fast = vae.__dict__.get("_unsloth_wide_stock_decode")
return (fast or stock)(z, return_dict = return_dict)
def _tiled_decode(
self: Any,
z: Any,
return_dict: bool = True,
) -> Any:
if wide_tiles_disabled() or stock_layout_ok(geometry, z.shape[-2], z.shape[-1]):
return _stock(z, return_dict)
# Never trade an OOM for quality: floor tile cannot fit (or OOMs) -> the smaller stock tiles. Before
# settling for them, the OOM retry frees the card (rest of the pipeline off it) and the wide tiles go again.
for _round in range(2):
reason = floor_shortfall(self, z)
if reason is None:
for max_area in ("auto", 0):
try:
return tiled_decode(self, z, return_dict = return_dict, max_area = max_area)
except Exception as exc: # noqa: BLE001
if not _is_oom(exc):
raise
reason = f"the wide tiles ran out of memory ({type(exc).__name__})"
tried = (self.__dict__.get("_unsloth_last_decode_tile") or (0, 0))[:2]
_clear_partial(self, z)
ratio, tile, _ = _geometry(self)
if tuple(tried) == (min(tile, z.shape[-2]), min(tile, z.shape[-1])):
break
if _round or not oom_free_first(self, z):
break
_log_stock_fallback(self, reason)
_clear_partial(self, z)
return _stock(z, return_dict)
def _tiled_encode(self: Any, x: Any) -> Any:
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._unsloth_wide_geometry = (ratio, *floor_tiles(vae))
vae._unsloth_wide_stock_tile = geometry[0]
vae._unsloth_wide_logger = logger
vae.tiled_decode = types.MethodType(_tiled_decode, vae)
if _wide_encode(vae):
vae._unsloth_wide_tiles_own_encode = own_encode
vae.tiled_encode = types.MethodType(_tiled_encode, vae)
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 (%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__,
ratio,
geometry[0],
geometry[1],
tile,
overlap,
)
return True
def uninstall(vae: Any) -> None:
if not getattr(vae, "_unsloth_wide_tiles", False):
return
fast = vae.__dict__.pop("_unsloth_wide_stock_decode", None)
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",
"_unsloth_wide_geometry",
"_unsloth_wide_weights",
"_unsloth_wide_logger",
"_unsloth_wide_fallback_logged",
"_unsloth_wide_stock_tile",
):
vae.__dict__.pop(name, None)
if fast is not None and "tiled_decode" not in vae.__dict__:
vae.tiled_decode = fast
vae._unsloth_wide_tiles = False