Aggiorna e ricrea un indice attivo

Panoramica

Nel caso di query di ricerca di grandi dimensioni, l'aggiornamento degli indici è importante per avere sempre le informazioni più precise. Oggi puoi aggiornare gli indici di Vector Search utilizzando un aggiornamento batch, che consente di inserire ed eliminare punti dati tramite una pianificazione batch o con un aggiornamento di flussi di dati, che consente di aggiornare ed eseguire query sull'indice in pochi secondi.

Inoltre, puoi utilizzare UpdateIndex per aggiornare i campi dei metadati importanti, come display_name, description e labels. Puoi anche aggiungere tag facoltativi all'indice per diversificare i risultati o filtrare le query pre-indice.

Aggiorna un indice batch

Per aggiornare i contenuti di un elemento Index esistente, utilizza il metodo IndexService.UpdateIndex.

Per sostituire i contenuti esistenti di un elemento Index esistente:

• Imposta Index.metadata.contentsDeltaUri sull'URI Cloud Storage che include i vettori che vuoi aggiornare.
• Imposta isCompleteOverwrite su true.

Se imposti il campo contentsDeltaUri durante la chiamata a IndexService.UpdateIndex, non è possibile aggiornare anche altri campi di indice (come displayName, description o userLabels) nell'ambito della stessa chiamata.

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 http://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 \
     "http://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 "http://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 a Index sono associati deployment (vedi il campo Index.deployed_indexes), quando vengono apportate determinate modifiche all'elemento Index originale, DeployedIndex viene aggiornato automaticamente in background in modo asincrono per riflettere queste modifiche.

Per verificare se la modifica è stata propagata, confronta l'ora di fine delle operazioni dell'indice di aggiornamento e il valore DeployedIndex.index_sync_time.

Aggiorna un indice di streaming

Con gli aggiornamenti in modalità flusso, puoi aggiornare ed eseguire query sull'indice in pochi secondi. Al momento, non puoi utilizzare gli aggiornamenti in modalità flusso su un indice di aggiornamento batch esistente, devi creare un nuovo indice. Per scoprire di più, consulta Creare un indice per l'aggiornamento dei flussi di dati.

Ti vengono addebitati 0,45 $per GB utilizzati per gli aggiornamenti in streaming. Per scoprire di più sui prezzi, consulta la pagina dei prezzi di Vertex AI. Gli aggiornamenti dei flussi di dati vengono applicati direttamente agli indici di cui è stato eseguito il deployment in memoria, che vengono poi riportati nei risultati delle query dopo un breve ritardo.

Punti dati upsert

