プロンプトキャッシュ

同じ大きなコンテキストを複数のリクエストで使う場合は、プロンプトキャッシュを使います。安定した指示、ドキュメント、例、ツール出力、ツール定義をキャッシュ可能としてマークすると、対応プロバイダーは後続の呼び出しでそのコンテキストを再利用できます。プロンプトキャッシュはレスポンスキャッシュとは異なります。プロンプトキャッシュでは推論を実行しますが、入力を繰り返し処理するコストとレイテンシを削減できます。レスポンスキャッシュは、同一リクエストに対して以前に生成した回答を返します。

プロンプトキャッシュの対応状況はプロバイダーとモデルによって異なります。未対応のプロバイダーはキャッシュヒントを無視するか、キャッシュ料金を適用せずにルーティングします。キャッシュの読み取りと書き込みの料金はモデルページの料金表で確認してください。

キャッシュする内容

リクエスト間で変わらない内容をキャッシュします。

長いシステム指示
再利用するRAGドキュメント
few-shotの例
ツール定義
次のターンで再利用する大きなツール結果

リクエストごとに変わる内容、短い一度限りのユーザー入力、または選択したプロバイダーへの保存をポリシーで禁止されている機密データはキャッシュしないでください。

キャッシュ制御

PhaseoはChat Completions、Responses、Anthropic Messagesの各リクエストで、トップレベルの互換ヒントcache_controlを受け付けます。

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

短期間共有するコンテキストにはttl: "5m"を使い、プロバイダーとモデルが長期間のプロンプトキャッシュに対応している場合はttl: "1h"を使います。対応プロバイダーでは、トップレベルのキャッシュ制御が自動またはデフォルトのキャッシュポリシーとして扱われます。対応するテキスト、画像、ツール結果、ツール定義の各ブロックにcache_controlを直接指定して、明示的なキャッシュ境界を設けることもできます。

{
  "type": "text",
  "text": "Large stable reference text...",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "1h"
  }
}

プロバイダー固有のエイリアスも引き続き使えます。たとえば、provider_optionsを使ってAnthropicのデフォルトキャッシュポリシーを指定できます。

{
  "provider_options": {
    "anthropic": {
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m",
        "scope": "last_user_message"
      }
    }
  }
}

対応しているscopeの値:

範囲	動作
`all_text`	キャッシュ制御がまだ設定されていないシステムテキストとユーザーのテキスト・画像ブロックに追加します。
`last_user_message`	最新のユーザーメッセージにのみキャッシュ制御を追加します。
`none`	デフォルトのキャッシュポリシーを適用しません。

ブロックごとのcache_controlはデフォルトポリシーより優先されます。

Chat Completions

OpenAI互換のチャットクライアントでは/v1/chat/completionsを使います。

curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "You are a support assistant. Follow the company policy exactly.",
            "cache_control": { "type": "ephemeral", "ttl": "1h" }
          }
        ]
      },
      {
        "role": "user",
        "content": "Summarise the latest ticket."
      }
    ]
  }'

OpenAI経由のリクエストでは、OpenAI互換のトップレベルフィールドでOpenAIのキャッシュ保持オプションを渡します。

{
  "prompt_cache_retention": "24h"
}

プロバイダー固有のエイリアスも指定できます。

{
  "provider_options": {
    "openai": {
      "prompt_cache_retention": "24h"
    }
  }
}

Responses

新しいOpenAI互換のテキスト統合やエージェントフローでは/v1/responsesを使います。

curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Reference document: Refunds are available for 30 days when...",
            "cache_control": { "type": "ephemeral", "ttl": "5m" }
          },
          {
            "type": "input_text",
            "text": "Answer this customer: Can I return an item after 20 days?"
          }
        ]
      }
    ]
  }'

すでにGoogle Geminiのキャッシュ済みコンテンツリソースがある場合は、provider_options.google.cached_contentで渡します。

{
  "provider_options": {
    "google": {
      "cached_content": "cachedContents/abc123"
    }
  }
}

Anthropic Messages

