Recuperar dados usando um agente de conhecimento no Azure AI Search

No Azure AI Search, a recuperação agêntica é uma nova arquitetura de consulta paralela que usa um modelo de linguagem de grande porte (LLM) para o planejamento de consultas. Ele gera subconsultas que ampliam o escopo do que é pesquisável e relevante. Ele incorpora o histórico de chat para obter contexto. A LLM estuda a consulta e a subdivide em consultas mais direcionadas, usando frases e terminologia diferentes para composição de subconsulta.

Este artigo explica como usar a ação de recuperação que invoca um agente de conhecimento e o processamento de consulta paralela. É atualizado para a nova versão prévia 2025-08-01, que apresenta alterações significativas da versão prévia 2025-05-01. Para obter ajuda com alterações interruptivas, consulte Migrar seu código de recuperação por meio de agentes.

Este artigo também explica os três componentes da resposta de recuperação:

• resposta extraída para o LLM
• resultados referenciados
• atividade de consulta

A solicitação de recuperação pode incluir instruções para o processamento de consultas que substituem os padrões configurados no agente de conhecimento.

Pré-requisitos

• Uma fonte de conhecimento que encapsula um índice pesquisável. É uma fonte de conhecimento do índice de pesquisa ou uma fonte de conhecimento de blob.

• Um agente de conhecimento que representa o modelo de conclusão de chat e uma ou mais fontes de conhecimento.

• Azure AI Search, em qualquer região que forneça classificação semântica, no nível de preço básico e superior. Seu serviço de pesquisa deve ter uma identidade gerenciada para acesso baseado em função a um modelo de conclusão de chat.

• Permissões no Azure AI Search. O Leitor de Dados do Índice de Pesquisa pode executar consultas no Azure AI Search, mas a identidade gerenciada do serviço de pesquisa deve ter permissões de usuário dos Serviços Cognitivos no recurso Azure OpenAI. Para obter mais informações sobre o teste local e a obtenção de tokens de acesso, consulte Início Rápido: Conectar sem chaves.

• Requisitos de API. Para criar ou usar um agente de conhecimento, use a API REST do plano de dados 2025-08-01-preview. Ou use um pacote de pré-lançamento de um SDK do Azure que fornece APIs do agente de conhecimento: SDK do Azure para Python, SDK do Azure para .NET, SDK do Azure para Java.

Para seguir as etapas neste guia, recomendamos o Visual Studio Code com um cliente REST para enviar chamadas à API REST para o Azure AI Search. Não há suporte ao portal no momento.

Chamar a ação de recuperação

Chame a ação de recuperação no objeto do agente de conhecimento para invocar a recuperação e retornar uma resposta. Use a API REST do plano de dados 2025-08-01-preview ou um pacote de pré-lançamento do SDK do Azure que fornece funcionalidade equivalente para essa tarefa.

Todos os searchable campos no índice de pesquisa estão no escopo para execução da consulta. Se o índice incluir campos de vetor, seu índice deverá ter uma definição de vetor válida para que ele possa vetorizar as entradas de consulta. Caso contrário, os campos de vetor serão ignorados. O tipo de consulta implícita é semantic, e não há nenhum modo de pesquisa ou seleção de campos de pesquisa.

A entrada para a rota de recuperação é o histórico de conversas do chat em linguagem natural, em que o array messages contém a conversa.

@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# Send grounding request
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You can answer questions about the Earth at night.
                    Sources have a JSON format with a ref_id that must be cited in the answer.
                    If you do not have the answer, respond with 'I do not know'." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?" }
                ]
            }
        ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

Pontos principais:

• A ação de recuperação tem como destino um agente de conhecimento. O agente de conhecimento especifica uma ou mais fontes de conhecimento e uma configuração de fonte de conhecimento. Examine a definição do agente de conhecimento para a configuração de saída e classificação semântica.

• messages articula as mensagens enviadas ao modelo. O formato da mensagem é semelhante às APIs do Azure OpenAI.

  • role define de onde veio a mensagem, por exemplo assistant , ou user. O modelo usado determina quais funções são válidas.

  • content é a mensagem ou prompt enviado para o LLM. Deve haver texto nesta pré-visualização.