Utilizza questi esempi per scoprire come eseguire l'upsert di un punto dati. Tieni presente che upsert-datapoints accetta JSON solo in formato array.

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`" http://${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: [...]}]}'
  
  

Il limite della quota di velocità effettiva è correlato alla quantità di dati inclusa in un upsert. Se l'ID punto dati esiste nell'indice, l'incorporamento viene aggiornato, altrimenti viene aggiunto un nuovo incorporamento.

Aggiornamento dei metadati dinamici

Ci sono molti motivi per cui potresti dover aggiornare limitazioni per i flussi di dati o restrizioni numeriche. Ad esempio, quando hai a che fare con dati ad alto volume e in rapida evoluzione, potresti voler dare la priorità a determinati stream di dati. L'aggiornamento diretto di limitazioni o restrizioni numeriche consente di perfezionare l'impostazione in tempo reale, assicurando che i dati più importanti vengano elaborati o evidenziati immediatamente.

Puoi aggiornare direttamente le restrizioni dei punti dati e le restrizioni numeriche all'interno di un indice di flussi di dati senza il costo di compattazione dell'aggiornamento completo.

Per eseguire questi aggiornamenti solo sui metadati, devi aggiungere il campo update_mask alla richiesta. Il valore di update_mask deve essere impostato su all_restricts. I valori di limitazione e di limitazione numerici impostati nei punti dati devono essere i nuovi valori che vuoi applicare nell'aggiornamento.

L'esempio seguente mostra come aggiungere limitazioni a due punti dati esistenti.

DATAPOINT_ID_1=
DATAPOINT_ID_2=

curl -H "Content-Type: application/json" -H "Authorization: Bearer gcloud auth print-access-token" http://${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"}'

Rimuovi punti dati

Potresti dover rimuovere i punti dati dall'indice di streaming. Puoi farlo utilizzando curl o dalla console Google Cloud.

Un caso d'uso chiave per l'eliminazione di un punto dati da un indice è mantenere la parità tra l'indice e la sua origine reale. Prendiamo come esempio un venditore di libri che utilizza l'incorporamento vettoriale per rappresentare l'inventario dei libri a scopo di ricerca e suggerimento. Quando un libro è esaurito o non è più disponibile, l'eliminazione del punto dati corrispondente dall'indice garantisce che i risultati di ricerca e i suggerimenti siano precisi e aggiornati.

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

Compattazione

Periodicamente, l'indice viene ricreato per tenere conto di tutti i nuovi aggiornamenti dall'ultima ricreazione. Questa ricompilazione, o "compazione", migliora l'affidabilità e le prestazioni delle query. Le compattazioni avvengono sia per gli aggiornamenti in modalità flusso che per gli aggiornamenti batch.

• Aggiornamento dei flussi di dati: Vector Search utilizza metriche basate su euristiche per determinare quando attivare la compattazione. Se i dati non compatti meno recenti risalgono a cinque giorni, la compattazione viene sempre attivata. Ti viene addebitato il costo della creazione dell'indice alla stessa velocità di un aggiornamento batch, oltre ai costi di aggiornamento dei flussi di dati.

• Aggiornamento batch: si verifica quando la dimensione incrementale del set di dati è superiore al 20% della dimensione di base del set di dati.

Ricrea ed esegui query sull'indice

Puoi inviare richieste di corrispondenza o di corrispondenza in batch come di consueto con l'interfaccia a riga di comando grpc, la libreria client o l'SDK Vertex AI per Python. Quando ricrei la query, puoi aspettarti di vedere gli aggiornamenti entro pochi secondi. Per scoprire come eseguire query su un indice, vedi Eseguire query sugli indici per ottenere i vicini più prossimi.

Campi facoltativi

Quando crei un indice, puoi usare alcuni campi facoltativi per perfezionare le query.

Esegui upsert con limitazioni

L'upsert dell'indice e l'aggiunta di una limitazione è un modo per eseguire il tagging dei punti dati in modo che siano già identificati per l'applicazione di filtri al momento della query. Potresti voler aggiungere tag di limitazione per limitare i risultati presentati nei dati prima dell'invio di una query. Ad esempio, un cliente vuole eseguire una query su un indice, ma vuole assicurarsi che nei risultati vengano visualizzati solo gli articoli che corrispondono al termine "rosso" in una ricerca di calzature. Nell'esempio seguente, l'indice viene sottoposto a upsert e filtra per tutte le scarpe rosse, ma rifiuta quelle blu. In questo modo, i filtri di ricerca vengono inseriti nelle migliori opzioni specifiche di un indice ampio e diversificato prima dell'esecuzione.

Oltre alle limitazioni dei token, nell'esempio vengono utilizzate limitazioni numeriche. In questo caso, il punto dati è associato a un prezzo di 20, una lunghezza di 0,3 e una larghezza di 0,5. Al momento della query, puoi utilizzare queste limitazioni numeriche per filtrare i risultati in modo da limitare i risultati della query in base ai valori di prezzo, lunghezza e larghezza. Ad esempio, questo punto dati verrebbe visualizzato in una query che filtra in base a prezzo > 25, lunghezza < 1 e larghezza < 1.

Per scoprire di più sui filtri, consulta la pagina Ricerca vettoriale per l'indicizzazione.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://${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}]
  }
]}'

Esegui upsert con crowding

Il tag di crowding limita risultati simili migliorandone la diversità. Il crowding è un vincolo su un elenco di vicini generato dalla ricerca di un vicino più prossimo e richiede che un gruppo di risultati non restituisca più di un determinato valore per lo stesso valore, ovvero crowding_attribute. Ad esempio, supponiamo che tu sia di nuovo online a cercare scarpe. Vuoi vedere una varietà di colori nei risultati, ma magari avere un solo stile, ad esempio scarpini da calcio. Puoi chiedere che non vengano restituite più di 3 paia di scarpe dello stesso colore impostando per_crowding_attribute_num_neighbors = 3 nella query, supponendo che tu imposti crowding_attribute sul colore delle scarpe durante l'inserimento del punto dati.

Questo campo rappresenta il numero massimo consentito di corrispondenze con lo stesso crowding tag.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://${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"},
  }
]}'

Passaggi successivi

• Scopri di più sui parametri di configurazione dell'indice
• Scopri come monitorare un indice.