Atualizar ou reconstruir um índice no IA do Azure Search

Artigo
09/03/2024

Esse artigo explica como atualizar um índice existente no IA do Azure Search com alterações de esquema ou alterações de conteúdo através de indexação incremental. Explica as circunstâncias sob as quais as reconstruções são necessárias e fornece recomendações para mitigar os efeitos das reconstruções em pedidos de consulta em curso.

Durante o desenvolvimento ativo, é comum remover e reconstruir índices quando você está iterando sobre o design do índice. A maioria dos desenvolvedores trabalha com uma pequena amostra representativa de seus dados para que a reindexação seja mais rápida.

Para alterações de esquema em aplicativos já em produção, recomendamos criar e testar um novo índice que execute lado a lado um índice existente. Use um alias de índice para trocar o novo índice, evitando alterações no código do aplicativo.

Atualizar conteúdo

A indexação incremental e a sincronização de um índice em relação às alterações nos dados de origem são fundamentais para a maioria dos aplicativos de pesquisa. Essa seção explica o fluxo de trabalho para atualizar o conteúdo do campo em um índice de pesquisa.

Utilize as mesmas técnicas para carregar documentos: Documentos - Índice (REST) ou uma API equivalente nos SDKs do Azure. Para obter mais informações sobre técnicas de indexação, veja Carregar documentos.

Defina o parâmetro @search.action para determinar o efeito nos documentos existentes:

Ação	Efeito
excluir	Remove todo o documento do índice. Se você quiser remover um campo individual, use merge em vez disso, definindo o campo em questão como nulo. Documentos e campos excluídos não liberam espaço imediatamente no índice. A cada poucos minutos, um processo em segundo plano executa a exclusão física. Quer você use o portal ou uma API para retornar estatísticas de índice, poderá esperar um pequeno atraso antes que a exclusão seja refletida no portal e por meio de APIs.
merge	Atualiza um documento que já existe e reprova um documento que não pode ser encontrado. Merge substitui os valores existentes. Por esse motivo, verifique se há campos de coleção que contêm vários valores, como campos do tipo `Collection(Edm.String)`. Por exemplo, se um campo `tags` começar com um valor de `["budget"]` e você executar uma mesclagem com `["economy", "pool"]`, o valor final do campo `tags` será `["economy", "pool"]`. Não será `["budget", "economy", "pool"]`.
mergeOrUpload	Comporta-se como mesclar se o documento existir e fazer upload se o documento for novo. Essa é a ação mais comum para atualizações incrementais.
upload	Semelhante a um "upsert" onde o documento é inserido se for novo e atualizado ou substituído se existir. Se o documento tiver valores ausentes que o índice requer, o valor do campo do documento será definido como nulo.

Poste a atualização.

As consultas continuam a ser executadas, mas se você estiver atualizando ou removendo campos existentes, poderá esperar resultados mistos e uma maior incidência de limitação.

Dicas para indexação incremental

Indexadores automatizam a indexação incremental. Se você puder usar um indexador e se a fonte de dados oferecer suporte ao controle de alterações, você poderá executar o indexador em uma programação recorrente para adicionar, atualizar ou substituir conteúdo pesquisável para que ele seja sincronizado com seus dados externos.
Se você estiver fazendo chamadas de índice diretamente pela API de push, use mergeOrUpload como ação de pesquisa.
A carga deve incluir as chaves ou identificadores de cada documento que você deseja adicionar, atualizar ou excluir.
Se o índice incluir campos vetoriais e você definir a propriedade stored como falsa,lembre-se de incluir o vetor na atualização parcial do documento, mesmo que o valor não tenha mudado. Um efeito colateral de definir stored como falso é que os vetores são descartados durante uma operação de reindexação. Fornecer o vetor no conteúdo dos documentos evita que isso aconteça.
Para atualizar o conteúdo de campos simples e subcampos em tipos complexos, liste apenas os campos que deseja alterar. Por exemplo, se você precisar apenas atualizar um campo de descrição, a carga deverá consistir na chave do documento e na descrição modificada. A omissão de outros campos mantém seus valores existentes.
Para mesclar alterações embutidas em uma coleção de cadeia de caracteres, forneça o valor inteiro. Lembre-se do exemplo do campo tags da seção anterior. Os novos valores substituem os valores antigos de um campo inteiro, e não há mesclagem dentro do conteúdo de um campo.

