执行摘要

• 一句话：以显式能力契约门禁量化 encoder checkpoint，拒绝静默回退
• 推荐动作：值得精读。核心看点：以数据契约（CheckpointQuantizationCapability）替代文本 allowlist 的准入设计、fail-closed 策略与异常穿透（ComponentCheckpointUnsupportedError）的组合，以及“架构解析失败但有量化配置就拒绝、无量化配置就 fallback”的精细化分支。建议关注 _resolve_and_configure_encoder_quantization 的判定顺序与 component_loader.load() 异常链的后续演进。

功能与动机

PR body 明确指出要 'replace the text-only quant allowlist with an explicit native encoder capability contract'，并 'reject quantized unknown/unsupported encoder architectures without silently falling back'。此前文本式 allowlist 只覆盖文本编码器，图像编码器一旦遇到量化 checkpoint 可能被静默启用或静默回退，产生错误加载行为；同时 PR 声明 'CLIP remains fail-closed until its SRT/diffusion backend is implemented and validated'，需要一套可扩展的契约来防止未经验证的量化路径被意外打开。

实现拆解

1. 能力契约落地（base.py）：在 python/sglang/multimodal_gen/runtime/models/encoders/base.py 中新增 CheckpointQuantizationCapability（frozen dataclass，含 backend 与 methods 两个字段），并把 checkpoint_quantization_capability 属性挂在 EncoderTensorParallelMixin 上，默认 None。同时将 manages_checkpoint_quantization 从 TextEncoder 上移到 Mixin，使图像/文本编码器共用同一份契约定义。
2. 准入逻辑泛化（text_encoder_loader.py）：把原来的 _configure_text_encoder_quantization 重构为 _configure_encoder_quantization，新增 component_name 参数；异常一律改为 ComponentCheckpointUnsupportedError；能力判断从 supported_checkpoint_quantization_methods 文本集合切换为 capability 契约（未声明能力、backend 非 diffusion、方法不在 methods 内三种情况全部拒绝）。新增 _resolve_and_configure_encoder_quantization：先尝试用 ModelRegistry.resolve_model_cls 解析架构，架构解析失败时若检测到量化配置则直接拒绝，避免未知量化架构静默走 native fallback。
3. 异常穿透（component_loader.py）：新增 ComponentCheckpointUnsupportedError(ValueError)，并在 load() 的异常链中让该异常直接抛出而不进入 native fallback 路径；ComponentResidencyError 仍维持原有行为。
4. 图像 loader 接入与 H3 迁移：image_encoder_loader.py 复用 _resolve_and_configure_encoder_quantization；minimax_h3_qwen3vl.py 中 MiniMaxH3Qwen3VLEncoder 显式声明 CheckpointQuantizationCapability(backend="diffusion", methods=frozenset({"fp8"}))，删除旧的 supported_checkpoint_quantization_methods 文本声明，并保留模型自管理量化（如 Ideogram）的绕过路径。
5. 测试配套：新增 test_image_encoder_loader.py，覆盖 CLIP 量化 fail-closed、未知量化架构拒绝 fallback、未知未量化架构保留 native fallback 三条关键路径；更新 test_text_encoder_loader.py 适配新函数签名，并新增 test_srt_backend_is_not_admitted_without_an_adapter 验证 srt backend 不会在 diffusion loader 中被放行。

关键文件：

