From 344613c159916c73cd81344683c3acb4c9f4ccec Mon Sep 17 00:00:00 2001
From: Xiaoyu Zhang <1182563586@qq.com>
Date: Mon, 24 Aug 2026 13:18:06 +0800
Subject: [PATCH] [diffusion] Default Hunyuan VAE to tiled decode (#36012)

---
 docs/docs/sglang-diffusion/api/cli.mdx        |  9 ++++++++
 .../configs/pipeline_configs/hunyuan.py       |  4 +++-
 .../test/unit/test_hunyuan_config.py          | 22 +++++++++++++++++++
 3 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 python/sglang/multimodal_gen/test/unit/test_hunyuan_config.py

diff --git a/docs/docs/sglang-diffusion/api/cli.mdx b/docs/docs/sglang-diffusion/api/cli.mdx
index 6d947bb96..b90b50b18 100644
--- a/docs/docs/sglang-diffusion/api/cli.mdx
+++ b/docs/docs/sglang-diffusion/api/cli.mdx
@@ -212,6 +212,15 @@ vae_sp: true
 enable_torch_compile: false
 ```
 
+HunyuanVideo and FastHunyuan use tiled VAE decode by default so multi-GPU runs
+distribute VAE tiles instead of selecting spatial-shard decode. At
+HunyuanVideo's supported 960×544×77 shape, spatial-shard decode can consume
+99.8 GiB per rank before requesting another 49.61 GiB causal mask. At
+FastHunyuan's default 1280×720×125 shape, the mask alone would require
+197.75 GiB. You can still override the policy with
+`--vae-config.parallel-decode-mode`, but `spatial` and `spatial_shard` should
+only be used for smaller validated shapes.
+
 ## Generate
 
 `sglang generate` runs a single generation job and exits when the job finishes.
diff --git a/python/sglang/multimodal_gen/configs/pipeline_configs/hunyuan.py b/python/sglang/multimodal_gen/configs/pipeline_configs/hunyuan.py
index edeaaf09c..0287b44ed 100644
--- a/python/sglang/multimodal_gen/configs/pipeline_configs/hunyuan.py
+++ b/python/sglang/multimodal_gen/configs/pipeline_configs/hunyuan.py
@@ -93,7 +93,9 @@ class HunyuanConfig(PipelineConfig):
     # DiT
     dit_config: DiTConfig = field(default_factory=HunyuanVideoConfig)
     # VAE
-    vae_config: VAEConfig = field(default_factory=HunyuanVAEConfig)
+    vae_config: VAEConfig = field(
+        default_factory=lambda: HunyuanVAEConfig(parallel_decode_mode="tiled")
+    )
     # Denoising stage
     embedded_cfg_scale: int = 6
     flow_shift: int = 7
diff --git a/python/sglang/multimodal_gen/test/unit/test_hunyuan_config.py b/python/sglang/multimodal_gen/test/unit/test_hunyuan_config.py
new file mode 100644
index 000000000..9e0d24ec3
--- /dev/null
+++ b/python/sglang/multimodal_gen/test/unit/test_hunyuan_config.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from sglang.multimodal_gen.configs.pipeline_configs.hunyuan import (
+    FastHunyuanConfig,
+    HunyuanConfig,
+)
+
+
+def test_hunyuan_configs_default_to_parallel_tiled_vae_decode():
+    for config_cls in (HunyuanConfig, FastHunyuanConfig):
+        assert config_cls().vae_config.parallel_decode_mode == "tiled"
+
+
+def test_hunyuan_parallel_decode_mode_can_be_overridden():
+    for config_cls in (HunyuanConfig, FastHunyuanConfig):
+        config = config_cls()
+
+        config.update_config_from_dict(
+            {"vae_config.parallel_decode_mode": "spatial_shard"}
+        )
+
+        assert config.vae_config.parallel_decode_mode == "spatial_shard"