Enriquecimento incremental e armazenamento em cache no Azure AI Search

  • Artigo

Importante

Esta funcionalidade está em pré-visualização pública sob termos de utilização suplementares. A API REST de visualização suporta esse recurso.

O enriquecimento incremental refere-se ao uso de enriquecimentos armazenados em cache durante a execução do conjunto de habilidades para que apenas habilidades e documentos novos e alterados incorram em encargos de processamento pré-pagos para chamadas de API para serviços de IA do Azure. O cache contém a saída da quebra de documentos, além das saídas de cada habilidade para cada documento. Embora o cache seja faturável (ele usa o Armazenamento do Azure), o custo geral do enriquecimento é reduzido porque os custos de armazenamento são menores do que a extração de imagens e o processamento de IA.

Quando você habilita o cache, o indexador avalia suas atualizações para determinar se os enriquecimentos existentes podem ser extraídos do cache. O conteúdo de imagem e texto da fase de quebra de documentos, além de saídas de habilidades que são upstream ou ortogonais para suas edições, provavelmente serão reutilizáveis.

Após a conclusão do processamento do conjunto de habilidades, os resultados atualizados são gravados de volta no cache e também no índice de pesquisa ou no armazenamento de conhecimento.

Limitações

Atenção

Se estiver a utilizar o indexador do SharePoint Online (Pré-visualização), deve evitar o enriquecimento incremental. Em determinadas circunstâncias, o cache torna-se inválido, exigindo uma redefinição e execução do indexador, caso você opte por recarregá-lo.

Configuração da cache

Fisicamente, o cache é armazenado em um contêiner de blob em sua conta de Armazenamento do Azure, um por indexador. A cada indexador é atribuído um identificador de cache exclusivo e imutável que corresponde ao contêiner que está usando.

O cache é criado quando você especifica a propriedade "cache" e executa o indexador. Apenas o conteúdo enriquecido pode ser armazenado em cache. Se o indexador não tiver um conjunto de habilidades anexado, o cache não se aplica.

O exemplo a seguir ilustra um indexador com o cache habilitado. Consulte Ativar cache de enriquecimento para obter instruções completas. Observe que, ao adicionar a propriedade cache, use uma versão da API de visualização, 2020-06-30-Preview ou posterior, na solicitação.

POST https://[search service name].search.windows.net/indexers?api-version=2020-06-30-Preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Gerenciamento de cache

O ciclo de vida do cache é gerenciado pelo indexador. Se um indexador for excluído, seu cache também será excluído. Se a cache propriedade no indexador for definida como null ou a cadeia de conexão for alterada, o cache existente será excluído na próxima execução do indexador.

Embora o enriquecimento incremental seja projetado para detetar e responder a alterações sem intervenção de sua parte, há parâmetros que você pode usar para invocar comportamentos específicos:

Priorizar novos documentos

A propriedade cache inclui um enableReprocessing parâmetro. Ele é usado para controlar o processamento de documentos recebidos já representados no cache. Quando true (padrão), os documentos que já estão no cache são reprocessados quando você executa novamente o indexador, supondo que sua atualização de habilidade afete esse documento.

Quando falsos, os documentos existentes não são reprocessados, priorizando efetivamente o conteúdo novo e recebido sobre o conteúdo existente. Você só deve definir enableReprocessing como false em uma base temporária. Ter enableReprocessing definido como true na maioria das vezes garante que todos os documentos, novos e existentes, sejam válidos de acordo com a definição atual do conjunto de habilidades.

Ignorar a avaliação do conjunto de competências

A modificação de uma habilidade e o reprocessamento dessa habilidade normalmente andam de mãos dadas. No entanto, algumas alterações em uma habilidade não devem resultar em reprocessamento (por exemplo, implantar uma habilidade personalizada em um novo local ou com uma nova chave de acesso). Muito provavelmente, trata-se de modificações periféricas que não têm impacto genuíno na substância do resultado da habilidade em si.

Se você sabe que uma mudança na habilidade é realmente superficial, você deve substituir a avaliação de habilidade definindo o disableCacheReprocessingChangeDetection parâmetro como true:

  1. Chame Update Skillset e modifique a definição do conjunto de habilidades.
  2. Anexe o parâmetro "disableCacheReprocessingChangeDetection=true" na solicitação.
  3. Envie a alteração.

A definição desse parâmetro garante que apenas as atualizações na definição do conjunto de habilidades sejam confirmadas e que a alteração não seja avaliada quanto a efeitos no cache existente. Use uma versão da API de visualização, 2020-06-30-Preview ou posterior.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2020-06-30-Preview&disableCacheReprocessingChangeDetection

Ignorar verificações de validação da fonte de dados

A maioria das alterações em uma definição de fonte de dados invalidará o cache. No entanto, para cenários em que você sabe que uma alteração não deve invalidar o cache - como alterar uma cadeia de conexão ou girar a chave na conta de armazenamento - acrescente o ignoreResetRequirement parâmetro na atualização da fonte de dados. Definir esse parâmetro como true permite que a confirmação seja executada, sem acionar uma condição de redefinição que resultaria em todos os objetos sendo reconstruídos e preenchidos do zero.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2020-06-30-Preview&ignoreResetRequirement

Avaliação do conjunto de competências de força

