GPT プロンプトキャッシュ

​

クイックスタート

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [固定で変化しない長い指示や参考資料をここに配置、≥1024 Token]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # キーは環境変数から読み取る
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [固定で変化しない長い指示や参考資料、≥1024 Token]"

# 同じプレフィックスで 2 回連続リクエストし、2 回目でキャッシュにヒット
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1 回目の呼び出し：ヒットなし
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2 回目の呼び出し：プレフィックスがキャッシュにヒット
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

キャッシュの課金

​

キャッシュが自動的に有効になる仕組み

1. プレフィックスが 1,024 Token に達し、一致するキャッシュ済みプレフィックスが見つかった場合、ヒット部分はキャッシュ読み取り価格で課金され、最初の Token のレイテンシが低減されます。
2. 見つからない場合は通常の入力として処理され、プレフィックスがキャッシュに書き込まれます（GPT-5.6 以降は書き込み費用として 1.25x で課金）。
3. ヒットにはプレフィックスのバイト単位の一致が必要で、プレフィックス内のいかなる変化も、その位置以降のキャッシュをすべて無効にします。

• 固定の長いシステム指示や大量の few-shot 例
• RAG シナリオで繰り返し参照される長い参考資料
• 大量のツール定義（tools）を伴う Agent ワークフロー
• 後ろに追記するだけの長いマルチターン会話

​

GPT-5.6 のキャッシュパラメータ

1. デフォルト（implicit モード）：キャッシュパラメータを一切渡さなくても自動でキャッシュに書き込まれます——システムが最新のメッセージの位置に自動的にブレークポイントを設定します。GPT-5.6 以降では、自動で発生するキャッシュ書き込みも同様に 1.25x で課金されます。
2. implicit モード + 明示的ブレークポイント：自動ブレークポイントに加えて、コンテンツブロックに prompt_cache_breakpoint を設定し、キャッシュ境界を安定したコンテンツの末尾に固定できます。ブレークポイント以降のコンテンツの変化は、ブレークポイント以前のプレフィックスキャッシュを壊しません。
3. explicit モード：prompt_cache_options.mode を "explicit" にすると手動ブレークポイントのみを使用します。ブレークポイントをまったく設定しない場合、そのリクエストはキャッシュを使用せず、キャッシュ書き込み費用も発生しません。公式原文：“If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[再利用しない一回限りの長いコンテンツ]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[固定で変化しない長い指示や参考資料、≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• 各リクエストで作成できる新しいキャッシュ書き込みは最大 4 つ。implicit モードでは自動ブレークポイントがそのうち 1 つを占有します。
• ブレークポイント以前のプレフィックスは 1,024 Token に達しないとキャッシュされません。
• 読み取り時は直近 50 個のブレークポイントの中から最長一致のプレフィックスを使用します。
• 対応していないコンテンツブロックにブレークポイントを設定すると 400 invalid_request_error が返されます。Chat Completions は text / image_url / input_audio / file / refusal ブロックに、Responses API は input_text / input_image / input_file ブロックに対応しています。

​

キャッシュがヒットしない理由

• プレフィックスが 1,024 Token 未満：最小キャッシュ長を下回るリクエストは通常の入力として処理されます。
• プレフィックスに変化するコンテンツが混入：タイムスタンプ、セッション ID、ユーザー変数などは固定コンテンツの後に配置してください。プレフィックス内のいかなる変化も、それ以降のキャッシュを無効にします。
• tools の定義や順序の変化：ツールリストはプレフィックスの計算に含まれ、定義と並び順が完全に一致している必要があります。
• 画像の detail パラメータの不一致：detail は画像の Token 化結果に影響するため、同一に保つ必要があります。
• 構造化出力 schema の変化：response_format の JSON Schema はシステムメッセージのプレフィックスとしてキャッシュに含まれ、schema の変化はプレフィックスの変化になります。
• reasoning_effort の変化：公式ドキュメントでキャッシュヒット率低下の一般的な原因として挙げられています（“Changes to reasoning effort”）。
• キャッシュ保持期間の超過：GPT-5.6 より前は非アクティブ 5〜10 分後に削除、GPT-5.6 以降は最低 30 分間保持されます。
• prompt_cache_key 未設定（GPT-5.6）：未設定でも自動ヒットする場合はありますが、より信頼性の高いマッチング機構は使用されません。

​

ベストプラクティス

• 固定コンテンツ（システム指示、例、参考資料、ツール定義）をリクエストの最前部に、毎ターン変化するコンテンツを最後に配置します。
• 同じプレフィックスを共有するトラフィックには同一の安定した prompt_cache_key を設定し、1 つの key の総トラフィックを約 15 回/分以内に抑えます。超える場合は業務ごとに key を分割します。
• マルチターン会話では後ろへの追記のみを行い、過去のメッセージの変更を避けます。
• 同じプレフィックスのリクエストに継続的なトラフィックを維持し、キャッシュが削除される機会を減らします。
• プレフィックスを再利用しない一回限りの長いリクエストは、explicit モードでキャッシュ書き込み費用を回避します（GPT-5.6 以降）。
• usage.prompt_tokens_details.cached_tokens でヒット状況を継続的に監視します。

​

よくある質問（FAQ）

​

GPT のプロンプトキャッシュは手動で有効にする必要がありますか？

​

GPT-5.6 のキャッシュ書き込み費用はどう計算されますか？不要な書き込み費用を避けるには？

​

キャッシュはどれくらい保持されますか？

​

GPT-5.6 の明示的ブレークポイントと Claude の cache_control の違いは何ですか？

​

キャッシュは出力内容に影響しますか？

​

公式リファレンス

• GPT-5.6 リリース発表：キャッシュ書き込み 1.25x / 読み取り 90% 割引の課金ルール
• プロンプトキャッシュガイド：機構、パラメータ、usage フィールドと制限
• OpenAI Pricing：各モデルの公式価格
• GPT-5.6 モデルドキュメント：コンテキストウィンドウ、長コンテキスト課金のしきい値