本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用代理程式擷取來查詢知識庫
<a name="kb-test-agentic-retrieve"></a>

代理程式擷取使用基礎模型，以智慧方式將複雜的查詢分解為子查詢、反覆從您的知識庫擷取相關資訊，並評估擷取的結果是否足以回答原始查詢。此方法可改善單一擷取傳遞可能無法完全解決之複雜多步驟問題的擷取準確性。

例如，假設查詢*「Arthur's magazine 或 First for women？」，*代理程式擷取會將其分解為個別的子查詢，例如*「Arthur's Gallery 何時成立？」* 和*「何時首次為女性建立？」*， 會擷取每個結果，並評估合併的結果是否足夠。

## 代理程式擷取的運作方式
<a name="kb-agentic-retrieve-how-it-works"></a>

當您傳送請求至 `AgenticRetrieveStream` API 時，會發生下列程序：

1. **工作階段歷史記錄載入** – 當您提供包含 `memoryConfiguration`的 時`sessionBinding`，Amazon Bedrock 會在代理程式開始運作之前，從 AgentCore Memory 短期記憶體還原該工作階段的先前歷史記錄。還原的歷史記錄會成為請求的對話內容。

1. **規劃** – 基礎模型會分析您的查詢，並建立計劃將其分解為一或多個子查詢。每個子查詢都以您設定的特定來源為目標，可以是知識庫擷取器或 AgentCore 記憶體長期記憶體。收集擷取結果後，基礎模型會評估它們是否足以回答原始查詢。如果沒有，它會規劃並執行額外的擷取反覆運算，直到設定的最大值為止。

1. **擷取** – 子查詢會針對設定的來源執行。系統會從每個擷取收集結果。

1. **完整文件擴展** – 當基礎模型判斷需要文件的完整內容時 （例如，用於摘要、驗證完整性或存取特定區段），它會呼叫 GetDocumentContent API 來擷取完整的文件內容。

1. **回應產生** – 當 `generateResponse` 設為 `true`（預設值） 時，基礎模型會從擷取的結果合成自然語言答案。Amazon Bedrock 會透過`responseEvent`事件將答案串流回給您。當 `sessionBinding` 設定為 且 `persistenceMode` 時`DEFAULT`，Amazon Bedrock 會保留問題和工作階段產生的答案。

1. **結果事件** – 來自所有反覆運算的重複資料刪除擷取結果、完整合成的自然語言答案和引文都會傳回給您。追蹤事件會在整個過程中串流，以提供可觀測性。

## 先決條件
<a name="kb-agentic-retrieve-prereqs"></a>

