执行摘要

• 一句话：扩散模型新增性能模式自动选择
• 推荐动作：本 PR 的设计模式（ModelDeploymentConfig 契约 + ServerArgsAutoTuner 分段调优）具有很强的借鉴价值，适合多模型部署平台参考。建议仔细阅读 server_args_auto_tune.py 和 model_deployment_config.py 的实现。Review 中提出的三个问题尚未解决，在后续使用中需要注意相关风险。

功能与动机

根据 PR 描述，动机是提供一个统一的 --performance-mode / --mode CLI 参数，让用户无需手动指定大量参数即可获得针对不同模型优化的部署配置。同时将自动调优决策逻辑从 ServerArgs 中移至专门的模块，并通过 PipelineConfig 方法声明模型特定提示，避免硬编码类名检查。

实现拆解

1. 新增部署配置数据模型：在 model_deployment_config.py 中定义 ModelDeploymentConfig 冻结数据类，包含 auto_dit_layerwise_offload、auto_disable_component_offload_min_available_memory_gb、fsdp_auto_min_available_memory_gb 等字段，每个 PipelineConfig 子类通过 get_model_deployment_config() 返回自己的配置。

2. 创建 ServerArgsAutoTuner 类：在 server_args_auto_tune.py 中新增此类，接收 ServerArgs 引用。核心方法 adjust() 根据归一化后的 performance_mode（speed/memory）设置 FSDP、CFG 并行、offload 等默认值。另外提供 maybe_adjust_auto_component_residency_after_offload()、maybe_adjust_auto_fsdp_with_offload_enabled()、maybe_adjust_auto_dit_layerwise_offload() 等方法，用于在 auto 模式下根据可用 GPU 内存动态调整。

3. 集成到 ServerArgs：在 server_args.py 中新增 performance_mode 字段（默认 auto），导入 ServerArgsAutoTuner，在 _adjust_parameters() 中依次调用调优器的各个阶段，替代原有的直接 offload 调节。同时删除了原有硬编码的 Wan 层间 offload 阈值常量，改为由 deployment config 提供。

4. 各模型声明部署提示：在 wan.py、ltx_2.py、mova.py、qwen_image.py、zimage.py 等 PipelineConfig 子类中实现 get_model_deployment_config()，返回适合该模型的 ModelDeploymentConfig 实例（如 LTX 需要 layerwise offload，Wan 需要内存阈值等）。

5. LoRA 管道增强：在 lora_pipeline.py 中新增 LoRA 合并模式支持，通过 lora_merge_mode 参数（merge/dynamic/auto）控制是否合并权重；在 FSDP 场景下自动选择 dynamic 模式以避免全量 gather。

6. 测试与文档：在 test_server_args.py 中新增大量单元测试覆盖各模式组合、内存边界条件；在 test_server_common.py 中重构性能日志输出，移除旧的基线改进检测，改为每次运行打印性能日志。文档更新包括 deployment_cookbook.md 和 OOM 指南。

关键文件：

• python/sglang/multimodal_gen/runtime/server_args_auto_tune.py（模块 调优引擎；类别 source；类型 core-logic；符号 ServerArgsAutoTuner, init, _deployment_config, adjust）: 新增调优器核心，实现性能模式到具体参数的映射。
• python/sglang/multimodal_gen/configs/pipeline_configs/model_deployment_config.py（模块 部署契约；类别 source；类型 data-contract；符号 ModelDeploymentConfig）: 新增部署配置数据契约，模型通过此接口声明调优提示。
• python/sglang/multimodal_gen/runtime/server_args.py（模块 服务器参数；类别 source；类型 core-logic；符号 _uses_ltx23_snapshot_two_stage_residency）: 集成调优器，新增 performance_mode 和 lora_merge_mode 字段，修改参数调整流程。
• python/sglang/multimodal_gen/runtime/pipelines_core/lora_pipeline.py（模块 LoRA管道；类别 source；类型 dependency-wiring；符号 _uses_dtensor_weights, _has_active_unmerged_lora, _is_lora_effective_for_module, _resolve_lora_merge_mode）: 新增 LoRA 合并模式支持，处理 FSDP 场景下的权重合并策略。
• python/sglang/multimodal_gen/test/unit/test_server_args.py（模块 单元测试；类别 test；类型 test-coverage；符号 _from_dict_with_pipeline_config, get_available_gpu_memory, test_pipeline_configs_declare_auto_tune_hints, test_manual_mode_preserves_unset_performance_args）: 大量新增单元测试覆盖性能模式组合和内存边界条件。
• python/sglang/multimodal_gen/configs/pipeline_configs/wan.py（模块 模型配置；类别 source；类型 core-logic；符号 get_model_deployment_config）: Wan 模型声明部署配置，配置自动 layerwise offload 阈值。

关键符号：ServerArgsAutoTuner.adjust, maybe_adjust_auto_component_residency_after_offload, maybe_adjust_auto_fsdp_with_offload_enabled, maybe_adjust_auto_dit_layerwise_offload, finalize_auto_flags, get_model_deployment_config, _uses_dtensor_weights, _resolve_lora_merge_mode, _should_merge_lora_for_layers

关键源码片段

python/sglang/multimodal_gen/runtime/server_args_auto_tune.py

新增调优器核心，实现性能模式到具体参数的映射。

