vLLM PD 分离 · Decode 端 KV Cache 内存容量分析

1. 调研方法 & 目录

本报告基于 Playwright + Python urllib 直接从 raw.githubusercontent.com 拉取 vLLM main 分支的 design docs、用户文档及核心源码，聚焦 disaggregated prefill/decode（disagg_prefill）设计中 D 实例的 KV Cache 内存容量。

2. D 端 KV Cache pool / Block Manager 设计 (paged_attention.md · hybrid_kv_cache_manager.md · prefix_caching.md)

2.1 整体流程 (Scheduler → KVCacheManager → BlockPool → GPU tensor)

vLLM v1 把 KV Cache 管理抽象成三层（详见 hybrid_kv_cache_manager.md）：

┌──────────────────────────────────────────────────────────────┐
│ Scheduler (engine core)                                      │
│   └─ on_new_request / allocate_slots / free  (per-request)   │
└────────────────────┬─────────────────────────────────────────┘
                     │  KVCacheBlocks (per-request)
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ KVCacheManager (vllm/v1/core/kv_cache_manager.py)            │
│   └─ get_computed_blocks   (prefix cache hit 第一次扫描)     │
│   └─ allocate_slots        (调度一个 step 的分配)            │
│   └─ free                  (请求完成释放, 反向 order LRU)    │
│   └─ usage()               (0.0~1.0 占用率, 用于 watermark)  │
└────────────────────┬─────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ BlockPool (vllm/v1/core/block_pool.py)                       │
│   blocks: list[KVCacheBlock]   # 预分配好的所有 block        │
│   free_block_queue: FreeKVCacheBlockQueue (doubly-linked)    │
│   cached_block_hash_to_block: BlockHashToBlockMap            │
│   └─ allocate() / free() / cache_full_blocks() / evict_blocks│
└────────────────────┬─────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ KVCacheTensor (per-buffer, 跨 KV cache group 共享)            │
│   block_size × kv_hidden_size 的 slice 拼成 cuda 连续 tensor  │
└──────────────────────────────────────────────────────────────┘

2.2 谁是"D 端"的决定者

• Scheduler (engine core process)：在 D 实例上，NixlConnectorScheduler 在每次 scheduler step 里调用 build_connector_meta：
  • push 模式 D 端 → meta.push_registrations（把自己的 logical block_ids 给 P）
  • pull 模式 D 端 → 等待 P 的 KV READ, 通过 _pending_completion_notifs 完成通知
• Worker (GPU, 每 TP rank 一个)：执行实际的 KV Transfer 以及 KV Cache 的写入/读取。nixl-push-writer 是新增的专用后台线程（nixl_kv_push_connector.md §Threads）。
• KV Cache 调度器视角：D 端容量完全取决于 KVCacheManager 初始化时做出的 num_gpu_blocks 决策（基于 determine_available_memory() profiling 结果）。P→D 的 KV transfer 落到同一块 block里——push 时 P 直接 WRITE 到 D 预分配好的 block（"logical block ids (preallocated)"，参见 push_connector.md）。

2.3 PD 分离后 D 端的 KV Cache 来源（三种路径）

3. block_size / gpu_memory_utilization / kv_cache_memory_bytes 默认值及影响 (vllm/config/cache.py 实测源码)

# vllm/config/cache.py (GitHub main, 2026-07-15)
class CacheConfig:
    DEFAULT_BLOCK_SIZE: ClassVar[int] = 16

    block_size: int = Field(default=None, gt=0)
    # After construction, always int (resolved to DEFAULT_BLOCK_SIZE)

    gpu_memory_utilization: float = Field(default=0.92, gt=0, le=1)
    """The fraction of GPU memory to be used
    for the model executor, which can range from 0 to 1."""

    cache_dtype: CacheDType = "auto"
    """Data type for kv cache storage. If 'auto',
    will use model data type."""

    kv_cache_memory_bytes: int | None = None
    """... ignores gpu_memory_utilization when not-None"""

    num_gpu_blocks: int | None  # set after profiling
    num_cpu_blocks: int | None  # set after profiling

3.3 各参数对 D 端容量的实际影响

4. D 端 KV Cache 调度（swap / eviction / prefix caching）(kv_cache_manager.py · block_pool.py · prefix_caching.md)

4.1 核心调度逻辑（KVCacheManager.allocate_slots）

