Questa pagina è stata tradotta dall'API Cloud Translation.

Guida rapida di Ricerca vettoriale

Nella guida rapida di Vertex AI Vector Search, scopri come creare un indice da un set di dati di esempio di un sito fittizio di abbigliamento per l'e-commerce. Ai fini di questa guida rapida, gli incorporamenti sono già stati creati. Questa guida rapida ha lo scopo di aiutarti a iniziare a creare e implementare 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, consulta Configurare un progetto e un ambiente di sviluppo. Devi creare un progetto e configurare il tuo account di fatturazione.

Scegliere 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 tuo Google Cloud progetto, 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 circa qualche dollaro statunitense. 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:

Installare l'SDK Vertex AI Python

È possibile 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 nel seguente snippet di codice.

# 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 l'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 notebook su Colab, devi eseguire l'autenticazione della cella seguente. Questo passaggio non è necessario se utilizzi Vertex AI Workbench, poiché è 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()

Imposta autorizzazioni IAM

Devi aggiungere le autorizzazioni di accesso al account di servizio predefinito per utilizzare i servizi.

Vai alla pagina IAM nella console Google Cloud .
Cerca l'entità per il account di servizio Compute predefinito. Dovrebbe avere questo aspetto: compute@developer.gserviceaccount.com
Fai clic sul pulsante di modifica e concedi al account di servizio Compute predefinito i seguenti ruoli: Utente Vertex AI, Amministratore Storage e Amministratore utilizzo servizi.

Abilita API

Esegui il comando seguente 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 5000 righe di dati di prodotto sintetici per un sito di abbigliamento e-commerce fittizio.

Set di dati di esempio

Da questa tabella abbiamo preparato il file product-embs.json.

Incorporamenti di prodotti di esempio

Questo file è in formato JSONL e ogni riga contiene l'ID per l'ID prodotto, il nome per il 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 la ricerca vettoriale per completare una ricerca semantica degli elementi. Questo codice campione può essere utilizzato come base per altri sistemi di consigli rapidi in cui puoi trovare rapidamente "altri prodotti simili a questo".

Per scoprire di più su come creare gli incorporamenti dai dati di una tabella BigQuery e archiviarli in un file JSON, consulta Guida introduttiva agli incorporamenti di testo e a Vertex AI Vector Search.

Prepara i dati su Cloud Storage

Per creare un indice con Vertex AI, inserisci 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}"

! gcloud storage buckets create $BUCKET_URI --location=$LOCATION --project=$PROJECT_ID
! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

Per utilizzare la ricerca vettoriale per eseguire query, devi anche copiare il file di incorporamento nella directory locale:

! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests

Crea ed esegui il deployment di un indice Vector Search

Scopri come creare un indice, un endpoint indice e poi eseguire il deployment dell'indice sull'endpoint.

Crea un indice

Ora è il momento di caricare gli incorporamenti in Ricerca vettoriale. 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 relativa funzione create_tree_ah_index (Matching Engine è il nome precedente di Ricerca vettoriale).

# 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 = 100,
)

Il metodo MatchingEngineIndex.create_tree_ah_index() crea un indice. Se il set di dati è piccolo, l'operazione richiede meno di 10 minuti, altrimenti circa 60 minuti o più, a seconda delle dimensioni del set di dati. Puoi controllare lo stato della creazione dell'indice nella console Vector Search Google Cloud

Visualizza indici

I parametri per la creazione dell'indice:

contents_delta_uri: l'URI della directory Cloud Storage in cui hai archiviato i file JSON degli incorporamenti
dimensions: la dimensione della dimensione di ogni incorporamento. In questo caso, è 768 perché utilizzi gli embedding dell'API text embeddings.
approximate_neighbors_count: il numero di articoli simili che vuoi recuperare nei casi tipici

Per scoprire di più sulla creazione dell'indice e sui parametri disponibili, consulta Creare e gestire l'indice.

Crea l'endpoint indice ed esegui il deployment dell'indice

Per utilizzare l'indice, devi creare un endpoint indice. Funziona come un'istanza 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 di cui è stato eseguito il deployment univoco.

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 di indice, potrebbero essere necessari circa 30 minuti per creare e inizializzare automaticamente il backend. Per visualizzare lo stato del deployment dell'indice, vai alla sezione Deploy e utilizzo nella sezione Vertex AI della consoleGoogle Cloud . Seleziona Indici.

Visualizza gli indici

Eseguire una query con la ricerca vettoriale

Nel codice seguente, viene trovata un'incorporamento per un nome prodotto specificato e vengono trovati nomi di prodotti simili con la ricerca vettoriale.

Ottenere un embedding per eseguire una query

Innanzitutto, carica il file JSON di incorporamento per creare un dict di nomi di prodotti 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 ottenere un embedding.

 # 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 l'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 gli elementi simili anche quando hai 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.

Pulizia

Se utilizzi un tuo progetto Cloud, non un progetto temporaneo su Qwiklabs, assicurati di eliminare tutti gli indici, gli endpoint di indice e i bucket Cloud Storage al termine di questo tutorial. In caso contrario, potresti incorrere in costi imprevisti per le risorse rimanenti.

Se hai utilizzato Workbench, potresti dover eliminare i notebook anche 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
! gcloud storage rm {BUCKET_URI} --recursive

Utilità

La creazione o il deployment degli indici può richiedere del tempo e, nel frattempo, potresti perdere la connessione con il runtime di Colab. Se la connessione viene interrotta, anziché creare o eseguire di nuovo il deployment del nuovo indice, puoi controllare la console Google Cloud di Vector Search e utilizzare quelli esistenti per continuare.

Recuperare un indice esistente

Per ottenere un oggetto indice già esistente, sostituisci your-index-id con l'ID indice ed esegui la cella. Puoi ottenere l'ID indice controllando la console Vector Search Google Cloud . Nella sezione Vertex AI della console Google Cloud , vai alla sezione Deployment e utilizzo. Seleziona Indici.