vLLM-Omni VAE 并行详解：Patch/Tile 并行与 Wan 空间分片解码的实现与配置指南

vLLM-Omni VAE 并行详解Patch/Tile 并行与 Wan 空间分片解码的实现与配置指南【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni在 vLLM-Omni 中VAEVariational AutoEncoder解码往往是高分辨率图像生成和长视频生成的显存瓶颈。本篇指南围绕docs/user_guide/diffusion/parallelism/vae_parallelism.md展开讲清 VAE 并行的三种解码策略tile 分块、patch 分块、Wan 空间分片各自的工作原理与选型依据并给出从 Python API 到vllm serve服务端的完整配置方法、参数约束与源码级排查路径。读完后你可以正确启用 VAE patch 并行以降低 VAE decode 峰值显存、理解它与 DiT 并行组DiT process group的共享关系、以及在遇到配置被静默忽略类问题时能快速定位根因。一、总览VAE 并行在 vLLM-Omni 中的定位VAE parallelism 将 VAE 的 decode/encode 工作分摊到多张 GPU 上。当前仓库实现了两条路线VAE patch/tile parallelism把 latent 空间切成空间上的 tile 或 patch各 rank 解码一部分再由 rank 0 拼接成完整结果Wan spatial-shard decode针对 Wan VAE沿高度或宽度方向分片 decoder 特征图并在空间卷积处交换 halo 行/列。适用场景来自原指南高分辨率图像生成VAE decode 成为显存瓶颈时显存受限环境VAE decode 激活峰值超出可用 VRAM多 GPU 环境希望把 VAE 阶段也放到分布式资源上利用起来。各模型的支持情况见 Supported Models 中的VAE-Patch-Parallel列。两种策略对照表原文完整继承VAE patch parallelism 依据图像尺寸自动选择两种策略策略适用场景工作方式重叠区域处理输出质量Tiled Decode大图像触发 VAE tiling把既有的 VAE tiling 计算分摊到各 rank每个 rank 解码一组重叠 tile复用 VAE 原生的blend_v与blend_h函数无缝合并重叠区域Bit-identical与单卡 tiling 逻辑相同Patch Decode小图像不触发 VAE tiling把 latent 切成带 halo 的空间 patch每个 rank 解码一个 patch 及其边界上下文halo 区域提供边缘上下文核心区域直接拼接不做 blending近似一致diff 0.5%视觉不可感知从源码看策略选择逻辑位于 VaePatchParallelism.decode它先判断 latent 是否满足 diffusers 的 tiling 触发条件z.shape[-1] tile_latent_min_size or z.shape[-2] tile_latent_min_size满足则走_distributed_tiled_decode否则走_distributed_patch_decode与上表描述一致。与 DiT 并行组的关系VAE patch parallelism复用 DiT 的 process groupdit_group不会单独初始化新的 ProcessGroup。这意味着共享 ranksVAE patch 并行使用与 DiT 并行Tensor Parallel、Sequence Parallel 等相同的 GPU ranks组合使用VAE patch 并行通常与其他并行方式一起使用配置对齐vae_patch_parallel_size不应大于 DiT process group 的大小。实现上DistributedVaeExecutor 在初始化时直接取get_world_group().device_groupworker 全 WORLD 范围作为通信组world_size/rank均取自该组实际参与的 rank 数为min(vae_patch_parallel_size, world_size)。二、快速上手Quick Start基本用法最简可运行示例from vllm_omni import Omni from vllm_omni.inputs.data import OmniDiffusionSamplingParams from vllm_omni.diffusion.data import DiffusionParallelConfig # TP2 for DiT, VAE patch parallel also uses these 2 GPUs omni Omni( modelTongyi-MAI/Z-Image-Turbo, parallel_configDiffusionParallelConfig( tensor_parallel_size2, # Enable tensor parallelism for DiT vae_patch_parallel_size2, # Enable VAE patch parallelism ), vae_use_tilingTrue, # Required for VAE patch parallelism ) outputs omni.generate( a futuristic city at sunset, high resolution, 8k, OmniDiffusionSamplingParams( num_inference_steps9, height1152, # High resolution benefits from VAE patch parallel width1152, ), )要点DiffusionParallelConfig定义于 vllm_omni/diffusion/data.py其中vae_patch_parallel_size默认 1即关闭vae_parallel_mode默认tilevae_use_tiling在OmniDiffusionConfig层默认False见 data.py。使用 VAE patch 并行时需要开启它但即使忘了开注册器也会在启动时自动补上见下文配置校验一节。三、示例脚本离线推理使用examples/offline_inference/text_to_image/下的 text_to_image.py# Text-to-Image with Z-Image python examples/offline_inference/text_to_image/text_to_image.py \ --model Tongyi-MAI/Z-Image-Turbo \ --prompt a futuristic city at sunset \ --height 1152 \ --width 1152 \ --tensor-parallel-size 2 \ --vae-patch-parallel-size 2 \ --vae-use-tiling在线服务Online Serving在线服务通过--vae-patch-parallel-size启用该 CLI 参数在 vllm_omni/entrypoints/cli/serve.py 中定义# Text-to-Image with Z-Image, TP2 VAE patch parallel2 vllm serve Tongyi-MAI/Z-Image-Turbo --omni --port 8091 \ --tensor-parallel-size 2 \ --vae-patch-parallel-size 2 \ --vae-use-tiling四、配置参数详解DiffusionParallelConfig 中的参数参数类型默认值说明vae_patch_parallel_sizeint1VAE patch/tile 并行使用的 GPU 数。设为 2 或更大即启用。应与tensor_parallel_size一致因为二者共享同一个 process group。vae_parallel_modestrtileVAE 并行解码策略tile默认 tile/patch 并行解码、spatial_shard_height、spatial_shard_width空间分片解码仅 Wan 支持。见下文 Wan 空间分片解码。源码中该字段及约束vllm_omni/diffusion/data.pyvae_patch_parallel_sizeNumber of ranks used for VAE patch/tile parallelism (decode/encode)vae_parallel_modespatial_shard_* 模式是 decode-only且要求vae_patch_parallel_size与 DiT group size 匹配否则运行时回退到 tile 并行解码配置校验器_validate_parallel_config会断言vae_patch_parallel_size 0且vae_parallel_mode ∈ {tile, spatial_shard_height, spatial_shard_width}不满足会在构造DiffusionParallelConfig时直接报错data.py。附加要求参数类型默认值说明vae_use_tilingboolFalse使用 VAE patch 并行时必须设为True。!!! note 自动开启 VAE Tiling 当vae_patch_parallel_size 1且模型具备分布式 VAEDistributedVaeMixin时若vae_use_tiling尚未开启系统会自动将其置为True。这个自动行为在注册器中有明确实现vllm_omni/diffusion/registry.py 中vae_pp_size od_config.parallel_config.vae_patch_parallel_size is_distributed_vae hasattr(model, vae) and isinstance(model.vae, DistributedVaeMixin) if vae_pp_size 1 and not is_distributed_vae: logger.warning( vae_patch_parallel_size%d is set but VAE patch parallelism is NOT enabled for %s; ignoring., vae_pp_size, od_config.model_class_name, ) if vae_pp_size 1 and is_distributed_vae and not od_config.vae_use_tiling: logger.info( vae_patch_parallel_size%d requires vae_use_tiling; automatically enabling it., vae_pp_size, ) od_config.vae_use_tiling True ... if is_distributed_vae: model.vae.set_parallel_size(vae_pp_size, modeod_config.parallel_config.vae_parallel_mode)即注册器在加载 pipeline 后统一判断 VAE 是否为DistributedVaeMixin实例不支持则打警告并忽略配置支持则自动开启 tiling并把parallel_size与vae_parallel_mode一并传给 VAEDistributedVaeMixin.set_parallel_size。五、源码级原理tile 并行与 patch 并行如何工作分布式执行器DistributedVaeExecutor通用执行框架在 distributed_vae_executor.py其execute主流程为切分operator.split(z)把输入 latent 切成一组TileTask带tile_id、网格坐标与 workload负载均衡_balance_tasks按 workload 降序做贪心分配总是把下一个最大任务分给当前累计负载最小的 rank避免各 rank 忙闲不均本地解码每个 rank 只解码分配给自己的 tileoperator.exec形状协商_compute_global_padding_shape通过all_reduce(MAX)求出所有 tile 的最大尺寸保证 gather 时张量形状统一打包与收集每个 rank 把本地 tile 与元信息tile_id、H/W打包成定长张量all_gather到所有 rank拼接rank 0 调用operator.merge重建完整张量非 rank 0 返回空张量结果同步_sync_final_result先广播形状、再广播内容使所有 rank 拿到一致的完整输出。Tiled Decode复用 diffusers 原生 tiling 逻辑_distributed_tiled_decode 是 diffusersAutoencoderKL.tiled_decode的分布式版本仅 decode 路径按照overlap_size tile_latent_min_size * (1 - tile_overlap_factor)的步长在 latent 上生成 tile 网格tile 到 rank 的分配使用tile_rank (tile_id 1) % pp_size偏移 1 位是为了让 rank 0 避开最大的边界 tiletile_id0让最重的一块落到其他 rank 上各 rank 解码后gather到 rank 0rank 0 用 VAE 原生的blend_v/blend_h在blend_extent重叠区做线性混合再裁剪拼接——这正是bit-identical质量承诺的来源因为它执行的是与单卡 tiling 完全相同的混合与拼接代码。Patch Decode小图像也能受益_distributed_patch_decode 针对单卡本来不会触发 tiling的中小尺寸输入网格切分_factor_pp_grid为pp_size选一个接近正方形的 (rows, cols) 因子分解每个 rank 负责一个 patchhalo 计算halo max(halo_base, min(core_h, core_w) // 2)其中halo_base来自 tile overlap 参数。每个 rank 解码核心区 halo 边界上下文然后只裁出核心区ch0:ch1, cw0:cw1halo 的贡献被丢弃直接拼接核心块——因此质量是近似一致而非逐 bit 相同拼接同样发生在 rank 0先 gather 各 rank 的核心 RGB 块不足部分补零再按原 latent 网格坐标填回输出张量。回退与容错VaePatchParallelism.decode中有多重保护vae_patch_parallel.pylatent 非 4D、vae_patch_parallel_size 1、分布式未初始化、VAE 未开启use_tiling、取不到 process group 等情况一律回退到原始vae.decode若 rank 0 的并行解码产出为空打印VAE patch parallel decode produced empty output on rank0; falling back to vae.decode.并回退最终通过广播形状 广播张量让所有 rank 持有同一份完整输出pipeline 下游无需感知并行细节。另外还有一条更轻量的挂接路径 maybe_wrap_vae_decode_with_patch_parallelism它以实例级覆写的方式包装vae.decode通过能力检查有decode/decoder属性而非严格的 diffusers 类型检查来支持自定义 VAE并用_vllm_vae_patch_parallel_installed标志防止重复安装。哪些 VAE 实现了 DistributedVaeMixin仓库中实现 DistributedVaeMixin 的 VAE 分布在vllm_omni/diffusion/distributed/autoencoders/与部分模型目录下例如autoencoder_kl_wan.pyWan额外支持空间分片autoencoder_kl_qwenimage.pyQwen-Imageautoencoder_kl_hunyuan_video_15.py、autoencoder_kl_hunyuan.pyautoencoder_kl_ltx2.py 及 ltx2/vae/distributed.py模型内定制bagel/autoencoder.py、magi2/turbo_vae.py、minimax_h3/vae.py 等is_distributed_enabled()的判定条件是parallel_size 1、分布式已初始化、use_tiling为 True且min(parallel_size, world_size) 1若parallel_size超过 WORLD size会打印vae_patch_parallel_size... is greater than WORLD...; using WORLD size...警告并按 WORLD size 截断——这正是下一节配置超过 DiT group 大小问题的运行时表现。六、Wan 空间分片解码Spatially-Sharded Decode默认的vae_parallel_modetile把整块 tile 分给各 rank。针对WanVAE 还有备选策略——空间分片解码通过vae_parallel_modespatial_shard_height或spatial_shard_width选择。它不向各 rank 分派独立 tile而是把 decoder 特征图沿高度spatial_shard_height或宽度spatial_shard_width方向切分并在空间卷积spatial convolutions前后于相邻 rank 间交换 halo 行/列。这样跨分片边界处的感受野保持正确结果与单卡解码在数值误差范围内一致。Python APIfrom vllm_omni import Omni from vllm_omni.diffusion.data import DiffusionParallelConfig omni Omni( modelWan-AI/Wan2.1-T2V-1.3B-Diffusers, parallel_configDiffusionParallelConfig( tensor_parallel_size2, vae_patch_parallel_size2, # must match the DiT group size vae_parallel_modespatial_shard_width, # or spatial_shard_height ), )CLI / 服务端vllm serve Wan-AI/Wan2.1-T2V-1.3B-Diffusers --omni \ --tensor-parallel-size 2 \ --vae-patch-parallel-size 2 \ --vae-parallel-mode spatial_shard_width约束与行为空间分片解码是decode-only目前仅对WanVAE 实现其他模型会忽略spatial_shard_*模式要求vae_patch_parallel_size与 DiT process group 大小匹配不匹配时 VAE 记录警告并在运行时回退到 tile 并行解码对同一个 VAE 实例spatial_shard_height与spatial_shard_width互斥decoder 就地为单一 split 维度打补丁。源码印证autoencoder_kl_wan.py 中_spatial_shard_decode_enabled会检查is_distributed_enabled()与 split 维度配置命中后调用 wan_spatial_shard.spatial_shard_decode。后者内部通过install_wan_spatial_shard_decodewan_spatial_shard.py对 decoder 的就地打补丁——补丁时校验已安装的 split 维度若再次以不同维度安装会复用/保持单一维度与互斥的约束一致。端到端基准评估端到端时延/吞吐时以期望的vae_parallel_mode启动服务后可直接复用仓库现成的 diffusion serving benchmarkpython3 benchmarks/diffusion/diffusion_benchmark_serving.py \ --endpoint /v1/videos --dataset random --task t2v --num-prompts 1 \ --height 480 --width 832 --num-frames 17 --max-concurrency 1七、最佳实践何时使用适合高分辨率图像生成与长视频生成VAE decode 导致 OOM 的显存受限部署多 GPU 环境。不适合VAE decode 本就不是瓶颈的低分辨率图像/视频单 GPU 环境——单卡应使用 vae tiling decode而不是并行 vae tiling decode不支持 VAE patch parallel 的模型。八、常见问题排查Troubleshooting问题 1模型不支持 VAE Patch Parallel现象WARNING: vae_patch_parallel_size2 is set but VAE patch parallelism is NOT enabled for xxxPipeline; ignoring.根因VAE Patch Parallelism 要求模型的 VAE 实现DistributedVaeMixin。启动时 vllm_omni/diffusion/registry.py 检查实例化后的 pipeline 是否具有.vae属性且为DistributedVaeMixin实例若不是该配置被静默忽略仅打警告vae_pp_size od_config.parallel_config.vae_patch_parallel_size is_distributed_vae hasattr(model, vae) and isinstance(model.vae, DistributedVaeMixin) if vae_pp_size 1 and not is_distributed_vae: logger.warning( vae_patch_parallel_size%d is set but VAE patch parallelism is NOT enabled for %s; ignoring., vae_pp_size, od_config.model_class_name, )解决方案改用受支持的模型推荐查看 Supported Models 的 VAE-Patch-Parallel 列为新模型添加支持在其 VAE 类上实现DistributedVaeMixin欢迎贡献。问题 2vae_patch_parallel_size超过 DiT Process Group 大小现象出现警告信息且 VAE patch parallel size 被调整为 DiT process group size。根因VAE Patch Parallelism 复用 DiT process grouppp_size min(vae_patch_parallel_size, world_size)见 DistributedVaeMixin.is_distributed_enabled 与 VaePatchParallelism.decode 中的截断逻辑。建议始终把vae_patch_parallel_size设为不大于 DiT process group size 的值。注意 DiT process group size 等于dit_parallel_size data_parallel_size × cfg_parallel_size × sequence_parallel_size × pipeline_parallel_size × tensor_parallel_size其中 sequence_parallel_size ulysses_degree × ring_degree。九、总结启用 VAE Patch Parallelism在DiffusionParallelConfig中设置vae_patch_parallel_sizevae_use_tilingTrue以降低 VAE decode 峰值显存利用长序列收益VAE patch 并行的收益在长序列解码高分辨率、长视频场景下最明显组合其他并行方式建议与 Tensor Parallel 或 CFG-Parallel 一起使用以获得最大显存节省。配置入口一览Python API 使用DiffusionParallelConfigvllm_omni/diffusion/data.pyCLI/serve 使用--vae-patch-parallel-size与--vae-parallel-modevllm_omni/entrypoints/cli/serve.py离线脚本参考 text_to_image.py模型支持矩阵参考 docs/user_guide/diffusion_features.md。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考