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: CI guard that fails when any family's VAE decodes in tiles below the seam floor (#12766)

Daniel Hanb8b752543cde
diff --git a/.github/workflows/studio-vae-seam-guard.yml b/.github/workflows/studio-vae-seam-guard.yml
new file mode 100644
index 00000000000..eb038eecf7a
--- /dev/null
+++ b/.github/workflows/studio-vae-seam-guard.yml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# Runs test_vae_tile_geometry.py on CPU with the pinned diffusers, which Backend CI does not install
+# (there the guard would only skip).
+
+name: Studio VAE seam guard
+
+on:
+ pull_request:
+ paths:
+ - 'studio/backend/core/inference/**'
+ - 'studio/backend/requirements/diffusers-*.txt'
+ - 'studio/backend/requirements/studio.txt'
+ - 'studio/backend/tests/test_vae_tile_geometry.py'
+ - 'studio/backend/tests/fixtures/vae_tile_configs.json'
+ - '.github/workflows/studio-vae-seam-guard.yml'
+ push:
+ branches: [main]
+ paths:
+ - 'studio/backend/core/inference/**'
+ - 'studio/backend/requirements/diffusers-*.txt'
+ - 'studio/backend/requirements/studio.txt'
+ - 'studio/backend/tests/test_vae_tile_geometry.py'
+ - 'studio/backend/tests/fixtures/vae_tile_configs.json'
+ - '.github/workflows/studio-vae-seam-guard.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ # Unique per commit on main, so a merge burst cannot cancel a main run; superseded PR pushes are cancelled.
+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+ seam-guard:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+
+ - name: Install dependencies (CPU only)
+ run: |
+ python -m pip install --upgrade pip
+ pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
+ 'torch>=2.4,<2.11'
+ pip install -r studio/backend/requirements/studio.txt
+ # As Studio installs it: the release pin, then the main commit (Qwen-Image-2.1) on top.
+ pip install -r studio/backend/requirements/diffusers-pin.txt
+ pip install -r studio/backend/requirements/diffusers-main.txt
+ pip install pytest pytest-timeout
+
+ - name: Seam guard
+ working-directory: studio/backend
+ run: python -m pytest tests/test_vae_tile_geometry.py -q -rxXs --tb=short --timeout=600
diff --git a/studio/backend/tests/fixtures/vae_tile_configs.json b/studio/backend/tests/fixtures/vae_tile_configs.json
new file mode 100644
index 00000000000..0dde930c257
--- /dev/null
+++ b/studio/backend/tests/fixtures/vae_tile_configs.json
@@ -0,0 +1,1200 @@
+{
+ "_comment": "vae/config.json of every Studio image / video family's base repo, read by test_vae_tile_geometry.py (no weights). Refresh an entry when a family's base repo changes; keep the revision it was read at.",
+ "families": {
+ "flux.1": {
+ "kind": "image",
+ "repo": "unsloth/FLUX.1-schnell",
+ "revision": "9df3faa7ae3b6ddf0b2b69bb78616372897cc65c",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.30.0.dev0",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 16,
+ "latents_mean": null,
+ "latents_std": null,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.3611,
+ "shift_factor": 0.1159,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": false,
+ "use_quant_conv": false
+ }
+ },
+ "flux.2-klein": {
+ "kind": "image",
+ "repo": "black-forest-labs/FLUX.2-klein-4B",
+ "revision": "e7b7dc27f91deacad38e78976d1f2b499d76a294",
+ "config": {
+ "_class_name": "AutoencoderKLFlux2",
+ "_diffusers_version": "0.37.0.dev0",
+ "_name_or_path": "black-forest-labs/FLUX.2-dev",
+ "act_fn": "silu",
+ "batch_norm_eps": 0.0001,
+ "batch_norm_momentum": 0.1,
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "patch_size": [
+ 2,
+ 2
+ ],
+ "sample_size": 1024,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": true,
+ "use_quant_conv": true
+ }
+ },
+ "flux.2-dev": {
+ "kind": "image",
+ "repo": "unsloth/FLUX.2-dev",
+ "revision": "351bbb0ebab35d4dfec0445f67bcec34b383ddf9",
+ "config": {
+ "_class_name": "AutoencoderKLFlux2",
+ "_diffusers_version": "0.36.0.dev0",
+ "act_fn": "silu",
+ "batch_norm_eps": 0.0001,
+ "batch_norm_momentum": 0.1,
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "patch_size": [
+ 2,
+ 2
+ ],
+ "sample_size": 1024,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": true,
+ "use_quant_conv": true
+ }
+ },
+ "flux.1-kontext": {
+ "kind": "image",
+ "repo": "unsloth/FLUX.1-Kontext-dev",
+ "revision": "ed585f929575da3142d1cdd7a49ef25db6f12161",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.34.0.dev0",
+ "_name_or_path": "/raid/.cache/huggingface/models--black-forest-labs--FLUX.1-dev/snapshots/0ef5fff789c832c5c7f4e127f94c8b54bbcced44/vae",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 16,
+ "latents_mean": null,
+ "latents_std": null,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.3611,
+ "shift_factor": 0.1159,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": false,
+ "use_quant_conv": false
+ }
+ },
+ "qwen-image-edit": {
+ "kind": "image",
+ "repo": "Qwen/Qwen-Image-Edit-2511",
+ "revision": "6f3ccc0b56e431dc6a0c2b2039706d7d26f22cb9",
+ "config": {
+ "_class_name": "AutoencoderKLQwenImage",
+ "_diffusers_version": "0.36.0.dev0",
+ "attn_scales": [],
+ "base_dim": 96,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 4
+ ],
+ "dropout": 0.0,
+ "latents_mean": [
+ -0.7571,
+ -0.7089,
+ -0.9113,
+ 0.1075,
+ -0.1745,
+ 0.9653,
+ -0.1517,
+ 1.5508,
+ 0.4134,
+ -0.0715,
+ 0.5517,
+ -0.3632,
+ -0.1922,
+ -0.9497,
+ 0.2503,
+ -0.2921
+ ],
+ "latents_std": [
+ 2.8184,
+ 1.4541,
+ 2.3275,
+ 2.6558,
+ 1.2196,
+ 1.7708,
+ 2.6052,
+ 2.0743,
+ 3.2687,
+ 2.1526,
+ 2.8652,
+ 1.5579,
+ 1.6382,
+ 1.1253,
+ 2.8251,
+ 1.916
+ ],
+ "num_res_blocks": 2,
+ "temperal_downsample": [
+ false,
+ true,
+ true
+ ],
+ "z_dim": 16
+ }
+ },
+ "qwen-image": {
+ "kind": "image",
+ "repo": "Qwen/Qwen-Image",
+ "revision": "75e0b4be04f60ec59a75f475837eced720f823b6",
+ "config": {
+ "_class_name": "AutoencoderKLQwenImage",
+ "_diffusers_version": "0.34.0.dev0",
+ "attn_scales": [],
+ "base_dim": 96,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 4
+ ],
+ "dropout": 0.0,
+ "latents_mean": [
+ -0.7571,
+ -0.7089,
+ -0.9113,
+ 0.1075,
+ -0.1745,
+ 0.9653,
+ -0.1517,
+ 1.5508,
+ 0.4134,
+ -0.0715,
+ 0.5517,
+ -0.3632,
+ -0.1922,
+ -0.9497,
+ 0.2503,
+ -0.2921
+ ],
+ "latents_std": [
+ 2.8184,
+ 1.4541,
+ 2.3275,
+ 2.6558,
+ 1.2196,
+ 1.7708,
+ 2.6052,
+ 2.0743,
+ 3.2687,
+ 2.1526,
+ 2.8652,
+ 1.5579,
+ 1.6382,
+ 1.1253,
+ 2.8251,
+ 1.916
+ ],
+ "num_res_blocks": 2,
+ "temperal_downsample": [
+ false,
+ true,
+ true
+ ],
+ "z_dim": 16
+ }
+ },
+ "qwen-image-2.1": {
+ "kind": "image",
+ "repo": "Qwen/Qwen-Image-2.1",
+ "revision": "d26bb61231c349cf6b7896fa83353113880e1ba3",
+ "config": {
+ "_class_name": "AutoencoderKLQwenImage21",
+ "_diffusers_version": "0.37.0.dev0",
+ "attn_scales": [],
+ "base_dim": 96,
+ "decoder_base_dim": 144,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 8,
+ 8
+ ],
+ "dropout": 0.0,
+ "in_channels": 4,
+ "is_residual": true,
+ "latents_mean": [
+ 0.5126,
+ 0.7721,
+ -0.0631,
+ 1.3506,
+ -0.7855,
+ -2.1025,
+ -0.3458,
+ 1.3722,
+ 1.8873,
+ -1.7177,
+ -0.651,
+ 0.2732,
+ 0.7562,
+ -0.6163,
+ -1.0277,
+ 3.8363,
+ 2.021,
+ 0.0472,
+ 0.932,
+ 2.0087,
+ 2.4954,
+ -0.1391,
+ -1.4249,
+ 1.8464,
+ -0.5236,
+ 1.2826,
+ 3.7046,
+ -1.3035,
+ 2.7286,
+ -1.4518,
+ -1.9036,
+ -1.9955,
+ -0.0342,
+ -1.0265,
+ -0.7636,
+ 3.0555,
+ 0.0746,
+ -3.0751,
+ -0.1076,
+ 1.7376,
+ -1.0914,
+ -1.9435,
+ -0.2784,
+ -1.368,
+ 0.4809,
+ -0.4433,
+ 0.3764,
+ 0.5729,
+ -2.0595,
+ 1.096,
+ -1.326,
+ -2.0211,
+ -5.0179,
+ 0.5275,
+ 4.0162,
+ 1.8505,
+ 0.3026,
+ 1.9373,
+ 1.4937,
+ 0.2632,
+ 0.5547,
+ -1.7121,
+ -0.1562,
+ 0.0304
+ ],
+ "latents_std": [
+ 3.2001,
+ 3.2936,
+ 3.4321,
+ 3.0091,
+ 3.1061,
+ 4.0379,
+ 4.0705,
+ 3.791,
+ 3.0785,
+ 3.65,
+ 3.9308,
+ 3.0904,
+ 2.8778,
+ 3.7675,
+ 3.732,
+ 5.0756,
+ 3.2864,
+ 4.0397,
+ 3.1317,
+ 4.0443,
+ 2.9249,
+ 3.9454,
+ 3.0988,
+ 4.2489,
+ 3.4896,
+ 3.8513,
+ 3.9323,
+ 3.4719,
+ 3.7498,
+ 4.283,
+ 3.5694,
+ 4.2467,
+ 3.9037,
+ 3.2947,
+ 5.077,
+ 3.5075,
+ 3.27,
+ 3.4767,
+ 2.8063,
+ 5.1125,
+ 3.5327,
+ 4.7833,
+ 3.1286,
+ 4.1819,
+ 3.8527,
+ 3.8312,
+ 3.5605,
+ 4.3875,
+ 3.9624,
+ 4.0168,
+ 3.5643,
+ 4.055,
+ 5.5614,
+ 4.2963,
+ 4.408,
+ 3.4959,
+ 3.8747,
+ 3.7608,
+ 3.5735,
+ 3.149,
+ 3.7662,
+ 3.6746,
+ 3.4563,
+ 3.8161
+ ],
+ "num_res_blocks": 2,
+ "out_channels": 4,
+ "patch_size": null,
+ "scale_factor_spatial": 16,
+ "scale_factor_temporal": 8,
+ "temperal_downsample": [
+ false,
+ true,
+ true,
+ true
+ ],
+ "z_dim": 64
+ }
+ },
+ "z-image": {
+ "kind": "image",
+ "repo": "Tongyi-MAI/Z-Image-Turbo",
+ "revision": "f332072aa78be7aecdf3ee76d5c247082da564a6",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.36.0.dev0",
+ "_name_or_path": "flux-dev",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 16,
+ "latents_mean": null,
+ "latents_std": null,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.3611,
+ "shift_factor": 0.1159,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": false,
+ "use_quant_conv": false
+ }
+ },
+ "krea-2": {
+ "kind": "image",
+ "repo": "unsloth/Krea-2-Turbo",
+ "revision": "2489d0f4cb200616c0b5410f96f64d8fdc611b06",
+ "config": {
+ "_class_name": "AutoencoderKLQwenImage",
+ "_diffusers_version": "0.39.0.dev0",
+ "_name_or_path": "Qwen/Qwen-Image",
+ "attn_scales": [],
+ "base_dim": 96,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 4
+ ],
+ "dropout": 0.0,
+ "input_channels": 3,
+ "latents_mean": [
+ -0.7571,
+ -0.7089,
+ -0.9113,
+ 0.1075,
+ -0.1745,
+ 0.9653,
+ -0.1517,
+ 1.5508,
+ 0.4134,
+ -0.0715,
+ 0.5517,
+ -0.3632,
+ -0.1922,
+ -0.9497,
+ 0.2503,
+ -0.2921
+ ],
+ "latents_std": [
+ 2.8184,
+ 1.4541,
+ 2.3275,
+ 2.6558,
+ 1.2196,
+ 1.7708,
+ 2.6052,
+ 2.0743,
+ 3.2687,
+ 2.1526,
+ 2.8652,
+ 1.5579,
+ 1.6382,
+ 1.1253,
+ 2.8251,
+ 1.916
+ ],
+ "num_res_blocks": 2,
+ "temperal_downsample": [
+ false,
+ true,
+ true
+ ],
+ "z_dim": 16
+ }
+ },
+ "lumina-2": {
+ "kind": "image",
+ "repo": "Alpha-VLLM/Lumina-Image-2.0",
+ "revision": "53504abd8178b30685b6c4c7a4cd181ff78b73e9",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.33.0.dev0",
+ "_name_or_path": "black-forest-labs/FLUX.1-dev",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 16,
+ "latents_mean": null,
+ "latents_std": null,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.3611,
+ "shift_factor": 0.1159,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": false,
+ "use_quant_conv": false
+ }
+ },
+ "hunyuanimage-2.1": {
+ "kind": "image",
+ "repo": "hunyuanvideo-community/HunyuanImage-2.1-Diffusers",
+ "revision": "7e7b7a177de58591aeaffca0929f4765003d7ced",
+ "config": {
+ "_class_name": "AutoencoderKLHunyuanImage",
+ "_diffusers_version": "0.36.0.dev0",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512,
+ 1024,
+ 1024
+ ],
+ "downsample_match_channel": true,
+ "in_channels": 3,
+ "latent_channels": 64,
+ "layers_per_block": 2,
+ "out_channels": 3,
+ "sample_size": 384,
+ "scaling_factor": 0.75289,
+ "spatial_compression_ratio": 32,
+ "upsample_match_channel": true
+ }
+ },
+ "hidream-i1": {
+ "kind": "image",
+ "repo": "HiDream-ai/HiDream-I1-Full",
+ "revision": "8ccbbfb270ccdae26d6bb0081df67dc81e4033bf",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.30.0.dev0",
+ "_name_or_path": "../checkpoints/flux-dev",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 16,
+ "latents_mean": null,
+ "latents_std": null,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.3611,
+ "shift_factor": 0.1159,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": false,
+ "use_quant_conv": false
+ }
+ },
+ "ideogram-4": {
+ "kind": "image",
+ "repo": "unsloth/ideogram-4-fp8",
+ "revision": "518e05e745736960acb56d8726138ffbc174f0a9",
+ "config": {
+ "_class_name": "AutoencoderKLFlux2",
+ "_diffusers_version": "0.39.0.dev0",
+ "_name_or_path": "/home/jinli/.cache/huggingface/hub/models--ideogram-ai--debug-ideogram-v4/snapshots/41af6183c9fd9b6254864b0720319ef984535bfc/vae",
+ "act_fn": "silu",
+ "batch_norm_eps": 0.0001,
+ "batch_norm_momentum": 0.1,
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "decoder_block_out_channels": null,
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "patch_size": [
+ 2,
+ 2
+ ],
+ "sample_size": 1024,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": true,
+ "use_quant_conv": true
+ }
+ },
+ "sdxl": {
+ "kind": "image",
+ "repo": "stabilityai/stable-diffusion-xl-base-1.0",
+ "revision": "462165984030d82259a11f4367a4eed129e94a7b",
+ "config": {
+ "_class_name": "AutoencoderKL",
+ "_diffusers_version": "0.20.0.dev0",
+ "_name_or_path": "../sdxl-vae/",
+ "act_fn": "silu",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 4,
+ "layers_per_block": 2,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "sample_size": 1024,
+ "scaling_factor": 0.13025,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ]
+ }
+ },
+ "minimax-h3": {
+ "kind": "video",
+ "repo": "MiniMaxAI/MiniMax-H3",
+ "revision": "42ed227ee7df40d41602854ae760620d6eb651fe",
+ "config": {
+ "_class_name": "AutoencoderKLMiniMaxH3",
+ "_diffusers_version": "0.36.0.dev0",
+ "in_channels": 3,
+ "out_channels": 3,
+ "latent_channels": 24,
+ "block_out_channels": [
+ 128,
+ 256,
+ 256,
+ 512,
+ 512,
+ 1024
+ ],
+ "layers_per_block": 2,
+ "spatial_downsample_factors": [
+ 2,
+ 2,
+ 2,
+ 2,
+ 1,
+ 1
+ ],
+ "temporal_downsample_factors": [
+ 1,
+ 2,
+ 2,
+ 1,
+ 1,
+ 1
+ ],
+ "norm_num_groups": 32,
+ "norm_eps": 1e-06,
+ "spatial_padding_mode": "reflect",
+ "decoder_num_layers": 36,
+ "decoder_num_attention_heads": 32,
+ "decoder_attention_head_dim": 64,
+ "decoder_num_register_tokens": 4,
+ "decoder_ffn_mult": 4,
+ "decoder_rope_theta": 100.0,
+ "decoder_rope_dim_ratio": 0.75,
+ "decoder_norm_eps": 1e-05,
+ "clip_length": 17,
+ "token_drop": 3,
+ "latents_mean": [
+ 0.858090341091156,
+ -0.9606591463088989,
+ 1.0661640167236328,
+ -0.5090325474739075,
+ -0.2727581858634949,
+ -1.3675414323806763,
+ -0.2553254961967468,
+ -0.26907554268836975,
+ -0.5376840829849243,
+ -0.0464097298681736,
+ 0.6657370328903198,
+ 0.19690127670764923,
+ -0.5460608005523682,
+ -0.4035342037677765,
+ -0.23683024942874908,
+ 0.25928452610969543,
+ -0.30133944749832153,
+ 0.211341992020607,
+ -1.1206848621368408,
+ 0.3581933379173279,
+ -0.04225143790245056,
+ 0.2604829967021942,
+ 0.22864092886447906,
+ 0.7056031823158264
+ ],
+ "latents_std": [
+ 1.2223774194717407,
+ 1.2767263650894165,
+ 1.6831774711608887,
+ 1.7549455165863037,
+ 1.5636216402053833,
+ 2.194143533706665,
+ 0.9653137922286987,
+ 1.0569885969161987,
+ 0.841948926448822,
+ 0.7729952931404114,
+ 1.8955937623977661,
+ 0.946841835975647,
+ 0.7996809482574463,
+ 0.44988900423049927,
+ 0.7197399735450745,
+ 0.6936293244361877,
+ 2.961095094680786,
+ 2.7694199085235596,
+ 3.0496184825897217,
+ 2.1088054180145264,
+ 3.276226282119751,
+ 3.1627357006073,
+ 2.2816812992095947,
+ 2.6127843856811523
+ ]
+ }
+ },
+ "ltx-2": {
+ "kind": "video",
+ "repo": "Lightricks/LTX-2",
+ "revision": "dfcc2108383fe1aaa0584bdf55d368a4bdadd90c",
+ "config": {
+ "_class_name": "AutoencoderKLLTX2Video",
+ "_diffusers_version": "0.37.0.dev0",
+ "block_out_channels": [
+ 256,
+ 512,
+ 1024,
+ 2048
+ ],
+ "decoder_block_out_channels": [
+ 256,
+ 512,
+ 1024
+ ],
+ "decoder_causal": false,
+ "decoder_inject_noise": [
+ false,
+ false,
+ false,
+ false
+ ],
+ "decoder_layers_per_block": [
+ 5,
+ 5,
+ 5,
+ 5
+ ],
+ "decoder_spatial_padding_mode": "reflect",
+ "decoder_spatio_temporal_scaling": [
+ true,
+ true,
+ true
+ ],
+ "down_block_types": [
+ "LTX2VideoDownBlock3D",
+ "LTX2VideoDownBlock3D",
+ "LTX2VideoDownBlock3D",
+ "LTX2VideoDownBlock3D"
+ ],
+ "downsample_type": [
+ "spatial",
+ "temporal",
+ "spatiotemporal",
+ "spatiotemporal"
+ ],
+ "encoder_causal": true,
+ "encoder_spatial_padding_mode": "zeros",
+ "in_channels": 3,
+ "latent_channels": 128,
+ "layers_per_block": [
+ 4,
+ 6,
+ 6,
+ 2,
+ 2
+ ],
+ "out_channels": 3,
+ "patch_size": 4,
+ "patch_size_t": 1,
+ "resnet_norm_eps": 1e-06,
+ "scaling_factor": 1.0,
+ "spatial_compression_ratio": 32,
+ "spatio_temporal_scaling": [
+ true,
+ true,
+ true,
+ true
+ ],
+ "temporal_compression_ratio": 8,
+ "timestep_conditioning": false,
+ "upsample_factor": [
+ 2,
+ 2,
+ 2
+ ],
+ "upsample_residual": [
+ true,
+ true,
+ true
+ ]
+ }
+ },
+ "wan2.2-ti2v-5b": {
+ "kind": "video",
+ "repo": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+ "revision": "b8fff7315c768468a5333511427288870b2e9635",
+ "config": {
+ "_class_name": "AutoencoderKLWan",
+ "_diffusers_version": "0.35.0.dev0",
+ "attn_scales": [],
+ "base_dim": 160,
+ "clip_output": false,
+ "decoder_base_dim": 256,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 4
+ ],
+ "dropout": 0.0,
+ "in_channels": 12,
+ "is_residual": true,
+ "latents_mean": [
+ -0.2289,
+ -0.0052,
+ -0.1323,
+ -0.2339,
+ -0.2799,
+ 0.0174,
+ 0.1838,
+ 0.1557,
+ -0.1382,
+ 0.0542,
+ 0.2813,
+ 0.0891,
+ 0.157,
+ -0.0098,
+ 0.0375,
+ -0.1825,
+ -0.2246,
+ -0.1207,
+ -0.0698,
+ 0.5109,
+ 0.2665,
+ -0.2108,
+ -0.2158,
+ 0.2502,
+ -0.2055,
+ -0.0322,
+ 0.1109,
+ 0.1567,
+ -0.0729,
+ 0.0899,
+ -0.2799,
+ -0.123,
+ -0.0313,
+ -0.1649,
+ 0.0117,
+ 0.0723,
+ -0.2839,
+ -0.2083,
+ -0.052,
+ 0.3748,
+ 0.0152,
+ 0.1957,
+ 0.1433,
+ -0.2944,
+ 0.3573,
+ -0.0548,
+ -0.1681,
+ -0.0667
+ ],
+ "latents_std": [
+ 0.4765,
+ 1.0364,
+ 0.4514,
+ 1.1677,
+ 0.5313,
+ 0.499,
+ 0.4818,
+ 0.5013,
+ 0.8158,
+ 1.0344,
+ 0.5894,
+ 1.0901,
+ 0.6885,
+ 0.6165,
+ 0.8454,
+ 0.4978,
+ 0.5759,
+ 0.3523,
+ 0.7135,
+ 0.6804,
+ 0.5833,
+ 1.4146,
+ 0.8986,
+ 0.5659,
+ 0.7069,
+ 0.5338,
+ 0.4889,
+ 0.4917,
+ 0.4069,
+ 0.4999,
+ 0.6866,
+ 0.4093,
+ 0.5709,
+ 0.6065,
+ 0.6415,
+ 0.4944,
+ 0.5726,
+ 1.2042,
+ 0.5458,
+ 1.6887,
+ 0.3971,
+ 1.06,
+ 0.3943,
+ 0.5537,
+ 0.5444,
+ 0.4089,
+ 0.7468,
+ 0.7744
+ ],
+ "num_res_blocks": 2,
+ "out_channels": 12,
+ "patch_size": 2,
+ "scale_factor_spatial": 16,
+ "scale_factor_temporal": 4,
+ "temperal_downsample": [
+ false,
+ true,
+ true
+ ],
+ "z_dim": 48
+ }
+ },
+ "wan2.2-t2v-a14b": {
+ "kind": "video",
+ "repo": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+ "revision": "5be7df9619b54f4e2667b2755bc6a756675b5cd7",
+ "config": {
+ "_class_name": "AutoencoderKLWan",
+ "_diffusers_version": "0.35.0.dev0",
+ "attn_scales": [],
+ "base_dim": 96,
+ "dim_mult": [
+ 1,
+ 2,
+ 4,
+ 4
+ ],
+ "dropout": 0.0,
+ "latents_mean": [
+ -0.7571,
+ -0.7089,
+ -0.9113,
+ 0.1075,
+ -0.1745,
+ 0.9653,
+ -0.1517,
+ 1.5508,
+ 0.4134,
+ -0.0715,
+ 0.5517,
+ -0.3632,
+ -0.1922,
+ -0.9497,
+ 0.2503,
+ -0.2921
+ ],
+ "latents_std": [
+ 2.8184,
+ 1.4541,
+ 2.3275,
+ 2.6558,
+ 1.2196,
+ 1.7708,
+ 2.6052,
+ 2.0743,
+ 3.2687,
+ 2.1526,
+ 2.8652,
+ 1.5579,
+ 1.6382,
+ 1.1253,
+ 2.8251,
+ 1.916
+ ],
+ "num_res_blocks": 2,
+ "temperal_downsample": [
+ false,
+ true,
+ true
+ ],
+ "z_dim": 16
+ }
+ },
+ "hunyuanvideo-1.5": {
+ "kind": "video",
+ "repo": "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
+ "revision": "286be7ce72277246578a3e3cc2487e95ddae5bcf",
+ "config": {
+ "_class_name": "AutoencoderKLHunyuanVideo15",
+ "_diffusers_version": "0.36.0.dev0",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 1024,
+ 1024
+ ],
+ "downsample_match_channel": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "out_channels": 3,
+ "scaling_factor": 1.03682,
+ "spatial_compression_ratio": 16,
+ "temporal_compression_ratio": 4,
+ "upsample_match_channel": true
+ }
+ },
+ "hunyuanvideo-1.5-720p": {
+ "kind": "video",
+ "repo": "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v",
+ "revision": "f4dbc4a1efa4ac8ea56680cdf79d9f455105e814",
+ "config": {
+ "_class_name": "AutoencoderKLHunyuanVideo15",
+ "_diffusers_version": "0.36.0.dev0",
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 1024,
+ 1024
+ ],
+ "downsample_match_channel": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "out_channels": 3,
+ "scaling_factor": 1.03682,
+ "spatial_compression_ratio": 16,
+ "temporal_compression_ratio": 4,
+ "upsample_match_channel": true
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/studio/backend/tests/test_vae_tile_geometry.py b/studio/backend/tests/test_vae_tile_geometry.py
new file mode 100644
index 00000000000..1ad08d33f57
--- /dev/null
+++ b/studio/backend/tests/test_vae_tile_geometry.py
@@ -0,0 +1,476 @@
+# 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 guard: every VAE Studio tiles decodes in tiles wide and overlapping enough not to leave lines.
+
+Each family's VAE is built on the meta device from its real ``vae/config.json``, set up as a Studio load sets it
+up (``enable_tiling()`` plus every tile override module), and its real ``decode`` runs over every canvas side
+Studio offers with a shape-only decoder; the tile grid is read from the latent slices the decode takes. Off CUDA
+the overrides size tiles for zero free VRAM, the tightest tier.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+torch = pytest.importorskip("torch")
+diffusers = pytest.importorskip("diffusers")
+
+from torch.overrides import TorchFunctionMode
+
+from core.inference import diffusion_families as DF
+from core.inference import video_families as VF
+
+BACKEND = Path(__file__).resolve().parents[1]
+INFERENCE = BACKEND / "core" / "inference"
+FIXTURE = Path(__file__).resolve().parent / "fixtures" / "vae_tile_configs.json"
+
+# Fallback floor when diffusion_vae_tiling is absent.
+MIN_TILE = 32
+MIN_OVERLAP = 16
+# The probe holds the other axis at Studio's smallest side so only the swept axis tiles.
+MIN_SIDE = 256
+LTX23 = "ltx-2.3"
+
+
+@dataclass(frozen = True)
+class Floor:
+ tile: int
+ overlap: int
+ edge: int
+ why: str
+
+
+def _module(name: str):
+ try:
+ return importlib.import_module(f"core.inference.{name}")
+ except ImportError:
+ return None
+
+
+def default_floor() -> Floor:
+ """Read from diffusion_vae_tiling so the guard and the fix cannot drift apart."""
+ mod = _module("diffusion_vae_tiling")
+ tile = int(getattr(mod, "TILE_LATENTS", MIN_TILE))
+ overlap = int(getattr(mod, "OVERLAP_LATENTS", MIN_OVERLAP))
+ src = "diffusion_vae_tiling" if mod is not None and hasattr(mod, "TILE_LATENTS") else "default"
+ return Floor(tile, overlap, tile, src)
+
+
+def ltx_floor() -> Floor:
+ mod = _module("video_ltx2_vae_tiles")
+ tile = int(getattr(mod, "MIN_TILE_LATENTS", 16))
+ overlap = int(getattr(mod, "OVERLAP_LATENTS", 8))
+ return Floor(
+ tile, overlap, overlap, "LTX-2 wide tiles (video_ltx2_vae_tiles); seam bench clean"
+ )
+
+
+def keep_stock() -> dict[str, str]:
+ return dict(getattr(_module("diffusion_vae_tiling"), "KEEP_STOCK", {}) or {})
+
+
+# "VAE class@ratio" -> a smaller geometry measured seam-free (real latent, tiled vs untiled decode). Measurement required.
+SMALLER_GEOMETRY_OK: dict[str, Floor] = {
+ # #12698 seam bench: worst 64 px window <= 1.88 levels, PSNR >= 53 dB (stock 2-latent overlaps: 2.3-7.7).
+ "AutoencoderKLLTX2Video@32x": Floor(
+ 16, 8, 8, "PR #12698's 16-latent tiles, 8-latent overlaps: seam bench clean"
+ ),
+ "AutoencoderKLWan@8x": Floor(
+ 32, 8, 8, "seam bench: worst 64 px window 1.93 levels, PSNR >= 49.9 dB"
+ ),
+ # Untiled is worse here (20 dB vs the input photo, tiled 30 dB): Studio always decodes it tiled.
+ "AutoencoderKLMiniMaxH3@16x": Floor(
+ 16, 4, 16, "decoder works at its 256 px tile; untiled is out of distribution"
+ ),
+ # 16x video VAEs at stock tiles, real 33-frame clip vs untiled.
+ "AutoencoderKLHunyuanVideo15@16x": Floor(
+ 16, 4, 4, "video seam audit: PSNR >= 50.6 dB, no line at the boundaries"
+ ),
+ "AutoencoderKLWan@16x": Floor(
+ 16, 4, 8, "video seam audit: PSNR 49.3 dB, no line at the boundaries"
+ ),
+}
+
+# family -> open seam bug below the floor. Strict xfail, so the fix landing forces the entry out.
+KNOWN_SEAMS: dict[str, str] = {}
+
+GEOMETRY_PRESERVING = {
+ "diffusion_vae_fused": "batched stock tiled_decode: the stock attributes' tiles, decoded as one batch",
+}
+
+
+class _TileRecorder(TorchFunctionMode):
+ """Every (start, stop) slice taken of the last two dims of a tensor shaped like the latent."""
+
+ def __init__(self, hw):
+ super().__init__()
+ self.hw = tuple(int(v) for v in hw)
+ self.axes = (set(), set())
+ self.paused = False
+
+ def __torch_function__(
+ self,
+ func,
+ types,
+ args = (),
+ kwargs = None,
+ ):
+ kwargs = kwargs or {}
+ if not self.paused and func is torch.Tensor.__getitem__ and len(args) > 1:
+ self._record(args[0], args[1])
+ return func(*args, **kwargs)
+
+ def _record(self, t, idx):
+ if not torch.is_tensor(t) or t.dim() < 4 or tuple(t.shape[-2:]) != self.hw:
+ return
+ idx = idx if isinstance(idx, tuple) else (idx,)
+ if any(i is Ellipsis for i in idx):
+ k = next(n for n, i in enumerate(idx) if i is Ellipsis)
+ idx = idx[:k] + (slice(None),) * (t.dim() - len(idx) + 1) + idx[k + 1 :]
+ if len(idx) != t.dim() or not all(isinstance(s, slice) for s in idx[-2:]):
+ return
+ for axis, (s, n) in enumerate(zip(idx[-2:], self.hw)):
+ lo, hi, _ = s.indices(n)
+ if (lo, hi) != (0, n) and hi > lo:
+ self.axes[axis].add((lo, hi))
+
+
+_ACTIVE: list = []
+
+
+class _ShapeOnly(torch.nn.Module):
+ """Zeros of the real module's output shape. The real module runs on meta for the first two spatial sizes per
+ call signature; later sizes extrapolate the measured upsampling, so the sweep costs no further decoder passes."""
+
+ def __init__(self, inner):
+ super().__init__()
+ self.inner = inner
+ self._seen = {}
+
+ @staticmethod
+ def _sig(v, spatial: bool):
+ if torch.is_tensor(v):
+ return tuple(v.shape) if spatial else (tuple(v.shape[:-2]), v.dim())
+ return type(v).__name__ if isinstance(v, (list, dict, tuple)) else repr(v)
+
+ def _run(self, args, kwargs):
+ meta = lambda v: v.to("meta") if torch.is_tensor(v) else v # noqa: E731
+ for rec in _ACTIVE:
+ rec.paused = True
+ try:
+ return tuple(
+ self.inner(*map(meta, args), **{k: meta(v) for k, v in kwargs.items()}).shape
+ )
+ finally:
+ for rec in _ACTIVE:
+ rec.paused = False
+
+ def forward(self, *args, **kwargs):
+ x = next(a for a in args if torch.is_tensor(a))
+ key = (
+ tuple(self._sig(a, False) for a in args),
+ tuple(sorted((k, self._sig(v, False)) for k, v in kwargs.items())),
+ )
+ seen = self._seen.setdefault(key, [])
+ hw = tuple(x.shape[-2:])
+ known = [out for inp, out in seen if inp == hw]
+ if known:
+ shape = known[0]
+ elif len(seen) < 2:
+ shape = self._run(args, kwargs)
+ seen.append((hw, shape))
+ if len(seen) == 2:
+ (h0, w0), o0 = seen[0]
+ (h1, w1), o1 = seen[1]
+ if o0[:-2] != o1[:-2] or o0[-2] * h1 != o1[-2] * h0 or o0[-1] * w1 != o1[-1] * w0:
+ seen.append(((-1, -1), None)) # not a pure upsample: always run the module
+ elif any(out is None for _, out in seen):
+ shape = self._run(args, kwargs)
+ else:
+ (h0, w0), o0 = seen[0]
+ shape = (*o0[:-2], hw[0] * o0[-2] // h0, hw[1] * o0[-1] // w0)
+ return x if shape == tuple(x.shape) else x.new_zeros(shape)
+
+
+def tile_override_modules() -> tuple[list[str], list[str]]:
+ """(override modules a load applies with ``install(vae)``, other modules that rebind ``tiled_decode``)."""
+ found, other = [], []
+ for path in sorted(INFERENCE.glob("*.py")):
+ text = path.read_text(encoding = "utf-8", errors = "replace")
+ if not re.search(r"\.tiled_decode\s*=", text):
+ continue
+ if re.search(r"tiled_decode\s*=\s*types\.MethodType", text) and re.search(
+ r"^def install\(\s*vae\b", text, re.M
+ ):
+ found.append(path.stem)
+ else:
+ other.append(path.stem)
+ return found, other
+
+
+def _vae_class(name: str):
+ cls = getattr(diffusers, name, None)
+ if cls is None:
+ for mod in ("core.inference.video_minimax_h3_vae",):
+ cls = getattr(importlib.import_module(mod), name, None)
+ if cls is not None:
+ break
+ return cls
+
+
[email protected]_cache(maxsize = None)
+def _fixture() -> dict:
+ return json.loads(FIXTURE.read_text(encoding = "utf-8"))["families"]
+
+
+def _family_configs() -> dict[str, tuple[str, dict]]:
+ """family -> (kind, vae config) for every registry family, plus LTX-2.3's single-file VAE config."""
+ out = {}
+ fixture = _fixture()
+ for f in DF._FAMILIES:
+ if f.name in fixture:
+ out[f.name] = ("image", fixture[f.name]["config"])
+ for f in VF._FAMILIES:
+ if f.name in fixture:
+ out[f.name] = ("video", fixture[f.name]["config"])
+ from core.inference import video_ltx2
+
+ out[LTX23] = (
+ "video",
+ {"_class_name": "AutoencoderKLLTX2Video", **video_ltx2._VIDEO_VAE_CONFIG},
+ )
+ return out
+
+
+def _sides(family: str) -> list[int]:
+ fam = next((f for f in DF._FAMILIES if f.name == family), None)
+ if fam is not None:
+ step = max(8, int(fam.dimension_multiple))
+ return list(range(MIN_SIDE, int(fam.max_output_side) + 1, step))
+ fam = next(f for f in VF._FAMILIES if f.name == ("ltx-2" if family == LTX23 else family))
+ return sorted({v for wh in fam.resolution_presets for v in wh})
+
+
+# The loader each kind goes through: a family gets only the overrides its own loader installs.
+LOADERS = {"image": "diffusion.py", "video": "video.py"}
+
+
+def overrides_for(kind: str) -> list[str]:
+ src = (INFERENCE / LOADERS[kind]).read_text(encoding = "utf-8", errors = "replace")
+ return [m for m in tile_override_modules()[0] if re.search(rf"\.{m}\b", src)]
+
+
+def build_vae(config: dict, kind: str | None = None):
+ cfg = {k: v for k, v in config.items() if not k.startswith("_")}
+ cls = _vae_class(config["_class_name"])
+ if cls is None:
+ pytest.fail(
+ f"{config['_class_name']} is in neither diffusers {diffusers.__version__} nor Studio"
+ )
+ with torch.device("meta"):
+ vae = cls.from_config(cfg)
+ vae.enable_tiling()
+ applied = []
+ for mod in overrides_for(kind) if kind else ():
+ if importlib.import_module(f"core.inference.{mod}").install(vae):
+ applied.append(mod)
+ for name in ("decoder", "post_quant_conv"):
+ child = getattr(vae, name, None)
+ if isinstance(child, torch.nn.Module):
+ setattr(vae, name, _ShapeOnly(child))
+ return vae, applied
+
+
+def _latent_channels(config: dict) -> int:
+ for key in ("z_dim", "latent_channels", "z_channels"):
+ if config.get(key):
+ return int(config[key])
+ return 16
+
+
+def probe_axis(vae, config: dict, length: int, other: int, video: bool) -> list[tuple[int, int]]:
+ c = _latent_channels(config)
+ for frames in (1, 2, 4, 8) if video else (None,):
+ shape = (1, c, length, other) if frames is None else (1, c, frames, length, other)
+ rec = _TileRecorder(shape[-2:])
+ _ACTIVE.append(rec)
+ try:
+ with rec, torch.no_grad():
+ vae.decode(torch.zeros(shape), return_dict = False)
+ return sorted(rec.axes[0])
+ except Exception as exc: # noqa: BLE001 - a frame count the VAE's temporal chunking refuses
+ last = exc
+ finally:
+ _ACTIVE.remove(rec)
+ raise last
+
+
+def _ratio(vae) -> int:
+ ratio = getattr(vae, "spatial_compression_ratio", None)
+ if ratio is None: # AutoencoderKL-style: one 2x upsample per block after the first
+ ratio = 2 ** (len(vae.config.block_out_channels) - 1)
+ return int(ratio)
+
+
+def _is_5d(vae) -> bool:
+ import inspect
+ try:
+ src = inspect.getsource(type(vae)._encode)
+ except (OSError, TypeError, AttributeError):
+ return False
+ return (
+ re.search(r"num_frame|frames|shape\[2\]|(?:\w+\s*,\s*){4}\w+\s*=\s*\w+\.shape", src)
+ is not None
+ )
+
+
+def check_axis(tiles: list[tuple[int, int]], floor: Floor) -> list[str]:
+ if len(tiles) < 2:
+ return []
+ problems = []
+ longest = max(hi - lo for lo, hi in tiles)
+ shortest = min(hi - lo for lo, hi in tiles)
+ overlap = min(a[1] - b[0] for a, b in zip(tiles, tiles[1:]))
+ if longest < floor.tile:
+ problems.append(f"{longest}-latent tiles < {floor.tile}")
+ if overlap < floor.overlap:
+ problems.append(f"{overlap}-latent overlap < {floor.overlap}")
+ if shortest < floor.edge:
+ problems.append(f"a {shortest}-latent edge tile < {floor.edge}")
+ return problems
+
+
+_PROBED: dict = {}
+
+
+def _tile_key(vae, applied, video: bool) -> tuple:
+ attrs = sorted(
+ (k, repr(v)) for k, v in vars(vae).items() if k.startswith(("tile_", "use_framewise"))
+ )
+ return type(vae).__name__, _ratio(vae), tuple(attrs), tuple(applied), video
+
+
[email protected]_cache(maxsize = None)
+def geometry(family: str):
+ """(VAE class, ratio, overrides applied, {side px: tiles}, temporal problem or None) for ``family``."""
+ kind, config = _family_configs()[family]
+ vae, applied = build_vae(config, kind)
+ ratio = _ratio(vae)
+ video = _is_5d(vae)
+ other = max(1, MIN_SIDE // ratio)
+ cache = _PROBED.setdefault(_tile_key(vae, applied, video), {})
+ grid = {}
+ for side in _sides(family):
+ if side % ratio:
+ continue
+ length = side // ratio
+ if length not in cache:
+ cache[length] = probe_axis(vae, config, length, other, video)
+ grid[side] = cache[length]
+ temporal = None
+ if getattr(vae, "use_framewise_decoding", False):
+ t_ratio = int(getattr(vae, "temporal_compression_ratio", 1) or 1)
+ span = int(vae.tile_sample_min_num_frames) - int(vae.tile_sample_stride_num_frames)
+ if span < t_ratio:
+ temporal = f"temporal tiles share {span} frames < 1 latent frame ({t_ratio})"
+ return type(vae).__name__, ratio, tuple(applied), grid, temporal
+
+
+def _all_families() -> list[str]:
+ return [f.name for f in DF._FAMILIES] + [f.name for f in VF._FAMILIES] + [LTX23]
+
+
+def test_every_family_has_a_vae_config():
+ missing = [f.name for f in (*DF._FAMILIES, *VF._FAMILIES) if f.name not in _fixture()]
+ assert not missing, (
+ f"families without a VAE config in {FIXTURE.name}: {missing}. Add each one's vae/config.json "
+ "(base repo, pinned revision) so the seam guard checks the tile geometry Studio decodes it with."
+ )
+
+
+def test_every_tiled_decode_patch_is_probed():
+ _, other = tile_override_modules()
+ unknown = [m for m in other if m not in GEOMETRY_PRESERVING]
+ assert not unknown, (
+ f"{unknown} rebind a VAE's tiled_decode but expose no install(vae) this guard applies: give them one "
+ "(types.MethodType + def install(vae, logger=None)) or, if they keep the stock tile grid, list them in "
+ "GEOMETRY_PRESERVING with the reason."
+ )
+
+
+def _family_params():
+ return [
+ pytest.param(f, marks = pytest.mark.xfail(strict = True, reason = KNOWN_SEAMS[f]))
+ if f in KNOWN_SEAMS
+ else f
+ for f in _all_families()
+ ]
+
+
[email protected]("family", _family_params())
+def test_tile_geometry(family):
+ name, ratio, applied, grid, temporal = geometry(family)
+ # A blind recorder (tiling via narrow / split) must fail, not pass with no grid.
+ assert any(
+ len(t) >= 2 for t in grid.values()
+ ), f"{family}: {name} recorded no multi-tile grid on any canvas side; the probe no longer sees the tiling"
+ kept = keep_stock()
+ if name in kept:
+ # because the image module keeps this VAE on diffusers' tiles on purpose, with a measurement: its reason stands
+ pytest.skip(reason = f"{name} in diffusion_vae_tiling.KEEP_STOCK: {kept[name]}")
+ floor = ltx_floor() if name == "AutoencoderKLLTX2Video" else None
+ floor = floor or SMALLER_GEOMETRY_OK.get(f"{name}@{ratio}x", default_floor())
+ bad = {side: (tiles, check_axis(tiles, floor)) for side, tiles in grid.items()}
+ bad = {side: v for side, v in bad.items() if v[1]}
+ msgs = []
+ if bad:
+ side, (tiles, problems) = min(bad.items(), key = lambda kv: abs(kv[0] - 1024))
+ msgs.append(
+ f"{family}: {name} ({ratio}x, overrides {list(applied) or 'none'}) decodes a {side} px side in tiles "
+ f"{tiles} (latents): {', '.join(problems)}; {len(bad)} of {len(grid)} canvas sides fail "
+ f"({sorted(bad)[:8]}{' ...' if len(bad) > 8 else ''}). Need tile >= {floor.tile}, overlap >= "
+ f"{floor.overlap}, every tile >= {floor.edge} latents ({floor.why}). Install wide tiles for this VAE, "
+ "or add it to SMALLER_GEOMETRY_OK with a measured seam-free decode."
+ )
+ if temporal:
+ msgs.append(f"{family}: {name}: {temporal}")
+ assert not msgs, "\n".join(msgs)
+
+
+def test_overrides_follow_the_loader():
+ assert "diffusion_vae_tiling" in overrides_for("image")
+ assert "diffusion_vae_tiling" not in overrides_for("video")
+ assert "video_ltx2_vae_tiles" in overrides_for("video")
+
+
+def test_check_axis_flags_each_threshold():
+ ok = Floor(32, 16, 16, "test")
+ assert check_axis([(0, 64)], ok) == []
+ assert check_axis([(0, 32), (16, 48), (32, 64)], ok) == []
+ # Qwen-Image-2.1 before #12696, 1024 px
+ stock = [(0, 16), (12, 28), (24, 40), (36, 52), (48, 64), (60, 64)]
+ assert check_axis(stock, ok) == [
+ "16-latent tiles < 32",
+ "4-latent overlap < 16",
+ "a 4-latent edge tile < 16",
+ ]
+ # 8x AutoencoderKL at 1600 px: an 8-latent sliver
+ assert check_axis([(0, 128), (96, 200), (192, 200)], ok) == [
+ "8-latent overlap < 16",
+ "a 8-latent edge tile < 16",
+ ]
+
+
+def test_probe_reads_the_stock_grid():
+ vae, applied = build_vae({"_class_name": "AutoencoderKLWan", "z_dim": 16})
+ assert applied == []
+ tiles = probe_axis(vae, {"z_dim": 16}, 64, 8, True)
+ assert tiles == [(0, 32), (24, 56), (48, 64)]