キャッシュ

キャッシュを有効にすると、AI Gateway は AI モデルプロバイダーからのレスポンスをキャッシュできます。同一リクエストには、Cloudflare のキャッシュから直接返します。

キャッシュを使う利点

レイテンシの低減: 繰り返しのリクエストでオリジンの AI プロバイダー往復を避け、ユーザーへ速く返せます。
コスト削減: 有料リクエストの回数を減らせます。特に、よく参照する内容や動的でない内容で効果があります。
スループットの向上: 繰り返しリクエストを AI プロバイダーから切り離し、固有のリクエスト処理に回せます。

デフォルト設定

キャッシュはデフォルトで無効です。全体で有効にするには、デフォルトのキャッシュ設定を指定します。

ダッシュボードでデフォルトのキャッシュ設定を指定する手順:

Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
AI > AI Gateway を選択します。
Settings を選択します。
Cache Responses を有効にします。
デフォルトのキャッシュ値を、希望する値に変更します。

API でデフォルトのキャッシュ設定を指定する手順:

次の権限で API トークンを作成します。

AI Gateway - Read
AI Gateway - Edit

Account ID を取得します。
その API トークンと Account ID を使い、新しい Gateway を作成する POST リクエストを送り、cache_ttl の値を含めます。

キャッシュを全体で有効にすると、キャッシュ対応のすべてのリクエストにデフォルト動作が適用されます。個別リクエストをキャッシュ対象にしたり、リクエスト単位のヘッダーでキャッシュ設定を上書きしたりもできます。

レスポンスがキャッシュ由来かどうかは、cf-aig-cache-status が HIT か MISS かで分かります。

キャッシュキーの仕組み

デフォルトでは、AI Gateway は次を連結し、SHA-256 でハッシュしてキャッシュキーを作ります。

プロバイダー（例: openai、anthropic）
エンドポイント（API パス）
モデル（例: gpt-4o）
プロバイダー認証ヘッダー（例: Authorization のベアラートークン）
リクエスト本文全体

つまりキャッシュは、リクエスト全体の 完全一致 に基づきます。本文の違い（メッセージ、ツール、モデルパラメーターを含む）があると、別のキャッシュエントリになります。この動作を上書きするには、カスタムキャッシュキーヘッダーを使います。

リクエスト単位のキャッシュ

ゲートウェイのデフォルトキャッシュ設定は土台になります。一方で、データの鮮度、寿命が異なるコンテンツ、動的またはパーソナライズされたレスポンスなど、より細かい制御が必要なこともあります。

こうした用途向けに、AI Gateway では特定の HTTP ヘッダーで、リクエスト単位にデフォルトのキャッシュ動作を上書きできます。個別の API 呼び出しごとにキャッシュを最適化できます。

リクエスト単位のキャッシュ動作を定義するヘッダーは次のとおりです。

キャッシュをスキップする (cf-aig-skip-cache)

キャッシュをスキップすると、キャッシュ済みのコピーを使わず、元のプロバイダーから直接取得します。

cf-aig-skip-cache ヘッダーで、キャッシュ済みのレスポンスを迂回できます。

たとえば OpenAI へリクエストを送るときは、次のようにヘッダーを付けます。

キャッシュをスキップするリクエストbash

# 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（Time To Live）は、キャッシュ済みリクエストが有効な期間です。期限が切れると、元のソースから再取得します。すでにキャッシュを使うリクエストの保持期間は、cf-aig-cache-ttl で設定します。個別リクエストをキャッシュ対象にするには、cf-aig-cache-key を付けます。TTL の最小は 60 秒、最大は 1 か月です。

たとえば TTL を 1 時間にすると、そのリクエストは 1 時間キャッシュに残ります。その間の同一リクエストは、元の API ではなくキャッシュから返ります。1 時間後にキャッシュは期限切れになり、リクエストは元の API へ行って新しいレスポンスを取得し、そのレスポンスが次の 1 時間分のキャッシュになります。

たとえば OpenAI へリクエストを送るときは、次のようにヘッダーを付けます。

1 時間キャッシュするリクエストbash

# 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 へリクエストを送るときは、次のようにヘッダーを付けます。

カスタムキャッシュキーを使うリクエストbash

# 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"
      }
    ]
  }'