执行摘要

• 一句话：H3 注意力后端准入改为按 packed varlen 能力自证，显式配置冲突 fail closed
• 推荐动作：值得精读。该 PR 展示了两个可借鉴的设计决策：一是用“实现类是否覆写 forward_varlen”这种 introspection 从实现代码自证能力，替代后端名 allowlist；二是把准入校验从 per-request 路径上移到启动期 validate_server_args，并通过 fail closed 消除静默降级。阅读时重点关注 attention_backend.py 的 AttentionRequirements 契约设计与 selector.py 的 fail-closed 行为变更边界。

功能与动机

PR body 明确说明动机："replace MiniMax H3's handwritten DiT backend allowlist with a semantic packed-varlen requirement... derive that requirement from the backend implementation, so a backend that implements packed varlen is admitted without an H3-specific name change... fail closed when an explicitly selected backend conflicts with a legacy model constraint instead of silently selecting another backend"。核心诉求是把模型兼容性绑定到可执行的注意力操作（packed varlen）而非后端名字上，新增后端只要真正实现了 forward_varlen 即可被 H3 自动准入，无需改模型配置；显式配置冲突时宁可直接报错也不静默降级。

实现拆解

1. 引入能力契约：runtime/layers/attention/backends/attention_backend.py 新增 frozen dataclass AttentionRequirements（当前仅含 packed_varlen: bool = False 字段），并在 AttentionBackend 基类新增 supports_packed_varlen() 与 unsupported_requirements() 两个 classmethod。前者通过 cls.get_impl_cls().forward_varlen is not AttentionImpl.forward_varlen 判定实现类是否覆写 packed varlen 入口，让能力从实现代码自证；后者返回当前后端不满足的需求描述元组，供选择器 fail closed。

2. 选择器 fail-closed 改造：runtime/layers/attention/selector.py 的 get_attn_backend() 新增 attention_requirements 参数，在解析出最终后端后调用 unsupported_requirements() 校验，不满足即抛 ValueError（如 does not implement packed varlen attention）；_cached_get_attn_backend() 中，显式选择的后端不在该层支持集合内时，由原来的 debug 日志加 selected_backend = None 静默回退改为直接抛错。注意该函数带 @cache 装饰器且是模块级共享路径，此行为变更对所有 diffusion 管线生效。

3. H3 侧删除 allowlist、改为声明需求：configs/models/dits/minimax_h3.py 删除 MiniMaxH3DiTArchConfig._supported_attention_backends 字段及 AttentionBackendEnum 导入；runtime/models/dits/minimax_h3.py 中 _minimax_h3_attention_core_impl 与 _resolve_attention_backend_once 不再传 supported_attention_backends，改传 attention_requirements=AttentionRequirements(packed_varlen=True)，并移除 MiniMaxH3Attention 与 MiniMaxH3DiTModel 上的 _supported_attention_backends 引用；configs/pipeline_configs/minimax_h3.py 的 validate_server_args() 在启动早期（大组件下载前）读取 component_attention_backends 的 transformer 条目或全局 attention_backend，统一转成 AttentionBackendEnum 后调用 get_attn_backend(..., attention_requirements=AttentionRequirements(packed_varlen=True)) 做一次性准入校验。

4. 测试与配套调整：test_minimax_h3_admission.py 新增 test_validate_server_args_requires_packed_varlen_backend，断言 validate_server_args 以 SAGE_ATTN 加 packed_varlen=True 调用 get_attn_backend 且后端不支持时抛错；test_cuda_attention_backend.py 新增 test_explicit_backend_rejected_by_a_model_fails_closed，并在 setUp 中加入 _cached_get_attn_backend.cache_clear() 防止缓存污染；gpu_cases.py 移除 LTX2 用例的 --component-attention-backends transformer=fa 显式覆盖，让 LTX2 恢复按层自动选择。

5. 提交演进：6 个提交中，前两个完成核心机制（varlen 推导 → 能力化准入），第三个把 admission 断言从 partition stage 的 per-request 路径迁移到 validate_server_args（启动期一次校验），第四个 black 格式化，第五个重跑 CI，第六个调整 LTX2 用例。

关键文件：

