提示词缓存

自动提示词缓存允许 AISIX 为直接 Anthropic 模型的请求添加 Anthropic 提示词缓存标记，使调用方无需修改请求即可获得模型服务提供方的提示词缓存折扣。这是 Claude 模型上的模型服务提供方侧提示词缓存，不是复用已存储响应的网关侧响应缓存。

本指南将介绍如何在 Anthropic 模型上启用自动提示词缓存、选择缓存有效期，并验证具有稳定前缀的重复请求会以折扣价格读取缓存。

自动提示词缓存的工作原理

Anthropic 提示词缓存需要每个请求显式启用：调用方使用 cache_control 标记稳定前缀，之后模型服务提供方会在后续请求中以较低输入价格从缓存提供该前缀。许多客户端从不设置这些标记，因此每轮都需支付完整输入费用。

在模型上启用自动提示词缓存后，AISIX 会为未携带任何标记的调用方添加标记：

在最后一个系统内容块上添加一个标记，用于缓存稳定的工具和系统前缀。
在最后一条消息的最后一个内容块上添加一个标记，用于缓存整个对话前缀。因为标记位于最后一轮，对话增长时缓存前缀也会随之推进并增量重新缓存。

AISIX 最多只添加这两个标记，而且仅在请求未携带任何自定义标记时添加，因此不会超过模型服务提供方每个请求最多四个断点的限制。

如果调用方已经发送了任何 cache_control 标记，AISIX 会原样转发请求，不再添加标记。调用方自定义的缓存策略始终优先。

配置自动提示词缓存

自动提示词缓存是直接 Anthropic 模型的模型级设置，除非显式启用，否则处于关闭状态。

创建或更新模型时添加 auto_prompt_caching 配置：

{
  "enabled": true,
  "ttl": "5m"
}

字段	类型	描述
`enabled`	boolean	AISIX 是否为此模型注入提示词缓存标记。
`ttl`	string	注入标记的缓存有效期：`5m`（省略时的默认值）或 `1h`。参见选择缓存有效期。

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个 Anthropic 模型服务提供方密钥，以及可向 Claude 模型发送 Chat Completions 请求的调用方 API Key。

在模型上启用

创建一个已启用自动提示词缓存的直接 Anthropic 模型：

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export PROVIDER_KEY_ID="YOUR_ANTHROPIC_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "display_name": "claude-prod",
    "provider": "anthropic",
    "model_name": "claude-sonnet-4-5",
    "provider_key_id": "${PROVIDER_KEY_ID}",
    "auto_prompt_caching": {
      "enabled": true,
      "ttl": "5m"
    }
  }
EOF

若要为现有模型启用，请在发送给模型资源的 PATCH 请求中加入相同的 auto_prompt_caching 配置。空对象会清除此设置。

备注

自动提示词缓存仅适用于直接 Anthropic 模型。在路由、合议、语义或向量嵌入模型上设置 auto_prompt_caching 会被拒绝。

在 AISIX Cloud 中，可从控制台的模型表单启用：展开 Automatic prompt caching，开启该功能并选择缓存有效期。

选择缓存有效期

Anthropic 仅支持以下两种缓存有效期，AISIX 会注入你选择的值：

有效期	`ttl`	缓存写入费用	缓存读取费用
5 分钟（默认）	`5m`	基础输入价格的 1.25 倍	基础输入价格的 0.1 倍
1 小时	`1h`	基础输入价格的 2 倍	基础输入价格的 0.1 倍

两种有效期的缓存读取价格相同，差别在于写入费用和前缀保留时长。读取缓存还会刷新条目，因此持续使用的前缀会一直保持热状态。

大多数场景应使用 5m。它的写入费用更低，只需一次缓存读取即可达到收支平衡。只有当相同前缀会在超过五分钟的间隔后继续复用时才选择 1h，例如多轮之间存在空闲时段的长 Agent 会话；此时较高的写入费用可通过避免重复写入抵消。

有关当前倍率和支持的有效期，请参阅 Anthropic 提示词缓存文档。

验证缓存折扣

复用较大且稳定的前缀时，自动提示词缓存才能产生收益。发送两个共享同一系统提示词的请求，观察第一次写入缓存、第二次读取缓存。

发送带有较长系统提示词的第一个请求：

# 请替换为实际值
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-prod",
    "messages": [
      {"role": "system", "content": "<a long, stable system prompt above the model minimum>"},
      {"role": "user", "content": "First question"}
    ]
  }'

发送第二个请求，并保持相同的系统提示词：

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-prod",
    "messages": [
      {"role": "system", "content": "<the same long, stable system prompt>"},
      {"role": "user", "content": "Second question"}
    ]
  }'

网关会为第一个请求记录缓存写入 Token，为第二个请求记录缓存读取 Token，并按折扣价格计算缓存读取 Token。缓存写入和读取 Token 数会与提示词及补全 Token 一起出现在用量记录中，因此折扣会自动反映在预算和支出报告中。如需查看每个请求的缓存 Token，请参阅指标和日志。

备注

只有当前缀达到每个模型规定的最小长度时，Anthropic 才会缓存。低于该下限的前缀会正常处理且不会返回错误，但短提示词不会发生变化。自动提示词缓存最适合包含较大、稳定系统提示词或工具定义的请求。

范围和限制

自动提示词缓存适用于直接 Anthropic 模型，尚不适用于通过 Amazon Bedrock 或 Google Vertex AI 提供的 Claude 模型。这些模型的调用方仍可自行设置 cache_control 标记，AISIX 会原样转发。
模型服务提供方按 Anthropic 账号缓存前缀，而不是按 AISIX 组织或调用方 API Key 隔离。共享同一 Anthropic 模型服务提供方密钥的调用方也共享模型服务提供方侧缓存。如需在租户之间隔离缓存，请为每个租户分配独立的模型服务提供方密钥。
缓存读取 Token 不计入 Anthropic 的每分钟输入 Token 限制，因此缓存较大前缀还能提高该限制下的可用吞吐量。

后续步骤

你已经为 Anthropic 模型启用自动提示词缓存并验证缓存读取折扣。接下来可以：

在预算中跟踪相应成本。
添加网关侧响应缓存，对重复的相同请求复用完整响应。

自动提示词缓存的工作原理​

配置自动提示词缓存​

准备工作​

在模型上启用​

选择缓存有效期​

验证缓存折扣​

范围和限制​

后续步骤​