提示快取深入解析：把輸入成本砍掉 90%

# 多數人一開始的寫法：每一次呼叫都得重新為整段提示付費。
import anthropic

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

SYSTEM = open("system-prompt.md").read()        # 18,000 個權杖的規則 + 範例

# 一次工作階段裡有 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}],
    )

# 每次呼叫的成本（僅輸入）：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}],
)

# 第一次呼叫（寫入快取）：  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 放進系統提示，
# 會悄悄讓快取失效。請對你的輸入做雜湊；並驗證第二次發送相同呼叫時，
# cache_read_input_tokens 不為零。