# PR #25930 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[diffusion] chore: enable layerwise for wan
- 合并时间：2026-05-21 23:48
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/25930

---

# 执行摘要

- 一句话：Wan DiT layerwise 卸载默认开启
- 推荐动作：该 PR 值得阅读 `server_args_auto_tune.py` 中的条件判断与注释，它展示了显式 vs 隐式策略的典型设计权衡。但需注意 review 中未采纳的建议，可能是一个潜在的边界错误，建议团队在后续 PR 中修正。测试用例的设计也有参考价值，尤其是利用 mock 覆盖各种模型配置。

# 功能与动机

根据 PR 描述和性能分析，Wan T2V/I2V 模型的 DiT layerwise offload 可在无编译模式下略微降低延迟并将峰值驻留显存减少约一半。Prefetch 调优未能从增加 prefetch 大小中获得明显收益，因此保留当前默认行为。该 PR 旨在在 auto-tuner 拥有放置决策时自动为 Wan pipeline 配置启用 DiT layerwise offload，同时尊重用户的显式选择。

# 实现拆解

1. **新增 Wan 模型检测与 DiT layerwise 自动启用逻辑**：在 `server_args_auto_tune.py` 的 `_default_layerwise_components_for_unset_placement` 方法末尾，通过 `_is_wan_pipeline_config` 和 `auto_dit_layerwise_offload` 标记识别 Wan 配置，调用 `_should_auto_enable_dit_layerwise_offload` 决定是否将 `LAYERWISE_OFFLOAD_DIT_GROUP` 加入组件列表，并调用 `_set_default_wan_dit_offload_prefetch_size` 设置 prefetch 大小。
2. **分模式决策自动启用范围**：`_should_auto_enable_dit_layerwise_offload` 先过滤非 Wan、显式 `dit_cpu_offload`、使用 FSDP 或 cache-dit、平台不支持等情形。memory 模式对所有 Wan 启用，auto 模式仅对 Wan2.2 A14B 启用。
3. **设置默认 prefetch size**：`_set_default_wan_dit_offload_prefetch_size` 对 Wan2.2 A14B auto 模式且未显式设置时，将 `dit_offload_prefetch_size` 设为 2（实测最佳值）。
4. **简化 Wan pipeline 配置**：在 `wan.py` 中移除 `auto_dit_layerwise_offload_high_memory_disable_gb=130` 字段。
5. **单元测试覆盖**：在 `test_server_args.py` 新增 7 个测试用例，使用 mock 验证不同模型和模式下的自动启用行为及显式参数优先级。
6. **集成测试增强**：`test_server_common.py` 添加服务进程监视器 `_fail_if_server_stopped_or_crashed` 和带线程超时的生成函数 `_run_generation_with_server_watchdog`；`test_server_utils.py` 增加 `ServerContext.log_tail` 方法。
7. **CI 仪表盘调整**：`generate_diffusion_dashboard.py` 中 `MAX_HISTORY_RUNS` 从 14 增至 29。

关键文件：
- `python/sglang/multimodal_gen/runtime/server_args_auto_tune.py`（模块 自动调优；类别 source；类型 core-logic；符号 _should_auto_enable_dit_layerwise_offload, _is_wan2_2_a14b_pipeline_config, _set_default_wan_dit_offload_prefetch_size, _is_wan_pipeline_config）: 核心逻辑，新增自动启用 Wan DiT layerwise 的判断与入口。
- `python/sglang/multimodal_gen/test/unit/test_server_args.py`（模块 单元测试；类别 test；类型 test-coverage；符号 test_auto_wan2_2_a14b_layerwise_offload_adds_dit, test_auto_wan2_1_14b_layerwise_offload_uses_non_dit_default, test_auto_wan_layerwise_offload_preserves_explicit_dit_cpu_offload, test_auto_mova_layerwise_offload_does_not_implicitly_add_dit）: 单元测试覆盖自动启用条件与显式参数优先级。
- `python/sglang/multimodal_gen/test/server/test_server_common.py`（模块 集成测试；类别 test；类型 test-coverage；符号 _fail_if_server_stopped_or_crashed, _run_generation_with_server_watchdog, _target）: 集成测试增强：添加服务进程监视器与崩溃检测。
- `python/sglang/multimodal_gen/test/server/test_server_utils.py`（模块 测试工具；类别 test；类型 test-coverage；符号 log_tail）: 增加 log_tail 方法用于诊断服务端日志。
- `python/sglang/multimodal_gen/configs/pipeline_configs/wan.py`（模块 模型配置；类别 source；类型 core-logic）: 简化配置，移除未使用的高内存禁用阈值。
- `scripts/ci/utils/diffusion/generate_diffusion_dashboard.py`（模块 CI 脚本；类别 infra；类型 infrastructure）: 扩展 CI dashboard 历史窗口。

关键符号：_should_auto_enable_dit_layerwise_offload, _is_wan2_2_a14b_pipeline_config, _set_default_wan_dit_offload_prefetch_size, _is_wan_pipeline_config, _fail_if_server_stopped_or_crashed, _run_generation_with_server_watchdog, log_tail

## 关键源码片段

### `python/sglang/multimodal_gen/runtime/server_args_auto_tune.py`

核心逻辑，新增自动启用 Wan DiT layerwise 的判断与入口。

