Inizia a utilizzare Spanner per le applicazioni di AI generativa

Questo tutorial mostra come creare un'applicazione di AI generativa utilizzando Spanner e Vertex AI.

Questa applicazione ti consente di eseguire una ricerca di similarità semantica, permettendoti di trovare prodotti che corrispondono a una query in linguaggio naturale. Per farlo, utilizza gli embedding, che sono rappresentazioni numeriche del testo che acquisiscono il significato e il contesto delle parole. Utilizzerai un modello Vertex AI per generare questi embedding, quindi li archivierai e li cercherai 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.

Gli argomenti seguenti ti aiutano a scoprire come:

  1. Creare un Google Cloud progetto
  2. Creare un'istanza di Spanner
  3. Creare un database
  4. Creare un modello di embedding
  5. Caricare i dati in Spanner
  6. Generare embedding per i dati
  7. Eseguire la ricerca di similarità vettoriale KNN
  8. Scalare la ricerca vettoriale con un indice vettoriale
  9. Liberare spazio

Per informazioni dettagliate sui prezzi di Spanner, consulta Prezzi di Spanner.

Per provare un codelab, consulta Inizia a utilizzare la ricerca vettoriale di Spanner.

Prima di iniziare

Devi creare un Google Cloud progetto collegato a un account di fatturazione.

  1. Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. L'API Spanner dovrebbe essere abilitata automaticamente. In caso contrario, abilitala manualmente:

    Abilita l'API Spanner
  7. L'API Vertex AI dovrebbe essere abilitata automaticamente. In caso contrario, abilitala manualmente:

    Abilita l'API Vertex AI
  1. Per ottenere le autorizzazioni necessarie per creare istanze e database, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Cloud Spanner (roles/spanner.admin) nel tuo progetto.

  1. Per ottenere le autorizzazioni necessarie per eseguire query sui grafici di Spanner se non ti è stato concesso il ruolo Amministratore di Cloud Spanner, chiedi all'amministratore di concederti il ruolo IAM Lettore di database Cloud Spanner (roles/spanner.databaseReader) nel tuo progetto.

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 Google Cloud console.

  1. Nella Google Cloud console, vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona o crea un Google Cloud progetto, se non l'hai già fatto.

  3. Esegui una delle seguenti operazioni:

    1. Se non hai mai creato un'istanza di Spanner, nella pagina Benvenuto in Spanner, fai clic su Crea un'istanza di cui è stato eseguito il provisioning.
    2. Se hai creato un'istanza di Spanner, nella pagina Istanze, fai clic su Crea istanza.
  4. Nella pagina Seleziona una versione, seleziona Enterprise Plus o Enterprise.

    La ricerca vettoriale di Spanner è disponibile solo nella versione Enterprise o Enterprise Plus. Per confrontare le diverse versioni, fai clic su Confronta versioni. Per saperne di più, consulta la Panoramica delle versioni di Spanner.

  5. Fai clic su Continua.

  6. In Nome istanza, inserisci un nome dell'istanza, ad esempio, test-instance.

  7. In ID istanza , mantieni o modifica l'ID istanza. Per impostazione predefinita, l'ID istanza corrisponde al nome dell'istanza, ma puoi modificarlo. Il nome e l'ID istanza possono essere uguali o diversi.

  8. Fai clic su Continua.

  9. In Scegli una configurazione, segui questi passaggi:

    1. Mantieni selezionata l'opzione A livello di regione.
    2. In Seleziona una configurazione, seleziona una regione. La regione selezionata è quella in cui vengono archiviate e replicate le istanze.
    3. Fai clic su Continua.
  10. In Configura capacità di calcolo, segui questi passaggi:

    1. In Seleziona unità, seleziona Unità di elaborazione (PU).
    2. In Scegli una modalità di scalabilità, mantieni selezionata l'opzione Allocazione manuale e in Quantità mantieni 1000 unità di elaborazione.
  11. Fai clic su Crea. La Google Cloud console visualizza la pagina Panoramica dell' istanza che hai creato.

Crea un database

Dopo l'avvio dell'istanza, puoi creare il database. Definisci lo schema nel database .

  1. Nella Google Cloud console, vai alla pagina Istanze Spanner.

    Vai alle istanze Spanner

  2. Fai clic sull'istanza che hai creato, ad esempio test-instance.

  3. In Panoramica, sotto il nome dell'istanza, fai clic su Crea database.

  4. In Nome database, inserisci un nome del database. Ad esempio, example-db.

  5. In Seleziona dialetto database, scegli GoogleSQL standard.

    La ricerca vettoriale di Spanner non è disponibile nel dialetto PostgreSQL.

  6. Copia e incolla lo schema seguente 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);
    
  7. Non apportare modifiche in Mostra opzioni di crittografia.

  8. Fai clic su Crea. Google Cloud La console visualizza la pagina Panoramica del database che hai creato.

Crea un modello di embedding

Quando utilizzi l'CREATE MODEL istruzione DDL in Spanner, registri un riferimento all' endpoint del modello Vertex AI dal tuo database. Dopo aver registrato il modello, puoi utilizzare la ML.PREDICT funzione per accedere al modello nelle query.

