Crie um índice para recuperação agêncica no Pesquisa de IA do Azure 

Este artigo explica os campos de índice e as configurações necessários para a recuperação agêntica. Nenhum desses requisitos é novo. Você pode usar um índice existente que atenda aos critérios, mesmo que ele tenha sido criado com uma versão anterior da API.

Cada fonte de conhecimento indexada depende de um índice subjacente. Dependendo de como você configurou seu pipeline, o índice pode ser um dos seguintes:

• Existente: um índice autônomo exposto por meio de uma fonte de conhecimento do índice de pesquisa. O índice deve atender aos critérios neste artigo.

• Gerado: Um índice criado automaticamente por uma fonte de conhecimento indexada. Os índices gerados atendem a todos os critérios por padrão.

Critérios para a recuperação por meio de agentes

A tabela a seguir organiza os elementos de índice que afetam a recuperação agêntica por nível de requisito.

Definição de índice de exemplo

O exemplo a seguir mostra um índice que funciona para recuperação agêntica. Ele atende aos critérios dos elementos necessários e inclui campos de vetor como uma prática recomendada.

{
  "name": "earth_at_night",
  "description": "Contains images and descriptions of our planet in darkness as captured from space by Earth-observing satellites and astronauts on the International Space Station over the past 25 years.",
  "fields": [
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "key": true,
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "page_chunk", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false,
      "analyzer": "en.microsoft",
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "page_chunk_vector_text_3_large", "type": "Collection(Edm.Single)",
      "searchable": true, "retrievable": false, "filterable": false, "sortable": false, "facetable": false,
      "dimensions": 3072,
      "vectorSearchProfile": "hnsw_text_3_large",
      "stored": false,
      "synonymMaps": []
    },
    {
      "name": "page_number", "type": "Edm.Int32",
      "searchable": false, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "chapter_number", "type": "Edm.Int32",
      "searchable": false, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "stored": true,
      "synonymMaps": []
    }
  ],
  "semantic": {
    "defaultConfiguration": "semantic_config",
    "configurations": [
      {
        "name": "semantic_config",
        "flightingOptIn": false,
        "prioritizedFields": {
          "prioritizedContentFields": [
            {
              "fieldName": "page_chunk"
            }
          ],
          "prioritizedKeywordsFields": []
        }
      }
    ]
  },
  "vectorSearch": {
    "algorithms": [
      {
        "name": "alg",
        "kind": "hnsw",
        "hnswParameters": {
          "metric": "cosine",
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500
        }
      }
    ],
    "profiles": [
      {
        "name": "hnsw_text_3_large",
        "algorithm": "alg",
        "vectorizer": "azure_openai_text_3_large"
      }
    ],
    "vectorizers": [
      {
        "name": "azure_openai_text_3_large",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://YOUR-AOAI-RESOURCE.openai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    ],
    "compressions": []
  }
}

Um índice bem projetado para IA generativa ou para geração aumentada por recuperação (RAG) tem os seguintes componentes:

• Uma descrição que um LLM ou agente pode usar para determinar se um índice deve ser usado ou ignorado.

• Trechos de texto legível por humanos que você pode passar como tokens de entrada para um LLM formular respostas.

• Uma configuração de ranqueador semântico porque a recuperação por meio de agentes usa a classificação semântica de nível 2 (L2) para identificar os segmentos mais relevantes.

• (Opcional) Versões equivalentes de vetor das partes de texto legíveis por humanos para pesquisa de vetor complementar.

O texto segmentado é importante porque os LLMs consomem e geram sequências tokenizadas de conteúdo textual simples legível por humanos. Por esse motivo, é recomendável usar campos searchable que forneçam strings de texto sem formatação e estejam retrievable na resposta. Em Pesquisa de IA do Azure , você pode criar texto em partes usando soluções decompiladas ou de terceiros.

Uma suposição incorporada para conteúdo fragmentado é que os documentos de origem têm grandes quantidades de conteúdo verboso. Se o conteúdo de origem for dados estruturados, como um banco de dados de produto, seu índice deverá renunciar ao agrupamento e, em vez disso, incluir campos mapeados para a fonte de dados original, como um nome de produto, categoria ou descrição. A atribuição de searchable e retrievable também se aplica a dados estruturados. searchable torna o conteúdo elegível para consultas, e retrievable o adiciona aos resultados de busca (dados de fundamentação).

O conteúdo do vetor pode ser útil porque adiciona pesquisa de similaridade à recuperação de informações. No momento da consulta, quando os campos de vetor estão presentes no índice, o mecanismo de recuperação agente executa uma consulta de vetor em paralelo à consulta de texto. Como as consultas de vetor procuram conteúdo semelhante em vez de palavras correspondentes, uma consulta vetor pode encontrar um resultado altamente relevante que uma consulta de texto pode perder. Adicionar vetores pode aprimorar e melhorar a qualidade dos seus dados de embasamento, mas não é estritamente necessário. Pesquisa de IA do Azure  tem uma abordagem integrada de vetorização.

Os campos de vetor são usados apenas para execução de consulta em Pesquisa de IA do Azure . Você não precisa do vetor nos resultados porque ele não é humano nem legível para o LLM. Para minimizar os requisitos de espaço, recomendamos definir retrievable e stored como falso. Para obter mais informações, consulte Otimizar o armazenamento e o processamento de vetores.

Se você usar vetores, ter um vetorizador definido na configuração de pesquisa de vetor é fundamental. Ele determina se o campo de vetor é usado durante a execução da consulta. O vetorizador codifica as subconsultas de cadeia de caracteres em vetores durante a consulta para a busca de similaridade nos vetores. O vetorizador deve ser o mesmo modelo de inserção usado para criar os vetores no índice.

Por padrão, todos os searchable campos são incluídos na execução da consulta e todos os retrievable campos são retornados nos resultados. Você pode escolher quais campos usar para cada ação na definição da fonte de dados de conhecimento do índice de pesquisa.

Adicionar uma descrição

Um campo de índice description é uma cadeia de caracteres definida pelo usuário que você pode usar para fornecer diretrizes para servidores LLMs e protocolo MCP ao decidir usar um índice específico para uma consulta. Esse texto legível por humanos é inestimável quando um sistema deve acessar vários índices e tomar uma decisão com base na descrição.

Uma descrição de índice é uma atualização de esquema e você pode adicioná-la sem precisar recompilar todo o índice.

• O comprimento da cadeia de caracteres é máximo de 4.000 caracteres.

• O conteúdo deve ser legível por humanos, no Unicode. Seu caso de uso deve determinar qual idioma usar (por exemplo, inglês ou outro idioma).

Adicionar uma configuração semântica

O índice deve ter pelo menos uma configuração semântica. A configuração semântica deve ter:

• Uma configuração nomeada.
• Um prioritizedContentFields definido o para pelo menos um campo de cadeia de caracteres que é tanto searchable como retrievable.

Há duas maneiras de especificar uma configuração semântica por nome. Se o índice tiver defaultSemanticConfiguration definido como uma configuração nomeada, a recuperação o usará. Como alternativa, você pode especificar a configuração semântica dentro da fonte de conhecimento do índice de pesquisa.

Dentro da configuração, prioritizedContentFields é necessário. Título e palavras-chave são opcionais. Para conteúdo fragmentado, talvez você não tenha nenhum dos dois. No entanto, se você adicionar reconhecimento de entidade ou extração de frase-chave, poderá ter algumas palavras-chave associadas a cada parte que podem ser úteis em cenários de pesquisa, talvez em um perfil de pontuação.

O exemplo a seguir mostra uma configuração semântica que funciona para recuperação agêntica.

"semantic":{
   "defaultConfiguration":"semantic_config",
   "configurations":[
      {
         "name":"semantic_config",
         "flightingOptIn":false,
         "prioritizedFields":{
            "titleField":{
               "fieldName":""
            },
            "prioritizedContentFields":[
               {
                  "fieldName":"page_chunk"
               }
            ],
            "prioritizedKeywordsFields":[
               {
                  "fieldName":"Category"
               },
               {
                  "fieldName":"Tags"
               },
               {
                  "fieldName":"Location"
               }
            ]
         }
      }
   ]
}

Adicionar um vetorizador

Se o índice contiver campos de vetor, o plano de consulta incluirá esses campos se eles estiverem searchable e tiverem uma vectorizer atribuição.

Um vetorizador especifica um modelo de incorporação que fornece conversões de texto para vetor em tempo de consulta. Ele deve apontar para o mesmo modelo de inserção usado para codificar o conteúdo do vetor em seu índice. Você pode usar qualquer modelo de inserção compatível com Pesquisa de IA do Azure . Especifique vetorizadores em campos de vetor por meio de um perfil de vetor.

A definição do campo de vetor no exemplo de índice mostra os atributos de campo de chave: dimensions, que é o número de inserções geradas pelo modelo e vectorSearchProfile.

  {
    "name": "page_chunk_text_3_large", "type": "Collection(Edm.Single)",
    "searchable": true, "retrievable": false, "filterable": false, "sortable": false, "facetable": false,
    "dimensions": 3072,
    "vectorSearchProfile": "hnsw_text_3_large",
    "stored": false,
    "synonymMaps": []
  }

Perfis de vetor são configurações de vetorizadores, algoritmos e técnicas de compactação. Cada campo de vetor só pode usar um perfil, mas seu índice pode ter muitos caso você queira perfis exclusivos para cada campo de vetor.

Consultar vetores e chamar um vetorizador adicionam latência à requisição como um todo, mas, se você quiser busca por similaridade, essa troca pode valer a pena.

O exemplo a seguir mostra um vetorizador que funciona para recuperação agêntica, conforme aparece em uma configuração de vectorSearch. Não há nada na definição de vetorizador que precise de alteração para funcionar com a recuperação por meio de agentes.

"vectorSearch": {
  "algorithms": [
    {
      "name": "alg",
      "kind": "hnsw",
      "hnswParameters": {
        "metric": "cosine",
        "m": 4,
        "efConstruction": 400,
        "efSearch": 500
      }
    }
  ],
  "profiles": [
    {
      "name": "hnsw_text_3_large",
      "algorithm": "alg",
      "vectorizer": "azure_openai_text_3_large"
    }
  ],
  "vectorizers": [
    {
      "name": "azure_openai_text_3_large",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://YOUR-AOAI-RESOURCE.openai.azure.com",
        "deploymentId": "text-embedding-3-large",
        "modelName": "text-embedding-3-large"
      }
    }
  ],
  "compressions": []
}

