Claude API缓存为什么没命中？固定前缀、cache_control与usage核对

多次向Claude API发送同一份背景资料，每次只换最后的问题，可以缓存稳定前缀。但缓存并不是把第一次答案直接拿来重复输出，标了cache_control也不保证命中。本文用本地背景文件组织显式断点，以usage确认真实读取情况，不承诺固定节省比例。

第一步：识别稳定资料与变化问题

把不变的说明、示例或知识资料放在前面，把每次变化的问题放到后面。缓存前缀按tools、system、messages顺序累计，任何断点之前的内容变化都可能改变匹配。不要把当前时间、随机编号或本次用户问题混入稳定资料块。

官方同时支持顶层自动缓存和块级显式断点；本例选择显式方式，让变化问题不会成为断点。需要可用Anthropic API账号和兼容SDK。Managed Agents等产品的缓存行为不同，不能直接照搬Messages API参数，也不能把消费端订阅当成API凭据。

第二步：确认门槛并准备真实背景文件

最小缓存长度随模型变化。当前官方表中claude-opus-5-5门槛为512 token，部分旧型号更高；低于门槛可能正常返回却没有缓存，不一定报错。中文字符数不能直接当作token数，先按模型的计数方式核对。不要无意义重复文字来制造缓存测试。

from pathlib import Path
import anthropic

client = anthropic.Anthropic()
context = Path("background.txt").read_text(encoding="utf-8")
if not context.strip():
    raise ValueError("请提供有权使用的真实背景资料")
system = [{
    "type": "text",
    "text": "仅按以下背景回答，缺失信息明确说明。\n" + context,
    "cache_control": {"type": "ephemeral"}
}]

background.txt是自己准备且有权使用的稳定资料，不是教程附带的现成文件。先做脱敏和长度检查，再调用API；代码没有运行真实付费请求。保持同一份资料的换行和顺序，不在每轮重新生成一个看似相同的摘要。

第三步：连续请求并读取三类usage

questions = ["概括资料中的执行步骤。", "列出资料里明确的例外条件。"]
for question in questions:
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024,
        system=system,
        messages=[{"role": "user", "content": question}],
    )
    u = response.usage
    print({
        "cache_write": u.cache_creation_input_tokens,
        "cache_read": u.cache_read_input_tokens,
        "ordinary_input": u.input_tokens,
    })

第一次可能写入缓存，第二次在有效期内且前缀相同时才可能读取。以实际字段为准，不把示例预期数字硬编码进验收。默认TTL为5分钟，命中会刷新；官方说明计时从请求开始计算，长响应消耗的时间也算在内，不是从生成结束才开始计时。

第四步：按顺序排查零命中

先看写入和读取是否都为零，再查长度门槛、模型与平台支持、断点位置和TTL。若每次只有写入而没有读取，重点比较tools、system和断点前消息是否变化。不要只比较最后一个资料块，前缀中更早的工具定义改变同样会影响缓存。

缓存查找有有限回看窗口，长会话新增很多内容后可能找不到较早写入点。固定资料加变化后缀的场景先把显式断点放对位置，别一遇到问题就堆多个断点。若改用顶层自动缓存，还需核对平台限制，例如Bedrock运行时不支持这个顶层字段。

第五步：核对成本口径与答案质量

input_tokens只表示未读缓存或写缓存的普通输入部分，不是全部输入；应结合cache_read_input_tokens与cache_creation_input_tokens理解总量。缓存写入本身有成本，短期少次请求未必更省，不能因为普通input_tokens变小就断言账单下降相同比例。

验收记录：模型与平台；资料版本；缓存断点；第一次写入与读取；第二次写入与读取；两次普通输入；间隔；关键答案是否符合原资料。失败与未缓存分别记录，不修改响应字段制造命中。

缓存命中也不代替答案核对。改变背景资料时允许形成新缓存，并通过资料版本追踪原因；不应为了命中旧前缀继续使用已经过期的规则。

官方资料

资料核对日期：2026年11月12日。

• Anthropic：Prompt caching