Questo tutorial mostra come creare un'applicazione di AI generativa utilizzando Spanner e Vertex AI.
Questa applicazione consente di eseguire la ricerca di similarità semantica, permettendoti di trovare prodotti che corrispondono a una query in linguaggio naturale. Per farlo, utilizza gli incorporamenti, ovvero rappresentazioni numeriche del testo che acquisiscono il significato e il contesto delle parole. Utilizzerai un modello Vertex AI per generare questi incorporamenti, per poi archiviarli e cercarli in Spanner. Questo approccio è particolarmente utile per casi d'uso come la ricerca di prodotti, in cui gli utenti potrebbero descrivere ciò che vogliono in linguaggio naturale anziché con parole chiave specifiche.
I seguenti argomenti ti aiutano a scoprire come:
- Creare un Google Cloud progetto
- Crea un'istanza Spanner
- Creare un database
- Crea un modello di incorporamento
- Caricare i dati in Spanner
- Generare incorporamenti per i dati
- Eseguire la ricerca di similarità vettoriale KNN
- Scalare la ricerca vettoriale con un indice vettoriale
- Pulire le risorse
Per informazioni dettagliate sui prezzi di Spanner, consulta la pagina Prezzi di Spanner.
Per provare un codelab, vedi Guida introduttiva alla ricerca vettoriale di Spanner.
Prima di iniziare
Devi creare un progetto Google Cloud collegato a un account di fatturazione.
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verify that billing is enabled for your Google Cloud project.
- L'API Spanner dovrebbe essere abilitata automaticamente. In caso contrario, attivalo manualmente: Abilita l'API Spanner
- L'API Vertex AI dovrebbe essere abilitata automaticamente. In caso contrario, attivalo manualmente: Abilita l'API Vertex AI
-
Per ottenere le autorizzazioni necessarie per creare istanze e database, chiedi all'amministratore di concederti il ruolo IAM Cloud Spanner Admin (
roles/spanner.admin
) nel progetto. -
Per ottenere le autorizzazioni necessarie per eseguire query sui grafici Spanner se non ti è stato concesso il ruolo Amministratore Cloud Spanner, chiedi all'amministratore di concederti il ruolo IAM Lettore database Cloud Spanner (
roles/spanner.databaseReader
) nel tuo progetto. Nella console Google Cloud , vai alla pagina Spanner.
Seleziona o crea un Google Cloud progetto, se non l'hai ancora fatto.
Esegui una di queste operazioni:
- Se non hai mai creato un'istanza Spanner, nella pagina Benvenuto in Spanner, fai clic su Crea un'istanza di cui è stato eseguito il provisioning.
- Se hai creato un'istanza Spanner, nella pagina Istanze, fai clic su Crea istanza.
Nella pagina Seleziona una versione, seleziona Enterprise Plus o Enterprise.
La ricerca vettoriale di Spanner è disponibile solo nelle versioni Enterprise o Enterprise Plus. Per confrontare le diverse versioni, fai clic su Confronta le versioni. Per ulteriori informazioni, consulta la panoramica delle versioni di Spanner.
Fai clic su Continua.
In Nome istanza, inserisci un nome per l'istanza, ad esempio
test-instance
.In ID istanza, mantieni o modifica l'ID istanza. L'ID istanza viene impostato per impostazione predefinita sul nome dell'istanza, ma puoi modificarlo. Il nome e l'ID istanza possono essere uguali o diversi.
Fai clic su Continua.
In Scegli una configurazione, segui questi passaggi:
- Mantieni selezionata l'opzione Regionale.
- In Seleziona una configurazione, seleziona una regione. La regione selezionata è dove vengono archiviate e replicate le istanze.
- Fai clic su Continua.
In Configura capacità di calcolo, segui questi passaggi:
- In Seleziona unità, seleziona Unità di elaborazione (PU).
- In Scegli una modalità di scalabilità, mantieni selezionata l'opzione Allocazione manuale e in Quantità mantieni 1000 unità di elaborazione.
Fai clic su Crea. La console Google Cloud mostra la pagina Panoramica dell'istanza che hai creato.
Nella console Google Cloud , vai alla pagina Istanze Spanner.
Fai clic sull'istanza che hai creato, ad esempio
test-instance
.In Panoramica, fai clic su Crea database sotto il nome dell'istanza.
In Nome database, inserisci un nome per il database. Ad esempio,
example-db
.In Seleziona dialetto database, scegli Google Standard SQL.
La ricerca vettoriale di Spanner non è disponibile nel dialetto PostgreSQL.
Copia e incolla il seguente schema nella scheda dell'editor Modelli DDL. Lo schema definisce una tabella
Products
.CREATE TABLE products ( categoryId INT64 NOT NULL, productId INT64 NOT NULL, productName STRING(MAX) NOT NULL, productDescription STRING(MAX) NOT NULL, productDescriptionEmbedding ARRAY<FLOAT32>, createTime TIMESTAMP NOT NULL OPTIONS ( allow_commit_timestamp = true ), inventoryCount INT64 NOT NULL, priceInCents INT64, ) PRIMARY KEY(categoryId, productId);
Non apportare modifiche in Mostra opzioni di crittografia.
Fai clic su Crea.La console Google Cloud mostra la pagina Panoramica per il database che hai creato.
- Nella pagina Panoramica del database, fai clic su Spanner Studio.
- Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.
Digita:
CREATE MODEL EmbeddingsModel INPUT( content STRING(MAX), ) OUTPUT( embeddings STRUCT<values ARRAY<FLOAT32>>, ) REMOTE OPTIONS ( endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/us-central1/publishers/google/models/TEXT_EMBEDDING_MODEL' );
Sostituisci quanto segue:
- PROJECT_ID: un identificatore permanente univoco per il tuo Google Cloud progetto.
- TEXT_EMBEDDING_MODEL: il nome del modello di incorporamento di testo. Per un elenco dei modelli di text embedding di Vertex AI, consulta Modelli supportati.
Fai clic su Esegui per creare il modello.
Una volta aggiunto il modello, lo vedrai visualizzato nel riquadro Explorer.
In una nuova scheda di Spanner Studio, copia e incolla la seguente istruzione insert:
INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents) VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999), (1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999), (1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900), (1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999), (1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999), (1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999), (1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999), (1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999), (1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999), (1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);
Fai clic su Esegui per inserire i dati.
In una nuova scheda di Spanner Studio, copia e incolla la seguente istruzione di aggiornamento:
UPDATE products p1 SET productDescriptionEmbedding = (SELECT embeddings.values FROM ML.PREDICT(MODEL EmbeddingsModel, (SELECT p1.productDescription as content) ) ) WHERE categoryId=1;
Fai clic su Esegui per generare gli incorporamenti.
- Utilizza
ML.PREDICT
per generare un embedding per la query di ricerca specificata ("Vorrei acquistare una bici per principianti per mio figlio di 3 anni"). - Calcola la
COSINE_DISTANCE
tra questo incorporamento della query e l'productDescriptionEmbedding
di ciascun prodotto nella tabella dei prodotti per trovare risultati simili nel tuo negozio Cymbal. - Filtra i risultati in modo da includere solo i prodotti con un
inventoryCount
maggiore di 0. - Ordina i risultati in base alla distanza calcolata e restituisce i primi cinque
corrispondenze più vicine, insieme a
productName
,productDescription
einventoryCount
. In una nuova scheda di Spanner Studio, copia e incolla la seguente query:
SELECT productName, productDescription, inventoryCount, COSINE_DISTANCE( productDescriptionEmbedding, ( SELECT embeddings.values FROM ML.PREDICT( MODEL EmbeddingsModel, (SELECT "I'd like to buy a starter bike for my 3 year old child" AS content)) )) AS distance FROM products WHERE inventoryCount > 0 ORDER BY distance LIMIT 5;
Fai clic su Esegui per restituire i prodotti che corrispondono meglio al testo di ricerca.
Output di esempio:
/*-----------------+--------------------+----------------+--------------------* | productName | productDescription | inventoryCount | distance | +------------------+--------------------+----------------+--------------------+ | Cymbal Sprout | Let their cycling | 10 | 0.3094387191860244 | | | journey begin with | | | | | the Cymbal Sprout, | | | | | the ideal balance | | | | | bike for beginning | | | | | riders ages 2-4 | | | | | years... | | | | Cymbal Spark Jr | Light, vibrant, | 34 | 0.3412342902117166 | | | and ready for | | | | | adventure, the | | | | | Spark Jr. is the | | | | | perfect first bike | | | | | for young riders | | | | | (ages 5-8)... | | | | Cymbal Helios | Safety meets style | 100 | 0.4197863319656684 | | Helmet | with the Cymbal | | | | | children's bike | | | | | helmet... | | | | Cymbal Breeze | Cruise in style and| 72 | 0.485231776523978 | | | embrace effortless | | | | | pedaling with the | | | | | Breeze electric | | | | | bike... | | | | Cymbal Phoenix | See and be seen | 87 | 0.525101413779242 | | Lights | with the Phoenix | | | | | bike lights... | | | *------------------+--------------------+----------------+--------------------*/
In una nuova scheda di Spanner Studio, copia e incolla la seguente istruzione DDL per ricreare la colonna
productDescriptionEmbedding
:ALTER TABLE products DROP COLUMN productDescriptionEmbedding; ALTER TABLE products ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH_VALUE);
Sostituisci
VECTOR_LENGTH_VALUE
con le dimensioni massime dell'output del modello di incorporamento che hai scelto.Fai clic su Esegui.
Copia e incolla la seguente istruzione di inserimento per rigenerare gli incorporamenti vettoriali:
UPDATE products p1 SET productDescriptionEmbedding = (SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel, (SELECT p1.productDescription as content))) WHERE categoryId=1;
Fai clic su Esegui.
Copia e incolla la seguente istruzione DDL per creare l'indice vettoriale:
CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex ON products(productDescriptionEmbedding) WHERE productDescriptionEmbedding IS NOT NULL OPTIONS ( distance_type = 'COSINE' );
Fai clic su Esegui.
- Genera l'embedding del prompt separatamente, anziché all'interno della query SQL.
- Copia i risultati degli incorporamenti nella query.
- Utilizza il suggerimento
FORCE_INDEX
per fare riferimento al nuovo indice vettoriale:@{force_index=ProductDescriptionEmbeddingIndex}
- Utilizza la funzione di distanza vettoriale
APPROX_COSINE_DISTANCE
anzichéCOSINE_DISTANCE
. L'opzioneJSON '{"num_leaves_to_search": num_leaves}'
è obbligatoria. In una nuova scheda di Spanner Studio, copia e incolla la seguente query per generare l'incorporamento del prompt:
-- Generate the prompt embedding SELECT embeddings.values FROM ML.PREDICT( MODEL EmbeddingsModel, (SELECT "I'd like to buy a starter bike for my 3 year old child" as content) );
Fai clic su Esegui.
Copia il risultato
embeddings.values
.Sostituisci
embedding
nella seguente query con il risultato dell'incorporamento che hai copiato nel passaggio precedente.-- Update embedding query using the vector index SELECT productName, productDescription, inventoryCount, (APPROX_COSINE_DISTANCE(productDescriptionEmbedding, array<float32>[embedding], options => JSON '{\"num_leaves_to_search\": 10}')) as distance FROM products @{force_index=ProductDescriptionEmbeddingIndex} WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0 ORDER BY distance LIMIT 5;
La nuova query SQL è simile alla seguente:
SELECT productName, productDescription, count, (APPROX_COSINE_DISTANCE(productDescriptionEmbedding, array<float32>[-0.00457216799,-0.0771846101,-0.0319350846,0.0352052487,-0.0457422845,0.0183265656...], options => JSON '{\"num_leaves_to_search\": 10}')) as distance FROM products @{force_index=ProductDescriptionEmbeddingIndex} WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0 ORDER BY distance LIMIT 5;
Output di esempio:
/*-----------------+--------------------+----------------+--------------------* | productName | productDescription | inventoryCount | distance | +------------------+--------------------+----------------+--------------------+ | Cymbal Sprout | Let their cycling | 10 | 0.30935457151661594| | | journey begin with | | | | | the Cymbal Sprout, | | | | | the ideal balance | | | | | bike for beginning | | | | | riders ages 2-4 | | | | | years... | | | | Cymbal Spark Jr | Light, vibrant, | 34 | 0.34116496551593656| | | and ready for | | | | | adventure, the | | | | | Spark Jr. is the | | | | | perfect first bike | | | | | for young riders | | | | | (ages 5-8)... | | | | Cymbal Helios | Safety meets style | 100 | 0.4198014303921187 | | Helmet | with the Cymbal | | | | | children's bike | | | | | helmet... | | | | Cymbal Breeze | Cruise in style and| 72 | 0.4850674854267337 | | | embrace effortless | | | | | pedaling with the | | | | | Breeze electric | | | | | bike... | | | | Cymbal Phoenix | See and be seen | 87 | 0.525101413779242 | | Lights | with the Phoenix | | | | | bike lights... | | | *------------------+--------------------+----------------+--------------------*/
Cymbal Sprout, con il suo
APPROX_COSINE_DISTANCE
di 0,30935457151661594, ha il più alto grado di somiglianza con la query originale.Per saperne di più sull'interpretazione della relazione tra le funzioni vettoriali e la similarità, vedi Scegliere tra le funzioni di distanza vettoriale per misurare la similarità degli embedding vettoriali.
Nella console Google Cloud , vai alla pagina Istanze Spanner.
Fai clic sul nome dell'istanza che contiene il database che vuoi eliminare, ad esempio test-instance.
Fai clic sul nome del database che vuoi eliminare, ad esempio example-db.
Nella pagina Panoramica del database, fai clic su Elimina Elimina database.
Conferma di voler eliminare il database inserendone il nome e facendo clic su Elimina.
Nella console Google Cloud , vai alla pagina Istanze Spanner.
Fai clic sul nome dell'istanza che vuoi eliminare, ad esempio test-instance.
Fai clic su Elimina istanza.
Conferma di voler eliminare l'istanza inserendo il nome dell'istanza e facendo clic su Elimina.
- Scopri di più sulla funzionalità k-nearest neighbor (KNN) di Spanner.
- Scopri di più sulla funzionalità di ricerca approssimativa del vicino più prossimo (ANN) di Spanner.
- Scopri di più su come eseguire previsioni online con SQL utilizzando Vertex AI.
Crea un'istanza
La prima volta che utilizzi Spanner, devi creare un'istanza, ovvero un'allocazione di risorse utilizzate dai database Spanner. Questa sezione mostra come creare un'istanza utilizzando la console Google Cloud .
Crea un database
Dopo l'avvio dell'istanza, puoi creare il database. Definisci lo schema nel database .
Crea un modello di incorporamento
Quando utilizzi l'istruzione DDL CREATE MODEL
in Spanner, registri un riferimento all'endpoint del modello Vertex AI dal tuo database. Dopo aver registrato
il modello, puoi utilizzare la funzione ML.PREDICT
per accedere al modello nelle query.
L'esempio seguente mostra come registrare un modello di text embedding di Vertex AI, che viene poi utilizzato per eseguire la ricerca di somiglianza per trovare prodotti simili in un database.
Carica dati
Per caricare i dati di esempio di Cymbal nella tabella products
:
Generare vector embedding
Dopo aver registrato un modello e caricato i dati in Spanner, puoi generare incorporamenti vettoriali con le descrizioni dei prodotti dai tuoi dati. I vector embedding trasformano i dati di testo in un valore numerico che acquisisce il significato e il contesto delle parole. Questa trasformazione è fondamentale per eseguire una ricerca semantica.
In questo passaggio, compilerai la colonna productDescriptionEmbedding
generando incorporamenti dalla colonna productDescription
utilizzando
ML.PREDICT
. Ciò ti consente di eseguire una ricerca di similarità vettoriale nel passaggio successivo.
Eseguire la ricerca sulla similarità vettoriale
Nell'esempio seguente, fornisci una richiesta di ricerca in linguaggio naturale utilizzando una query SQL. La query SQL esegue una ricerca di similarità vettoriale utilizzando gli incorporamenti vettoriali generati in precedenza. La query esegue la ricerca nel seguente modo:
Scalare la ricerca vettoriale per utilizzare i vicini più prossimi approssimati
L'esempio precedente di ricerca vettoriale utilizza la ricerca vettoriale esatta dei vicini k più prossimi (KNN). Le funzioni di distanza vettoriale KNN (distanza del coseno, distanza euclidea e prodotto scalare) sono utili quando puoi eseguire query su un sottoinsieme specifico dei tuoi dati Spanner. Poiché la ricerca KNN calcola la distanza esatta tra un vettore di query e tutti i vettori nel database, è efficiente quando puoi partizionare i dati. Se la query deve confrontare il vettore della query con tutti i vettori del database senza filtri specifici e non puoi dividere la query in sottoquery indipendenti, potresti riscontrare colli di bottiglia delle prestazioni se utilizzi KNN. La ricerca vettoriale approssimativa del vicino più prossimo (ANN) diventa utile in queste situazioni. Per saperne di più, vedi Trovare i vicini più prossimi approssimativi.
Se i tuoi carichi di lavoro non sono partizionabili e hai una grande quantità di dati, puoi utilizzare la ricerca vettoriale ANN per aumentare le prestazioni delle query per set di dati più grandi.
Per scalare e utilizzare la ricerca vettoriale ANN in Spanner:
Crea un indice vettoriale
Spanner accelera le ricerche vettoriali ANN utilizzando un indice vettoriale specializzato che sfrutta la tecnologia Scalable Nearest Neighbor (ScaNN) di Google Research.
Per creare un indice vettoriale nel set di dati, devi modificare la
colonna productDescriptionEmbeddings
per definire un'annotazione vector_length
.
L'annotazione vector_length
indica la dimensione di ogni vettore. Le
seguenti istruzioni DDL eliminano la colonna productDescriptionEmbedding
e la ricreano con vector_length
. La lunghezza (dimensione) massima del vettore varia a seconda del
modello di incorporamento
che hai scelto.
Utilizzare la funzione di distanza vettoriale ANN
Per utilizzare la ricerca vettoriale ANN in Spanner, modifica quanto segue nella query SQL:
Esegui la pulizia
Questa sezione mostra come utilizzare la console Google Cloud per ripulire le risorse. Per evitare addebiti aggiuntivi al tuo account di fatturazione Cloud, elimina il database e l'istanza che hai creato durante la configurazione. L'eliminazione di un'istanza elimina tutti i database creati nell'istanza.