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

  • Artigo

Este artigo explica como importar documentos para um índice de pesquisa predefinido. No Azure AI Search, 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, pesquisa vetorial, pesquisa híbrida e mineração de conhecimento.

  • O conteúdo de texto simples pode ser obtido a partir de campos alfanuméricos na fonte de dados externa, 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 de Pesquisa de IA do Azure que se integram à IA aplicada.

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

Uma vez que os dados são indexados, as estruturas de dados físicas do índice são bloqueadas. Para obter orientação sobre o que pode e o que não pode ser alterado, consulte Atualizar e reconstruir um índice.

A indexação não é um processo em segundo plano. Um serviço de pesquisa equilibrará as cargas de trabalho de indexação e consulta, mas se a latência da 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.

Utilizar 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. Se quiser 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 comandos para criar e preencher um índice de pesquisa.

    Captura de ecrã do comando Importar dados

    Você pode seguir estes links para revisar o fluxo de trabalho: Guia de início rápido: criar um índice de pesquisa de IA do Azure e Guia de início rápido: vetorização integrada.

  3. Após a conclusão do assistente, use o Search Explorer para verificar os resultados.

Gorjeta

Os assistentes de importação criam e executam indexadores. Se os indexadores já estiverem definidos, você poderá redefinir e executar um indexador no portal do Azure, o que será útil se você estiver adicionando campos incrementalmente. A redefinição força o indexador a começar de novo, pegando todos os campos de todos os documentos de origem.

Utilizar APIs REST

Documentos - Índice é a API REST para importar dados para um índice de pesquisa. As APIs REST são úteis para testes iniciais de prova de conceito, onde você pode testar fluxos de trabalho de indexação sem precisar escrever muito código. O @search.action parâmetro determina se os documentos são adicionados na íntegra ou parcialmente em termos de valores novos ou de substituição para campos específicos.

Guia de início rápido: a pesquisa de texto usando REST explica as etapas. O exemplo a seguir é uma versão modificada do exemplo. Foi cortado para maior brevidade e o primeiro valor 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 de solicitação que inclua o @search.action parâmetro.

    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": "Stay-Kay City Hotel",
    "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": "Old Century Hotel",
    "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 @search.action parâmetro como upload para criar ou substituir um documento. Defina-o como merge ou uploadOrMerge se você estiver direcionando atualizações para campos específicos dentro do documento. O exemplo anterior mostra ambas as ações.

    Ação Efeito
    impressão em série Atualiza um documento que já existe e falha em um documento que não pode ser encontrado. A mesclagem substitui os valores existentes. Por esse motivo, certifique-se de verificar se há campos de coleta que contenham vários valores, como campos do tipo Collection(Edm.String). Por exemplo, se um tags campo começar com um valor de ["budget"] e você executar uma mesclagem com ["economy", "pool"], o valor final do tags campo será ["economy", "pool"]. Não será ["budget", "economy", "pool"].
    mergeOrUpload Comporta-se como mesclar se o documento existir e carregar se o documento for novo. Esta é 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 estiver faltando valores que o índice exige, o valor do campo do documento é definido como null.

  3. Envie o pedido.

  4. Procure os documentos que acabou de adicionar como passo de validação:

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

Quando a chave do documento ou ID é novo, null torna-se o valor para qualquer campo que não é especificado no documento. Para ações em um documento existente, os valores atualizados substituem os valores anteriores. Todos os campos que não foram especificados em "merge" ou "mergeUpload" são deixados intactos no índice de pesquisa.

Usar os SDKs do Azure

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

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

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

Consulte também