AI Deploy大模型本地部署帮你部署

vLLM 前缀缓存配置与推理复用实践

讲解 vLLM 前缀缓存的启用方式、相同 token 前缀的复用条件与完整块哈希规则，并给出长文档、多轮对话的验证步骤及常见失效排查方法。

根据前缀缓存功能文档，前缀缓存（APC）会保存已有请求的 KV cache；后续请求共享同一 token 前缀时，可以复用并跳过共享部分的 prefill 计算，Python engine 可通过 enable_prefix_caching=True 显式启用。它适合反复询问同一长文档或复用历史的多轮对话，但只缩短 prefill，不缩短 decode；答案很长或没有共同前缀时，官方文档明确称没有性能收益。在线服务可用 vllm serve 接收 engine arguments，参数组织方式见引擎参数文档。

部署前准备什么

开始前先明确四项内容：

  • 找出多次请求中保持不变的前缀，例如系统说明、固定文档或历史对话，避免每轮重写。
  • 记录模型标识、实际版本和启动配置，方便复现实验环境。
  • 把 prefill 与 decode 分开观察，不用总响应时间代替缓存复用效果。
  • 准备一组不共享前缀的对照请求，用来区分“请求模式不同”和“缓存没有生效”。

vLLM 前缀缓存配置：显式启用并校准内存

在已能导入 LLM 的 Python 环境中，把前缀缓存参数明确写入引擎配置：

from vllm import LLM

llm = LLM(
    model="YOUR_VALUE",
    enable_prefix_caching=True,
)

当前 CacheConfig 源码把 enable_prefix_caching 默认设为 True。不过，源码默认值不代表所有已安装版本或启动包装脚本都相同；显式写出该参数更便于检查。在线命令行选项应以当前安装版本的 vllm serve --help 为准，不要仅按 Python 键名猜测连字符形式。

基础在线启动形式是：

vllm serve YOUR_VALUE

需要把上下文和显存预算写清楚时，可以按当前部署条件配置：

vllm serve YOUR_VALUE \
  --max-model-len YOUR_VALUE \
  --gpu-memory-utilization 0.92

按照vllm serve 命令参考，--max-model-len 表示 prompt 与 output 合计的上下文长度；未设置时从模型配置推导，指定 -1 或 auto 时会选择 GPU 内存能够容纳的最大长度。--gpu-memory-utilization 的文档默认值是 0.92，且它是每个实例的限制，不是同一 GPU 上所有实例共享的上限。如果设置 --kv-cache-memory-bytes YOUR_VALUE，则会直接指定每张 GPU 的 KV cache 大小，并覆盖 gpu_memory_utilization；两种设置不能当作可相加的额度。

哪些前缀能够复用

根据前缀缓存设计文档，vLLM 会把每个 KV-cache block 与该块的 token 以及此前的前缀 token 一起计算 hash。因此，前面任一 token 发生变化，都会影响后续块的匹配。文档还明确说明只缓存完整块，不应期待不足一个完整块的内容形成可复用块。

块标识还包含区分内容所需的额外值，例如 LoRA IDs、多模态输入 hash，以及用于多租户缓存隔离的 cache salt。多租户服务不能把请求里的普通用户字段当成唯一的缓存隔离依据。

从 v0.11 开始，默认 hash 算法是 sha256；可以通过 --prefix-caching-hash-algo 指定算法。需要跨语言生成可复现 hash 时，文档列出了 sha256_cbor。只在同一服务内部使用时，没有必要为了普通 APC 配置而随意更换算法。

推理复用实践：按请求序列验收

长文档问答应把固定文档放在前面，只替换末尾的问题。第一个请求建立可复用的完整块，第二个请求保持完全相同的 token 前缀并追加新问题。多轮对话则保持历史消息的内容和顺序，再追加新一轮内容；如果重写或摘要旧历史，前缀本身已经改变。

使用 Chat API 时，OpenAI 兼容服务器文档列出的路径是：

/v1/chat/completions

该接口需要模型提供 chat template，并且会忽略 user 参数。验收时按以下顺序检查：

  1. 用固定长前缀发送第一个请求，再以相同 token 前缀发送不同问题。
  2. 进行连续多轮对话，不改写前面的历史内容。
  3. 发送一条没有共同前缀的请求，作为对照。
  4. 分别记录 prefill 与 decode 的变化，不用请求成功或总耗时单独证明缓存命中。

所引接口文档没有给出可跨版本依赖的前缀缓存命中字段格式。若当前版本另外暴露了相关指标，应以其最新文档为准，不要自行假定字段名称；同时把验收范围限定在同一服务实例和同一配置内，因为这些文档没有承诺跨实例或重启后的持久复用。

常见失效点

  • 配置已启用但复用不明显：先检查前缀是否保持相同 token 序列、是否形成完整块，以及请求是否落到同一服务实例。
  • 总耗时看不出变化：分开观察 prefill 与 decode；长答案主要消耗生成阶段时，APC 本来就不会缩短该阶段。
  • 多租户结果混杂：核对 cache salt、LoRA IDs 和多模态输入 hash，不能只依赖被接口忽略的 user 参数。
  • 默认行为判断错误：当前源码的默认值不能替代对实际安装版本、启动脚本和运行配置的检查。
  • 无必要地更换 hash 算法：只有明确需要跨语言复现时，再按文档采用 sha256_cbor。

本文步骤仅按文中链接的官方文档整理，不包含运行结果；使用前请对照当前 vLLM 版本和实际启动配置复核。

资料来源