Knowledge Retrieval - Retrieve

Serviço:: Search Service

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

O KnowledgeAgent recupera dados relevantes de repositórios de backup.

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

Parâmetros de URI

Nome	Em	Obrigató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 da solicitação

Nome	Obrigatório	Tipo	Description
x-ms-client-request-id		string (uuid)	A ID de acompanhamento enviada com a solicitação para ajudar na depuração.
x-ms-query-source-authorization		string	Token que identifica o usuário para o qual a consulta está sendo executada. Esse token é usado para impor restrições de segurança em documentos.

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
messages	True	KnowledgeAgentMessage[]	O objeto de estilo de mensagem de linguagem natural.
targetIndexParams		KnowledgeAgentIndexParams[]

Respostas

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

Exemplos

KnowledgeAgentRetrieve

Solicitação de exemplo

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 de exemplo

Código de status:: 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

Nome	Description
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
Image
KnowledgeAgentAzureSearchDocReference	Representa uma referência de documento do Azure Search.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	O objeto de estilo de mensagem de 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

Objeto

As informações adicionais do erro de gerenciamento de recursos.

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

ErrorDetail

Objeto

O detalhe do erro.

Nome	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	As informações adicionais do erro.
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

Objeto

Resposta de erro

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

Image

Objeto

Nome	Tipo	Description
url	string	O url da imagem.

KnowledgeAgentAzureSearchDocReference

Objeto

Representa uma referência de documento do Azure Search.

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

KnowledgeAgentIndexParams

Objeto

Nome	Tipo	Description
filterAddOn	string	Uma condição de filtro aplicada ao índice (por exemplo, 'State eq VA').
includeReferenceSourceData	boolean	Indica se os dados da fonte 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 limite para reclassificação de resultados (intervalo: 0-4).

KnowledgeAgentMessage

Objeto

O objeto de estilo de mensagem de linguagem natural.

Nome	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

Objeto

Tipo de mensagem de texto.

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

KnowledgeAgentMessageTextContent

Objeto

Tipo de mensagem de texto.

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

KnowledgeAgentModelQueryPlanningActivityRecord

Objeto

Representa um registro de atividade de planejamento de consulta LLM.

Nome	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 do 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

Objeto

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

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

KnowledgeAgentRetrievalResponse

Objeto

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

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

KnowledgeAgentSearchActivityRecord

Objeto

Representa um registro de atividade de recuperação.

Nome	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 de destino para a atividade de recuperação.
type	string: AzureSearchQuery	O tipo de registro de atividade.

KnowledgeAgentSemanticRankerActivityRecord

Objeto

Representa um registro de atividade do classificador semântico.

Nome	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 do classificador semântico.
type	string: AzureSearchSemanticRanker	O tipo de registro de atividade.

Query

Objeto

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

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