Gerir uma cache para enriquecimento (pré-visualização)

Note

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Importante

Funcionalidades, capacidades ou propriedades assinaladas (pré-visualização) não são abrangidas por um acordo de nível de serviço, não são recomendadas para cargas de trabalho em produção e podem mudar ou ser limitadas antes de se tornarem geralmente disponíveis. Os termos de pré-visualização do Pesquisa de IA do Azure aplicam-se a todas as funcionalidades de pré-visualização, sejam independentes ou parte de uma funcionalidade geralmente disponível.

Uma memória cache de enriquecimento (pré-visualização) é um recurso opcional que armazena conteúdo enriquecido gerado durante a execução do conjunto de competências. Preserva o conteúdo entre execuções, de modo que apenas competências e documentos alterados precisam de ser reprocessados. Não é uma cópia de segurança dos resultados do conjunto de competências, do estado do indexador ou de documentos indexados.

Crias a cache de enriquecimento no Armazenamento do Azure. A cache contém a saída da quebra de documentos, mais as saídas de cada habilidade para cada documento. Embora a cache seja faturável (utiliza Armazenamento do Azure), o custo global de enriquecimento é reduzido porque os custos de armazenamento são inferiores aos da extração de imagem e processamento de IA.

Se configurar uma cache de enriquecimento, este artigo explica como gerir as atualizações das aptidões e das fontes de dados para tirar o máximo partido dos enriquecimentos armazenados em cache.

Pré-requisitos

Limitações

Cautela

Se estiver a usar o indexador SharePoint (pré-visualização), evite o enriquecimento incremental. Em certas circunstâncias, a cache torna-se inválida. Para o recarregar, faz um reset do indexador e uma reconstrução completa.

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

Cautela

Para grandes fontes de dados, um cache de enriquecimento pode aumentar o reprocessamento total quando ocorrem competências de longa duração, interrupções repetidas ou falhas frequentes de competência. O indexador dá prioridade à correção em vez de minimizar o reprocessamento, pelo que uma acumulação na cache causada por interrupções repetidas intensifica o comportamento de repetição de tentativas.

Para recuperar de um acúmulo crescente de cache, particione a fonte de dados em contentores mais pequenos ou pastas virtuais. Depois usa indexadores paralelos que apontam para o mesmo índice. Para dissociar a cache, defina a cache propriedade como nula no indexador.

Configuração da cache

Fisicamente, a cache é armazenada num contentor de blob e em tabelas na sua conta Armazenamento do Azure, uma por indexador. Cada indexador recebe um identificador de cache único e imutável que corresponde ao contentor que está a usar.

A cache é criada quando especificas a cache propriedade e executas o indexador. Apenas conteúdos enriquecidos podem ser armazenados em cache. Se o teu indexador não tiver um conjunto de competências associado, então o cache não se aplica.

O exemplo seguinte ilustra um indexador com cache ativada. Consulte Configurar cache de enriquecimento para 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": []
    }

Gestão de cache

O indexador gere o ciclo de vida da cache. Se eliminares um indexador, também eliminas a cache dele. Se definir a propriedade do cache indexador como nula ou alterar a cadeia de ligação, a cache existente é eliminada durante a próxima execução do indexador.

Embora o enriquecimento incremental seja concebido para detetar e responder a mudanças sem qualquer intervenção da sua parte, 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 em cache é reprocessado. Quando é verdadeiro (por defeito), o indexador reprocessa documentos em cache quando o reexecuta, caso uma atualização de skill os afete.

Quando falso, o indexador não reprocessa documentos existentes, o que dá prioridade ao novo conteúdo. Defina enableReprocessing para falso apenas temporariamente. Mantê-lo verdadeiro na maior parte do tempo garante que tanto os documentos novos como os existentes permanecem válidos para a definição atual do conjunto de competências.

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

Modificar uma competência normalmente anda de mãos dadas com reprocessar essa competência. No entanto, algumas alterações numa competência não deveriam desencadear um reprocessamento. Por exemplo, implementar uma habilidade personalizada num novo local ou com uma nova chave de acesso. Estas alterações são geralmente modificações periféricas que não afetam a substância do resultado da habilidade.

Se souber que uma alteração à competência é superficial, anule a avaliação da competência definindo o disableCacheReprocessingChangeDetection parâmetro para verdadeiro:

  1. Chame Update Skillset e modifique a sua definição.
  2. Adicione o disableCacheReprocessingChangeDetection=true parâmetro ao pedido.
  3. Submete a alteração.

