Newshot

在 Amazon Bedrock 上对开放权重模型使用提示缓存

AI summary

许多生成式 AI 应用每次请求都会发送相同的长上下文,提示缓存可避免每次重复处理。Amazon Bedrock 上的开放权重模型能跨请求复用这些上下文,从而降低输入成本和响应延迟。Bedrock 会为你管理缓存,支持自动生效的隐式缓存、需标记可复用前缀的显式缓存或两者兼用;复用越多越频繁,节省越多。与其他模型一样,你的提示和输出不会与模型提供方共享,也不会用于训练模型。

Translation(model translation, not the source's own text)

在 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。

Python 应用程序和 OpenCode 智能体都通过同一个 Chat Completions API 端点访问 Amazon Bedrock
Python 应用程序和 OpenCode 智能体都通过同一个 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 小时。你无需创建或存储长期密钥。

  1. 创建虚拟环境并安装这些包:

        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 个 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,并添加章节,直到长度超过模型卡上的最小前缀长度。占位文本即可,因为缓存只需要一个完全相同的前缀。保留所示的三节,它们回答了示例问题。

  1. 将以下设置代码保存为同一目录下的 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 展示了如何读取这些字段,以及每个示例的三次调用中应出现的模式。

三次调用中的缓存使用字段,展示隐式和显式模式下的已缓存、已写入和未缓存 token
三次调用中的缓存使用字段,展示隐式和显式模式下的已缓存、已写入和未缓存 token

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

OpenCode 一轮交互中的两个请求,其中请求 2 从缓存中读取请求 1 并只处理新的尾部
OpenCode 一轮交互中的两个请求,其中请求 2 从缓存中读取请求 1 并只处理新的尾部

图 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 显示了会话中每个请求从缓存读取的比例。

Cache reads across an OpenCode session, each request reusing everything up to the end of the previous request
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 数的前缀才有资格被缓存。
  • 通过 usage 字段确认命中。在任一模式下,检查每个响应中的缓存读取和写入。在整个工作负载中,跟踪 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 会话。显式缓存通过一个请求选项和每个可复用层的断点提供了精确控制。在每种情况下,每个响应的 usage 字段都会显示哪些内容来自缓存,因此你可以基于自己的流量衡量收益。

要开始使用,请在 Amazon Bedrock 上选择一个支持提示缓存的开放权重模型。用你自己的参考内容运行本文的示例,并将缓存读取与未缓存的输入进行对比。提示缓存指南涵盖了每个模型的限制和选项,而 Amazon Bedrock 运行时指标可让你跟踪应用程序中的缓存读取和写入。如有疑问,请通过 AWS Support 或 AWS re:Post 社区联系我们。

关于作者

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by AWS Machine Learning
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