Mulai menggunakan Spanner untuk aplikasi AI generatif

Tutorial ini menunjukkan cara membuat aplikasi AI generatif menggunakan Spanner dan Gemini Enterprise Agent Platform.

Aplikasi ini memungkinkan Anda melakukan penelusuran kemiripan semantik, sehingga Anda dapat menemukan produk yang cocok dengan kueri bahasa alami. Hal ini dicapai dengan menggunakan embedding, yang merupakan representasi numerik teks yang menangkap makna dan konteks kata. Anda akan menggunakan model Agent Platform untuk membuat embedding ini, lalu menyimpan dan menelusuri embedding di Spanner. Pendekatan ini sangat berguna untuk kasus penggunaan seperti penelusuran produk, di mana pengguna dapat mendeskripsikan apa yang mereka inginkan dalam bahasa alami, bukan kata kunci tertentu.

Topik berikut membantu Anda mempelajari cara:

  1. Membuat Google Cloud project
  2. Membuat instance Spanner
  3. Membuat database
  4. Membuat model embedding
  5. Memuat data ke Spanner
  6. Membuat embedding untuk data
  7. Melakukan penelusuran kemiripan vektor KNN
  8. Menskalakan penelusuran vektor dengan indeks vektor
  9. Membersihkan resource

Untuk mempelajari detail harga Spanner, lihat Harga Spanner.

Untuk mencoba codelab, lihat Memulai penelusuran vektor Spanner.

Sebelum memulai

Anda harus membuat Google Cloud project yang terhubung ke akun penagihan.

  1. Login keakun Anda. Google Cloud Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy 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. Spanner API akan otomatis diaktifkan. Jika tidak, aktifkan secara manual:

    Mengaktifkan Spanner API
  7. Agent Platform API akan otomatis diaktifkan. Jika tidak, aktifkan secara manual:

    Mengaktifkan Agent Platform API

  1. Untuk mendapatkan izin yang diperlukan untuk membuat instance dan database, minta administrator untuk memberi Anda peran IAM Cloud Spanner Admin (roles/spanner.admin) di project Anda.

  1. Untuk mendapatkan izin yang diperlukan untuk membuat kueri grafik Spanner jika Anda tidak diberi peran Cloud Spanner Admin, minta administrator untuk memberi Anda Cloud Spanner Database Reader (roles/spanner.databaseReader) peran IAM di project Anda.

Membuat instance

Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Bagian ini menunjukkan cara membuat instance menggunakan the Google Cloud console.

  1. Di Google Cloud konsol, buka halaman Spanner.

    Buka Spanner

  2. Pilih atau buat Google Cloud project jika Anda belum melakukannya.

  3. Lakukan salah satu hal berikut:

    1. Jika Anda belum pernah membuat instance Spanner, di halaman Welcome to Spanner, klik Create a provisioned instance.
    2. Jika Anda telah membuat instance Spanner, di halaman Instances, klik Create instance.

  4. Di halaman Select an edition, pilih Enterprise Plus atau Enterprise.

    Penelusuran vektor Spanner hanya tersedia di edisi Enterprise atau Enterprise Plus. Untuk membandingkan berbagai edisi, klik Compare editions. Untuk mengetahui informasi selengkapnya, lihat Ringkasan edisi Spanner.

  5. Klik Lanjutkan.

  6. Di Instance name, masukkan nama instance, misalnya, test-instance.

  7. Di Instance ID , pertahankan atau ubah ID instance. ID instance Anda secara default adalah nama instance, tetapi Anda dapat mengubahnya. Nama instance dan ID instance Anda dapat sama atau berbeda.

  8. Klik Lanjutkan.

  9. Di Choose a configuration, lakukan hal berikut:

    1. Pertahankan Regional dipilih.
    2. Di Select a configuration, pilih region. Region yang Anda pilih adalah tempat instance Anda disimpan dan direplikasi.
    3. Klik Lanjutkan.

  10. Di Configure compute capacity, lakukan hal berikut:

    1. Di Select unit, pilih Processing units (PUs).
    2. Di Choose a scaling mode, pertahankan Manual allocation dipilih dan di Quantity, pertahankan 1.000 unit pemrosesan.

  11. Klik Create. Konsol menampilkan halaman Overview untuk instance yang Anda buat. Google Cloud

Membuat database

