跳到正文
AWS Machine Learning Blog· Dustin Liu·· 1 天前AI 评分38

在 Amazon Bedrock 上用开放权重模型实现提示词缓存

Use prompt caching with open-weight models on Amazon Bedrock

AI 导读

Amazon Bedrock 的开放权重模型现已支持显式提示词缓存,可与自动生效的隐式缓存配合使用。缓存会复用匹配提示词前缀的计算状态,重复上下文直接从缓存读取,从而降低输入成本和响应延迟;缓存读取按低于标准输入的价格计费。两种模式均通过 Chat Completions API 使用,并可从响应中读取缓存用量字段。

正文 · AI 翻译

许多生成式 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 轮,缓存将从该点开始重建。

Conversation turns reusing each previous request as the cached prefix, and rebuilding the cache when an early turn changes

图 1:对话各轮次中的隐式提示缓存

显式缓存:你在每个可复用前缀的末尾标记一个缓存断点。你可以添加多个断点,最多不超过模型支持的上限,以便缓存以不同速率变化的层,如图 2 所示。每个断点之前的内容会写入缓存一次,并在后续请求中读取;最后一个断点之后的内容则在每次请求时处理。请查看模型卡,了解断点前的最小 token 数、最大断点数以及生存时间(TTL),TTL 会在每次缓存命中时重置。

A cache breakpoint marking the end of the shared prefix, cached once and then read on later requests

图 2:在共享前缀之后设置断点的显式提示缓存

使用隐式缓存时,Amazon Bedrock 也可能将后续请求永远不会复用的内容写入缓存,例如每次都不相同的问题。当共享前缀之后的内容在每次请求时都发生变化时,请使用显式缓存,将缓存写入限制在共享前缀范围内。最后一个断点之后的内容按标准输入费率计费。在缓存写入收费更高的模型上,你无需为永远不会被读回的内容支付更高的写入费率。

解决方案概述

下图展示了本文中的两个示例如何通过同一个 Chat Completions API 端点访问 Amazon Bedrock。

Python application and OpenCode agent both reaching Amazon Bedrock through one Chat Completions API endpoint

图 3:本文中的两个示例如何访问 Amazon Bedrock

  1. Python 应用程序和 OpenCode 编码代理向您所在区域的 Amazon Bedrock Runtime 端点发送请求,并使用短期 Amazon Bedrock API 密钥进行身份验证。
  2. Amazon Bedrock 检查提示缓存中是否有匹配的前缀。它从缓存中读取匹配的前缀,并将新的可缓存内容写入缓存。
  3. 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 展示了如何读取这些字段,以及每个示例的三次调用中应预期的模式。

Cache usage fields across three calls, showing cached, written, and uncached tokens for implicit and explicit modes

图 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 从缓存中读取的部分。

Two requests in one OpenCode turn, where request 2 reads request 1 from cache and processes only the new tail

图 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 显示了会话中每个请求有多少内容从缓存读取。

Cache reads across an OpenCode session, each request reusing everything up to the end of the previous request

图 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 Liu

Dustin 是 AWS 驻澳大利亚墨尔本的 AI/ML 专家解决方案架构师。他与数字原生/独立软件供应商合作,设计、实现生产化并扩展 AI 解决方案。他喜欢保持动手实践,构建解决实际业务问题的解决方案。

Aman Arora

Aman Arora

Aman 是 AWS 驻澳大利亚悉尼的生成式 AI 专家解决方案架构师。他与客户合作,在 Amazon Bedrock 和 Amazon Bedrock AgentCore 上设计和构建生成式 AI 应用程序和 AI 智能体。他专注于帮助企业在生产环境中大规模运行智能体系统,重点在于评估、可观测性和可靠性。

Melanie Li

Melanie Li

Melanie 博士是 AWS 驻澳大利亚悉尼的高级生成式 AI 专家解决方案架构师,她的工作重点是帮助客户使用最先进的 AI/ML 工具构建解决方案。她积极参与亚太及日本地区的多个生成式 AI 计划,充分发挥 LLM 的能力。在加入 AWS 之前,Li 博士曾在金融和零售行业担任数据科学相关职位。

Saurabh Trikande

Saurabh Trikande

Saurabh 是 Amazon Bedrock 和 Amazon SageMaker Inference 的高级产品经理。他专注于部署复杂 AI 应用程序、多租户模型推理、成本优化以及让生成式 AI 模型的部署更易于使用等核心挑战。业余时间,Saurabh 喜欢徒步旅行、了解创新技术、关注 TechCrunch 以及与家人共度时光。

来源:AWS Machine Learning Blog · aws.amazon.com