Compartilhar via

Enriquecimento incremental e cache no Azure AI Search

  • Artigo

Importante

Esse recurso está em versão prévia pública nos termos de uso complementares. A versão prévia da API REST dá suporte a esse recurso.

O enriquecimento incremental refere-se ao uso de enriquecimentos em armazenar em cache durante a execução do conjunto de habilidades, de modo que somente as habilidades e os documentos novos e alterados incorram em taxas de processamento pagas conforme o uso para chamadas de API aos serviços de IA 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 o Azure Armazenamento), o custo geral de enriquecimento é reduzido porque os custos de armazenamento são menores que a extração de imagem e o processamento de IA.

Para garantir a sincronização entre os dados da fonte de dados e o índice, é importante entender sua fonte de dados exclusiva os pré-requisitos de controle de alteração e exclusão. Este guia aborda especificamente como gerenciar modificações incrementais em termos de processamento de habilidades e como utilizar o cache para essa finalidade.

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

Depois que o processamento do conjunto de habilidades for concluído, os resultados atualizados serão gravados novamente no cache e também no índice de pesquisa ou no repositório de conhecimento.

Limitações

Cuidado

Se você estiver usando o indexador do SharePoint Online (versão prévia), evite o enriquecimento incremental. Em determinadas circunstâncias, o cache se torna inválido, exigindo uma redefinição e execução do indexador, caso você opte por recarregá-lo.

Configuração do cache

Fisicamente, o cache é armazenado em um contêiner de blob na sua conta de Armazenamento do Azure, um 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 propriedade "cache" e executa o indexador. Somente o conteúdo aprimorado 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. Confira Habilitar o cache de enriquecimento para obter instruções completas.

Para usar a propriedade cache, você pode usar 2020-06-30-preview ou posterior ao criar ou atualizar um indexador. Recomendamos a API de visualização mais recente.

POST https://[search service name].search.windows.net/indexers?api-version=2024-05-01-rreview
    {
        "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á. Se a propriedade cache no indexador for definida como nulo ou a cadeia de conexão for alterada, o cache existente será excluído.

Embora o aperfeiçoamento incremental seja projetado para detectar e responder a alterações sem intervenção de sua parte, há parâmetros que podem ser usados para invocar os comportamentos padrão:

Priorizar novos documentos

A propriedade de cache inclui um parâmetro enableReprocessing. É utilizada para controlar o processamento de documentos de entrada já representados no cache. Quando true (padrão), os documentos que já estão no cache serão reprocessados quando executar novamente o indexador, supondo que sua atualização de habilidades afete esse documento.

Quando false, os documentos existentes não são reprocessados, priorizando efetivamente o conteúdo novo e de entrada em relação ao conteúdo existente. Você só deve definir enableReprocessing como false em uma base temporária. Ter enableReprocessing definido como verdadeiro na maior parte do tempo garante que todos os documentos, novos e existentes, sejam válidos de acordo com a definição do conjunto de habilidades atual.

Ignorar a avaliação do conjunto de habilidades

A modificação de uma habilidade e o reprocessamento dessa habilidade normalmente andam lado a lado. 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). Provavelmente, essas são modificações periféricas que não têm nenhum impacto original sobre a substância da saída da habilidade em si.

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

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

Definir esse parâmetro garante que apenas atualizações do conjunto de habilidades sejam confirmadas e que a alteração não seja avaliada quanto aos efeitos no cache existente. Use uma versão de API de versão preliminar, 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=2024-05-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 parâmetro ignoreResetRequirement na atualização da fonte de dados. Definir esse parâmetro como true permite que a confirmação continue, sem disparar uma condição de redefinição que resultaria em todos os objetos sendo recriados e populados a partir do zero.

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

Forçar avaliação do conjunto de habilidades

A finalidade do cache é evitar o processamento desnecessário, mas suponha que 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, é possível usar Redefinir habilidades para forçar o reprocessamento de uma determinada habilidade, incluindo quaisquer habilidades de downstream que tenham uma dependência na 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 novamente em cache documentos específicos

Redefinir um indexador fará com que todos os documentos no corpus de pesquisa sejam reprocessados.

Em cenários em que apenas alguns documentos precisam ser reprocessados, use Redefinir documentos (versão preliminar) para forçar o reprocessamento de documentos específicos. Quando um documento é redefinido, o indexador invalida seu cache para esse documento, que é reprocessado lendo-o na 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 como lidas no índice de pesquisa. Se a chave for mapeada para um campo na fonte de dados externa, o valor que você fornecer deverá ser aquele usado no índice de pesquisa.

Dependendo de como você chama a API, a solicitação acrescentará, substituirá ou colocará na fila 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 “substituir” consulta de cadeia de caracteres definido como true substituirá a lista atual de chaves do documento a ser redefinida com a carga da solicitação.

  • Chamar a API resulta apenas nas chaves de documento que estão sendo adicionadas à fila de trabalho que o indexador executa. Quando o indexador for invocado, seja como agendado ou sob demanda, ele priorizará o processamento das chaves de redefinição do documento antes de qualquer outra alteração 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=2024-05-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 que exige reprocessamento. Esta seção enumera as alterações que invalidam o cache totalmente, seguida por alterações que disparam o processamento incremental.

Uma alteração que causa invalidação faz com que o cache inteiro deixe de ser válido. Um exemplo de alteração que causa invalidação é aquela em que a fonte de dados é atualizada. Aqui está a lista completa de alterações em qualquer parte do pipeline do indexador que invalidaria seu cache:

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

Alterações que disparam o processamento incremental

O processamento incremental avalia a definição de habilidades e determina quais habilidades executar novamente, atualizando 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 de OData da habilidade é atualizado)
  • Atualização de parâmetros específicos da habilidade, por exemplo, a URL, padrões ou outros parâmetros
  • Alterações nas saídas da habilidade, a habilidade retorna saídas adicionais ou diferentes
  • Alterações de entrada de habilidades resultando em ancestrais diferentes, o encadeamento de habilidades foi alterado
  • 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 repositório de conhecimento resultam em nova projeção de documentos
  • Alterações nas projeções do repositório de conhecimento resultam em nova projeção de documentos
  • Alterações nos mapeamentos do campo de saída de um indexador resultam em nova projeção de documentos para o índice

APIs usadas para cache

A versão da API REST 2020-06-30-Preview ou posterior fornece enriquecimento incremental por meio de propriedades extras em indexadores. Recomendamos a API de visualização mais recente.

Conjunto de habilidades e fontes de dados podem usar a versão disponível para o público geral. Além da documentação de referência, confira Configurar o Cache para aprimoramento incremental para obter detalhes sobre a ordem das operações.

Próximas etapas

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

Habilitar o cache para enriquecimento incremental