Habilitar o cache para enriquecimento incremental no Azure AI Search

Artigo
12/10/2024

Importante

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

Este artigo explica como adicionar cache a um pipeline de enriquecimento para que você possa modificar as etapas de enriquecimento downstream sem ter que reconstruir totalmente sempre. Por padrão, um conjunto de habilidades é sem monitoração de estado, e alterar qualquer parte de sua composição requer uma reexecuçã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 detetadas nas definições do conjunto de habilidades ou do indexador. A produção processada existente é preservada e reutilizada sempre que possível.

O conteúdo armazenado em cache é colocado no Armazenamento do 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. Deve ser considerado um componente interno gerido pelo seu serviço de pesquisa e não deve ser modificado.

Pré-requisitos

Armazenamento do Azure para armazenar enriquecimentos em cache. A conta de armazenamento deve ser de uso geral v2.
Somente para indexação de blob, se você precisar de remoção sincronizada de documentos 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 essa política, a exclusão de documentos do cache não é suportada.

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

Atenção

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

Ativar em novos indexadores

Você pode usar o portal do Azure, APIs de visualização ou SDKs beta do Azure são 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, fonte de dados e conjunto de habilidades existentes.
Habilite o cache incremental e defina a conta de Armazenamento do Azure.

Em novos indexadores, adicione a propriedade "cache" na carga útil de definição do indexador ao chamar Create ou Update Indexer.

Você pode usar as versões de visualização da API 2021-04-30-preview e posteriores. Recomendamos a visualização mais recente para Criar ou atualizar indexador (2024-05-01-preview).

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-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": []
    }

Ativar em indexadores existentes

Para indexadores existentes que já têm um conjunto de habilidades, use as etapas a seguir para adicionar cache. Como uma operação única, redefina e execute novamente o indexador na íntegra para carregar o cache.

Etapa 1: Obter a definição do indexador

Comece com um indexador de trabalho 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 da API de visualização para o indexador GET, uma propriedade "cache" definida como null é adicionada à definição automaticamente.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-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) enableReprocessing Boolean Property (true por padrão), indica que o enriquecimento incremental está habilitado. Defina como false se você deseja suspender o processamento incremental enquanto outras operações que consomem muitos recursos, como a indexação de novos documentos, estão em andamento e, em seguida, alterne novamente para true mais tarde.

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-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

Redefinir indexador é necessário ao configurar o enriquecimento incremental para indexadores existentes para garantir que todos os documentos estejam em um estado consistente. Você pode usar o portal do Azure ou um cliente de API para essa tarefa.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Etapa 4: salvar o indexador

Atualize o indexador com uma solicitação PUT, onde o corpo da solicitação inclui "cache".

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

Se você agora emitir outra solicitação GET no indexador, a resposta do serviço incluirá uma ID propriedade no objeto de cache. A cadeia de caracteres é acrescentada ao nome do contêiner contendo todos os resultados armazenados em cache e o estado intermediário de cada documento processado por esse indexador. O ID é usado para nomear exclusivamente o cache no armazenamento de Blob.

    "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 do Azure ou a API. No portal do Azure, na lista de indexadores, selecione o indexador e selecione Executar. Uma vantagem de usar o portal do Azure é que você pode monitorar o status do indexador, anotar 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=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Nota

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

Verifique se há saída em cache

Localize o cache no Armazenamento do Azure, em contêiner de Blob. 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 e, em seguida, compare as métricas de antes e depois para o tempo de execução e as contagens de documentos.

Habilidades que incluem análise de imagem e reconhecimento ótico de caracteres (OCR) de documentos digitalizados são bons casos de teste. 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 OCR do cache, atualizando e processando apenas as alterações relacionadas ao texto indicadas por suas edições. Você pode esperar ver menos documentos na contagem de documentos de execução do indexador, tempos de execução mais curtos e menos cobranças em sua fatura.

O conjunto de arquivos usado em 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. Mude en para es ou outro idioma na habilidade de tradução de texto para teste de prova de conceito de enriquecimento incremental.

Erros comuns

O seguinte erro ocorre se você esquecer de especificar uma versão da API de visualização 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 400 Bad Request também ocorrerá se você não tiver um requisito de indexador. A mensagem de erro especifica quaisquer dependências ausentes.

Próximos passos

O enriquecimento incremental é aplicável em indexadores que contêm conjuntos de habilidades, fornecendo conteúdo reutilizável para índices e armazenamentos de conhecimento. Os links a seguir fornecem mais informações sobre cache e conjuntos de habilidades.

Partilhar via