Knowledge Retrieval - Retrieve

服務:: Search Service

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

KnowledgeAgent 會從支援存放區擷取相關資料。

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-08-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)	隨請求一起傳送的追蹤 ID，以協助偵錯。
x-ms-query-source-authorization		string	識別正在執行查詢的使用者的權杖。此權杖可用來對文件強制執行安全性限制。

要求本文

名稱	必要	類型	Description
messages	True	KnowledgeAgentMessage[]	自然語言訊息樣式物件。
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

回應

名稱	類型	Description
200 OK	KnowledgeAgentRetrievalResponse	擷取回應已順利傳回。
Other Status Codes	ErrorResponse	錯誤回應。

範例

KnowledgeAgentRetrieve

範例要求

HTTP

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



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-preview-test",
      "kind": "searchIndex"
    }
  ]
}

範例回覆

狀態碼:: 200

{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world two",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "semanticReranker",
      "id": 3,
      "inputTokens": 74,
      "elapsedMs": 0
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
Image
KnowledgeAgentAzureBlobActivityArguments	代表執行 Azure Blob 擷取活動時所使用的引數。
KnowledgeAgentAzureBlobActivityRecord	代表 Azure Blob 擷取活動記錄。
KnowledgeAgentAzureBlobReference	代表 Azure Blob 儲存體檔參考。
KnowledgeAgentMessage	自然語言訊息樣式物件。
KnowledgeAgentMessageContentType	訊息內容的類型。
KnowledgeAgentMessageImageContent	簡訊類型。
KnowledgeAgentMessageTextContent	簡訊類型。
KnowledgeAgentModelAnswerSynthesisActivityRecord	代表 LLM 答案綜合活動記錄。
KnowledgeAgentModelQueryPlanningActivityRecord	代表 LLM 查詢規劃活動記錄。
KnowledgeAgentRetrievalRequest	擷取要求的輸入合約。
KnowledgeAgentRetrievalResponse	擷取回應的輸出合約。
KnowledgeAgentSearchIndexActivityArguments	代表執行搜尋索引擷取活動時所使用的引數。
KnowledgeAgentSearchIndexActivityRecord	代表搜尋索引擷取活動記錄。
KnowledgeAgentSearchIndexReference	代表 Azure 搜尋服務檔參考。
KnowledgeAgentSemanticRerankerActivityRecord	代表語意排名器活動記錄。
KnowledgeSourceKind	知識來源的那種。
SearchIndexKnowledgeSourceParams	指定搜尋索引知識來源的執行階段參數

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 (uri)	影像的網址。

KnowledgeAgentAzureBlobActivityArguments

Object

代表執行 Azure Blob 擷取活動時所使用的引數。

名稱	類型	Description
search	string	用來查詢 Blob 內容的搜尋字串。

KnowledgeAgentAzureBlobActivityRecord

Object

代表 Azure Blob 擷取活動記錄。

名稱	類型	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	擷取活動的 Azure Blob 引數。
count	integer (int32)	檢索到的足夠相關的文件計數，足以通過重新排名閾值。
elapsedMs	integer (int32)	擷取活動的經過時間（以毫秒為單位）。
id	integer (int32)	活動記錄的識別碼。
knowledgeSourceName	string	擷取活動的知識來源。
queryTime	string (date-time)	此擷取活動的查詢時間。
type	string: azureBlob	活動記錄的類型。

KnowledgeAgentAzureBlobReference

Object

代表 Azure Blob 儲存體檔參考。

名稱	類型	Description
activitySource	integer (int32)	參考的來源活動 ID。
blobUrl	string	參考的 Blob URL。
id	string	參考的 ID。
rerankerScore	number (float)	文件參考的重新排名者分數。
sourceData	object
type	string: azureBlob	參考的類型。

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	訊息的類型

KnowledgeAgentModelAnswerSynthesisActivityRecord

Object

代表 LLM 答案綜合活動記錄。

名稱	類型	Description
elapsedMs	integer (int32)	擷取活動的經過時間（以毫秒為單位）。
id	integer (int32)	活動記錄的識別碼。
inputTokens	integer (int32)	LLM 答案合成活動的輸入權杖數目。
outputTokens	integer (int32)	LLM 答案綜合活動的輸出權杖數目。
type	string: modelAnswerSynthesis	活動記錄的類型。

KnowledgeAgentModelQueryPlanningActivityRecord

Object

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

名稱	類型	Description
elapsedMs	integer (int32)	擷取活動的經過時間（以毫秒為單位）。
id	integer (int32)	活動記錄的識別碼。
inputTokens	integer (int32)	LLM 查詢規劃活動的輸入權杖數目。
outputTokens	integer (int32)	LLM 查詢規劃活動的輸出權杖數目。
type	string: modelQueryPlanning	活動記錄的類型。

KnowledgeAgentRetrievalRequest

Object

擷取要求的輸入合約。

名稱	類型	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	自然語言訊息樣式物件。

KnowledgeAgentRetrievalResponse

Object

擷取回應的輸出合約。

名稱	類型	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	用於追蹤進度和計費影響的活動記錄。
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	回應中使用的擷取資料參考。
response	KnowledgeAgentMessage[]	自然語言訊息樣式物件。

KnowledgeAgentSearchIndexActivityArguments

Object

代表執行搜尋索引擷取活動時所使用的引數。

名稱	類型	Description
filter	string	篩選字串。
search	string	用來查詢搜尋索引的搜尋字串。

KnowledgeAgentSearchIndexActivityRecord

Object

代表搜尋索引擷取活動記錄。

名稱	類型	Description
count	integer (int32)	檢索到的足夠相關的文件計數，足以通過重新排名閾值。
elapsedMs	integer (int32)	擷取活動的經過時間（以毫秒為單位）。
id	integer (int32)	活動記錄的識別碼。
knowledgeSourceName	string	擷取活動的知識來源。
queryTime	string (date-time)	此擷取活動的查詢時間。
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	擷取活動的搜尋索引引數。
type	string: searchIndex	活動記錄的類型。

KnowledgeAgentSearchIndexReference

Object

代表 Azure 搜尋服務檔參考。

名稱	類型	Description
activitySource	integer (int32)	參考的來源活動 ID。
docKey	string	參考的文件索引鍵。
id	string	參考的 ID。
rerankerScore	number (float)	文件參考的重新排名者分數。
sourceData	object
type	string: searchIndex	參考的類型。

KnowledgeAgentSemanticRerankerActivityRecord

Object

代表語意排名器活動記錄。

名稱	類型	Description
elapsedMs	integer (int32)	擷取活動的經過時間（以毫秒為單位）。
id	integer (int32)	活動記錄的識別碼。
inputTokens	integer (int32)	語意排名器活動的輸入權杖數目。
type	string: semanticReranker	活動記錄的類型。

KnowledgeSourceKind

列舉型別

知識來源的那種。

值	Description
searchIndex	從搜尋索引讀取資料的知識來源。
azureBlob	從 Azure Blob 儲存體讀取資料並將其擷取至搜尋索引的知識來源。

SearchIndexKnowledgeSourceParams

Object

指定搜尋索引知識來源的執行階段參數

名稱	類型	Description
filterAddOn	string	套用至索引的篩選條件（例如，'State eq VA'）。
kind	string: searchIndex	知識來源的類型。
knowledgeSourceName	string	參數套用的索引名稱。