跳到正文
AWS Machine Learning Blog· Dustin Liu·· 3 天前精選AI 評分62

Amazon Bedrock 開放權重模型現支援顯式提示詞快取

Introducing explicit prompt caching with open-weight models on Amazon Bedrock

AI 導讀

Amazon Bedrock 的開放權重模型現已支援顯式提示詞快取,並可透過 Chat Completions API 標記可重用的提示詞前綴。文章以 Python 範例比較隱式與顯式快取,並示範 OpenCode 編碼智能體工作階段如何使用隱式快取及檢視快取用量欄位。快取讀取的費率低於標準輸入,快取寫入費率則視乎模型而定;回應中的用量欄位可用來核對快取讀寫。

推薦理由

文章比較隱式與顯式快取的適用情境,並以 Python 範例展示快取讀寫欄位,再示範 OpenCode 工作階段中的快取讀取。

正文 · 繁體中文

許多生成式 AI 應用程式每次提出請求時,都會傳送相同的長篇上下文;提示詞快取可避免每次都重新處理這些內容。這些上下文可以是系統提示詞、參考文件、工具定義,或截至目前的對話內容。Amazon Bedrock 上的開放權重模型可以在不同請求之間重用這些內容,有助降低輸入成本及回應延遲。

提示詞快取會重用相符提示詞前綴的運算狀態,讓重複的上下文直接從快取讀取,而不必再次處理。Amazon Bedrock 會代你管理快取。視乎模型而定,你可以使用會自動運作的隱式快取、由你標記可重用前綴的明確快取,或同時使用兩者。重用的上下文越多、重用次數越頻密,節省就越多。

與 Amazon Bedrock 上的其他模型一樣,你的提示詞和輸出內容不會與模型供應商分享,也不會用於訓練模型。如需更多資訊,請參閲《Amazon Bedrock User Guide》中的資料保護。

Amazon Bedrock 上的開放權重模型現已支援明確提示詞快取。本文會透過 Chat Completions API,使用開放權重模型示範兩種模式,並説明如何從每個回應讀取快取用量。接着,我們會在同一 API 上,為 OpenCode 編碼 Agent 工作階段套用隱式快取,最後介紹最佳做法。

Amazon Bedrock 上開放權重模型的提示詞快取

當請求以與先前請求相同的內容開頭時,Amazon Bedrock 會從快取讀取該前綴,只處理其餘內容。快取讀取的收費低於標準輸入,因此每次重用前綴都能增加節省幅度。視乎模型而定,快取寫入的收費可能高於標準輸入。各模型的收費請參閲 Amazon Bedrock 定價。

支援的模式視乎模型和 API 而定。各模型支援的快取模式、前綴最短長度,以及快取項目的保留時間,請參閲模型一覽。兩種模式的比較如下:

功能 隱式快取 明確快取
請求變更 無 在 Chat Completions API 上,prompt_cache_options,模式設為 explicit,並加入一個或多個 prompt_cache_breakpoint 標記
快取內容 系統會盡力自動選取符合條件的前綴 截至每個斷點(包括該斷點)的內容
適用情況 已以穩定前綴開頭的提示詞,例如對話和 Agent 循環 固定的共用前綴搭配會變動的問題,或需要自行控制的分層前綴

隱式快取: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 編碼 Agent 會向你所在區域的 Amazon Bedrock Runtime 端點傳送請求,並使用短期 Amazon Bedrock API 金鑰進行驗證。
  2. Amazon Bedrock 會在提示詞快取中檢查是否有相符的前綴。若找到相符的前綴,便會從快取讀取,並將新的可快取內容寫入快取。
  3. Amazon Bedrock 會將請求傳送至所選的開放權重模型,並傳回回應,其中包括以下章節會説明如何讀取的快取用量欄位。

先決條件

執行範例前,你需要具備以下項目:

  • 一個可在 Amazon Bedrock 使用所選模型的 AWS 帳戶。模型的可用性和提示詞快取支援因 AWS 區域而異,請查閲模型卡,確認模型支援的區域。
  • 具備權限的 AWS Identity and Access Management (IAM) 身分的 AWS 憑證,可用來在 Amazon Bedrock 呼叫所選模型。
  • Python 3.12,以及 openai(3.26.0 或更新版本)和 aws-bedrock-token-generator(1.1.0 或更新版本)套件。
  • 編碼 Agent 範例需要使用 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 個 Markdown token。以下摘錄展示其格式:

# 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,這些 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:如何解讀快取用量欄位(示意)

在隱式模式下,第一次呼叫會將提示詞寫入快取。第二和第三次呼叫會從快取讀取包含指示和手冊的系統訊息。每次也會寫入少量 token,因為隱式模式會延伸快取前綴,涵蓋每條新問題。每次呼叫中,最後一則訊息之後的少量 token 都不會快取。首次執行時會出現這種模式。如果在 TTL 內再次執行範例,所有呼叫都會從快取讀取,亦不會有任何寫入。

顯式快取

選用顯式快取,即可精確控制哪些內容會被快取。如圖 4 所示,隱式快取執行中的第二和第三次呼叫都會向快取寫入少量 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 編碼 Agent 中使用提示詞快取

編碼 Agent 每一步都會重新傳送大量而穩定的前綴:系統提示詞、工具定義,以及目前為止的對話。因此,隱式快取很適合用於這類 Agent。OpenCode 是一款開源編碼 Agent。它可透過自訂的 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 工作階段,兩者均完全不需要設定快取。顯式快取則只需一個請求選項,並為每個可重用層設定一個斷點,即可精確控制。在所有情況下,每個回應中的用量欄位都會顯示哪些內容來自快取,讓你可以根據自己的流量衡量效益。

如要開始使用,請選擇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 Agent。他專注協助企業大規模在生產環境中運行 Agent 系統,尤其重視評估、可觀測性及可靠性。

Melanie Li

Melanie Li

Melanie 擁有博士學位,是 AWS 的資深生成式 AI 專家解決方案架構師,常駐澳洲悉尼,專注與客戶合作,使用最先進的 AI/ML 工具構建方案。她積極參與 APJ 多項生成式 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