• python/sglang/multimodal_gen/runtime/loader/component_loaders/text_encoder_loader.py（模块 加载器；类别 source；类型 core-logic；符号 _configure_encoder_quantization, _resolve_and_configure_encoder_quantization, _process_quantized_encoder_weights）: 核心准入逻辑所在：将文本专用量化配置函数泛化为 text/image 共用，并新增架构解析失败时的拒绝分支，是本 PR 的主要行为变更点。
• python/sglang/multimodal_gen/runtime/models/encoders/base.py（模块 能力契约；类别 source；类型 data-contract；符号 CheckpointQuantizationCapability, EncoderTensorParallelMixin）: 定义 CheckpointQuantizationCapability 数据契约，并把能力属性挂到 EncoderTensorParallelMixin，是整个门禁机制的基础。
• python/sglang/multimodal_gen/runtime/loader/component_loaders/component_loader.py（模块 组件加载；类别 source；类型 core-logic；符号 ComponentCheckpointUnsupportedError）: 新增 ComponentCheckpointUnsupportedError 并在 load() 异常链中直接穿透，是阻止量化不支持 checkpoint 走 native fallback 的关键控制点。
• python/sglang/multimodal_gen/runtime/models/encoders/minimax_h3_qwen3vl.py（模块 H3 编码器；类别 source；类型 data-contract；符号 MiniMaxH3Qwen3VLEncoder）: MiniMax H3 是首个迁移到新能力契约的 encoder，展示从旧 allowlist 到 capability 声明的具体迁移方式。
• python/sglang/multimodal_gen/test/unit/test_image_encoder_loader.py（模块 图像加载测试；类别 test；类型 test-coverage；符号 TestImageEncoderQuantizationAdmission, test_quantized_clip_checkpoint_is_not_silently_enabled, test_unknown_quantized_architecture_does_not_fall_back, test_unknown_unquantized_architecture_keeps_native_fallback）: 新增测试文件，覆盖图像编码器量化准入的三条关键路径，是验证 fail-closed 行为的主要依据。
• python/sglang/multimodal_gen/test/unit/test_text_encoder_loader.py（模块 文本加载测试；类别 test；类型 test-coverage；符号 test_srt_backend_is_not_admitted_without_an_adapter）: 适配新函数签名并新增 srt backend 拒绝测试，验证为未来预留的 backend 不会在 diffusion loader 中被放行。
• python/sglang/multimodal_gen/runtime/loader/component_loaders/image_encoder_loader.py（模块 图像加载器；类别 source；类型 core-logic）: 图像编码器 loader 接入统一准入逻辑，使 text/image 行为一致。

关键符号：_configure_encoder_quantization, _resolve_and_configure_encoder_quantization, _process_quantized_encoder_weights, CheckpointQuantizationCapability, ComponentCheckpointUnsupportedError, test_quantized_clip_checkpoint_is_not_silently_enabled, test_unknown_quantized_architecture_does_not_fall_back, test_unknown_unquantized_architecture_keeps_native_fallback, test_srt_backend_is_not_admitted_without_an_adapter

关键源码片段

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

核心准入逻辑所在：将文本专用量化配置函数泛化为 text/image 共用，并新增架构解析失败时的拒绝分支，是本 PR 的主要行为变更点。

def _configure_encoder_quantization(
    model_config: EncoderConfig,
    model_cls: type[nn.Module],
    component_config: dict,
    component_model_path: str,
    component_name: str,
) -> None:
    # 模型自管理 checkpoint 量化的场景（如 Ideogram 的 bitsandbytes 状态）直接放行，
    # 避免通用生命周期重复处理权重。
    if getattr(model_cls, "manages_checkpoint_quantization", False):
        return
​
    # 解析量化配置失败时统一转为 ComponentCheckpointUnsupportedError，
    # 让上层 loader 直接拒绝而不是静默回退到未量化路径。
    try:
        quant_config = get_quant_config(component_config, component_model_path)
    except (KeyError, ValueError) as error:
        raise ComponentCheckpointUnsupportedError(
            f"Cannot configure checkpoint quantization for {component_name!r}: {error}"
        ) from error
​
    model_config.quant_config = quant_config
    if quant_config is None:
        return
​
    # 量化 checkpoint 要求树内 native encoder（EncoderTensorParallelMixin 子类）。
    if not issubclass(model_cls, EncoderTensorParallelMixin):
        raise ComponentCheckpointUnsupportedError(
            f"A quantized {component_name!r} checkpoint requires an in-tree "
            "native encoder; "
            f"got {model_cls.__name__}"
        )