• python/sglang/multimodal_gen/runtime/layers/attention/backends/attention_backend.py（模块 注意力后端；类别 source；类型 core-logic；符号 AttentionRequirements, supports_packed_varlen, unsupported_requirements）: 新增 AttentionRequirements 契约与 supports_packed_varlen / unsupported_requirements 两个 classmethod，是“能力自证 + fail closed”机制的核心。
• python/sglang/multimodal_gen/runtime/layers/attention/selector.py（模块 后端选择器；类别 source；类型 core-logic；符号 get_attn_backend, _cached_get_attn_backend）: get_attn_backend 新增 attention_requirements 校验；_cached_get_attn_backend 由静默回退改为抛错，行为影响所有 diffusion 管线。
• python/sglang/multimodal_gen/configs/pipeline_configs/minimax_h3.py（模块 管线配置；类别 source；类型 dependency-wiring；符号 MiniMaxH3PipelineConfig.validate_server_args）: validate_server_args 在启动期对显式后端做 packed varlen 准入校验，构成“一次性校验”的落点。
• python/sglang/multimodal_gen/configs/models/dits/minimax_h3.py（模块 模型配置；类别 source；类型 data-contract；符号 MiniMaxH3DiTArchConfig）: 删除 _supported_attention_backends allowlist 字段，是“按能力而非名字准入”的模型侧落点。
• python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py（模块 模型运行时；类别 source；类型 data-contract；符号 _minimax_h3_attention_core_impl, _resolve_attention_backend_once, MiniMaxH3Attention）: 注意力核心路径改用 AttentionRequirements(packed_varlen=True) 声明需求，替代原来的 allowlist 传参。
• python/sglang/multimodal_gen/test/unit/test_minimax_h3_admission.py（模块 准入测试；类别 test；类型 test-coverage；符号 test_validate_server_args_requires_packed_varlen_backend）: 新增 validate_server_args 阶段的能力准入断言，锁定“启动期一次性校验”行为。
• python/sglang/multimodal_gen/test/unit/test_cuda_attention_backend.py（模块 后端测试；类别 test；类型 test-coverage；符号 test_explicit_backend_rejected_by_a_model_fails_closed）: 验证显式后端被模型拒绝时 fail closed，并清理 _cached_get_attn_backend 缓存避免断言污染。
• python/sglang/multimodal_gen/test/server/gpu_cases.py（模块 集成用例；类别 test；类型 test-coverage）: LTX2 用例移除 transformer=fa 显式覆盖，适配 fail-closed 语义并恢复按层选择。

关键符号：AttentionRequirements, AttentionBackend.supports_packed_varlen, AttentionBackend.unsupported_requirements, get_attn_backend, _cached_get_attn_backend, MiniMaxH3PipelineConfig.validate_server_args, _minimax_h3_attention_core_impl, MiniMaxH3DiTModel._resolve_attention_backend_once

关键源码片段

python/sglang/multimodal_gen/runtime/layers/attention/backends/attention_backend.py

新增 AttentionRequirements 契约与 supports_packed_varlen / unsupported_requirements 两个 classmethod，是“能力自证 + fail closed”机制的核心。

# 节选自 python/sglang/multimodal_gen/runtime/layers/attention/backends/attention_backend.py
# SPDX-License-Identifier: Apache-2.0
​
from dataclasses import dataclass
​
from sglang.multimodal_gen.runtime.platforms import AttentionBackendEnum
​
​
@dataclass(frozen=True)
class AttentionRequirements:
    """调用方需要的语义化注意力能力，与后端名称解耦。
​
    模型/管线只声明需要 packed varlen，不再维护模型到后端名列表，
    新增后端无需改动任何模型配置即可被准入。
    """
​
    packed_varlen: bool = False
​
​
class AttentionBackend(ABC):
    """抽象注意力后端。"""
​
    @staticmethod
    @abstractmethod
    def get_impl_cls() -> type["AttentionImpl"]:
        raise NotImplementedError
​
    @classmethod
    def supports_packed_varlen(cls) -> bool:
        # 用实现类是否覆写 forward_varlen 自证能力：基类版本是占位实现，
        # 只有真正实现 packed varlen 的子类才会覆写它。
        # 能力声明跟随实现代码，避免后端名 allowlist 的双份维护。
        return cls.get_impl_cls().forward_varlen is not AttentionImpl.forward_varlen
​
    @classmethod
    def unsupported_requirements(
        cls, requirements: AttentionRequirements
    ) -> tuple[str, ...]:
        # 返回当前后端无法满足的需求描述；空元组表示全部满足。
        # selector 依据该结果 fail closed，而不是静默换用别的后端。
        if requirements.packed_varlen and not cls.supports_packed_varlen():
            return ("packed varlen attention",)
        return ()

python/sglang/multimodal_gen/runtime/layers/attention/selector.py

get_attn_backend 新增 attention_requirements 校验；_cached_get_attn_backend 由静默回退改为抛错，行为影响所有 diffusion 管线。

# 节选自 python/sglang/multimodal_gen/runtime/layers/attention/selector.py
​
def get_attn_backend(
    head_size: int,
    dtype: torch.dtype,
    supported_attention_backends: set[AttentionBackendEnum] | None = None,
    selected_attention_backend: AttentionBackendEnum | None = None,
    attention_requirements: AttentionRequirements | None = None,
) -> type[AttentionBackend]:
    # ... 环境变量 / server_args / 组件约束的后端解析逻辑略 ...
​
    attention_backend_cls = _cached_get_attn_backend(
        head_size,
        dtype,
        be_tuple,
        selected_backend,
    )
