文本生成/Claude API 提示词缓存高命中配置指南

通过 UniGateway 配置 Claude 提示词缓存，最大化缓存前缀复用并验证实际命中。

Claude API 提示词缓存高命中配置指南

通过 UniGateway 使用 Claude Messages API 时，将稳定内容放在前面、动态内容放在后面，并保持缓存断点之前的前缀不变，可以提高提示词缓存的复用率。

缓存命中取决于实际请求结构、模型的最小可缓存长度、请求间隔和前缀复用程度。本文提供最大化复用的配置方式，不承诺所有工作负载都能达到固定命中率。

前置条件

  • 已获取 UniGateway API Key，并将其保存为 UNIGATEWAY_API_KEY
  • 已通过 GET /v1/models 确认目标 Claude 模型在当前账号中可用
  • 使用 POST /v1/messages 发送 Anthropic Messages API 请求

追加式多轮对话

当会话历史只会在末尾追加新消息时，在请求顶层添加标准 cache_control 对象：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "cache_control": {
    "type": "ephemeral"
  },
  "system": "长期稳定的系统指令",
  "messages": [
    {"role": "user", "content": "第一轮问题"},
    {"role": "assistant", "content": "第一轮回答"},
    {"role": "user", "content": "本轮新增问题"}
  ]
}

自动缓存会在最近的可缓存内容处建立断点，并随对话增长向前推进。它适合历史消息只追加、不重写的聊天场景。

固定前缀与动态问题

当系统指令、工具定义或参考资料长期不变，而每次问题不同，请将断点放在最后一个稳定内容块上：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "长期稳定的系统指令和参考资料",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "本次动态问题"}
      ]
    }
  ]
}

不要将断点放在时间戳、实时检索结果或本轮用户问题之后。这样每次请求都会建立新的缓存，而不是读取已有缓存。

保持前缀可复用

Claude 按 tools、system、messages 的顺序形成缓存前缀。断点覆盖其之前的全部内容，应按以下顺序组织请求：

  1. 固定的工具定义及其 schema。
  2. 固定的系统指令、规则和长期参考资料。
  3. 可追加的对话历史或版本固定的上下文。
  4. 本次用户问题、时间戳、实时检索结果等动态内容。

命中要求断点之前的文本和图片完全一致。请保持以下内容不变：

  • 同一复用流量使用同一模型。
  • 工具数组、工具定义和 schema 的内容及顺序。
  • 系统提示词、参考资料和图片的内容及顺序。
  • 历史消息的既有部分；历史应追加而不是重写、重排或重新序列化。
  • cache_control 的位置，以及会影响消息内容的请求配置。

断点与 TTL

  • 每个 cache_control 都应填写 "type": "ephemeral"。
  • 单个请求最多可使用 4 个缓存断点；顶层自动缓存也计入此上限。无必要时，不要混用自动缓存和多个显式断点。
  • 默认 TTL 为 5 分钟。每次读取会刷新该 TTL。
  • 预计下一次复用会超过 5 分钟但不超过 1 小时时，可在断点上配置 1 小时 TTL：
{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "1h"
  }
}

1 小时缓存写入成本高于 5 分钟缓存，应只用于会在该时间窗口内再次使用的长稳定前缀。一个请求混用两种 TTL 时，所有 1h 断点必须出现在所有 5m 断点之前。

缓存前缀还必须达到所选模型的最小可缓存 token 长度。该阈值因模型而异；低于阈值的请求会正常执行，但不会建立缓存。上线前请依据 Anthropic 最新文档核对所用模型的阈值。

验证缓存命中

先发送一次请求建立缓存。收到该请求的首个响应后，再发送一个缓存前缀完全相同的请求。并发的首次请求不能共享尚未就绪的缓存。

检查响应中的 usage：

字段含义
cache_creation_input_tokens本次新建或重建缓存的 token 数。
cache_read_input_tokens本次从缓存读取的 token 数；大于 0 表示实际命中。
input_tokens未作为缓存读写处理的输入 token 数。
cache_creation.ephemeral_5m_input_tokens / cache_creation.ephemeral_1h_input_tokens可用时，分别显示按 TTL 新建的缓存 token 数。

按 token 而不是按请求数量计算缓存复用率：

cache_read_input_tokens
-----------------------------------------------
input_tokens + cache_creation_input_tokens + cache_read_input_tokens

对一组重复请求汇总上式中的字段。首次创建缓存的请求不应被当作命中；后续请求的 cache_read_input_tokens 才是实际复用证据。

预热热点前缀

对于首轮延迟敏感且会被频繁复用的长稳定前缀，可使用 max_tokens: 0 配合显式断点预热。预热请求仍会产生缓存写入成本，且断点必须位于未来真实请求也会保持相同的稳定前缀末尾。不要将占位的动态用户消息作为预热断点的一部分。

发布前检查

  • 所有缓存标记都包含 "type": "ephemeral"。
  • 断点位于稳定内容的末尾，动态内容位于断点之后。
  • 同一复用流量的模型、工具、系统提示词、图片和既有历史完全一致。
  • 缓存前缀满足所选模型当前的最小可缓存长度。
  • 首次创建后，第二次相同前缀请求的 cache_read_input_tokens 大于 0。
  • 缓存命中率按 token 汇总，不将首次写缓存请求当作命中。

官方参考