​
    # capability 契约：未声明能力、backend 不是 diffusion、方法不在 methods 内
    # 三者任一命中都直接拒绝，保证 fail-closed。
    capability = model_cls.checkpoint_quantization_capability
    if capability is None:
        raise ComponentCheckpointUnsupportedError(
            f"{model_cls.__name__} does not support quantized checkpoints for "
            f"{component_name!r}: no checkpoint quantization capability is declared"
        )
    if capability.backend != "diffusion":
        raise ComponentCheckpointUnsupportedError(
            f"{model_cls.__name__} declares the {capability.backend!r} checkpoint "
            f"quantization backend for {component_name!r}, but the native encoder "
            "loader currently supports only the 'diffusion' backend"
        )
​
    quant_method = quant_config.get_name()
    if quant_method not in capability.methods:
        raise ComponentCheckpointUnsupportedError(
            f"{model_cls.__name__} does not support {component_name!r} checkpoints "
            f"quantized with {quant_method!r}; supported methods for the "
            f"{capability.backend!r} backend: {sorted(capability.methods)}"
        )

python/sglang/multimodal_gen/runtime/models/encoders/base.py

定义 CheckpointQuantizationCapability 数据契约，并把能力属性挂到 EncoderTensorParallelMixin，是整个门禁机制的基础。

@dataclass(frozen=True)
class CheckpointQuantizationCapability:
    """Native encoder 对量化 checkpoint 的能力契约（替代文本式 allowlist）。"""
​
    # backend 表示权重量化由哪一侧运行时消费："diffusion" 为多模态生成侧原生 loader，
    # "srt" 预留用于 SRT 侧 encoder（当前 loader 尚未支持）。
    backend: Literal["diffusion", "srt"]
    # methods 为该 backend 下支持的量化方法集合，例如 {"fp8"}。
    methods: frozenset[str]
​
​
class EncoderTensorParallelMixin:
    """Keep an encoder on the TP group that was used to build its shards."""
​
    _encoder_tp_group: GroupCoordinator | None = None
    # 默认 None 表示该 encoder 未声明量化能力，量化 checkpoint 一律拒绝加载。
    checkpoint_quantization_capability: CheckpointQuantizationCapability | None = None
    # 自管理量化的 encoder（如 Ideogram）绕过通用加载生命周期。
    manages_checkpoint_quantization = False

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

新增测试文件，覆盖图像编码器量化准入的三条关键路径，是验证 fail-closed 行为的主要依据。

class TestImageEncoderQuantizationAdmission(unittest.TestCase):
    def setUp(self):
        self.loader = ImageEncoderLoader()
        # 打桩 load_native，便于断言 fallback 是否被调用。
        load_native_patcher = mock.patch.object(
            self.loader, "load_native", return_value=object()
        )
        self.load_native = load_native_patcher.start()
        self.addCleanup(load_native_patcher.stop)
        self.server_args = SimpleNamespace(
            pipeline_config=SimpleNamespace(
                image_encoder_config=CLIPVisionConfig(),
                image_encoder_precision="bf16",
                native_only_components=(),
            ),
            encoder_parallel="replicate",
            resolve_component_attention_backend=lambda _name: (None, None),
        )
​
    def _component_config(self, architecture, *, quantized):
        config = {"architectures": [architecture]}
        if quantized:
            config["quantization_config"] = {
                "quant_method": "fp8",
                "activation_scheme": "dynamic",
            }
        return config
​
    def _config_patch(self, config):
        return mock.patch(
            "sglang.multimodal_gen.runtime.loader.component_loaders."
            "image_encoder_loader.get_diffusers_component_config",
            return_value=config,
        )
​
    def test_unknown_quantized_architecture_does_not_fall_back(self):
        # 未知架构但带量化配置：必须拒绝且不调用 native fallback。
        config = self._component_config("UnknownVisionModel", quantized=True)
        with self._config_patch(config), self.assertRaises(
            ComponentCheckpointUnsupportedError
        ):
            self._load()
        self.load_native.assert_not_called()
