Nella guida rapida di Vertex AI Vector Search, scopri come creare un indice a partire da un set di dati di esempio da un sito di abbigliamento e-commerce fittizio. Ai fini di questa guida rapida, gli incorporamenti sono già stati creati. Questa guida rapida è pensata per aiutarti a creare ed eseguire il deployment di un indice in meno di 30 minuti.
Prerequisiti
Questo tutorial richiede un progetto Google Cloud collegato a un account di fatturazione. Per creare un nuovo progetto, vedi Configurare un progetto e un ambiente di sviluppo. Devi creare un progetto e configurare il tuo account di fatturazione.
Scegli l'ambiente di runtime
Questo tutorial può essere eseguito su Colab o Vertex AI Workbench.
- Colab: apri questo tutorial in Colab.
- Vertex AI Workbench: apri questo tutorial in Vertex AI Workbench. Se è la prima volta che utilizzi Vertex AI Workbench nel progetto Google Cloud, vai alla sezione Vertex AI Workbench della console Google Cloud e fai clic su Abilita per abilitare l'API Notebooks.
Per visualizzare questo blocco note in GitHub, vedi GitHub.
Costo per completare questa guida rapida
Il completamento di questo tutorial costa all'incirca alcuni dollari statunitensi. I prezzi dei servizi Google Cloud utilizzati in questo tutorial sono disponibili nelle seguenti pagine:
Puoi anche utilizzare il Calcolatore prezzi per generare una stima dei costi in base all'utilizzo previsto.
Configurazione
Prima di iniziare a utilizzare Vertex AI, devi configurare quanto segue:
- Installa l'SDK Vertex AI per Python
- Imposta le variabili di ambiente
- Autentica (solo Colab)
- Imposta le autorizzazioni IAM
- Abilita le API
Installare l'SDK Vertex AI per Python
Puoi accedere alle API Vertex AI e Cloud Storage in diversi modi, tra cui l'API REST e l'SDK Vertex AI per Python. In questo tutorial viene utilizzato l'SDK Vertex AI per Python.
!pip install --upgrade --user google-cloud-aiplatform>=1.29.0 google-cloud-storage
Per utilizzare i pacchetti appena installati in questo runtime Jupyter, devi riavviare il runtime, come mostrato nello snippet di codice riportato di seguito.
# Restart kernel after installs so that your environment can access the new packages
import IPython
app = IPython.Application.instance()
app.kernel.do_shutdown(True)
Variabili di ambiente
Imposta le variabili di ambiente. Se richiesto, sostituisci your-project-id con il tuo ID progetto ed esegui la cella.
# get project ID
PROJECT_ID = ! gcloud config get-value project
PROJECT_ID = PROJECT_ID[0]
LOCATION = "us-central1"
if PROJECT_ID == "(unset)":
print(f"Please set the project ID manually below")
# define project information
if PROJECT_ID == "(unset)":
PROJECT_ID = "[your-project-id]"
# generate a unique id for this session
from datetime import datetime
UID = datetime.now().strftime("%m%d%H%M")
Autenticazione (solo Colab)
Se esegui questo blocco note su Colab, devi eseguire la seguente autenticazione delle celle. Questo passaggio non è richiesto se utilizzi Vertex AI Workbench in quanto è preautenticato.
import sys
# if it's Colab runtime, authenticate the user with Google Cloud
if 'google.colab' in sys.modules:
from google.colab import auth
auth.authenticate_user()
Impostazione delle autorizzazioni IAM
Per utilizzare i servizi, devi aggiungere le autorizzazioni di accesso all'account di servizio predefinito.
- Vai alla pagina IAM nella console Google Cloud.
- Cerca l'entità per l'account di servizio Compute predefinito.
Dovrebbe avere il seguente formato:
compute@developer.gserviceaccount.com - Fai clic sul pulsante Modifica e concedi all'account di servizio Compute predefinito con i seguenti ruoli: Utente Vertex AI e Amministratore Storage e Amministratore utilizzo dei servizi.
Abilita le API
Esegui questo comando per abilitare le API per Compute Engine, Vertex AI e Cloud Storage con questo progetto Google Cloud.
! gcloud services enable compute.googleapis.com aiplatform.googleapis.com storage.googleapis.com --project {PROJECT_ID}
prepara i dati di esempio
In questo tutorial utilizziamo il set di dati TheLook, che contiene una tabella dei prodotti con circa 30.000 righe di dati di prodotto sintetici per un sito di abbigliamento e-commerce fittizio.
Da questa tabella abbiamo preparato il file product-embs.json.
Questo file è in formato JSONL e ogni riga contiene ID per l'ID prodotto, il nome del nome del prodotto e l'incorporamento per l'incorporamento del nome del prodotto in 768 dimensioni, generato in precedenza con gli incorporamenti di Vertex AI per il testo.
Gli incorporamenti di testo rappresentano il significato dei nomi dei prodotti di abbigliamento. In questo tutorial utilizziamo Vector Search per completare una ricerca semantica degli elementi. Questo codice campione può essere utilizzato come base per altri sistemi di suggerimenti rapidi in cui puoi trovare rapidamente "altri prodotti simili a questo".
Per scoprire di più su come creare incorporamenti dai dati in una tabella BigQuery e archiviarli in un file JSON, consulta Introduzione agli incorporamenti di testo + Vertex AI Vector Search.
prepara i dati su Cloud Storage
Per creare un indice con Vertex AI, posiziona il file di incorporamento in un bucket Cloud Storage. Il seguente codice completa due attività:
- Crea un bucket Cloud Storage.
- Copia il file di esempio nel tuo bucket Cloud Storage.
BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"
! gsutil mb -l $LOCATION -p $PROJECT_ID $BUCKET_URI
! gsutil cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI
Per utilizzare Vector Search per eseguire query, devi anche copiare il file di incorporamento nella directory locale:
! gsutil cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests
Crea ed esegui il deployment di un indice di Vector Search
Scopri come creare un indice e un endpoint indice ed eseguire il deployment dell'indice nell'endpoint.
Crea un indice
È arrivato il momento di caricare gli incorporamenti in Vector Search.
Le API sono disponibili nel pacchetto aiplatform dell'SDK.
# init the aiplatform package
from google.cloud import aiplatform
aiplatform.init(project=PROJECT_ID, location=LOCATION)
Crea un MatchingEngineIndex
con la sua funzione create_tree_ah_index (Matching Engine è il nome precedente di Vector Search).
# create Index
my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
display_name = f"vs-quickstart-index-{UID}",
contents_delta_uri = BUCKET_URI,
dimensions = 768,
approximate_neighbors_count = 10,
)
Il metodo MatchingEngineIndex.create_tree_ah_index() crea un indice.
Questa operazione richiede meno di 10 minuti se il set di dati è piccolo, altrimenti circa 60 minuti o più, a seconda delle dimensioni del set di dati. Puoi controllare lo stato della creazione
dell'indice nella console Google Cloud di Vector Search
I parametri per la creazione dell'indice:
contents_delta_uri: l'URI della directory Cloud Storage in cui hai archiviato i file JSON di incorporamentodimensions: dimensioni di ogni incorporamento. In questo caso, è 768, perché stai usando gli incorporamenti dell'API text Embeddings.approximate_neighbors_count: quanti elementi simili vuoi recuperare in casi tipici
Per scoprire di più sulla creazione dell'indice e dei parametri disponibili, consulta Creare e gestire l'indice
Crea un endpoint indice ed esegui il deployment dell'indice
Per utilizzare l'indice, devi creare un endpoint indice. Funziona come un'istanza del server che accetta richieste di query per l'indice.
## create `IndexEndpoint`
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
display_name = f"vs-quickstart-index-endpoint-{UID}",
public_endpoint_enabled = True
)
Con l'endpoint indice, esegui il deployment dell'indice specificando un ID indice univoco di cui è stato eseguito il deployment.
DEPLOYED_INDEX_ID = f"vs_quickstart_deployed_{UID}"
# deploy the Index to the Index Endpoint
my_index_endpoint.deploy_index(
index = my_index, deployed_index_id = DEPLOYED_INDEX_ID
)
Se è la prima volta che esegui il deployment di questo indice in un endpoint indice, la creazione e l'avvio del backend automatici possono richiedere circa 30 minuti. Per visualizzare lo stato del deployment dell'indice, nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Indici
Eseguire una query con Vector Search
Nel codice seguente, trova un incorporamento per il nome di un prodotto specificato e trova nomi di prodotti simili con la ricerca vettoriale.
Ottieni un incorporamento per eseguire una query
Innanzitutto, carica il file JSON di incorporamento per creare un dict di nomi di prodotto e incorporamenti.
import json
# build dicts for product names and embs
product_names = {}
product_embs = {}
with open('product-embs.json') as f:
for l in f.readlines():
p = json.loads(l)
id = p['id']
product_names[id] = p['name']
product_embs[id] = p['embedding']
Con il dizionario product_embs, puoi specificare un ID prodotto per riceverne l'incorporamento.
# Get the embedding for ID 6523 "cloudveil women's excursion short"
you can also try with other IDs such as 12711, 18090, 19536 and 11863
query_emb = product_embs['6523']
esegui una query
Passa il metodo di incorporamento al metodo Endpoint.find_neighbors() per trovare nomi di prodotti simili.
# run query
response = my_index_endpoint.find_neighbors(
deployed_index_id = DEPLOYED_INDEX_ID,
queries = [query_emb],
num_neighbors = 10
)
# show the results
for idx, neighbor in enumerate(response[0]):
print(f"{neighbor.distance:.2f} {product_names[neighbor.id]}")
Il metodo find_neighbors() impiega solo millisecondi per recuperare elementi simili anche quando sono presenti miliardi di elementi nell'indice, grazie all'algoritmo ScaNN.
Vector Search supporta anche la scalabilità automatica, che può ridimensionare
automaticamente il numero di nodi in base alle esigenze dei tuoi carichi di lavoro.
esegui la pulizia
Se utilizzi il tuo progetto Cloud, non un progetto temporaneo su Qwiklabs, assicurati di eliminare tutti gli indici, gli endpoint indice e i bucket Cloud Storage al termine di questo tutorial. In caso contrario, potresti incorrere in costi imprevisti per le risorse rimanenti.
Se utilizzavi Workbench, potresti dover eliminare i blocchi note dalla console.
# wait for a confirmation
input("Press Enter to delete Index Endpoint, Index and Cloud Storage bucket:")
# delete Index Endpoint
my_index_endpoint.undeploy_all()
my_index_endpoint.delete(force = True)
# delete Index
my_index.delete()
# delete Cloud Storage bucket
! gsutil rm -r {BUCKET_URI}
Utilità
La creazione o il deployment degli indici potrebbe richiedere un po' di tempo e, nel frattempo, potresti perdere la connessione con il runtime Colab. Se perdi la connessione, anziché creare o eseguire nuovamente il deployment del nuovo indice, puoi controllare la console Google Cloud di Vector Search e utilizzare quelle esistenti per continuare.
Recupera un indice esistente
Per ottenere un oggetto indice già esistente, sostituisci il seguente your-index-id con l'ID indice ed esegui la cella. Puoi ottenere l'ID indice controllando
la console Google Cloud di Vector Search. Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Indici
my_index_id = "[your-index-id]"
my_index = aiplatform.MatchingEngineIndex(my_index_id)
Recupera un endpoint indice esistente
Per ottenere un oggetto endpoint indice già esistente, sostituisci il seguente your-index-endpoint-id con l'ID dell'endpoint indice ed esegui la cella.
Puoi ottenere l'endpoint indice controllando la console Google Cloud di Vector Search.
Nella sezione Vertex AI della console Google Cloud, vai alla sezione Deployment e utilizzo. Seleziona Endpoint indice
my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)