本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用代理检索来查询知识库
<a name="kb-test-agentic-retrieve"></a>

代理检索使用基础模型智能地将复杂的查询分解为子查询，以迭代方式从知识库中检索相关信息，并评估检索到的结果是否足以回答原始查询。这种方法提高了复杂、多步骤问题的检索准确性，而单次检索通道可能无法完全解决这些问题。

例如，给出 *“哪本杂志是先创办的，《亚瑟杂志》还是《女性》第一本杂志？”* ，代理检索将其分解为单独的子查询，例如 *“亚瑟杂志是什么时候成立的？*” 以及 *“First for Women 是什么时候成立的？”* ，检索每个结果并评估组合结果是否足够。

## 代理检索的工作原理
<a name="kb-agentic-retrieve-how-it-works"></a>

当您向 `AgenticRetrieveStream` API 发送请求时，会发生以下过程：

1. **规划**-基础模型分析您的查询，并制定计划，将其分解为一个或多个子查询。每个子查询都以您配置的特定检索器为目标。收集检索结果后，基础模型将评估它们是否足以回答原始查询。否则，它会计划并执行额外的检索迭代，最多不超过配置的最大值。

1. **检索**-子查询是针对配置的知识库检索器执行的。每次检索都会收集结果。

1. **完整文档扩展** — 当基础模型确定需要文档的完整内容（例如，用于摘要、验证完整性或访问特定部分）时，它会调用 GetDocumentContent API 来检索完整的文档内容。

1. **响应生成**-当设置`generateResponse`为`true`（默认）时，基础模型会根据检索到的结果合成自然语言答案。答案将通过`responseEvent`活动直播回给您。

1. **结果事件** — 所有迭代中经过重复数据删除的检索结果、完整的合成自然语言答案和引文都会返回给您。为了便于观察，跟踪事件会在整个过程中流式传输。

## 先决条件
<a name="kb-agentic-retrieve-prereqs"></a>

在使用代理检索之前，必须具备以下条件：
+ 完全托管的 Amazon Bedrock 知识库。代理检索目前仅支持托管知识库。
+ 访问 Amazon Bedrock 中的基础模型，用于查询规划和评估。
+ 所需的 IAM 权限。有关更多信息，请参阅 [代理检索所需的权限](#kb-agentic-retrieve-permissions)。

## 使用代理检索功能查询知识库
<a name="kb-agentic-retrieve-api"></a>

要使用代理检索，[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)请发送请求。响应是一个包含检索结果和跟踪事件的流。

下表描述了关键请求字段：


**必填字段**  

| 字段 | 说明 | 
| --- | --- | 
| 消息 | 输入查询和对话历史记录。每条消息都包含一个content带有text值的role字段和一个字段（user或assistant）。 | 
| 寻回者 | 要从中获取数据的知识库检索器。您最多可以指定 5 个检索器，每个检索器都通过其 ID 指向托管知识库。每个检索器都可以选择包含元数据过滤器和最大数量的结果。 | 
| 代理的 RetrieveConfiguration | 代理检索配置，包括用于查询规划和评估的基础模型，以及可选的重新排序模型和最大代理迭代次数。 | 


**可选字段**  

| 字段 | 说明 | 
| --- | --- | 
| 策略配置 | 将 Amazon Bedrock 护栏配置为在代理检索期间使用。指定guardrailId和guardrailVersion。 | 
| 用户上下文 | 为访问控制筛选提供用户上下文。 | 
| 生成响应 | 一个布尔字段，当设置为true（默认）时，它指示基础模型根据检索到的结果生成自然语言答案。答案以文本块的形式流式传回并包含在结果事件中。 | 

有关完整的请求和响应语法，请参阅 API 参考[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)中的。

## 代理检索响应
<a name="kb-agentic-retrieve-response"></a>

`AgenticRetrieveStream`响应是一个包含以下事件类型的流：
+ **结果事件** (`AgenticRetrieveResultEvent`)-处理完成时传送的最终事件。包含检索结果，如果启用响应生成，则包含生成的响应。结果事件包括：
  + **检索结果** (`results`)-在所有迭代中检索到的源块。每个结果都包括内容、源检索器标识符和可选的元数据。当多个子查询检索到同一个区块时，它只会在最终结果中出现一次。
  + **生成的响应** (`generatedResponse`)-当设置`generateResponse`为`true`（默认）时，结果事件将包含一个包含以下内容的`generatedResponse`对象：
    + `answer`— 完整的合成自然语言答案文本。
    + `citations`— 一个可选列表，将答案的跨度映射到支持的检索结果。每份引文都包含：
      + `startIndex`— 被引段落在`answer`字符串中开始的字符偏移量。
      + `endIndex`— 被引段落结尾处的字符偏移量（独家——引用的文本从`startIndex`上到但不包括`endIndex`）。
      + `references`— 一个列表，其中每个参考文献都有一个`resultIndex`字段，该字段在同一结果事件上索引到`results`数组中，指示哪个检索结果支持引用的跨度。
+ **响应事件** (`AgenticRetrieveResponseEvent`)-如果设置`generateResponse`为`true`（默认），则在生成响应期间流式传输`responseEvent`事件。每个事件都包含一个`text`字段，其中包含合成自然语言答案的增量部分。
+ **跟踪事件** (`AgenticRetrieveTraceEvent`)-在代理检索过程中流式传输的事件，可提供对每个步骤的可见性。以下是跟踪事件的类型：
  + **规划**-表示基础模型正在分析查询并创建子查询。包括计划中的操作和目标检索者。
  + **检索**-表示正在对知识库执行检索。包括检索输入、输出以及任何警告或故障。
  + **推测性检索** — 在第一个计划步骤之前运行的初始检索，以减少延迟。对于单个知识库，这将使用原始用户查询来检索结果。对于多个知识库，它会执行探测搜索，以帮助将查询路由到相应的检索器。
  + **完整文档扩展**-表示代理正在检索特定文档的全部内容。包括文档 ID、源检索器和状态（InProgress、成功或失败）。

## 代理检索所需的权限
<a name="kb-agentic-retrieve-permissions"></a>

要使用该 `AgenticRetrieveStream` API，调用 IAM 的身份必须具有以下权限：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:AgenticRetrieveStream",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:GetDocumentContent"
            ],
            "Resource": "arn:aws:bedrock:{{region}}:{{account-id}}:knowledge-base/*"
        },
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModelWithResponseStream",
            "Resource": "*"
        }
    ]
}
```

如果您在代理检索中使用护栏，请添加以下权限：

```
{
    "Effect": "Allow",
    "Action": [
        "bedrock:GetGuardrail",
        "bedrock:ApplyGuardrail"
    ],
    "Resource": "*"
}
```

## 注意事项
<a name="kb-agentic-retrieve-considerations"></a>

使用代理检索时，请记住以下几点：
+ 代理检索仅支持托管的 Amazon Bedrock 知识库。
+ 有关每次请求的检索者配额、每次检索调用的结果和最大代理迭代次数的配额，请参阅。[托管知识库的服务配额](kb-managed-quotas.md)
+ 减少最大迭代次数可能会导致代理提前停止，从而可能降低复杂查询的准确性。
+ 配置护栏时，仅支持该`BLOCK`操作。代理检索不支持该`MASK`操作。
+ 客户提供并拥有代理检索期间使用的基础模型、嵌入模型和重新排序模型（如果提供）。您的 IAM 证书用于调用这些模型。