在 Amazon Bedrock 上对开放权重模型使用提示缓存
许多生成式 AI 应用每次请求都会发送相同的长上下文,而提示缓存可以避免每次都重新处理它。该上下文可以是系统提示、参考文档、工具定义或截至目前的对话内容。Amazon Bedrock 上的开放权重模型可以跨请求复用它,这有助于降低输入成本和响应延迟。
提示缓存会复用匹配的提示前缀已计算的状态,因此重复的上下文会从缓存中读取,而不再重新处理。Amazon Bedrock 为你管理缓存。视模型而定,你可以使用自动生效的隐式缓存、由你标记可复用前缀的显式缓存,或两者兼用。你复用的上下文越多、复用越频繁,节省就越多。
与 Amazon Bedrock 上的其他模型一样,你的提示和输出不会与模型提供方共享,也不会用于训练模型。更多信息,请参阅 Amazon Bedrock 用户指南中的数据保护。
Amazon Bedrock 上的开放权重模型现已支持显式提示缓存。在本文中,我们通过 Chat Completions API 对开放权重模型使用这两种模式,并展示如何从每个响应中读取缓存使用情况。随后,我们在同一 API 上对 OpenCode 编码智能体会话应用隐式缓存,最后以最佳实践收尾。
在 Amazon Bedrock 上为开放权重模型使用提示缓存
当一次请求的开头内容与更早的请求相同时,Amazon Bedrock 会从缓存中读取该前缀,只处理其余部分。缓存读取的计费费率低于标准输入,因此每次复用前缀时节省都会累积。视模型而定,缓存写入的计费费率可能高于标准输入。各模型的费率请参阅 Amazon Bedrock 定价。
支持的模式取决于模型和 API。各模型支持的缓存模式、最小前缀长度以及缓存条目的保留时长,请参阅 Models at a glance。两种模式的对比如下:
| 特性 | 隐式缓存 | 显式缓存 |
|---|---|---|
| 请求改动 | 无 | 在 Chat Completions API 上,prompt_cache_options 的 mode 设为 explicit,外加一个或多个 prompt_cache_breakpoint 标记 |
| 缓存内容 | 符合条件的提示前缀,由系统以尽力而为的方式自动选取 | 截至并包含每个断点的内容 |
| 适用场景 | 已经以稳定前缀开头的提示,例如对话和智能体循环 | 带有变化问题的固定共享前缀,或你希望控制的分层前缀 |
隐式缓存:Amazon Bedrock 会以尽力而为的方式自动复用符合条件的前缀。在对话中,每个请求都会重新发送完整上下文,因此上一个请求就成为下一个请求的缓存前缀(图 1)。正如提示缓存指南所建议的,请把静态内容放在前面、动态内容放在最后。保持提示开头稳定,可以让之后的每个请求都复用它。如果靠前的部分发生变化,如图 1 的第 4 轮,缓存就从该处重建。

图 1:对话各轮次间的隐式提示缓存
显式缓存:你用缓存断点标记每个可复用前缀的结束位置。你可以添加多个断点,最多不超过模型支持的上限,以缓存以不同频率变化的分层内容,如图 2 所示。截至每个断点的内容会被写入缓存一次,之后的请求会读取它;最后一个断点之后的内容则每次请求都会重新处理。请查看模型卡片,了解断点之前所需的最小 token 数、最大断点数以及生存时间(TTL),该时间在每次缓存命中时重置。

图 2:在共享前缀之后设置断点的显式提示缓存
借助隐式缓存,Amazon Bedrock 也可能将后续请求永远不会复用的内容写入缓存,例如每次都不相同的问题。当共享前缀之后的内容在每次请求中都会变化时,请使用显式缓存,将缓存写入限制在共享前缀范围内。最后一个断点之后的内容按标准输入费率计费。对于缓存写入费用更高的模型,你无需为永远不会被读回的内容支付更高的写入费率。
解决方案概述
下图展示了本文中的两个示例如何通过同一个 Chat Completions API 端点访问 Amazon Bedrock。

