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)	Идентификатор отслеживания, отправляемый запросом на отладку.
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)	Идентификатор исходного действия для ссылки.
docKey	string	Ключ документа для справки.
id	string	Идентификатор ссылки.
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)	Идентификатор записи о действии.
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)	Идентификатор записи о действии.
query	Query	Сведения о запросе для действия извлечения.
queryTime	string (date-time)	Время запроса для этого действия извлечения.
targetIndex	string	Целевой индекс для действия извлечения.
type	string: AzureSearchQuery	Тип записи об активности.

KnowledgeAgentSemanticRankerActivityRecord

Объект

Представляет запись активности семантического ранжирования.

Имя	Тип	Описание
elapsedMs	integer (int32)	Затраченное время в миллисекундах для действия модели.
id	integer (int32)	Идентификатор записи о действии.
inputTokens	integer (int32)	Количество входных маркеров для действия семантического ранжирования.
type	string: AzureSearchSemanticRanker	Тип записи об активности.

Query

Объект

Сведения о запросе для действия извлечения.

Имя	Тип	Описание
filter	string	Строка фильтра.
search	string	Строка поиска.