​
    def test_unknown_unquantized_architecture_keeps_native_fallback(self):
        # 未知架构且未量化：保持原有 native fallback 行为。
        config = self._component_config("UnknownVisionModel", quantized=False)
        with self._config_patch(config):
            self._load()
        self.load_native.assert_called_once()

评论区精华

该 PR 没有 review 评论记录，唯一评论是作者触发的 CI 重跑指令 /tag-and-rerun-ci（Extra 组 CI 曾失败为 Run #32220500757）。PR body 中作者明确了两条设计约束：CLIP 保持 fail-closed，直至其 SRT/diffusion backend 实现并验证；模型自管理量化（如 Ideogram 的 bitsandbytes 状态）继续绕过通用生命周期。提交历史还显示第二次提交与 Yiqi Yang 合作修复量化后处理 staging——逐层 stage 一个量化层，避免组件 offload 时在加速器上瞬时物化整个 encoder，这是值得注意的显存/内存权衡决策。

• CI 与 /tag-and-rerun-ci (other): 作者通过重跑 CI 恢复状态；实现本身无 reviewer 质疑记录。

风险与影响

• 风险：
  1. 行为回归：所有未声明 checkpoint_quantization_capability 的量化 encoder（如 CLIP）将从可能的静默加载或错误行为变为确定性报错，依赖旧行为的部署会立即失败，但这是设计意图。
  2. 契约迁移：任何继承 TextEncoder 且声明过 supported_checkpoint_quantization_methods 的第三方 encoder 必须迁移到新契约，否则量化 checkpoint 会被拒绝。
  3. 异常路径：component_loader.load() 的 except 链新增直接穿透的异常分支，若未来 _resolve_and_configure_encoder_quantization 误把未量化配置判为量化，会错误拒绝；目前有 unit 测试覆盖三态（量化已知不支持/量化未知/未量化未知）。
  4. 兼容性边界：capability.backend 目前只放行 diffusion，srt 被显式拒绝，这是为未来 SRT encoder 预留的断点，届时需要同步更新 loader。
  5. 测试覆盖主要停留在 unit 级，缺少端到端加载量化 checkpoint 的集成验证。
     - 影响：用户侧：MiniMax H3 FP8 量化加载路径保持可用；试图加载量化 CLIP 或未知架构量化 checkpoint 的用户会得到明确的 ComponentCheckpointUnsupportedError，而不是静默错误结果。系统侧：diffusion 子系统的 text/image 编码器加载准入统一到同一契约，新增 native encoder 时必须显式声明量化能力，防止未来误配。团队侧：该契约成为后续 SRT/diffusion encoder 融合方向（如 PR#35006）的量化准入基础，降低跨模块行为漂移风险。
     - 风险标记：核心加载路径变更, fail-closed 行为变化, 契约迁移要求, 缺少端到端集成测试覆盖, srt backend 预留未启用

关联脉络

• PR #34986 前置基础 PR（标题未在上下文中提供）: PR body 声明 Stacked on #34986，本 PR 是在其量化加载能力之上做的门禁重构。
• PR #35174 [Diffusion] Reuse shared checkpoint quant metadata resolver: 同为 diffusion 量化加载链路的元数据解析重构，为能力契约提供统一入口。
• PR #35353 [diffusion] make --vae-tiling honest, fix the decode OOM advice, gate NVFP4 on Blackwell: 同属 diffusion 量化能力门禁主题（NVFP4 卡型门禁），体现按能力而非文本列表放行的趋势。
• PR #35172 [Quantization] Extract shared checkpoint quant metadata resolver: SRT 侧同步提取 checkpoint 量化元数据解析器，与本文的 encoder 能力契约正交互补。
• PR #34993 [diffusion] fix: make MiniMax-H3 AdaLN cache rebuild transactional: MiniMax H3 相关修复，本 PR 中 H3 encoder 是首个声明 checkpoint_quantization_capability 的模型。