您必須先擁有下列項目，才能使用代理程式擷取：
+ 全受管 Amazon Bedrock 知識庫。代理程式擷取目前僅支援受管知識庫。
+ 存取 Amazon Bedrock 中的基礎模型，以用於查詢規劃和評估。
+ 所需的 IAM 許可。如需詳細資訊，請參閱[代理程式擷取的必要許可](#kb-agentic-retrieve-permissions)。

## 使用代理程式擷取查詢知識庫
<a name="kb-agentic-retrieve-api"></a>

若要使用代理程式擷取，請傳送 [`AgenticRetrieveStream`](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)請求。回應是包含擷取結果和追蹤事件的串流。

下表說明金鑰請求欄位：


**必要欄位**  

| 欄位 | 說明 | 
| --- | --- | 
| messages | 輸入查詢和對話歷史記錄。每個訊息都包含一個content欄位，其中包含一個text值和一個role欄位 (user 或 assistant)。 | 
| 擷取器 | 要從中擷取資料的知識庫擷取器。您最多可以指定 5 個擷取器，每個擷取器都依其 ID 指向受管知識庫。每個擷取器都可以選擇性地包含中繼資料篩選條件和最大數量的結果。 | 
| agenticRetrieveConfiguration | 代理程式擷取組態，包括用於查詢規劃和評估的基礎模型，以及選擇性的重新排名模型和代理程式反覆運算計數上限。 | 


**選填欄位**  

| 欄位 | 說明 | 
| --- | --- | 
| policyConfiguration | 設定要在代理程式擷取期間套用的 Amazon Bedrock 護欄。指定 guardrailId和 guardrailVersion。 | 
| userContext | 提供存取控制篩選的使用者內容。 | 
| memoryConfiguration | 設定要與擷取搭配使用的 AgentCore 記憶體資源。指定 memoryId，然後sessionBinding還原並繼續工作階段，retrievalConfigs讓代理程式從長期記憶體或兩者中擷取。如需詳細資訊，請參閱[使用 AgentCore 記憶體進行代理程式擷取](#kb-agentic-retrieve-memory)。 | 
| generateResponse | 布林值欄位，當設定為 true（預設值） 時，會指示基礎模型從擷取的結果產生自然語言答案。答案會串流回文字區塊，並包含在結果事件中。 | 

如需完整的請求和回應語法，請參閱 API 參考[`AgenticRetrieveStream`](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`) – 在客服人員擷取程序期間串流的事件，可提供每個步驟的可見性。以下是追蹤事件的類型：
  + **規劃** – 表示基礎模型正在分析查詢並建立子查詢。包括計劃的動作和目標來源。每個動作都是以知識庫為目標`retrieve`的動作，或是以長期記憶體為目標`memoryRetrieve`的動作，其中包括已編寫的查詢和 `memoryId`。
  + **擷取** – 表示正在針對設定的來源執行擷取。包括擷取輸入、輸出和任何警告或失敗。`retrievalMetadata` 項目會報告來源類型，`BedrockKnowledgeBase`或 `BedrockAgentCoreMemory`。
  + **推測擷取** – 在第一個規劃步驟之前執行的初始擷取，以減少延遲。對於單一知識庫，這會使用原始使用者查詢擷取結果。對於多個知識庫，這會執行探查搜尋，以協助將查詢路由到適當的擷取器。當您設定 時`retrievalConfigs`，此步驟也可以從長期記憶體擷取。
  + **完整文件擴展** – 表示代理程式正在擷取特定文件的完整內容。包括文件 ID、來源擷取器和狀態 (InProgress、成功或失敗）。
  + **工作階段歷史記錄載入** – 表示 Amazon Bedrock 在代理程式開始運作之前，正在從 AgentCore 記憶體短期記憶體還原較早工作階段的歷史記錄。

## 使用 AgentCore 記憶體進行代理程式擷取
<a name="kb-agentic-retrieve-memory"></a>

您可以授予 [Amazon Bedrock AgentCore 記憶體](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html)資源的代理程式擷取存取權。透過記憶體存取，擷取可以繼續較早的工作階段，並利用客服人員在先前工作階段中學到的內容。使用您帳戶中處於 `ACTIVE` 狀態`memoryId`的記憶體資源的 提供 `memoryConfiguration` 欄位。

記憶體是選用的。僅設定 `memoryConfiguration`的 `memoryId` 無效。當您提供 時`memoryConfiguration`，您必須至少使用下列兩種方式之一的記憶體資源：
+ **短期記憶體** (`sessionBinding`) - 還原先前工作階段的歷史記錄，以便請求繼續該工作階段，而不是啟動新的工作階段。使用 `actorId`和 識別工作階段`sessionId`。`actorId` 範圍為歷史記錄，因此一個演員的歷史記錄永遠不會為另一個演員傳回。設定 `sessionBinding` 時， `messages` 只能承載目前的查詢，且 `role`為 `user`。您無法還原工作階段，並在相同的請求`messages`中提供 中較早的對話歷史記錄。還原會載入角色為 `USER`或 的對話事件`ASSISTANT`。
+ **長期記憶體** (`retrievalConfigs`)—讓 AgentCore 記憶體從舊版工作階段中擷取的記憶體記錄可供代理程式使用。識別字`namespace`首為 的記錄，或使用 `namespacePath` 來擷取父系下的每個命名空間。您可以使用 `strategyId`和 進一步縮小結果範圍`metadataFilters`。代理程式決定是否要擷取和編寫自己的查詢。

提供與記憶體策略上設定的命名空間完全相同的命名空間，預留位置已解析。例如，如果策略定義命名空間 `/strategy/{memoryStrategyId}/actor/{actorId}`，請提供解析的值，而不是範本。如需命名空間、策略和記憶體記錄的詳細資訊，請參閱《*Amazon Bedrock AgentCore 開發人員指南*》中的[記憶體術語](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-terminology.html)。

**注意**  
您負責提供正確的 `memoryId`、 `sessionBinding`和 `retrievalConfigs`值。客服人員擷取不會驗證您提供的工作階段或命名空間是否對應到您要繼續的對話。如果您提供不正確的值，您會收到非預期的結果。

設定 `sessionBinding` 時，使用 `persistenceMode` 控制目前交換是否寫回工作階段：
+ `DEFAULT` （預設值）—將工作階段的問題和產生的答案保留為單一事件。此值`generateResponse`必須為 `true`。
+ `NONE`- 讓工作階段保持不變。使用此值讀取工作階段歷史記錄，而不新增。

下列範例會還原較早的工作階段，讓代理程式存取該演員的長期記憶體，並將交換保留回工作階段：

```
{
    "messages": [
        {
            "content": {
                "text": "What did we decide about the migration timeline?"
            },
            "role": "user"
        }
    ],
    "retrievers": [
        {
            "configuration": {
                "knowledgeBase": {
                    "knowledgeBaseId": "{{KB12345678}}"
                }
            }
        }
    ],
    "agenticRetrieveConfiguration": {
        "foundationModelType": "MANAGED",
        "rerankingModelType": "MANAGED"
    },
    "memoryConfiguration": {
        "memoryId": "{{projectAssistantMemory-1a2b3c4d5e}}",
        "sessionBinding": {
            "actorId": "{{user-123}}",
            "sessionId": "{{session-456}}"
        },
        "retrievalConfigs": [
            {
                "namespace": "{{/strategy/summarization-1a2b3c4d5e/actor/user-123}}"
            }
        ],
        "persistenceMode": "DEFAULT"
    }
}
```

回應串流會報告記憶體活動。還原會顯示為**工作階段歷史記錄負載**追蹤事件。長期記憶體傳回的記錄會顯示在來源類型為 的**擷取**追蹤事件上`BedrockAgentCoreMemory`，以擷取的步驟為準。

擷取本身的顯示方式取決於何時發生。當基礎模型選擇搜尋記憶體 （通常在持續的工作階段上） 時，擷取會顯示為**規劃**追蹤事件上的`memoryRetrieve`動作。在新的工作階段上，代理程式可以在**推測擷取期間**，在第一個規劃步驟之前擷取長期記憶體，在這種情況下不會發出`memoryRetrieve`任何動作。如需詳細資訊，請參閱[代理程式擷取回應](#kb-agentic-retrieve-response)。

## 代理程式擷取的必要許可
<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": "*"
}
```

如果您使用 AgentCore 記憶體資源進行代理程式擷取，請新增下列許可：

```
{
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetMemory",
        "bedrock-agentcore:ListEvents",
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:CreateEvent"
    ],
    "Resource": "arn:aws:bedrock-agentcore:{{region}}:{{account-id}}:memory/{{memory-id}}"
}
```

`bedrock-agentcore:ListEvents` 只有在您設定 時才需要 `sessionBinding`。只有在您設定 時才`bedrock-agentcore:RetrieveMemoryRecords`需要 `retrievalConfigs`。只有在 `persistenceMode`為 時才`bedrock-agentcore:CreateEvent`需要 `DEFAULT`。

如果使用客戶受管金鑰加密記憶體資源，請在該金鑰上新增下列許可：

```
{
    "Effect": "Allow",
    "Action": "kms:Decrypt",
    "Resource": "arn:aws:kms:{{region}}:{{account-id}}:key/{{key-id}}"
}
```

## 考量事項
<a name="kb-agentic-retrieve-considerations"></a>

使用代理程式擷取時，請記住下列事項：
+ 代理程式擷取僅支援受管 Amazon Bedrock 知識庫。
+ 如需每個請求的擷取器配額、每個擷取呼叫的結果和客服人員重複次數上限，請參閱 [受管知識庫的服務配額](kb-managed-quotas.md)。
+ 減少最大反覆運算計數可能會導致代理程式提早停止，進而降低複雜查詢的準確性。
+ 設定護欄時，僅支援 `BLOCK`動作。代理程式擷取不支援 `MASK`動作。
+ 客戶提供並擁有基礎模型、內嵌模型，以及在客服人員擷取期間使用的重新排名模型，如果提供的話。您的 IAM 登入資料會用來叫用這些模型。
+ 當您使用 AgentCore 記憶體資源時，資源必須位於與知識庫相同的 帳戶中，且必須處於 `ACTIVE` 狀態。
+ 當您設定 時`sessionBinding`， `messages` 只能使用 `role`的 承載目前的查詢`user`。您無法在相同的請求`messages`中還原工作階段並提供先前的對話歷史記錄。
+ 還原工作階段會載入角色為 `USER`或 的對話事件`ASSISTANT`。AgentCore 記憶體也接受還原不會載入的 `TOOL`和 `OTHER`角色。如需詳細資訊，請參閱《*Amazon Bedrock AgentCore API 參考*[`Conversational`](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_Conversational.html)》中的 。
+ `retrievalConfigs` 目前最多接受一個項目，每個項目最多接受 5 個`metadataFilters`表達式。
+ `persistenceMode` 的 `DEFAULT``generateResponse`必須是 `true`，因為工作階段會保留產生的答案。