# PR #49774 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Bugfix][Spec Decode] Preserve draft buffers across level-2 sleep
- 合并时间：2026-07-28 15:16
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/49774

---

# 执行摘要

- 一句话：修复推测解码 draft 模型缓冲区在 level-2 sleep 时丢失
- 推荐动作：值得精读，尤其是对 sleep/wake 生命周期和 buffer 管理感兴趣的开发者。设计决策（条件恢复、对称快照、移除冗余钩子）提供了良好的实践经验。

# 功能与动机

在 level-2 sleep 释放 weights pool 后，draft 模型的注册缓冲区（如 cos_sin_cache）未被持久化，唤醒后变为垃圾值，导致 draft 质量崩溃。同时，wake_up 在未唤醒 weights 时仍执行缓冲区恢复，写入无效地址并清空快照，使后续权重唤醒无法恢复缓冲区。此前仅对 target 模型做快照，而 draft 模型被忽略。

# 实现拆解

1. 在 Worker.__init__中新增 _sleep_saved_draft_buffers 字典，与原有的 _sleep_saved_buffers 对称，用于缓存 draft 模型缓冲区。
2. 在 sleep 方法中，当 level==2 时，除了保存 target 模型缓冲区外，通过 get_draft_model() 获取 draft 模型实例，将其所有 named_buffers 快照到 _sleep_saved_draft_buffers。
3. 在 wake_up 方法中，增加 wake_weights 变量判断（tags is None or "weights" in tags），只在唤醒 weights 时从快照恢复缓冲区；否则保留快照不被清除。
4. 移除 _sleep_rebuild_draft_metadata_buffers 标志及其相关逻辑，因为缓冲区原地恢复 + weight reload 已足够重建 metadata。

关键文件：
- `vllm/v1/worker/gpu_worker.py`（模块 工作节点；类别 source；类型 core-logic；符号 __init__, sleep, wake_up）: 唯一变更文件，包含了所有修复逻辑：添加 draft 缓冲区快照、条件恢复、移除冗余重建机制。

关键符号：__init__, sleep, wake_up


# 评论区精华

本 PR 无实质 review 讨论。作者在 PR body 中详细说明了 bug 表现、修复方案和移除冗余机制的理由。维护者 ywang96 直接 approve。

- 暂无高价值评论线程

# 风险与影响

- 风险：核心路径变更：level-2 sleep/wake 是资源管理的关键路径，但作者已在固定 token 场景验证输出一致。缺少回归测试：PR 未添加针对 level-2 wake 后缓冲区正确性的自动化测试，未来可能退化。隐式依赖：移除重建钩子依赖于 weight reload 必然发生；若未来有跳过 reload 的唤醒流程，draft 元数据可能不完整。
- 影响：正面影响：使用推测解码（如 MTP）且启用 level-2 sleep 的用户将不再遭遇 draft 质量下降问题。代码量减少，且不再耦合特定 draft 模型的 _build_fused_kv_buffers 内部接口，维护性提升。负面影响：无。影响范围：仅限于 V1 引擎中推测解码与 level-2 sleep 的组合场景。
- 风险标记：核心路径变更 , 缺少回归测试 , 隐式依赖 weight reload 顺序

# 关联脉络

- 暂无明显关联 PR