プロンプトキャッシュとコスト最適化

上級

多くのリクエストが大きく変化しない塊——長いシステムプロンプト、大きなドキュメント、ツールカタログ——を共有しているなら、プロンプトキャッシュによって、毎回読み直す代わりに処理済みのプレフィックスを API が再利用できます。これによりキャッシュ部分のコストとレイテンシの両方が削減されます。

What you'll learn

メンタルモデル：安定したプレフィックスの後にキャッシュのブレークポイントを置き、呼び出し間で再利用する
Python と TypeScript で cache_control を使ってブレークポイントを印付ける方法
成否を分ける唯一の不変条件——プレフィックスはバイト単位で一致していなければならない
usage フィールドを読み、実際にキャッシュヒットが起きているか確認する方法
キャッシュが最も効く場所と、バッチ処理および適切なモデル選択との組み合わせ方

仕組み（メンタルモデル）

安定したプレフィックスの後にキャッシュのブレークポイントを印付けます。最初の呼び出しでそれが処理されキャッシュされます。まったく同じプレフィックスを共有する以降の呼び出しはキャッシュにヒットし、その分の支払いがずっと少なくなります。

キャッシュの用語

Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。

1 / 4

ブレークポイントを印付ける（コピペ可）

最後の安定したブロックに cache_control を追加します——ここでは大きなシステムプロンプト。ユーザーのターンはその後に来て自由に変化します。印付けたブロックまで（それを含む）がキャッシュされます。

Guided walkthrough1 of 4

大きく変化しない塊——長いシステムプロンプト、大きなドキュメント、または多くのリクエストで再利用されるツールカタログ——を見つけます。

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_PROMPT,  # long, unchanging — the cached prefix
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Summarize the key points."}],  # varies per call
)

print(message.usage.cache_read_input_tokens)  # > 0 means you got a hit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: LARGE_STABLE_PROMPT, // long, unchanging — the cached prefix
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points." }], // varies per call
});

console.log(message.usage.cache_read_input_tokens); // > 0 means you got a hit

最初の呼び出しは、キャッシュを満たすための小さな書き込みプレミアムを払います。同じプレフィックスを持つ以降のすべての呼び出しは、入力料金のわずかな割合でそれを読み戻します。プレフィックスは対象になるのに十分な長さ——数千トークン、モデル依存——でなければなりません。そうでないと静かにキャッシュされません。

成否を分ける不変条件

:::warning キャッシュはプレフィックス完全一致キャッシュヒットには、キャッシュされたプレフィックスがバイト単位で一致している必要があります。最もよくあるバグ：プロンプト上部付近のサイレント無効化要因——タイムスタンプ、変化するユーザー名、並び替えたツール一覧——がプレフィックスを変え、ヒット率を静かにゼロへ落とします。 :::

**安定したものはすべて先に、可変のものはすべて後に置き、**プレフィックスを本当に一定に保ちましょう。

実際に効いているか確認する

思い込まず、レスポンスの usage から読み戻しましょう：

cache_creation_input_tokens — この呼び出しでキャッシュに書き込まれたトークン（最初のリクエスト）。
cache_read_input_tokens — キャッシュから提供されたトークン（節約分）。
input_tokens — キャッシュされなかった残り。全額で課金される。

プレフィックスを共有しているはずの繰り返しリクエストで cache_read_input_tokens がゼロのままなら、サイレント無効化要因が働いています——2つの呼び出し間でレンダリングされたプロンプトのバイトを diff して見つけましょう。

最も効く場所

ユーザー間で再利用される長いシステムプロンプト。
同じソーステキストが繰り返し問い合わせられる RAG / ドキュメント Q&A。
固定のツールカタログと指示を多くのターンにわたって持つエージェント。

オフラインワークロードではバッチ処理と、最大の合計節約には適切なモデル選択（モデルの選び方）とキャッシュを組み合わせましょう——コスト & レイテンシを参照。

理解度チェック

0/3

キャッシュヒットはキャッシュされたプレフィックスに何を要求しますか？
トークンがキャッシュから提供された（節約分）ことを示す usage フィールドはどれですか？
可変な呼び出しごとのコンテンツは、キャッシュのブレークポイントに対してどこに置くべきですか？

Key takeaways

安定したプレフィックスの後にキャッシュのブレークポイントを印付ける。最初の呼び出しが書き込み、以降の呼び出しが安く読み戻す。
キャッシュヒットにはバイト単位で一致したプレフィックスが必要——安定したコンテンツを先に、可変コンテンツを後に保つ。
プロンプト上部付近のサイレント無効化要因（タイムスタンプ、名前、並び替えたツール）はヒット率を静かにゼロへ落とす。
usage で確認：cache_read_input_tokens > 0 ならヒット；繰り返しリクエストでゼロなら無効化要因が働いている。
キャッシュは再利用されるシステムプロンプト、RAG、エージェントで最も効く；バッチ処理と適切なモデル選択と組み合わせる。

仕組み（メンタルモデル）​

ブレークポイントを印付ける（コピペ可）​

成否を分ける不変条件​

実際に効いているか確認する​

最も効く場所​