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)	Идентификатор отслеживания, отправленный вместе с запросом на помощь в отладке.
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	Представляет аргументы, с которыми было выполнено действие извлечения BLOB-объектов Azure.
KnowledgeAgentAzureBlobActivityRecord	Представляет запись о действиях по получению BLOB-объектов Azure.
KnowledgeAgentAzureBlobReference	Представляет собой справочник по документам хранилища BLOB-объектов Azure.
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

Объект

Представляет аргументы, с которыми было выполнено действие извлечения BLOB-объектов Azure.

Имя	Тип	Описание
search	string	Строка поиска, используемая для запроса содержимого BLOB-объекта.

KnowledgeAgentAzureBlobActivityRecord

Объект

Представляет запись о действиях по получению BLOB-объектов Azure.

Имя	Тип	Описание
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Аргументы большого двоичного объекта Azure для действия извлечения.
count	integer (int32)	Количество извлеченных документов, которые были достаточно релевантными для того, чтобы преодолеть порог повторного ранжирования.
elapsedMs	integer (int32)	Затраченное время в миллисекундах для извлечения данных.
id	integer (int32)	Идентификатор записи о действии.
knowledgeSourceName	string	Источник знаний для действия по извлечению.
queryTime	string (date-time)	Время запроса для этого действия извлечения.
type	string: azureBlob	Тип записи об активности.

KnowledgeAgentAzureBlobReference

Объект

Представляет собой справочник по документам хранилища BLOB-объектов Azure.

Имя	Тип	Описание
activitySource	integer (int32)	Идентификатор исходного действия для ссылки.
blobUrl	string	URL-адрес большого двоичного объекта для ссылки.
id	string	Идентификатор ссылки.
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)	Идентификатор записи о действии.
inputTokens	integer (int32)	Количество входных токенов для действия синтеза ответов LLM.
outputTokens	integer (int32)	Количество выходных токенов для действия синтеза ответов LLM.
type	string: modelAnswerSynthesis	Тип записи об активности.

KnowledgeAgentModelQueryPlanningActivityRecord

Объект

Представляет запись о планировании запроса LLM.

Имя	Тип	Описание
elapsedMs	integer (int32)	Затраченное время в миллисекундах для извлечения данных.
id	integer (int32)	Идентификатор записи о действии.
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)	Идентификатор записи о действии.
knowledgeSourceName	string	Источник знаний для действия по извлечению.
queryTime	string (date-time)	Время запроса для этого действия извлечения.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Аргументы поискового индекса для действия извлечения.
type	string: searchIndex	Тип записи об активности.

KnowledgeAgentSearchIndexReference

Объект

Представляет ссылку на документ Поиска Azure.

Имя	Тип	Описание
activitySource	integer (int32)	Идентификатор исходного действия для ссылки.
docKey	string	Ключ документа для справки.
id	string	Идентификатор ссылки.
rerankerScore	number (float)	Оценка повторного ранкинга для ссылки на документ.
sourceData	object
type	string: searchIndex	Тип ссылки.

KnowledgeAgentSemanticRerankerActivityRecord

Объект

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

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

KnowledgeSourceKind

Перечисление

Вид источника знаний.

Значение	Описание
searchIndex	Источник знаний, который считывает данные из индекса поиска.
azureBlob	Источник знаний, который считывает и принимает данные из хранилища BLOB-объектов Azure в индекс поиска.

SearchIndexKnowledgeSourceParams

Объект

Задает параметры времени выполнения для источника знаний индекса поиска

Имя	Тип	Описание
filterAddOn	string	Условие фильтра, применяемое к индексу (например, 'State eq VA').
kind	string: searchIndex	Тип источника знаний.
knowledgeSourceName	string	Имя индекса, к которому применяются параметры.