你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Knowledge Retrieval - Retrieve

服务:: Search Service

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

KnowledgeAgent 从后备存储中检索相关数据。

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

URI 参数

名称	在	必需	类型	说明
agentName	path	True	string	代理的名称。
endpoint	path	True	string (url)	搜索服务的终结点 URL。
api-version	query	True	string	客户端 API 版本。

请求头

名称	必需	类型	说明
x-ms-client-request-id		string (uuid)	随请求一起发送的跟踪 ID，以帮助调试。
x-ms-query-source-authorization		string	标识正在执行查询的用户的令牌。此令牌用于对文档实施安全限制。

请求正文

名称	必需	类型	说明
messages	True	KnowledgeAgentMessage[]	自然语言消息样式对象。
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

响应

名称	类型	说明
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"
    }
  ]
}

定义

名称	说明
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

对象

资源管理错误附加信息。

名称	类型	说明
info	object	其他信息。
type	string	其他信息类型。

ErrorDetail

对象

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

对象

错误响应

名称	类型	说明
error	ErrorDetail	错误对象。

Image

对象

名称	类型	说明
url	string (uri)	图像的 URL。

KnowledgeAgentAzureBlobActivityArguments

对象

表示运行 Azure Blob 检索活动时使用的参数。

名称	类型	说明
search	string	用于查询 blob 内容的搜索字符串。

KnowledgeAgentAzureBlobActivityRecord

对象

表示 Azure Blob 检索活动记录。

名称	类型	说明
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	检索活动的 azure blob 参数。
count	integer (int32)	检索到的足够相关以通过重新排序阈值的文档计数。
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
knowledgeSourceName	string	检索活动的知识源。
queryTime	string (date-time)	此检索活动的查询时间。
type	string: azureBlob	作业记录的类型。

KnowledgeAgentAzureBlobReference

对象

表示 Azure Blob 存储文档引用。

名称	类型	说明
activitySource	integer (int32)	引用的源活动 ID。
blobUrl	string	引用的 blob URL。
id	string	引用的 ID。
rerankerScore	number (float)	文档引用的重新排序器分数。
sourceData	object
type	string: azureBlob	引用的类型。

KnowledgeAgentMessage

对象

自然语言消息样式对象。

名称	类型	说明
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	指定消息内容的类型。
role	string	工具响应的作用。

KnowledgeAgentMessageContentType

枚举

消息内容的类型。

值	说明
text	短信内容类型。
image	图像消息内容类型。

KnowledgeAgentMessageImageContent

对象

短信类型。

名称	类型	说明
image	Image
type	string: image	消息的类型

KnowledgeAgentMessageTextContent

对象

短信类型。

名称	类型	说明
text	string
type	string: text	消息的类型

KnowledgeAgentModelAnswerSynthesisActivityRecord

对象

表示 LLM 答案合成活动记录。

名称	类型	说明
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
inputTokens	integer (int32)	LLM 答案合成活动的输入令牌数。
outputTokens	integer (int32)	LLM 答案合成活动的输出令牌数。
type	string: modelAnswerSynthesis	作业记录的类型。

KnowledgeAgentModelQueryPlanningActivityRecord

对象

表示 LLM 查询计划活动记录。

名称	类型	说明
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
inputTokens	integer (int32)	LLM 查询规划活动的输入标记数。
outputTokens	integer (int32)	LLM 查询规划活动的输出令牌数。
type	string: modelQueryPlanning	作业记录的类型。

KnowledgeAgentRetrievalRequest

对象

检索请求的输入协定。

名称	类型	说明
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	自然语言消息样式对象。

KnowledgeAgentRetrievalResponse

对象

检索响应的输出协定。

名称	类型	说明
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	用于跟踪进度和计费影响的活动记录。
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	响应中使用的检索数据的引用。
response	KnowledgeAgentMessage[]	自然语言消息样式对象。

KnowledgeAgentSearchIndexActivityArguments

对象

表示运行搜索索引检索活动时使用的参数。

名称	类型	说明
filter	string	筛选器字符串。
search	string	用于查询搜索索引的搜索字符串。

KnowledgeAgentSearchIndexActivityRecord

对象

表示搜索索引检索活动记录。

名称	类型	说明
count	integer (int32)	检索到的足够相关以通过重新排序阈值的文档计数。
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
knowledgeSourceName	string	检索活动的知识源。
queryTime	string (date-time)	此检索活动的查询时间。
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	检索活动的搜索索引参数。
type	string: searchIndex	作业记录的类型。

KnowledgeAgentSearchIndexReference

对象

表示 Azure 搜索文档引用。

名称	类型	说明
activitySource	integer (int32)	引用的源活动 ID。
docKey	string	引用的文档密钥。
id	string	引用的 ID。
rerankerScore	number (float)	文档引用的重新排序器分数。
sourceData	object
type	string: searchIndex	引用的类型。

KnowledgeAgentSemanticRerankerActivityRecord

对象

表示语义排名器活动记录。

名称	类型	说明
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
inputTokens	integer (int32)	语义排名器活动的输入标记数。
type	string: semanticReranker	作业记录的类型。

KnowledgeSourceKind

枚举

知识来源的那种。

值	说明
searchIndex	从搜索索引中读取数据的知识源。
azureBlob	用于读取数据并将其从 Azure Blob 存储引入搜索索引的知识源。

SearchIndexKnowledgeSourceParams

对象

指定搜索索引知识源的运行时参数

名称	类型	说明
filterAddOn	string	应用于索引的筛选条件（例如，“State eq VA”）。
kind	string: searchIndex	知识源的类型。
knowledgeSourceName	string	参数应用到的索引的名称。