执行摘要

• 一句话：引入 kv-canary 安装 API 并接入模型前向路径
• 推荐动作：该 PR 是 kv-canary 功能线的地基，值得计划使用 KV 缓存监控的团队精读。设计上采用 monkey-patch 与上下文管理器组合，展示了在现有执行流中非侵入式嵌入验证逻辑的模式。Review 中的防御性编程建议可在后续迭代中参考采纳。

功能与动机

为了实现对 KV 缓存完整性的运行时监控与验证，需要建立 kv-canary 运行时的安装和路由机制。该 PR 是 kv-canary 系列功能的基础设施 PR，为后续的扰动注入、指纹验证和健康检查提供入口。

实现拆解

1. 新增安装 API：在 python/sglang/srt/kv_canary/api.py 中定义 install_canary 函数。
   - 从 ServerArgs 读取 CanaryConfig，若模式为 NONE 则返回 None。
   - 断言 disable_piecewise_cuda_graph（当前设计限制）。
   - 调用 attach_canary_buffers 将金丝雀缓冲区挂接到 KV 池。
   - 计算 CanaryLaunchCapacities 并构造 CanaryManager。
   - 调用 _patch_model_forward 对 model.forward 进行 monkey-patch，插入 pre_ops_maybe_inside_graph 和 post_ops_maybe_inside_graph。

2. 集成到模型执行器：修改 python/sglang/srt/model_executor/model_runner.py。
   - 在 initialize 中，在 init_memory_pool 之后调用 install_canary，保存返回的管理器为 self.canary_manager。
   - 在图捕获和预热之后，若管理器非空且非 draft worker，调用 mark_init_finished。
   - 在 forward 中，将原本的 canary_ctx = nullcontext() 替换为包含 with_ops_outside_graph 和 with_active_single_forward_manager 的条件上下文。

3. 集成到 CUDA 图执行器：修改 python/sglang/srt/model_executor/cuda_graph_runner.py。
   - 在 CUDA 图预热阶段的 run_once 中，同样替换 canary_ctx 为 with_active_single_forward_manager(0)（仅当 canary_manager 非空且非 draft worker）。

4. 新增测试文件：

   • test/registered/kv_canary/test_self_e2e_baseline.py：基线端到端测试，验证无扰动时不触发违规。
   • test/registered/kv_canary/test_self_unit_runner_per_forward.py：单元测试，使用 mock 验证每次前向的 plan/verify/write 执行顺序。
   • test/registered/kv_canary/test_self_e2e_bench_speed.py：性能基准测试，量化金丝雀启用的延迟开销。
   • 修改了多个注意力测试类，预置 --kv-canary raise 参数（但默认不生效）。

关键文件：

• python/sglang/srt/kv_canary/api.py（模块 KV检测层；类别 source；类型 entrypoint；符号 install_canary, _patch_model_forward, _with_canary_bracketing, _extract_forward_batch）: 新增文件，提供 kv-canary 安装入口和模型 forward 的 monkey-patch 核心逻辑，是整个功能线的起点。
• python/sglang/srt/model_executor/model_runner.py（模块 模型执行器；类别 source；类型 data-contract）: 在模型初始化和前向路径中嵌入金丝雀管理器，是核心执行流改动。
• python/sglang/srt/model_executor/cuda_graph_runner.py（模块 CUDA图执行器；类别 source；类型 data-contract）: 在 CUDA 图预热阶段接入金丝雀上下文，保证图捕获时正确执行。
• test/registered/kv_canary/test_self_unit_runner_per_forward.py（模块 单元测试；类别 test；类型 test-coverage；符号 TestManagerPerForward, test_per_forward_orchestrates_plan_head_tail, TestLaunchEndpointsPerForward, test_launch_endpoints_per_forward_keeps_padded_token_tensors）: 核心单元测试，验证每次前向调用的执行顺序和端点传递正确性。
• test/registered/kv_canary/test_self_e2e_baseline.py（模块 端到端测试；类别 test；类型 test-coverage；符号 _BaselineBase, setUpClass, test_no_violation, TestBaselineMha）: 基线端到端测试，验证无扰动时金丝雀不产生误报。
• test/registered/kv_canary/test_self_e2e_bench_speed.py（模块 性能测试；类别 test；类型 test-coverage；符号 _make_server_args, _make_bench_args, _run_one_canary_setting, _make_scenario_key）: 性能基准测试，量化金丝鹤启用后的延迟开销。

