Knowledge Retrieval - Retrieve

服務:: Search Service

API 版本:: 2025-05-01-preview

KnowledgeAgent 從後備存儲中檢索相關數據。

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-01-preview

URI 參數

名稱	位於	必要	類型	Description
agentName	path	True	string	代理程式的名稱。
endpoint	path	True	string (url)	搜尋服務的端點 URL。
api-version	query	True	string	用戶端 API 版本。

要求標頭

名稱	必要	類型	Description
x-ms-client-request-id		string (uuid)	隨要求一起傳送的追蹤標識碼，以協助偵錯。
x-ms-query-source-authorization		string	標識正在為其執行查詢的使用者的令牌。此令牌用於對文檔實施安全限制。

要求本文

名稱	必要	類型	Description
messages	True	KnowledgeAgentMessage[]	自然語言消息樣式物件。
targetIndexParams		KnowledgeAgentIndexParams[]

回應

名稱	類型	Description
200 OK	KnowledgeAgentRetrievalResponse	檢索回應成功返回。
Other Status Codes	ErrorResponse	錯誤回應。

範例

KnowledgeAgentRetrieve

範例要求

HTTP

POST https://previewexampleservice.search.windows.net/agents('agent-preview-test')/retrieve?api-version=2025-05-01-preview



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "targetIndexParams": [
    {
      "indexName": "preview-test",
      "filterAddOn": "foo eq bar",
      "maxDocsForReranker": 100,
      "rerankerThreshold": 2.5,
      "includeReferenceSourceData": true
    }
  ]
}

範例回覆

狀態碼:: 200

{
  "response": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world two",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 3,
      "inputTokens": 74
    }
  ],
  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d40",
      "activitySource": 1,
      "docKey": "myDocKey1",
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      }
    },
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d41",
      "activitySource": 1,
      "docKey": "myDocKey2",
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      }
    }
  ]
}

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
Image
KnowledgeAgentAzureSearchDocReference	表示 Azure 搜尋文件引用。
KnowledgeAgentIndexParams
KnowledgeAgentMessage	自然語言消息樣式物件。
KnowledgeAgentMessageContentType	消息內容的類型。
KnowledgeAgentMessageImageContent	簡訊類型。
KnowledgeAgentMessageTextContent	簡訊類型。
KnowledgeAgentModelQueryPlanningActivityRecord	表示 LLM 查詢規劃活動記錄。
KnowledgeAgentRetrievalRequest	檢索請求的 input 協定。
KnowledgeAgentRetrievalResponse	檢索回應的輸出協定。
KnowledgeAgentSearchActivityRecord	表示檢索活動記錄。
KnowledgeAgentSemanticRankerActivityRecord	表示語義排名程序活動記錄。
Query	檢索活動的查詢詳細資訊。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細數據。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

Image

Object

名稱	類型	Description
url	string	圖像的url。

KnowledgeAgentAzureSearchDocReference

Object

表示 Azure 搜尋文件引用。

名稱	類型	Description
activitySource	integer (int32)	引用的源活動ID。
docKey	string	引用的文件鍵。
id	string	引用的ID。
sourceData	object
type	string: AzureSearchDoc	引用的類型。

KnowledgeAgentIndexParams

Object

名稱	類型	Description
filterAddOn	string	應用於索引的篩選條件（例如，'State eq VA'）。
includeReferenceSourceData	boolean	指示是否應包含引用源數據。
indexName	string	參數應用於的索引的名稱。
maxDocsForReranker	integer (int32)	限制考慮進行排名的文件數量。
rerankerThreshold	number (float) minimum: 0 maximum: 4	重新排名結果的閾值（範圍：0-4）。

KnowledgeAgentMessage

Object

自然語言消息樣式物件。

名稱	類型	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	指定消息內容的類型。
role	string	工具回應的角色。

KnowledgeAgentMessageContentType

列舉型別

消息內容的類型。

值	Description
text	簡訊內容類型。
image	圖片消息內容種類。

KnowledgeAgentMessageImageContent

Object

簡訊類型。

名稱	類型	Description
image	Image
type	string: image	訊息的類型

KnowledgeAgentMessageTextContent

Object

簡訊類型。

名稱	類型	Description
text	string
type	string: text	訊息的類型

KnowledgeAgentModelQueryPlanningActivityRecord

Object

表示 LLM 查詢規劃活動記錄。

名稱	類型	Description
elapsedMs	integer (int32)	模型活動經過的時間（以毫秒為單位）。
id	integer (int32)	活動記錄的ID。
inputTokens	integer (int32)	LLM 查詢規劃活動的輸入令牌數。
outputTokens	integer (int32)	LLM 查詢規劃活動的輸出令牌數。
type	string: ModelQueryPlanning	活動記錄的類型。

KnowledgeAgentRetrievalRequest

Object

檢索請求的 input 協定。

名稱	類型	Description
messages	KnowledgeAgentMessage[]	自然語言消息樣式物件。
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Object

檢索回應的輸出協定。

名稱	類型	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	用於跟蹤進度和計費影響的活動記錄。
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	回應中使用的檢索數據的引用。
response	KnowledgeAgentMessage[]	自然語言消息樣式物件。

KnowledgeAgentSearchActivityRecord

Object

表示檢索活動記錄。

名稱	類型	Description
count	integer (int32)	檢索的文件計數。
elapsedMs	integer (int32)	檢索活動經過的時間（以毫秒為單位）。
id	integer (int32)	活動記錄的ID。
query	Query	檢索活動的查詢詳細資訊。
queryTime	string (date-time)	此檢索活動的查詢時間。
targetIndex	string	檢索活動的目標索引。
type	string: AzureSearchQuery	活動記錄的類型。

KnowledgeAgentSemanticRankerActivityRecord

Object

表示語義排名程序活動記錄。

名稱	類型	Description
elapsedMs	integer (int32)	模型活動經過的時間（以毫秒為單位）。
id	integer (int32)	活動記錄的ID。
inputTokens	integer (int32)	語義排名器活動的輸入標記數。
type	string: AzureSearchSemanticRanker	活動記錄的類型。

Query

Object

檢索活動的查詢詳細資訊。

名稱	類型	Description
filter	string	篩選器字串。
search	string	搜索字串。