Prompt Caching

Prompt Caching 用于缓存重复的长上下文，适合固定系统提示词、大段知识库上下文、长文档问答和重复业务规则。它可以降低重复输入的成本，并改善部分长上下文场景的延迟。

什么是 Prompt Caching

Prompt Caching 会缓存请求中可复用的前缀内容，例如工具定义、系统提示词和消息内容。后续请求只要命中相同前缀，就可以复用缓存。

常见缓存内容包括：

• 固定工具定义
• 长系统提示词
• 业务规则
• 知识库材料
• 大型文档内容
• 长对话中的稳定历史

适合哪些场景

场景	适合原因
长系统提示词	多次请求中保持不变
大段知识库上下文	用户围绕同一资料连续提问
固定背景资料	规则、合同、产品手册重复使用
多轮文档问答	文档内容稳定，用户问题变化
Agent 工具定义	工具列表通常比用户问题更稳定

长系统提示词缓存

可以把稳定的系统提示词写成内容块，并在可复用段落末尾增加 cache_control。

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are an enterprise knowledge-base assistant. Here are the fixed business rules and answer boundaries: ...",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What is the customer refund policy?"
    }
  ]
}

大段知识库上下文缓存

当多个问题围绕同一份文档时，可以缓存文档正文，把用户问题放在后面。

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here is the full product manual: ...",
          "cache_control": {
            "type": "ephemeral"
          }
        },
        {
          "type": "text",
          "text": "Answer this: how do I configure an API key?"
        }
      ]
    }
  ]
}

固定背景资料缓存

固定背景资料应放在请求前部，动态问题放在请求后部。缓存命中依赖内容完全一致，所以不要把时间戳、随机 ID、用户临时状态混入缓存段。

如何设计缓存边界

• 把稳定内容放在前面
• 把每次变化的用户问题放在后面
• 在稳定内容末尾设置 cache_control
• 避免在缓存段中加入当前时间、请求 ID 等动态内容
• 对大型上下文按变化频率拆分缓存边界

成本优化

缓存适合重复使用的长内容。短 prompt 或一次性请求通常不需要缓存。使用前应评估：

• 上下文是否足够长
• 是否会被多次复用
• 多次请求是否能保持完全相同的缓存前缀
• 业务是否能接受缓存写入和读取的计费方式

延迟优化

命中缓存后，长上下文重复处理的开销会降低。对于文档问答、长规则客服、复杂工具定义等场景，可以明显改善连续请求体验。

注意事项

• 缓存命中要求缓存前缀完全一致
• 缓存有最小 token 长度要求，过短内容不会产生明显收益
• 默认缓存时长适合短时间内重复调用
• 需要更长复用窗口时，可以按官方能力选择更长 TTL
• 通过响应中的 usage 字段观察缓存创建和读取情况