View a markdown version of this page

一般架構支援 - Amazon Bedrock AgentCore
支援的慣例如何識別跨度如何擷取評估欄位組態需求

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

一般架構支援

Amazon Bedrock AgentCore Evaluations 透過兩個開放標準讀取遙測：OpenTelemetry 生成式 AI 語意慣例和 OpenInference 語意慣例。除了本節中具有自有頁面的架構之外，此服務還支援在這兩個慣例之一中發出遙測的任何代理程式。這是一般架構支援。

當您使用本節中沒有頁面的架構建置時，或當您為自訂代理程式撰寫自己的檢測時，請使用一般架構支援。設定您的檢測以發出此頁面所述的範圍名稱、範圍屬性和識別屬性，服務會使用與具名架構相同的範圍分類和欄位擷取，來識別您的範圍並擷取評估者所需的值。

由於您架構本身的資料結構尚未事先得知，因此服務會將每個值擷取為字串，而不是剖析為架構特定的結構。在如何擷取評估欄位列出的屬性中保留提示、回應和工具引數，而不是包裝在您自己的結構中，例如巢狀請求物件或自訂訊息信封，以便評估者接收乾淨的值。

主題

支援的慣例

服務會選取如何從跨度的 讀取每個跨度scope.name。將檢測的範圍名稱設定為下列其中一個字首，服務會使用相符的慣例讀取跨度：

慣例 範圍名稱字首

OpenTelemetry

opentelemetry.instrumentation.*

OpenInference

openinference.instrumentation.*

如果範圍在本節中具有自己的頁面，則服務會改用該頁面上所述的處理方式。一般架構支援適用於符合其中一個字首的所有其他範圍。

有些範圍符合 OpenTelemetry 字首，但不是 GenAI 代理程式架構。這些是傳輸和基礎設施檢測，例如 HTTP 用戶端 urllib3(httpx、urllib、、aiohttp_client)、Web 架構 (starlette、fastapi)、模型內容協定 (MCP) 檢測和 AWS SDK (botocore) 檢測，包括其 bedrock-agentcore和 bedrock-runtime範圍。服務將這些範圍排除在一般架構支援之外，因此其範圍不會產生假代理程式、工具或推論範圍。

如何識別跨度

此服務會使用其慣例的標準識別屬性，將每個跨度分類為三種類型的其中之一。在您想要評估的每個跨度上設定此屬性。其值會告知服務跨度代表什麼，而無論對話內容存放在何處，服務都會從跨度本身讀取。

範例
OpenTelemetry

服務會使用 來分類範圍gen_ai.operation.name，並在操作名稱不存在traceloop.span.kind時回復為 。

跨度類型 識別屬性

叫用代理程式

gen_ai.operation.name = invoke_agent（或 traceloop.span.kind = workflow)

執行工具

gen_ai.operation.name = execute_tool（或 traceloop.span.kind = tool)

Inference

gen_ai.operation.name = chat（或 llm.request.type = chat)
OpenInference

服務會使用 來分類跨度openinference.span.kind。

跨度類型 識別屬性

叫用代理程式

openinference.span.kind = AGENT或 CHAIN

執行工具

openinference.span.kind = TOOL

Inference

openinference.span.kind = LLM

如何擷取評估欄位

對於每個分類範圍，服務會讀取所需的值，例如使用者提示、客服人員回應，以及工具輸入和輸出。與具名架構一樣，對話內容所在的位置取決於遙測交付模式。透過分割遙測，內容會存在於相關事件記錄中。使用統一遙測，它會保留在跨度上做為屬性。如需詳細資訊，請參閱遙測設定和交付。

服務會為每個欄位嘗試多個位置，並使用第一個保留值的位置，因此您可以發出檢測已設定的任何屬性。每個擷取的值都是字串化的，而不是剖析為架構特定的結構。

OpenTelemetry 慣例

對於使用 OpenTelemetry 慣例的架構，服務會依序從下列位置讀取每個欄位：

  • 使用者提示 （叫用客服人員範圍）：從事件記錄 body.input；然後從gen_ai.task.input範圍屬性。

  • 客服人員回應 （叫用客服人員範圍）：從事件記錄 body.output；然後從gen_ai.task.output範圍屬性。如果兩者都不存在，則服務會回到第一個使用者訊息，以及從追蹤推論範圍收集的最後一個助理訊息。

  • 推論訊息 （推論範圍）：來自事件記錄 body.input.messages和 body.output.messages；然後來自 gen_ai.output.messages gen_ai.input.messages和 範圍屬性。

  • 工具名稱 （執行工具範圍）：來自 gen_ai.tool.name span 屬性，然後來自 traceloop.entity.name span 屬性。

  • 工具引數 （執行工具範圍）：來自 gen_ai.tool.call.arguments span 屬性；接著來自事件記錄 body.input；接著來自 traceloop.entity.input span 屬性。

  • 工具結果 （執行工具範圍）：來自 gen_ai.tool.call.result span 屬性；接著來自事件記錄 body.output；接著來自 traceloop.entity.output span 屬性。

  • 系統提示 （推論範圍）：來自 gen_ai.system_instructions span 屬性。

OpenInference 慣例

對於使用 OpenInference 慣例的架構，服務會依序從下列位置讀取每個欄位：

  • 使用者提示 （呼叫代理程式範圍）：來自 input.value span 屬性，然後來自事件記錄內文輸入。

  • 客服人員回應 （呼叫客服人員範圍）：來自 output.value span 屬性；然後來自事件記錄內文輸出。

  • 推論訊息 （推論範圍）：來自範圍的 OpenInference 訊息屬性 （例如 llm.input_messages.*和 llm.output_messages.*)；接著來自 input.value和 output.value；接著來自事件記錄內文。

  • 工具引數 （執行工具範圍）：來自 input.value span 屬性，然後來自事件記錄內文輸入。

  • 工具結果 （執行工具範圍）：來自 output.value span 屬性，然後來自事件記錄內文輸出。

  • 系統提示 （推論範圍）：來自推論範圍屬性，然後來自事件記錄內文。

  • 可用的工具：從推論範圍的工具定義屬性 (llm.tools.*)；然後從事件記錄內文或 中的序列化請求剖析input.value。

組態需求

若要使用一般架構支援進行評估，請設定您的檢測，如下所示：

  • 使用可辨識的範圍名稱。在以 opentelemetry.instrumentation.*或 開頭的範圍名稱下發出。 openinference.instrumentation.*服務只會讀取具有一般架構支援的這些字首。

  • 在每個範圍上設定識別屬性。gen_ai.operation.name traceloop.span.kind 為 OpenTelemetry 慣例設定 或 ，或openinference.span.kind為 OpenInference 慣例設定 或 。服務會略過沒有識別屬性的跨度。

  • 將內容放在記錄的屬性中。設定如何擷取評估欄位中列出的提示、回應和工具屬性。如果您將這些值包裝在自己的結構中，則擷取的值會包含該周圍結構，因為服務會字串內容，而不是剖析架構的資料模型。

如果您無法設定慣例屬性，您仍然可以評估頂層客服人員輪換。設定 AgentCore SDK 也會發出的 agentcore.invocation.agent_response agentcore.invocation.user_prompt和 跨度屬性。服務會從任何範圍讀取這些屬性，而且只涵蓋客服人員提示和回應，而不是推論或工具範圍。