# PR #34848 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Fix MiniMax-H3 Cache-DiT BCG warning
- 合并时间：2026-08-14 22:07
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/34848

---

# 执行摘要

- 一句话：修复 MiniMax-H3 在 BCG 下 Cache-DiT 的 AttributeError
- 推荐动作：值得快速阅读，理解 PR#34242 与 H3 override 的边界交互。设计上采用“入口分流、委托基类”的方式，避免在 BCG 下重复实现缓存挂载，是一个简洁且风险可控的修复。对后续在扩散模型阶段叠加运行时开关有借鉴意义。

# 功能与动机

PR body 指出：#33827 与 #34242 的交互使 MiniMax-H3 override 在到达可断 CUDA 图警告路径前就触碰 `self.transformer`，导致回归测试以 `AttributeError` 失败。修复目标是在不破坏 `quality="lossless"` 行为的前提下，让 BCG 请求走基类逻辑。

# 实现拆解

1. 在 `python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py` 的 `_maybe_enable_cache_dit` 方法中，于 `desired_mode` 计算完成后插入 BCG 判断分支。
2. 若 `self.server_args.enable_breakable_cuda_graph` 为真且 `desired_mode` 非 None，直接调用 `super()._maybe_enable_cache_dit(num_inference_steps, batch)` 并返回，从而跳过 H3 自定义的 transformer 卸载与重新挂载逻辑，避免触碰 `self.transformer`。
3. 若 BCG 启用但 `desired_mode` 为 None，直接返回，等价于不启用 Cache-DiT，保持基类默认行为。
4. 非 BCG 路径完全保留原有 H3 专属逻辑（unmount 优先、输入保留预置、委托挂载），不影响既有行为。
5. 测试配套：未新增测试文件，依赖现有回归测试集 `diffusion_bcg_padding` 与 `minimax_h3_admission`，通过 `run_suite.py` 验证，34 个测试全部通过。

关键文件：
- `python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py`（模块 去噪阶段；类别 source；类型 core-logic；符号 _maybe_enable_cache_dit）: 修复核心所在：在 `_maybe_enable_cache_dit` 入口增加 BCG 快捷分支，将 BCG 请求委托给基类，避免触碰 `self.transformer` 导致 AttributeError。

关键符号：_maybe_enable_cache_dit

## 关键源码片段

### `python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py`

修复核心所在：在 `_maybe_enable_cache_dit` 入口增加 BCG 快捷分支，将 BCG 请求委托给基类，避免触碰 `self.transformer` 导致 AttributeError。

```python
# denoising.py 中 MiniMax-H3 阶段的关键方法片段
# 新增的 BCG 快捷分支位于方法入口处，避免触碰 self.transformer 的状态

def _maybe_enable_cache_dit(self, num_inference_steps, batch) -> None:
    quality = getattr(batch.sampling_params, "quality", "lossless")
    explicit_fields = getattr(batch.sampling_params, "_explicit_fields", ())
    generic_requested = (
        super()._cache_dit_requested() and "quality" not in explicit_fields
    )
    desired_mode = (
        "high" if quality == "high" else ("generic" if generic_requested else None)
    )
    current_mode = getattr(self, "_minimax_h3_cache_mode", None)
    self._minimax_h3_quality = quality

    # BCG 路径：可断 CUDA 图下直接委托基类，不经过 H3 自定义的 unmount / resume 逻辑
    # 这避免了在到达警告路径前就把 self.transformer 换掉而抛 AttributeError
    if self.server_args.enable_breakable_cuda_graph:
        if desired_mode is not None:
            super()._maybe_enable_cache_dit(num_inference_steps, batch)
        return

    # 非 BCG 路径维持原有 H3 专属逻辑：先卸载旧缓存再决定是否挂载
    if self._cache_dit_enabled and current_mode != desired_mode:
        self.transformer = disable_cache_on_transformer(self.transformer)
        self._cache_dit_enabled = False
        self._cached_num_steps = None
        self._minimax_h3_cache_mode = None
        self._set_cache_dit_input_preservation(False)

    if desired_mode is None:
        return

    # 预先设置输入保留，再尝试挂载
    was_enabled = self._cache_dit_enabled
    if not was_enabled:
        self._set_cache_dit_input_preservation(True)
    try:
        super()._maybe_enable_cache_dit(num_inference_steps, batch)
    except Exception:
        ...

```

# 评论区精华

Review 面板无实质评论线程，唯一 reviewer BBuf 直接 APPROVED。PR body 说明了根因："The interaction between #33827 and #34242 made the MiniMax-H3 override touch `self.transformer` before reaching the breakable-CUDA-graph warning path, causing the regression test to fail with an `AttributeError`"。

- 暂无高价值评论线程

# 风险与影响

- 风险：改动集中在一个方法入口，风险较低。但需注意：
 - BCG 启用时，H3 自定义的 `quality == "high"` 强制缓存逻辑被委托给基类，基类是否能正确处理 H3 的缓存语义取决于基类实现；若基类不感知 MiniMax-H3 的特殊挂载需求，可能在 BCG 下缓存行为与预期有差异。
 - 新增分支在 `desired_mode` 计算之后才判断，而 `self._minimax_h3_quality` 已被更新，若后续异常可能留下状态不一致（但该分支直接返回，无后续状态修改）。
 - 没有新增独立测试，依赖已有回归测试覆盖，若测试环境未启用 BCG 则可能遗漏问题。
 - 影响：影响范围：仅影响 MiniMax-H3 模型在启用 `enable_breakable_cuda_graph` 时的 Cache-DiT 启用路径；修复了回归测试失败；对非 BCG 场景无任何行为变化。影响程度低，用户无感知，但保障了 BCG 与 Cache-DiT 组合场景的稳定性。
 - 风险标记：BCG 路径行为变更 , 依赖现有回归测试 , 仅影响 MiniMax-H3

# 关联脉络

- PR #34242 [diffusion] Warn when BCG disables Cache-DiT: PR body 指出该 PR 与 #33827 的交互导致 AttributeError，本 PR 修复了由它引入的 BCG 警告路径与 H3 override 的冲突。
- PR #34650 feat(diffusion): rebuild MiniMax-H3 AdaLN outputs on demand: 同为 MiniMax-H3 模块的近期改动，涉及同一 denoising 阶段，展示该模型的持续演进。