Setelah instance mulai berjalan, Anda dapat membuat database. Anda menentukan skema dalam database .

  1. Di Google Cloud konsol, buka halaman Spanner Instances.

    Buka instance Spanner

  2. Klik instance yang Anda buat, misalnya, test-instance.

  3. Di Overview, di bagian nama instance Anda, klik Create database.

  4. Di Database name, masukkan nama database. Misalnya, example-db.

  5. Di Select database dialect, pilih Google Standard SQL.

    Penelusuran vektor Spanner tidak tersedia dalam dialek PostgreSQL.

  6. Salin dan tempel skema berikut ke tab editor DDL Templates. Skema ini menentukan tabel 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. Jangan lakukan perubahan apa pun di Show encryption options.

  8. Klik Create. Google Cloud Konsol menampilkan halaman Overview untuk database yang Anda buat.

Membuat model embedding

Saat menggunakan pernyataan CREATE MODEL DDL di Spanner, Anda mendaftarkan referensi ke endpoint model Agent Platform dari database Anda. Setelah mendaftarkan model, Anda dapat menggunakan ML.PREDICT fungsi untuk mengakses model dalam kueri Anda.

Contoh berikut menunjukkan cara mendaftarkan model embedding teks Agent Platform , yang kemudian digunakan untuk melakukan penelusuran kemiripan guna menemukan produk serupa dalam database.

  1. Di halaman Overview database, klik Spanner Studio.
  2. Di halaman Spanner Studio, klik New tab atau gunakan tab editor kosong.

  3. Masukkan:

    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'
);

    Ganti kode berikut:

    • PROJECT_ID: ID permanen yang unik untuk Google Cloud project Anda.
    • TEXT_EMBEDDING_MODEL: nama model embedding teks. Untuk mengetahui daftar model embedding teks Agent Platform, lihat Model yang didukung.

  4. Klik Run untuk membuat model.

    Setelah model berhasil ditambahkan, Anda akan melihatnya ditampilkan di panel Explorer.

Memuat data

Untuk memuat data sampel Cymbal ke dalam tabel products, lakukan hal berikut:

  1. Di tab baru di Spanner Studio, salin dan tempel pernyataan penyisipan berikut:

    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. Klik Run untuk menyisipkan data.

Membuat embedding vektor

Setelah mendaftarkan model dan memuat data ke Spanner, Anda dapat membuat embedding vektor dengan deskripsi produk dari data Anda. Embedding vektor mengubah data teks menjadi nilai numerik yang menangkap makna dan konteks kata. Transformasi ini sangat penting untuk melakukan penelusuran semantik.

Pada langkah ini, Anda akan mengisi kolom productDescriptionEmbedding dengan membuat embedding dari kolom productDescription menggunakan ML.PREDICT. Hal ini memungkinkan Anda melakukan penelusuran kemiripan vektor pada langkah berikutnya.

  1. Di tab baru di Spanner Studio, salin dan tempel pernyataan update berikut:

    UPDATE products p1
SET productDescriptionEmbedding =
  (SELECT embeddings.values
    FROM ML.PREDICT(MODEL EmbeddingsModel,
      (SELECT p1.productDescription as content)
    )
  )
WHERE categoryId=1;

  2. Klik Run untuk membuat embedding.

