Claudeプロンプトキャッシュ

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "あなたは文学作品を分析するAIアシスタントです。あなたの目標は、テーマ、登場人物、文体について洞察に満ちたコメントを提供することです。"
      },
      {
        "type": "text",
        "text": "ジェーン・オースティンの高慢と偏見... [ここに完全なテキストコンテンツを配置]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "高慢と偏見の主要なテーマを分析してください。"
      }
    ]
  }'

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

プロンプトキャッシュの仕組み

1. システムは、最近のクエリで指定されたキャッシュブレークポイントより前のプロンプトプレフィックスがすでにキャッシュされているかどうかを確認します。
2. 見つかった場合、キャッシュされたバージョンが使用され、処理時間とコストが削減されます。
3. そうでない場合、システムは完全なプロンプトを処理し、応答の開始時にプレフィックス部分をキャッシュします。

• 大量の例を含むプロンプト
• 大量のコンテキストまたは背景情報
• 一貫した指示を持つ繰り返しのタスク
• 長時間の複数ターン会話

​

キャッシュの料金

• 5分キャッシュ書き込みトークン価格は基本入力トークン価格の1.25倍です。
• 1時間キャッシュ書き込みトークン価格は基本入力トークン価格の2倍です。
• キャッシュ読み取りトークン価格は基本入力トークン価格の0.1倍です。
• 通常の入力および出力トークンはプラットフォームの標準料金で課金されます。

​

プロンプトキャッシュの実装方法

​

サポートされているモデル

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

プロンプト構造の構築

​

キャッシュの制限

• Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5、Claude Opus 3は1024トークン
• Claude Haiku 3.5とClaude Haiku 3は2048トークン

• “ephemeral”：デフォルトの5分間の有効期間
• 1時間キャッシュ（ベータ版）：より長いキャッシュ期間が必要なシナリオ向け

​

1時間キャッシュ期間（ベータ版）

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "長期的な指示...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

1時間キャッシュを使用するタイミング

• バッチ処理ジョブ：共通のプレフィックスを持つ大量のリクエストを処理する場合
• 長時間のセッション：長い指示やアップロードされたドキュメントを含む、長期間にわたってコンテキストを維持する必要がある会話
• 大規模なドキュメント分析：同じドキュメントに対して複数回異なる種類の分析を行う場合
• コードベースの質問応答：長期間にわたって同じコードベースに対して複数回クエリを実行する場合

​

異なるTTLの組み合わせ

