AWS Machine Learning Blog

Use prompt caching with open-weight models on Amazon Bedrock

8.5内容质量
Use prompt caching with open-weight models on Amazon Bedrock

TL;DR · AI 摘要

AWS 通过 Amazon Bedrock 支持提示缓存,可显著降低输入成本和响应延迟。

核心要点

  • 使用提示缓存可减少重复上下文的处理,从而降低输入成本。
  • Amazon Bedrock 支持隐式和显式两种缓存模式。
  • 隐式缓存适用于稳定前缀的提示,如对话和代理循环。

结构提纲

按章节快速跳转。

  1. 提示缓存可避免重复处理相同上下文,从而节省成本和时间。

  2. 提示缓存通过重用匹配的提示前缀状态,减少重复处理。

  3. 隐式缓存自动选择合适的前缀进行缓存,适用于稳定前缀的提示。

  4. 显式缓存需要手动标记可重用的前缀,适用于固定共享前缀的场景。

  5. 隐式和显式缓存模式在请求更改、缓存内容和适用场景上有所不同。

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • Amazon Bedrock 提示缓存
    • 隐式缓存
      • 自动选择前缀
      • 适用于稳定前缀的提示
    • 显式缓存
      • 手动标记前缀
      • 适用于固定共享前缀
    • 缓存优势
      • 降低输入成本
      • 减少响应延迟

金句 / Highlights

值得收藏与分享的关键句。

#Amazon Bedrock#AI#提示缓存#AWS
打开原文

在 Amazon Bedrock 上使用开放权重模型的提示缓存 | 人工智能

在 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。有关每个模型的缓存模式、最小前缀长度以及条目在缓存中保留的时间,请参阅《模型概览》。两种模式的比较如下:

功能

隐式缓存

显式缓存

请求更改

无

在 Chat Completions API 上,

code
prompt_cache_options

将模式设置为显式,再加上一个或多个

code
prompt_cache_breakpoint

标记

缓存内容

符合条件的前缀,根据最佳努力自动选择

包括每个断点的内容

适用场景

已经以稳定前缀开头的提示,如对话和代理循环

具有固定共享前缀和变化问题的提示,或您希望控制的分层前缀

隐式缓存:Amazon Bedrock 会根据最佳努力自动重复使用符合条件的前缀。在对话中,每个请求会重新发送完整的上下文,因此上一个请求会成为下一个请求的缓存前缀(图 1)。根据提示缓存指南的建议,将静态内容放在提示的开头,动态内容放在最后。保持提示的开头稳定,可以让每个后续请求重复使用它。如果早期部分发生变化,如图 1 的第 4 轮所示,缓存将从该点重新构建。

图 1:对话轮次之间的隐式提示缓存

