执行摘要

• 一句话：修复 runner_backend 循环导入导致的 CI 失败
• 推荐动作：建议所有涉及循环依赖修复的 PR 参考此模式：当符号仅用于类型注解时，利用 TYPE_CHECKING 和 from __future__ import annotations 延迟导入。此 PR 展示了清晰的诊断和最小化修复，值得精读。

功能与动机

base-b-test-cpu (Xeon) job 在 main 分支及每个 PR 上失败，错误为 AttributeError: module 'sglang.srt.model_executor' has no attribute 'runner_backend'。实际上是由于循环导入：runner_backend 模块导入 runner.shape_key 时触发 runner/__init__，进而重新进入 runner_backend 导致未初始化。该问题只在 mock.patch 的 dotted-name 解析路径下暴露。

实现拆解

1. 在四个 runner_backend 文件中，将全局的 from sglang.srt.model_executor.runner.shape_key import ShapeKey 删除。
2. 在已有 TYPE_CHECKING 块内添加 from sglang.srt.model_executor.runner.shape_key import ShapeKey，因为 ShapeKey 仅在类型注解中使用。
3. 所有四个文件已包含 from __future__ import annotations，因此类型注解在运行时不会被求值，导入移入 TYPE_CHECKING 后不会影响实际行为。
4. 不影响测试或其他配置，无需额外改动。

关键文件：

• python/sglang/srt/model_executor/runner_backend/base_cuda_graph_backend.py（模块 模型执行器；类别 source；类型 import）: 作为抽象基类，是所有 CUDA 图后端的共同父类，修复必须从此开始。
• python/sglang/srt/model_executor/runner_backend/breakable_cuda_graph_backend.py（模块 模型执行器；类别 source；类型 import）: 同样是循环导入链中的一环，修复与基类同步。
• python/sglang/srt/model_executor/runner_backend/full_cuda_graph_backend.py（模块 模型执行器；类别 source；类型 import）: 修复同步，确保导入安全。
• python/sglang/srt/model_executor/runner_backend/tc_piecewise_cuda_graph_backend.py（模块 模型执行器；类别 source；类型 import）: 修复同步，确保导入安全。

关键符号：未识别

关键源码片段

python/sglang/srt/model_executor/runner_backend/base_cuda_graph_backend.py

作为抽象基类，是所有 CUDA 图后端的共同父类，修复必须从此开始。

"""Backend interface for CUDA graph capture/replay."""
from __future__ import annotations
​
from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional
​
import torch
​
# ShapeKey 仅用于类型注解，移入 TYPE_CHECKING 避免循环导入
if TYPE_CHECKING:
    from sglang.srt.model_executor.forward_batch_info import ForwardBatch
    from sglang.srt.model_executor.runner.shape_key import ShapeKey
​
​
class BaseCudaGraphBackend(ABC):
    """Pure ABC: no state, no defaults."""
    # ... 类方法保持不变

评论区精华

作者在 PR 描述中详细分析了循环导入的精确路径：runner_backend/__init__ -> base_cuda_graph_backend -> runner.shape_key (executes runner/__init__) -> decode_cuda_graph_runner -> runner_backend.breakable_cuda_graph_backend -> base_cuda_graph_backend。该分析揭示了仅当 runner_backend 作为入口时才会触发，因此某些 CI job 不失败。reviewer ch-wan 直接批准，无进一步讨论。

• 循环导入根因分析 (correctness): 将 ShapeKey 移入 TYPE_CHECKING 块即可打破循环，不需要修改业务逻辑。

风险与影响

• 风险：变更极小（仅导入位置移动），且四个文件均已使用 from __future__ import annotations，运行时不会执行 TYPE_CHECKING 块内的导入。回归风险极低。但需注意若未来某个文件移除了 from __future__ import annotations 或 ShapeKey 被用于运行时（非类型注解），则需重新评估导入位置。
• 影响：直接影响：修复 CPU Xeon 测试套件的 CI 崩溃，使 test_server_args.py 从 1 failed/63 passed 变为 64 passed。不影响任何功能逻辑，不改变用户可见行为。团队：减少 CI 噪音，提升开发效率。
• 风险标记：极低回归风险, 入口导入路径修正

关联脉络

• 暂无明显关联 PR