Adicionar um perfil de pontuação

Perfis de pontuação são critérios para aumento de relevância. Eles são aplicados a campos não vetoriais (texto e números) e são avaliados durante a execução da consulta, embora o comportamento preciso dependa da versão da API usada para criar o índice.

É mais provável que um perfil de pontuação adicione valor à sua solução se o índice for baseado em dados estruturados. Os dados estruturados são indexados em vários campos discretos, o que significa que seu perfil de pontuação pode ter critérios direcionados ao conteúdo ou às características de um campo específico.

Se você criar o índice usando 2025-05-01-preview ou posterior, o perfil de pontuação será executado por último. Se o índice for criado usando uma versão anterior da API, os perfis de pontuação serão avaliados antes do reclassificado semântico. A ordem real dos resultados semanticamente classificados é determinada pela propriedade rankingOrder no índice, e que pode ser definida como boostedRerankerScore (caso um perfil de pontuação tenha sido aplicado) ou rerankerScore (caso nenhum perfil de pontuação tenha sido aplicado).

Você pode usar qualquer perfil de pontuação que faça sentido para o índice. O exemplo a seguir mostra um perfil de pontuação que aumenta a pontuação de busca de uma correspondência quando ela é encontrada em um campo específico. Os campos são ponderados aumentando-se os multiplicadores. Por exemplo, se uma correspondência for encontrada no campo "Categoria", a pontuação aumentada será multiplicada por 5.

