缓存 · Cloudflare AI Gateway docs

AI Gateway 可以缓存 AI 模型提供商的响应，对相同请求直接从 Cloudflare 缓存提供。

使用缓存的优势

降低延迟： 对重复请求避免往返源 AI 提供商，更快向用户提供响应。
节省成本： 减少对 AI 提供商的付费请求次数，尤其对频繁访问或非动态内容。
提高吞吐量： 将重复请求从 AI 提供商卸载，使其更高效地处理唯一请求。

默认配置

要在仪表板中设置默认缓存配置：

登录 Cloudflare 仪表板 ↗ 并选择你的账户。
选择 AI > AI Gateway。
选择 Settings（设置）。
启用 Cache Responses（缓存响应）。
将默认缓存更改为你偏好的值。

要使用 API 设置默认缓存配置：

创建 API token，并授予以下权限：

AI Gateway - Read
AI Gateway - Edit

获取你的 Account ID。
使用该 API token 和 Account ID，发送 POST 请求创建新 Gateway，并为 cache_ttl 指定值。

此缓存行为将统一应用于所有支持缓存的请求。若需为特定请求修改缓存设置，可按请求灵活覆盖。

要检查响应是否来自缓存，cf-aig-cache-status 将标记为 HIT 或 MISS。

缓存键的工作原理

默认情况下，AI Gateway 通过拼接以下内容并用 SHA-256 哈希构建缓存键：

Provider（例如 openai、anthropic）
Endpoint（API 路径）
Model（例如 gpt-4o）
Provider authentication header（例如 Authorization bearer token）
完整请求体

这意味着缓存基于整个请求的精确匹配。请求体中的任何差异——包括 messages、tools 或 model 参数——都会产生单独的缓存条目。要覆盖此行为，请使用自定义缓存键标头。

按请求缓存

Gateway 的默认缓存设置提供了良好基线，但你可能需要更细粒度的控制。这些情况包括数据新鲜度、内容生命周期各异，或动态/个性化响应。

为满足这些需求，AI Gateway 允许你通过特定 HTTP 标头按请求覆盖默认缓存行为，为单个 API 调用提供精确优化。

以下标头可定义按请求的缓存行为：

跳过缓存 (cf-aig-skip-cache)

跳过缓存指绕过缓存，直接从原始提供商获取请求，不使用任何缓存副本。

可使用 cf-aig-skip-cache 标头绕过请求的缓存版本。

例如，向 OpenAI 提交请求时，按以下方式包含标头：

Request skipping the cachebash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-skip-cache: true" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'

缓存 TTL (cf-aig-cache-ttl)

Cache TTL（生存时间）是缓存请求在过期并从原始源刷新之前保持有效的时长。可使用 cf-aig-cache-ttl 设置所需缓存时长（秒）。最小 TTL 为 60 秒，最大 TTL 为一个月。

例如，若设置 TTL 为一小时，请求将在缓存中保留一小时。在该小时内，相同请求将从缓存而非原始 API 提供。一小时后缓存过期，请求将访问原始 API 获取新响应，并重新填充缓存。

例如，向 OpenAI 提交请求时，按以下方式包含标头：

Request to be cached for an hourbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-cache-ttl: 3600" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'

自定义缓存键 (cf-aig-cache-key)

自定义缓存键可覆盖默认缓存键，精确设置任何资源的可缓存性。要覆盖默认缓存键，可使用 cf-aig-cache-key 标头。

首次使用 cf-aig-cache-key 标头时，你将收到来自提供商的响应。后续使用相同标头的请求将返回缓存响应。若使用 cf-aig-cache-ttl 标头，响应将按指定的 Cache Time To Live 缓存。否则，响应将按仪表板中的缓存设置缓存。若 gateway 未启用缓存，响应默认缓存 5 分钟。

例如，向 OpenAI 提交请求时，按以下方式包含标头：

Request with custom cache keybash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-cache-key: responseA" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'