Amazon Bedrockのオープンウェイトモデルで実現するプロンプトキャッシュ:暗黙・明示制御と実装パターン
オープンウェイトモデル向けキャッシュの仕組みと選択基準
Amazon Bedrockのオープンウェイトモデルで、プロンプトキャッシュの明示モードが利用可能になった。プロンプトキャッシュは、以前のリクエストと一致するプロンプトの先頭部分(prefix)の計算済み状態を再利用する仕組みだ。同じ長いコンテキストを繰り返し送るアプリケーションでは、キャッシュ済み部分を再処理せずに済むため、入力コストと応答遅延の削減につながる。キャッシュ管理はBedrockが担い、キャッシュ読み取りは標準入力より低い料金で課金される。一方、モデルによってはキャッシュ書き込みが標準入力より高くなる場合があるため、再利用頻度を考慮した設計が重要になる。
キャッシュ方式は、モデルとAPIが対応する範囲で、暗黙キャッシュ、明示キャッシュ、または両方を利用できる。
| 観点 | 暗黙キャッシュ | 明示キャッシュ |
|---|---|---|
| 設定 | なし。Bedrockが適格なprefixをベストエフォートで選択 | prompt_cache_optionsで明示モードを指定し、prompt_cache_breakpointを配置 |
| キャッシュ範囲 | 自動選択された適格prefix | 各breakpointまでの内容 |
| 向く用途 | 会話やエージェントのように、安定したprefixから始まるリクエスト | 共通prefixの後に質問が変わる構成や、層ごとに範囲を制御したい構成 |
暗黙モードでは、会話の各リクエストがそれまでの文脈を再送する場合、直前のリクエストが次のリクエストのprefixとなる。静的なシステム指示、ツール定義、参照文書を先に置き、変化する質問や追加情報を後ろに置くと、共通部分を再利用しやすい。prefixの早い位置が変わると、その位置以降のキャッシュを再構築することになる。また、毎回異なる質問までキャッシュ対象に含まれることがあり、後続リクエストで再利用されない内容にも書き込みが発生し得る。
明示モードでは、キャッシュする範囲の末尾にbreakpointを置く。複数のbreakpointを使えば、変化する頻度が異なるコンテキストを層として分けられる。たとえば共通指示・ツール定義と、顧客ごとの文書を別々にキャッシュし、最後のbreakpoint以降に置いた質問は毎回処理する構成が可能だ。書き込みコストが高いモデルでは、再利用されない質問をキャッシュ対象から除くことで、不要な高単価書き込みを避けられる。
breakpoint前の最低トークン数、モデルごとの最大breakpoint数、キャッシュのTTLはモデル依存である。TTLはキャッシュヒットごとにリセットされる。利用可能なキャッシュ方式、リージョン、制限、TTL値はモデルカードで確認する必要がある。
Chat Completions APIで使用量を検証する
記事の実装例は、OpenAI Python SDKからBedrockのChat Completions API互換エンドポイントを呼び出し、架空の浄水器の取扱説明書を参照するサポートアシスタントを構成する。システムメッセージに指示と約4,000トークンのMarkdownマニュアルを入れ、ユーザーメッセージには毎回異なる質問を置く。必要な環境はPython 3.12、openai 3.26.0以降、aws-bedrock-token-generator 1.1.0以降で、実行には対象モデルを呼び出すIAM権限も必要となる。
認証にはprovide_token()を使い、AWS認証情報から最大12時間有効の短期Bedrock APIキーを生成する。長期キーを作成・保管せずに、次のようなBedrock RuntimeのエンドポイントをOpenAI SDKから利用できる。
client = OpenAI(
api_key=provide_token(region=REGION),
base_url=f"https://bedrock-runtime.{REGION}.amazonaws.com/openai/v1",
)
暗黙キャッシュでは、システムメッセージに固定の指示とマニュアル、ユーザーメッセージに質問を置くだけでよい。初回はプロンプトを書き込み、後続呼び出しではシステムメッセージをキャッシュから読み取る。暗黙モードがprefixを新しい質問まで延長する場合、後続リクエストでも少量の書き込みが生じる。キャッシュがTTL内に残っている状態でサンプルを再実行すると、すべての呼び出しが読み取りとなり、書き込みが発生しないパターンも示されている。
明示キャッシュでは、リクエストにextra_body={"prompt_cache_options": {"mode": "explicit"}}を渡し、キャッシュしたいテキスト部分にprompt_cache_breakpointを指定する。両方の設定が必要で、明示モードだけではキャッシュされず、breakpointだけでは暗黙キャッシュとして扱われる。breakpoint後の質問はキャッシュされず、標準入力レートで処理される。
効果の確認にはレスポンスのusage.prompt_tokens_detailsを使う。例では、cached_tokensがキャッシュ読み取り、cache_write_tokensが書き込み量を示す。入力全体から読み取り・書き込み分を差し引けば、未キャッシュ入力の量も確認できる。明示モードの例では、初回だけprefixを書き込み、後続呼び出しはprefix全体を読み取り、書き込みなしで異なる質問を処理する。暗黙モードと明示モードの差は、単なるヒット有無ではなく、どの可変部分まで書き込み対象にするかに現れる。
エージェントへの適用と運用上の注意
OpenCodeのようなコーディングエージェントは、システムプロンプト、ツール定義、会話履歴を各ステップで再送するため、暗黙キャッシュと親和性が高い。記事の例では、エージェントが最初のリクエストを送り、Bedrockがその内容をキャッシュする。モデルのツール呼び出しをローカルで実行した後、ツール結果を含む次のリクエストを送ると、Bedrockは前回までの部分を読み取り、新たに追加された末尾を処理する。キャッシュ専用の設定をエージェント側に追加しなくても、この再利用が成立する。
例ではOpenCode 1.18.35をOpenAI互換プロバイダーとして構成し、同じBedrock Chat Completionsエンドポイントを利用する。セッション内の各リクエストの使用量はopencode exportで確認でき、cache.readはBedrockのcached_tokensに対応する。一方、このOpenCodeバージョンはOpenAI互換プロバイダーのcache_write_tokensを記録しないため、cache.writeは常に0となる。書き込み量を検証する場合は、Bedrockのレスポンス使用量やランタイムメトリクスも併せて確認する必要がある。
プロンプト構成では、システム指示、ツール定義、参照文書などの静的情報を先に置き、タイムスタンプやリクエストIDなどの変動値を後ろに置く。prefixはモデルカードに記載された最低トークン数を満たす必要があり、短すぎる場合はキャッシュ対象にならない。運用ではレスポンスの読み書きフィールドに加え、CacheReadInputTokenCountとCacheWriteInputTokenCountをワークロード単位で追跡し、キャッシュ読み取り量と書き込み量の双方を評価する。
TTLより長いアイドル時間があると、次のリクエストでprefixが再度書き込まれる。継続的なトラフィックはTTLをヒットごとに更新してキャッシュを維持するが、常に維持できるとは限らない。また、クロスリージョン推論では需要が高い時間帯に追加のキャッシュ書き込みが発生する場合がある。キャッシュの節約効果は再利用によって得られるため、単純な書き込み量ではなく、読み取りの反復回数とモデル固有の料金を合わせて判断することが重要だ。
記事では、プロンプトと出力はモデルプロバイダーと共有されず、モデルの学習にも使用されないとしている。利用前にはモデルカードにリンクされたライセンスとサービス条件、およびAWS Responsible AI Policyを確認する。サンプルは推論呼び出しのみでAWSリソースを作成せず、キャッシュエントリはTTLの間読み取られなければ期限切れとなる。短期APIキーも自動で期限切れになる。
開発者・エンジニア視点での考察
-
キャッシュ境界をプロンプトの構造設計として扱う。 静的情報を前方に集約し、変更頻度の異なる情報を分けることで、暗黙モードのprefix変化を抑えられる。質問が毎回変わる構成では、明示breakpointを共通文書の直後に置き、再利用されない末尾をキャッシュ書き込みから外す設計を比較したい。
-
キャッシュヒット率だけでなく、書き込みと読み取りの経済性を測る。 読み取りは標準入力より低料金だが、モデルによって書き込みは高料金になり得る。
cached_tokensとcache_write_tokensをリクエスト単位で確認し、ランタイムメトリクスも使って、prefix長・再利用回数・アイドル時間を含む実トラフィックで評価するべきだ。 -
エージェントでは「リクエスト全体の再送」を再利用機会として捉える。 ツール定義と会話履歴を繰り返し送るループは、キャッシュが効く一方、変化する履歴末尾が増える。ツールの追加や指示の変更がprefixの早期に入ると再利用範囲が崩れ得るため、設定・ツール定義の安定性を保ち、利用量フィールドでキャッシュ境界の実際の挙動を検証することが有効だ。
Source / 元記事
この記事について
この記事は、公開されているニュース、論文、公式発表、RSSフィードなどをもとに、AIが要約・補足調査・考察を行って作成しています。
元記事の完全な翻訳・逐語的な要約ではなく、AIによる背景説明や開発者向けの考察を含みます。
重要な技術仕様・価格・提供状況などは、必ず元記事または公式情報をご確認ください。


