用提示缓存降低编程智能体调用开销
文章演示通过 Chat Completions API,为 Bedrock 上的开放权重模型启用隐式和显式提示缓存,复用重复发送的长上下文。另以 OpenCode 编程智能体会话展示应用方式,以降低输入成本和延迟。
AI 深度解读
长文档、工具定义、对话历史,往往会在每次模型请求里重复发送。AWS 这篇文章讨论的是:如何让 Amazon Bedrock 上的开放权重模型复用这些内容已经算好的状态,减少重复处理带来的输入成本和等待时间。
作者用产品客服和 OpenCode 编程会话演示了两种缓存方式。对程序员最有用的结论是:提示词的排列顺序会影响缓存命中,缓存写入也可能收费,是否省钱必须看返回的用量字段。
缓存复用的是相同前缀,提示词顺序就很重要
提示词缓存(prompt caching)保存的是模型处理一段输入后产生的计算状态。后续请求以相同内容开头,就能读取这段状态,只继续处理新增部分。它没有缓存最终答案,同一份手册后面仍然可以接不同问题。
因此,缓存优化首先是组织输入,而不是增加一个开关。
作者建议把系统指令、工具定义、参考文档放在前面,把用户问题、时间戳、请求 ID 放在后面。前面的内容越稳定,后续请求能复用的部分越长。如果在开头插入每次变化的请求 ID,从那里开始的缓存就需要重新建立。
Amazon Bedrock 提供两种模式,具体支持情况由模型和 API 决定。
隐式缓存(implicit caching)自动尝试复用符合条件的前缀,属于尽力命中。多轮对话会反复发送历史内容,上一轮请求自然成为下一轮的可复用前缀。
显式缓存(explicit caching)需要开发者设置断点,标记可复用内容在哪里结束。断点之后的内容每次重新处理。还可以设置多个断点,把公共指令、工具定义、客户专属文档分层缓存,但数量上限要看模型卡。
两者的差别还涉及账单。缓存读取比普通输入便宜,但部分模型的缓存写入比普通输入贵。隐式模式可能把每次都不同的问题也写进去;显式模式可以只缓存共享手册,让问题按普通输入计费。
文章没有指定具体模型,也没有给统一的最小前缀长度、断点数量、TTL 或价格。这些都需要查看所选模型的模型卡。TTL 是缓存的存活时间,每次命中会重新计时;空闲超过 TTL,下一次请求就需要重新写入。
显式缓存必须同时设置模式和断点
作者的客服示例使用虚构净水器 AnyCompany AquaPure 500,把一句系统指令和约 4,000 tokens 的 Markdown 手册作为固定前缀,再连续提出三个不同问题。
手册包含 E07 排水管受阻、AP-F4 后置滤芯每 12 个月更换,以及龙头保修 3 年但不覆盖 3 V 电池等内容。这里验证的是同一份资料能否复用,手册本身还必须超过模型要求的最小前缀长度。
运行环境是 Python 3.12、openai>=3.26.0 和 aws-bedrock-token-generator>=1.1.0。代码使用 OpenAI Python SDK,但 base_url 指向 Amazon Bedrock Runtime 的 /openai/v1,MODEL_ID 可以是模型 ID 或推理配置 ID。provide_token(region=REGION) 将 AWS 凭证转换为最长有效 12 小时的短期 API key。
下面是原文的显式缓存请求。它解决的是「只缓存系统消息中的共享手册,不缓存每次变化的问题」:
from common import MODEL_ID, QUESTIONS, SYSTEM_PROMPT, client, report
for i, question in enumerate(QUESTIONS, start=1):
response = client.chat.completions.create(
model=MODEL_ID,
messages=[
{
"role": "system",
"content": [
{
"type": "text",
"text": SYSTEM_PROMPT,
# 缓存截至此内容部分的全部内容,包括此部分。
"prompt_cache_breakpoint": {"mode": "explicit"},
}
],
},
{"role": "user", "content": question}, # 位于断点之后,不缓存
],
max_tokens=1024,
extra_body={"prompt_cache_options": {"mode": "explicit"}},
)
report(i, response)
要同时看 prompt_cache_breakpoint 和最后的 extra_body。只设置显式模式、不放断点,什么也不会缓存;只放断点、不设置显式模式,则按隐式缓存运行。可选 ttl 参数支持哪些值,仍然取决于模型。
max_tokens=1024 也有原因:如果模型返回推理 tokens,它们同样占用这个额度,短答案也需要预留足够空间。
作者还报告了一个具体实验现象:手册放在 system 消息、问题放在 user 消息时,隐式缓存能够命中;把两者放进同一条 user 消息时,没有得到隐式缓存命中。原文没有提供足够信息解释原因,因此不宜把它扩大成所有模型的通用限制。
OpenCode 能自动命中,但显示为零未必没有写入
编程代理适合隐式缓存,因为一次任务通常会发起多次模型请求。
OpenCode 首次发送系统提示词、工具定义和用户需求;模型要求调用工具后,OpenCode 在本机执行工具,再把调用记录和结果追加到上下文里发送。前半段基本相同,新增内容集中在尾部,正好符合前缀复用的条件。
作者使用 OpenCode 1.18.35,通过自定义 provider 接入同一个 Chat Completions API。安装命令是 npm install --prefix ~/.local/opt/opencode opencode-ai@1.18.35,provider 使用 @ai-sdk/openai-compatible,从 BEDROCK_API_KEY 读取短期密钥。
配置中的 model 和 small_model 都指向已启用的 Bedrock 模型。后者用于生成会话标题,不能只配置主模型。接入后可以用 opencode models bedrock 检查模型是否列出。
他们在一个只有短 Python 文件的小仓库里做了三轮会话:先检查 src/inventory.py 中 Inventory.remove 的问题,再给出修复代码,最后解释 low_stock。后两轮使用 -s <sessionID> 延续会话,前两轮明确要求不修改文件。
这个例子展示了缓存随上下文追加而复用的过程,但图表标为示意图,文章没有提供实际节省金额或响应时间数据。
验证时可以通过 opencode export <sessionID> 查看请求用量,其中 cache.read 对应 Bedrock 的 cached_tokens,input 是其余输入。OpenCode 1.18.35 的 cache.write 为 0,不能证明没有发生缓存写入。 这个版本的 OpenAI-compatible provider 没有记录 cache_write_tokens。
直接调用 API 时,原文用下面的代码检查真实返回字段:
def report(call_number, response):
"""打印响应 usage 中的缓存字段。"""
usage = response.usage
read = usage.prompt_tokens_details.cached_tokens or 0
written = usage.prompt_tokens_details.cache_write_tokens or 0
print(
f"Call {call_number}: prompt_tokens={usage.prompt_tokens} cached_tokens={read} "
f"cache_write_tokens={written} uncached={usage.prompt_tokens - read - written}"
)
重点是最后一项:普通输入要从 prompt_tokens 中同时扣除读取和写入量。只看缓存读取比例,会漏掉写入费用。
我的判断
这套方法适合重复上下文较长、请求间隔较短的应用。它保留原来的文档和对话结构,服务端负责管理缓存,对现有 API 调用的改动也比较小。
显式缓存尤其适合「固定资料加独立问题」;隐式缓存更适合不断追加上下文的代理会话。但这仍然是结构上的适配判断,作者没有给两种模式的完整成本对照。
缓存也不能代替上下文治理。它复用计算,却没有替你删除过时历史、筛选无关文档。与检索增强生成相比,缓存适合重复使用相同资料,检索则负责挑出当前问题需要的资料;两者可以配合。与压缩对话历史相比,缓存保留原始上下文,压缩则会改变输入内容,也可能影响已有前缀的复用。
原文的前提还包括模型权限、Region 支持和足够长的前缀。低频使用、资料频繁改动、空闲时间经常超过 TTL,都可能削弱收益。跨 Region 推理在高需求时还可能产生额外缓存写入。
AWS 声明提示词和输出不会分享给模型提供方,也不会用于训练模型。模型许可证和服务条款仍需单独检查,不能从「开放权重」直接推导使用范围。
能拿来做什么
- 给固定文档问答或代码规范助手调整消息顺序,把公共指令和资料放在前面,把当前问题放在后面,并保持固定内容一致。
- 给日常 AI 编程会话检查工具定义和系统提示词是否稳定,再用同一会话连续执行「检查代码、提出修改、追问细节」,观察后续请求的缓存读取量。
- 对固定资料、独立问题的接口试用显式断点,比较普通输入、缓存读取和缓存写入三部分费用;首次冷启动测试可在提示词开头加入一次性的 Run ID,随后保持它不变。
- 在应用监控中记录
CacheReadInputTokenCount和CacheWriteInputTokenCount,结合实际流量间隔与模型价格判断收益,并在短期密钥到期后重新生成凭证。