Atualizar e recriar um índice ativo

Informações gerais

Com consultas de pesquisa grandes, a atualização dos índices é importante para ter sempre as informações mais precisas. Hoje você pode atualizar os índices da Pesquisa de vetor usando uma atualização em lote, que permite inserir e excluir pontos de dados com uma programação em lote, ou com a atualização de streaming, que permite atualizar e consultar o índice em alguns segundos.

Além disso, é possível usar UpdateIndex para atualizar campos de metadados importantes, como display_name, description e labels. Também é possível adicionar tags opcionais ao índice para ajudar a diversificar os resultados ou filtrar a consulta pré-índice.

Observação :é possível invocar UpdateIndex para atualizar o conteúdo do índice ou os campos de metadados, mas não ambos em uma única invocação. Por exemplo, para adicionar pontos de dados e atualizar a descrição, é necessário fazer duas invocações separadas.

Atualizar um índice de lote

Para atualizar o conteúdo de um Index existente, use o método IndexService.UpdateIndex.

Para substituir o conteúdo existente de um Index:

• Defina Index.metadata.contentsDeltaUri como o URI do Cloud Storage que inclui os vetores que você quer atualizar.
• isCompleteOverwrite: definido como verdadeiro

Se você definir o campo contentsDeltaUri ao chamar IndexService.UpdateIndex, nenhum outro campo de índice (como displayName, description ou userLabels) também poderá ser atualizado. como parte da mesma chamada.

gcloud

1. Atualize o arquivo de metadados de índices.
2. Use o comandocomando gcloud ai indexes update.

Antes de usar os dados do comando abaixo, faça estas substituições:

• LOCAL_PATH_TO_METADATA_FILE: o caminho local para o arquivo de metadados.
• INDEX_ID: o ID do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o este comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INPUT_DIR: o caminho do diretório do Cloud Storage do conteúdo do índice.
• INDEX_ID: o ID do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

Corpo JSON da solicitação:

