> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS 中间件集成

> 使用 LangChain Python 与 AWS 中间件集成。

专为托管在 AWS Bedrock 上的模型设计的中间件。了解更多关于 [中间件](/oss/python/langchain/middleware/overview) 的信息。

| 中间件                      | 描述                |
| ------------------------ | ----------------- |
| [提示词缓存](#prompt-caching) | 通过缓存重复的提示词前缀来降低成本 |

## 提示词缓存

通过在 Amazon Bedrock 上缓存频繁重用的提示词前缀，降低推理延迟和输入令牌成本。此中间件会在系统提示词、工具定义和最近的消息之后自动放置缓存检查点，以便模型在后续请求中跳过对先前所见内容的重新计算。

提示词缓存适用于以下场景：

* 具有长且一致的系统提示词的多轮对话
* 拥有大量跨调用保持不变的工具体系定义的代理
* 基于文档的问答，用户针对同一上传上下文提出多个问题
* 具有重复静态内容的批处理工作负载

支持的模型：

* **Anthropic Claude**
* **Amazon Nova**

<Info>
  了解更多关于 [AWS Bedrock 提示词缓存](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) 策略和限制的信息。缓存内容必须超过 1,024 个令牌，缓存检查点才会生效，具体取决于模型有时可能更多。请参阅 [支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。
</Info>

**API 参考：** [`BedrockPromptCachingMiddleware`](https://reference.langchain.com/python/langchain-aws/middleware/prompt_caching/BedrockPromptCachingMiddleware)

```python ChatBedrockConverse theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_aws import ChatBedrockConverse
from langchain_aws.middleware.prompt_caching import BedrockPromptCachingMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-5-20250929-v1:0"),
    system_prompt="<Your long system prompt here>",
    middleware=[BedrockPromptCachingMiddleware(ttl="1h")], # [!code highlight]
)
```

```python ChatBedrock theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_aws import ChatBedrock
from langchain_aws.middleware.prompt_caching import BedrockPromptCachingMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatBedrock(model="us.anthropic.claude-sonnet-4-5-20250929-v1:0"),
    system_prompt="<Your long system prompt here>",
    middleware=[BedrockPromptCachingMiddleware(ttl="5m")], # [!code highlight]
)
```

<Accordion title="配置选项">
  <ParamField body="type" type="string" default="ephemeral">
    缓存类型。对于 `ChatBedrock`，目前仅支持 `'ephemeral'`。对于 `ChatBedrockConverse`，此值被忽略，因为 Converse API 始终使用 `"default"` 缓存类型。
  </ParamField>

  <ParamField body="ttl" type="string" default="5m">
    缓存内容的生存时间。有效值：`'5m'` 或 `'1h'`。请注意，Amazon Nova 模型仅支持 `'5m'`。
  </ParamField>

  <ParamField body="min_messages_to_cache" type="number" default="0">
    开始缓存前的最小消息数量。
  </ParamField>

  <ParamField body="unsupported_model_behavior" type="string" default="warn">
    使用不支持的模型时的行为。选项：`'ignore'`, `'warn'`, 或 `'raise'`。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  该中间件会缓存每个请求中直到并包括最新消息的内容。在 TTL 窗口内（5 分钟或 1 小时）的后续请求中，先前看到的内容将从缓存中检索而不是重新处理，从而降低成本和延迟。

  **工作原理：**

  1. 首次请求：系统提示词、工具和用户消息被发送到 API 并缓存
  2. 第二次请求：从缓存中检索缓存的内容。只需处理新消息
  3. 此模式在每个回合继续，每个请求重用缓存的对话历史

  <Note>
    提示词缓存通过缓存令牌来降低 API 成本，但**不**提供对话记忆。要在跨调用中持久化对话历史，请使用类似 `MemorySaver` 的 [检查点器](https://langchain-ai.github.io/langgraph/concepts/persistence/#checkpointer-libraries)。
  </Note>

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain_aws import ChatBedrockConverse
  from langchain_aws.middleware.prompt_caching import BedrockPromptCachingMiddleware
  from langchain.agents import create_agent
  from langchain_core.runnables import RunnableConfig
  from langchain.messages import HumanMessage
  from langchain.tools import tool
  from langgraph.checkpoint.memory import MemorySaver


  @tool
  def get_weather(city: str) -> str:
      """Get the current weather for a city."""
      return f"The weather in {city} is sunny and 72F."


  # System prompt must exceed 1,024 tokens for caching to take effect
  LONG_PROMPT = (
      "You are a helpful weather assistant with deep expertise in meteorology, "
      "climate science, and atmospheric phenomena. When answering questions about "
      "weather, provide accurate and up-to-date information. "
      + "You should always strive to give the most helpful response possible. " * 85
  )

  agent = create_agent(
      model=ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-5-20250929-v1:0"),
      system_prompt=LONG_PROMPT,
      tools=[get_weather],
      middleware=[BedrockPromptCachingMiddleware(ttl="5m")], # [!code highlight]
      checkpointer=MemorySaver(),  # Persists conversation history
  )

  # Use a thread_id to maintain conversation state
  config: RunnableConfig = {"configurable": {"thread_id": "user-123"}}

  # First invocation: Creates cache with system prompt, tools, and user message
  response = agent.invoke(
      {"messages": [HumanMessage("What is the weather in Miami?")]}, config=config
  )

  last_msg = response["messages"][-1]
  print(last_msg.content)

  # Check cache token usage
  um = last_msg.usage_metadata
  if um:
      details = um.get("input_token_details", {})
      cache_read = details.get("cache_read", 0) or 0
      cache_write = details.get("cache_creation", 0) or 0
      print(f"Cache read: {cache_read}, Cache write: {cache_write}")

  # Second invocation: Reuses cached system prompt, tools, and previous messages
  response = agent.invoke(
      {"messages": [HumanMessage("How about Seattle?")]}, config=config
  )
  print(response["messages"][-1].content)
  ```
</Accordion>

### 特定于模型的行为

该中间件会自动处理 API 和模型系列之间的差异：

| 功能            | ChatBedrockConverse (Anthropic) | ChatBedrockConverse (Nova) | ChatBedrock (Anthropic) |
| ------------- | :-----------------------------: | :------------------------: | :---------------------: |
| 系统提示词缓存       |                ✅                |              ✅             |            ✅            |
| 工具定义缓存        |                ✅                |              ❌             |            ✅            |
| 消息缓存          |                ✅                |        ✅ (排除工具结果消息)        |            ✅            |
| 扩展 TTL (`1h`) |                ✅                |              ❌             |            ✅            |

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\python\integrations\middleware\aws.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>