Anthropic 提示词缓存

Anthropic 自动提示词缓存允许 AISIX 为直连 Claude 模型的合格请求添加缓存标记，调用方无需自行添加标记即可获得模型服务提供方缓存折扣。这是针对重复提示词前缀的模型服务提供方侧缓存，不同于存储并复用完整响应的网关侧响应缓存。

本指南介绍如何通过 AISIX Cloud 或声明式资源文件启用自动提示词缓存、选择缓存有效期，并验证稳定前缀的缓存创建 Token 和缓存读取 Token。

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

Anthropic 提示词缓存要求每个合格请求包含 cache_control 标记。调用方可以自行放置标记，也可以让 AISIX 为已配置模型自动添加。后续请求中，Anthropic 可以按较低输入费率从缓存提供带标记的前缀；没有标记时，提示词按标准输入费率处理。

在模型上启用自动提示词缓存后，对于不含调用方自定义标记的请求，AISIX 最多添加两个标记：

如果请求包含非空系统内容块，AISIX 会标记其最后一个内容块，以缓存工具和系统前缀。
如果最后一条消息包含非空的最后一个内容块，AISIX 会标记该内容块，以缓存对话前缀。由于标记位于最后一轮，对话增长时，缓存前缀也会推进，新内容会被增量缓存。

AISIX 最多只添加这两个标记，而且只会添加到不含自定义标记的请求中，因此不会超过模型服务提供方每个请求最多四个断点的限制。

如果调用方已发送任意 cache_control 标记，AISIX 会保留调用方的标记，不再添加任何标记。调用方的缓存策略优先。

启用自动提示词缓存

自动提示词缓存是模型级设置，默认关闭。请选择 AISIX Cloud 或开源配置路径。

准备工作

开始前，请准备以下内容：

以下配置路径之一：
- AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
一个 Anthropic 模型服务提供方密钥、一个直连 Claude 模型，以及有权使用该模型的调用方 API Key。
用于验证模型服务提供方缓存创建和读取的真实 Anthropic 凭证。无需发送真实模型请求也可以验证配置结构。
对于开源验证：已配置的 Datadog、阿里云 SLS 或对象存储导出器。OTLP 导出器不会公开缓存专属 Token 计数器。
用于验证请求的 curl 和 jq。

自动提示词缓存只支持直连 Anthropic 模型。请勿在路由、合议、语义或向量嵌入模型上设置。对于通过 Amazon Bedrock 或 Google Vertex AI 提供的 Claude 模型，AISIX 也不会注入标记。

AISIX Cloud

导出控制平面连接参数和直连 Claude 模型的 ID：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export MODEL_ID="YOUR_DIRECT_MODEL_ID"

在模型上启用自动提示词缓存：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_prompt_caching": {
      "enabled": true,
      "ttl": "5m"
    }
  }' | jq

在另一个 PATCH 请求中发送空的 auto_prompt_caching 对象，可清除该设置。

也可以使用控制台模型表单。打开 Automatic prompt caching，将其开启并选择缓存有效期。

开源 AISIX 网关

在 resources.yaml 的直连 Anthropic 模型中添加 auto_prompt_caching：

resources.yaml
models:
  - display_name: claude-prod
    provider: anthropic
    model_name: claude-sonnet-4-5
    provider_key: anthropic-prod
    auto_prompt_caching:
      enabled: true
      ttl: 5m

provider_key 的值必须指向 provider_keys 下的 Anthropic 条目。验证完整资源文件，然后重新加载网关。可运行的 Docker 工作流参见重新加载资源文件。

配置字段

两种配置路径使用以下字段。只要对象包含配置字段，就必须提供 enabled。

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

选择缓存有效期

Anthropic 支持两种缓存有效期，AISIX 会注入所选值：

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

两种有效期读取缓存时使用相同折扣费率，差别在于缓存创建费用和前缀保留时长。缓存读取还会刷新条目，因此只要前缀持续活跃，其有效期就会延长。

默认使用 5m。它的缓存创建费用较低，只需一次缓存读取即可达到收支平衡。只有同一前缀会在超过五分钟的间隔后继续复用时才选择 1h。例如，对于各轮之间存在空闲时段的长 Agent 会话，较高的创建费用可以避免反复创建缓存条目，因此可能更划算。

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

验证缓存折扣

复用较大且稳定的前缀时，自动提示词缓存才会产生收益。要进行验证，请发送两个共享相同前缀的请求，并检查缓存创建和读取 Token。

Anthropic 对每种模型的缓存提示词有最小长度要求。较短的前缀会正常处理且不缓存，也不会返回错误。因此，请使用满足所选 Claude 模型最低要求的前缀。

导出网关连接和请求参数：

# AISIX_PROXY 末尾不包含斜杠或 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="YOUR_DIRECT_MODEL_ALIAS"

使用足够长且稳定的系统提示词发送第一个请求。将占位符替换为真实提示词，并在第二个请求中使用完全相同的文本：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {"role": "system", "content": "<a stable system prompt that meets the model minimum>"},
      {"role": "user", "content": "First question"}
    ]
  }' | jq

第一个请求应记录缓存创建 Token。发送第二个请求，并保持系统提示词完全相同：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {"role": "system", "content": "<a stable system prompt that meets the model minimum>"},
      {"role": "user", "content": "Second question"}
    ]
  }' | jq

第二个请求应记录缓存读取 Token。通过适用路径检查两个请求：

**AISIX Cloud：**打开环境的 Logs 页面。第一个请求显示 Cache creation tokens，第二个请求显示 Cache read tokens。
**开源 AISIX 网关：**在对象存储或 SLS 记录中检查 cache_creation_tokens 和 cache_read_tokens，或在 Datadog 中检查 aisix.cache_creation_tokens 和 aisix.cache_read_tokens。

token_type="total" 网关指标也包含 Anthropic 缓存创建和读取 Token，但不会区分二者。

AISIX 会把缓存创建和读取 Token 与普通输入 Token 分开记录。在 AISIX Cloud 中，模型服务提供方折扣后的缓存读取费用会反映在预算和支出报告中。两种缓存 Token 都会计入 AISIX 基于 Token 的限流。

范围和限制

自动提示词缓存适用于通过 /v1/chat/completions 或 /v1/responses 发送到直连 Anthropic 模型的规范化请求。对于 Anthropic 模型，原生 /v1/messages 路由会原样透传：AISIX 不会在该路由上自动添加标记，但会保留调用方提供的标记。
Anthropic 按自身组织和工作区边界隔离缓存，而不是按 AISIX 组织或调用方 API Key 隔离。因此，共用同一 Anthropic 模型服务提供方密钥的调用方可以共享同一模型服务提供方侧缓存。如需在租户之间隔离缓存，请使用来自不同 Anthropic 工作区的模型服务提供方密钥。
缓存读取 Token 不计入 Anthropic 的每分钟输入 Token 限制。该模型服务提供方行为独立于 AISIX 基于 Token 的限流；AISIX 限流会同时计入缓存读取和缓存创建 Token。

后续步骤

你已经启用自动提示词缓存，并验证了模型服务提供方缓存折扣。接下来：

在 AISIX Cloud 中，通过预算跟踪相应成本。
当相同请求可以复用完整响应时，添加网关侧响应缓存。

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

启用自动提示词缓存​

准备工作​

AISIX Cloud​

开源 AISIX 网关​

配置字段​

选择缓存有效期​

验证缓存折扣​

范围和限制​

后续步骤​