Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiorna e ricrea un indice attivo

Panoramica

In caso di query di ricerca lunghe, l'aggiornamento degli indici è importante per avere le informazioni più accurate. Attualmente puoi aggiornare gli indici di ricerca vettoriale utilizzando un aggiornamento batch, che ti consente di inserire ed eliminare punti dati tramite una pianificazione batch, oppure con l'aggiornamento in streaming, che ti consente di aggiornare e 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 al tuo indice per contribuire a diversificare i risultati o filtrare la query precedente all'indice.

Aggiornare un indice batch

Per aggiornare i contenuti di un Index esistente, usa IndexService.UpdateIndex .

Per sostituire i contenuti di un elemento Index esistente:

Imposta Index.metadata.contentsDeltaUri sull'URI di Cloud Storage che include i vettori che vuoi aggiornare.
Imposta isCompleteOverwrite su true. Se impostato su true, l'intero indice viene completamente sovrascritto con il nuovo file di metadati da te fornito.

Se imposti il campo contentsDeltaUri durante la chiamata IndexService.UpdateIndex, quindi nessun altro campo dell'indice (ad esempio displayName, description o userLabels) possono essere aggiornati anche nell'ambito della stessa chiamata.

gcloud

Aggiorna il file dei metadati dell'indice .

Utilizza il comando gcloud ai indexes update.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

LOCAL_PATH_TO_METADATA_FILE: il percorso locale del file di metadati.
INDEX_ID: l'ID dell'indice.
LOCATION: la regione in cui utilizzi Vertex AI.
PROJECT_ID: il tuo ID progetto Google Cloud.

Esegui il seguente comando:

Linux, macOS o Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

INPUT_DIR: il percorso della directory Cloud Storage dei contenuti dell'indice.
INDEX_ID: l'ID dell'indice.
LOCATION: la regione in cui utilizzi Vertex AI.
PROJECT_ID: il tuo ID progetto Google Cloud.
PROJECT_NUMBER: il numero di progetto generato automaticamente per il tuo progetto.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo comando:

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)

Nota: Il comando seguente presuppone che tu abbia eseguito l'accesso a l'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login di Google. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Segui queste istruzioni per aggiornare i contenuti di un indice batch.

Nella sezione Vertex AI della console Google Cloud, vai alla sezione Esegui il deployment e utilizza. Seleziona Vector Search (Ricerca vettoriale).
Vai a Ricerca vettoriale
Seleziona l'indice da aggiornare. Viene visualizzata la pagina Informazioni sull'indice.
Seleziona Modifica indice. Viene visualizzato un riquadro di modifica dell'indice.
Nel campo Cloud Storage, cerca e seleziona la cartella Cloud Storage in cui sono archiviati i dati vettoriali.
(Facoltativo) Seleziona la casella Sostituzione completa se vuoi sovrascrivere tutti i dati esistenti.
Fai clic su Aggiorna.
Fai clic su Fine per chiudere il riquadro.

Se a Index sono associati deployment (vedi il campo Index.deployed_indexes), quando determinate modifiche al l'elemento Index originale è terminato, il DeployedIndex viene aggiornato automaticamente in modo asincrono in background per riflettere queste modifiche.

Per verificare se la modifica è stata propagata, confronta la data e l'ora di completamento dell'operazione di indice di aggiornamento e DeployedIndex.index_sync_time.

Aggiorna un indice di flussi di dati

Con gli aggiornamenti in modalità flusso, puoi aggiornare l'indice ed eseguire query 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. Consulta Creare un indice per l'aggiornamento dello streaming per saperne di più.

Ti vengono addebitati 0,45 $ per GB utilizzato per gli aggiornamenti in streaming. Per scoprire di più sui prezzi, consulta la pagina dei prezzi di Vertex AI. Gli aggiornamenti in modalità flusso vengono applicati direttamente agli indici di cui è stato eseguito il deployment in memoria. che si rifletteranno nei risultati della query dopo un breve ritardo.

Punti dati upsert

Utilizza questi esempi per vedere come eseguire l'upsert di un punto dati. Ricorda: upsert-datapoints accetta JSON solo in formato array.

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

Il limite della quota di velocità effettiva si riferisce alla quantità di dati inclusi in un upsert. Se l'ID punto dati esiste nell'indice, l'embedding viene aggiornato, altrimenti viene aggiunto un nuovo embedding.

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

