Le seguenti sezioni descrivono come configurare, creare, elencare ed eliminare i tuoi indici.
Panoramica indice
Un indice è uno o più file costituiti dai tuoi vettori di incorporamento. Questi vettori sono costituiti da grandi quantità di dati di cui vuoi eseguire il deployment e che vuoi interrogare con Vector Search. Con Vector Search, puoi creare due tipi di indici, a seconda di come prevedi di aggiornarli con i tuoi dati. Puoi creare un indice progettato per gli aggiornamenti batch o un indice progettato per il flusso di aggiornamenti.
Un indice batch è utile per aggiornare l'indice in batch, con dati che sono stati archiviati per un determinato periodo di tempo, come sistemi che vengono elaborati settimanalmente o mensilmente. Un indice di flussi di dati consente di aggiornare i dati dell'indice man mano che vengono aggiunti nuovi dati al tuo datastore, ad esempio se hai una libreria e vuoi mostrare nuovo inventario online il prima possibile. Che il tipo scelto è importante, dato che configurazione e requisiti sono diversi.
Configura i parametri indice
Prima di creare un indice, configura i parametri dell'indice.
Ad esempio, crea un file denominato index_metadata.json
:
{ "contentsDeltaUri": "gs://BUCKET_NAME/path", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "shardSize": "SHARD_SIZE_MEDIUM", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 5000, "leafNodesToSearchPercent": 3 } } } }
La definizione di ciascuno di questi campi è disponibile in Parametri di configurazione dell'indice.
Crea un indice
Dimensioni indice
I dati dell'indice vengono suddivisi in parti uguali chiamate shard per l'elaborazione. Quando crei un indice, devi specificare le dimensioni degli shard da utilizzare. Le dimensioni supportate sono le seguenti:
SHARD_SIZE_SMALL
: 2 GiB per shard.SHARD_SIZE_MEDIUM
: 20 GiB per shard.SHARD_SIZE_LARGE
: 50 GiB per shard.
I tipi di macchina che puoi utilizzare per eseguire il deployment dell'indice (utilizzando endpoint pubblici o utilizzando endpoint VPC) dipendono dalla dimensione dello shard dell'indice. La seguente tabella mostra le dimensioni degli shard supportate da ogni tipo di macchina:
Tipo di macchina | SHARD_SIZE_SMALL |
SHARD_SIZE_MEDIUM |
SHARD_SIZE_LARGE |
---|---|---|---|
n1-standard-16 |
|||
n1-standard-32 |
|||
e2-standard-2 |
(predefinita) | ||
e2-standard-16 |
(predefinita) | ||
e2-highmem-16 |
(predefinita) | ||
n2d-standard-32 |
Per scoprire in che modo le dimensioni dello shard e il tipo di macchina influiscono sui prezzi, consulta la pagina dei prezzi di Vertex AI.
Crea un indice per l'aggiornamento batch
Utilizza queste istruzioni per creare il tuo indice ed eseguirne il deployment. Se non hai ancora pronto gli incorporamenti, puoi passare a Creare un indice batch vuoto. Con questa opzione, non sono richiesti dati di incorporamenti al momento della creazione dell'indice.
Per creare un indice:
gcloud
Prima di utilizzare qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:
- LOCAL_PATH_TO_METADATA_FILE: il percorso locale del file dei metadati.
- INDEX_NAME: nome visualizzato dell'indice.
- LOCATION: la regione in cui stai utilizzando Vertex AI.
- PROJECT_ID: il tuo ID progetto Google Cloud.
Esegui questo seguente comando:
Linux, macOS o Cloud Shell
gcloud ai indexes create \ --metadata-file=LOCAL_PATH_TO_METADATA_FILE \ --display-name=INDEX_NAME \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes create ` --metadata-file=LOCAL_PATH_TO_METADATA_FILE ` --display-name=INDEX_NAME ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes create ^ --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^ --display-name=INDEX_NAME ^ --region=LOCATION ^ --project=PROJECT_ID
Dovresti ricevere una risposta simile alla seguente:
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
Consulta le operazioni di gcloud ai per scoprire di più sul comando describe
.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- INPUT_DIR: il percorso della directory Cloud Storage dei contenuti dell'indice.
- INDEX_NAME: nome visualizzato dell'indice.
- LOCATION: la regione in cui stai utilizzando 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:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
Corpo JSON della richiesta:
{ "display_name": "INDEX_NAME", "metadata": { "contentsDeltaUri": "INPUT_DIR", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
Per inviare la richiesta, espandi una delle seguenti opzioni:
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.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T01:21:10.147035Z", "updateTime": "2022-01-08T01:21:10.147035Z" } } }
Terraform
L'esempio seguente utilizza la risorsa Terraform google_vertex_ai_index
per creare un indice per gli aggiornamenti batch.
Per scoprire come applicare o rimuovere una configurazione Terraform, vedi Comandi Terraform di base.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Console
Utilizza queste istruzioni per creare un indice per gli aggiornamenti batch.
- Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Vector Search (Ricerca vettoriale).
- Fai clic su Crea nuovo indice per aprire il riquadro Indice. Viene visualizzato il riquadro Crea un nuovo indice.
- Nel campo Nome visualizzato, fornisci un nome per identificare in modo univoco il tuo indice.
- Nel campo Descrizione, fornisci una descrizione della finalità dell'indice.
- Nel campo Regione, seleziona una regione dall'elenco a discesa.
- Nel campo Cloud Storage, cerca e seleziona la cartella Cloud Storage in cui sono archiviati i tuoi dati vettoriali.
- Nel menu a discesa Tipo di algoritmo, seleziona il tipo di algoritmo utilizzato da Vector Search per una ricerca efficiente. Se selezioni l'algoritmo TreeAh, inserisci il numero approssimativo di vicini.
- Nel campo Dimensioni, inserisci il numero di dimensioni dei vettori di input.
- Nel campo Aggiornamento del metodo, seleziona Batch.
- Nel campo Dimensione shard, seleziona dal menu a discesa le dimensioni dello shard che vuoi.
- Fai clic su Crea. Una volta pronto, il nuovo indice viene visualizzato nell'elenco degli indici. Nota: il completamento della build può richiedere fino a un'ora.
Crea un indice batch vuoto
Per creare ed eseguire subito il deployment dell'indice, puoi creare un indice batch vuoto. Con questa opzione, non sono richiesti dati di incorporamenti al momento della creazione dell'indice.
Per creare un indice vuoto, la richiesta è quasi identica alla creazione di un indice
per gli aggiornamenti batch. La differenza è che rimuovi il campo contentsDeltaUri
,
dal momento che non stai collegando una località dei dati. Ecco un esempio di indice batch vuoto:
Esempio di richiesta di indice vuota
{ "display_name": INDEX_NAME, "indexUpdateMethod": "BATCH_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
Crea un indice per gli aggiornamenti in streaming
Utilizza queste istruzioni per creare ed eseguire il deployment del tuo indice di flussi. Se gli incorporamenti non sono ancora pronti, passa a Creare un indice vuoto per gli aggiornamenti streaming. Con questa opzione, non sono richiesti dati di incorporamenti al momento della creazione dell'indice.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- INDEX_NAME: nome visualizzato dell'indice.
- DESCRIPTION: una descrizione dell'indice.
- INPUT_DIR: il percorso della directory Cloud Storage dei contenuti dell'indice.
- DIMENSIONS: numero di dimensioni del vettore di incorporamento.
- PROJECT_ID: il tuo ID progetto Google Cloud.
- PROJECT_NUMBER: il numero di progetto generato automaticamente per il tuo progetto.
- LOCATION: la regione in cui stai utilizzando Vertex AI.
Metodo HTTP e URL:
POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
Corpo JSON della richiesta:
{ displayName: "INDEX_NAME", description: "DESCRIPTION", metadata: { contentsDeltaUri: "INPUT_DIR", config: { dimensions: "DIMENSIONS", approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}} }, }, indexUpdateMethod: "STREAM_UPDATE" }
Per inviare la richiesta, espandi una delle seguenti opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2023-12-05T23:17:45.416117Z", "updateTime": "2023-12-05T23:17:45.416117Z", "state": "RUNNING", "worksOn": [ "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID" ] } } }
Console
Segui queste istruzioni per creare un indice per gli aggiornamenti in streaming nella console Google Cloud.
Per creare un indice disponibile per gli aggiornamenti in modalità flusso sono necessari passaggi simili alla configurazione di un indice di aggiornamento batch, a meno che non sia necessario impostare indexUpdateMethod
su STREAM_UPDATE
.
- Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Vector Search
- Fai clic su Crea nuovo indice per aprire il riquadro Indice. Viene visualizzato il riquadro Crea un nuovo indice.
- Nel campo Nome visualizzato, fornisci un nome per identificare in modo univoco il tuo indice.
- Nel campo Descrizione, fornisci una descrizione dello scopo dell'indice.
- Nel campo Regione, seleziona una regione dall'elenco a discesa.
- Nel campo Cloud Storage, cerca e seleziona la cartella di Cloud Storage in cui sono archiviati i tuoi dati vettoriali.
- Nel menu a discesa Tipo di algoritmo, seleziona il tipo di algoritmo che Vector Search utilizzerà per eseguire la ricerca. Se selezioni l'algoritmo TreeAh, inserisci il numero approssimativo di vicini.
- Nel campo Dimensioni, inserisci il numero di dimensioni dei vettori di input.
- Nel campo Metodo di aggiornamento, seleziona Stream.
- Nel campo Dimensione shard, seleziona dal menu a discesa le dimensioni dello shard che vuoi.
- Fai clic su Crea. Una volta pronto, il nuovo indice viene visualizzato nell'elenco degli indici. Nota: il completamento della build può richiedere fino a un'ora.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Crea un indice vuoto per gli aggiornamenti in streaming
Per creare ed eseguire subito il deployment dell'indice, puoi creare un indice vuoto per il flusso di dati. Con questa opzione, non sono richiesti dati di incorporamenti al momento della creazione dell'indice.
Per creare un indice vuoto, la richiesta è quasi identica alla creazione di un indice
per i flussi di dati. La differenza è che rimuovi il campo contentsDeltaUri
,
dal momento che non stai collegando una località dei dati. Ecco un esempio di indice di streaming vuoto:
Esempio di richiesta di indice vuota
{ "display_name": INDEX_NAME, "indexUpdateMethod": "STREAM_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
Elenca indici
gcloud
Prima di utilizzare qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:
- INDEX_NAME: nome visualizzato dell'indice.
- LOCATION: la regione in cui stai utilizzando Vertex AI.
- PROJECT_ID: il tuo ID progetto Google Cloud.
Esegui questo seguente comando:
Linux, macOS o Cloud Shell
gcloud ai indexes list \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes list ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes list ^ --region=LOCATION ^ --project=PROJECT_ID
Dovresti ricevere una risposta simile alla seguente:
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
Consulta le operazioni di gcloud ai per scoprire di più sul comando describe
.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- INDEX_NAME: nome visualizzato dell'indice.
- LOCATION: la regione in cui stai utilizzando 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:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
Per inviare la richiesta, espandi una delle seguenti opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{ "indexes": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID", "displayName": "INDEX_NAME", "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "featureNormType": "NONE", "algorithmConfig": { "treeAhConfig": { "maxLeavesToSearch": 50, "leafNodeCount": 10000 } } } }, "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=", "createTime": "2020-11-08T21:56:30.558449Z", "updateTime": "2020-11-08T22:39:25.048623Z" } ] }
Console
Utilizza queste istruzioni per visualizzare un elenco dei tuoi indici.
- Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Vector Search (Ricerca vettoriale).
- Viene visualizzato un elenco degli indici attivi.
Ottimizzazione dell'indice
L'ottimizzazione dell'indice richiede l'impostazione dei parametri di configurazione che influiscono sulle prestazioni degli indici di cui è stato eseguito il deployment, in particolare richiamo e latenza. Questi parametri vengono impostati quando crei l'indice per la prima volta. Puoi utilizzare gli indici di forza bruta per misurare il richiamo.
Parametri di configurazione che influiscono sulle prestazioni
I seguenti parametri di configurazione possono essere impostati al momento della creazione dell'indice e possono influire su richiamo, latenza, disponibilità e costo quando si utilizza Vector Search. Queste linee guida si applicano alla maggior parte dei casi. Tuttavia, sperimenta sempre le configurazioni per assicurarti che funzionino per il tuo caso d'uso.
Per le definizioni dei parametri, consulta la sezione Parametri di configurazione dell'indice.
Parametro | Informazioni | Impatto sulle prestazioni |
---|---|---|
shardSize
|
Controlla la quantità di dati su ogni macchina. Quando scegli la dimensione dello shard, stima le dimensioni del tuo set di dati in futuro. Se la dimensione del set di dati ha un limite superiore, scegli la dimensione dello shard appropriata per ospitarlo. Se non esiste un limite superiore o se il tuo caso d'uso è estremamente sensibile alla variabilità della latenza, ti consigliamo di scegliere una dimensione dello shard elevata. |
Se configuri per un numero maggiore di shard più piccoli, durante la ricerca viene elaborato un numero maggiore di risultati candidati. Un numero maggiore di shard può influire sulle prestazioni nei seguenti modi:
Se configuri per un numero inferiore di shard più grandi, durante la ricerca vengono elaborati meno risultati candidati. Un numero minore di shard può influire sulle prestazioni nei seguenti modi:
|
distanceMeasureType
|
Determina l'algoritmo utilizzato per il calcolo della distanza tra i punti dati e il vettore di query. |
Le seguenti impostazioni di
|
leafNodeEmbeddingCount
|
Il numero di incorporamenti per ogni nodo foglia. Per impostazione predefinita, questo numero è impostato su 1000.
In genere, la modifica del valore di |
Aumentare il numero di incorporamenti per ogni nodo foglia può ridurre la latenza, ma la qualità del richiamo. Può influire sulle prestazioni nei seguenti modi:
La riduzione del numero di incorporamenti per ogni nodo foglia può influire sulle prestazioni nei seguenti modi:
|
Utilizzo di un indice di forza bruta per misurare il richiamo.
Per ottenere i vicini più prossimi esatti, utilizza gli indici con l'algoritmo di forza bruta. L'algoritmo di forza bruta fornisce il 100% di richiamo, a scapito di una latenza più elevata. L'utilizzo di un indice di forza bruta per misurare il richiamo di solito non è una buona scelta per la pubblicazione in produzione, ma potrebbe essere utile per valutare il richiamo di varie opzioni di indicizzazione offline.
Per creare un indice con l'algoritmo di forza bruta, specifica brute_force_config
nei metadati dell'indice:
curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer `gcloud auth print-access-token`" \ https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \ -d '{ displayName: "'${DISPLAY_NAME}'", description: "'${DESCRIPTION}'", metadata: { contentsDeltaUri: "'${INPUT_DIR}'", config: { dimensions: 100, approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", featureNormType: "UNIT_L2_NORM", algorithmConfig: { bruteForceConfig: {} } }, }, }'
Eliminare un indice
gcloud
Prima di utilizzare qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:
- INDEX_ID: l'ID dell'indice.
- LOCATION: la regione in cui stai utilizzando Vertex AI.
- PROJECT_ID: il tuo ID progetto Google Cloud.
Esegui questo seguente comando:
Linux, macOS o Cloud Shell
gcloud ai indexes delete INDEX_ID \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes delete INDEX_ID ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes delete INDEX_ID ^ --region=LOCATION ^ --project=PROJECT_ID
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- INDEX_ID: l'ID dell'indice.
- LOCATION: la regione in cui stai utilizzando 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:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID
Per inviare la richiesta, espandi una delle seguenti opzioni:
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.DeleteOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T02:35:56.364956Z", "updateTime": "2022-01-08T02:35:56.364956Z" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
Console
Utilizza queste istruzioni per eliminare uno o più indici.
- Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Vector Search (Ricerca vettoriale).
- Viene visualizzato un elenco degli indici attivi.
- Per eliminare un indice, vai al menu opzioni che si trova nella stessa riga dell'indice e seleziona Elimina.
Passaggi successivi
- Scopri di più sui parametri di configurazione dell'indice.
- Scopri come eseguire il deployment e gestire gli endpoint indice pubblici
- Scopri come eseguire il deployment e gestire gli endpoint indice in una rete VPC
- Scopri come aggiornare e ricreare l'indice.
- Scopri come monitorare un indice