执行摘要

• 一句话：修复显式组件卸载与固定驻留冲突，拒绝冲突配置
• 推荐动作：该 PR 值得精读，尤其是 require_component_resident 中 explicit_residency_mode 与 canonical_residency_mode 的区分，这是配置校验设计中的关键权衡。测试用例覆盖全面，可作为类似冲突检测的参考。

功能与动机

根据 PR 描述，目标是“Reject a resident-only feature when that exact component was explicitly selected for component offload or layerwise offload through any supported option.” 即当用户显式选择了组件卸载或逐层卸载时，应拒绝仅驻留功能；同时“Preserve automatic placement: a resident-only feature may still reserve residency when the user did not explicitly choose an incompatible mode.” 确保用户未显式选择不兼容模式时，自动放置仍可被覆盖。这源于组件驻留要求与用户显式卸载配置之间的语义冲突，需要让用户显式选择优先。

实现拆解

实现分为两个层面：

1. 修改核心检查逻辑（python/sglang/multimodal_gen/runtime/server_args/server_args.py）：在 require_component_resident 方法中，将 configured_mode 的获取从 canonical_residency_mode(component_name) 改为 explicit_residency_mode(component_name)。这是因为 canonical_residency_mode 可能返回自动推导的驻留模式（例如基于内存预算的默认放置），而 explicit_residency_mode 仅返回用户显式指定的模式。此改动使得函数仅拒绝用户显式指定的非驻留模式，而不再误拒自动放置。同时更新了错误提示信息，从 from --component-residency 改为更通用的 from an explicit residency option，以涵盖所有显式卸载选项（如 cpu_offload_components、layerwise_offload_components 等）。

2. 新增测试覆盖（python/sglang/multimodal_gen/test/unit/test_server_args.py）：

   • 新增 test_resident_requirement_rejects_every_explicit_offload_surface：遍历所有显式卸载选项（component_residency 中的 component-offload 和 layerwise-offload、cpu_offload_components、text_encoder_cpu_offload、layerwise_offload_components），断言 require_component_resident 均抛出 ValueError。
   • 新增 test_resident_requirement_can_override_automatic_placement：在默认配置（memory_gb=16）下，explicit_residency_mode("text_encoder") 返回 None，且 residency_mode 不为 RESIDENT；调用 require_component_resident 后，residency_mode 变为 RESIDENT，验证自动放置可以被覆盖。

该变更属于配置校验语义的修正，不涉及运行时行为，仅影响参数解析阶段的冲突检测。

关键文件：

• python/sglang/multimodal_gen/runtime/server_args/server_args.py（模块 参数解析；类别 source；类型 core-logic；符号 require_component_resident）: 核心逻辑变更，修改 require_component_resident 的判定依据，使显式卸载配置被正确拒绝。
• python/sglang/multimodal_gen/test/unit/test_server_args.py（模块 参数测试；类别 test；类型 test-coverage；符号 test_resident_requirement_rejects_every_explicit_offload_surface, test_resident_requirement_can_override_automatic_placement）: 新增两个测试，覆盖所有显式卸载入口的拒绝行为以及自动放置的可覆盖性。

关键符号：require_component_resident

关键源码片段

python/sglang/multimodal_gen/runtime/server_args/server_args.py

核心逻辑变更，修改 require_component_resident 的判定依据，使显式卸载配置被正确拒绝。

# python/sglang/multimodal_gen/runtime/server_args/server_args.py
# 修改 require_component_resident 的判定逻辑
​
def require_component_resident(
    self, component_name: str, *, feature_name: str
) -> None:
    # 仅检查用户显式指定的模式，忽略自动推导的驻留模式（如基于内存的默认放置）
    configured_mode = self.explicit_residency_mode(component_name)
    # 若用户显式指定了非驻留模式，则抛出 ValueError 拒绝该功能
    if configured_mode is not None and configured_mode != RESIDENT:
        raise ValueError(
            f"{feature_name} requires {component_name!r} to be resident; "
            f"got {configured_mode!r} from an explicit residency option"
        )
    # 记录需要强制驻留的组件，覆盖自动放置
    self._required_resident_components.add(component_name)

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

新增两个测试，覆盖所有显式卸载入口的拒绝行为以及自动放置的可覆盖性。

# python/sglang/multimodal_gen/test/unit/test_server_args.py
# 新增测试覆盖显式卸载冲突检测
​
def test_resident_requirement_rejects_every_explicit_offload_surface(self):
    # 遍历所有显式卸载选项，确保 require_component_resident 均抛出 ValueError
    cases = (
        {"component_residency": ["text_encoder=component-offload"]},
        {"component_residency": ["text_encoder=layerwise-offload"]},
        {"cpu_offload_components": ["text_encoder"]},
        {"text_encoder_cpu_offload": True},
        {"layerwise_offload_components": ["text_encoder"]},
    )
    for kwargs in cases:
        with self.subTest(kwargs=kwargs):
            args = self._from_dict_with_task_type(
                ModelTaskType.T2V,
                kwargs={"performance_mode": "manual", **kwargs},
            )
            with self.assertRaisesRegex(ValueError, "explicit residency option"):
                args.require_component_resident(
                    "text_encoder", feature_name="test backend"
                )
​
# 验证无显式配置时，require_component_resident 可覆盖自动放置
def test_resident_requirement_can_override_automatic_placement(self):
    args = self._from_dict_with_task_type(ModelTaskType.T2V, memory_gb=16)
    # 未显式指定时，explicit_residency_mode 返回 None
    self.assertIsNone(args.explicit_residency_mode("text_encoder"))
    # 自动放置可能不是 RESIDENT
    self.assertNotEqual(args.residency_mode("text_encoder"), RESIDENT)
    # 调用后强制为 RESIDENT
    args.require_component_resident("text_encoder", feature_name="test backend")
    self.assertEqual(args.residency_mode("text_encoder"), RESIDENT)

评论区精华

本 PR 无 review 评论或讨论线程。

• 暂无高价值评论线程

风险与影响

• 风险：风险较低。主要风险点：

• 行为变化：依赖原有错误提示文本（包含 --component-residency）的外部脚本或测试可能受影响，但本 PR 已同步更新测试，且错误类型仍为 ValueError，仅消息文本变化。

• 语义边界：explicit_residency_mode 如果未覆盖所有显式卸载入口（例如 --component-residency 中的 resident 之外的模式），可能导致某些冲突未被拒绝，但测试已覆盖主要入口。
• 无回归风险：变更仅影响 require_component_resident 的判定，该函数调用方需确认其行为预期，但测试已覆盖关键场景。
• 影响：影响范围：
  • 用户：当显式配置组件卸载与 resident-only 功能（如某些注意力后端）冲突时，现在会得到明确报错，而非静默覆盖，提升了配置可预期性。
  • 系统：不影响运行时性能，仅影响参数校验阶段。
  • 团队：为扩散模型组件驻留逻辑的后续演进提供了更清晰的语义边界，便于维护。
  • 风险标记：配置冲突校验语义调整, 错误提示文本变化

关联脉络

• PR #36863 [diffusion] Fix image encoder parallel folding proposal: 同为扩散模型 server_args 相关修复，涉及组件配置逻辑。