Claude Code 深度学习手册

主题

提示词缓存（Prompt Caching） ​

把请求开头逐 token 相同的『前缀』缓存起来，命中只花 0.1× 输入价；本站附带一个可交互的深度图解页。

你的真实缓存数据 ​

从你本机实测（~/.claude/projects/ 的 usage 字段 + ~/.claude/stats-cache.json）：

范围数据来源请求/会话缓存命中率输入侧 token
本项目（kejizhuantifuwu）jsonl 实算（2026-05-30）4,518 次助手请求86.8%cache_read 16.1 亿 / 写入 2.43 亿 / 全价 187 万
全部 13 个项目（全局）stats-cache 快照（截至 2026-05-26）70 个会话 · 19,286 条消息≈ 97%cache_read 26.9 亿 / 写入 0.75 亿 / 全价 495 万（合计 ≈ 27.7 亿）

命中率 = cache_read ÷ 输入侧总 token。本项目偏低（86.8%）是因为这几天在本会话里大量重建文档、频繁刷新大段上下文（写入多）；全局长期稳定在 ~97%。主用模型 Opus 4.7（另有少量 Haiku 4.5 / Sonnet 4.6）。

省钱（粗估，仅示意）：命中读按约 0.1× 输入价计费。全局 26.9 亿命中 token，若全部全价、按 Opus 输入 $5/MTok 估算约 $13.5k，实际命中只花约 1 成（≈ $1.3k），即缓存粗估替你省下约九成输入成本。这个美元数是按单一单价的粗算示意，不是账单实数——准确账单见 platform.claude.com/usage。关键事实是：你几乎什么都没配，就已经吃到 Claude Code 自动打缓存断点的红利。

去真实体验 ​

