KV Cache Offloading | vllm 学习笔记

将不活跃的 KV Cache 从 GPU 显存卸载到 CPU 内存或磁盘，在有限显存下支持更长上下文或更大 batch。

为什么需要 KV Cache Offloading

KV Cache 随序列长度和 batch size 线性增长，很快耗尽 GPU 显存。在长上下文场景（128K+ tokens）中，KV Cache 可能占用数十 GB 显存，远超模型权重本身。KV Cache Offloading 将暂时不活跃的 KV block 搬移到 CPU 内存（或磁盘），在需要时再搬回 GPU，以时间换空间。

核心原理

Swap 机制：当 GPU 显存不足时，调度器选择部分 sequence 的 KV Cache swap 到 CPU pinned memory。
Recompute 机制：也可选择丢弃 KV Cache 并在需要时从原始 token 重新计算，适用于重计算成本较低的场景。
预取（Prefetch）：在 sequence 即将被调度前异步将其 KV Cache 从 CPU 预取到 GPU，掩盖传输延迟。
层级管理：Hot KV 在 GPU、Warm KV 在 CPU、Cold KV 可选择丢弃，形成多级缓存层次。

在源码中的实现

vllm/worker/cache_engine.py — CacheEngine 的 swap_in/swap_out 方法执行 GPU-CPU 数据搬运。
vllm/core/block_manager.py — BlockSpaceManager 追踪哪些 block 在 GPU、哪些被 swap 到 CPU。
vllm/core/scheduler.py — Scheduler 在显存不足时触发 preempt 和 swap 决策。
vllm/swap_manager.py — 管理 swap buffer 的分配和异步传输。
vllm/v1/kv_offload/tiering/fs/ — 文件系统分层：FileSystemTierManager + DualQueueThreadPool 实现磁盘级 KV 缓存。
vllm/v1/kv_offload/file_mapper.py — 将 KV block 哈希映射到文件路径（哈希子目录结构）。
vllm/distributed/kv_connector/v1/mooncake/ — MooncakeStore 分布式 KV 缓存连接器（支持多组 KV cache）。
vllm/distributed/kv_connector/v1/simple_cpu_offload_connector.py — Simple CPU Offload 后端（支持 DSV4 混合注意力）。

为什么需要 KV Cache Offloading ​

核心原理 ​

在源码中的实现 ​

相关概念 ​

为什么需要 KV Cache Offloading

核心原理

在源码中的实现

相关概念