执行摘要

• 一句话：VAE channels_last_3d 默认策略改为模型感知自动选择
• 推荐动作：该 PR 是性能优化与策略精细化的良好实践，设计决策基于详细 benchmark 数据，可信赖。建议部署前确认关键模型在预期默认值下的表现。若用户对特定模型有明确偏好，可通过设置 SGLANG_DIFFUSION_VAE_CHANNELS_LAST_3D=true 或 false 覆盖默认策略。

功能与动机

PR body 中的 benchmark 数据表明，全局开启 channels_last_3d 对于某些模型（如多 GPU Wan、LTX、FastHunyuan）会导致显著减速（最高 46.8% 的 VAE 解码延迟增加），而 QwenImage 和单 GPU Wan 则受益。因此需要更精细的默认策略，在避免性能退化的同时最大化加速效果。

实现拆解

1. 修改环境变量默认值和类型：在 envs.py 中，将 SGLANG_DIFFUSION_VAE_CHANNELS_LAST_3D 的默认值从 True 改为 "auto"，类型从 bool 改为 str，读取函数从 _lazy_bool 改为 _lazy_str。这为 "auto" 语义提供支持。

2. 重写决策函数：在 vae_loader.py 中，_should_use_channels_last_3d 函数现在优先检查环境变量是否明确设置为 true 或 false，若是则直接返回相应值。否则（或为 auto 时），根据 server_args.pipeline_config.__class__.__name__ 和 server_args.num_gpus 决定默认值。规则是：QwenImage 系列默认启用；单 GPU 的 Wan 系列默认启用；其他模型默认禁用。

3. 新增单元测试：在 test_vae_loader.py 中，添加了 _FakeServerArgs 辅助类和多个测试用例，覆盖 QwenImage、单 GPU Wan、多 GPU Wan、LTX 等场景，验证预期默认值是否正确。

4. 维持 parity 测试：在 test_component_accuracy_1_gpu.py 和 test_component_accuracy_2_gpu.py 中，保留并调整了 VAE_CHANNELS_LAST_3D_PARITY_CASES 列表（仅格式调整），确保已有准确性测试继续执行。

5. 更新测试数据版本：test_utils.py 中的 SGL_TEST_FILES_CI_DATA_REVISION 更新到新哈希，以同步一致性测试的参考数据。

关键文件：

• python/sglang/multimodal_gen/runtime/loader/component_loaders/vae_loader.py（模块 VAE加载器；类别 source；类型 core-logic；符号 _should_use_channels_last_3d）: 核心逻辑：模型感知的 channels_last_3d 策略决策函数
• python/sglang/multimodal_gen/envs.py（模块 环境变量；类别 source；类型 configuration）: 环境变量默认值从 True 改为 "auto"，类型从 bool 改为 str
• python/sglang/multimodal_gen/test/unit/test_vae_loader.py（模块 单元测试；类别 test；类型 test-coverage；符号 _FakeServerArgs, QwenImagePipelineConfig, WanT2V480PConfig, FastWan2_2_TI2V_5B_Config）: 新增大量单元测试，覆盖各种模型配置的默认策略行为
• python/sglang/multimodal_gen/test/server/test_component_accuracy_1_gpu.py（模块 精度测试；类别 test；类型 test-coverage）: 调整 VAE_CHANNELS_LAST_3D_PARITY_CASE_IDS 格式，维持 parity 测试
• python/sglang/multimodal_gen/test/server/test_component_accuracy_2_gpu.py（模块 精度测试；类别 test；类型 test-coverage）: 调整 VAE_CHANNELS_LAST_3D_PARITY_CASE_IDS 格式，维持 parity 测试
• python/sglang/multimodal_gen/test/test_utils.py（模块 测试工具；类别 test；类型 test-coverage）: 更新 SGL_TEST_FILES_CI_DATA_REVISION 哈希值

关键符号：_should_use_channels_last_3d

关键源码片段

python/sglang/multimodal_gen/runtime/loader/component_loaders/vae_loader.py

核心逻辑：模型感知的 channels_last_3d 策略决策函数

def _should_use_channels_last_3d(
    server_args: ServerArgs | None, component_name: str
) -> bool:
    # 只在 VAE / video VAE 组件且 CUDA / ROCM 平台下考虑
    if component_name not in ('vae', 'video_vae') or not (
        current_platform.is_cuda() or current_platform.is_rocm()
    ):
        return False
​
    # 用户可以通过环境变量强制开启或关闭
    override = os.getenv(VAE_CHANNELS_LAST_3D_ENV)
    if override is not None and override.strip().lower() != 'auto':
        return get_bool_env_var(VAE_CHANNELS_LAST_3D_ENV)
​
    # 没有明确设置或为 auto 时，根据模型和 GPU 数量自动判断
    if server_args is None:
        return False
​
    pipeline_name = server_args.pipeline_config.__class__.__name__
​
    # QwenImage 系列默认启用
    if pipeline_name.startswith('QwenImage'):
        return True
​
    # 单 GPU 的 Wan 系列默认启用（包括变体）
    if 'Wan' in pipeline_name and server_args.num_gpus == 1:
        return True
​
    # 其他模型（LTX, Hunyuan, Helios 等）默认禁用
    return False

评论区精华

无实质性讨论。gemini-code-assist bot 评论指出 PR 更新了 VAE 加载器并增加了 LTX 2.3 parity 测试，无进一步反馈。

• Code review by gemini-code-assist (other): 无问题。

风险与影响

• 风险：
  1. 性能回退风险：新策略自动选择默认值，若模型名称不匹配预期模式（例如未来新增的模型不以 'QwenImage' 开头或不包含 'Wan'），将默认禁用 channels_last_3d，可能错失加速机会。
  2. 依赖模型命名规范：决策基于 pipeline_config.__class__.__name__ 字符串匹配，如果命名规则变化，策略可能失效。
  3. 环境变量行为变更：之前默认是 True，现在改为 auto，已显式设置环境变量的用户不受影响，但依赖默认开启的用户可能发现 VAE 解码速度变化（若模型默认被禁用）。
  4. server_args 为空保护：当 server_args 为 None 时函数返回 False，可能隐藏某些边缘情况（如某些调用点未传递 server_args）。
     - 影响：影响范围：所有使用 diffusion VAE 的推理路径。QwenImage 和单 GPU Wan 用户获得约 5-10% 的 VAE 解码加速；多 GPU Wan、LTX、Hunyuan 等用户避免之前可能存在的性能降级；其他模型行为不变（由于之前全局启用可能已降速，现在默认禁用则恢复）。需要用户注意环境变量行为变化。测试覆盖了主流模型，风险可控。
     - 风险标记：性能回退风险, 依赖模型命名规范, 环境变量行为变化

关联脉络

• 暂无明显关联 PR