Mulai menggunakan Spanner untuk aplikasi AI generatif

Tutorial ini menunjukkan cara membangun aplikasi AI generatif menggunakan Spanner dan Vertex AI.

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 Vertex AI 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. Buat instance Spanner
  3. Membuat database
  4. Membuat model embedding
  5. Memuat data ke Spanner
  6. Menghasilkan 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 Mulai menggunakan penelusuran vektor Spanner.

Sebelum memulai

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

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    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.

    Go to project selector

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

  6. Spanner API akan diaktifkan secara otomatis. Jika tidak, aktifkan secara manual:

    Aktifkan Spanner API
  7. Vertex AI API akan diaktifkan secara otomatis. Jika tidak, aktifkan secara manual:

    Mengaktifkan Vertex AI 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 Admin Cloud Spanner, minta administrator Anda untuk memberi Anda peran IAM Cloud Spanner Database Reader (roles/spanner.databaseReader) di project Anda.

    Membuat instance

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

    1. Di Google Cloud console, 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 Pilih edisi, pilih Enterprise Plus atau Enterprise.

      Penelusuran vektor Spanner hanya tersedia di edisi Enterprise atau Enterprise Plus. Untuk membandingkan berbagai edisi, klik Bandingkan edisi. 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 bisa sama atau berbeda.

    8. Klik Lanjutkan.

    9. Di Pilih konfigurasi, lakukan hal berikut:

      1. Biarkan Regional tetap dipilih.
      2. Di Pilih konfigurasi, pilih wilayah. Region yang Anda pilih adalah tempat instance Anda disimpan dan direplikasi.
      3. Klik Lanjutkan.
    10. Di Configure compute capacity, lakukan hal berikut:

      1. Di Pilih unit, pilih Unit pemrosesan (PU).
      2. Di Pilih mode penskalaan, tetap pilih Alokasi manual dan di Jumlah, tetap gunakan 1.000 unit pemrosesan.
    11. Klik Buat. Konsol Google Cloud menampilkan halaman Ringkasan untuk instance yang Anda buat.

    Buat database

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

    1. Di konsol Google Cloud , 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 Nama database, masukkan nama database. Contoh, 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 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 buat perubahan apa pun di Tampilkan opsi enkripsi.

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

    Membuat model embedding

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

    Contoh berikut menunjukkan cara mendaftarkan model embedding teks Vertex AI, 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 Tab baru atau gunakan tab editor yang kosong.
    3. Enter:

      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 project Google Cloud Anda.
      • TEXT_EMBEDDING_MODEL: nama model embedding teks. Untuk mengetahui daftar model penyematan teks Vertex AI, lihat Model yang didukung.
    4. Klik Run untuk membuat model.

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

    Muat 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 penyematan untuk kueri penelusuran tertentu ("Saya ingin membeli sepeda pemula untuk anak saya yang berusia 3 tahun").
    • Menghitung COSINE_DISTANCE antara sematan kueri ini dan productDescriptionEmbedding setiap produk dalam tabel produk untuk menemukan hasil serupa di toko Cymbal Anda.
    • Memfilter hasil agar hanya menyertakan produk dengan inventoryCount 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 Jalankan 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 K-terdekat (KNN) yang tepat. Fungsi jarak vektor KNN (jarak kosinus, jarak Euclidean, dan produk titik) berguna saat Anda dapat membuat kueri subset tertentu dari data Spanner Anda. Karena penelusuran KNN menghitung jarak yang tepat antara vektor kueri dan semua vektor dalam database, penelusuran ini efisien jika 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 hambatan performa jika menggunakan KNN. Penelusuran vektor perkiraan tetangga terdekat (ANN) menjadi berguna dalam situasi ini. Untuk mengetahui informasi selengkapnya, lihat Menemukan tetangga terdekat perkiraan.

    Jika workload Anda tidak dapat dipartisi, dan Anda memiliki sejumlah besar data, 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) dari Google Research.

    Untuk membuat indeks vektor dalam set data, Anda perlu mengubah kolom productDescriptionEmbeddings untuk menentukan anotasi vector_length. Anotasi vector_length menunjukkan dimensi setiap vektor. Pernyataan DDL berikut akan menghapus kolom productDescriptionEmbedding, dan membuatnya kembali dengan vector_length. Panjang maksimum (dimensi) vektor bervariasi bergantung pada model sematan 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 penyematan yang telah Anda pilih.

    2. Klik Run.

    3. Salin dan tempel pernyataan penyisipan berikut untuk membuat ulang sematan vector:

      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 sematan 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 penyematan perintah:

      -- 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)
        );
      
    2. Klik Run.

    3. Salin hasil embeddings.values.

    4. Ganti embedding dalam kueri berikut dengan hasil penyematan yang Anda salin pada langkah sebelumnya.

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

      Kueri SQL baru akan terlihat mirip dengan berikut ini:

      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;
      

      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 0.30935457151661594, memiliki tingkat kesamaan tertinggi dengan kueri asli.

      Untuk mengetahui informasi selengkapnya tentang menafsirkan hubungan antara fungsi vektor dan kesamaan, lihat Memilih di antara fungsi jarak vektor untuk mengukur kesamaan penyematan vektor.

    Pembersihan

    Bagian ini menunjukkan cara menggunakan konsol Google Cloud untuk membersihkan resource Anda. Untuk menghindari biaya tambahan pada 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 konsol Google Cloud , 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 Ringkasan database, klik hapus Hapus database.

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

    Menghapus instance

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

      Buka instance Spanner

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

    3. Klik Hapus instance.

    4. Konfirmasi bahwa Anda ingin menghapus instance dengan memasukkan nama instance, lalu klik Hapus.

    Apa langkah selanjutnya?