跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

缓存

最后更新 查看 MarkdownAgent 设置

启用缓存后,AI Gateway 可以缓存 AI 模型提供商的响应。对于相同请求,会直接从 Cloudflare 缓存提供响应。

使用缓存的优势

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

默认配置

缓存默认禁用。要全局启用缓存,请设置默认缓存配置:

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

  1. 登录 Cloudflare 仪表板 ↗ 并选择你的账户。
  2. 选择 AI > AI Gateway。
  3. 选择 Settings(设置)。
  4. 启用 Cache Responses(缓存响应)。
  5. 将默认缓存更改为你偏好的值。

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

  1. 创建 API token,并授予以下权限:
  • AI Gateway - Read
  • AI Gateway - Edit
  1. 获取你的 Account ID。
  2. 使用该 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)

缓存 TTL(生存时间)是已缓存请求在过期并从原始来源刷新之前保持有效的时长。对于已经使用缓存的请求,请使用 cf-aig-cache-ttl 设置缓存时长。要为单个请求启用缓存,请包含 cf-aig-cache-key。最短 TTL 为 60 秒,最长为一个月。

例如,若设置 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.
# Use a key shared only by requests with equivalent responses.
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: responseWithCustomTtl" \
  --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,该请求会将其用作缓存 TTL;否则使用网关配置的默认缓存 TTL。对于包含 cf-aig-cache-key 的请求,如果既未配置 cf-aig-cache-ttl,也未配置默认网关缓存 TTL,则缓存 TTL 为 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"
      }
    ]
  }'

这篇文档对您有帮助吗?