{
 "metadata": {
   "contentsDeltaUri": "INPUT_DIR",
   "isCompleteOverwrite": true
 }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID"

PowerShell (Windows)

Observação: o comando a seguir considera que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Console

Use estas instruções para atualizar um conteúdo de índice em lote.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Selecione o índice que você quer atualizar. A página Informações do índice é aberta.
3. Selecione Editar índice. Um painel de edição do índice será aberto.
4. No campo do Cloud Storage, pesquise e selecione a pasta do Cloud Storage em que os dados vetoriais estão armazenados.
5. (Opcional) Marque a caixa de substituição completa se você quiser substituir todos os dados.
6. Clique em Atualizar.
7. Clique em Concluído para fechar o painel.

Se o Index tiver implantações associadas (consulte o campo Index.deployed_indexes), quando certas alterações no Index original estiverem sendo feitas, o DeployedIndex é atualizado de forma assíncrona em segundo plano para refletir essas alterações.

Para verificar se a alteração foi propagada, compare o horário de término da operação de índice de atualização e o DeployedIndex.index_sync_time.

Atualizar um índice de streaming

Com as atualizações de streaming, é possível atualizar e consultar seu índice em alguns segundos. No momento, não é possível usar atualizações por streaming em um índice de atualização de lote. É preciso criar um novo índice. Consulte Criar um índice para atualização de streaming para saber mais.

É cobrado US$ 0,45 por GB usado nas atualizações de streaming. Para saber mais sobre os preços, consulte a página de preços da Vertex AI. As atualizações de streaming são aplicadas diretamente aos índices implantados na memória para que sejam refletidas nos resultados da consulta após um pequeno atraso.

Observação: depois de criar um índice para atualizações por streaming, não é possível executar uma atualização em lote nesse índice. Execute uma substituição completa para usar o índice ou crie um novo índice preparado para atualizações em lote. Consulte Criar um índice para saber mais.

Pontos de dados do comando upsert

Use estes exemplos para saber como inserir e atualizar um ponto de dados. Lembre-se de que upsert-datapoints aceita JSON somente no formato de matriz.

Python

Python

def stream_update_vector_search_index(
    project: str, location: str, index_name: str, datapoints: Sequence[dict]
) -> None:
    """Stream update an existing vector search index

    Args:
      project (str): Required. The Project ID
      location (str): Required. The region name, e.g. "us-central1"
      index_name (str): Required. The index to update. A fully-qualified index
        resource name or a index ID.  Example:
        "projects/123/locations/us-central1/indexes/my_index_id" or
        "my_index_id".
      datapoints: Sequence[dict]: Required. The datapoints to be updated. The dict
        element should be of the IndexDatapoint type.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index with stream_update
    # enabled
    my_index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Upsert the datapoints to the index
    my_index.upsert_datapoints(datapoints=datapoints)

Curl

O limite da cota de capacidade de processamento está relacionado à quantidade de dados incluídos em um comando upsert. Se o ID do ponto de dados existir no índice, o embedding será atualizado. Caso contrário, um novo embedding será adicionado.

  
  DATAPOINT_ID_1=
  DATAPOINT_ID_2=
  curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
  -d '{datapoints: [{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...]},
  {datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...]}]}'
  
  

Console

Console

Use estas instruções para atualizar o conteúdo para um índice de streaming.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Selecione o índice que você quer atualizar. A página Informações do índice é aberta.
3. Selecione Editar índice. Um painel de edição do índice será aberto.
4. No painel, selecione Atualizar ponto de dados para adicionar conteúdo.
5. Insira o ID do ponto de dados.
6. Insira os valores de vetor de elementos do ponto de dados que você quer fazer upsert (atualizar/inserir). Esse campo precisa conter números separados por vírgula (por exemplo: 9,32, 0,12, -2,35).
7. Insira a string.
8. Clique em Atualizar.
9. Clique em Concluído para fechar o painel.

O limite da cota de capacidade de processamento está relacionado à quantidade de dados incluídos em um comando upsert. Se o ID do ponto de dados existir no índice, o embedding será atualizado. Caso contrário, um novo embedding será adicionado.

Atualizar metadados dinâmicos

Há muitos motivos para você atualizar restrições de streaming ou restrições numéricas. Por exemplo, ao lidar com dados de alto volume e movimentação rápida, pode ser necessário priorizar determinados fluxos de dados. Atualizar diretamente restrições ou restrições numéricas permite refinar o foco em tempo real, garantindo que os dados mais importantes sejam processados ou destacados imediatamente.

É possível atualizar diretamente restrições de pontos de dados e restrições numéricas dentro de um índice de streaming sem o custo de compactação da atualização completa.

Para executar essas atualizações somente de metadados, adicione o campo update_mask à solicitação. O valor de update_mask precisa ser definido como all_restricts. Os valores de restrição e de restrição numérica definidos nos pontos de dados precisam ser os novos valores que você quer aplicar à atualização.

O exemplo a seguir mostra como adicionar restrições a dois pontos de dados já existentes.

DATAPOINT_ID_1=
DATAPOINT_ID_2=

curl -H "Content-Type: application/json" -H "Authorization: Bearer gcloud auth print-access-token" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{datapoints:
[{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]},
{datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]}
], update_mask: "all_restricts"}'

Remover pontos de dados

Talvez seja necessário remover os pontos de dados do índice de streaming. É possível fazer isso usando curl ou no console do Google Cloud.

Um caso de uso importante para excluir um ponto de dados de um índice é manter a paridade entre o índice e a origem real dele. Imagine um livraria que usa um embedding de vetor para representar o inventário de livros para fins de pesquisa e recomendação. Quando um livro é esgotado ou removido do estoque, a exclusão do ponto de dados correspondente do índice garante que os resultados da pesquisa e as recomendações permaneçam precisos e atualizados.

Curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/indexes/{INDEX_ID}:removeDatapoints -d '{datapoint_ids: ["'{DATAPOINT_ID_1}'", "'{DATAPOINT_ID_2}'"]}'

Console

Console

Use estas instruções para excluir um ponto de dados do índice de streaming.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Selecione o índice de streaming que você quer atualizar. A página Informações do índice é aberta.
3. Selecione Editar índice. Um painel de edição do índice será aberto.
4. No painel, selecione a guia Remover pontos de dados.
5. Adicione até 20 pontos de dados fornecendo uma lista de IDs de pontos de dados delimitada por vírgulas
6. Clique em Remover.
7. Clique em Concluído para fechar o painel.

Compactação

Periodicamente, seu índice é recriado para considerar todas as novas atualizações desde a última recriação. Essa reconstrução, ou "compactação", melhora o desempenho e a confiabilidade da consulta. As compactações ocorrem para atualizações de streaming e em lote.

• Atualização de streaming: a pesquisa de vetores usa métricas baseadas em heurística para determinar quando acionar a compactação. Se os dados não compactados mais antigos tiverem cinco dias, a compactação será sempre acionada. Você será cobrado pelo custo de recriar o índice pela mesma taxa de uma atualização em lote, além dos custos da atualização de streaming.

• Atualização em lote: ocorre quando o tamanho do conjunto de dados incremental é maior que 20% do tamanho do conjunto de dados base.

Observação: essas compactações ocorrem automaticamente e, quando ocorrem, você recebe um e-mail na caixa de entrada da conta. Se você criou o índice com uma conta de serviço, não receberá um e-mail de aviso de compactação.

Recriar e consultar o índice

Como de costume, envie solicitações de correspondência ou de correspondência em lote com o gRPC cli, a biblioteca de cliente ou o SDK da Vertex AI para Python. Ao recriar a consulta, você pode esperar ver suas atualizações em alguns segundos. Para saber como consultar um índice, veja Consultar índices para ver os vizinhos mais próximos.

Campos opcionais

Ao criar um índice, há alguns campos opcionais que podem ser usados para ajustar suas consultas.

Upsert com restrições

Adicionar o índice e uma restrição é uma maneira de marcar os pontos de dados para que eles já sejam identificados para filtragem no momento da consulta. Você pode adicionar tags de restrição para limitar os resultados apresentados nos seus dados antes que uma consulta seja enviada. Por exemplo, um cliente quer executar uma consulta em um índice, mas quer garantir que os resultados mostrem apenas itens que correspondam a "vermelho" em uma pesquisa por calçados. No exemplo abaixo, o índice está sendo mantido e está filtrando todos os sapatos vermelhos, mas excluindo os azuis. Isso garante que os filtros sejam encontrados nas melhores opções específicas de um índice grande e variado antes da execução.

Além das restrições de token, o exemplo usa restrições numéricas. Nesse caso, o ponto de dados está associado a um preço de 20, um comprimento de 0,3 e uma largura de 0,5. No momento da consulta, use essas restrições numéricas para filtrar os resultados e limitar os resultados da consulta nos valores de preço, comprimento e largura. Por exemplo, esse ponto de dados apareceria em uma consulta que filtra preço > 25, comprimento < 1 e largura < 1.

Para saber mais sobre filtros, consulte Pesquisa de vetor para indexação.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "color", allow_list: ["red"], deny_list: ["blue"]},
    numeric_restricts: [{namespace: "price", value_int: 20}, {namespace: "length", value_float: 0.3}, {namespace: "width", value_double: 0.5}]
  }
]}'

Upsert com o recolhimento

A tag de recolhimento limita os resultados semelhantes, melhorando a diversidade de resultados. O recolhimento é uma restrição em uma lista vizinha produzida por uma pesquisa vizinha mais próxima. Ele exige que, no máximo, um valor de um grupo de resultados retorne o mesmo valor de crowding_attribute. Por exemplo, digamos que você voltou a comprar sapatos on-line. Você quer ver uma ampla variedade de cores nos resultados, mas talvez queira somente um estilo, como chuteiras. Para solicitar que mais de três pares de sapatos com a mesma cor sejam retornados, defina per_crowding_attribute_num_neighbors = 3 na consulta, supondo que você defina Crowding_attribute com a cor dos sapatos ao inserir o ponto de dados.

Esse campo representa o número máximo permitido de correspondências com a mesma tag de recolhimento.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "type", allow_list: ["cleats"]}
    crowding_tag: { crowding_attribute: "red-shoe"},
  }
]}'

A seguir

• Conheça os parâmetros de configuração de índice.
• Saiba como monitorar um índice