# PR #26809 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Add the KV-canary install API and forward-path wiring
- 合并时间：2026-05-31 09:55
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/26809

---

# 执行摘要

- 一句话：引入 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`

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

```python
# 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 功能线的上下游。