• knowledgeSourceParams é opcional. Especifique uma fonte de conhecimento se o agente tiver mais de um e você quiser concentrar a ação de recuperação em apenas uma fonte de conhecimento. Se o agente de conhecimento tiver apenas uma fonte de conhecimento com a configuração desejada, você poderá omitir esta seção.

  Uma especificação de fonte de conhecimento na ação de recuperação descreve o índice de pesquisa de destino no serviço de pesquisa. Portanto, mesmo que a fonte de conhecimento "kind" seja o blob do Azure, o valor válido aqui será searchIndex. Nesta primeira versão de visualização pública, knowledgeSourceParams.kind é sempre searchIndex.

Examinar a resposta extraída

A resposta extraída é uma única cadeia de caracteres unificada que normalmente é passada para uma LLM que a consome como dados de aterramento, usando-a para formular uma resposta. Sua chamada à API do LLM inclui a cadeia de caracteres unificada e instruções para o modelo, como, por exemplo, se o aterramento deve ser usado de forma exclusiva ou como suplemento.

O corpo da resposta também é estruturado no formato de estilo de mensagem de chat. Atualmente nesta versão prévia, o conteúdo é serializado JSON.

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":0,\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

Pontos principais:

• content.text é uma matriz JSON. É uma única cadeia de caracteres composta pelos documentos mais relevantes (ou partes) encontrados no índice de pesquisa, considerando as entradas de consulta e histórico de chat. Esta matriz são seus dados de fundamentação que um modelo de conclusão de chat usa para formular uma resposta à pergunta do usuário.

  Essa parte da resposta consiste em 200 partes ou menos, excluindo os resultados que não atingirem o limite mínimo de uma pontuação reclassificadora de 2,5.

  A cadeia de caracteres começa com a ID de referência da parte (usada para fins de citação) e todos os campos especificados na configuração semântica do índice de destino. Neste exemplo, você deve assumir que a configuração semântica no índice de destino tem um campo "título", um campo "termos" e um campo "conteúdo".

• content.type tem um valor válido nesta versão prévia: text.

Examinar a matriz de atividades

A matriz de atividades gera o plano de consulta e ajuda você a acompanhar as operações executadas ao executar a solicitação. Ele fornece transparência das operações para que você possa entender as implicações de cobrança e a frequência das invocações de recursos.

A saída inclui:

• Token usado para entrada
• Contagens de tokens para saída
• Subconsultas enviadas para o pipeline de recuperação
• Contagem de resultados por subconsulta
• Filtros na subconsulta, se aplicável
• Contagens de tokens usadas para classificação e extração

Aqui está um exemplo de uma matriz de atividades.

"activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 1261,
      "outputTokens": 270
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "suburban belts December brightening urban cores comparison",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:25.944Z",
      "count": 0,
      "elapsedMs": 600
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "Phoenix nighttime street grid visibility from space",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.128Z",
      "count": 2,
      "elapsedMs": 161
    },
    {
      "type": "AzureSearchQuery",
      "id": 3,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "interstate visibility from space midwestern cities",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.277Z",
      "count": 0,
      "elapsedMs": 147
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 4,
      "inputTokens": 2622
    }
  ],

Examinar a matriz de referências

A references matriz é uma referência direta dos dados de aterramento subjacentes e inclui o sourceData usado para gerar a resposta. Ele consiste em cada documento encontrado e semanticamente classificado pelo mecanismo de pesquisa. Os campos no sourceData incluem um id e campos semânticos: title, terms, content.

O id é um identificador de referência para um item dentro de uma resposta específica. Não é a chave do documento no índice de busca. É usado para fornecer citações.

A finalidade dessa matriz é fornecer uma estrutura de estilo de mensagem de chat para facilitar a integração. Por exemplo, se você quiser serializar os resultados em uma estrutura diferente ou precisar de alguma manipulação programática dos dados antes de retornar ao usuário.

Você também pode obter os dados estruturados do objeto de dados de origem na matriz de referências para manipulá-los como achar adequado.

Aqui está um exemplo da matriz de referências.

  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "AzureSearchDoc",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

Conteúdo relacionado

• Recuperação com agentes na Pesquisa de IA do Azure

• RAG Agentic: criar um mecanismo de recuperação de raciocínio com a Pesquisa de IA do Azure (vídeo do YouTube)

• Demonstração do Azure OpenAI apresentando recuperação por agentes