提示词缓存与性能入门教程

编辑部发布 2026-06-26 更新 2026-06-27 11 分钟阅读 2,149 字

提示词缓存（Prompt Caching）是一项通过复用先前计算的中间表示（KV Cache）来消除重复 token 计算的技术。对 API 调用者而言，它能将延迟降低 40–70%，并将输入 token 成本削减约 50%。然而，这种优化仅在提示词前缀完全一致、上下文窗口对齐且服务端明确支持时才会生效。本教程将从基础概念出发，逐步引导你掌握缓存配置、效果验证与常见问题的排查方法。

Before you start

准备工作

API 密钥：确保你持有支持提示词缓存的模型密钥。目前已验证支持的包括 Anthropic Claude 系列、部分 OpenAI 模型（如 gpt-4o）以及 Gemini 1.5 Pro/Flash。
开发环境：安装 HTTP 客户端或编程语言环境（cURL、Python 3.8+ 或 Node.js 18+ 均可）。
基础知识：熟悉 JSON 格式与 API 请求构造。
模型版本认知：不同模型可能采用各异的缓存机制。例如，Claude 3.5 Sonnet 与 Claude 3 Haiku 在缓存实现上存在显著差异，务必查阅官方文档确认细节。

缓存生效的三个硬性前提

前缀完全匹配：缓存键基于提示词开头的连续 token 序列构建。任何中间插入或删除字符（包括空格）都会打破匹配。
缓存粒度对齐：服务商对前缀长度有最小要求。Anthropic 以 1,024 token 为缓存区，OpenAI 则以 128 token 为单位。未达门槛的前缀不会被缓存。
缓存生存时间（TTL）：缓存通常在最近一次命中后 1–5 分钟内有效。若长时间未被访问，系统将自动清除。

Steps

第一步：构造支持缓存标记的请求

以 Anthropic API 为例，在请求体中使用 cache_control 关键字标记希望缓存的前缀段：

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "你是一位资深的技术文档翻译专家。",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "请将以下技术手册翻译成中文：\n\n[这里是实际内容...]"}
  ]
}

关键点：仅对重复出现的长期指令、角色设定或固定知识库前缀添加 cache_control。日常对话内容不应缓存。

第二步：在响应头中确认缓存命中

发送请求后，检查 API 响应的 HTTP 头部（以 Anthropic 为例）：

x-amz-cache-hit: cache_hit → 缓存命中，延迟降低。
x-amz-cache-hit: cache_miss → 未命中，仍占用完整计算资源。
x-request-id → 请求标识符，可用于后续调试。

常见误区：仅凭响应速度判断缓存状态，而忽略头部确认。网络波动可能导致偶然的低延迟，并非缓存所致。

第三步：至少发送两次相同前缀的请求

首次请求必定为 cache_miss，因为缓存初始为空。第二次及之后的相同前缀请求才可能命中。完整验证流程如下：

构造包含长期指令的提示词（确保前缀长度超过最小缓存单元）。
发送请求 A（预计 miss）。
在 5 秒内发送请求 B（内容不同但前缀相同），预计 hit。
对比两个请求响应中的 cache_creation_input_tokens 与 cache_read_input_tokens 数值，确认节省幅度。

第四步：计算实际成本与延迟节省

利用响应中的计费 token 明细量化收益：

指标	无缓存	有缓存（首次）	有缓存（后续命中）
输入 token 计费	全部输入	全部输入（缓存创建）	仅新增部分
延迟（典型值）	1,200–3,500ms	1,200–3,500ms	400–1,200ms
输入成本	高	高	降低约 50%

实际场景示例：在一个翻译工作流程中，系统提示词包含 2,000 token，每次请求仅新增 300 token 的待翻译内容。启用缓存后，后续请求的输入成本从 2,300 token 骤降至 300 token，延迟从 2–3 秒缩短至 0.6–1.2 秒。

Checks

缓存是否生效的快速自查清单

响应头部是否包含缓存相关字段（cache_hit / cache_read_input_tokens）？
第二次请求的 input_tokens 是否显著低于第一次？
日志中同一前缀的请求是否出现在 5 分钟内？
缓存前缀长度是否达到模型的最小要求（Anthropic：1,024 token；OpenAI：128 token）？

缓存无效的常见原因

前缀差异：即使一个空格或换行符不同，也会导致缓存 miss。务必通过日志或请求体对比工具（如 diff）确保前缀一致性。
模型版本变更：升级或回退 model 字符串（如 claude-3-5-sonnet-20241022 → claude-3-5-sonnet-20240620）会立即使缓存失效。
跨服务端节点：某些 API 采用多区域部署，缓存可能未同步。测试时优先使用同一 API 端点。
超过缓存 TTL：两次请求间隔超过 5–10 分钟（视服务商而定），缓存将被清除。

Troubleshooting

问题 1：始终收到 `cache_miss`

检查顺序：

确认 model 名称正确且该模型支持缓存。2024 年底起主流模型已陆续支持，但仍有例外，请查阅官方文档。
确认 cache_control 参数位于 system 或 messages 的 content 数组中，而非消息层级。
发送完全相同的请求两次（使用占位符保持前缀不变），排除微差异。

何时停止排查：如果确认上述检查无误后仍一直 miss，可能是 API 底层缓存策略变更。建议查阅官方版本发布说明，或切换到其他已验证模型。

问题 2：缓存命中但 token 节省不如预期

原因：cache_control 标记的范围过小。只有长度超过服务商最小缓存单元的片段才会被缓存。例如，标记一个 200 token 的 system prompt，而最小缓存单元为 1,024 token，则该标记无效。

解决办法：将固定知识库、角色设定、格式说明等内容合并为一个较大的前缀段，确保其长度超过最小缓存单元。避免分别标记多个小段。

问题 3：请求报错或忽略 `cache_control`

典型场景：返回 400 错误，提示 unknown parameter。常见于使用旧版 SDK 或直接发送请求但未包含正确的缓存参数格式。

回滚方案：

移除所有 cache_control 参数，确保基础请求正常。
确认端点版本与模型字符串，查询该版本的正确缓存语法。
逐项添加 cache_control，仅添加在 type: "text" 对象上，而非 message 级别。

FAQ