图 3:本文中的两个示例如何访问 Amazon Bedrock
- Python 应用程序和 OpenCode 编码智能体向你所选区域的 Amazon Bedrock Runtime 端点发送请求,并使用短期 Amazon Bedrock API 密钥进行身份验证。
- Amazon Bedrock 检查提示缓存中是否存在匹配的前缀。它从缓存中读取匹配的前缀,并将新的可缓存内容写入缓存。
- Amazon Bedrock 将请求发送给所选的开放权重模型并返回响应,其中包括后续章节将向你展示如何读取的缓存用量字段。
先决条件
要运行这些示例,你需要以下条件:
- 一个 AWS 账户,并且能够访问你在 Amazon Bedrock 上选择的模型。模型可用性和提示缓存支持因 AWS 区域而异,因此请查看模型卡以了解你的模型所支持的区域。
- 具有 AWS Identity and Access Management (IAM) 身份的 AWS 凭证,该身份拥有在 Amazon Bedrock 上调用你所选模型的权限。
- Python 3.12,以及 openai(3.26.0 或更高版本)和 aws-bedrock-token-generator(1.1.0 或更高版本)包。
- 对于编码智能体示例,需要 npm 来安装 OpenCode 1.18.35。
在使用模型之前,请查看其许可证和服务条款,这些内容可从其模型卡中链接获取。你对模型的使用还须遵守 AWS Responsible AI Policy。
通过 Chat Completions API 缓存产品手册
该示例是一个虚构净水器 AnyCompany AquaPure 500 的支持助手。系统提示中包含一行指令和用户手册,后者即为可复用的前缀。每个请求都会询问不同的客户问题。
设置客户端
这些示例使用 OpenAI Python SDK 搭配 Amazon Bedrock Chat Completions 端点。在身份验证方面,aws-bedrock-token-generator 包中的 provide_token() 函数会将你的 AWS 凭证转换为短期的 Amazon Bedrock API 密钥,有效期最长 12 小时。你无需创建或存储长期密钥。
- 创建虚拟环境并安装这些包:
python3.12 -m venv .venv
source .venv/bin/activate
pip install "openai>=3.26.0" "aws-bedrock-token-generator>=1.1.0"
- 创建手册。我们的手册是约 4,000 个 token 的 Markdown。以下摘录展示了其格式:
# AnyCompany AquaPure 500 Owner's Manual
### 7.1 Replacement schedule
| Stage | Cartridge | Part number | Replace every |
| ----- | ------------------- | ----------- | ------------- |
| 1 | Sediment pre-filter | AP-F1 | 6 months |
| 4 | Carbon post-filter | AP-F4 | 12 months |
### 9. Error codes
| Code | Description | What to do |
| ---- | ----------------------- | -------------------------------------------- |
| E01 | Low feed water pressure | Check that the feed water valve is open. |
| E07 | Drain line restriction | Check the black concentrate tube for kinks. |
### 11. Warranty
- 水龙头:自购买之日起 3 年。3 V 电池不在保修范围内。
将其保存为 manual.md,并添加章节,直到长度超过模型卡上的最小前缀长度。占位文本即可,因为缓存只需要一个完全相同的前缀。保留所示的三节,它们回答了示例问题。
- 将以下设置代码保存为同一目录下的 common.py。接下来创建的示例会从中导入。
from pathlib import Path
from aws_bedrock_token_generator import provide_token
from openai import OpenAI
REGION = "<AWS_REGION>"
MODEL_ID = "<MODEL_ID_OR_INFERENCE_PROFILE_ID>"
MANUAL = Path(__file__).with_name("manual.md").read_text()
SYSTEM_PROMPT = (
"You are the AnyCompany AquaPure support assistant. Answer the customer's question in at "
"most three sentences, using only the owner's manual below.\n\n" + MANUAL
)
QUESTIONS = [
"My filter shows error code E07. What does it mean and how do I fix it?",
"How often do I need to replace the AP-F4 post-filter?",
"Is the 3 V battery in the smart faucet covered by the warranty?",
]
# Chat Completions API client: the OpenAI SDK pointed at the Amazon Bedrock OpenAI-compatible endpoint
client = OpenAI(
api_key=provide_token(region=REGION),
base_url=f"https://bedrock-runtime.{REGION}.amazonaws.com/openai/v1",
)
def report(call_number, response):
"""Print the cache fields from the 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}"
)
如果你的模型返回推理 token,它们会计入 max_tokens。这些示例设置 max_tokens=1024,以便简短回答有足够的空间完成。
隐式缓存
隐式缓存不需要任何缓存控制。将手册放在系统消息中,将问题放在用户消息中。把两者作为同一条用户消息的组成部分发送,不会获得隐式缓存命中。将以下内容保存为 implicit.py,并用 python implicit.py 运行:
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": SYSTEM_PROMPT}, # static, same every call
{"role": "user", "content": question}, # changes every call
],
max_tokens=1024,
)
report(i, response)
验证隐式缓存
每个响应都会在 usage.prompt_tokens_details 中报告缓存活动。图 4 展示了如何读取这些字段,以及每个示例的三次调用中应出现的模式。

图 4:如何读取缓存使用字段(示意)
在隐式模式下,第 1 次调用将提示写入缓存。第 2 次和第 3 次调用从缓存中读回包含指令和手册的系统消息。它们还会各自写入少量 token,因为隐式模式会扩展缓存前缀以覆盖每个新问题。每次调用中,最后一条消息之后的少量 token 保持未缓存。这是首次运行的模式。如果在 TTL 内再次运行该示例,每次调用都会从缓存读取,且不会写入。
显式缓存
选择显式缓存可以精确控制缓存的内容。如图 4 所示,隐式运行的第 2 次和第 3 次调用各自向缓存写入少量 token,而使用显式缓存的相同调用则不会写入任何内容。借助多个断点,你可以缓存分层前缀,例如共享指令和工具,后跟每个客户的文档(图 2)。
文章标题:在 Amazon Bedrock 上对开放权重模型使用提示缓存
正文: 对于显式缓存,请在请求中添加以下内容:
prompt_cache_options将mode设置为explicit即选择显式模式。它是 Amazon Bedrock 的请求字段,OpenAI SDK 通过extra_body将其发送。
- 文本内容部分上的
prompt_cache_breakpoint标记可复用前缀的结束位置。截至并包含该部分的内容会被缓存,其后的内容在每次请求时都会重新处理。
将同一循环的显式版本保存为 explicit.py:
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,
# Cache everything up to and including this content part.
"prompt_cache_breakpoint": {"mode": "explicit"},
}
],
},
{"role": "user", "content": question}, # after the breakpoint, not cached
],
max_tokens=1024,
extra_body={"prompt_cache_options": {"mode": "explicit"}},
)
report(i, response)
请同时设置这两个部分。没有断点的显式模式不会缓存任何内容,而没有显式模式的断点行为与隐式缓存相同。关于 prompt_cache_options 的可选 ttl 字段,请查看模型卡以了解支持的值。
验证显式缓存
如果在 implicit.py 之后立即运行 explicit.py,其第一次调用就已经是缓存命中。若要从冷启动的第一次调用开始,请为系统提示添加一个唯一的第一行,例如 SYSTEM_PROMPT = f"Run ID: {uuid.uuid4()}\n" + SYSTEM_PROMPT(在 explicit.py 顶部加上 import uuid)。
如图 4 中的显式柱所示,只有第一次调用会写入。每次重复都会读取断点之前的整个前缀且不写入任何内容,而断点之后的问题构成了未缓存的剩余部分。
将提示缓存与 OpenCode 编码代理配合使用
编码代理在每一步都会重新发送一个庞大而稳定的前缀:系统提示、工具定义以及到目前为止的对话。这使它们天然适合隐式缓存。OpenCode 是一个开源编码代理。它可以通过自定义的 OpenAI 兼容提供程序调用任何 Chat Completions 端点,因此可以使用与 Python 示例相同的 Amazon Bedrock 端点。图 5 展示了 OpenCode 在一轮交互中发送的请求,以及 Amazon Bedrock 从缓存中读取的部分。

图 5:OpenCode 在一轮交互中向 Amazon Bedrock 发送的请求
在一轮交互中,OpenCode 发送请求 1,其中包含其系统提示、工具定义和你的提示,Amazon Bedrock 将其写入缓存。模型以工具调用作为响应,OpenCode 会在你的机器上运行该调用。随后 OpenCode 发送请求 2,其中包含请求 1 加上工具调用及其结果。Amazon Bedrock 从缓存中读取请求 1,只写入新的尾部,并返回响应。
配置 OpenCode
安装 OpenCode 并检查版本:
npm install --prefix ~/.local/opt/opencode [email protected]
export PATH="$HOME/.local/opt/opencode/node_modules/.bin:$PATH"
opencode --version
接下来,将以下 opencode.json 添加到仓库根目录,或将其保存为 ~/.config/opencode/opencode.json 以应用于每个项目。它定义了一个名为 bedrock 的提供程序,使用 OpenAI 兼容包来调用 Amazon Bedrock Chat Completions 端点:
{
"$schema": "https://opencode.ai/config.json",
"model": "bedrock/<MODEL_ID_OR_INFERENCE_PROFILE_ID>",
"small_model": "bedrock/<MODEL_ID_OR_INFERENCE_PROFILE_ID>",
"provider": {
"bedrock": {
"npm": "@ai-sdk/openai-compatible",
"name": "Amazon Bedrock (Chat Completions)",
"options": {
"baseURL": "https://bedrock-runtime.<AWS_REGION>.amazonaws.com/openai/v1",
"apiKey": "{env:BEDROCK_API_KEY}"
},
"models": {
"<MODEL_ID_OR_INFERENCE_PROFILE_ID>": { "name": "Open-weight model on Amazon Bedrock" }
}
}
}
}
OpenCode 使用 small_model 生成会话标题,因此将它指向同一个模型,可以让每个请求都落在你已启用的模型上。该 provider 从 BEDROCK_API_KEY 读取密钥。请把它设置为从 provide_token() 获取的 Amazon Bedrock 短期 API 密钥,在第一个示例所用的虚拟环境中执行。如果密钥过期,请再次运行该命令以获取新密钥:
export BEDROCK_API_KEY="$(python -c '
from aws_bedrock_token_generator import provide_token
print(provide_token(region="<AWS_REGION>"))')"
确认 OpenCode 列出了该模型:
opencode models bedrock
在编码会话中验证隐式缓存
我们针对一个只包含一个简短 Python 文件的小型仓库运行了一个三轮会话。第 1 轮要求进行缺陷审查,第 2 轮要求修复,第 3 轮要求一个简短的后续追问:
opencode run --format json --title "cache-demo" \
"Read src/inventory.py and list any bugs in Inventory.remove. Do not edit files."
opencode run --format json -s <sessionID> \
"Now propose a fixed version of Inventory.remove as a code block. Do not edit files."
opencode run --format json -s <sessionID> \
"In one sentence, what does low_stock return?"
将 <sessionID> 替换为第 1 轮 JSON 输出中的 sessionID 值。opencode export <sessionID> 命令会列出每个请求的 token 用量:cache.read 保存来自 Amazon Bedrock 的 cached_tokens 值,input 保存其余部分。OpenCode 1.18.35 不会为 OpenAI 兼容 provider 记录 cache_write_tokens,因此 cache.write 保持为 0。
图 6 显示了会话中每个请求从缓存读取的比例。

图 6:OpenCode 会话中的缓存读取(示意)
第一个请求处理整个提示词,其中大部分是 OpenCode 系统提示词和工具定义,Amazon Bedrock 会将其写入缓存。后续每个请求都会从缓存中读取截至上一个请求结尾的全部内容,因此只有对话新增的尾部会被处理。这无需任何缓存配置即可生效。
最佳实践
这些实践适用于任何支持提示词缓存的模型:
- 在两种模式下都将静态内容放在前面。将系统提示词、工具定义和参考文档放在会变化的内容之前,并在各请求之间保持它们完全一致。在显式模式下,将每个断点放在它所覆盖的静态内容之后。时间戳和请求 ID 应放在提示词末尾。
- 使前缀足够长。满足模型卡上最低 token 数的前缀才有资格被缓存。
- 通过 usage 字段确认命中。在任一模式下,检查每个响应中的缓存读取和写入。在整个工作负载中,跟踪 CacheReadInputTokenCount 和 CacheWriteInputTokenCount 运行时指标。
- 保持缓存温热。稳定的流量会让前缀保持缓存,因为 TTL 会在每次命中时重置。在超过 TTL 的空闲间隔之后,下一个请求会重新写入前缀。
- 缓存你重复使用的内容。节省来自缓存读取,因此应缓存后续请求会再次读取的内容,尤其是在缓存写入成本高于标准输入的情况下。使用跨区域推理时,在高需求时段预计会有一些额外的缓存写入。
清理
这些示例只发起推理调用,不会在你的 AWS 账户中创建任何资源。缓存条目在 TTL 内未被读取后会过期。provide_token() 返回的短期 API 密钥也会自行过期,示例从不会将其写入磁盘。若想更早从 shell 中清除它,请运行 unset BEDROCK_API_KEY。
要删除本地文件:
- 删除示例目录及其 Python 虚拟环境。
- 从你的代码仓库中删除 opencode.json,若你将其保存在全局位置,则删除 ~/.config/opencode/opencode.json。
- 若你不再需要 OpenCode,请删除 ~/.local/opt/opencode。
结论
提示缓存让 Amazon Bedrock 上的开放权重模型能够复用重复的上下文,而几乎或完全无需改动你的代码。在本文中,隐式缓存无需任何缓存设置就覆盖了支持助手和 OpenCode 会话。显式缓存通过一个请求选项和每个可复用层的断点提供了精确控制。在每种情况下,每个响应的 usage 字段都会显示哪些内容来自缓存,因此你可以基于自己的流量衡量收益。
要开始使用,请在 Amazon Bedrock 上选择一个支持提示缓存的开放权重模型。用你自己的参考内容运行本文的示例,并将缓存读取与未缓存的输入进行对比。提示缓存指南涵盖了每个模型的限制和选项,而 Amazon Bedrock 运行时指标可让你跟踪应用程序中的缓存读取和写入。如有疑问,请通过 AWS Support 或 AWS re:Post 社区联系我们。