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": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

{"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. そうでない場合、システムは完全なプロンプトを処理し、応答の開始時にプレフィックス部分をキャッシュします。

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

​

よくある間違い：キャッシュを「書き込むだけで読み取れない」

​

❌ 誤った書き方：毎回変化する質問をブレークポイントの前に置く

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ 正しい書き方：大きなドキュメントを最前に + ブレークポイント + 質問を最後に

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

実測比較（claude-opus-4-6、同一チャネル固定、2回の呼び出しは数秒間隔）

1. 固定不変の大きなブロック（参考ドキュメント、長いコンテキスト）をmessagesのユーザーメッセージの最前に置き、cache_controlをその末尾に付けます。このコンテンツは一文字も変更してはいけません。
2. 毎回変化する質問/指示はブレークポイントより後（同じuserメッセージ内の大きなドキュメントの後、または後続のメッセージ）に置きます。複数ターンの会話では後ろに追記するだけにし、過去のメッセージを戻って修正しないでください。
3. thinkingを有効にする場合、過去のアシスタントのターンの思考ブロックはそのまま返送する必要があります。さもないとプレフィックスが同様に途切れます（後述の「キャッシュできないコンテンツ」を参照）。
4. ブロックが最小キャッシュしきい値（Opus 4.5/4.6、Haiku 4.5は4096トークン）未満の場合、cache_controlをマークしてもキャッシュに書き込まれません。これは想定どおりの動作です。後述の「キャッシュの制限」を参照してください。

​

キャッシュの料金

• 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": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

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

​

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

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

​

異なるTTLの組み合わせ

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "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でマークする必要があります。
• 出力トークンの生成： プロンプトキャッシュは出力トークンの生成には影響しません。受け取る応答は、プロンプトキャッシュを使用しない場合とまったく同じです。

​

クライアント / プラットフォームでClaudeキャッシュを有効にする

​

Dify（Aihubmixプラグイン経由）

1. キャッシュしたいプロンプト（固定不変のシステムプロンプト / 長いコンテキスト）を<cache>…</cache>で囲むと、プラグインがその箇所を自動的にcache_controlブレークポイントに変換します。
2. モデルパラメータで「大きなメッセージの自動キャッシュしきい値」を正の整数に設定します。コンテンツがそのトークンしきい値に達して初めて実際にキャッシュが書き込まれます（下記「キャッシュの制限」の最小キャッシュ制約を依然として受けます。Opus 4.5/4.6、Haiku 4.5は4096トークン）。0または空欄に設定すると無効になります。

​

Cherry Studio

1. Aihubmixプロバイダー名の右側にある歯車をクリックして「API設定」（API Settings）を開きます。

2. 以下の3項目を設定すると、クライアントがそれに基づいてClaudeに自動的にcache_controlを注入します。

• キャッシュトークンしきい値（Cache Token Threshold）：コンテンツがそのトークン数を超えた場合のみキャッシュブレークポイントを注入します（正の数で有効、0または空欄で無効）。
• システムメッセージをキャッシュ（Cache System Message）：有効にするとsystemメッセージにキャッシュブレークポイントを付けます（固定の長いシステムプロンプトのキャッシュに適しています）。
• 最後のN件のメッセージをキャッシュ（Cache Last N Messages）：直近のN件のメッセージにキャッシュブレークポイントを付けます（複数ターン会話のローリングキャッシュに適しています）。

​

よくある質問（FAQ）

​

キャッシュを書き込んでいる（cache_creation_input_tokensが大きい）のに、なぜずっと読み取れない（cache_read_input_tokensが0）のですか？

​

キャッシュには最低どれくらいのトークンが必要ですか？

​

キャッシュの有効期間はどれくらいですか？1時間に変更できますか？

​

Dify / Cherry Studioではどうやってキャッシュを有効にしますか？

​

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

• プロンプトキャッシュのサポートは、モデル自体に依存します。
• モデル自体がサポートしており、関連するパラメータを明示的に宣言する必要がない場合、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ビデオのプリプロセスキャッシュのみが暗黙的なキャッシュをサポートしています。