Criar um indexador no Azure AI Search

  • Artigo

Use um indexador para automatizar a importação e 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 baseada em texto, extrair cadeias de caracteres e metadados de conteúdo textual para cenários de pesquisa de texto completo.

  • Indexação baseada em habilidades, usando habilidades internas ou personalizadas que adicionam aprendizado de máquina integrado para análise sobre imagens e conteúdo indiferenciado grande, extraindo ou inferindo texto e estrutura. A indexação baseada em habilidades permite a pesquisa sobre conteúdo que, de outra forma, não seria facilmente pesquisável em texto completo. Para saber mais, consulte Enriquecimento de IA no Azure AI Search.

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.

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 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 texto ou enriquecimento de IA com 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 texto

A indexação baseada em texto para pesquisa de texto completo é o principal caso de uso para indexadores e, para esse 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: "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

Os indexadores também impulsionam o enriquecimento da IA. Todas as propriedades e parâmetros acima para se aplicam, mas as seguintes propriedades extras são específicas para o enriquecimento de 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 de enriquecimento 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 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-o 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:

  • Dados pesquisáveis são texto.
  • Os dados filtráveis são alfanuméricos.

O Azure AI Search não pode pesquisar dados binários em nenhum 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.

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. A lista a seguir é algumas das fontes de dados usadas com mais frequência:

  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 acima 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. Inicie sessão no portal do Azure.

  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 na medida em que cria todos os elementos necessários. Outras abordagens requerem uma fonte de dados e um índice predefinidos.

    • New Indexer, um editor visual para especificar uma definição de indexador.

    A captura de tela a seguir mostra onde você pode encontrar esses recursos no portal.

    indexador de hotéis

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 na Pesquisa de IA do Azure.

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 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.

Próximos passos