Habilitar o cache para enriquecimento incremental na IA do Azure Search

Artigo
03/11/2024

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.

Este artigo explica como adicionar o cache a um pipeline de enriquecimento para modificar as etapas de enriquecimento de downstream sem precisar recompilar todas as vezes. Por padrão, um conjunto de habilidades é sem estado, e a alteração de qualquer parte de sua composição requer uma execução completa do indexador. Com um cache de enriquecimento, o indexador pode determinar quais partes da árvore de documentos devem ser atualizadas com base nas alterações detectadas no conjunto de habilidades ou nas definições do indexador. A saída processada existente é preservada e reutilizada sempre que possível.

O conteúdo armazenado em cache é colocado no Armazenamento do Microsoft Azure usando as informações de conta que você fornece. O contêiner, chamado ms-az-search-indexercache-<alpha-numerc-string>, é criado quando você executa o indexador. Ele deve ser considerado um componente interno gerenciado pelo serviço de pesquisa e não deve ser modificado.

Pré-requisitos

Armazenamento do Microsoft Azure para armazenar enriquecimentos armazenados em cache. A conta de armazenamento deve ser do tipo v2 para uso geral.
Somente para indexação de blobs, se você precisar de remoção de documento sincronizada do cache e do índice quando os blobs forem excluídos da fonte de dados, habilite uma política de exclusão no indexador. Sem esta política, não há suporte para a exclusão de documentos do cache.

Você deve estar familiarizado com a configuração de indexadores. Comece com a visão geral do indexador e continue em conjuntos de habilidades para saber mais sobre pipelines de enriquecimento. Para obter mais informações sobre os principais conceitos, confira enriquecimento incremental.

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.

Habilitação em novos indexadores

Você pode usar o portal do Azure, as APIs de visualização ou os SDKs beta do Azure, necessários para habilitar um cache de enriquecimento em um indexador.

Portal do Azure
REST

À esquerda, selecione Indexadores e, em seguida, selecione Adicionar indexador.
Forneça um nome de indexador e um índice, uma fonte de dados e um conjunto de habilidades existentes.
Habilite o cache incremental e defina a conta de Armazenamento do Microsoft Azure.

Em novos indexadores, adicione a propriedade "cache" na carga de definição do indexador ao chamar Criar ou atualizar o indexador (2021-04-30-Preview). Você também pode usar a versão prévia anterior da API, a 2020-06-30-Preview.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

Habilitação em indexadores existentes

Nos indexadores existentes que já tiverem um conjunto de habilidades, siga as etapas a seguir para adicionar o cache. Como uma operação única, redefina e execute novamente o indexador de forma completa para carregar o cache.

Etapa 1: obter a definição do indexador

Comece com um indexador válido que tenha estes componentes: fonte de dados, conjunto de habilidades, índice. Usando um cliente de API, envie uma solicitação GET Indexer para recuperar o indexador. Quando você usa a versão prévia da API para obter o indexador, uma propriedade "cache" definida como nula é adicionada automaticamente às definições.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Etapa 2: definir a propriedade de cache

Na definição de índice, modifique "cache" para incluir as seguintes propriedades obrigatórias e opcionais:

(Obrigatório) storageConnectionString deve ser definido como uma cadeia de conexão do Armazenamento do Azure.
(Opcional) A propriedade booliana enableReprocessing (true por padrão) indica que o enriquecimento incremental está habilitado. Defina como false para suspender o processamento incremental enquanto outras operações com uso intensivo de recursos, como a indexação de novos documentos, estão em andamento e, em seguida, altere novamente para true.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Etapa 3: redefinir o indexador

Uma redefinição de indexador é necessária ao configurar o enriquecimento incremental para os indexadores existentes a fim de garantir que todos os documentos estejam em um estado consistente. Você pode usar o portal ou um cliente de API para esta tarefa.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Etapa 4: salvar o indexador

Atualize o indexador (2021-04-30-Preview) com uma solicitação PUT, em que o corpo da solicitação inclua "cache".

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

Se agora você emitir outra solicitação GET no indexador, a resposta do serviço incluirá uma propriedade ID no objeto de cache. A cadeia de caracteres alfanumérica é anexada ao nome do contêiner que contém todos os resultados armazenados em cache e o estado intermediário de cada documento processado por esse indexador. A ID é usada para nomear exclusivamente o cache no Armazenamento de Blobs.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

Etapa 5: executar o indexador

Para executar o indexador, você pode usar o portal ou a API. No portal, na lista de indexadores, selecione o indexador e selecione Executar. Uma vantagem de usar o portal é que você pode monitorar o status do indexador, observar a duração do trabalho e quantos documentos são processados. As páginas do portal são atualizadas a cada poucos minutos.

Como alternativa, você pode usar REST para executar o indexador:

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Observação

Uma redefinição e uma nova execução do indexador resulta em uma recompilação completa para que o conteúdo possa ser armazenado em cache. Todos os enriquecimentos cognitivos serão executados novamente em todos os documentos. A reutilização de conteúdos enriquecidos do cache começa depois que o cache é carregado.

Verificar a saída armazenada em cache

Localize o cache no Armazenamento do Azure, em Contêiner de blobs. O nome do contêiner é ms-az-search-indexercache-<some-alphanumeric-string>.

Um cache é criado e usado por um indexador. Seu conteúdo não é legível por humanos.

Para verificar se o cache está operacional, modifique um conjunto de habilidades e execute o indexador, em seguida, compare as métricas antes e depois do tempo de execução e as contagens de documentos.

Os conjuntos de habilidades que incluem análises de imagem e OCR (reconhecimento óptico de caracteres) de documentos digitalizados são casos de teste adequados. Se você modificar uma habilidade de texto downstream ou qualquer habilidade que não esteja relacionada à imagem, o indexador poderá recuperar toda a imagem processada anteriormente e o conteúdo do OCR do cache, atualizando e processando apenas as alterações relacionadas ao texto indicadas por suas edições. Você deve ver menos documentos na contagem de documentos de execução do indexador, tempos de execução menores e menos encargos em sua fatura.

O conjunto de arquivos usado nos tutoriais cog-search-demo é um caso de teste útil porque contém 14 arquivos de vários formatos (JPG, PNG, HTML, DOCX, PPTX e outros tipos). Altere en para es ou outro idioma na habilidade de tradução de texto para testes de prova de conceito de enriquecimento incremental.

Erros comuns

O seguinte erro ocorrerá se você esquecer de especificar uma versão prévia de API na solicitação:

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

Um erro de solicitação inválida 400 também ocorrerá se você estiver perdendo um requisito do indexador. A mensagem de erro especifica as dependências ausentes.

Próximas etapas

O enriquecimento incremental é aplicável a indexadores que contêm conjuntos de habilidades e fornece conteúdo reutilizável para índices e repositórios de conhecimento. Os links a seguir fornecem mais informações sobre o cache e os conjuntos de habilidades.