提示词缓存（提高缓存命中率）

多轮对话、长 system 提示词、反复带同一份文档的场景，每次请求里大部分输入都和上一次一样。开启提示词缓存后，这部分重复内容会走缓存：命中缓存的输入 token 按厂商的缓存读取刊例价计费，首 token 延迟通常也会下降。

本页适用于通过 POST /v1/messages（Claude 原生格式）调用、且支持提示词缓存的模型。在 模型广场 选择一个支持 /v1/messages 的模型，使用它的模型 ID。

基本做法：在内容块上标记 cache_control复制锚点链接

示例中的 your-model-id 请替换为模型广场中的模型 ID（也可以调用 GET /v1/models 查看）。

在希望缓存的内容块上加 "cache_control": {"type": "ephemeral"}。缓存按前缀生效：从请求开头到这个标记为止的全部内容（tools → system → messages）都会被缓存，下次请求前缀完全相同时直接命中。

最常见的写法是把长 system 提示词写成内容块数组，并在最后一块上打标记：

curl https://ai.myaiexp.com/v1/messages \
  -H "x-api-key: $MYAIEXP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. <long reference material here>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

多轮对话时，可以在最后一条消息的最后一个内容块上也加一个 cache_control，这样历史消息会随着对话增长持续命中缓存。

缓存时长：默认 5 分钟，可选 1 小时复制锚点链接

默认缓存有效期是 5 分钟，每次命中都会刷新计时。如果两次请求的间隔经常超过 5 分钟（例如用户隔十几分钟才回复一次），可以显式指定 1 小时缓存：

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

请求本身就很密集（间隔小于 5 分钟）时，5 分钟缓存会被不断刷新，一直有效，用 1 小时缓存反而多付写入费用。各模型的缓存写入、读取单价见 模型广场，价格每日同步各厂商官方公开刊例价。

测试命中率时注意：有最小 token 数限制复制锚点链接

缓存的前缀内容必须达到模型的最小长度，否则不会缓存，而且不会报错，只是 cache_creation_input_tokens 和 cache_read_input_tokens 都为 0。所以测试命中率时，不要用一两句话的短提示词去测，可以放一份较长的 system 提示词或文档。

不同模型的最小可缓存长度不同，且并不是越新的模型越小，具体数值以 Anthropic 官方文档 为准。如果两个缓存字段一直为 0，先把前缀加长再测。

如何确认命中复制锚点链接

看响应里的 usage 字段，同样的请求连续发两次。第二次的返回类似（数字仅为示意）：

"usage": {
  "input_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 2051,
  "output_tokens": 380
}

总输入 token = input_tokens + cache_creation_input_tokens + cache_read_input_tokens。每次请求的用量和扣费也可以在控制台的 使用日志 中查看。

提高命中率的小技巧复制锚点链接

• 固定内容放前面，变化内容放后面。 缓存按前缀匹配，顺序是 tools → system → messages，前面任何一个字节变化都会让后面的缓存失效。
• 不要在 system 里放时间戳、请求 ID 等每次都变的内容。 这是命中率为 0 最常见的原因。
• 工具列表和 JSON 要保持稳定。 每次请求的工具顺序、字段顺序都应一致。
• 多轮对话把断点放在最新的消息上。 断点跟着对话往后移，历史消息会持续命中。
• 一次请求最多 4 个缓存断点。 可以分别标在 tools、system 和消息上，分层缓存变化频率不同的内容。
• 用 /v1/messages。 cache_control 是 Anthropic Messages 格式的参数，需要精确控制缓存时请用本页的写法，而不是 Chat Completions。