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

# 使用代理程式擷取來查詢知識庫
<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. **規劃** – 基礎模型會分析您的查詢，並建立計劃將其分解為一或多個子查詢。每個子查詢都會以您設定的特定擷取器為目標。收集擷取結果後，基礎模型會評估它們是否足以回答原始查詢。如果沒有，它會規劃並執行額外的擷取反覆運算，直到設定的最大值為止。

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)請求。回應是包含擷取結果和追蹤事件的串流。

下表說明金鑰請求欄位：


**必要欄位**  

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


**選填欄位**  

| 欄位 | 說明 | 
| --- | --- | 
| policyConfiguration | 設定要在代理程式擷取期間套用的 Amazon Bedrock 護欄。指定 guardrailId和 guardrailVersion。 | 
| userContext | 提供存取控制篩選的使用者內容。 | 
| generateResponse | 布林值欄位，當設定為 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 登入資料會用來叫用這些模型。