启用缓存后,AI Gateway 可以缓存 AI 模型提供商的响应。对于相同请求,会直接从 Cloudflare 缓存提供响应。
- 降低延迟: 对重复请求避免往返源 AI 提供商,更快向用户提供响应。
- 节省成本: 减少对 AI 提供商的付费请求次数,尤其对频繁访问或非动态内容。
- 提高吞吐量: 将重复请求从 AI 提供商卸载,使其更高效地处理唯一请求。
缓存默认禁用。要全局启用缓存,请设置默认缓存配置:
要在仪表板中设置默认缓存配置:
- 登录 Cloudflare 仪表板 ↗ 并选择你的账户。
- 选择 AI > AI Gateway。
- 选择 Settings(设置)。
- 启用 Cache Responses(缓存响应)。
- 将默认缓存更改为你偏好的值。
要使用 API 设置默认缓存配置:
- 创建 API token,并授予以下权限:
AI Gateway - ReadAI 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(例如
Authorizationbearer token) - 完整请求体
这意味着缓存基于整个请求的精确匹配。请求体中的任何差异——包括 messages、tools 或 model 参数——都会产生单独的缓存条目。要覆盖此行为,请使用自定义缓存键标头。
Gateway 的默认缓存设置提供了良好基线,但你可能需要更细粒度的控制。这些情况包括数据新鲜度、内容生命周期各异,或动态/个性化响应。
为满足这些需求,AI Gateway 允许你通过特定 HTTP 标头按请求覆盖默认缓存行为,为单个 API 调用提供精确优化。
以下标头可定义按请求的缓存行为:
跳过缓存指绕过缓存,直接从原始提供商获取请求,不使用任何缓存副本。
可使用 cf-aig-skip-cache 标头绕过请求的缓存版本。
例如,向 OpenAI 提交请求时,按以下方式包含标头:
# 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 设置缓存时长。要为单个请求启用缓存,请包含 cf-aig-cache-key。最短 TTL 为 60 秒,最长为一个月。
例如,若设置 TTL 为一小时,请求将在缓存中保留一小时。在该小时内,相同请求将从缓存而非原始 API 提供。一小时后缓存过期,请求将访问原始 API 获取新响应,并重新填充缓存。
例如,向 OpenAI 提交请求时,按以下方式包含标头:
# 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-ttl,该请求会将其用作缓存 TTL;否则使用网关配置的默认缓存 TTL。对于包含 cf-aig-cache-key 的请求,如果既未配置 cf-aig-cache-ttl,也未配置默认网关缓存 TTL,则缓存 TTL 为 5 分钟。
例如,向 OpenAI 提交请求时,按以下方式包含标头:
# 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"
}
]
}'