自动识别并复用不同请求间相同 prompt 前缀的 KV Cache，避免重复计算。

为什么需要 Prefix Caching

在对话场景中，不同用户请求共享相同的 system prompt，或同一用户的多次请求共享历史对话。对这些共享前缀重复计算 KV 是巨大的浪费。Prefix Caching 利用 PagedAttention 的 block 机制实现 Copy-on-Write 共享，多个请求复用同一组物理 KV block，首 token 延迟和计算成本大幅降低。

核心原理

• Hash 索引：对 prompt token 序列计算 hash，在 block pool 中查找是否有完全匹配的前缀 block 链。
• Copy-on-Write：匹配的 block 被多个 sequence 共享引用，仅当 sequence 生成不同 token 时才分配新 block。
• 自动前缀匹配：vLLM 支持自动前缀匹配（Automatic Prefix Caching, APC），无需用户手动标记。
• LRU 淘汰：block pool 中的 cached block 按 LRU 策略淘汰，为新的 prefix 让出空间。

在源码中的实现

• vllm/core/block_manager.py — BlockSpaceManager 支持 enable_caching 模式，维护 cached block 的 hash 索引。
• vllm/core/block/block_hash.py — 定义 block 的 hash 计算与比较逻辑。
• vllm/core/eviction_policy.py — LRU 等淘汰策略管理 cached block 的生命周期。
• vllm/config.py — CacheConfig.enable_prefix_caching 开关。

相关概念

• paged-attention — Block 级共享是 prefix caching 的基础
• kv-cache — 被缓存和复用的数据结构
• chunked-prefill — 前缀命中后可跳过对应 chunk 的计算
• kv-cache-offloading — Prefix cache 也可卸载到 CPU 降低显存压力