Partilhar via

Criar um indexador no Azure AI Search

  • Artigo

Este artigo se concentra nas etapas básicas da criação de um indexador. Dependendo da fonte de dados e do seu fluxo de trabalho, mais configuração pode ser necessária.

Você pode usar um indexador para automatizar a importação e a indexação de dados no Azure AI Search. Um indexador é um objeto nomeado em um serviço de pesquisa que se conecta a uma fonte de dados externa do Azure, lê dados e os passa para um mecanismo de pesquisa para indexação. O uso de indexadores reduz significativamente a quantidade e a complexidade do código que você precisa escrever se estiver usando uma fonte de dados suportada.

Os indexadores suportam dois fluxos de trabalho:

  • Indexação de conteúdo bruto (texto simples ou vetores): extraia cadeias de caracteres e metadados de conteúdo textual para cenários de pesquisa de texto completo. Extrai conteúdo vetorial bruto para pesquisa vetorial (por exemplo, vetores em um banco de dados SQL do Azure ou coleção do Azure Cosmos DB). Neste fluxo de trabalho, a indexação ocorre apenas sobre o conteúdo existente que você fornece.

  • Indexação baseada em habilidades: estende a indexação por meio de habilidades internas ou personalizadas que criam ou geram novo conteúdo pesquisável. Por exemplo, você pode adicionar aprendizado de máquina integrado para análise sobre imagens e texto não estruturado, extraindo ou inferindo texto e estrutura. Ou use habilidades para fragmentar e vetorizar conteúdo de texto e imagens. A indexação baseada em habilidades cria ou gera novo conteúdo que não existe em sua fonte de dados externa. O novo conteúdo torna-se parte do índice quando você adiciona campos ao esquema de índice que aceita os dados de entrada. Para saber mais, consulte Enriquecimento de IA no Azure AI Search.

Pré-requisitos

  • Uma fonte de dados suportada que contém o conteúdo que você deseja ingerir.

  • Uma fonte de dados indexadora que configura uma conexão com dados externos.

  • Um índice de pesquisa que pode aceitar dados recebidos.

  • Esteja abaixo dos limites máximos para o seu nível de serviço. O nível Free permite três objetos de cada tipo e 1-3 minutos de processamento do indexador, ou 3-10 minutos se houver um conjunto de habilidades.

Padrões de indexação

Quando você cria um indexador, a definição é um de dois padrões: indexação baseada em conteúdo ou indexação baseada em habilidades. Os padrões são os mesmos, exceto que a indexação baseada em habilidades tem mais definições.

Exemplo de indexador para indexação baseada em conteúdo

A indexação baseada em conteúdo para pesquisa vetorial ou de texto completo é o principal caso de uso para indexadores. Para este fluxo de trabalho, um indexador se parece com este exemplo.

{
  "name": (required) String that uniquely identifies the indexer,
  "description": (optional),
  "dataSourceName": (required) String indicating which existing data source to use,
  "targetIndexName": (required) String indicating which existing index to use,
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "base64EncodeKeys": false,
    "configuration": {}
  },
  "fieldMappings": (optional) unless field discrepancies need resolution,
  "disabled": null,
  "schedule": null,
  "encryptionKey": null
}

Os indexadores têm os seguintes requisitos:

  • Uma name propriedade que identifica exclusivamente o indexador na coleção de indexadores
  • Uma dataSourceName propriedade que aponta para um objeto de fonte de dados. Ele especifica uma conexão com dados externos
  • Uma targetIndexName propriedade que aponta para o índice de pesquisa de destino

Outros parâmetros são opcionais e modificam comportamentos de tempo de execução, como quantos erros aceitar antes de falhar o trabalho inteiro. Os parâmetros necessários são especificados em todos os indexadores e estão documentados na referência da API REST.

Os indexadores específicos da fonte de dados para blobs, SQL e Azure Cosmos DB fornecem parâmetros extras configuration para comportamentos específicos da fonte. Por exemplo, se a origem for Armazenamento de Blob, você poderá definir um parâmetro que filtre as extensões de arquivo, como:

"parameters" : { "configuration" : { "indexedFileNameExtensions" : ".pdf,.docx" } }

Se a origem for o SQL do Azure, você poderá definir um parâmetro de tempo limite de consulta.

Os mapeamentos de campo são usados para mapear explicitamente campos de origem para destino se houver discrepâncias por nome ou tipo entre um campo na fonte de dados e um campo no índice de pesquisa.

Por padrão, um indexador é executado imediatamente quando você o cria no serviço de pesquisa. Se você não quiser a execução do indexador, defina disabled como true ao criar o indexador.

Você também pode especificar uma agenda ou definir uma chave de criptografia para criptografia suplementar da definição do indexador.

Exemplo de indexador para indexação baseada em competências

A indexação baseada em habilidades usa o enriquecimento de IA para processar conteúdo que não é pesquisável em sua forma bruta. Todas as propriedades e parâmetros acima se aplicam, mas as seguintes propriedades extras são específicas para o enriquecimento da IA: skillSetName, cache, outputFieldMappings.

