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.

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 ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

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

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

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

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

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"

$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

{
 "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"
   }
 }
}

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.

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.

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)

  
  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: [...]}]}'
  
  

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 -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}'"]}'

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.

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