Quando defines este parâmetro, apenas as atualizações da definição do conjunto de competências são confirmadas. A alteração não é avaliada quanto aos efeitos na cache existente. Utilize uma versão de pré-visualização da API, 2020-06-30-Preview ou posterior. Use a API de pré-visualização 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 à definição de uma fonte de dados invalida a cache. No entanto, para cenários em que sabe que uma alteração não deve invalidar a cache – como alterar uma cadeia de conexão ou rotacionar a chave na conta de armazenamento – adicione o parâmetro ignoreResetRequirement à atualização da fonte de dados. Defina este parâmetro como true para permitir que o commit avance, sem ativar uma condição de reset que resultaria em todos os objetos serem reconstruídos e preenchidos do zero.

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

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

O objetivo da cache é evitar processamento desnecessário. Mas suponha que faz uma alteração numa competência que o indexador não detetou (por exemplo, alterar algo em código externo, como uma competência personalizada).

Neste caso, utilize a API Reset Skills para forçar o reprocessamento de uma competência específica, incluindo quaisquer competências subsequentes que tenham uma dependência do resultado dessa competência. Esta API aceita um pedido POST com uma lista de competências que devem ser invalidadas e marcadas para reprocessamento. Após o Reset Skills, segue um pedido Run Indexer para invocar o processamento do pipeline.

Re-cache de documentos específicos

Se redefinir um indexador, todos os documentos do corpus de pesquisa são reprocessados.

Em cenários em que apenas alguns documentos precisem de ser reprocessados, use Reset Documents (preview) para forçar o reprocessamento de documentos específicos. Quando reinicias um documento, o indexador invalida a cache desse documento. O indexador reprocessa então o documento lendo-o da fonte de dados. Para mais informações, consulte Executar ou redefinir indexadores, competências e documentos.

Para repor documentos específicos, inclua no pedido uma lista de chaves de documentos conforme lidas no índice de procura. Se a chave corresponde a um campo na fonte de dados externa, use o valor do índice de pesquisa.

Dependendo de como invocas a API, o pedido ou acrescenta, sobrescreve ou coloca a lista de chaves em fila de espera:

  • Chamar a API várias vezes com chaves diferentes adiciona as novas chaves à lista de chaves do documento para reiniciar.

  • Ao chamar a API com o parâmetro da cadeia de consulta overwrite definido como true, a lista atual de chaves de documentos a repor é substituída pelo payload do pedido.

  • Chamar a API adiciona as chaves do documento à fila de trabalho que o indexador realiza. Quando o indexador é novamente invocado, seja conforme programado ou a pedido, prioriza o processamento das chaves de redefinição do documento antes de quaisquer outras alterações na fonte de dados.

O exemplo seguinte ilustra um pedido 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 a cache

Quando ativas uma cache, o indexador verifica alterações na composição do teu pipeline para decidir que conteúdo pode reutilizar e qual precisa de reprocessamento. Esta secção lista alterações que invalidam a cache, seguidas de alterações que desencadeiam o processamento incremental.

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

  • Alteração do tipo de fonte de dados
  • Alteração do contentor de fonte de dados
  • Alteração das credenciais da fonte de dados
  • Alteração da política de deteção de alterações à fonte de dados
  • Alteração da política de deteção de eliminação de fontes de dados
  • Alterar os mapeamentos de campos do indexador
  • Alterar parâmetros do indexador:
    • Modo de Análise Sintática
    • Nomes de Ficheiros com Extensões Excluídas
    • Extensões de Nomes de Ficheiros Indexados
    • Metadados de armazenamento de índice apenas para documentos sobredimensionados
    • 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 desencadeiam o processamento incremental

O processamento incremental avalia a definição do teu conjunto de competências e determina quais as competências a repetir. Atualiza 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 (atualizar o tipo OData da habilidade)
  • Atualização de parâmetros específicos da competência, como URL, padrões ou outros parâmetros
  • Alterar as saídas da competência, como quando a competência devolve saídas adicionais ou diferentes
  • Alterar entradas de habilidades que resultam em diferentes ascendências ou cadeias de habilidades
  • Qualquer invalidação de competência a montante, se atualizares uma competência que forneça uma entrada para essa competência
  • Atualização da localização da projeção do repositório de conhecimento, o que resulta na reprojeção dos documentos
  • Alterar as projeções do armazenamento de conhecimento, o que resulta na reprojeção dos documentos
  • Alterar os mapeamentos dos campos de saída num indexador, o que resulta na re-projeção dos documentos para o índice

APIs usadas para cache

As APIs de Pré-visualização fornecem propriedades extra nos indexadores. Use a API de pré-visualização mais recente.

Use a versão geralmente disponível para conjuntos de competências e fontes de dados. Para além da documentação de referência, consulte Configurar cache para enriquecimento incremental para detalhes sobre a ordem das operações.

  • Última atualização a