想验证什么这样做
可交互深度图解（token 切分、TTL 倒计时、缓存层级演示）打开本站 缓存交互图解
看本次会话 token / 花费（含缓存读写）在 Claude Code 里输入 /cost
自己复算某项目命中率`jq -s '[.[]
看全局累计统计cat ~/.claude/stats-cache.json（modelUsage 里有 cacheRead/cacheCreation/input 分模型汇总）

对你的实际意义 ​

  • 你 CLAUDE.md/AGENTS.md 这类稳定内容靠前——天然命中，别频繁改（改一个字，它及之后全部重算，这也是本项目这几天写入偏多、命中率被拉低的原因）。
  • 你装了 5 个 MCP（serena/context7/playwright/figma/chrome-devtools）+ 一堆插件，工具默认 deferred 不占上下文，也都在缓存前缀里复用。
  • 你装了 ralph-loop：跑 /loop 这类定时/轮询时别卡在 5 分钟 TTL 边缘——要么间隔 <270s 保住缓存，要么 1200s+ 接受一次重算换更长间隔。
  • 你是 Claude 订阅用户（stats 里 costUSD=0、走订阅额度），订阅下 Claude Code 默认请求 1 小时 TTL（计划内不额外计费），比 API key 默认的 5 分钟更耐放。

完整原理（前缀逐 token 匹配、tools→system→messages 层级、TTL、价格倍率）见下方官方要点，或那个交互页。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Prompt Caching（提示词缓存）让你复用请求里从开头开始、逐 token 完全相同的那一段『前缀』。命中时只按 0.1× 基准输入价计费，写入按 1.25×（5 分钟）或 2×（1 小时）。Claude Code 自动在 tools / system / 上下文等稳定边界打缓存断点，所以连续对话里几万 token 的前缀几乎免费复用。本模块以 Claude Code 的自动缓存行为为主（出处 code.claude.com/prompt-caching），底层 API 机制（cache_control 断点、最小长度、回看窗口）见 platform.claude.com/docs/en/docs/build-with-claude/prompt-caching。本站另附可交互深度图解（含真实使用数据、TTL 倒计时、token 切分演示）。

怎么工作 ​

  • 缓存按线性 token 序列做前缀匹配：从第 0 个 token 起逐个比对，遇到第一个不同的 token，从那里到结尾全部失效、重算。
  • 缓存层级 tools → system → messages：上层变了下层全废（改工具定义最贵，改最后一条消息几乎无损）。
  • 命中 0.1×、5 分钟写 1.25×、1 小时写 2×（相对基准输入价，对所有模型固定）。
  • TTL 由认证方式自动选：Claude 订阅自动用 1 小时（计划内不额外计费，超额走 usage credits 时降回 5 分钟）；API key/Bedrock/Vertex/Foundry 默认 5 分钟。每命中一次免费刷新计时——过期看的是『两次请求的间隔』，与任务总时长无关。
  • 前缀必须 100% 逐 token 相同。Claude Code 层缓存按『机器 + 目录』隔离（不同目录/worktree 互不命中，同目录并行会话可互相命中）；底层 API 缓存按组织隔离，自 2026-02-05 起 Claude API / Claude Platform on AWS / Foundry(beta) 改为按 workspace 隔离，Bedrock / Vertex 仍按组织。

怎么配置 / 用法 ​

调 API 时在内容块上打断点：

json
{
  "system": [{ "type": "text", "text": "<大段稳定内容>", "cache_control": { "type": "ephemeral" } }],
  "messages": [{ "role": "user", "content": "易变的本轮输入，放最后、不打标" }]
}

要点：稳定大块放前面并打断点；易变内容放最后不打标；最多 4 个断点；低于最小可缓存长度即使打标也不缓存（官方表：Opus 4.7/4.6/4.5 与 Haiku 4.5 = 4096，Sonnet 4.6 = 1024；Opus 4.8 官方表未单列，最新 Opus 占位项归 1024 组）。

看命中情况：响应 usage 的 cache_read_input_tokens（命中）/ cache_creation_input_tokens（写入）/ input_tokens（全价）。

在 Claude Code 里：缓存全自动，无需手动打断点。会让缓存失效的操作：切模型、切 effort、MCP server 连/断、deny 整个工具（裸 Bash/WebFetch）、/compact、升级 Claude Code。关闭缓存（调试用）：环境变量 DISABLE_PROMPT_CACHING（全部）或 DISABLE_PROMPT_CACHING_HAIKU / _SONNET / _OPUS（按模型）。TTL 覆盖：ENABLE_PROMPT_CACHING_1H=1（开 1 小时）/ FORCE_PROMPT_CACHING_5M=1（强制 5 分钟）。

什么时候用 ​

  • 同一前缀会被反复读（连续对话、长 system/工具/文档）→ 缓存几乎总是划算（写 1.25× + 读 0.1× < 2× 正常价，读一次就回本）。
  • 把稳定内容放前面、易变内容放最后，最大化命中。
  • 睡眠/等待别卡在 300 秒整（TTL 边缘）：要么 <270s 保住缓存，要么 1200s+ 接受一次重算换更长间隔。

限制 / 坑 ​

  • 前缀必须逐 token 完全相同；改靠前的稳定内容（system/CLAUDE.md/工具）会连带作废其后全部。
  • 低于最小可缓存长度即使打标也不缓存。官方表：Opus 4.7/4.6/4.5 与 Haiku 4.5 = 4096，Sonnet 4.6 = 1024；Opus 4.8 官方表未单列（最新 Opus 占位项归 1024 组）。此表仅适用 Claude API / Claude Platform on AWS / Vertex / Foundry(beta)。
  • 每请求最多 4 个缓存断点；不跨模型、不跨 effort 共享（各自独立缓存）。
  • TTL：订阅默认 1 小时、API key/三方默认 5 分钟（详见上方）；过期需从头重建。

硬事实速查（8 条） ​

  • 倍率：命中读 0.1×、5 分钟写 1.25×、1 小时写 2×（相对基准输入价）。
  • Opus 4.8 实价：基准输入 $5/MTok、命中 $0.50、5m 写 $6.25、输出 $25。
  • 最小可缓存（官方表）：Opus 4.7/4.6/4.5 = 4096，Sonnet 4.6 = 1024，Haiku 4.5 = 4096；Opus 4.8 官方表未单列（最新 Opus 占位项归 1024 组）。
  • 最多 4 个缓存断点；回看窗口 20 个块；前缀 100% 逐 token 匹配。
  • TTL 按认证自动选：订阅 1 小时（计划内不额外计费）、API key/三方 5 分钟；ENABLE_PROMPT_CACHING_1H=1 / FORCE_PROMPT_CACHING_5M=1 覆盖。
  • 会让缓存失效的操作：切模型、切 effort、MCP server 连/断、deny 整工具、/compact、升级 Claude Code。
  • 关闭缓存：DISABLE_PROMPT_CACHING（全部）/ _HAIKU / _SONNET / _OPUS（按模型）。
  • usage 三字段：cache_read_input_tokens / cache_creation_input_tokens / input_tokens，三者之和 = 总输入。

官方出处：https://code.claude.com/docs/en/prompt-caching