本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 受管知識庫的可觀測性 對於受管知識庫，Amazon Bedrock 會將操作指標和擷取日誌發佈到 AWS 您的帳戶，以便您可以監控知識庫的運作狀態和使用情況。執行時間指標可讓您追蹤知識庫 API 操作的請求量、錯誤和限流，而擷取日誌可讓您在資料擷取任務期間追蹤個別文件的狀態。下列各節說明可用的可觀測性資料，以及如何存取資料。 ## 受管知識庫的執行期指標 Amazon Bedrock 會將知識庫 API 操作的執行時間指標發佈至 `AWS/Bedrock/KnowledgeBases` 命名空間下的 Amazon CloudWatch。使用這些指標來監控 等操作的調用量、錯誤率和限流`Retrieve`。指標會免費發佈至您的帳戶，並顯示在 CloudWatch 主控台中。 下表說明 Amazon Bedrock 為受管知識庫發佈的執行期指標。 | 指標名稱 | 單位 | 說明 | | --- | --- | --- | | 調用 | 計數 | 對知識庫操作的請求數量。此指標會針對每個請求發佈，包括導致錯誤的請求。 | | ClientErrors | 計數 | 導致用戶端錯誤 （限流以外的 HTTP `4xx`回應） 的請求數量。 | | ServerErrors | 計數 | 導致伺服器端錯誤 (HTTP `5xx`回應） 的請求數量。 | | 限流 | 計數 | 已調節的請求數目 (HTTP `429`回應）。調節請求不會計為 `ClientErrors`或 `ServerErrors`。 | `ClientErrors`只有在發生對應的條件時，才會發佈 `ServerErrors`、 和 `Throttles`指標。`Invocations` 指標會針對每個請求發佈。 ### AgenticRetrieveStream 操作的其他指標 除了上表中的指標之外， `AgenticRetrieveStream`操作還會發佈下列指標。 | 指標名稱 | 單位 | 說明 | | --- | --- | --- | | TotalIterationCount | 計數 | 在請求期間執行的代理程式擷取反覆運算總數。當請求成功完成時，此指標只會針對 `AgenticRetrieveStream`操作發佈。 | 此指標使用值為 的`Operation`維度`AgenticRetrieveStream`。 ### 受管知識庫指標的維度 Amazon Bedrock 將下列維度用於受管知識庫執行期指標。 | 維度 | 說明 | | --- | --- | | 作業 | 發佈指標的知識庫 API 操作。可能值為 `Retrieve` 和 `AgenticRetrieveStream`。 | | KnowledgeBaseId | 請求目標的知識庫，格式為 `knowledge-base/{{knowledge-base-id}}`。此維度包含於以單一知識庫為目標的 `Retrieve`操作。並非以單一知識庫為目標的操作只會以 `Operation`維度發佈。 | ### 發佈指標的許可 Amazon Bedrock 會使用與請求相關聯的登入資料，將這些指標發佈至您的帳戶： + 對於 `Retrieve`操作，Amazon Bedrock 會使用知識庫服務角色。 + 對於其他操作，Amazon Bedrock 透過轉送存取工作階段使用呼叫身分的登入資料 （呼叫操作的 IAM 使用者或角色）。 若要發佈指標，必須允許該身分呼叫 `cloudwatch:PutMetricData` 做為`AWS/Bedrock/KnowledgeBases`命名空間。將授予此許可的政策連接到知識庫服務角色，以及呼叫知識庫操作的任何身分。下列範例會授予所需的許可。 ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "cloudwatch:PutMetricData", "Resource": "*", "Condition": { "StringEquals": { "cloudwatch:namespace": "AWS/Bedrock/KnowledgeBases" } } } ] } ``` 指標發佈是最佳作法。如果身分沒有必要的許可，則不會發佈對應的指標，但知識庫請求本身不會受到影響。 ### 檢視執行時間指標 您可以使用 AWS CLI AWS 管理主控台、 或 CloudWatch API 取得知識庫的指標。您可以透過其中一個 AWS 軟體開發套件 (SDKs) 或 CloudWatch API 工具來使用 CloudWatch API。 若要在 CloudWatch 主控台中檢視受管知識庫指標，請前往導覽窗格中的指標區段，然後選取所有指標選項，然後搜尋`AWS/Bedrock/KnowledgeBases`命名空間。 您必須擁有適當的 CloudWatch 許可，才能使用 CloudWatch 監控您的知識庫。如需詳細資訊，請參閱《[Amazon CloudWatch 使用者指南》中的 Amazon CloudWatch 的身分驗證和存取控制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html)。 *Amazon CloudWatch * ## 受管知識庫的儲存指標 對於受管知識庫，Amazon Bedrock 會在`AWS/Bedrock/KnowledgeBases`命名空間下將儲存指標發佈至 Amazon CloudWatch。此指標會報告存放在知識庫中的來源資料的總原始大小，並在資料擷取任務完成後發佈至您的帳戶，以便您可以追蹤一段時間內存放在知識庫中的資料量。 下表說明 Amazon Bedrock 為受管知識庫發佈的儲存指標。 | 指標名稱 | 單位 | 說明 | | --- | --- | --- | | RawDataSize | GB | 存放在知識庫中來源資料的總原始大小，以 GB 為單位。此指標會在資料擷取任務完成後發佈。 | 儲存指標使用 `KnowledgeBaseId`維度，格式為 `knowledge-base/{{knowledge-base-id}}`。 ## 受管知識庫的擷取可觀測性 Amazon Bedrock 會發出日誌，追蹤受管知識庫的資料擷取任務進度，包括整體任務狀態和處理的每個文件狀態。您可以使用這些日誌來確認擷取哪些文件、調查擷取結果中未傳回文件的原因，以及對擷取失敗進行疑難排解。 日誌會傳送到您設定的目的地 (CloudWatch Logs、Amazon S3 或 Amazon Data Firehose)。下列各節說明如何啟用日誌交付、擷取期間文件的生命週期、發出的日誌類型，以及範例查詢。 ### 啟用擷取日誌交付 若要接收擷取日誌，請使用 AWS 管理主控台 或 CloudWatch API 為您的知識庫設定日誌交付。您可以將日誌交付至 CloudWatch Logs、Amazon S3 或 Amazon Data Firehose。 #### 使用主控台啟用日誌交付 1. **開啟您的知識庫**：在 Amazon Bedrock 主控台中，開啟您要監控的受管知識庫。 1. **新增日誌交付**：編輯知識庫以新增日誌交付，並設定下列詳細資訊： + 記錄目的地 (CloudWatch Logs、Amazon S3 或 Amazon Data Firehose)。 + (CloudWatch Logs) 日誌群組名稱。 + (Amazon S3) 儲存貯體名稱。 + (Amazon Data Firehose) Firehose 串流。 1. **確認交付狀態**：確認日誌交付狀態在主控台中為*交付作用中*。 #### 使用 CloudWatch API 啟用日誌交付 1. **取得知識庫的 ARN**：呼叫 [GetKnowledgeBase](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetKnowledgeBase.html) API 以取得知識庫的 Amazon Resource Name (ARN)。知識庫 ARN 的格式如下：{{arn：aws：bedrock：your-region：your-account-id：knowledge-base/knowledge-base-id}}。 1. **呼叫 `PutDeliverySource`**：使用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html) API 為知識庫建立交付來源。傳遞知識庫 ARN 做為 ，`resourceArn`並指定 `APPLICATION_LOGS`做為 `logType`。 ``` { "logType": "APPLICATION_LOGS", "name": "my-knowledge-base-delivery-source", "resourceArn": "arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge_base_id" } ``` 1. **呼叫 `PutDeliveryDestination`**：使用 [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html) API 來設定日誌存放的位置。指定 CloudWatch Logs、Amazon S3 或 Amazon Data Firehose 目的地的 ARN。您可以將 `outputFormat`設定為 `json`、`plain`、`raw`、 `w3c`或 `parquet`。 ``` { "deliveryDestinationConfiguration": { "destinationResourceArn": "arn:aws:s3:::bucket-name" }, "name": "my-knowledge-base-delivery-destination", "outputFormat": "json" } ``` 如果您要將日誌交付至不同的帳戶，請使用 `PutDeliveryDestinationPolicy` API 將 AWS Identity and Access Management (IAM) 政策連接至目的地帳戶。 1. **呼叫 `CreateDelivery`**：使用 [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html) API 將交付來源連結至交付目的地。 ``` { "deliveryDestinationArn": "string", "deliverySourceName": "my-knowledge-base-delivery-source" } ``` #### 支援的日誌類型和許可 受管知識庫支援下列日誌類型： + `APPLICATION_LOGS`：追蹤擷取任務狀態的日誌，以及在任務期間處理的每個文件。 + `TRACES`：執行時間操作的分散式追蹤 （跨度）。追蹤只會針對 `Retrieve`操作發出，並傳送到 AWS X-Ray。如需詳細資訊，請參閱[受管知識庫的追蹤可觀測性](#kb-managed-observability-traces)。 若要啟用日誌交付，使用者或角色除了寫入所選目的地所需的`bedrock:AllowVendedLogDeliveryForResource`許可之外，還必須具有知識庫資源的許可。如需每個目的地的 IAM 政策範例，請參閱《*Amazon CloudWatch Logs 使用者指南》中的*[不同交付目的地的已終止日誌許可](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2)。 ### 擷取期間的文件生命週期 在資料擷取任務期間，每個文件會經過三個階段，而文件的日誌會記錄每個階段的狀態： + **爬取** (`crawl_status`)：Amazon Bedrock 會從資料來源擷取文件，並判斷文件是否必須新增、更新或刪除。`crawl_action` 欄位設定為 `ADD`、 `DELETE`或 `UNMODIFIED`。在其餘階段`UNMODIFIED`略過的文件。 + **同步** (`sync_status`)：將文件提交至知識庫進行處理。 + **索引** (`index_status`)：文件已區塊化、內嵌並保留在知識庫中。`chunk_statistics` 欄位摘要說明已建立或刪除的區塊。 每個階段狀態為 `SUCCESS`或 `FAILED`。`connector_document_status` 欄位會報告文件的合併狀態，且只有在文件無法處理時才會填入`error_message`欄位。 ### 日誌類型和範例 Amazon Bedrock 會針對受管知識庫擷取任務發出兩種類型的日誌項目，並以 `event_type` 欄位區分： + `StartIngestionJob.StatusChanged` – 記錄整體擷取任務進度的任務層級日誌，例如爬取開始和完成的時間。`message` 欄位包含人類可讀取狀態，例如 `Crawling started`或 `Crawling completed`。 + `StartIngestionJob.ResourceStatusChanged` – 記錄個別文件處理狀態的文件層級日誌。 以下是任務層級狀態日誌的範例。 ``` { "event_timestamp": 1718677300000, "event": { "ingestion_job_id": "", "data_source_id": "", "knowledge_base_arn": "arn:aws:bedrock:::knowledge-base/", "message": "Crawling started" }, "event_version": "1.0", "event_type": "StartIngestionJob.StatusChanged", "level": "INFO" } ``` 以下是記錄單一文件處理狀態的文件層級日誌範例。 ``` { "event_timestamp": 1718677342332, "event": { "ingestion_job_id": "", "data_source_id": "", "knowledge_base_arn": "arn:aws:bedrock:::knowledge-base/", "document_id": "", "source_uri": "", "content_type": "", "crawl_action": "ADD" | "DELETE" | "UNMODIFIED", "index_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "crawl_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "sync_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "chunk_statistics": { "created": int, "deleted": int, "failed_to_create": int, "failed_to_delete": int }, "error_message": "" }, "event_version": "1.0", "event_type": "StartIngestionJob.ResourceStatusChanged", "level": "INFO" | "ERROR" } ``` 只有當文件無法處理時， `error_message` 欄位才會出現。`chunk_statistics` 欄位摘要說明為文件建立或刪除的區塊。 有些文件層級日誌會報告連接器狀態訊息，而不是上述顯示的狀態欄位。這些日誌包含具有人類可讀描述`message`的欄位 （例如，指出無法擷取或刪除文件的訊息），以及 `INFO`、 `WARN`或 `level`的 `ERROR`。 ### 查詢範例 如果您將日誌交付至 CloudWatch Logs，您可以使用 CloudWatch Logs Insights 來查詢知識庫的擷取日誌。以下是一些常見的查詢。 + 列出擷取期間無法處理的所有文件，以及其錯誤訊息。 `filter event.connector_document_status.Status = "FAILED" | fields event.document_id, event.source_uri, event.error_message, @timestamp | sort @timestamp desc` + 依來源位置尋找特定文件的所有日誌項目。 `filter event.source_uri = "s3:///" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc` + 列出由特定擷取任務處理的所有文件。 `filter event.ingestion_job_id = "" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc` + 檢視擷取任務的整體進度，包括爬取開始和完成的時間。 `filter event_type = "StartIngestionJob.StatusChanged" | fields event.message, @timestamp | sort @timestamp asc` ## 受管知識庫的追蹤可觀測性 Amazon Bedrock 可以發出知識庫執行期操作的分散式追蹤 （跨度），以便您可以分析請求延遲和請求的內部步驟。追蹤只會針對 `Retrieve`操作發出，並傳送到 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)。追蹤交付使用與擷取日誌相同的付費日誌交付管道，其中包含`TRACES`日誌類型和 X-Ray 交付目的地。 ### 使用 CloudWatch API 啟用追蹤交付 若要將追蹤交付至 AWS X-Ray，請依照下列步驟使用 CloudWatch API 建立交付。 1. **呼叫 `PutDeliverySource`**：使用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html) API 為知識庫建立交付來源。傳遞知識庫 ARN 做為 ，`resourceArn`並指定 `TRACES`做為 `logType`。 1. **呼叫 `PutDeliveryDestination`**：搭配 `deliveryDestinationType`的 使用 [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html) API`XRAY`。X-Ray 是受管目的地，因此您不會指定 `destinationResourceArn`。請注意回應中傳回的 ARN。 1. **呼叫 `CreateDelivery`**：使用 [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html) API 將交付來源名稱連結至 X-Ray 交付目的地 ARN。 **注意** 這些 API 呼叫是等冪的。如果資源已存在，您可以安全地忽略 `ConflictException`或 `ResourceAlreadyExistsException`。 ### 追蹤交付的許可 若要啟用追蹤交付，除了交付至 AWS X-Ray 所需的`bedrock:AllowVendedLogDeliveryForResource`許可之外，使用者或角色還必須具有知識庫資源的許可。 ### 檢視追蹤 啟用追蹤交付後，請呼叫 `Retrieve`操作來產生追蹤，然後在 AWS X-Ray 主控台中檢視它們。 ## 受管知識庫的 AgentCore 可觀測性 Amazon Bedrock 將受管知識庫可觀測性資料與 Amazon Bedrock AgentCore 可觀測性體驗整合，讓您合併檢視知識庫指標和追蹤與其他 AgentCore 遙測。 此整合不需要額外的組態。如前幾節所述啟用執行時間指標和追蹤交付後，AgentCore 可觀測性頁面會自動填入對應的知識庫資料。無需採取額外的動作。 **注意** AgentCore 可觀測性整合僅適用於受管知識庫。 ## 客戶支援和故障診斷 Amazon Bedrock 受管知識庫會暫時存放客戶查詢和相關聯的擷取資料，僅用於提供偵錯支援，以回應客戶報告的問題。除非客戶在支援參與期間明確同意，否則 AWS 不會存取此資料。Amazon Bedrock 不會使用此資料來訓練或改善基礎模型。