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

Knowledge Retrieval - Retrieve

服务:: Search Service

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

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

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-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[]	自然语言消息样式对象。
targetIndexParams		KnowledgeAgentIndexParams[]

响应

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

定义

名称	说明
ErrorAdditionalInfo	资源管理错误附加信息。
ErrorDetail	错误详细信息。
ErrorResponse	错误响应
Image
KnowledgeAgentAzureSearchDocReference	表示 Azure 搜索文档引用。
KnowledgeAgentIndexParams
KnowledgeAgentMessage	自然语言消息样式对象。
KnowledgeAgentMessageContentType	消息内容的类型。
KnowledgeAgentMessageImageContent	短信类型。
KnowledgeAgentMessageTextContent	短信类型。
KnowledgeAgentModelQueryPlanningActivityRecord	表示 LLM 查询计划活动记录。
KnowledgeAgentRetrievalRequest	检索请求的输入协定。
KnowledgeAgentRetrievalResponse	检索响应的输出协定。
KnowledgeAgentSearchActivityRecord	表示检索活动记录。
KnowledgeAgentSemanticRankerActivityRecord	表示语义排名器活动记录。
Query	检索活动的查询详细信息。

ErrorAdditionalInfo

对象

资源管理错误附加信息。

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

ErrorDetail

对象

错误详细信息。

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

ErrorResponse

对象

错误响应

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

Image

对象

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

KnowledgeAgentAzureSearchDocReference

对象

表示 Azure 搜索文档引用。

名称	类型	说明
activitySource	integer (int32)	引用的源活动 ID。
docKey	string	引用的文档密钥。
id	string	引用的 ID。
sourceData	object
type	string: AzureSearchDoc	引用的类型。

KnowledgeAgentIndexParams

对象

名称	类型	说明
filterAddOn	string	应用于索引的筛选条件（例如，“State eq VA”）。
includeReferenceSourceData	boolean	指示是否应包含引用源数据。
indexName	string	参数应用到的索引的名称。
maxDocsForReranker	integer (int32)	限制考虑进行排名的文档数量。
rerankerThreshold	number (float) minimum: 0 maximum: 4	重新排名结果的阈值（范围：0-4）。

KnowledgeAgentMessage

对象

自然语言消息样式对象。

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

KnowledgeAgentMessageContentType

枚举

消息内容的类型。

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

KnowledgeAgentMessageImageContent

对象

短信类型。

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

KnowledgeAgentMessageTextContent

对象

短信类型。

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

KnowledgeAgentModelQueryPlanningActivityRecord

对象

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

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

KnowledgeAgentRetrievalRequest

对象

检索请求的输入协定。

名称	类型	说明
messages	KnowledgeAgentMessage[]	自然语言消息样式对象。
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

对象

检索响应的输出协定。

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

KnowledgeAgentSearchActivityRecord

对象

表示检索活动记录。

名称	类型	说明
count	integer (int32)	检索到的文档计数。
elapsedMs	integer (int32)	检索活动的经过时间（以毫秒为单位）。
id	integer (int32)	活动记录的 ID。
query	Query	检索活动的查询详细信息。
queryTime	string (date-time)	此检索活动的查询时间。
targetIndex	string	检索活动的目标索引。
type	string: AzureSearchQuery	作业记录的类型。

KnowledgeAgentSemanticRankerActivityRecord

对象

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

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

Query

对象

检索活动的查询详细信息。

名称	类型	说明
filter	string	筛选器字符串。
search	string	搜索字符串。