{
  "name": (required) String that uniquely identifies the indexer,
  "dataSourceName": (required) String, provides raw content that will be enriched,
  "targetIndexName": (required) String, name of an existing index,
  "skillsetName" : (required for AI enrichment) String, name of an existing skillset,
  "cache":  {
    "storageConnectionString" : (required if you enable the cache) Connection string to a blob container,
    "enableReprocessing": true
    },
  "parameters": { },
  "fieldMappings": (optional) Maps fields in the underlying data source to fields in an index,
  "outputFieldMappings" : (required) Maps skill outputs to fields in an index,
}

O enriquecimento da IA é a sua própria área temática e está fora do âmbito deste artigo. Para obter mais informações, comece com Enriquecimento de IA, Conjuntos de habilidades na Pesquisa de IA do Azure, Criar um conjunto de habilidades, Mapear campos de saída enriquecidos e Habilitar cache para enriquecimento de IA.

Preparar dados externos

Os indexadores trabalham com conjuntos de dados. Quando você executa um indexador, ele se conecta à sua fonte de dados, recupera os dados do contêiner ou pasta, opcionalmente os serializa em JSON antes de passá-los para o mecanismo de pesquisa para indexação. Esta seção descreve os requisitos de dados de entrada para indexação baseada em texto.

Dados de origem Tarefas
Documentos JSON Os documentos JSON podem conter texto, números e vetores. Certifique-se de que a estrutura ou a forma dos dados recebidos corresponde ao esquema do seu índice de pesquisa. A maioria dos índices de pesquisa são bastante planos, onde a coleção de campos consiste em campos no mesmo nível. No entanto, estruturas hierárquicas ou aninhadas são possíveis através de campos e coleções complexas.
Relacional Forneça dados como um conjunto de linhas nivelado, onde cada linha se torna um documento de pesquisa completo ou parcial no índice.

Para nivelar dados relacionais em um conjunto de linhas, você deve criar uma exibição SQL ou criar uma consulta que retorne registros pai e filho na mesma linha. Por exemplo, o conjunto de dados de exemplo de hotéis interno é um banco de dados SQL que tem 50 registros (um para cada hotel), vinculados a registros de quarto em uma tabela relacionada. A consulta que nivela os dados coletivos em um conjunto de linhas incorpora todas as informações da sala em documentos JSON em cada registro de hotel. As informações de sala incorporadas são geradas por uma consulta que usa uma cláusula PARA JSON AUTO .

Você pode aprender mais sobre essa técnica em definir uma consulta que retorna JSON incorporado. Este é apenas um exemplo; Você pode encontrar outras abordagens que produzem o mesmo resultado.
Ficheiros Um indexador geralmente cria um documento de pesquisa para cada arquivo, onde o documento de pesquisa consiste em campos para conteúdo e metadados. Dependendo do tipo de arquivo, o indexador às vezes pode analisar um arquivo em vários documentos de pesquisa. Por exemplo, em um arquivo CSV, cada linha pode se tornar um documento de pesquisa autônomo.

Lembre-se de que você só precisa obter dados pesquisáveis e filtráveis:

  • Os dados pesquisáveis são texto ou vetores
  • Os dados filtráveis são texto e números (campos não vetoriais)

O Azure AI Search não pode fazer uma pesquisa de texto completo sobre dados binários em qualquer formato, embora possa extrair e inferir descrições de texto de arquivos de imagem (consulte Enriquecimento de IA) para criar conteúdo pesquisável. Da mesma forma, o texto grande pode ser dividido e analisado por modelos de linguagem natural para encontrar estrutura ou informações relevantes, gerando novo conteúdo que você pode adicionar a um documento de pesquisa. Ele também pode fazer pesquisa vetorial sobre incorporações, incluindo incorporações quantizadas em um formato binário.

Dado que os indexadores não corrigem problemas de dados, outras formas de limpeza ou manipulação de dados podem ser necessárias. Para obter mais informações, consulte a documentação do produto do seu produto de banco de dados do Azure.

Preparar uma fonte de dados

Os indexadores exigem uma fonte de dados que especifique o tipo, o contêiner e a conexão.

  1. Certifique-se de que está a utilizar um tipo de fonte de dados suportado.

  2. Crie uma definição de fonte de dados. As seguintes fontes de dados são algumas das fontes mais utilizadas:

  3. Se a fonte de dados for um banco de dados, como o Azure SQL ou o Cosmos DB, habilite o controle de alterações. O Armazenamento do Azure tem controle de alterações interno por meio da LastModified propriedade em cada blob, arquivo e tabela. Os links para as várias fontes de dados explicam quais métodos de controle de alterações são suportados pelos indexadores.

Preparar um índice

