提示缓存深度解析：把输入成本砍掉 60～90%

# 大多数人一开始的写法：每次调用都为整段提示重新付一遍钱。
import anthropic

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

SYSTEM = open("system-prompt.md").read()        # 18,000 个 token 的规则 + 示例

# 一个会话里有 10 个用户问题。每次调用都发送这段 18K token 的系统块。
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 个 token 的提示自动缓存。
# 无需设置任何开关。"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 个 token
        {"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 个 token
         "cache_control": {"type": "ephemeral"}},     # 断点 1
        {"type": "text",
         "text": LARGE_KNOWLEDGE_BASE,                # 约 15,000 个 token，很少改动
         "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 不为零。