{
  "system": [
    {
      "type": "text", 
      "text": "長期的な指示...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "短期的なコンテキスト...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

キャッシュ可能なコンテンツ

• ツール：tools配列内のツール定義
• システムメッセージ：system配列内のコンテンツブロック
• メッセージ：messages.content配列内のコンテンツブロック。ユーザーとアシスタントの会話ターンを含む
• 画像とドキュメント：ユーザー会話ターン中のmessages.content配列内のコンテンツブロック
• ツール使用とツール結果：ユーザーとアシスタント会話ターン中のmessages.content配列内のコンテンツブロック

​

キャッシュできないコンテンツ

• 思考ブロックはcache_controlを使用して直接キャッシュすることはできません。ただし、思考ブロックが以前のアシスタントのターンに表示された場合、他のコンテンツと一緒にキャッシュできます。この方法でキャッシュされた場合、キャッシュから読み取ると入力トークンとしてカウントされます。
• サブコンテンツブロック（参照など）はそれ自体を直接キャッシュすることはできません。代わりに、トップレベルのブロックをキャッシュします。
• 空のテキストブロックはキャッシュできません。

​

キャッシュパフォーマンスの追跡

• cache_creation_input_tokens: 新しいキャッシュエントリが作成されたときにキャッシュに書き込まれたトークン数
• cache_read_input_tokens: キャッシュから取得されたトークン数
• input_tokens: キャッシュから読み取られなかった、またはキャッシュの作成に使用された入力トークン数

​

効果的なキャッシュのベストプラクティス

• システム指示、背景情報、大規模なコンテキスト、または頻繁に使用されるツール定義など、安定した再利用可能なコンテンツをキャッシュします。
• 最高のパフォーマンスを得るために、キャッシュコンテンツをプロンプトの先頭に配置します。
• 異なるキャッシュ可能なプレフィックス部分を区切るために、キャッシュブレークポイントを戦略的に使用します。
• キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。
• 長期的に使用するコンテンツの場合、より良い費用対効果のために1時間キャッシュの使用を検討します。

​

さまざまなユースケースの最適化

• 会話エージェント：長時間の会話のコストと遅延を削減します。特に、長い指示やアップロードされたドキュメントを含む会話の場合。
• プログラミングアシスタント：プロンプトに関連する部分やコードベースの要約バージョンを保持することで、自動補完とコードベースの質問応答を改善します。
• 大規模ドキュメント処理：応答の遅延を増やすことなく、プロンプトに完全な長文資料（画像を含む）を埋め込みます。
• 詳細な指示セット：Claudeの応答を微調整するために、広範な指示、手順、および例のリストを共有します。開発者は通常、プロンプトに1つまたは2つの例を含めますが、プロンプトキャッシュを使用すると、20以上の高品質な回答の多様な例を含めることで、より良いパフォーマンスを得ることができます。
• エージェントツール使用：複数のツール呼び出しと反復的なコード変更を含むシナリオのパフォーマンスを向上させます。各ステップは通常、新しいAPI呼び出しを必要とします。
• 書籍、論文、ドキュメント、ポッドキャストの記録、その他の長文コンテンツとの会話：プロンプトにドキュメント全体を埋め込むことで、ユーザーが質問できるようにします。

​

よくある問題の解決

• キャッシュ部分が異なる呼び出し間で完全に同じであり、同じ位置にcache_controlがマークされていることを確認してください。
• 呼び出しがキャッシュの有効期間内（5分または1時間）であることを確認してください。
• tool_choiceと画像の有無が呼び出し間で一貫していることを確認してください。
• キャッシュしたトークン数が最小要件を満たしていることを確認してください。
• システムはキャッシュブレークポイントより前の位置のキャッシュされたコンテンツを使用しようとしますが、追加のcache_controlパラメータを使用して、プロンプトの前の部分のキャッシュを確実に検索できます。これは、非常に長いコンテンツブロックのリストを含むクエリに役立つ場合があります。

​

キャッシュの保存と共有

• 組織の分離： キャッシュは組織間で分離されています。異なる組織は、同じプロンプトを使用してもキャッシュを共有することはありません。
• 正確な一致： キャッシュヒットには、cache_controlでマークされたブロックの前のすべてのテキストと画像、およびそれ自体を含む、100%同じプロンプトセグメントが必要です。キャッシュの読み取りと作成中に、同じブロックをcache_controlでマークする必要があります。
• 出力トークンの生成： プロンプトキャッシュは出力トークンの生成には影響しません。受け取る応答は、プロンプトキャッシュを使用しない場合とまったく同じです。

​

異なるモデルのサポート状況

• プロンプトキャッシュのサポートは、モデル自体に依存します。
• モデル自体がサポートしており、関連するパラメータを明示的に宣言する必要がない場合、OpenAI互換形式での転送はサポートされます。
• OpenAIはデフォルトでプロンプトキャッシュをサポートしており、キャッシュは課金されず、キャッシュされたトークンの読み取り費用は半額になります。5〜10分間再利用されない状態が続くと自動的にクリアされます。ドキュメント
• Claudeはネイティブのcache_control: { type: "ephemeral" }宣言が必要です。キャッシュ料金は通常の入力の1.25倍（5分）または2倍（1時間）で、キャッシュされたトークンの読み取り費用は0.1倍です。有効期間は5分または1時間です。ドキュメント
• Deepseek V3とR1はネイティブでサポートされており、キャッシュ料金は通常の入力の1倍で、キャッシュされたトークンの読み取り費用は0.1倍です。ドキュメント
• Geminiモデルは暗黙的なキャッシュをサポートしています。
  • 暗黙的なキャッシュ：すべてのGemini 2.5モデルでデフォルトで有効になっています。リクエストがキャッシュにヒットした場合、コスト削減が自動的に適用されます。この機能は2025年5月8日から有効です。コンテキストキャッシュの最小入力トークン数：Gemini 2.5 Flashは1,024、Gemini 2.5 Proは2,048。
    • 暗黙的なキャッシュヒット率を高めるヒント：
      • 共通の大きなコンテンツブロックをプロンプトの先頭に配置します。
      • 短期間にプレフィックスが類似するリクエストを送信してみてください。
    • 応答オブジェクトのusage_metadataフィールドで、キャッシュヒットしたトークン数を確認できます。
    • コスト削減は、プリフィルキャッシュヒット数に基づいて測定されます。プリフィルキャッシュとYouTubeビデオのプリプロセスキャッシュのみが暗黙的なキャッシュをサポートしています。