Atualizar ou reconstruir um índice no Azure AI Search

Artigo
07/04/2024

Este artigo explica como atualizar um índice existente no Azure AI Search com alterações de esquema ou alterações de conteúdo por meio de indexação incremental. Ele explica as circunstâncias em que as reconstruções são necessárias e fornece recomendações para mitigar os efeitos das reconstruções em solicitações de consulta em andamento.

Durante o desenvolvimento ativo, é comum descartar 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 alterar o código do aplicativo.

Atualizar conteúdo

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

Use 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, consulte Carregar documentos.

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

Ação	Efeito
delete	Remove todo o documento do índice. Se você quiser remover um campo individual, use mesclar 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. Se você usa o portal ou uma API para retornar estatísticas de índice, você pode esperar um pequeno atraso antes que a exclusão seja refletida no portal e por meio de APIs.
impressão em série	Atualiza um documento que já existe e falha em um documento que não pode ser encontrado. A mesclagem substitui os valores existentes. Por esse motivo, certifique-se de verificar se há campos de coleta que contenham vários valores, como campos do tipo `Collection(Edm.String)`. Por exemplo, se um `tags` campo começar com um valor de `["budget"]` e você executar uma mesclagem com `["economy", "pool"]`, o valor final do `tags` campo será `["economy", "pool"]`. Não será `["budget", "economy", "pool"]`.
mergeOrUpload	Comporta-se como mesclar se o documento existir e carregar se o documento for novo. Esta é 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 estiver faltando valores que o índice exige, o valor do campo do documento é definido como null.

Publique 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

Os 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, poderá executá-lo em uma agenda 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, use mergeOrUpload como a ação de pesquisa.
A carga deve incluir as chaves ou identificadores de cada documento que você deseja adicionar, atualizar ou excluir.
Para atualizar o conteúdo de campos e subcampos simples em tipos complexos, liste apenas os campos que deseja alterar. Por exemplo, se você só precisa atualizar um campo de descrição, a carga útil deve consistir na chave do documento e na descrição modificada. Omitir outros campos mantém seus valores existentes.
Para mesclar alterações embutidas na coleção de cadeias de caracteres, forneça o valor inteiro. Lembre-se do tags exemplo de campo da seção anterior. Novos valores substituem os valores antigos de um campo inteiro e não há mesclagem no conteúdo de um campo.

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

### Get Secret Point Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

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

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Secret Point 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=2023-11-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ê pode 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 campo novo
Definir o retrievable atributo em um campo existente
Atualizar searchAnalyzer em um campo com 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 de operações é:

Obtenha a definição do índice.
Revise o esquema com atualizações da lista anterior.
Atualizar esquema de índice no serviço de pesquisa.
Atualize o conteúdo do índice para corresponder ao 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 pelo Azure AI Search.

Não deve haver interrupções de consulta durante as atualizações, mas os resultados da consulta variam à medida que as atualizações entram em vigor.

Soltar e reconstruir um índice

Algumas modificações exigem uma queda de índice e reconstrução, substituindo um índice atual por um novo.

Ação	Descrição
Eliminar um campo	Para remover fisicamente todos os vestígios de um campo, é necessário reconstruir o índice. Quando uma reconstrução imediata não é prática, você pode modificar o código do aplicativo para redirecionar o acesso para longe de um campo obsoleto ou usar searchFields e selecionar parâmetros de consulta 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 reconstruçã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ável, filtrável, classificável, 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. Você pode adicionar uma nova definição de analisador a um índice a qualquer momento, mas só pode atribuir um analisador quando o campo for criado. Isso é verdadeiro para as propriedades do analisador e do indexAnalyzer. A propriedade searchAnalyzer é uma exceção (você pode atribuir essa propriedade a um campo existente).
Atualizar ou excluir uma definição de analisador em um índice	Não é possível excluir ou alterar uma configuração existente do analisador (analisador, tokenizador, filtro de token ou filtro char) no índice, a menos que você reconstrua todo o índice.
Adicionar um campo a um sugeridor	Se um campo já existir e você quiser adicioná-lo a uma construção Sugestões , reconstrua o índice.
Alternar níveis	Não há suporte para atualizações in-loco. Se você 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. Este aplicativo faz backup do seu índice para uma série de arquivos JSON e, em seguida, recria o índice em um serviço de pesquisa que você especificar.

A ordem de operações é:

Obtenha uma definição de índice caso precise dela para referência futura ou para usá-la como base para uma nova versão.
Considere o uso de 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.
Solte o índice existente. As consultas direcionadas ao índice são imediatamente descartadas. Lembre-se de que excluir um índice é irreversível, destruindo o armazenamento físico para a coleção de campos e outras construções.
Postar um índice revisado, onde o corpo da solicitação inclui 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.

Quando você cria 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 que não são pesquisáveis podem ser usados em filtros ou expressões, mas não têm índices invertidos e não são de texto completo ou pesquisáveis difusos. 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.

Equilibrando cargas de trabalho

A indexação não é executada em segundo plano, mas o serviço de pesquisa equilibrará quaisquer trabalhos de indexação em relação a consultas contínuas. Durante a indexação, você pode monitorar as solicitações de consulta no portal para garantir que as consultas sejam concluídas em tempo hábil.

Se as cargas de trabalho de indexação introduzirem níveis inaceitáveis de latência de consulta, realize análises de desempenho e analise essas dicas de desempenho para obter uma possível atenuaçã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 do documento de pesquisa retornará o documento específico. Para testes mais amplos, você deve esperar até que o índice seja totalmente carregado e, em seguida, usar consultas para verificar o contexto 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 depois de atualizar um índice, mas lembre-se de esperar um pequeno atraso à medida que o serviço processa a alteração e contabilizar as taxas de atualização do portal, que podem ser de alguns minutos.

Eliminar documentos órfãos

O Azure AI Search dá suporte a operações no nível do 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. Se você usa o portal ou uma API para retornar estatísticas de índice, você pode esperar um pequeno atraso antes que a exclusão seja refletida no portal e nas métricas da API.

Identifique qual campo é a chave do documento. No portal, é possível visualizar os campos de cada índice. As chaves de documento são campos de cadeia de caracteres e são indicadas com um ícone de chave para facilitar a sua localização.
Verifique os valores do campo chave do documento: search=*&$select=HotelId. Uma cadeia de caracteres simples é simples, mas se o índice usa um campo codificado em base 64 ou se os documentos de pesquisa foram gerados a partir de uma parsingMode configuração, você pode estar trabalhando com valores com os quais não está familiarizado.
Procure o documento para verificar o valor do ID do documento e para rever o seu conteúdo antes de o eliminar. Especifique a chave ou 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.
```
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2023-11-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2023-11-01
```

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

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

Partilhar via