KV Cache | vllm 学习笔记

存储注意力机制中 Key 和 Value 向量的缓存，避免自回归解码时重复计算已生成 token 的投影。

为什么需要 KV Cache

LLM 自回归生成时，每步需对全部历史 token 计算注意力。若不缓存 Key/Value，每步的计算量随序列长度线性增长，总复杂度退化为 O(n^2)。KV Cache 将已计算的 Key/Value 保留在显存中，使每步仅需计算新 token 的投影，将增量解码复杂度降至 O(1)。

Prefill 阶段：一次性计算 prompt 所有 token 的 K/V 并缓存。
Decode 阶段：仅计算新 token 的 Q/K/V，K/V 追加到缓存，用全量 K/V 与当前 Q 计算注意力。
显存瓶颈：KV Cache 占用与 batch_size * seq_len * num_layers * hidden_dim 成正比，是长序列推理的主要显存开销。
量化压缩：可用 FP8/INT8/INT4 对 KV Cache 进行量化，降低显存占用与带宽压力。
物理布局：逻辑形状统一为 [L, B, H, N, C]（Layer/Block/Head/NumStates/Content），由 KVCacheLayout 枚举描述（RFC #42082 收官：backend 经 supported_kv_cache_layouts() 声明偏好、engine core 一次性解析），取代了各后端自定义的 get_kv_cache_shape()。

vllm/v1/core/kv_cache_manager.py — KVCacheManager 追踪每个 sequence 的 KV block 使用情况。
vllm/v1/core/kv_cache_coordinator.py — HybridKVCacheCoordinator 协调多组 KV cache（混合注意力）与 partial prefix cache。
vllm/v1/core/block_pool.py — BlockPool 物理块池与引用计数、block→hash 反向索引。
vllm/v1/kv_cache_layout.py — KVCacheLayout 布局枚举（stride 置换 + is_block_contiguous 等谓词）。
vllm/v1/kv_cache_interface.py — spec 类族（AttentionSpec/MambaSpec/KpoolTailSpec 等）与 compute_layer_kv_cache_shape_bytes/create_kv_cache_views 几何计算。
vllm/v1/attention/backends/ — Attention 后端的 forward 接收 kv_cache 参数并执行 KV 读写。
vllm/config/ — 缓存配置（block_size、gpu_memory_utilization、dtype、kv_cache_layout）分散到 VllmConfig 的各子配置中（如 config/cache.py、config/model.py）。