Anthropic互換のクライアントでは/v1/messagesを使います。

curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "system": [
      {
        "type": "text",
        "text": "You are a careful support assistant. Use the policy below.",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Policy: refunds are available for 30 days when...",
            "cache_control": { "type": "ephemeral", "ttl": "5m" }
          },
          {
            "type": "text",
            "text": "Can this customer return an item after 20 days?"
          }
        ]
      }
    ],
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order status.",
        "input_schema": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"]
        },
        "cache_control": { "type": "ephemeral", "ttl": "5m" }
      }
    ]
  }'

Anthropic Messagesでは次の箇所でキャッシュ制御を利用できます。

systemのテキストブロック
メッセージのテキストブロックと画像ブロック
ツール結果ブロック
ツール定義

使用量と料金フィールド

プロバイダーがキャッシュ使用量を返すと、Phaseoは共通の使用量フィールドに正規化します。

項目	意味
`input_tokens_details.cached_tokens`	プロバイダーのプロンプトキャッシュから読み取られたキャッシュ済み入力トークン。
`output_tokens_details.cached_tokens`	プロバイダーのプロンプトキャッシュに書き込まれたキャッシュ済み入力トークン。
`cached_read_text_tokens`	キャッシュ読み取りの料金メーターです。プロバイダーのキャッシュから再利用された入力テキストを表します。
`cached_write_text_tokens`	プロバイダーのキャッシュ書き込み料金が一律の場合に使われる料金メーターです。
`cached_write_text_tokens_5m`	プロバイダーがTTL別の書き込み量を返す場合の、5分TTLキャッシュ書き込みトークン。
`cached_write_text_tokens_1h`	プロバイダーがTTL別の書き込み量を返す場合の、1時間TTLキャッシュ書き込みトークン。

キャッシュへの書き込みは通常の入力トークンより高く、読み取りは通常より安価です。正確な料金はプロバイダー、モデル、TTLによって異なります。

実践的な確認

プロンプトキャッシュを追加した後:

キャッシュを作成またはウォームアップするために、1件リクエストを送ります。
同じキャッシュ対象コンテンツを含む2件目のリクエストを送ります。
レスポンスの使用量とリクエスト詳細を確認し、キャッシュの読み取り・書き込みフィールドを探します。
初回だけでなく、複数回の呼び出し全体でレイテンシとコストを比較します。

プロバイダーとの親和性

デフォルトでPhaseoは、プロバイダーのプロンプトキャッシュ使用量をルーティングシグナルとして利用します。プロバイダーがキャッシュ済み入力トークンを返すと、同じキャッシュキーまたは安定した冒頭のコンテキストを持つリクエストは15分間そのプロバイダーを優先します。これにより、別のプロバイダーに同じプロンプトキャッシュを再構築させる費用を避けられます。 session_idを含めると、キャッシュ読み取りが確認された時点でセッション親和性も作成されます。 Phaseoはアクティブなセッション期間中その親和性を保持しながら、プロバイダーが不健全になった場合やポリシー対象外になった場合はフェイルオーバーします。 1つのリクエストで無効にするにはprovider.cache_aware_routingをfalseに設定します。続けて、リクエストにsession_idが含まれていても、通常のコンテキストベースのルーティングだけを使う場合は、 routing.session_affinityをfalseに設定します。

概要

モデルとルーティング

機能

連携

ワークスペースとアクセス

信頼性と運用

プラットフォームと研究

移行ガイド

コミュニティ

プロンプトキャッシュ

キャッシュする内容

キャッシュ制御

Chat Completions

Responses

Anthropic Messages

使用量と料金フィールド

実践的な確認

プロバイダーとの親和性

関連ページ

​キャッシュする内容

​キャッシュ制御

​Chat Completions

​Responses

​Anthropic Messages

​使用量と料金フィールド

​実践的な確認

​プロバイダーとの親和性

​関連ページ

キャッシュする内容

キャッシュ制御

Chat Completions

Responses

Anthropic Messages

使用量と料金フィールド

実践的な確認

プロバイダーとの親和性

関連ページ