# vllm/v1/core/kv_cache_manager.py
watermark_blocks = int(watermark * kv_cache_config.num_blocks)  # 默认 watermark ≈ 0.01
required_blocks = num_blocks_to_allocate + watermark_blocks     # 只有 waiting/preempted 请求才加

if self.block_pool.get_num_free_blocks() < required_blocks:
    # 水位线未通过, 拒绝新的 waiting/preempted 请求 admission
    return None, None
# ... 正常 prefix cache hit 扫描 + 分配新 block

4.2 请求生命周期内的 KV Cache 操作

4.3 与 CPU swap / OffloadingConnector 的协同

vLLM 提供 OffloadingConnector（详见 §5 kv_offloading_usage.md）：当 D 端 HBM 不足时, 可以把 KV block 以 DMA(cudaMemcpyAsync) offload 到 pinned CPU memory。配置入口：

--kv-transfer-config '{
  "kv_connector": "OffloadingConnector",
  "kv_role": "kv_both",
  "kv_connector_extra_config": {
    "block_size": 64,               # 必须为 GPU block_size 倍数
    "cpu_bytes_to_use": 1000000000, # ~1 GiB CPU pinned mem
    "eviction_policy": "lru"        # 或 "arc"
  }
}'

4.4 Swap / Preemption 策略

vLLM v1 不支持把 KV swap 到 CPU 的 preemption/restore—— Scheduler 的 preemption 策略是 RECOMPUTE（见 v1 scheduler）：一个请求如果分配不到 block, 直接丢弃已有 KV, 恢复到 waiting 队列, 等待 free block 水位线恢复后重新 allocate_slots。watermark_blocks（watermark 乘 num_blocks, 默认 0.01）是避免"频繁 preempt"的唯一护栏。

这意味着：D 端高并发时, PD 请求等待队列中的 lease 往往因为 preemption 而被作废——P 端已经传过来的 KV 也将被重新传输。

5. kv_cache_dtype 与精度对 D 端容量的影响 (cache.py · conserving_memory.md)

5.1 支持的 KV Cache dtype 全量

来自 vllm/config/cache.py CacheDType 类型别名：

5.2 各 dtype 存储容量折算（相对 fp16 baseline 的比值）

5.3 对 D 端工程取舍

• PD 分离下 D 端 KV 复制倍数大——D 端要存储每个 request 所有 prefix + decode 的 KV, 选择 fp8 / nvfp4 可让 D 端 HBM 中 KV Cache 容量翻倍乃至 4×
• 精度降级需要配套 per-token / per-head scale——fp8_per_token_head、int4_per_token_head 在运行时动态计算 scale, 牺牲一点算力换容量
• DeepSeek V3/R1 系列默认 KV Cache 已是 fp8（cache_dtype=auto → fp8）—— 这已经是 PD 部署的"甜区"配置
• DeepSeek V3.2 特殊条款：官方建议把 kv_cache_dtype 从 fp8 设为 bfloat16 以换取精度（参见 cache.py 注释）

6. D 端 Memory Profiling：权重 + KV Cache + 激活 + 碎片 各占多少 (gpu_worker.py · mem_utils.py)

6.1 核心函数 GPUWorker.determine_available_memory()

# vllm/v1/worker/gpu_worker.py (GitHub main, 2026-07-15, 简化)
@torch.inference_mode()
def determine_available_memory(self) -> int:
    # (1) 手动指定 kv_cache_memory_bytes 时, 直接旁路 profiling
    if kv_cache_memory_bytes := self.cache_config.kv_cache_memory_bytes:
        self.model_runner.profile_run()
        return self._reserve_mm_ipc_gpu_memory(kv_cache_memory_bytes)

    # (2) 否则执行 profile pass
    with memory_profiling(self.init_snapshot,
                          weights_memory=int(self.model_runner.model_memory_usage)
                          ) as profile_result:
        self.model_runner.profile_run()          # 一次 dummy forward
        profile_torch_peak = torch.accelerator.memory_stats(...)
                                                .get("allocated_bytes.all.peak", 0)
        # (3) cudagraph 占用的额外显存估计
        cudagraph_memory_estimate = 0
        if compilation_config.cudagraph_mode != NONE:
            cudagraph_memory_estimate = self.model_runner.profile_cudagraph_memory()

    profile_result.torch_peak_increase = \
        profile_torch_peak - profile_result.before_profile.torch_peak
    profile_result.non_kv_cache_memory = (
        profile_result.non_torch_increase     # 非 torch 显存增量 (NCCL buffer, attn backend)
        + profile_result.torch_peak_increase  # activation 峰值
        + profile_result.weights_memory       # 模型权重
    )

    self.available_kv_cache_memory_bytes = (
        self.requested_memory                                    # = total_gpu_mem * 0.92
        - profile_result.non_kv_cache_memory
        - cudagraph_memory_estimate    # (VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=1 时计入)
    )
    return self._reserve_mm_ipc_gpu_memory(self.available_kv_cache_memory_bytes)

