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.

fix(studio): pad VAE downsample shortcuts by concatenation on MPS (#13028)

Long Yixing92cbd1d5ea8a
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index e9217f65c28..a7bf29e4ea4 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -92,6 +92,7 @@ from .diffusion_device import (
apply_diffusion_device_ordinal,
diffusion_device_scope,
diffusion_device_target_from_torch_device,
+ install_frame_pad_fix,
pin_cuda_ordinal,
placed_cuda_ordinal,
resolve_diffusion_device_target,
@@ -7827,6 +7828,7 @@ class DiffusionBackend:
install_wide_vae_tiles(getattr(pipe, "vae", None), logger)
except Exception as exc: # noqa: BLE001 - keep the stock tiled decode
logger.warning("diffusion.vae_tiling: not installed: %s", exc)
+ install_frame_pad_fix(pipe, target, logger = logger)
# Before the speed optims so their decode compile lands inside the non-finite check; `off` keeps fp32.
vae_fp16 = str(
speed_mode or ""
diff --git a/studio/backend/core/inference/diffusion_device.py b/studio/backend/core/inference/diffusion_device.py
index 001463830e5..c1c0d2e7c1c 100644
--- a/studio/backend/core/inference/diffusion_device.py
+++ b/studio/backend/core/inference/diffusion_device.py
@@ -88,6 +88,56 @@ def force_float32_rope(
return changed
+# Downsample shortcuts that zero-pad only the frame axis in front, to a multiple of ``factor_t``.
+_FRAME_PAD_CLASSES = frozenset({"QwenImage21AvgDown3D", "AvgDown3D"})
+
+
+def _prepend_zero_frames(module: Any, args: tuple) -> Optional[tuple]:
+ x = args[0]
+ pad_t = -x.shape[2] % module.factor_t
+ if not pad_t:
+ return None
+ import torch
+
+ zeros = x.new_zeros((*x.shape[:2], pad_t, *x.shape[3:]))
+ return (torch.cat([zeros, x], dim = 2), *args[1:])
+
+
+def install_frame_pad_fix(
+ pipe: Any,
+ target: DiffusionDeviceTarget,
+ *,
+ logger: Any = None,
+) -> int:
+ """Pad the VAE downsample shortcuts' frame axis by concatenation on Metal; returns the modules patched.
+
+ ``F.pad`` on MPS silently returns wrong data (all zeros for a front pad) for a 5-D tensor padded
+ on the frame axis alone once a frame holds 65536 values, i.e. from a 256x256 feature map up
+ (torch 2.10 through 2.14). The shortcuts pad a single frame exactly that way; prepending the zero
+ frames leaves their own pad empty.
+ """
+ if target.device != "mps":
+ return 0
+ patched = 0
+ for component in getattr(pipe, "components", {}).values() or ():
+ modules = getattr(component, "modules", None)
+ if not callable(modules):
+ continue
+ for module in modules():
+ if type(module).__name__ not in _FRAME_PAD_CLASSES:
+ continue
+ if getattr(module, "_unsloth_frame_pad_fix", False):
+ continue
+ module.register_forward_pre_hook(_prepend_zero_frames)
+ module._unsloth_frame_pad_fix = True
+ patched += 1
+ if patched and logger is not None:
+ logger.info(
+ "diffusion.vae_frame_pad: %d module(s) pad by concatenation (MPS pad defect)", patched
+ )
+ return patched
+
+
# Fraction of the device's recommended working set above which a decode starts synchronising.
DECODE_SYNC_FRACTION = 0.85
diff --git a/studio/backend/tests/test_diffusion_device.py b/studio/backend/tests/test_diffusion_device.py
index 8e74ef47681..4af4b1e574b 100644
--- a/studio/backend/tests/test_diffusion_device.py
+++ b/studio/backend/tests/test_diffusion_device.py
@@ -463,6 +463,58 @@ def test_the_video_loader_demotes_rope():
)
+# ── Frame padding by concatenation on Metal ───────────────────────────
+
+
+def _frame_pad_pipe(factor_t: int, name: str = "AvgDown3D"):
+ torch = pytest.importorskip("torch")
+
+ class Shortcut(torch.nn.Module):
+ """The diffusers shortcut's padding, recording how much of it ``F.pad`` was left to do."""
+
+ def __init__(self):
+ super().__init__()
+ self.factor_t = factor_t
+ self.padded = []
+
+ def forward(self, x):
+ pad_t = (self.factor_t - x.shape[2] % self.factor_t) % self.factor_t
+ self.padded.append(pad_t)
+ return torch.nn.functional.pad(x, (0, 0, 0, 0, pad_t, 0))
+
+ Shortcut.__name__ = name
+ shortcut = Shortcut()
+ return torch, shortcut, _Pipe(vae = torch.nn.Sequential(shortcut), scheduler = object())
+
+
[email protected]("name", ["AvgDown3D", "QwenImage21AvgDown3D"])
[email protected]("factor_t, frames", [(2, 1), (2, 3), (4, 5), (2, 4)])
+def test_frame_pad_fix_pads_by_concatenation_on_mps(factor_t, frames, name):
+ torch, shortcut, pipe = _frame_pad_pipe(factor_t, name)
+ x = torch.arange(2 * 3 * frames * 2 * 2, dtype = torch.float32).reshape(2, 3, frames, 2, 2)
+ expected = shortcut(x)
+ assert dd.install_frame_pad_fix(pipe, _mps_target()) == 1
+ assert dd.install_frame_pad_fix(pipe, _mps_target()) == 0 # one hook, however often a load runs
+ shortcut.padded.clear()
+ assert torch.equal(shortcut(x), expected)
+ assert shortcut.padded == [0] # nothing left for the pad Metal gets wrong
+
+
+def test_frame_pad_fix_is_metal_only():
+ torch, shortcut, pipe = _frame_pad_pipe(2)
+ assert dd.install_frame_pad_fix(pipe, _cuda_target()) == 0
+ shortcut(torch.zeros(1, 1, 1, 2, 2))
+ assert shortcut.padded == [1]
+
+
+def test_the_image_loader_installs_the_frame_pad_fix():
+ from pathlib import Path
+ src = (Path(__file__).resolve().parent.parent / "core/inference/diffusion.py").read_text(
+ encoding = "utf-8"
+ )
+ assert "install_frame_pad_fix(pipe, target, logger = logger)" in src
+
+
# ── Pressure-gated decoder sync ───────────────────────────────────────