L'esempio seguente mostra come registrare un modello di text embedding Vertex AI , che viene poi utilizzato per eseguire la ricerca di similarità per trovare prodotti simili in un database.

  1. Nella pagina Panoramica del database, fai clic su Spanner Studio.
  2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.
  3. 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 text embedding. Per un elenco dei modelli di text embedding Vertex AI, consulta Modelli supportati.
  4. Fai clic su Esegui per creare il modello.

    Dopo aver aggiunto correttamente il modello, lo vedrai visualizzato nel riquadro Explorer.

Carica dati

Per caricare i dati di esempio di Cymbal nella tabella products:

  1. In una nuova scheda di Spanner Studio, copia e incolla la seguente istruzione di inserimento:

    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);
    
  2. Fai clic su Esegui per inserire i dati.

Genera vector embedding

Dopo aver registrato un modello e caricato i dati in Spanner, puoi generare vector embedding 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, popolerai la colonna productDescriptionEmbedding generando embedding dalla colonna productDescription utilizzando ML.PREDICT. In questo modo, nel passaggio successivo potrai eseguire una ricerca di similarità vettoriale.

  1. 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;
    
  2. Fai clic su Esegui per generare gli embedding.

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 i vector embedding generati in precedenza. La query esegue la ricerca nel seguente modo:

  • Utilizza ML.PREDICT per generare un embedding per la query di ricerca specificata ("Vorrei comprare una bici per principianti per mio figlio di 3 anni").
  • Calcola la COSINE_DISTANCE tra questo embedding della query e la productDescriptionEmbedding di ogni 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 le prime cinque corrispondenze più vicine, insieme a productName, productDescription e inventoryCount.
  1. 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;
    
  2. 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...     |                |                    |
    *------------------+--------------------+----------------+--------------------*/
    

L'esempio precedente di ricerca vettoriale utilizza la ricerca vettoriale esatta, del vicino più prossimo (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 dati di 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 di query con tutti i vettori nel database senza filtri specifici e non puoi dividere la query in sottoquery indipendenti, potresti riscontrare colli di bottiglia delle prestazioni se utilizzi KNN. In queste situazioni, la ricerca vettoriale del vicino più prossimo approssimato (ANN) diventa utile. Per saperne di più, consulta Trovare i vicini più prossimi approssimati.

Se i tuoi workload non sono partizionabili e hai una grande quantità di dati, puoi utilizzare la ricerca vettoriale ANN per aumentare il rendimento 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 Scalable Nearest Neighbor (ScaNN) di Google Research's .

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 massima (dimensione) del vettore varia a seconda del modello di embedding scelto.

  1. 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 di output massime del modello di embedding scelto.

  2. Fai clic su Esegui.

  3. Copia e incolla la seguente istruzione di inserimento per rigenerare i vector embedding:

    UPDATE products p1
    SET productDescriptionEmbedding =
    (SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel,
    (SELECT p1.productDescription as content)))
    WHERE categoryId=1;
    
  4. Fai clic su Esegui.

  5. 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'
    );
    
  6. Fai clic su Esegui.

Utilizza la funzione di distanza vettoriale ANN

Per utilizzare la ricerca vettoriale ANN in Spanner, modifica quanto segue nella query SQL:

  • Genera l'embedding del prompt separatamente, anziché all'interno della query SQL.
  • Copia i risultati degli embedding 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'opzione JSON '{"num_leaves_to_search": num_leaves}' è obbligatoria.
  1. In una nuova scheda di Spanner Studio, copia e incolla la seguente query per generare l'embedding del prompt ed eseguire la ricerca vettoriale:

    -- Generate the prompt embedding
    WITH embedding AS (
      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)
      )
    )
    -- Use embedding to find the most similar entries in the database
    SELECT productName, productDescription, inventoryCount,
      (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
       embedding.values,
      options => JSON '{"num_leaves_to_search": 10}')) as distance
    FROM products @{force_index=ProductDescriptionEmbeddingIndex}, embedding
    WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
    ORDER BY distance
    LIMIT 5;
    
  2. Fai clic su Esegui.

    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 una APPROX_COSINE_DISTANCE di 0,30935457151661594, ha il massimo grado di similarità con la query originale.

    Per saperne di più sull'interpretazione della relazione tra le funzioni vettoriali e la similarità, consulta Scegliere tra le funzioni di distanza vettoriale per misurare la similarità dei vector embedding.

Libera spazio

Questa sezione mostra come utilizzare la Google Cloud console per eseguire la pulizia delle risorse. Per evitare addebiti aggiuntivi sul 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.

Elimina il database

  1. Nella Google Cloud console, vai alla pagina Istanze Spanner.

    Vai alle istanze Spanner

  2. Fai clic sul nome dell'istanza che contiene il database che vuoi eliminare, ad esempio test-instance.

  3. Fai clic sul nome del database che vuoi eliminare, ad esempio example-db.

  4. Nella pagina Panoramica database, fai clic su Elimina Elimina database.

  5. Conferma di voler eliminare il database inserendone il nome e facendo clic su Elimina.

Elimina l'istanza

  1. Nella Google Cloud console, vai alla pagina Istanze Spanner.

    Vai alle istanze Spanner

  2. Fai clic sul nome dell'istanza che vuoi eliminare, ad esempio test-instance.

  3. Fai clic su Elimina istanza.

  4. Conferma di voler eliminare l'istanza inserendone il nome e facendo clic su Elimina.

Passaggi successivi