在 Amazon Bedrock 上用开放权重模型实现提示词缓存
Use prompt caching with open-weight models on Amazon Bedrock
Amazon Bedrock 的开放权重模型现已支持显式提示词缓存,可与自动生效的隐式缓存配合使用。缓存会复用匹配提示词前缀的计算状态,重复上下文直接从缓存读取,从而降低输入成本和响应延迟;缓存读取按低于标准输入的价格计费。两种模式均通过 Chat Completions API 使用,并可从响应中读取缓存用量字段。
许多生成式 AI 应用在每次请求时都会发送相同的长上下文,而提示缓存可以避免每次都重新处理它。该上下文可以是系统提示、参考文档、工具定义或到目前为止的对话。Amazon Bedrock 上的开放权重模型可以跨请求复用它,这有助于降低输入成本和响应延迟。
提示缓存会复用匹配的提示前缀已计算的状态,因此重复的上下文会从缓存中读取,而不是再次处理。Amazon Bedrock 会为你管理缓存。根据模型的不同,你可以使用自动生效的隐式缓存、需要标记可复用前缀的显式缓存,或两者兼用。你复用的上下文越多、复用越频繁,节省就越多。
与 Amazon Bedrock 上的其他模型一样,你的提示和输出不会与模型提供商共享,也不会用于训练模型。更多信息,请参阅 Amazon Bedrock 用户指南中的数据保护。
Amazon Bedrock 上的开放权重模型现在支持显式提示缓存。在本文中,我们通过 Chat Completions API 在开放权重模型上使用这两种模式,并展示如何从每个响应中读取缓存使用情况。然后,我们在同一 API 上对 OpenCode 编码代理会话应用隐式缓存,最后以最佳实践作结。
Amazon Bedrock 上开放权重模型的提示缓存
当请求的开头与先前的请求内容相同时,Amazon Bedrock 会从缓存中读取该前缀,只处理其余部分。缓存读取的计费费率低于标准输入,因此每次复用前缀都能带来更多节省。根据模型的不同,缓存写入的计费费率可能高于标准输入。各模型的费率请参阅 Amazon Bedrock 定价。
支持的缓存模式取决于模型和 API。各模型的缓存模式、最小前缀长度以及缓存条目的保留时长,请参阅模型概览。两种模式的比较如下:
| 特性 | 隐式缓存 | 显式缓存 |
| 请求变更 | 无 | 在 Chat Completions API 上,使用 prompt_cache_options 并将 mode 设为 explicit,外加一个或多个 prompt_cache_breakpoint 标记 |
| 缓存内容 | 符合条件的提示前缀,由系统以尽力而为的方式自动选择 | 每个断点之前(含断点)的内容 |
| 适用场景 | 开头已具有稳定前缀的提示,例如对话和代理循环 | 固定共享前缀加变化的问题,或你希望控制的分层前缀 |
隐式缓存:Amazon Bedrock 会以尽力而为的方式自动复用符合条件的前缀。在对话中,每个请求都会重新发送完整上下文,因此上一个请求会成为下一个请求的缓存前缀(图 1)。正如提示缓存指南所建议的,将静态内容放在前面,动态内容放在后面。保持提示开头稳定,可以让后续每个请求都复用它。如果靠前的部分发生变化,如图 1 中的第 4 轮,缓存将从该点开始重建。
图 1:对话各轮次中的隐式提示缓存
显式缓存:你在每个可复用前缀的末尾标记一个缓存断点。你可以添加多个断点,最多不超过模型支持的上限,以便缓存以不同速率变化的层,如图 2 所示。每个断点之前的内容会写入缓存一次,并在后续请求中读取;最后一个断点之后的内容则在每次请求时处理。请查看模型卡,了解断点前的最小 token 数、最大断点数以及生存时间(TTL),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 区域而异,因此请查看模型卡,了解您的模型支持的区域。
- 具有调用 Amazon Bedrock 上您所选模型权限的 AWS Identity and Access Management (IAM) 身份的 AWS 凭证。
- Python 3.12,以及
openai(3.26.0 或更高版本)和aws-bedrock-token-generator(1.1.0 或更高版本)包。 - 对于编码代理示例,需要 npm 来安装 OpenCode 1.18.35。
在使用模型之前,请查看其许可证和服务条款,链接位于其模型卡中。您对模型的使用还须遵守 AWS 负责任 AI 政策。
通过 Chat Completions API 缓存产品手册
该示例是一个虚构净水器 AnyCompany AquaPure 500 的支持助手。系统提示包含一行指令和用户手册,即可复用前缀。每个请求都会询问不同的客户问题。
设置客户端
这些示例使用 OpenAI Python SDK 和 Amazon Bedrock Chat Completions 端点。对于身份验证,aws-bedrock-token-generator 包中的 provide_token() 函数会将您的 AWS 凭证转换为短期 Amazon Bedrock API 密钥,有效期最长 12 小时。您无需创建或存储长期密钥。
1. 创建虚拟环境并安装这些包:
python3.12 -m venv .venv
source .venv/bin/activate
pip install "openai>=3.26.0" "aws-bedrock-token-generator>=1.1.0"2. 创建手册。我们的手册大约有 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
- Faucet: 3 years from the date of purchase. The 3 V cell is not covered.将其保存为 manual.md,并不断添加章节,直到长度超过模型卡上的最小前缀长度。占位文本即可,因为缓存只需要完全相同的前缀。保留所示的三个章节,它们回答了示例问题。
3. 将以下设置代码保存为同一目录下的 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)。
对于显式缓存,请在请求中添加以下内容:
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(将 import uuid 放在 explicit.py 的顶部)。
如图 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 opencode-ai@1.18.35
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 生成会话标题,因此将其指向同一模型可确保每个请求都落在你已启用的模型上。该提供商从 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 兼容提供商记录 cache_write_tokens,因此 cache.write 保持为 0。
图 6 显示了会话中每个请求有多少内容从缓存读取。
图 6:OpenCode 会话中的缓存读取(示意)
第一个请求处理整个提示,其中大部分是 OpenCode 系统提示和工具定义,Amazon Bedrock 将其写入缓存。后续每个请求都从缓存读取直到上一个请求末尾的全部内容,因此只处理对话的新增尾部。这无需任何缓存配置即可生效。
最佳实践
这些实践适用于任何支持提示缓存的模型:
- 在两种模式下都将静态内容放在前面。 将系统提示、工具定义和参考文档放在会变化的内容之前,并在请求之间保持它们完全一致。在显式模式下,将每个断点放在其所覆盖的静态内容之后。时间戳和请求 ID 应放在提示末尾。
- 使前缀足够长。 达到模型卡上最低 token 数的前缀才有资格被缓存。
- 通过用量字段确认命中。 在任一模式下,检查每个响应中的缓存读取和写入。在整个工作负载中,跟踪
CacheReadInputTokenCount和CacheWriteInputTokenCount运行时指标。 - 保持缓存热度。 稳定的流量可使前缀保持缓存,因为每次命中都会重置 TTL。在超过 TTL 的空闲间隔后,下一个请求会再次写入前缀。
- 缓存你重复使用的内容。 节省来自缓存读取,因此应缓存后续请求会再次读取的内容,尤其是在缓存写入成本高于标准输入的情况下。使用跨区域推理时,在高需求时段预计会有一些额外的缓存写入。
清理
这些示例仅进行推理调用,不会在你的 AWS 账户中创建任何资源。缓存条目在超过 TTL 未被读取后过期。来自 provide_token() 的短期 API 密钥也会自行过期,且示例从不将其写入磁盘。要更早地从 shell 中清除它,请运行 unset BEDROCK_API_KEY。
要删除本地文件:
1. 删除示例目录及其 Python 虚拟环境。
2. 从你的仓库中删除 opencode.json,如果你将其保存在全局位置,则删除 ~/.config/opencode/opencode.json。
3. 如果你不再需要 OpenCode,请删除 ~/.local/opt/opencode。
结论
提示缓存让 Amazon Bedrock 上的开放权重模型能够复用重复的上下文,而几乎无需或完全无需修改你的代码。在本文中,隐式缓存覆盖了支持助手和 OpenCode 会话,且完全不需要任何缓存设置。显式缓存通过一个请求选项和每个可复用层的断点提供了精确控制。在每种情况下,每个响应的 usage 字段都会显示哪些内容来自缓存,因此你可以根据自己的流量来衡量收益。
要开始使用,请选择支持提示缓存的 Amazon Bedrock 开放权重模型。用你自己的参考内容运行本文中的示例,并将缓存读取量与未缓存的输入进行比较。提示缓存指南涵盖了每个模型的限制和选项,而 Amazon Bedrock 的运行时指标可让你跨应用程序跟踪缓存读取和写入。如有问题,请通过 AWS Support 或 AWS re:Post 社区联系我们。
关于作者
Dustin Liu
Dustin 是 AWS 驻澳大利亚墨尔本的 AI/ML 专家解决方案架构师。他与数字原生/独立软件供应商合作,设计、实现生产化并扩展 AI 解决方案。他喜欢保持动手实践,构建解决实际业务问题的解决方案。
Aman Arora
Aman 是 AWS 驻澳大利亚悉尼的生成式 AI 专家解决方案架构师。他与客户合作,在 Amazon Bedrock 和 Amazon Bedrock AgentCore 上设计和构建生成式 AI 应用程序和 AI 智能体。他专注于帮助企业在生产环境中大规模运行智能体系统,重点在于评估、可观测性和可靠性。
Melanie Li
Melanie 博士是 AWS 驻澳大利亚悉尼的高级生成式 AI 专家解决方案架构师,她的工作重点是帮助客户使用最先进的 AI/ML 工具构建解决方案。她积极参与亚太及日本地区的多个生成式 AI 计划,充分发挥 LLM 的能力。在加入 AWS 之前,Li 博士曾在金融和零售行业担任数据科学相关职位。
Saurabh Trikande
Saurabh 是 Amazon Bedrock 和 Amazon SageMaker Inference 的高级产品经理。他专注于部署复杂 AI 应用程序、多租户模型推理、成本优化以及让生成式 AI 模型的部署更易于使用等核心挑战。业余时间,Saurabh 喜欢徒步旅行、了解创新技术、关注 TechCrunch 以及与家人共度时光。
来源:AWS Machine Learning Blog · aws.amazon.com