显式缓存:您通过在每个可重用前缀的末尾添加缓存断点来标记缓存的结束。您可以添加多个断点,最多达到模型支持的最大数量,以缓存以不同速度变化的层,如图 2 所示。每个断点之前的内容将被写入缓存一次,之后在后续请求中读取;而最后一个断点之后的内容则在每次请求时进行处理。请查看模型卡片,了解断点之前的最小令牌数、最大断点数以及缓存生存时间(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 将请求发送到所选的开源模型,并返回响应,包括以下部分中将介绍的缓存使用字段。

先决条件

要运行这些示例,您需要以下内容:

  • 一个具有访问 Amazon Bedrock 上所选模型权限的 AWS 账户。模型可用性和提示缓存支持因 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 负责任的人工智能政策。

通过 Chat Completions API 缓存产品手册

该示例是一个虚构的水过滤器 AnyCompany AquaPure 500 的支持助手。系统提示中包含一条单行指令和用户手册,这是可重用的前缀。每个请求都会询问不同的客户问题。

设置客户端

这些示例使用 OpenAI Python SDK 和 Amazon Bedrock Chat Completions 端点。为了进行身份验证,aws-bedrock-token-generator 包中的 provide_token() 函数将您的 AWS 凭据转换为一个有效期最长为 12 小时的短期 Amazon Bedrock API 密钥。您无需创建或存储长期密钥。

  1. 创建虚拟环境并安装包:
code
python3.12 -m venv .venv
source .venv/bin/activate
pip install "openai>=3.26.0" "aws-bedrock-token-generator>=1.1.0"
  1. 创建手册。我们的手册大约有 4,000 个 Markdown 标记。以下摘录展示了其格式:
code
# AnyCompany AquaPure 500 所有者手册

### 7.1 更换时间表
| 阶段 | 滤芯 | 零件号 | 更换周期 |
| ----- | ------------------- | ----------- | ------------- |
| 1 | 沉淀预滤芯 | AP-F1 | 6 个月 |
| 4 | 碳后滤芯 | AP-F4 | 12 个月 |

### 9. 错误代码
| 代码 | 描述 | 解决方法 |
| ---- | ----------------------- | -------------------------------------------- |
| E01 | 进水压力低 | 检查进水阀是否打开。 |
| E07 | 排水管道受阻 | 检查黑色浓缩管是否有弯折。 |

### 11. 保修
- 水龙头:自购买之日起 3 年。3 V 电池不在保修范围内。

将其保存为 manual.md,并添加部分直到其长度超过模型卡片上的最小前缀长度。占位符文本可以使用,因为缓存只需要相同的前缀。保留显示的三个部分,它们可以回答示例问题。

  1. 将以下设置代码保存为 common.py,并保存在同一个目录中。接下来创建的示例将从其中导入。
code
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 = (
    "你是 AnyCompany AquaPure 的支持助手。用下面的所有者手册回答客户的问题,最多三句话。\n\n" + MANUAL
)

QUESTIONS = [
    "我的滤芯显示错误代码 E07。这是什么意思,我该如何解决?",
    "我需要多久更换一次 AP-F4 后滤芯?",
    "智能水龙头中的 3 V 电池是否在保修范围内?",
]

# 聊天补全 API 客户端:指向 Amazon Bedrock OpenAI 兼容端点的 OpenAI SDK
client = OpenAI(
    api_key=provide_token(region=REGION),
    base_url=f"https://bedrock-runtime.{REGION}.amazonaws.com/openai/v1",
)

def report(call_number, response):
    """从响应使用情况中打印缓存字段。"""
    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_number}: prompt_tokens={usage.prompt_tokens} cached_tokens={read} "
        f"cache_write_tokens={written} uncached={usage.prompt_tokens - read - written}"
    )

如果模型返回推理标记,它们将计入 max_tokens。示例中设置 max_tokens=1024,以便短答案有空间完成。

隐式缓存

隐式缓存不需要缓存控制。将手册放入系统消息中,问题放入用户消息中。将两者作为一条用户消息的一部分发送,没有隐式缓存命中。将以下内容保存为 implicit.py,并使用 python implicit.py 运行它:

code
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}, # 静态,每次调用相同
            {"role": "user", "content": question}, # 每次调用不同
        ],
        max_tokens=1024,
    )
    report(i, response)

验证隐式缓存

每条响应都会在 usage.prompt_tokens_details 中报告缓存活动。图 4 展示了如何读取这些字段,并且在每个样本的三次调用中,可以预期的模式。

图 4:如何读取缓存使用字段(示例)

在隐式模式下,第一次调用将提示写入缓存。第二次和第三次调用从缓存中读取系统消息、指令和手册。它们还会各自写入少量的标记,因为隐式模式会将缓存的前缀扩展以覆盖每个新问题。在最后一次消息之后的少量标记在每次调用中都未被缓存。这是第一次运行的模式。如果你在 TTL 内再次运行样本,每次调用都会从缓存中读取,而不会有任何写入。

显式缓存

选择显式缓存以精确控制缓存的内容。如图 4 所示,在隐式运行中,第二次和第三次调用各自向缓存写入少量标记,而使用显式缓存的相同调用则不会写入任何内容。通过设置多个断点,你可以缓存分层的前缀,例如共享的指令和工具,随后是每个客户的文档(如图 2 所示)。