Aqui está um exemplo de API REST demonstrando essas dicas:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Alterar um esquema de índice

O esquema de índice define as estruturas de dados físicas criadas no serviço de pesquisa, portanto, não há muitas alterações de esquema que você possa fazer sem incorrer em uma reconstrução completa. A lista a seguir enumera as alterações de esquema que podem ser introduzidas perfeitamente em um índice existente. Geralmente, a lista inclui novos campos e funcionalidades usadas durante a execução da consulta.

Adicionar um novo campo
Defina o atributo retrievable em um campo existente
Atualizar searchAnalyzer em um campo que já possui um indexAnalyzer
Adicionar uma nova definição de analisador em um índice (que pode ser aplicado a novos campos)
Adicionar, atualizar ou excluir perfis de pontuação
Adicionar, atualizar ou excluir configurações de CORS
Adicionar, atualizar ou excluir synonymMaps
Adicionar, atualizar ou excluir configurações semânticas

A ordem das operações é:

Obtenha a definição do índice.
Revise o esquema com atualizações da lista anterior.
Atualize o esquema de índice no serviço de pesquisa.
Atualize o conteúdo do índice para corresponder ao seu esquema revisado se você adicionou um novo campo. Para todas as outras alterações, o conteúdo indexado existente é usado no estado em que se encontra.

Quando você atualiza um esquema de índice para incluir um novo campo, os documentos existentes no índice recebem um valor nulo para esse campo. No próximo trabalho de indexação, os valores dos dados de origem externa substituem os nulos adicionados pela Pesquisa de IA do Azure.

Não deve haver interrupções nas consultas durante as atualizações, mas os resultados das consultas poderão variar à medida que as atualizações entrarem em vigor.

Remover e recompilar um índice

Algumas modificações exigem a remoção e a recompilação do índice, substituindo um índice atual por um novo.

Ação	Descrição
Excluir um campo	Para remover fisicamente todos os rastreamentos de um campo, você precisa recriar o índice. Quando uma reconstrução imediata não for prática, você poderá modificar o código do aplicativo para redirecionar o acesso de um campo obsoleto ou usar os parâmetros de consulta searchFields e select para escolher quais campos serão pesquisados e retornados. Fisicamente, a definição e o conteúdo do campo permanecem no índice até a próxima recompilação, quando você aplica um esquema que omite o campo em questão.
Alterar uma definição de campo	As revisões de um nome de campo, tipo de dados ou atributos de índice específicos (pesquisáveis, filtráveis, classificáveis, facetable) exigem uma reconstrução completa.
Atribuir um analisador a um campo	Os analisadores são definidos em um índice, atribuídos a campos e, em seguida, invocados durante a indexação para informar como os tokens são criados. É possível adicionar uma nova definição de analisador a um índice a qualquer momento, mas só é possível atribuir um analisador quando o campo é criado. Isso é verdadeiro para as propriedades analyzer e indexAnalyzer. A propriedade searchAnalyzer é uma exceção (é possível atribuir essa propriedade a um campo existente).
Atualizar ou excluir uma definição de analisador em um índice	Não é possível excluir nem alterar uma configuração de analisador existente (analisador, gerador de token, filtro de token ou filtro de caracteres) no índice, a menos que você reconstrua todo o índice.
Adicionar um campo a um sugestor	Se um campo já existir e você quiser adicioná-lo a uma construção Sugestores, reconstrua o índice.
Alternar camadas	Não há suporte para atualizações in-loco. Se precisar de mais capacidade, crie um novo serviço e reconstrua seus índices do zero. Para ajudar a automatizar esse processo, você pode usar o código de exemplo index-backup-restore neste repositório de exemplo .NET do Azure AI Search. Esse aplicativo faz backup do seu índice em uma série de arquivos JSON e, em seguida, recria o índice em um serviço de pesquisa especificado.

A ordem das operações é:

Obtenha uma definição de índice caso você precise dela para referência futura ou para usar como base para uma nova versão.
Considere usar uma solução de backup e restauração para preservar uma cópia do conteúdo do índice. Existem soluções em C# e em Python. Recomendamos a versão Python porque é mais atualizada.

Se você tiver capacidade em seu serviço de pesquisa, mantenha o índice existente enquanto cria e testa o novo.
Elimine o índice existente. As consultas direcionadas ao índice são descartadas imediatamente. Lembre-se de que a exclusão de um índice é irreversível, pois destrói o armazenamento físico para a coleção de campos e outros constructos.
Publique um índice revisado, onde o corpo da solicitação inclua definições e configurações de campo alteradas ou modificadas.
Carregue o índice com documentos de uma fonte externa. Os documentos são indexados usando as definições e configurações de campo do novo esquema.

Ao criar o índice, o armazenamento físico é alocado para cada campo no esquema de índice, com um índice invertido criado para cada campo pesquisável e um índice vetorial criado para cada campo vetorial. Os campos não pesquisáveis podem ser usados em filtros ou expressões, mas não têm índices invertidos e não são pesquisáveis em texto completo ou difuso. Em uma reconstrução de índice, esses índices invertidos e índices vetoriais são excluídos e recriados com base no esquema de índice fornecido.

Balanceamento de cargas de trabalho

A indexação não é executada em segundo plano, mas o serviço de pesquisa balanceia os trabalhos de indexação em relação a consultas em andamento. Durante a indexação, você pode monitorar solicitações de consulta no portal para garantir que as consultas sejam completadas em tempo hábil.

Se as cargas de trabalho de indexação apresentarem níveis inaceitáveis de latência de consulta, realize uma análise de desempenho e examine estas dicas de desempenho para possível mitigação.

Verificar se há atualizações

Você pode começar a consultar um índice, assim que o primeiro documento for carregado. Se você souber a ID de um documento, a API REST de Procurar documento retorna o documento específico. Para testes mais amplos, você deve aguardar até que o índice seja totalmente carregado e, em seguida, usar consultas para verificar o contexto em que você espera ver.

Você pode usar o Search Explorer ou um cliente REST para verificar se há conteúdo atualizado.

Se você adicionou ou renomeou um campo, use $select para retornar esse campo: search=*&$select=document-id,my-new-field,some-old-field&$count=true.

O portal do Azure fornece o tamanho do índice e o tamanho do índice vetorial. Você pode verificar esses valores após atualizar um índice, mas lembre-se de esperar um pequeno atraso enquanto o serviço processa a alteração e de levar em conta as taxas de atualização do portal, que podem levar alguns minutos.

Excluir documentos órfãos

O Azure AI Search dá suporte a operações de nível de documento para que você possa pesquisar, atualizar e excluir um documento específico isoladamente. O exemplo a seguir mostra como excluir um documento.

A exclusão de um documento não libera espaço imediatamente no índice. A cada poucos minutos, um processo em segundo plano executa a exclusão física. Quer você use o portal ou uma API para retornar estatísticas de índice, você pode esperar um pequeno atraso antes que a exclusão seja refletida nas métricas do portal e da API.

Identifique qual campo é a chave do documento. No portal, você pode ver os campos de cada índice. Chaves de documento são campos de cadeia de caracteres e apresentam um ícone de chave para facilitar a identificação.
Verifique os valores do campo de chave do documento: search=*&$select=HotelId. Uma cadeia de caracteres simples é básica, mas se o índice usar um campo codificado em base 64 ou se os documentos de pesquisa forem gerados por uma configuração parsingMode, você poderá estar trabalhando com valores com os quais não está familiarizado.
Procure o documento para verificar o valor da ID do documento e para examinar o conteúdo antes de excluí-lo. Especifique a chave ou a ID do documento na solicitação. Os exemplos a seguir ilustram uma cadeia de caracteres simples para o índice de exemplo Hotels e uma cadeia de caracteres codificada em base 64 para a chave metadata_storage_path do índice cog-search-demo index.
```
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
```

Exclua o documento usando delete @search.action para removê-lo do índice de pesquisa.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Compartilhar via