关键符号：install_canary, _patch_model_forward, _with_canary_bracketing, _extract_forward_batch

关键源码片段

python/sglang/srt/model_executor/model_runner.py

在模型初始化和前向路径中嵌入金丝雀管理器，是核心执行流改动。

# model_runner.py 中的安装与上下文路由
# 1. 在 initialize 方法中，init_memory_pool 之后调用 install_canary：
self.canary_manager = install_canary(
    server_args=server_args,
    model_runner=self,
)
​
# 2. 在预热和捕获之后，通知管理器初始化完成：
if self.canary_manager is not None and not self.is_draft_worker:
    self.canary_manager.mark_init_finished()
​
# 3. 在 forward 方法中，替换 canary_ctx 占位符为条件上下文：
canary_ctx = (
    context_tuple(
        c.with_ops_outside_graph(
            single_forward_indices=[0],
            maybe_inaccurate_forward_batch=forward_batch,
        ),
        c.with_active_single_forward_manager(0),
    )
    if not self.is_draft_worker and ((c := self.canary_manager) is not None)
    else contextlib.nullcontext()
)
​
# 之后通过 with canary_ctx: 包裹前向计算，保证 pre/post 操作在正确上下文中执行。

评论区精华

Review 评论主要由 gemini-code-assist[bot] 提出，重点包括：

• assert 替换为异常：在 api.py 中，assert disable_piecewise_cuda_graph 在 -O 模式下会被跳过，建议改为 raise ValueError。
• draft worker 隔离：cuda_graph_runner.py 未检查 draft worker，与 model_runner.py 行为不一致，可能导致 draft worker 错误启用金丝雀。
• 除零保护：测试 test_self_e2e_bench_speed.py 中 on.latency - off.latency / off.latency 可能因 off.latency 为 0 而崩溃。
• 防御性属性访问：多处在直接访问属性（如 model_runner.sliding_window_size）的地方，建议使用 getattr 加默认值。

这些评论均未获得作者回复，PR 已被合并，因此建议未在当前版本中采纳。

• 禁止使用 assert 进行运行时校验 (correctness): 未收到作者回复，PR 已合并，当前仍使用 assert。
• cuda_graph_runner 缺少 draft worker 隔离 (correctness): 未明确回复，PR 合并时未修改。
• 性能基准测试中除零风险 (correctness): 未回复，PR 已合并，当前未添加除零保护。

风险与影响

• 风险：
  • 核心路径变更风险：model_runner.py 和 cuda_graph_runner.py 的上下文切换位于模型前向热路径，若存在错误可能导致死锁或前向失败。但默认关闭，风险有限。
  • 强制禁用 piecewise CUDA graph：启用金丝雀必须设置 --disable-piecewise-cuda-graph，可能影响使用该特性的用户。
  • draft worker 隔离不完整：cuda_graph_runner.py 中未像 model_runner.py 一样检查 is_draft_worker，可能导致 draft worker 错误启用（但 draft worker 通常不会触发金丝雀上下文，因为管理器为空）。
  • assert 跳过风险：api.py 中的 assert 在 -O 优化模式下失效，可能忽略必要的配置验证。
• 影响：
  • 用户影响：默认无影响，功能关闭。用户可通过 --kv-canary 启用，但需显式配合 --disable-piecewise-cuda-graph。
  • 系统影响：为 kv-canary 功能线提供核心入口，后续所有金丝雀验证、扰动注入、健康检查均依赖此安装机制。
  • 团队影响：定义了公共 API 和集成模式，后续开发者需理解 install_canary 及上下文管理器组合。
  • 风险标记：核心路径变更, 缺少draft worker检查, 使用assert可能导致跳过, 强制禁用piecewise cuda graph

关联脉络

• PR #26810 Add KV-canary SWA + DeepSeek-V4 pool support: 该 PR 提供的 pool_patcher 是 install_canary 中 attach_canary_buffers 的基础依赖。
• PR #26813 Support EAGLE speculative decoding in the KV-canary: EAGLE 集成需要本 PR 的安装 API 和路由机制，两者构成 kv-canary 功能线的上下游。