"scoringProfiles": [
    {
      "name": "boostSearchTerms",
      "text": {
        "weights": {
          "Location": 2,
          "Category": 5
        }
      }
    }
]

Adicionar um analisador

Os analisadores se aplicam a campos de texto e podem ser analisadores de linguagem ou analisadores personalizados que controlam a tokenização no índice, como preservar caracteres especiais ou espaço em branco.

Os analisadores são definidos em um índice de pesquisa e atribuídos a campos. Os exemplo da coleção de campos inclui uma referência do analisador nos segmentos de texto. Neste exemplo, o analisador padrão (Lucene padrão) é substituído por um analisador de idioma Microsoft para o idioma inglês.

{
  "name": "page_chunk", "type": "Edm.String",
  "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false,
  "analyzer": "en.microsoft",
  "stored": true,
  "synonymMaps": []
}

Adicionar um mapa de sinônimos

Mapas de sinônimos expandem consultas adicionando sinônimos para termos nomeados. Por exemplo, você pode ter termos científicos ou médicos para termos comuns.

Os mapas de sinônimos são definidos como um recurso de nível superior em um índice de pesquisa e atribuídos a campos. O exemplo da coleção de campos não inclui um mapa de sinônimos, mas o exemplo a seguir mostra como um mapa de sinônimos com ortografias variantes de nomes de país/região pode ser atribuído a um campo hipotético de "locais".

{
    "name":"locations",
    "type":"Edm.String",
    "searchable":true,
    "synonymMaps":[ "country-region-synonyms" ]
}

Adicionar seu índice a uma fonte de conhecimento

Se você tiver um índice autônomo que já existe e não for gerado por uma fonte de conhecimento, crie os seguintes objetos:

• Uma fonte de conhecimento de um índice de busca para encapsular seu conteúdo indexado.
• Uma base de conhecimento que representa uma ou mais fontes de conhecimento e outras instruções para recuperação agêntica.

Conteúdo relacionado

• Recuperação por meio de agentes na Pesquisa de IA do Azure
• Agentic RAG: criar um mecanismo de recuperação de raciocínio com Pesquisa de IA do Azure  (vídeo do YouTube)
• Demonstração do Azure OpenAI com recuperação baseada em agentes