Knowledge Retrieval - Retrieve

Serviço:: Search Service

Versão da API:: 2025-05-01-preview

O KnowledgeAgent recupera dados relevantes de armazenamentos de backup.

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

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
agentName	path	True	string	O nome do agente.
endpoint	path	True	string (url)	A URL do ponto de extremidade do serviço de pesquisa.
api-version	query	True	string	Versão da API do cliente.

Cabeçalho do Pedido

Name	Necessário	Tipo	Description
x-ms-client-request-id		string (uuid)	O ID de rastreamento enviado com a solicitação para ajudar com a depuração.
x-ms-query-source-authorization		string	Token que identifica o usuário para o qual a consulta está sendo executada. Este token é usado para impor restrições de segurança em documentos.

Corpo do Pedido

Name	Necessário	Tipo	Description
messages	True	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.
targetIndexParams		KnowledgeAgentIndexParams[]

Respostas

Name	Tipo	Description
200 OK	KnowledgeAgentRetrievalResponse	A resposta de recuperação é retornada com êxito.
Other Status Codes	ErrorResponse	Resposta de erro.

Exemplos

KnowledgeAgentRetrieve

Pedido de amostra

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
    }
  ]
}

Resposta da amostra

Código de estado:: 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"
      }
    }
  ]
}

Definições

Name	Description
ErrorAdditionalInfo	O erro de gerenciamento de recursos informações adicionais.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
Image
KnowledgeAgentAzureSearchDocReference	Representa uma referência de documento da Pesquisa do Azure.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	O objeto de estilo de mensagem em linguagem natural.
KnowledgeAgentMessageContentType	O tipo de conteúdo da mensagem.
KnowledgeAgentMessageImageContent	Tipo de mensagem de texto.
KnowledgeAgentMessageTextContent	Tipo de mensagem de texto.
KnowledgeAgentModelQueryPlanningActivityRecord	Representa um registro de atividade de planejamento de consulta LLM.
KnowledgeAgentRetrievalRequest	O contrato de entrada para a solicitação de recuperação.
KnowledgeAgentRetrievalResponse	O contrato de saída para a resposta de recuperação.
KnowledgeAgentSearchActivityRecord	Representa um registro de atividade de recuperação.
KnowledgeAgentSemanticRankerActivityRecord	Representa um registro de atividade do classificador semântico.
Query	Os detalhes da consulta para a atividade de recuperação.

ErrorAdditionalInfo

Object

O erro de gerenciamento de recursos informações adicionais.

Name	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

Object

O detalhe do erro.

Name	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	O erro informações adicionais.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Object

Resposta de erro

Name	Tipo	Description
error	ErrorDetail	O objeto de erro.

Image

Object

Name	Tipo	Description
url	string	O url da imagem.

KnowledgeAgentAzureSearchDocReference

Object

Representa uma referência de documento da Pesquisa do Azure.

Name	Tipo	Description
activitySource	integer (int32)	O ID da atividade de origem para a referência.
docKey	string	A chave do documento para a referência.
id	string	O ID da referência.
sourceData	object
type	string: AzureSearchDoc	O tipo de referência.

KnowledgeAgentIndexParams

Object

Name	Tipo	Description
filterAddOn	string	Uma condição de filtro aplicada ao índice (por exemplo, «State eq VA»).
includeReferenceSourceData	boolean	Indica se os dados de origem de referência devem ser incluídos.
indexName	string	O nome do índice ao qual os parâmetros se aplicam.
maxDocsForReranker	integer (int32)	Limita o número de documentos considerados para classificação.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Um limiar para reclassificar os resultados (intervalo: 0-4).

KnowledgeAgentMessage

Object

O objeto de estilo de mensagem em linguagem natural.

Name	Tipo	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Especifica o tipo de conteúdo da mensagem.
role	string	O papel da resposta da ferramenta.

KnowledgeAgentMessageContentType

Enumeração

O tipo de conteúdo da mensagem.

Valor	Description
text	Tipo de conteúdo de mensagem de texto.
image	Tipo de conteúdo da mensagem de imagem.

KnowledgeAgentMessageImageContent

Object

Tipo de mensagem de texto.

Name	Tipo	Description
image	Image
type	string: image	O tipo da mensagem

KnowledgeAgentMessageTextContent

Object

Tipo de mensagem de texto.

Name	Tipo	Description
text	string
type	string: text	O tipo da mensagem

KnowledgeAgentModelQueryPlanningActivityRecord

Object

Representa um registro de atividade de planejamento de consulta LLM.

Name	Tipo	Description
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade do modelo.
id	integer (int32)	A ID do registro de atividade.
inputTokens	integer (int32)	O número de tokens de entrada para a atividade de planejamento de consulta LLM.
outputTokens	integer (int32)	O número de tokens de saída para a atividade de planejamento de consulta LLM.
type	string: ModelQueryPlanning	O tipo de registro de atividade.

KnowledgeAgentRetrievalRequest

Object

O contrato de entrada para a solicitação de recuperação.

Name	Tipo	Description
messages	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Object

O contrato de saída para a resposta de recuperação.

Name	Tipo	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Os registros de atividade para acompanhar o progresso e as implicações de faturamento.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	As referências para os dados de recuperação usados na resposta.
response	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.

KnowledgeAgentSearchActivityRecord

Object

Representa um registro de atividade de recuperação.

Name	Tipo	Description
count	integer (int32)	A contagem de documentos recuperados.
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
query	Query	Os detalhes da consulta para a atividade de recuperação.
queryTime	string (date-time)	O tempo de consulta para essa atividade de recuperação.
targetIndex	string	O índice alvo para a atividade de recuperação.
type	string: AzureSearchQuery	O tipo de registro de atividade.

KnowledgeAgentSemanticRankerActivityRecord

Object

Representa um registro de atividade do classificador semântico.

Name	Tipo	Description
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade do modelo.
id	integer (int32)	A ID do registro de atividade.
inputTokens	integer (int32)	O número de tokens de entrada para a atividade de classificação semântica.
type	string: AzureSearchSemanticRanker	O tipo de registro de atividade.

Query

Object

Os detalhes da consulta para a atividade de recuperação.

Name	Tipo	Description
filter	string	A cadeia de caracteres do filtro.
search	string	A cadeia de caracteres de pesquisa.