​
    backend_name = attention_backend_cls.get_enum().name.lower()
    # 能力校验放在最终后端解析完成之后：无论后端来自显式指定、平台默认
    # 还是组件约束，都必须满足 AttentionRequirements，否则启动即报错。
    unsupported_requirements = attention_backend_cls.unsupported_requirements(
        attention_requirements or AttentionRequirements()
    )
    if unsupported_requirements:
        raise ValueError(
            f"Attention backend '{backend_name}' does not implement "
            f"{', '.join(unsupported_requirements)}"
        )
    reason = "component constraint" if backend_name == constraint_backend else None
    if not _record_component_attn_backend(backend_name, reason):
        logger.info_once(f"Using {backend_name} attention backend")
    return attention_backend_cls
​
​
# _cached_get_attn_backend 内部的关键控制流（节选）：
# 显式选择的后端不在该层支持集合内时，旧逻辑只记 debug 日志并把
# selected_backend 置为 None（静默回退平台默认后端）；新逻辑直接抛错，
# 消除显式配置被悄悄忽略的隐性降级。
elif selected_backend is not None and not _is_backend_supported(
    selected_backend, supported_attention_backends
):
    supported_attention_backends_str = [str(b) for b in supported_attention_backends]
    raise ValueError(
        f"Attention backend '{selected_backend}' is not supported by this "
        f"attention layer; supported backends: {supported_attention_backends_str}"
    )

评论区精华

PR 没有任何 review 评论；5 条 issue 评论全部是作者触发的 /tag-and-rerun-ci（CI 重跑指令）。值得注意的设计演进来自提交历史：提交 d33c04c 说明 per-request 的后端 admission 断言原在 partition stage，后迁移到 validate_server_args 一次性执行，测试断言也随之从 partition stage 迁移到 server-args 校验——即把昂贵的后端解析与准入从请求热路径搬到启动期。

• 后端能力校验的时机与位置 (design): 采用启动期 validate_server_args 一次性校验，避免每请求重复解析后端能力。

风险与影响

• 风险：
  1. 能力自证的脆弱性：supports_packed_varlen 依赖 AttentionImpl.forward_varlen 基类占位存在且子类覆写；若某后端通过包装器、别名赋值等方式引入 forward_varlen，判定可能失真（假阴性导致误拒）。
  2. 全局 fail-closed 行为变更：_cached_get_attn_backend 对 multimodal_gen 下所有注意力管线生效，此前“显式后端不在支持集合内则静默回退”的存量配置现在会直接启动失败；这是 PR 声明的意图，但对错误配置属于兼容性 break。
  3. 枚举转换缺失容错：configs/pipeline_configs/minimax_h3.py 中 AttentionBackendEnum[str(attention_backend).strip().upper()] 对非法字符串直接抛 KeyError，而 selector 原有同类转换带有更友好的 ValueError 包装，启动报错信息质量略降。
  4. 配置面删除：_supported_attention_backends 从 MiniMaxH3DiTArchConfig 移除，仓库内引用已同步清理，但外部自定义配置若引用该字段会报错。
  5. LTX2 用例行为变化：移除 transformer=fa 显式覆盖后，CI 用例改由按层默认选择后端，若默认后端与 FA 存在数值或性能差异，需关注基线波动（提交 831bb77 专门处理）。
• 影响：影响范围集中在 multimodal_gen（diffusion）子系统：
  • 用户侧：MiniMax-H3 用户显式指定不支持 packed varlen 的后端时，启动期即可得到明确报错，而非运行期静默降级；其他 diffusion 管线的显式后端冲突配置同样会从静默回退变为硬失败。
  • 系统侧：AttentionRequirements 成为通用能力契约，任何模型均可声明需求，后端无需再被模型 allowlist 逐一点名；validate_server_args 阶段的一次性校验把准入从请求热路径移出。
  • 团队侧：新增后端（如 USPAttention、新 NPU 后端）只要实现 forward_varlen 即可被 H3 准入，后续维护成本显著降低。
  • 风险标记：全局后端选择行为变更, 依赖方法覆写推断能力, 显式后端配置兼容性风险, 非法后端名报错信息降级

关联脉络

• PR #33875 [diffusion] Fix 4/8-step distilled MiniMax-H3 Turbo LoRA merge: 同属 MiniMax-H3 模型线，改动重叠在 H3 配置与文档面，是 H3 功能演进的伴随改动。
• PR #33923 [Diffusion] Route zimage and hunyuanvideo attention through USPAttention: diffusion 注意力后端的持续演进；本 PR 的能力自证机制让此类新后端免改模型配置即可准入。
• PR #32667 [Diffusion] Add K/V-gather sequence parallel attention: 同属 diffusion 注意力后端与能力扩展，关系 attention 层与 selector 的选择语义。
• PR #33851 [diffusion] validate and document Spectrum controls: 同属 diffusion 侧 validate_server_args 启动期校验模式，机制相互呼应。