Dalam contoh berikut, Anda memberikan permintaan penelusuran bahasa alami menggunakan kueri SQL. Kueri SQL melakukan penelusuran kemiripan vektor menggunakan embedding vektor yang Anda buat sebelumnya. Kueri melakukan penelusuran dengan melakukan hal berikut:

  • Menggunakan ML.PREDICT untuk membuat embedding untuk kueri penelusuran yang diberikan ("I'd like to buy a starter bike for my 3 year old child").
  • Menghitung COSINE_DISTANCE antara embedding kueri ini dan productDescriptionEmbedding setiap produk dalam tabel produk untuk menemukan hasil yang serupa di toko Cymbal Anda.
  • Memfilter hasil agar hanya menyertakan produk dengan inventoryCount yang lebih besar dari 0.
  • Mengurutkan hasil berdasarkan jarak yang dihitung dan menampilkan lima kecocokan terdekat, beserta productName, productDescription, dan inventoryCount.

  1. Di tab baru di Spanner Studio, salin dan tempel kueri berikut:

    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. Klik Run untuk menampilkan produk yang paling cocok dengan teks penelusuran Anda.

    Contoh output:

    /*-----------------+--------------------+----------------+--------------------*
| 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...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

Contoh penelusuran vektor sebelumnya menggunakan penelusuran vektor tetangga terdekat (KNN) yang tepat, . Fungsi jarak vektor KNN (jarak kosinus, jarak Euclidean, dan perkalian titik) berguna saat Anda dapat membuat kueri subset data Spanner tertentu. Karena penelusuran KNN menghitung jarak yang tepat antara vektor kueri dan semua vektor dalam database, penelusuran ini efisien saat Anda dapat mempartisi data. Jika kueri Anda perlu membandingkan vektor kueri dengan semua vektor dalam database tanpa filter tertentu, dan Anda tidak dapat membagi kueri menjadi subkueri independen, Anda mungkin mengalami bottleneck performa jika menggunakan KNN. Penelusuran vektor perkiraan tetangga terdekat (ANN) menjadi berguna dalam situasi ini. Untuk mengetahui informasi selengkapnya, lihat Menemukan perkiraan tetangga terdekat.

Jika workload Anda tidak dapat dipartisi, dan Anda memiliki data dalam jumlah besar, Anda dapat menggunakan penelusuran vektor ANN untuk meningkatkan performa kueri untuk set data yang lebih besar.

Untuk menskalakan dan menggunakan penelusuran vektor ANN di Spanner, lakukan hal berikut:

Membuat indeks vektor

Spanner mempercepat penelusuran vektor ANN dengan menggunakan indeks vektor khusus yang memanfaatkan Scalable Nearest Neighbor (ScaNN) Google Research.

Untuk membuat indeks vektor dalam set data, Anda harus mengubah kolom productDescriptionEmbeddings untuk menentukan anotasi vector_length. Anotasi vector_length menunjukkan dimensi setiap vektor. Pernyataan DDL berikut menghapus kolom productDescriptionEmbedding, dan membuatnya kembali dengan vector_length. Panjang (dimensi) maksimum vektor bervariasi bergantung pada model embedding yang Anda pilih.

  1. Di tab baru di Spanner Studio, salin dan tempel pernyataan DDL berikut untuk membuat ulang kolom productDescriptionEmbedding:

    ALTER TABLE products DROP COLUMN productDescriptionEmbedding;
ALTER TABLE products
  ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH_VALUE);

    Ganti VECTOR_LENGTH_VALUE dengan dimensi output maksimum model embedding yang Anda pilih.

  2. Klik Run.

  3. Salin dan tempel pernyataan penyisipan berikut untuk membuat ulang embedding vektor:

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

  4. Klik Run.

  5. Salin dan tempel pernyataan DDL berikut untuk membuat indeks vektor:

    CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex
    ON products(productDescriptionEmbedding)
    WHERE productDescriptionEmbedding IS NOT NULL
OPTIONS (
distance_type = 'COSINE'
);

  6. Klik Run.

Menggunakan fungsi jarak vektor ANN

Untuk menggunakan penelusuran vektor ANN di Spanner, ubah hal berikut dalam kueri SQL Anda:

  • Buat embedding perintah secara terpisah, bukan dalam kueri SQL.
  • Salin hasil embedding ke dalam kueri.
  • Gunakan petunjuk FORCE_INDEX untuk mereferensikan indeks vektor baru: @{force_index=ProductDescriptionEmbeddingIndex}
  • Gunakan fungsi jarak vektor APPROX_COSINE_DISTANCE, bukan COSINE_DISTANCE. Opsi JSON '{"num_leaves_to_search": num_leaves}' diperlukan.

  1. Di tab baru di Spanner Studio, salin dan tempel kueri berikut untuk membuat embedding perintah dan melakukan penelusuran vektor:

    -- 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. Klik Run.

    Contoh output:

    /*-----------------+--------------------+----------------+--------------------*
| 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, dengan APPROX_COSINE_DISTANCE sebesar 0,30935457151661594, memiliki tingkat kemiripan tertinggi dengan kueri asli.

    Untuk mengetahui informasi selengkapnya tentang cara menginterpretasikan hubungan antara fungsi vektor dan kemiripan, lihat Memilih di antara fungsi jarak vektor untuk mengukur kemiripan embedding vektor.

Pembersihan

Bagian ini menunjukkan cara menggunakan Google Cloud console untuk membersihkan resource Anda. Untuk menghindari biaya tambahan ke akun Penagihan Cloud Anda, hapus database dan instance yang Anda buat selama penyiapan. Menghapus instance akan menghapus semua database yang dibuat di instance tersebut.

Menghapus database

  1. Di Google Cloud konsol, buka halaman Spanner Instances.

    Buka instance Spanner

  2. Klik nama instance yang memiliki database yang ingin Anda hapus, misalnya, test-instance.

  3. Klik nama database yang ingin Anda hapus, misalnya, example-db.

  4. Di halaman Database overview, klik delete Delete database.

  5. Konfirmasi bahwa Anda ingin menghapus database dengan memasukkan nama database dan mengklik Delete.

Menghapus instance

  1. Di Google Cloud konsol, buka halaman Spanner Instances.

    Buka instance Spanner

  2. Klik nama instance yang ingin Anda hapus, misalnya, test-instance.

  3. Klik Delete instance.

  4. Konfirmasi bahwa Anda ingin menghapus instance dengan memasukkan nama instance dan mengklik Delete.

Apa langkah selanjutnya?