6.2 vLLM 官方分类公式（memory_profiling docstring，mem_utils.py L242-276）

The memory in one GPU can be classified into 3 categories:
    1. memory used by anything other than the current vLLM instance
    2. memory used by torch in the current vLLM instance
    3. memory used in the current vLLM instance, but not by torch

Quantitive example:
  Before creating the current vLLM instance:
      category 1: 1 GiB, category 2: 0 GiB, category 3: 0 GiB

  After creating the current vLLM instance and loading the model:
      category 1: 1 GiB, category 2: 2 GiB (model weights take 2 GiB)
                , category 3: 0.5 GiB (memory used by NCCL)

  During profiling (peak):
      category 1: 1 GiB, category 2: 4 GiB (peak activation tensors take 2 GiB)
                , category 3: 1 GiB (NCCL + attn backend buffers)

  After profiling:
      category 1: 1 GiB, category 2: 3 GiB (after GC of activation tensors)
                , category 3: 1 GiB

  => non-kv cache takes 5 GiB in total, including:
      a. 2 GiB model weights (category 2)
      b. 2 GiB reserved for peak activation tensors (category 2)
      c. 1 GiB used by non-torch components (category 3)

6.3 命名与公式速查

6.4 典型 D 端 HBM 分布（经验值, 源自 conserving_memory.md + 用户报告）

注：上表基于社区讨论 + 加权估算, 真实数字因 batch shape、attention backend、TP 数量差异显著。实际运行请参考 vLLM 启动时打印的 "Available KV cache memory: X GiB" 日志。

6.5 关键环境变量（显存 profiling 细粒度控制）

# 手动指定 KV cache 字节, 旁路 profiling（PD 场景最稳）
--kv-cache-memory-bytes $((50 * 1024**3))

# 关闭 cudagraph memory 估计 (v0.21+)
export VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=0

# 多模态 IPC 显存保留 (multimodal PD 才需要)
# vllm/v1/worker/gpu_worker.py 中 _reserve_mm_ipc_gpu_memory() 自动维护

7. 长 context (1M) 下 vLLM 的 HBM 挑战 (kv_cache_utils.py)

1M context 意味着每个 request 的 KV Cache 需求急剧放大。以 DeepSeek-V3 (MLA, 57B A23, kv_lora_rank=512, qk_rope_head_dim=64, num_heads=128) 为例：

7.1 单 token KV 显存

7.2 1M token KV Cache 需求（单个 request）

KV_per_request ≈ 1,000,000 × (kv_lora_rank + qk_rope_head_dim + v_head_dim) × 2 (K+V)

Llama-3.1-70B (fp16):  1M × 16,384 bytes = 15.3 GiB  ← 单卡放不下一个 1M 的 request
Qwen2.5-72B (fp16):   1M ×  4,096 bytes  =  3.8 GiB
DeepSeek-V3 (fp8):    1M ×    704 bytes  =  0.66 GiB  ← MLA + fp8 占优
DeepSeek-V3 (fp16):   1M ×  1,408 bytes  =  1.3 GiB

7.3 PD 分离对 D 端 1M context 的影响

• D 端 KV Cache = 整个 1M 的 prefix KV——需要 62,500 个 block（block_size=16）, 远超一般 D 实例 num_gpu_blocks（通常 5k~30k）
• Lease renewal 压力——5 分钟以上的 decode 要不断给 P 端 heartbeat（§8）
• OffloadingConnector 成刚需——CPU-only Tier 容量远超 HBM, 可以把 90%+ 的 block offload
• prefix caching 是另一个刚需——1M 共享 system prompt, 不同 conversation turn 的 prefix 大概率 cache hit, 大幅减少 D 端 KV 重建
• CPU bytes 预留建议——cpu_bytes_to_use 应比 D 端 GPU KV 容量大, 否则"镜像 CPU tier"没有意义

7.4 缓解路径

8. PD KV Transfer 的 D 端内存承诺（Lease / Push / Watchdog）(nixl_kv_cache_lease.md · nixl_kv_push_connector.md)

