Atualizar ou reconstruir um índice no Azure AI Search

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 no novo índice para que você possa evitar alterações no 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 por meio da API REST, mas os SDKs do Azure fornecem funcionalidade equivalente.

O corpo do pedido contém um ou mais documentos a indexar. Os documentos são identificados por uma chave exclusiva que diferencia maiúsculas de minúsculas. Cada documento está associado a uma ação: "upload", "delete", "merge" ou "mergeOrUpload". As solicitações de upload devem incluir os dados do documento como um conjunto de pares chave/valor.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

• Primeiro, use as APIs para carregar documentos, como Documents - Index (REST) ou uma API equivalente nos SDKs do Azure. Para obter mais informações sobre técnicas de indexação, consulte Carregar documentos.

• Para uma atualização grande, o envio em lote (até 1.000 documentos por lote, ou cerca de 16 MB por lote, o que ocorrer primeiro) é recomendado e melhora significativamente o desempenho da indexação.

• Defina o @search.action parâmetro na API 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. Quer utilize o portal do Azure ou uma API para devolver estatísticas de índice, pode esperar um pequeno atraso antes de a eliminação ser refletida no portal do Azure e através 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"]. O mesmo comportamento se aplica a coleções complexas. Se o documento contiver um campo de coleção complexo chamado Salas com um valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }], e você executar uma mesclagem com um valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], o valor final do campo Salas será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ele não acrescentará ou mesclará valores novos e existentes.
  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.

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

Respostas

O código de status 200 é retornado para uma resposta bem-sucedida, o que significa que todos os itens foram armazenados de forma durável e começarão a ser indexados. A indexação é executada em segundo plano e torna novos documentos disponíveis (ou seja, consultáveis e pesquisáveis) alguns segundos após a conclusão da operação de indexação. O atraso específico depende da carga no serviço.

A indexação bem-sucedida é indicada pela propriedade status sendo definida como true para todos os itens, bem como a statusCode propriedade sendo definida como 201 (para documentos recém-carregados) ou 200 (para documentos mesclados ou excluídos):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

O código de status 207 é retornado quando pelo menos um item não foi indexado com êxito. Os itens que não foram indexados têm o campo de status definido como false. As errorMessage propriedades e statusCode indicam o motivo do erro de indexação:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

A errorMessage propriedade indica o motivo do erro de indexação, se possível.

A tabela a seguir explica os vários códigos de status por documento que podem ser retornados na resposta. Alguns códigos de status indicam problemas com a própria solicitação, enquanto outros indicam condições de erro temporárias. Este último você deve tentar novamente após um atraso.

Se o código do cliente encontrar frequentemente uma resposta 207, uma possível razão é que o sistema está sob carga. Você pode confirmar isso verificando a propriedade statusCode para 503. Se o statusCode for 503, recomendamos limitar as solicitações de indexação. Caso contrário, se o tráfego de indexação não diminuir, o sistema poderá começar a rejeitar todas as solicitações com erros 503.

O código de status 429 indica que você excedeu sua cota no número de documentos por índice. Você deve criar um novo índice ou atualizar para limites de capacidade mais altos.

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 por meio da API 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 stored propriedade como false, certifique-se de fornecer o vetor na atualização parcial do documento, mesmo que o valor não seja alterado. Um efeito colateral da configuração stored como false é que os vetores são descartados em uma operação de reindexação. Fornecer o vetor na carga útil dos documentos impede que isso aconteça.

• 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 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}}

Atualizar 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.

Atualizações sem reconstrução

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 synonymMaps
• Adicionar, atualizar ou excluir configurações semânticas
• Adicionar, atualizar ou excluir configurações de CORS

A ordem de operações é:

1. Obtenha a definição do índice.

2. Revise o esquema com atualizações da lista anterior.

3. Atualizar esquema de índice no serviço de pesquisa.

4. 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.

Atualizações que exigem uma reconstrução

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

A ordem de operações é:

1. Obtenha uma definição de índice caso precise dela para referência futura ou para usá-la como base para uma nova versão.

2. 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.

3. 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.

4. Postar um índice revisado, onde o corpo da solicitação inclui definições e configurações de campo alteradas ou modificadas.

5. 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.

Para minimizar a interrupção no código do aplicativo, considere a criação de um alias de índice. O código do aplicativo faz referência ao alias, mas você pode atualizar o nome do índice para o qual o alias aponta.

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 solicitações de consulta no portal do Azure 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. Quer utilize o portal do Azure ou uma API para devolver estatísticas de índice, pode esperar um pequeno atraso antes de a eliminação ser refletida no portal do Azure e nas métricas da API.

1. Identifique qual campo é a chave do documento. No portal do Azure, você pode exibir 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.

2. 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.

3. 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=2024-07-01
   

   GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
   

4. 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=2024-07-01
   Content-Type: application/json   
   api-key: [admin key] 
   {  
     "value": [  
       {  
         "@search.action": "delete",  
         "id": "1111"  
       }  
     ]  
   }
   

Consulte também

• Descrição geral do Indexador
• Indexar grandes conjuntos de dados em escala
• Indexação no portal do Azure
• Indexador do Banco de Dados SQL do Azure
• Azure Cosmos DB para indexador NoSQL
• Indexador de blob do Azure
• Indexador de tabelas do Azure
• Segurança na Pesquisa de IA do Azure