vllm 学习笔记

Appearance

自动识别并复用不同请求间相同 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 链。链式哈希的种子 NONE_HASH 对密码学哈希默认用固定种子 "vllm-none-hash"（#51875），保证跨进程 hash 一致——P2P offload / 多实例共享复用由此才能工作（P2P 握手经 get_none_hash_seed() 通告对端）。
  • Copy-on-Write：匹配的 block 被多个 sequence 共享引用，仅当 sequence 生成不同 token 时才分配新 block。
  • 自动前缀匹配：vLLM 支持自动前缀匹配（Automatic Prefix Caching, APC），无需用户手动标记。
  • LRU 淘汰：block pool 中的 cached block 按 LRU 策略淘汰，为新的 prefix 让出空间。
  • 有状态层（Mamba/KDA）：无逐 token KV，经「内部 prefill checkpoint」支持前缀复用——chunked prefill 中在内部对齐位置写状态快照（MambaSpec.prefill_checkpoint_alignment），TTFT 改善 9%~25%（#52789/#53614）；sliding-window/Mamba 组还可配 CacheConfig.prefix_cache_retention_interval（0=仅语义 checkpoint，正数=周期性稀疏 checkpoint，#52216）。

在源码中的实现 ​

  • vllm/v1/core/kv_cache_manager.py — KVCacheManager 支持 prefix caching 模式，维护 cached block 的 hash 索引。
  • vllm/v1/core/kv_cache_utils.py — 定义 block 的 hash 计算与比较逻辑；resolve_none_hash_seed / resolve_dcp_kv_block_size（DCP 下 block_size 乘 dcp_world_size）。
  • vllm/v1/core/block_pool.py — LRU 淘汰策略与 block→hash 反向索引，管理 cached block 的生命周期。
  • vllm/v1/kv_cache_interface.py — spec 类族；get_mamba_prefill_checkpoint_position() 判定内部 checkpoint 位置。
  • vllm/config/cache.py — CacheConfig.enable_prefix_caching 开关与 prefix_cache_retention_interval。

相关概念 ​

反向链接