Partilhar via

Gerenciar um cache de enriquecimento

Important

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

Um cache de enriquecimento é um recurso opcional que armazena conteúdo enriquecido reutilizável criado durante a execução do conjunto de habilidades, de modo que apenas habilidades e documentos novos e alterados incorram em encargos de processamento padrão durante o processamento futuro do indexador e do conjunto de habilidades.

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.

Se você configurou um cache de enriquecimento, este artigo explica como gerenciar atualizações de habilidades e fontes de dados para obter o máximo de utilidade dos enriquecimentos em cache.

Prerequisites

Limitations

Caution

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 do indexador e uma reconstrução completa, caso você opte por recarregá-lo.

Configuração de cache

Fisicamente, o cache é armazenado em um contêiner ou tabela 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 Configurar cache de enriquecimento para obter instruções completas.

Para definir a propriedade de cache, use a API REST de visualização mais recente para Criar ou Atualizar Indexador ou um pacote SDK do Azure de visualização que forneça o recurso. Você também pode habilitar o cache de enriquecimento no assistente de importação de dados no portal do Azure.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2025-08-01-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. Enviar 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. Recomendamos a API de visualização mais recente.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2025-08-01-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=2025-08-01-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=2025-08-01-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

As APIs de visualização fornecem propriedades extras em indexadores. Recomendamos a API de visualização mais recente.

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.