Nella guida rapida di Vector Search su Gemini Enterprise Agent Platform, scopri come creare un indice da un set di dati di esempio di un sito di e-commerce di abbigliamento fittizio. Ai fini di questa guida rapida, gli embedding sono già stati creati. Questa guida rapida è pensata per aiutarti a iniziare 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, consulta Configura 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 su Gemini Enterprise Agent Platform Workbench.
- Colab: apri questo tutorial in Colab
- Gemini Enterprise Agent Platform Workbench: apri questo tutorial in Gemini Enterprise Agent Platform Workbench. Se è la prima volta che utilizzi Gemini Enterprise Agent Platform Workbench nel tuo progetto Google Cloud , vai alla sezione Gemini Enterprise Agent Platform Workbench della console Google Cloud e fai clic su Abilita per abilitare l'API Notebooks.
Per visualizzare questo notebook in GitHub, consulta GitHub.
Costo per completare questa guida rapida
Il completamento di questo tutorial costa circa un paio di dollari. I prezzi dei servizi Google Cloud utilizzati in questo tutorial sono disponibili nelle seguenti pagine:
- Gemini Enterprise Agent Platform Vector Search
- Cloud Storage
- Gemini Enterprise Agent Platform Workbench
Puoi anche utilizzare il Calcolatore prezzi per generare una stima dei costi in base all'utilizzo previsto.
Configurazione
Prima di iniziare a utilizzare Gemini Enterprise Agent Platform, devi configurare quanto segue:
- Installa l'SDK Agent Platform per Python
- Imposta le variabili di ambiente
- Autenticazione (solo Colab)
- Imposta autorizzazioni IAM
- Abilita le API
Installa l'SDK Agent Platform per Python
È possibile accedere alle API Gemini Enterprise Agent Platform e Cloud Storage in diversi modi, tra cui l'API REST e l'SDK Agent Platform per Python. In questo tutorial viene utilizzato l'SDK Agent Platform 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 seguente.
# 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 la seguente cella di autenticazione. Questo passaggio non è necessario se utilizzi Gemini Enterprise Agent Platform Workbench, poiché è pre-autenticato.
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 il seguente aspetto:
compute@ - Fai clic sul pulsante di modifica e concedi al account di servizio Compute predefinito i seguenti ruoli: Agent Platform User, Storage Admin e Service Usage Admin.
Abilita API
Esegui il comando seguente per abilitare le API per Compute Engine, Gemini Enterprise Agent Platform 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 campionati
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 e-commerce di abbigliamento fittizio.

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

Questo file è in formato JSONL e ogni riga contiene l'ID prodotto, il nome del prodotto e l'embedding del nome del prodotto in 768 dimensioni, generato in precedenza con gli embedding per il testo di Gemini Enterprise Agent Platform.
I text embedding 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 gli embedding dai dati di una tabella BigQuery e archiviarli in un file JSON, consulta Introduzione ai text embedding + Vector Search di Gemini Enterprise Agent Platform.
Prepara i dati su Cloud Storage
Per creare un indice con Gemini Enterprise Agent Platform, inserisci il file di embedding in un bucket Cloud Storage. Il codice seguente completa due attività:
- Crea un bucket Cloud Storage.
- Copia il file di esempio nel 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 Vector Search per eseguire query, devi anche copiare il file di embedding 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, creare un endpoint indice ed eseguire il deployment dell'indice nell'endpoint.
Crea un indice
Ora è il momento di caricare gli embedding 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 relativa 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 = 100,
)
Il metodo MatchingEngineIndex.create_tree_ah_index() crea un indice.
L'operazione richiede meno di 10 minuti se il set di dati è di piccole dimensioni, 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
I parametri per la creazione dell'indice:
contents_delta_uri: l'URI della directory di Cloud Storage in cui hai archiviato i file JSON di embeddingdimensions: la dimensione di ogni embedding. In questo caso, è 768, poiché stai utilizzando gli embedding dell'API Text Embeddings.approximate_neighbors_count: il numero di elementi simili che vuoi recuperare in casi tipici
Per scoprire di più sulla creazione dell'indice e sui parametri disponibili, consulta Crea e gestisci 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 indice, la creazione e l'avvio automatici del backend possono richiedere circa 30 minuti. Per visualizzare lo stato del deployment dell'indice, vai alla sezione Esegui il deployment e utilizza nella sezione Agent Platform della consoleGoogle Cloud . Seleziona Indici.
Esegui una query con Vector Search
Nel codice seguente, trova un embedding per un nome di prodotto specificato e trova nomi di prodotti simili con Vector Search.
Ottieni un embedding per eseguire una query
Innanzitutto, carica il file JSON di embedding per creare un dict di nomi di prodotti ed embedding.
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'embedding 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 nell'indice sono presenti miliardi di elementi, 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 workload.
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 dopo aver completato questo tutorial. In caso contrario, potresti sostenere costi imprevisti per le risorse rimanenti.
Se hai utilizzato Workbench, potresti anche dover eliminare i notebook 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 un po' di tempo e, nel frattempo, potresti perdere la connessione al runtime di Colab. Se perdi la connessione, invece di creare o eseguire nuovamente il deployment del nuovo indice, puoi controllare la console di Vector SearchGoogle Cloud e utilizzare quelli esistenti per continuare.
Ottieni 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 Agent Platform della console Google Cloud , vai alla sezione Esegui il deployment e utilizza. 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 your-index-endpoint-id con l'ID endpoint indice ed esegui la cella.
Puoi ottenere l'endpoint indice controllando la console Vector Search Google Cloud .
Nella sezione Agent Platform della console Google Cloud , vai alla sezione Esegui il deployment e utilizza. Seleziona Endpoint indice.
Visualizza gli endpoint indice
my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)