```python
    def _should_auto_enable_dit_layerwise_offload(self) -> bool:
        """判断是否应在默认组件卸载列表中自动加入 DiT 层以启用 layerwise offload. 
        
        当前仅对 Wan 模型生效，且受显式参数保护。
        """
        args = self.server_args

        # 仅限 Wan pipeline 配置
        if not self._is_wan_pipeline_config():
            return False
        # 需模型部署配置允许自动启用
        if not self._deployment_config().auto_dit_layerwise_offload:
            return False

        # 以下任一条件满足时不应自动启用：
        # - 模型配置了 DMD 去噪步数（特殊模型变体）
        # - 平台默认未启用此功能
        # - 用户启用了 cache-dit 模式
        # - 用户已启用 FSDP（与 DiT offload 竞争）
        # - 用户显式设置了 dit_cpu_offload（无论值为何）
        if (
            args.pipeline_config.dmd_denoising_steps is not None
            or not current_platform.enable_dit_layerwise_offload_for_wan_by_default()
            or envs.SGLANG_CACHE_DIT_ENABLED
            or args.use_fsdp_inference
            or args.is_arg_explicitly_set("dit_cpu_offload")
        ):
            return False

        # memory 模式：优先节省内存，对所有 Wan 模型启用
        if args.performance_mode == "memory":
            return True

        # auto 模式：性能优先，仅 Profiling 确认 Wan2.2 A14B 有明显收益
        return (
            args.performance_mode == "auto" and self._is_wan2_2_a14b_pipeline_config()
        )

```

### `python/sglang/multimodal_gen/test/unit/test_server_args.py`

单元测试覆盖自动启用条件与显式参数优先级。

```python
    def test_auto_wan2_2_a14b_layerwise_offload_adds_dit(self):
        """当 Wan2.2 A14B 模型在 auto 模式下且未设置显式覆盖时，
        应自动将 "dit" 加入 layerwise_offload_components 并设置 prefetch=2，
        同时自动禁用粗粒度的 dit_cpu_offload。"""
        for pipeline_config, model_path in (
            (Wan2_2_T2V_A14B_Config(), "Wan-AI/Wan2.2-T2V-A14B-Diffusers"),
            (Wan2_2_I2V_A14B_Config(), "Wan-AI/Wan2.2-I2V-A14B-Diffusers"),
        ):
            with self.subTest(pipeline_config=pipeline_config.__class__.__name__):
                args = self._from_dict_with_pipeline_config(
                    pipeline_config,
                    kwargs={
                        "model_path": model_path,
                        "performance_mode": "auto",
                    },
                )

                # layerwise offload 组件应非空（包含非 DiT 部分）
                self.assertTrue(args.layerwise_offload_components)
                # 不应自动启用 FSDP（因为只设定了 auto 模式）
                self.assertFalse(args.use_fsdp_inference)
                # DiT CPU offload 应被自动禁用（因为改为 layerwise）
                self.assertFalse(args.dit_cpu_offload)
                # text_encoder 与 image_encoder 默认不使用 CPU offload
                self.assertFalse(args.text_encoder_cpu_offload)
                self.assertFalse(args.image_encoder_cpu_offload)
                # prefetch size 应为 2（默认经验值）
                self.assertEqual(args.dit_offload_prefetch_size, 2)
                # 组件列表应包含 "dit" 在首位
                self.assertEqual(
                    args.layerwise_offload_components,
                    ["dit", "text_encoder", "image_encoder", "vae"],
                )

```

# 评论区精华

在代码审查中，`gemini-code-assist[bot]` 指出 `_should_auto_enable_dit_layerwise_offload` 缺乏对 `dit_layerwise_offload` 显式设置的检查，建议添加 `not args.is_arg_explicitly_set('dit_layerwise_offload')` 条件，以避免用户通过 `--dit-layerwise-offload false` 显式禁用时仍被自动启用。该建议未被采纳，最终合并代码未包含此检查。这意味着用户如果显式设置了 `--dit-layerwise-offload false`，自动调优器仍可能在 Wan2.2 A14B 的 auto 模式下自动启用 DiT layerwise offload，与 PR 标题声称的“尊重显式用户选择”不完全一致。

- 应检查 dit_layerwise_offload 显式设置 (design): 未采纳，最终合并代码未包含此检查，可能仍会覆盖用户显式禁用。

# 风险与影响

- 风险：
 - **自动覆盖显式选项**：用户显式设置 `--dit-layerwise-offload false` 后，自动逻辑仍可能启用 DiT layerwise offload（详见评论区精华）。
 - **memory 模式全量启用风险**：移除了 `auto_dit_layerwise_offload_high_memory_disable_gb` 配置，所有 Wan 模型在 memory 模式都会启用 DiT layerwise offload，可能对高带宽 GPU 服务器造成性能退化（CPU-GPU 传输开销）。
 - **prefetch size 硬编码**：自动设置 prefetch=2，缺少自适应或用户修改手段。
 - **测试覆盖有限**：单元测试使用 mock 避免实际模型加载，集成测试仅覆盖基础场景，多 GPU 和异构环境未验证。
 - **集成测试 watchdog 风险**：线程同步若超时设置不当可能导致误判失败。
- 影响：
 - **用户影响**：Wan 模型用户默认获得显存节省（约 50%），但可能因自动策略与期望不符造成困惑。memory 模式用户的推理行为可能变化。
 - **系统影响**：自动调优器对 Wan 模型增加决策路径，但整体复杂度可控。
 - **团队维护**：新增约 370 行代码，主要集中在测试和自动调优逻辑。需要为后续其他模型扩展类似功能时提供参考。
 - **退化风险**：若用户对性能敏感且不需要 DiT layerwise，可能希望关闭，但当前自动开启可能未被注意到。
 - 风险标记：自动覆盖显式选项 , prefetch size 硬编码 , 缺少完整测试覆盖 , memory 模式可能引起性能退化

# 关联脉络

- 暂无明显关联 PR