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

# ChatBedrock 集成

> 使用 LangChain Python 集成 ChatBedrock 对话模型。

本文档将帮助您开始使用 AWS Bedrock [对话模型](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md)。Amazon Bedrock 是一个完全托管的服务，通过单个 API 提供来自 AI21 Labs、Anthropic、Cohere、Meta、Stability AI 和 Amazon 等领先 AI 公司的高性能基础模型（FMs），以及构建生成式 AI 应用所需的一系列广泛功能，同时确保安全性、隐私和负责任的 AI。使用 Amazon Bedrock，您可以轻松地实验和评估适用于您用例的顶级 FMs，使用微调和检索增强生成（RAG）等技术以私有方式使用您的数据对其进行定制，并构建使用您的企业系统和数据源执行任务的智能体。由于 Amazon Bedrock 是无服务器的，您无需管理任何基础设施，并且可以使用您已经熟悉的 AWS 服务将生成式 AI 功能安全地集成和部署到您的应用程序中。

AWS Bedrock 维护一个 [Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)，它为 Bedrock 模型提供了一个统一的对话界面。此 API 目前不支持自定义模型。您可以在 [此处查看所有支持的模型列表](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html)。

> [!NOTE]
>
> **我们推荐使用 Converse API 给不需要使用自定义模型的用户。它可以通过 [`ChatBedrockConverse`](https://reference.langchain.com/python/langchain-aws/chat_models/bedrock_converse/ChatBedrockConverse) 访问。**

> [!NOTE]
>
> **Bedrock 上的 Anthropic 模型**
>
> 对于 Anthropic 模型，您可以使用 `ChatAnthropicBedrock`，它扩展了 `ChatAnthropic`，并在 AWS Bedrock 上运行，提供相同的 API。有关详细信息，请参阅下文 [ChatAnthropicBedrock 部分](#chatanthropicbedrock)。

有关所有 Bedrock 功能和配置的详细文档，请访问 [API 参考](https://reference.langchain.com/python/langchain-aws/chat_models/bedrock_converse/ChatBedrockConverse)。

## 概述

### 集成细节

| 类 | 包 | 可序列化 | [JS 支持](https://langchain-docs-zh.mintlify.site/langchain/oss/javascript/integrations/chat/bedrock_converse.md) | 下载 | 版本 |
| :- | :- | :-: | :-: | :-: | :-: |
| [`ChatBedrock`](https://reference.langchain.com/python/langchain-aws/chat_models/bedrock/ChatBedrock) | [`langchain-aws`](https://reference.langchain.com/python/langchain-aws) | beta | ✅ | ![PyPI - 下载](https://img.shields.io/pypi/dm/langchain-aws?style=flat-square\&label=%20) | ![PyPI - 版本](https://img.shields.io/pypi/v/langchain-aws?style=flat-square\&label=%20) |
| [`ChatBedrockConverse`](https://reference.langchain.com/python/langchain-aws/chat_models/bedrock_converse/ChatBedrockConverse) | [`langchain-aws`](https://reference.langchain.com/python/langchain-aws) | beta | ✅ | ![PyPI - 下载](https://img.shields.io/pypi/dm/langchain-aws?style=flat-square\&label=%20) | ![PyPI - 版本](https://img.shields.io/pypi/v/langchain-aws?style=flat-square\&label=%20) |

### 模型功能

下文适用于 `ChatBedrock` 和 `ChatBedrockConverse`。

| [工具调用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md) | [结构化输出](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/structured-output.md) | [图像输入](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#多模态) | 音频输入 | 视频输入 | [Token 级流式输出](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/streaming.md) | 原生异步 | [Token 使用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md#token-使用) | [Logprobs](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md#对数概率) |
| :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ |

## 设置

要访问 Bedrock 模型，您需要创建一个 AWS 账户，设置 Bedrock API 服务，获取访问密钥 ID 和密钥，并安装 `langchain-aws` 集成包。

### 凭证

前往 [AWS 文档](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html) 注册 AWS 并设置您的凭证。

或者，`ChatBedrockConverse` 默认会从以下环境变量中读取：

```python theme={null}
# os.environ["AWS_ACCESS_KEY_ID"] = "..."
# os.environ["AWS_SECRET_ACCESS_KEY"] = "..."

# Not required unless using temporary credentials.
# os.environ["AWS_SESSION_TOKEN"] = "..."
```

您还需要为您的账户开启模型访问权限，您可以通过 [这些说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) 来完成。

要启用对模型调用的自动跟踪，请设置您的 [LangSmith](https://docs.langchain.com/langsmith/observability) API 密钥：

```python theme={null}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"
```

### 安装

LangChain Bedrock 集成位于 `langchain-aws` 包中：

```python theme={null}
pip install -qU langchain-aws
```

## 实例化

现在我们可以实例化我们的模型对象并生成对话完成：

```python theme={null}
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(
    model_id="us.anthropic.claude-sonnet-4-6",
    # region_name=...,
    # aws_access_key_id=...,
    # aws_secret_access_key=...,
    # aws_session_token=...,
    # temperature=...,
    # max_tokens=...,
    # other params...
)
```

## 调用

```python theme={null}
messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = llm.invoke(messages)
ai_msg
```

```text theme={null}
AIMessage(content="J'adore la programmation.", additional_kwargs={}, response_metadata={'ResponseMetadata': {'RequestId': 'b07d1630-06f2-44b1-82bf-e82538dd2215', 'HTTPStatusCode': 200, 'HTTPHeaders': {'date': 'Wed, 16 Apr 2025 19:35:34 GMT', 'content-type': 'application/json', 'content-length': '206', 'connection': 'keep-alive', 'x-amzn-requestid': 'b07d1630-06f2-44b1-82bf-e82538dd2215'}, 'RetryAttempts': 0}, 'stopReason': 'end_turn', 'metrics': {'latencyMs': [488]}, 'model_name': 'us.anthropic.claude-sonnet-4-6'}, id='run-d09ed928-146a-4336-b1fd-b63c9e623494-0', usage_metadata={'input_tokens': 29, 'output_tokens': 11, 'total_tokens': 40, 'input_token_details': {'cache_creation': 0, 'cache_read': 0}})
```

```python theme={null}
print(ai_msg.content)
```

```text theme={null}
J'adore la programmation.
```

### 流式输出

使用 `stream_events` 直接流式传输 Token：

```python theme={null}
stream = llm.stream_events(messages, version="v3")
for token in stream.text:
    print(token, end="|")
```

```text theme={null}
J|'adore la| programmation.|
```

### 流式传输工具调用和结构化输出

在使用 [工具调用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md) 或 [结构化输出](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/structured-output.md) 与 Anthropic 模型时，工具调用参数默认按部分 JSON 块流式传输。

要减少延迟并获取更均匀分布的块，您可以启用 Anthropic 的细粒度工具流式传输 Beta 版：

```python theme={null}
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(
    model_id="us.anthropic.claude-sonnet-4-5-20250514-v1:0",
    additional_model_request_fields={
        "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"]
    }
)
```

> [!NOTE]
>
> 细粒度工具流式传输支持 Claude 4.5+ 模型。有关更多详细信息，请参阅 [Claude 文档](https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)。

> [!WARNING]
>
> 在使用细粒度工具流式传输时，您可能会收到无效或部分的 JSON 输入。请确保在您的代码中考虑这些边缘情况。

## 扩展思考

本指南重点介绍如何使用 AWS Bedrock 和 LangChain 的 `ChatBedrockConverse` 集成实现扩展思考。

### 支持的模型

扩展思考适用于 AWS Bedrock 上的以下 Claude 模型：

| 模型 | 模型 ID |
| - | - |
| **Claude Opus 4** | `anthropic.claude-opus-4-20250514-v1:0` |
| **Claude Sonnet 4** | `anthropic.claude-sonnet-4-20250514-v1:0` |
| **Claude 3.7 Sonnet** | `us.anthropic.claude-3-7-sonnet-20250219-v1:0` |

```python theme={null}
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(
    model_id="us.anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    max_tokens=4096,
    additional_model_request_fields={
        "thinking": {"type": "enabled", "budget_tokens": 1024},
    },
)

ai_msg = llm.invoke(messages)
ai_msg.content_blocks
```

```text theme={null}
[{'type': 'reasoning',
  'reasoning': 'The user wants me to translate "I love programming" from English to French.\n\n"I love" translates to "J\'aime" in French.\n"Programming" translates to "la programmation" in French.\n\nSo the full translation would be "J\'aime la programmation."',
  'extras': {'signature': 'EpkDCkgIBxABGAIqQGI0KGz8LoVaFwqSAYPN7N+FecI1ZGtb0zpfPr5F8Sb1yxtQHQlmbKUS8JByenWCFGpRKigNaQh1+rLZ59GEX/sSDB+6gxZAT24DJrq4pxoMySVhzwALI6FEC+1UIjDcozOIznjRTYlDWPcYUNYvpt8rwF9IHE38Ha2uqVY8ROJa1tjOMk3OEnbSoV13Pa8q/gETsz+1UwxNX5tgxOa+38jLEryhdFyyAk2JDLrmluZBM6TMrtyzALQvVbZqjpkKAXdtcVCrsz8zUo/LZT1B/92Ukux2dE0O1ZOdcW3tORK+NFLSBaWuqigcFUTDH9XNQoHd2WpQNhl+ypnCItbL2wDRscN/tEBkgGMQugvPmL0LAuLKBmsRKStKRi/RMYGJb3Ft2yEDsRnYNJBJ6TtgxXFvjDwqc/UaI9cIcTxdoVVlsPFsYccpVwirzwAOiz6CSQ1oOQTYJVT90eQ71QW74n1ubbFIZAvDBKk0KG8jK1FGx4FpuuZyFhBpXtfrgOCdrlVSAO/EE9fKCbP9FlhPbRgB'}},
 {'type': 'text', 'text': "J'aime la programmation."}]
```

### 扩展思考的工作原理

当启用扩展思考时，Claude 会创建思考内容块，在其中输出其内部推理。Claude 会结合这些推理中的见解，然后再构建最终响应。API 响应将包括思考内容块，然后是文本内容块。

```python theme={null}
next_messages = messages + [("ai", ai_msg.content), ("human", "I love AI")]

ai_msg = llm.invoke(next_messages)
ai_msg.content_blocks
```

```text theme={null}
[{'type': 'reasoning',
  'reasoning': 'The user wants me to translate "I love AI" from English to French. \n\n"I love" translates to "J\'aime" in French.\n"AI" stands for "Artificial Intelligence" which in French is "Intelligence Artificielle" or "IA" (the French abbreviation).\n\nSo the translation would be "J\'aime l\'IA" or "J\'aime l\'intelligence artificielle".\n\nI think using the abbreviation "IA" would be more natural and concise, similar to how the user used "AI" in English.',
  'extras': {'signature': 'EuAECkgIBxABGAIqQLWbkzJ8RzfxhVN1BhfRj5+On8/M9Utt0yH9kvj9P2zlQkO5xloq6I/AiEeArwwdJeqJVcLRjqLtinh6HIBbSDwSDFwt0GL409TqjSZNBhoMPQtJdZmx/uiPrLHUIjCJXyyjgSK3vzbcSEnsvo7pdpoo+waUFrAPDCGL/CIN5u7c8ueLCuCn8W0qGGc+BNgqxQO6UbV11RnMdnUyFmVgTPJErfzBr6U6KyUHd5dJmFWIUVpbbxT2C9vawpbKMPThaRW3BhItEafWGUpPqztzFhqJpSegXtXehIn5iY4yHzTUZ5FPdkNIuAmTsFNNGxiKr9H/gqknvQ2B7I4ushRHLg+drU4cH18EGZlAo5Tu1O9yH5GbweIEew4Uv7oWje+R8TIku0OFVhrbnQqqqukBicMV2JRifUYuz6dYM1UDYS8SfxQ1MmcVY5t1L9LDpoL4F/CtpL8/6YDsB/FosU37Qc1qm+D+pKEPTYnyxaP5tRXqTBfqUIiNJGqr9Egl17Akoy6NIv234rPfuf8HjTcu5scZoPGhOreG5rWxJ7AbTCIXgGWqpcf2TqDtniOac3jW4OtnlID9fsloKNq6Y5twgXHDR47c4Jh6vWmucZiIlL6hkklQzt5To6vOnqcTOGUtuCis8Y2wRzlNGeR2d8A+ocYm7mBvR/Y5DvDgstJwB/vCLoQlIL+jm6+h8k6EX/24GqOsh5hxsS5IsNIob/p8tr4TBbc9noCoUSYkMhbQPi2xpRrNML9GUIo7Skbh1ni67uqeShj1xuUrFG+cN6x4yzDaRb59LCAYAQ=='}},
 {'type': 'text', 'text': "J'aime l'IA."}]
```

## 推理努力

> [!NOTE]
>
> `reasoning_effort` 需要 `langchain-aws>=1.7.0`。

[`ChatBedrockConverse`](https://reference.langchain.com/python/langchain-aws/chat_models/bedrock_converse/ChatBedrockConverse) 支持标准 [`reasoning_effort`](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models#推理) 参数，用于具有可配置推理的模型，包括 Claude (Opus 5, Sonnet 5)、Amazon Nova 2、以及 Bedrock 上的 OpenAI gpt-oss 和 Moonshot Kimi K2 模型。与 `temperature` 类似，它可以在模型构建时或每次调用时设置，并将其转换为底层模型系列的请求格式：

```python theme={null}
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(
    model="us.anthropic.claude-sonnet-5",
    region_name="us-west-2",
    reasoning_effort="high",
)

response = llm.invoke("What is the cube root of 50.653?")
```

支持的努力级别因模型而异。检查模型的 [配置文件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/models.md#模型配置文件) 以了解它支持的级别：

```python theme={null}
llm.profile["reasoning_effort_levels"]  # e.g. ['low', 'medium', 'high', 'xhigh', 'max']
```

显式的 `additional_model_request_fields` 值优先于从 `reasoning_effort` 派生的字段。没有已知翻译的模型会忽略 `reasoning_effort` 并发出警告。

## 提示词缓存

Bedrock 支持 [缓存](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) 您提示词的元素，包括消息和工具。这允许您重用大型文档、指令、[少样本文档](https://docs.langchain.com/langsmith/create-few-shot-evaluators) 和其他数据，以减少延迟和成本。

> [!NOTE]
>
> **并非所有模型都支持提示词缓存。请参阅 [Bedrock 提示词缓存支持的模型](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。**

> [!NOTE]
>
> 对于 LangChain 智能体，使用 [`BedrockPromptCachingMiddleware`](https://langchain-docs-zh.mintlify.site/langchain/oss/python/integrations/middleware/aws#提示词缓存) 让 LangChain 优化稳定的系统提示词和工具内容。对于直接模型调用，根据模型和 API 使用手动 `cachePoint` 块或调用级别的 `cache_control`，具体取决于模型和 API。

要启用提示词元素的缓存，请使用 `cachePoint` 键标记其关联的内容块。下方为示例：

```python theme={null}
import requests
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-6")

# Pull LangChain readme
get_response = requests.get(
    "https://raw.githubusercontent.com/langchain-ai/langchain/b476fdb54aa6e6f5f0b24a68c2f4a94e43b369f9/README.md"
)
readme = get_response.text

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's LangChain, according to its README?",
            },
            {
                "type": "text",
                "text": f"{readme}",
            },
            {
                "cachePoint": {"type": "default"},
            },
        ],
    },
]

response_1 = llm.invoke(messages)
response_2 = llm.invoke(messages)

usage_1 = response_1.usage_metadata["input_token_details"]
usage_2 = response_2.usage_metadata["input_token_details"]

print(f"First invocation:\n{usage_1}")
print(f"\nSecond:\n{usage_2}")
```

```python theme={null}
First invocation:
{'cache_creation': 1528, 'cache_read': 0}

Second:
{'cache_creation': 0, 'cache_read': 1528}
```

## 引用

如果输入文档启用了引用生成功能，则可以生成引用。文档可以使用 Bedrock 的 [原生格式](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html) 或 LangChain 的 [标准类型](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#多模态) 指定：

```python Bedrock format theme={null}
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-20250514-v1:0")

pdf_path = "path/to/your/file.pdf"

with open(pdf_path, "rb") as f:
    pdf_bytes = f.read()

document = {
    "document": {
        "format": "pdf",
        "source": {"bytes": pdf_bytes},
        "name": "my-pdf",
        "citations": {"enabled": True},  # [!code highlight]
    },
}

response = llm.invoke(
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this document."},
                document,
            ]
        },
    ]
)
response.content_blocks
```

```python LangChain standard format theme={null}
import base64
from langchain_aws import ChatBedrockConverse

llm = ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-20250514-v1:0")

pdf_path = "path/to/your/file.pdf"

with open(pdf_path, "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

document = {
    "type": "file",
    "mime_type": "application/pdf",
    "base64": pdf_base64,
    "name": "my-pdf",  # Converse requires a filename
    "citations": {"enabled": True},  # [!code highlight]
}

response = llm.invoke(
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this document."},
                document,
            ]
        },
    ]
)
response.content_blocks
```

***

## ChatAnthropicBedrock

针对特别关注 Anthropic 模型的 AWS Bedrock 用户，`langchain-aws` 提供 `ChatAnthropicBedrock`。该类扩展了 `ChatAnthropic`，并在 AWS Bedrock 基础设施上运行时提供相同的接口。这利用了 Anthropic SDK 的 [Bedrock 客户端](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock)。

### 安装

使用 `langchain-aws` 并添加 `anthropic` 扩展来获取所需的依赖项：

```bash pip theme={null}
pip install --upgrade "langchain-aws[anthropic]"
```

```bash uv theme={null}
uv add "langchain-aws[anthropic]"
```

### 使用

`ChatAnthropicBedrock` 支持与 `ChatAnthropic` 相同的功能和参数。您可以使用 AWS 特定参数初始化它：

```python theme={null}
from langchain_aws import ChatAnthropicBedrock

model = ChatAnthropicBedrock(
    model="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-west-2",
    aws_access_key_id="...",
    aws_secret_access_key="...",
    aws_session_token="...",
)
```

AWS 凭证也可以从环境变量中读取或由 boto3 自动发现：

```python theme={null}
# Set environment variables
# os.environ["AWS_ACCESS_KEY_ID"] = "..."
# os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
# os.environ["AWS_REGION"] = "..."

from langchain_aws import ChatAnthropicBedrock

model = ChatAnthropicBedrock(model="us.anthropic.claude-haiku-4-5-20251001-v1:0")
```

有关可用参数和功能的详细文档，请参阅 [`ChatAnthropic` 集成页面](https://langchain-docs-zh.mintlify.site/langchain/oss/python/integrations/chat/anthropic)。

***

## API 参考

有关所有 `ChatBedrock`、`ChatBedrockConverse` 和 `ChatAnthropicBedrock` 功能和配置的详细文档，请前往 [API 参考](https://reference.langchain.com/python/langchain-aws)。

***

> 官方原文：[src/oss/python/integrations/chat/bedrock.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/chat/bedrock.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.