Con la ricerca ibrida, che è Anteprima pubblica, rappresentazioni sparse e dense per un sono supportati i punti dati. In un'operazione upsert, l'omissione di un incorporamento denso elimina l'incorporamento denso e l'omissione di un incorporamento sparso elimina la rappresentazione sparsa.

Questo esempio aggiorna sia gli incorporamenti densi che quelli sparsi.

  
    curl -X POST -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: "111", feature_vector: [0.111, 0.111], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

Questo esempio aggiorna gli incorporamenti densi e rimuove quelli sparsi.

    
      curl -X POST -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: "111", feature_vector: [0.111, 0.111]}]}'

Questo esempio aggiorna gli incorporamenti sparsi e rimuove quelli densi.

    
      curl -X POST -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: "111",  "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

Console

Segui queste istruzioni per aggiornare i contenuti in un indice di streaming.

Nella console Google Cloud, vai alla pagina Ricerca di vettori.
Vai a Ricerca vettoriale
Seleziona l'indice da aggiornare. Viene visualizzata la pagina Informazioni sull'indice.
Fai clic su Modifica indice. Viene visualizzato un riquadro di modifica dell'indice.
Nel riquadro, seleziona la scheda Aggiorna punto dati per aggiungere contenuti.
Inserisci l'ID del punto dati.
Inserisci almeno un tipo di incorporamento:

Embedding denso: inserisci un array di valori in virgola mobile separati da virgole. Il numero di valori deve corrispondere alle dimensioni dell'indice.
Embedding sparso (anteprima pubblica):

Inserisci le dimensioni dell'embedding sparso come array di numeri interi separati da virgole. Il numero di valori non deve necessariamente corrispondere alle dimensioni dell'indice.
Inserisci i valori sotto forma di array di valori con rappresentazione in virgola mobile separati da virgole. Il numero di valori deve corrispondere al numero di dimensioni di incorporamento sparse.

(Facoltativo) Per attivare il filtro in base alle limitazioni del token in questo punto dati, fai clic su Aggiungi limitazione token, quindi inserisci uno spazio dei nomi e stringhe separate da virgole come token.
(Facoltativo) Per attivare il filtro in base alle limitazioni numeriche su questo punto dati, fai clic su Aggiungi limitazione numerica, inserisci un ambito, seleziona un tipo di numero e inserisci un valore.
(Facoltativo) Per evitare molti risultati simili, inserisci una stringa tag di crowding.
Fai clic su Upsert.
Fai clic su Fine per chiudere il riquadro.

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

Aggiornare i metadati dinamici

Ci sono molti motivi per cui potresti dover aggiornare le restrizioni o i valori numerici del flusso . Ad esempio, quando si ha a che fare con dati ad alto volume e in rapida evoluzione, potrebbe essere utile dare la priorità a determinati stream di dati. L'aggiornamento diretto delle limitazioni o delle limitazioni numeriche consente di perfezionare l'attenzione in tempo reale, garantendo che i dati più importanti vengano elaborati o evidenziati immediatamente.

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

Per eseguire questi aggiornamenti relativi solo ai 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 limitazione numerica impostati nei punti dati devono essere i nuovi valori da 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" 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"}'

Rimuovi punti dati

Potresti dover rimuovere i punti dati dall'indice in streaming. Puoi eseguire questa operazione utilizzando curl o dalla console Google Cloud.

Un caso d'uso chiave per eliminare un punto dati da un indice è mantenere parità tra l'indice e la sua origine reale. Immagina un libraccio che utilizza un embedding vettoriale per rappresentare il proprio inventario di libri per scopi di ricerca e consigli. Quando un libro è esaurito o viene rimosso dagli inventari, l'eliminazione del relativo punto di dati dall'indice garantisce che i risultati di ricerca e i consigli rimangano accurati e aggiornati.

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

Utilizza queste istruzioni per eliminare un punto dati dall'indice di flussi di dati.

Nella sezione Vertex AI della console Google Cloud, vai a nella sezione Deployment e utilizzo. Seleziona Ricerca vettoriale.
Vai a Ricerca vettoriale
Seleziona l'indice di streaming che vuoi aggiornare. Si apre la pagina Informazioni indice.
Seleziona Modifica indice. Si apre un riquadro di modifica dell'indice.
Dal riquadro, seleziona la scheda Rimuovi punti dati.
Aggiungi fino a 20 punti dati fornendo un elenco separato da virgole di ID punto dati
Fai clic su Rimuovi.
Fai clic su Fine per chiudere il riquadro.