8.1 关键参数与默认值

8.2 D 端三个内存事件（push 模式, 详见 nixl_kv_push_connector.md）

1. 注册阶段：D scheduler 在 update_state_after_alloc 后, 把 local_block_ids(D 端预分配的 logical block ids) 打包成 PUSH_REG:<msgpack> 通知, 经 nixl-push-writer 线程发给 P
2. 写入完成：P 端 WRITE 完所有 block, 发 completion notif → D _pending_completion_notifs → finished_recving → scheduler 清除 watchdog
3. Watchdog 兜底：超过 push_registration_timeout 未完成, 取消注册, 由 engine 的 abort path 兜底 fail request

8.3 Lease renewal 对 D 端 KV Cache 的影响 (nixl_kv_cache_lease.md)

vLLM PD 中 D 端 heartbeat 必须在 request 入 scheduler 时就启动, 而不是被调度后才启动。这意味着：

• 等待队列中每个未调度的 request 都持续给 P 端续 lease
• D 端给 P 端续 lease 的代价：NIXL send_notif 一次 / 5 秒 per engine
• 但如果 D 端 scheduler 自身被 blocking 或排队太长, D 端等待队列中积累的 request 可能在 D 端还没被 schedule 就占着 D 端的 KV block——这就是 PD 下 D 端 KV Cache 的第一个"隐形杀手"

8.4 Lease 设计总结

P 端 lease 生命周期：
  prefill 完成 ---(30s)--> HB1 (D~5s 一次) ---(+20s)--> HB2 ... --> KV transfer 完成/超时清空

三种回收路径（lease.md §Lease lifecycle）：
  (1) D 完成 KV transfer → P 立即 free
  (2) D 持续 HB → lease 永远续
  (3) D crash / 超时 → lease 失效, P 在 ~20s 内 free

参考 PR：lease 机制由 PR #41383 引入

9. 引用 & 调研过程附件

9.1 主要引用来源

9.2 下载到本地的文件（vllm_pd_decode_memory/）

• design docs: nixl_kv_push_connector.md, nixl_kv_cache_lease.md, hybrid_kv_cache_manager.md, paged_attention.md, prefix_caching.md, arch_overview.md
• feature docs: conserving_memory.md, disagg_prefill.md, kv_offloading_usage.md
• 源码: vllm_config_cache.py (CacheConfig 完整定义), vllm_v1_worker_gpu_worker.py + gpu_model_runner.py, vllm_v1_core_kv_cache_manager.py + block_pool.py + kv_cache_utils.py, vllm_utils_mem_utils.py

9.3 关键发现总结

1. D 端 KV Cache 容量 = (total_gpu_memory × gpu_memory_utilization − non_kv_cache_memory − cudagraph_memory_estimate) ÷ page_size, 其中 page_size = block_size(默认 16) × num_layers × kv_hidden_size × num_kv_cache_groups（取 lcm）。
2. 所有关键默认值透明可查：block_size=16 / gpu_memory_utilization=0.92 / cache_dtype="auto" / enable_prefix_caching=True（均来自 vllm/config/cache.py）。
3. PD 后 D 端 KV Cache 的"承诺"模式：pull/push 都要求 D 端先分配 block, 再由 P 端 RDMA 写入。这是 D 端高并发时 HBM 紧张的第一原因。Lease renewal（30s + 20s/5s）是避免 P 端 KV 被长时间无效占用（D crash 等）的关键机制。
4. prefix caching + CPU offloading 是 PD D 端的双保险：OffloadingConnector（默认 offload_prompt_only=true）把已满 block 异步搬到 pinned CPU memory（DMA cudaMemcpyAsync）。
5. kv_cache_dtype 非常丰富的量化选型：支持 fp8 / fp8_ds_mla / nvfp4 / turboquant系列 / per-token-head 动态 scale, 让 D 端 KV 容量最多放大 5×。DeepSeek V3/R1 默认已是 fp8 KV。
6. 1M context 场景：1M token × 稀疏化 KV（MLA+fp8） ≈ 0.66 GiB / request, 但 MHA/GQA 模型高达 15 GiB / request——D 端 HBM 必须走 CPU offload + MLA + nvfp4 组合路径才有经济可行性。
7. vLLM v1 不支持 swap/restore preemption, 只有 RECOMPUTE, 所以 watermark_blocks 是避免频繁 preempt 的唯一护栏。PD 长等待队列会加剧这一路径的触发。