05 提示缓存优化策略
05 提示缓存优化策略
学习目标
- 理解 claude-api 技能中对提示缓存的具体指导
- 掌握静默失效审计的诊断方法
- 学习 Anthropic 定义的缓存断点放置策略
- 分析 Opus 4.7 上缓存与 effort/adaptive thinking 的交互
前置知识
本章涉及提示缓存的通用原理，建议先阅读：
下文假设你已理解上述概念，直接聚焦 claude-api 技能的具体实现。
项目实践
claude-api 技能中的缓存指导
claude-api/SKILL.md 中有两段关键的缓存指导：
1. 默认值部分：
For the Claude model version, please use Claude Opus 4.7… Please default to using adaptive thinking (
thinking: {type: "adaptive"}) for anything remotely complicated… And finally, please default to streaming for any request that may involve long input, long output, or highmax_tokens— it prevents hitting request timeouts.
这里将 streaming 作为默认策略，不仅仅是为了避免超时——streaming 也防止缓存命中前的请求超时。
2. 快速参考部分：
Prefix match. Any byte change anywhere in the prefix invalidates everything after it. Render order is
tools→system→messages. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the lastcache_controlbreakpoint.
3. 验证指令：
Verify with
usage.cache_read_input_tokens— if it’s zero across repeated requests, a silent invalidator is at work (datetime.now()in system prompt, unsorted JSON, varying tool set).
静默失效审计检查清单
claude-api 技能明确列出了三个常见的静默失效原因：
| 原因 | 检测方式 | 修复 |
|---|---|---|
datetime.now() 在系统提示中 | 每次请求 token 计数为零 | 将时间戳移到消息部分 |
| 未排序的 JSON | 序列化不一致 | 使用排序后的 key |
| 变化的工具集 | 每次请求工具不同 | 固定工具集或放在最后断点后 |
Opus 4.7 特有的缓存交互
在 Opus 4.7 上，缓存与以下特性有交互：
- Adaptive Thinking：思考块的渲染可能改变前缀。如果 thinking 内容变化，之后的缓存会失效。
- Effort 参数：不同的 effort 值（
low/high/xhigh/max）会改变模型输出长度，但不影响输入缓存。 - Compaction：服务端压缩会在上下文超过阈值时自动总结早期内容。compaction blocks 必须保留——只提取文本字符串会静默丢失压缩状态。
问题与规避
最大 max_tokens 需要 streaming
问题：Opus 4.6/4.7 支持 128K max_tokens，但 SDK 需要 streaming 才能避免 HTTP 超时。
规避策略：对大输出请求使用 .stream() + .get_final_message() / .finalMessage()。
Compaction 状态丢失
问题：追加消息时只提取文本字符串（response.content[0].text），而非完整的 response.content（包含 compaction blocks）。
规避策略：始终追加 response.content（不仅仅是文本）。Compaction blocks 是 API 用来替换压缩历史的标记。
设计取舍
为什么推荐 Opus 4.7 + adaptive thinking 作为默认？
优势：adaptive thinking 让模型自己决定何时思考、思考多少，无需手动调 budget_tokens。
代价：比固定 thinking budget 消耗更多 token（模型可能在简单任务上也思考）。
Anthropic 的立场：这是”non-negotiable”的默认选择——不应为 4.7 代码使用 budget_tokens。
参考来源
- Anthropic Skills 仓库：
skills/claude-api/SKILL.md - Anthropic Skills 缓存文档：
skills/claude-api/shared/prompt-caching.md - Anthropic 官方文档：https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching