Gerenciar um cache de enriquecimento (versão prévia)

Note

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

Um cache de enriquecimento (versão prévia) é um recurso opcional que armazena conteúdo enriquecido criado durante a execução do conjunto de habilidades. Ele preserva o conteúdo entre execuções para que apenas as habilidades e documentos alterados exijam reprocessamento. Não é um backup de: saídas do conjunto de habilidades, estado do indexador ou documentos indexados.

Você cria o cache de enriquecimento no Armazenamento do Azure. O cache contém os resultados da quebra de documento mais as saídas de cada habilidade para cada documento. Embora o cache seja faturável (ele usa Armazenamento do Azure), o custo geral do enriquecimento é reduzido porque os custos de armazenamento são menores do que a extração de imagem e o processamento de IA.

Se você configurar um cache de enriquecimento, este artigo explica como gerenciar atualizações nas habilidades e nas fontes de dados para que você obtenha o máximo proveito dos enriquecimentos em cache.

Pré-requisitos

Limitações

Cuidado

Se você estiver usando o indexador SharePoint (versão prévia), evite o enriquecimento incremental. Em determinadas circunstâncias, o cache se torna inválido. Para recarregá-lo, execute uma redefinição do indexador e uma recompilação completa.

Grandes fontes de dados têm uma limitação de cache adicional.

Cuidado

Para grandes fontes de dados, um cache de enriquecimento pode aumentar o reprocessamento total quando ocorrem habilidades de execução prolongada, interrupções repetidas ou falhas frequentes em habilidades. O indexador prioriza a corretude em vez de minimizar o reprocessamento, de modo que um acúmulo no cache causado por interrupções repetidas amplifica o comportamento de novas tentativas.

Para se recuperar de um acúmulo crescente de cache, particione a fonte de dados em contêineres menores ou pastas virtuais. Em seguida, use indexadores paralelos apontando para o mesmo índice. Para desassociar o cache, defina a cache propriedade como nula no indexador.

Configuração de cache

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

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

O exemplo a seguir ilustra um indexador com cache habilitado. Consulte Configurar o cache de enriquecimento para obter instruções completas.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-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 indexador gerencia o ciclo de vida do cache. Se você excluir um indexador, você também excluirá seu cache. Se você definir a propriedade do indexador como nula ou alterar o cadeia de conexão, o cache existente será excluído durante a próxima execução do cache indexador.

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

Priorizar novos documentos

A cache propriedade inclui um enableReprocessing parâmetro que controla se o conteúdo armazenado em cache é reprocessado. Quando verdadeiro (padrão), o indexador reprocessa documentos armazenados em cache quando você o executa novamente se uma atualização de habilidade os afeta.

Quando falso, o indexador não reprocessa documentos existentes, o que prioriza o novo conteúdo. Defina enableReprocessing como false apenas temporariamente. Mantê-lo verdadeiro na maior parte do tempo garante que os documentos novos e existentes permaneçam válidos para a definição do conjunto de habilidades atual.

Ignorar a avaliação do conjunto de habilidades

Modificar uma habilidade geralmente anda de mãos dadas com o reprocessamento dessa habilidade. No entanto, algumas alterações em uma habilidade não devem disparar o reprocessamento. Por exemplo, implantar uma habilidade personalizada em um novo local ou com uma nova chave de acesso. Essas alterações geralmente são modificações periféricas que não afetam o conteúdo do resultado da habilidade.

Se você souber que uma alteração na habilidade é superficial, substitua a avaliação de habilidade definindo o disableCacheReprocessingChangeDetection parâmetro como verdadeiro:

  1. Chame Atualizar Conjunto de Habilidades e modifique a definição do conjunto de habilidades.
  2. Acrescente o disableCacheReprocessingChangeDetection=true parâmetro na solicitação.
  3. Envie a alteração.

Quando você define esse parâmetro, somente as atualizações para a definição do conjunto de habilidades são confirmadas. A alteração não é avaliada quanto aos efeitos no cache existente. Use uma versão prévia da API, 2020-06-30-Preview ou posterior. Use a API de versão prévia mais recente.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-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 invalida o cache. No entanto, para cenários em que você sabe que uma alteração não deve invalidar o cache - como alterar uma string de conexão ou rotacionar a chave na conta de armazenamento - acrescente o parâmetro ignoreResetRequirement na atualização da fonte de dados. Defina esse parâmetro como true para permitir que a confirmação passe, sem disparar uma condição de redefinição que resultaria em todos os objetos sendo recriados e preenchidos do zero.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

Forçar avaliação de habilidades

A finalidade do cache é evitar o processamento desnecessário. Mas suponha que você faça uma alteração em uma habilidade que o indexador não detecta (por exemplo, alterando algo no código externo, como uma habilidade personalizada).

Nesse caso, use a API de Redefinição de Habilidades para forçar o reprocessamento de uma habilidade específica, incluindo quaisquer habilidades downstream que tenham uma dependência da saída dessa habilidade. Essa API aceita uma solicitação POST com uma lista de habilidades que devem ser invalidadas e marcadas para reprocessamento. Após a redefinição das habilidades, siga com uma solicitação de Execução do Indexador para invocar o processamento do pipeline.

Armazenar documentos específicos em cache novamente

Se você redefinir um indexador, todos os documentos no corpus de pesquisa serão reprocessados.

Em cenários em que apenas alguns documentos precisam ser reprocessados, use Redefinir Documentos (versão prévia) para forçar o reprocessamento de documentos específicos. Quando você redefine um documento, o indexador invalida o cache desse documento. Em seguida, o indexador reprocessa o documento lendo-o da fonte de dados. Para obter mais informações, consulte Executar ou redefinir indexadores, habilidades e documentos.

Para redefinir documentos específicos, inclua uma lista de chaves de documento como lidas no índice de pesquisa na solicitação. Se a chave corresponder a um campo na fonte de dados externa, use o valor do índice de busca.

Dependendo de como você chama a API, a solicitação acrescenta, substitui ou enfileira a lista de chaves:

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

  • Chamar a API com o parâmetro da cadeia de consulta overwrite definido como true substitui a lista atual de chaves do documento a ser redefinida com a carga da solicitação.

  • Chamar a API adiciona as chaves de documento à fila de trabalho que o indexador executa. Quando o indexador for executado novamente, seja conforme agendamento ou sob demanda, ele priorizará o processamento das chaves dos documentos redefinidos antes de quaisquer outras alterações na 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=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Alterações que invalidam o cache

Quando você habilita um cache, o indexador verifica se há alterações na composição do pipeline para decidir qual conteúdo ele pode reutilizar e qual conteúdo precisa ser reprocessado. Esta seção lista as alterações que invalidam o cache, seguidas por alterações que disparam o processamento incremental.

Uma alteração invalidada é aquela em que todo o cache se torna inválido. Por exemplo, atualizar sua fonte de dados é uma alteração invalidante. Aqui está a lista completa de alterações em qualquer parte do pipeline do indexador que invalidam seu cache:

  • Alterando o tipo de fonte de dados
  • Alterando o contêiner da fonte de dados
  • Alterando as credenciais da fonte de dados
  • Alterando a política de detecção de alterações da fonte de dados
  • Alterar a política de detecçã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
    • Armazenar metadados de índice apenas para documentos superdimensionados
    • 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 disparam o processamento incremental

O processamento incremental avalia sua definição de conjunto de habilidades e determina quais habilidades executar novamente. Ele atualiza seletivamente as partes afetadas da árvore de documentos. Aqui está a lista completa de alterações que resultam em enriquecimento incremental:

  • Alterando o tipo de habilidade (atualizando o tipo OData da habilidade)
  • Atualizando parâmetros específicos da habilidade, como uma URL, padrões ou outros parâmetros
  • Alterando saídas de habilidade, como quando a habilidade retorna saídas adicionais ou diferentes
  • Alterar entradas de habilidades que resultam em ancestralidade distinta ou encadeamento de habilidades
  • Qualquer invalidação de habilidade upstream, se você atualizar uma habilidade que forneça uma entrada para essa habilidade
  • Atualizando o local de projeção do repositório de conhecimento, o que resulta na nova projeção de documentos
  • Alterando as projeções do repositório de conhecimento, o que resulta na nova projeção de documentos
  • Alterando mapeamentos de campo de saída em um indexador, o que resulta na nova projeção de documentos para o índice

APIs utilizadas para armazenamento em cache

As APIs de visualização fornecem propriedades extras em indexadores. Use a API de versão prévia mais recente.

Use a versão de disponibilidade geral para conjuntos de habilidades e fontes de dados. Além da documentação de referência, consulte Configurar o cache para enriquecimento incremental para obter detalhes sobre a ordem das operações.

  • Última atualização em