class ServerArgsAutoTuner:
    # 根据性能模式自动调整 server_args
    def __init__(self, server_args: 'ServerArgs'):
        self.server_args = server_args
        self._explicit_memory_policy = self._has_explicit_memory_policy()
​
    def adjust(self) -> None:
        # 归一化模式名称（如 aggressive->speed, conservative->memory）
        args = self.server_args
        args.performance_mode = self._normalize_performance_mode()
​
        # CPU 平台不支持 FSDP/offload，直接返回
        if current_platform.is_cpu():
            return
​
        if args.performance_mode == 'speed':
            # 吞吐优先：尽可能使用 FSDP + CFG 并行
            if args.num_gpus >= 2 and self._can_apply_fsdp_policy(require_memory_headroom=False):
                self._set_gpu_resident_defaults(use_fsdp=True)
                self._enable_cfg_parallel_if_supported()
            else:
                self._set_gpu_resident_defaults(use_fsdp=False)
            return
​
        if args.performance_mode == 'memory':
            # 内存优先：尽可能 offload，但也保留 FSDP 显式启用
            if args.use_fsdp_inference:
                self._set_gpu_resident_defaults(use_fsdp=True)
                return
            args.use_fsdp_inference = False
            if self._can_apply_dit_layerwise_offload_policy():
                # 逐层 offload 可以减少显存峰值
                self._set_layerwise_offload_defaults()
            else:
                self._set_component_offload_defaults()
            return

python/sglang/multimodal_gen/configs/pipeline_configs/model_deployment_config.py

新增部署配置数据契约，模型通过此接口声明调优提示。

from dataclasses import dataclass
from typing import Literal
​
OffloadComponentName = Literal['dit', 'text_encoder', 'image_encoder']
​
​
@dataclass(frozen=True)
class ModelDeploymentConfig:
    # 是否启用 DiT 逐层 offload（对 Wan/LTX 等模型）
    auto_dit_layerwise_offload: bool = False
    # 若可用内存超过此值，则禁用手层 offload 以提升速度
    auto_dit_layerwise_offload_high_memory_disable_gb: float | None = None
    # 若可用内存超过此值，则自动禁用组件 offload（全部驻留 GPU）
    auto_disable_component_offload_min_available_memory_gb: float | None = None
    # 可被自动驻留的组件列表
    auto_disable_component_offload_components: tuple[OffloadComponentName, ...] = (
        'dit', 'text_encoder', 'image_encoder',
    )
    # 自动启用 FSDP 所需的最小可用内存
    fsdp_auto_min_available_memory_gb: float | None = None
    # FSDP 自动启用需要 CFG 并行支持
    fsdp_auto_requires_cfg: bool = True
    # FSDP 自动启用需要默认并行设置
    fsdp_auto_requires_default_parallelism: bool = True

评论区精华

1. GPU 内存检测准确性：gemini-code-assist[bot] 建议在 get_available_gpu_memory 中使用 empty_cache=True，避免缓存导致检测值偏高，影响 FSDP 自动启用决策。

2. Memory 模式下 FSDP 行为：评论指出在 memory 模式且显式启用 FSDP 时，调优器会禁用 encoder CPU offload，这与 memory 模式目标矛盾，建议保持 offload。

3. 逻辑重复：自动启用 layerwise offload 的逻辑在 server_args_auto_tune.py 和 ServerArgs._adjust_platform_specific 中存在重复，建议提取为辅助方法。

• GPU 内存检测应使用 empty_cache=True (correctness): 未在 PR 中修改，风险仍然存在。
• Memory 模式下 FSDP 行为反直觉 (design): 未在 PR 中修改，可能已记录为后续改进。
• 自动 layerwise offload 逻辑重复 (design): PR 中未完全消除重复，维护风险依然存在。

风险与影响

• 风险：
  • GPU 内存检测不准确：server_args_auto_tune.py 中 _get_min_available_device_memory_gb() 未使用 empty_cache=True，在共享环境或单元测试中可能因缓存导致错误决策（如错误启用 FSDP），引发 OOM。
  • Memory 模式下 FSDP 反直觉：当用户设置 use_fsdp_inference=True 且选择 memory 模式时，调优器会调用 _set_gpu_resident_defaults(use_fsdp=True) 关闭 encoder offload，可能造成不必要的 GPU 内存消耗。
  • 重复逻辑维护风险：server_args_auto_tune.py 与 ServerArgs._adjust_platform_specific 中存在相似 offload 决策代码，未来修改可能导致行为不一致。
  • 影响面广泛：79 个文件修改，涉及扩散管线各个环节，回归风险高。
  • 影响：用户影响：引入 --performance-mode 简化配置，但 auto 模式的自动决策可能在陌生硬件上产生非预期行为（如 OOM 或性能回退）。原手动参数仍可用，但默认 behavior 变化（performance_mode 默认 auto）。

系统影响：启动时增加内存检测和策略计算，开销较小。多 GPU 场景下 FSDP 自动启用可能增加通信竞争。

团队影响：后续模型必须实现 get_model_deployment_config() 才能获得最优 auto 模式配置；维护者需熟悉双层调优逻辑。

• 风险标记：GPU 内存检测不准确, 自动调优反直觉行为, 重复逻辑维护成本, 影响面广泛

关联脉络

• PR #20930 feat(multimodal_gen): plumb max_sequence_length via diffusers_kwargs: 同属 multimodal_gen 扩散管线，涉及多 GPU 部署配置的调整。