O objetivo do cache é evitar processamento desnecessário, mas suponha que você faça uma alteração em uma habilidade que o indexador não deteta (por exemplo, alterar algo em código externo, como uma habilidade personalizada).

Nesse caso, você pode usar as Habilidades de Redefinição para forçar o reprocessamento de uma habilidade específica, incluindo quaisquer habilidades downstream que dependam da saída dessa habilidade. Esta API aceita uma solicitação POST com uma lista de habilidades que devem ser invalidadas e marcadas para reprocessamento. Depois de Redefinir habilidades, siga com uma solicitação Run Indexer para invocar o processamento do pipeline.

Armazenar novamente documentos específicos em cache

A reposição de um indexador resultará no reprocessamento de todos os documentos do corpus de pesquisa. Em cenários em que apenas alguns documentos precisam ser reprocessados, use Redefinir documentos (visualização) para forçar o reprocessamento de documentos específicos. Quando um documento é redefinido, o indexador invalida o cache desse documento, que é reprocessado lendo-o da fonte de dados. Para obter mais informações, consulte Executar ou redefinir indexadores, habilidades e documentos.

Para redefinir documentos específicos, a solicitação fornece uma lista de chaves de documento conforme lidas no índice de pesquisa. Se a chave for mapeada para um campo na fonte de dados externa, o valor fornecido deverá ser o usado no índice de pesquisa.

Dependendo de como você chamar a API, a solicitação acrescentará, substituirá ou enfileirará a lista de chaves:

  • Chamar a API várias vezes com chaves diferentes acrescenta as novas chaves à lista de chaves de documento redefinidas.

  • Chamar a API com o parâmetro de cadeia de caracteres de consulta "substituir" definido como true substituirá a lista atual de chaves de documento a serem redefinidas com a carga útil da solicitação.

  • Chamar a API resulta apenas na adição das chaves de documento à fila de trabalho que o indexador executa. Quando o indexador for invocado pela próxima vez, conforme agendado ou sob demanda, ele priorizará o processamento das chaves do documento de redefinição antes de quaisquer outras alterações da fonte de dados.

O exemplo a seguir ilustra uma solicitação de redefinição de documento:

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2020-06-30-Preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Alterações que invalidam o cache

Depois de habilitar um cache, o indexador avalia as alterações na composição do pipeline para determinar qual conteúdo pode ser reutilizado e qual precisa ser reprocessado. Esta seção enumera as alterações que invalidam o cache definitivamente, seguidas por alterações que acionam o processamento incremental.

Uma alteração inválida é aquela em que todo o cache não é mais válido. Um exemplo de alteração inválida é aquele em que sua fonte de dados é atualizada. Aqui está a lista completa de alterações em qualquer parte do pipeline do indexador que invalidariam seu cache:

  • Alterando o tipo de fonte de dados
  • Alterando o contêiner da fonte de dados
  • Alterando credenciais de fonte de dados
  • Alterando a política de deteção de alterações da fonte de dados
  • Alterando a política de deteção de exclusão da fonte de dados
  • Alterando mapeamentos de campo do indexador
  • Alterando os parâmetros do indexador:
    • Modo de análise
    • Extensões de nome de arquivo excluídas
    • Extensões de nome de arquivo indexado
    • Indexar metadados de armazenamento apenas para documentos de grandes dimensões
    • Cabeçalhos de texto delimitados
    • Delimitador de texto delimitado
    • Raiz do documento
    • Ação da imagem (alterações na forma como as imagens são extraídas)

Alterações que acionam o processamento incremental

O processamento incremental avalia a definição do conjunto de competências e determina quais as competências a voltar a executar ao atualizar seletivamente as partes afetadas da árvore de documentos. Aqui está a lista completa de alterações que resultam em enriquecimento incremental:

  • Alterar o tipo de habilidade (o tipo OData da habilidade é atualizado)
  • Parâmetros específicos de habilidade são atualizados, por exemplo, uma URL, padrões ou outros parâmetros
  • A saída de habilidade muda, a habilidade retorna saídas adicionais ou diferentes
  • A entrada de habilidades muda resultando em ancestralidade diferente, o encadeamento de habilidades mudou
  • Qualquer invalidação de habilidade upstream, se uma habilidade que fornece uma entrada para essa habilidade for atualizada
  • Atualizações no local de projeção do armazenamento de conhecimento resultam na reprojeção de documentos
  • Alterações nas projeções do armazenamento de conhecimento, resultados na reprojeção de documentos
  • Mapeamentos de campo de saída alterados em um indexador resultam na reprojeção de documentos para o índice

APIs usadas para armazenamento em cache

A versão 2020-06-30-Preview da API REST ou posterior fornece enriquecimento incremental por meio de propriedades adicionais em indexadores. Conjuntos de habilidades e fontes de dados podem usar a versão geralmente disponível. Além da documentação de referência, consulte Configurar cache para enriquecimento incremental para obter detalhes sobre a ordem das operações.

Próximos passos

O enriquecimento incremental é um recurso poderoso que estende o controle de alterações a conjuntos de habilidades e enriquecimento de IA. O enriquecimento incremental permite a reutilização do conteúdo processado existente à medida que você itera sobre o design do conjunto de habilidades. Como próxima etapa, habilite o cache em seus indexadores.

Habilitar o cache para enriquecimento incremental