プロンプトキャッシュ徹底解説：入力コストを最大90%削る方法

# 多くの人が最初に書く形：呼び出しごとにプロンプト全体を再課金している。
import anthropic

client = anthropic.Anthropic(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com",
)

SYSTEM = open("system-prompt.md").read()        # 18,000 トークンのルール + 例

# 1 セッションでユーザーから 10 個の質問。毎回 18K トークンのシステムブロックを送る。
for question in questions:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=600,
        system=SYSTEM,
        messages=[{"role": "user", "content": question}],
    )

# 1 回あたりのコスト（入力のみ）: 18,000 × $3 / 1M = $0.054
# 10 回: 入力だけで $0.54。

# 修正方法：静的なプレフィックスをキャッシュ可能と印付けする。最初の呼び出しの後、
# 約 5 分以内の後続呼び出しは、キャッシュされた部分について入力レートの 10% を払う。
# 同じ答え、89% 安い。
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {
            "type": "text",
            "text": SYSTEM,
            "cache_control": {"type": "ephemeral"},  # キャッシュ可能と印付け
        }
    ],
    messages=[{"role": "user", "content": question}],
)

# 1 回目（キャッシュ書き込み）:  18,000 × $3   / 1M = $0.054
# 2〜10 回目（キャッシュヒット）: 18,000 × $0.30 / 1M = 各 $0.0054
# 合計: $0.054 + 9 × $0.0054 = $0.103 （以前は $0.54 — 81% 節約）

# OpenAI Chat Completions スタイル — 1024 トークン以上のプロンプトはキャッシュが自動。
# 設定するフラグはない。"usage" オブジェクトが何がキャッシュされたかを教えてくれる。
from openai import OpenAI

client = OpenAI(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},  # >1024 トークン
        {"role": "user", "content": "Latest question…"},
    ],
)

# レスポンスの中で:
#   resp.usage.prompt_tokens_details.cached_tokens  →  17,800
#   resp.usage.prompt_tokens                        →  18,200
# 17.8K/18.2K = 入力の 98% がキャッシュ由来。請求はそれを自動で反映する。

# Anthropic はリクエストごとに最大 4 つのキャッシュブレークポイントをサポートする —
# 後半のレイヤーが変わってもキャッシュを温かいまま保つために使おう。
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {"type": "text",
         "text": ROLE_AND_RULES,                      # 約 3,000 トークン
         "cache_control": {"type": "ephemeral"}},     # ブレークポイント 1
        {"type": "text",
         "text": LARGE_KNOWLEDGE_BASE,                # 約 15,000 トークン、めったに変わらない
         "cache_control": {"type": "ephemeral"}},     # ブレークポイント 2
    ],
    messages=[
        {"role": "user",
         "content": [
             {"type": "text",
              "text": CONVERSATION_HISTORY,           # ターンごとに増えていく
              "cache_control": {"type": "ephemeral"}}, # ブレークポイント 3
             {"type": "text", "text": new_question},
         ]},
    ],
)

# CONVERSATION_HISTORY が変わっても、ブレークポイント 1+2 はキャッシュにヒットする。
# 全額の入力レートを払うのはブレークポイント 3 + 新しい質問だけ。

# 必ず usage を読む。ヒットを期待したのに cached_tokens が 0 なら、
# どこかがおかしい — たいていは非決定的なプレフィックスが原因。
resp = client.messages.create(...)
u = resp.usage
print({
    "input_uncached":  u.input_tokens,
    "input_cache_read": u.cache_read_input_tokens,
    "input_cache_write": u.cache_creation_input_tokens,
    "output": u.output_tokens,
})

# よくある落とし穴：システムプロンプトに今日の日付や request_id を入れると、
# 静かにキャッシュが無効化される。入力をハッシュ化し、2 回目の同一呼び出しで
# cache_read_input_tokens が 0 でないことを検証しよう。