根据 PR body（Follow up of #23906），目的是恢复重构期间被删除的必要注释，为新文件添加许可证，并清理不再需要的命令行选项。保持代码风格一致，移除未发布的别名以避免混淆。
建议快速合并。该 PR 是高质量的技术债务清理，尤其值得关注的是：
1) 如何在不改变行为的前提下通过注释传达设计意图（如 can_run 中的禁用条件说明）；
2) 对于从未发布的 CLI 别名，选择直接删除而非走废弃周期，简化了长期维护。
PR 无实质 review 讨论（共有 2 条评论，来自 bot 和作者自己的 /tag-run-ci-label）。变更内容已由 CI 验证通过。
decode_cuda_graph_runner.py 中，还原了关于 TARGET_VERIFY 模式、隐藏状态返回双捕获避免、LoRA CUDA 图两阶段初始化、PDMux 初始化等的关键注释；在 can_run 方法中增加了关于 token embedding 覆盖、混合 batch 限制的注释。cuda_graph_buffer_registry.py、cuda_graph_config.py、shape_key.py 以及所有 runner_backend 下的文件（base_cuda_graph_backend.py、breakable_cuda_graph_backend.py、full_cuda_graph_backend.py、tc_piecewise_cuda_graph_backend.py、utils.py）和 runner_utils/buffers.py 添加了 Apache-2.0 许可证头。--prefill-cuda-graph-backend 和 --decode-cuda-graph-backend 别名标志（这些标志在重构过程中引入但未被任何发布版本包含）。同时将 disable_prefill_cuda_graph 和 disable_decode_cuda_graph 字段从“遗留”区段移到常规便捷标志区段，并为其添加了正式的 CLI 参数。base_cuda_graph_runner.py 的 get_batch_sizes_to_capture 函数中添加了关于为什么要 pad num_max_requests 以及输入 token 计数对齐要求的注释；调整了 server_args.py 中字段的顺序，使便捷标志与对应配置更接近。| 文件 | 模块 | 状态 | 重要度 |
|---|---|---|---|
python/sglang/srt/server_args.py |
配置管理 | modified | 6.1 |
python/sglang/srt/model_executor/runner/decode_cuda_graph_runner.py |
CUDA 图解码 | modified | 6.14 |
python/sglang/srt/model_executor/runner/base_cuda_graph_runner.py |
CUDA 图基类 | modified | 5.51 |
python/sglang/srt/server_args.py
core-logic
核心配置类，移除了未发布的别名标志，将 disable_prefill/decode_cuda_graph 提升为一级便捷标志，并调整了字段顺序和注释。
# 以下代码展示了调整后的 CUDA 图配置解析顺序：
# 优先级：显式 JSON > 便捷标志 > 遗留标志 > 默认值
def _parse_cuda_graph_config(self):
raw_input = self.cuda_graph_config
explicit_input = raw_input.to_dict() if isinstance(raw_input, CudaGraphConfig) else (raw_input or {})
config = default_cuda_graph_config()
locked: set = set()
def _set(phase, key, value):
setattr(getattr(config, phase), key, value)
locked.add((phase, key))
# ---- Legacy global flags (lowest precedence above defaults) ----
if self.disable_cuda_graph:
_set(Phase.DECODE, "backend", Backend.DISABLED)
_set(Phase.PREFILL, "backend", Backend.DISABLED)
# ---- Boolean per-phase off-switches ----
# 位于显式后端选择器下方，因此如果同时指定，
# --cuda-graph-backend-* 的优先级更高
if self.disable_prefill_cuda_graph:
_set(Phase.PREFILL, "backend", Backend.DISABLED)
if self.disable_decode_cuda_graph:
_set(Phase.DECODE, "backend", Backend.DISABLED)
# ---- Per-phase convenience flags ----
if self.cuda_graph_backend_decode is not None:
_set(Phase.DECODE, "backend", self.cuda_graph_backend_decode)
if self.cuda_graph_backend_prefill is not None:
_set(Phase.PREFILL, "backend", self.cuda_graph_backend_prefill)
# 注意：prefill_cuda_graph_backend 和 decode_cuda_graph_backend 已完全移除
当前评论区没有形成足够清晰的争议点或结论，后续有更多讨论时会体现在这里。
风险极低。主要变更包括：
1) 注释恢复和许可证添加，不影响运行时逻辑；
2) 删除的 --prefill/decode-cuda-graph-backend 别名从未发布，因此不会破坏现有用户；
3) disable_prefill/decode_cuda_graph 字段的提升仅改变了其在配置中的优先级顺序，实际行为通过 _parse_cuda_graph_config 中的逻辑保持不变。唯一需要注意的潜在风险是 decode_cuda_graph_runner.py 中注释恢复可能暗示了控制流调整（如 TARGET_VERIFY 模式注释），但实际仅添加注释，逻辑未变。CI 绿色通过进一步降低了风险。
对用户：无行为影响。删除的别名从未发布，用户不会感知。--disable-prefill-cuda-graph 和 --disable-decode-cuda-graph 现在有正式的 CLI 帮助文本，更易于发现。
对系统：无性能影响。
对团队：代码可读性提高，后续维护者能更好理解 CUDA 图捕获的逻辑和限制。
当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。
参与讨论