Compattazione

Periodicamente, l'indice viene ricostruito per tenere conto di tutti i nuovi aggiornamenti dall'ultima ricostruzione. Questa ricostruzione, o "compazione", migliora le prestazioni e l'affidabilità delle query. Le compattazioni si verificano sia per gli aggiornamenti in streaming sia per quelli batch.

Aggiornamento in streaming: Ricerca vettoriale utilizza metriche basate su heuristics per determinare quando attivare il compattamento. Se i dati non compressi più vecchi risalgono a cinque giorni fa, la compressione viene sempre attivata. Ti viene addebitato il costo della ricostruzione dell'indice alla stessa tariffa di un aggiornamento batch, oltre ai costi dell'aggiornamento in streaming.
Aggiornamento batch: si verifica quando la dimensione incrementale del set di dati è > 20% della base la dimensione del set di dati.

Ricostruisci l'indice ed esegui query

Puoi inviare richieste di corrispondenza o di corrispondenza in batch come di consueto con l'interfaccia a riga di comando grpc, la libreria client, Vertex AI SDK per Python. Quando ricostruisci la query, dovresti visualizzare gli aggiornamenti tra pochi secondi. Per scoprire come eseguire query su un indice, consulta Esegui query sugli indici per ottenere i vicini più vicini.

Campi facoltativi

Quando crei un indice, ci sono alcuni campi facoltativi che puoi utilizzare ottimizzare le query.

Esegui upsert con limitazioni

L'inserimento dell'indice e l'aggiunta di una limitazione sono un modo per taggare i punti di dati in modo che siano già identificati per essere filtrati al momento della query. Ti consigliamo di aggiungere tag di limitazione per limitare i risultati visualizzati nei tuoi dati prima dell'invio di una query. Ad esempio, un cliente vuole esegue una query su un indice, ma vuole assicurarsi che i risultati mostrino solo elementi che corrispondono a "rosso" alla ricerca di calzature. Nell'esempio seguente, è sottoposto all'upsert e filtra tutte le scarpe rosse, ma rifiuta quelle blu. In questo modo, prima dell'esecuzione, la ricerca filtra le opzioni specifiche migliori da un indice ampio e variegato.

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

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

Python

# Upsert datapoints
_TEST_DATAPOINT_1 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="3",
    feature_vector=[0.00526886899, -0.0198396724],
    restricts=[
        aiplatform_v1.types.index.IndexDatapoint.Restriction(namespace="Color", allow_list=["red"])
    ],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_int=1,
        )
    ],
)
_TEST_DATAPOINT_2 =  aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="4",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_double=0.1,
        )
    ],
    crowding_tag=aiplatform_v1.types.index.IndexDatapoint.CrowdingTag(crowding_attribute="crowding"),
)
_TEST_DATAPOINT_3 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="5",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)

_TEST_DATAPOINTS = [_TEST_DATAPOINT_1, _TEST_DATAPOINT_2, _TEST_DATAPOINT_3]

my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=_TEST_DATAPOINTS)

# Dynamic metadata update
_TEST_DATAPOINT_4 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="-2",
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)
my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=[_TEST_DATAPOINT4], update_mask=["all_restricts"])

curl

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 con sovraffollamento

Il crowding tag limita risultati simili migliorando la diversità dei risultati. Il crowding è un vincolo di un elenco di vicini generato dal vicino più prossimo che richiede che non più di un valore, di un gruppo di risultati, restituisca il valore lo stesso valore di crowding_attribute. Ad esempio, supponiamo che tu sia tornato online per acquistare scarpe. Vuoi visualizzare una vasta gamma di colori nei risultati, ma forse li vuoi in un unico stile, ad esempio scarpini da calcio. Puoi chiedere di non superare più di 3 paia di scarpe con lo stesso colore viene restituito impostando per_crowding_attribute_num_neighbors = 3 nella query, supponendo che imposti crowding_attribute sul colore delle scarpe quando inserisci il punto dati.

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

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

Passaggi successivi

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