Os indexadores também exigem um índice de pesquisa. Lembre-se de que os indexadores passam dados para o mecanismo de pesquisa para indexação. Assim como os indexadores têm propriedades que determinam o comportamento de execução, um esquema de índice tem propriedades que afetam profundamente como as cadeias de caracteres são indexadas (apenas as cadeias de caracteres são analisadas e tokenizadas).

  1. Comece com Criar um índice de pesquisa.

  2. Configure a coleção de campos e os atributos de campo.

    Os campos são os únicos recetores de conteúdo externo. Dependendo de como os campos são atribuídos no esquema, os valores de cada campo são analisados, tokenizados ou armazenados como cadeias de caracteres literais para filtros, pesquisa difusa e consultas typeahead.

    Os indexadores podem mapear automaticamente os campos de origem para os campos de índice de destino quando os nomes e tipos são equivalentes. Se um campo não puder ser mapeado implicitamente, lembre-se de que você pode definir um mapeamento de campo explícito que diga ao indexador como rotear o conteúdo.

  3. Analise as atribuições do analisador em cada campo. Os analisadores podem transformar cadeias de caracteres. Como tal, as cadeias de caracteres indexadas podem ser diferentes do que você passou. Você pode avaliar os efeitos dos analisadores usando Analisar texto (REST). Para obter mais informações sobre analisadores, consulte Analisadores para processamento de texto.

Durante a indexação, um indexador verifica apenas nomes e tipos de campos. Não há nenhuma etapa de validação que garanta que o conteúdo recebido esteja correto para o campo de pesquisa correspondente no índice.

Criar um indexador

Quando estiver pronto para criar um indexador em um serviço de pesquisa remota, você precisará de um cliente de pesquisa. Um cliente de pesquisa pode ser o portal do Azure, um cliente REST ou um código que instancia um cliente indexador. Recomendamos o portal do Azure ou APIs REST para desenvolvimento inicial e testes de prova de conceito.

  1. Entre no portal do Azure e localize seu serviço de pesquisa.

  2. Na página Visão geral do serviço de pesquisa, escolha entre duas opções:

    • Assistente de importação de dados: o assistente é exclusivo porque cria todos os elementos necessários. Outras abordagens requerem uma fonte de dados e um índice predefinidos.

      Captura de tela que mostra o assistente Importar dados.

    • Adicionar indexador: um editor visual para especificar uma definição de indexador.

      Captura de tela que mostra o botão Adicionar indexador.

Executar o indexador

Por padrão, um indexador é executado imediatamente quando você o cria no serviço de pesquisa. Você pode substituir esse comportamento definindo disabled como true na definição do indexador. A execução do indexador é o momento da verdade onde você descobre se há problemas com conexões, mapeamentos de campo ou construção de conjunto de habilidades.

Há várias maneiras de executar um indexador:

  • Executar na criação ou atualização do indexador (padrão).

  • Executar sob demanda quando não houver alterações na definição ou preceder com reset para indexação completa. Para obter mais informações, consulte Executar ou redefinir indexadores.

  • Agende o processamento do indexador para invocar a execução em intervalos regulares.

A execução agendada geralmente é implementada quando você precisa de indexação incremental para que possa pegar as alterações mais recentes. Como tal, o agendamento depende da deteção de alterações.

Os indexadores são um dos poucos subsistemas que fazem chamadas de saída explícitas para outros recursos do Azure. Em termos de funções do Azure, os indexadores não têm identidades separadas; uma conexão do mecanismo de pesquisa com outro recurso do Azure é feita usando o sistema ou a identidade gerenciada atribuída pelo usuário de um serviço de pesquisa. Se o indexador se conectar a um recurso do Azure em uma rede virtual, você deverá criar um link privado compartilhado para essa conexão. Para obter mais informações sobre conexões seguras, consulte Segurança no Azure AI Search.

Ver resultados

Monitore o status do indexador para verificar o status. A execução bem-sucedida ainda pode incluir avisos e notificações. Certifique-se de verificar as notificações de status bem-sucedidas e com falha para obter detalhes sobre o trabalho.

Para verificação de conteúdo, execute consultas no índice preenchido que retornem documentos inteiros ou campos selecionados.

Deteção de alterações e estado interno

Se sua fonte de dados oferecer suporte à deteção de alterações, um indexador poderá detetar alterações subjacentes nos dados e processar apenas os documentos novos ou atualizados em cada execução do indexador, deixando o conteúdo inalterado como está. Se o histórico de execução do indexador disser que uma execução foi bem-sucedida com 0/0 de documentos processados, isso significa que o indexador não encontrou linhas ou blobs novos ou alterados na fonte de dados subjacente.

A lógica de deteção de alterações é incorporada nas plataformas de dados. A forma como um indexador suporta a deteção de alterações varia consoante a origem dos dados:

Os indexadores controlam o último documento processado a partir da fonte de dados através de uma marca de água alta interna. O marcador nunca é exposto na API, mas internamente o indexador controla onde parou. Quando a indexação é retomada, seja por meio de uma execução agendada ou de uma chamada sob demanda, o indexador faz referência à marca d'água alta para que ela possa continuar de onde parou.

Se você precisar limpar a marca d'água alta para reindexar completamente, você pode usar Redefinir indexador. Para uma reindexação mais seletiva, use Redefinir habilidades ou Redefinir documentos. Por meio das APIs de redefinição, você pode limpar o estado interno e também liberar o cache se tiver habilitado o enriquecimento incremental. Para obter mais informações básicas e comparação de cada opção de redefinição, consulte Executar ou redefinir indexadores, habilidades e documentos.

Conteúdos relacionados