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 MiniMax-H3 VAE: stitch batched decoder tiles into the frame as they arrive (#17097)

Daniel Han162990fe9f53
diff --git a/studio/backend/core/inference/video_minimax_h3_vae.py b/studio/backend/core/inference/video_minimax_h3_vae.py
index 3a7284a01b5..cb3bec90063 100644
--- a/studio/backend/core/inference/video_minimax_h3_vae.py
+++ b/studio/backend/core/inference/video_minimax_h3_vae.py
@@ -20,6 +20,10 @@ H3_VAE_FAST_ENV = "UNSLOTH_H3_VAE_FAST"
H3_VAE_INT8_ENV = "UNSLOTH_H3_VAE_INT8"
H3_VAE_TILE_BATCH_ENV = "UNSLOTH_H3_VAE_TILE_BATCH"
H3_VAE_INT8_FUSED_ENV = "UNSLOTH_H3_VAE_INT8_FUSED"
+# "0": batched tile decode keeps every tile for diffusers' _stitch_tiles.
+H3_VAE_STREAM_STITCH_ENV = "UNSLOTH_H3_VAE_STREAM_STITCH"
+# sha256[:16] of the mirrored AutoencoderKLMiniMaxH3._stitch_tiles source (0.42.1).
+_STITCH_TILES_SHA = frozenset({"ae481626afa30528"})
FP16_ACCUM_DISABLE_ENV = "UNSLOTH_DISABLE_FP16_ACCUM"
LEVER_FUSED_ENCODER = "fused_encoder"
@@ -1047,6 +1051,10 @@ def _batched_decode_clip(self: Any, z: Any) -> Any:
]
per = z.shape[0]
batch = _tile_batch_size(z)
+ cols = len(x_indices)
+ stitch = None
+ if _stream_stitch(self) and all(o > 0 for o in (*y_overlaps, *x_overlaps)):
+ stitch = _TileStitcher(self, len(y_indices), cols, y_overlaps, x_overlaps)
decoded: list = []
start = 0
while start < len(tiles):
@@ -1062,13 +1070,107 @@ def _batched_decode_clip(self: Any, z: Any) -> Any:
torch.cuda.empty_cache()
batch = 1
continue
- decoded.extend(out.split(per) if len(group) > 1 else [out])
+ parts = out.split(per) if len(group) > 1 else [out]
+ del out
+ if stitch is None:
+ decoded.extend(parts)
+ else:
+ for k in range(len(parts)):
+ stitch.add(start + k, parts[k])
+ del parts # a live view pins its whole decoder batch
start += len(group)
- cols = len(x_indices)
+ if stitch is not None:
+ return stitch.result()
rows = [decoded[r * cols : (r + 1) * cols] for r in range(len(y_indices))]
return self._stitch_tiles(rows, y_overlaps, x_overlaps)
+def _stream_stitch(vae: Any) -> bool:
+ if _env(H3_VAE_STREAM_STITCH_ENV) in _FALSE:
+ return False
+ cls = type(vae)
+ known = _STITCH_KNOWN.get(cls)
+ if known is None:
+ import hashlib
+ import inspect
+
+ try:
+ sha = hashlib.sha256(inspect.getsource(cls._stitch_tiles).encode()).hexdigest()[:16]
+ except Exception: # noqa: BLE001
+ sha = None
+ known = _STITCH_KNOWN[cls] = sha in _STITCH_TILES_SHA
+ return known and "_stitch_tiles" not in getattr(vae, "__dict__", {})
+
+
+_STITCH_KNOWN: dict = {}
+
+
+class _TileStitcher:
+ """``_stitch_tiles`` one tile at a time: keeps only the ORIGINAL neighbour strips the stock blend reads (copies,
+ so each decoder batch is freed), fills one row buffer at a time and joins the rows at the end; bit-identical."""
+
+ __slots__ = (
+ "vae",
+ "rows",
+ "cols",
+ "y_overlaps",
+ "x_overlaps",
+ "below",
+ "left",
+ "done",
+ "row",
+ "x0",
+ )
+
+ def __init__(self, vae: Any, rows: int, cols: int, y_overlaps: list, x_overlaps: list) -> None:
+ self.vae, self.rows, self.cols = vae, rows, cols
+ self.y_overlaps, self.x_overlaps = y_overlaps, x_overlaps
+ self.below: list = [None] * cols
+ self.left = None
+ self.done: list = []
+ self.row = None
+ self.x0 = 0
+
+ def add(self, index: int, tile: Any) -> None:
+ import torch
+
+ i, j = divmod(index, self.cols)
+ out = tile
+ if i > 0:
+ out = self.vae._blend(self.below[j], out, self.y_overlaps[i - 1], dim = -2)
+ if j > 0:
+ out = self.vae._blend(self.left, out, self.x_overlaps[j - 1], dim = -1)
+ if i < self.rows - 1:
+ ov = self.y_overlaps[i]
+ self.below[j] = tile[..., -min(tile.shape[-2], ov) :, :].clone()
+ out = out[..., :-ov, :]
+ else:
+ self.below[j] = None
+ if j < self.cols - 1:
+ ov = self.x_overlaps[j]
+ self.left = tile[..., :, -min(tile.shape[-1], ov) :].clone()
+ out = out[..., :, :-ov]
+ else:
+ self.left = None
+ if j == 0:
+ width = sum(
+ tile.shape[-1] - self.x_overlaps[c] if c < self.cols - 1 else tile.shape[-1]
+ for c in range(self.cols)
+ )
+ self.row = torch.empty((*out.shape[:-1], width), dtype = out.dtype, device = out.device)
+ self.x0 = 0
+ self.row[..., self.x0 : self.x0 + out.shape[-1]].copy_(out)
+ self.x0 += out.shape[-1]
+ if j == self.cols - 1:
+ self.done.append(self.row)
+ self.row = None
+
+ def result(self) -> Any:
+ import torch
+ rows, self.done = self.done, []
+ return rows[0] if len(rows) == 1 else torch.cat(rows, dim = -2)
+
+
def _install_tile_batch(vae: Any) -> bool:
if not all(
hasattr(vae, n)
diff --git a/studio/backend/tests/test_video_minimax_h3_vae.py b/studio/backend/tests/test_video_minimax_h3_vae.py
index baf806cb6ce..6a5dedffd1d 100644
--- a/studio/backend/tests/test_video_minimax_h3_vae.py
+++ b/studio/backend/tests/test_video_minimax_h3_vae.py
@@ -419,6 +419,63 @@ def test_tile_batching_matches_the_stock_tile_loop(monkeypatch):
torch.testing.assert_close(fast._decode_clip(z), ref, rtol = 1e-5, atol = 1e-5)
[email protected]("batch", ["1", "2", "3"])
[email protected]("shape", [(6, 9), (4, 4), (10, 5), (3, 12)])
+def test_streamed_stitch_equals_the_stock_stitch_bit_for_bit(monkeypatch, batch, shape):
+ vae = _tiny_vae()
+ assert H._install_tile_batch(vae)
+ monkeypatch.setenv(H.H3_VAE_TILE_BATCH_ENV, batch)
+ z = torch.randn(1, 8, 3, *shape, generator = torch.Generator().manual_seed(5))
+ with torch.no_grad():
+ monkeypatch.setenv(H.H3_VAE_STREAM_STITCH_ENV, "0")
+ ref = vae._decode_clip(z)
+ monkeypatch.delenv(H.H3_VAE_STREAM_STITCH_ENV)
+ got = vae._decode_clip(z)
+ assert got.dtype == ref.dtype and got.shape == ref.shape and got.is_contiguous()
+ assert torch.equal(got, ref)
+
+
+def test_streamed_stitch_releases_each_decoder_batch(monkeypatch):
+ from torch.multiprocessing.reductions import StorageWeakRef
+
+ vae = _tiny_vae()
+ assert H._install_tile_batch(vae)
+ monkeypatch.setenv(H.H3_VAE_TILE_BATCH_ENV, "2")
+ stock_decoder = vae.decoder.forward
+
+ def run(stream):
+ outs, alive = [], []
+
+ def decoder(x):
+ alive.append(sum(not r.expired() for r in outs))
+ out = stock_decoder(x)
+ outs.append(StorageWeakRef(out.untyped_storage()))
+ return out
+
+ monkeypatch.setattr(vae.decoder, "forward", decoder)
+ if stream:
+ monkeypatch.delenv(H.H3_VAE_STREAM_STITCH_ENV, raising = False)
+ else:
+ monkeypatch.setenv(H.H3_VAE_STREAM_STITCH_ENV, "0")
+ with torch.no_grad():
+ vae._decode_clip(torch.randn(1, 8, 3, 10, 9))
+ return alive
+
+ assert run(stream = False)[-1] > 0, "stock keeps every decoded batch until the stitch"
+ assert set(run(stream = True)) == {0}
+
+
+def test_streamed_stitch_keeps_stock_for_an_unknown_stitch(monkeypatch):
+ vae = _tiny_vae()
+ assert H._install_tile_batch(vae)
+ calls = []
+ stock = vae._stitch_tiles
+ monkeypatch.setattr(vae, "_stitch_tiles", lambda *a: calls.append(1) or stock(*a))
+ with torch.no_grad():
+ vae._decode_clip(torch.randn(1, 8, 3, 6, 9))
+ assert calls == [1]
+
+
def test_int8_decoder_replaces_block_linears_and_stays_close():
vae = _tiny_vae()
fast = copy.deepcopy(vae)