Carregar dados em um índice de pesquisa no Azure AI Search

  • Artigo

Este artigo explica como importar documentos para um índice de pesquisa predefinido. Na Pesquisa de IA do Azure, um índice de pesquisa é criado primeiro com a importação de dados seguindo como uma segunda etapa. A exceção são os assistentes de Importação no portal e nos pipelines de indexador, que criam e carregam um índice em um fluxo de trabalho.

Como funciona a importação de dados

Um serviço de pesquisa aceita documentos JSON que estão em conformidade com o esquema de índice. Um serviço de pesquisa importa e indexa texto sem formatação e vetores em JSON, usados em cenários de pesquisa de texto completo, busca em vetores, pesquisa híbrida e mineração de conhecimento.

  • O conteúdo de texto sem formatação pode ser obtido a partir de campos alfanuméricos na fonte de dados externos, metadados úteis em cenários de pesquisa ou conteúdo enriquecido criado por um conjunto de habilidades (as habilidades podem extrair ou inferir descrições textuais de imagens e conteúdo não estruturado).

  • O conteúdo vetorial é vetorizado usando um modelo de incorporação externo ou vetorização integrada usando recursos do IA do Azure Search que se integram à IA aplicada.

Você mesmo pode preparar esses documentos, mas se o conteúdo residir em uma fonte de dados suportada, a execução de um indexador ou o uso de um assistente de Importação pode automatizar a recuperação de documentos, a serialização JSON e a indexação.

Depois que os dados são indexados, as estruturas de dados físicas do índice são bloqueadas. Para obter diretrizes sobre o que pode e o que não pode ser alterado, consulte Atualizar e recompilar um índice.

A indexação não é um processo em segundo plano. Um serviço de pesquisa equilibra a indexação e as cargas de trabalho de consulta, mas quando a latência de consulta for muito alta, você poderá adicionar capacidade ou identificar períodos de baixa atividade de consulta para carregar um índice.

Para obter mais informações, consulte Estratégias de importação de dados.

Use o Portal do Azure

No portal do Azure, use os assistentes de importação para criar e carregar índices em um fluxo de trabalho contínuo. Caso deseje carregar um índice existente, escolha uma abordagem alternativa.

  1. Entre no Portal do Azure com sua conta do Azure e encontre seu serviço de pesquisa.

  2. Na página Visão geral, selecione Importar dados ou Importar e vetorizar dados na barra de comando para criar e preencher um índice de pesquisa.

    Captura de tela do comando Importar dados

    Você pode seguir esses links para revisar o fluxo de trabalho: Início Rápido: criar um índice do IA do Azure Search e Início rápido: vetorização integrada.

  3. Depois de concluído o assistente, use Gerenciador de Pesquisa para verificar os resultados.

Dica

Os assistentes de importação criam e executam indexadores. Se os indexadores já estiverem definidos, redefina e execute um indexador no portal do Azure, o que será útil se você estiver adicionando campos de maneira incremental. A redefinição força o indexador a reiniciar, obtendo todos os campos nos documentos de origem.

Usar as APIs REST

Documents - Index é a API REST para importação de dados para um índice de pesquisa. As APIs REST são úteis para testes iniciais de prova de conceito, nos quais você pode testar fluxos de trabalho de indexação sem precisar gravar muito código. O parâmetro @search.action determina se os documentos são adicionados por completo ou parcialmente em termos de valores novos ou substitutos para campos específicos.

O Início Rápido: Pesquisa de texto com a REST explica as etapas. O exemplo a seguir é uma versão modificada do exemplo. Ele foi cortado para simplificar e o primeiro valor de HotelId foi alterado para evitar a substituição de um documento existente.

  1. Formule uma chamada POST especificando o nome do índice, o ponto de extremidade "docs/index" e um corpo da solicitação que inclua o parâmetro @search.action.

    POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1111",
    "HotelName": "Secret Point Motel",
    "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
    "Category": "Boutique",
    "Tags": [ "pool", "air conditioning", "concierge" ]
    },
    {
    "@search.action": "mergeOrUpload",
    "HotelId": "2",
    "HotelName": "Twin Dome Motel",
    "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
    }
  ]
}

  2. Defina o parâmetro @search.action como upload para criar ou substituir um documento. Defina-o como merge ou uploadOrMerge se estiver direcionando atualizações para campos específicos dentro do documento. O exemplo anterior mostra ambas as ações.

    Ação Efeito
    merge Atualiza um documento que já existe e reprova um documento que não pode ser encontrado. Merge substitui os valores existentes. Por esse motivo, verifique se há campos de coleção que contêm vários valores, como campos do tipo Collection(Edm.String). Por exemplo, se um campo tags começar com um valor de ["budget"] e você executar uma mesclagem com ["economy", "pool"], o valor final do campo tags será ["economy", "pool"]. Não será ["budget", "economy", "pool"].
    mergeOrUpload Comporta-se como mesclar se o documento existir e fazer upload se o documento for novo. Essa é a ação mais comum para atualizações incrementais.
    upload Semelhante a um "upsert" onde o documento é inserido se for novo e atualizado ou substituído se existir. Se o documento tiver valores ausentes que o índice requer, o valor do campo do documento será definido como nulo.

  3. Enviar a solicitação.

  4. Procure os documentos que você acabou de adicionar como uma etapa de validação:

    GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01

Quando a chave ou a ID do documento é nova, null se torna o valor de todos os campos não especificados no documento. Para ações em um documento existente, os valores atualizados substituem os valores anteriores. Os campos que não foram especificados em um "merge" ou um "mergeUpload" serão deixados intactos no índice de pesquisa.

Use os SDKs do Azure

A programação é fornecida nos seguintes SDKs do Azure.

O SDK do Azure para .NET fornece as seguintes APIs para uploads de documentos simples e em massa em um índice:

Há vários exemplos que ilustram a indexação no contexto de indexação simples e em grande escala:

Confira também