对于显式缓存,请在请求中添加以下内容:

  • prompt_cache_options 将模式设置为 explicit 以选择显式模式。这是一个 Amazon Bedrock 请求字段,OpenAI SDK 通过 extra_body 发送它。
  • 在文本内容部分添加 prompt_cache_breakpoint 以标记可重用前缀的结束。包括该部分及之前的内容会被缓存,而之后的内容在每次请求中都会被重新处理。

将相同循环的显式版本保存为 explicit.py:

code
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_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 并检查版本:

code
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 端点:

code
{
  "$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 密钥。如果密钥过期,再次运行命令以获取新的密钥:

code
export BEDROCK_API_KEY="$(python -c '
from aws_bedrock_token_generator import provide_token
print(provide_token(region="<AWS_REGION>"))')"

确认 OpenCode 列出模型:

code
opencode models bedrock

在编码会话中验证隐式缓存

我们针对一个包含一个简短 Python 文件的小型仓库运行了一个三轮会话。第一轮要求进行错误检查,第二轮要求进行修复,第三轮要求进行简短的后续问题:

code
opencode run --format json --title "cache-demo" \
"Read src/inventory.py and list any bugs in Inventory.remove. Do not edit files."
code
opencode run --format json -s <sessionID> \
"Now propose a fixed version of Inventory.remove as a code block. Do not edit files."
code
opencode run --format json -s <sessionID> \
"In one sentence, what does low_stock return?"

将 <sessionID> 替换为第一轮 JSON 输出中的 sessionID 值。opencode export <sessionID> 命令列出每个请求的令牌使用情况: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 应位于提示的末尾。
  • 确保前缀足够长。符合模型卡片上最小令牌数的前缀有资格进行缓存。
  • 使用使用字段确认命中。在任一模式下,检查每个响应中的缓存读取和写入。在整个工作负载中,跟踪 CacheReadInputTokenCount 和 CacheWriteInputTokenCount 运行时指标。
  • 保持缓存的热度。稳定的流量会保持前缀缓存,因为每次命中时 TTL 会重置。如果空闲时间超过 TTL,则下一个请求将再次写入前缀。
  • 缓存你重复使用的内容。节省来自于缓存读取,因此缓存那些后续请求会再次读取的内容,特别是在缓存写入成本高于标准输入的情况下。在跨区域推理时,高需求期间可能会出现一些额外的缓存写入。

清理

这些示例仅进行推理调用,并不会在您的 AWS 账户中创建任何资源。缓存条目在未读取超过 TTL 后会过期。从 provide_token() 获取的短期 API 密钥也会自行过期,示例从不会将其写入磁盘。若想更快地从 shell 中清除它,请运行 unset BEDROCK_API_KEY。

要删除本地文件:

  1. 删除示例目录及其 Python 虚拟环境。
  1. 从您的仓库中删除 opencode.json,或者如果全局保存了它,则删除 ~/.config/opencode/opencode.json。
  1. 如果您不再需要 OpenCode,请删除 ~/.local/opt/opencode。

结论

提示缓存使 Amazon Bedrock 上的开放权重模型能够重复使用上下文,而对您的代码几乎没有或没有更改。在本文中,隐式缓存涵盖了支持助手和 OpenCode 会话,且没有任何缓存设置。显式缓存则通过一个请求选项和每个可重复使用的层的断点提供了精确的控制。在所有情况下,每个响应上的使用字段都会显示哪些内容来自缓存,因此您可以根据自己的流量衡量其优势。

要开始使用,请选择一个支持提示缓存的 Amazon Bedrock 开源模型。使用本文中的示例,并用自己的参考内容进行运行,将缓存读取与未缓存的输入进行比较。提示缓存指南涵盖了每个模型的限制和选项,而 Amazon Bedrock 运行时指标可帮助您跟踪应用程序中的缓存读取和写入情况。如有问题,请通过 AWS Support 或 AWS re:Post 社区进行咨询。

关于作者

'"`