Mulai menggunakan Penelusuran Hybrid di AlloyDB

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara melakukan penelusuran campuran di AlloyDB menggunakan ekstensi RUM (Ranking Update Method) dan indeks Scalable Nearest Neighbor (ScaNN). Lab ini adalah bagian dari koleksi lab yang dikhususkan untuk fitur AI AlloyDB. Anda dapat membaca selengkapnya di halaman AlloyDB AI dalam dokumentasi.

Prasyarat

Pemahaman dasar tentang Konsol Google Cloud
Keterampilan dasar dalam antarmuka command line dan Google Shell

Yang akan Anda pelajari

Cara men-deploy cluster dan instance utama AlloyDB
Cara terhubung ke AlloyDB dari VM Google Compute Engine
Cara membuat database dan mengaktifkan AlloyDB AI
Cara memuat data ke database
Cara menggunakan AlloyDB Studio
Membuat embedding dengan Vertex AI
Cara membuat indeks vektor ScaNN untuk meningkatkan penelusuran vektor
Cara mengaktifkan dan menggunakan ekstensi RUM untuk penelusuran teks lengkap
Lakukan penelusuran campuran dengan menggabungkan penelusuran teks lengkap, penelusuran vektor, dan Reciprocal Rank Fusion (RRF)

Yang Anda butuhkan

Akun Google Cloud dan Project Google Cloud
Browser web seperti Chrome

2. Penyiapan dan Persyaratan

Penyiapan Project

Gunakan akun pribadi, bukan akun kantor atau sekolah.

Buat Project Google Cloud

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Aktifkan Penagihan

Untuk mengaktifkan penagihan, Anda memiliki dua opsi. Anda dapat menggunakan akun penagihan pribadi atau menukarkan kredit dengan langkah-langkah berikut.

Menyiapkan akun penagihan pribadi

Jika menyiapkan penagihan menggunakan kredit Google Cloud, Anda dapat melewati langkah ini.

Untuk menyiapkan akun penagihan pribadi, buka di sini untuk mengaktifkan penagihan di Cloud Console.

Beberapa Catatan:

Menyelesaikan lab ini akan dikenai biaya kurang dari $3 USD untuk resource Cloud.
Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
Pengguna baru memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD.

Mulai Cloud Shell

Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
```
gcloud auth list
```
Pastikan project Anda dikonfigurasi:
```
gcloud config get project
```

Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.

3. Sebelum memulai

Aktifkan API

Output:

Untuk menggunakan AlloyDB, Compute Engine, Layanan jaringan, dan Vertex AI, Anda harus mengaktifkan API masing-masing di project Google Cloud Anda.

Mengaktifkan API

Di dalam Cloud Shell di terminal, pastikan project ID Anda sudah disiapkan:

gcloud config set project [YOUR-PROJECT-ID]

Tetapkan variabel lingkungan PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

Aktifkan semua API yang diperlukan:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com

Output yang diharapkan

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

Memperkenalkan API

AlloyDB API (alloydb.googleapis.com) memungkinkan Anda membuat, mengelola, dan menskalakan cluster AlloyDB untuk PostgreSQL. Layanan ini menyediakan layanan database yang kompatibel dengan PostgreSQL dan terkelola sepenuhnya, yang dirancang untuk workload transaksional dan analitis perusahaan yang berat.
Compute Engine API (compute.googleapis.com) memungkinkan Anda membuat dan mengelola mesin virtual (VM), persistent disk, dan setelan jaringan. Layanan ini menyediakan fondasi Infrastructure-as-a-Service (IaaS) inti yang diperlukan untuk menjalankan beban kerja Anda dan menghosting infrastruktur yang mendasarinya untuk banyak layanan terkelola.
Cloud Resource Manager API (cloudresourcemanager.googleapis.com) memungkinkan Anda mengelola metadata dan konfigurasi project Google Cloud secara terprogram. Dengan demikian, Anda dapat mengatur resource, menangani kebijakan Identity and Access Management (IAM), dan memvalidasi izin di seluruh hierarki project.
Service Networking API (servicenetworking.googleapis.com) memungkinkan Anda mengotomatiskan penyiapan konektivitas pribadi antara jaringan Virtual Private Cloud (VPC) dan layanan terkelola Google. Hal ini secara khusus diperlukan untuk membuat akses IP pribadi bagi layanan seperti AlloyDB agar dapat berkomunikasi dengan aman dengan resource Anda yang lain.
Vertex AI API (aiplatform.googleapis.com) memungkinkan aplikasi Anda membangun, men-deploy, dan menskalakan model machine learning. Vertex AI menyediakan antarmuka terpadu untuk semua layanan AI Google Cloud, termasuk akses ke model AI Generatif (seperti Gemini) dan pelatihan model kustom.

Sebagai opsi, Anda dapat mengonfigurasi region default untuk menggunakan model penyematan Vertex AI. Baca selengkapnya tentang lokasi yang tersedia untuk Vertex AI. Dalam contoh ini, kita menggunakan region us-central1.

gcloud config set compute/region us-central1

4. Men-deploy AlloyDB

Sebelum membuat cluster AlloyDB, kita memerlukan rentang IP pribadi yang tersedia di VPC untuk digunakan oleh instance AlloyDB mendatang. Jika belum ada, kita perlu membuatnya, menetapkannya untuk digunakan oleh layanan Google internal, dan setelah itu kita akan dapat membuat cluster dan instance.

Buat rentang IP pribadi

Kita perlu mengonfigurasi konfigurasi Akses Layanan Pribadi di VPC untuk AlloyDB. Asumsinya di sini adalah kita memiliki jaringan VPC "default" dalam project dan jaringan tersebut akan digunakan untuk semua tindakan.

Buat rentang IP pribadi:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

Buat koneksi pribadi menggunakan rentang IP yang dialokasikan:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

Buat Cluster AlloyDB

Di bagian ini, kita akan membuat cluster AlloyDB di region us-central1.

Tentukan sandi untuk pengguna postgres. Anda dapat menentukan sandi Anda sendiri atau menggunakan fungsi acak untuk membuatnya

export PGPASSWORD=`openssl rand -hex 12`

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

Catat sandi PostgreSQL untuk penggunaan berikutnya.

echo $PGPASSWORD

Anda akan memerlukan sandi tersebut pada masa mendatang untuk terhubung ke instance sebagai pengguna postgres. Sebaiknya tulis atau salin di suatu tempat agar dapat digunakan nanti.

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

Buat Cluster AlloyDB

Tentukan region dan nama cluster AlloyDB. Kita akan menggunakan region us-central1 dan alloydb-hybrid-search sebagai nama cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search

Jalankan perintah untuk membuat cluster:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

Output konsol yang diharapkan:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

Buat instance utama AlloyDB untuk cluster di sesi cloud shell yang sama. Jika koneksi terputus, Anda harus menentukan variabel lingkungan nama cluster dan region lagi.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Output konsol yang diharapkan:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

5. Membuat koneksi ke AlloyDB

AlloyDB di-deploy menggunakan koneksi khusus pribadi, jadi kita memerlukan VM dengan klien PostgreSQL yang diinstal untuk bekerja dengan database.

Deploy VM GCE

Buat VM GCE di region dan VPC yang sama dengan cluster AlloyDB.

Di Cloud Shell, jalankan:

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Output konsol yang diharapkan:

student@cloudshell:~ (alloydb-hybrid-search)$ export ZONE=us-central1-a
student@cloudshell:~ (talloydb-hybrid-search)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.71.192.233
STATUS: RUNNING

Instal Klien Postgres

Instal software klien PostgreSQL pada VM yang di-deploy

Hubungkan ke VM:

gcloud compute ssh instance-1 --zone=us-central1-a

Output konsol yang diharapkan:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1.us-central1-a.c.gleb-test-short-001-418811.internal 6.1.0-18-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.76-1 (2024-02-01) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Instal software yang menjalankan perintah dalam VM:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Output konsol yang diharapkan:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable InRelease [5146 B]
Get:2 https://packages.cloud.google.com/apt cloud-sdk-bullseye InRelease [6406 B]   
Hit:3 https://deb.debian.org/debian bullseye InRelease  
Get:4 https://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
Get:5 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable/main amd64 Packages [1930 B]
Get:6 https://deb.debian.org/debian bullseye-updates InRelease [44.1 kB]
Get:7 https://deb.debian.org/debian bullseye-backports InRelease [49.0 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/13/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (13+225) ...
Processing triggers for man-db (2.9.4-2) ...
Processing triggers for libc-bin (2.31-13+deb11u7) ...

Hubungkan ke Instance

Hubungkan ke instance utama dari VM menggunakan psql.

Di tab Cloud Shell yang sama dengan sesi SSH yang dibuka ke VM instance-1 Anda.

Gunakan nilai sandi AlloyDB (PGPASSWORD) yang dicatat dan ID cluster AlloyDB untuk terhubung ke AlloyDB dari VM GCE:

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Output konsol yang diharapkan:

student@instance-1:~$ export PGPASSWORD=CQhOi5OygD4ps6ty
student@instance-1:~$ ADBCLUSTER=alloydb-aip-01
student@instance-1:~$ REGION=us-central1
student@instance-1:~$ INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
gleb@instance-1:~$ psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (15.6 (Debian 15.6-0+deb12u1), server 15.5)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

Tutup sesi psql:

exit

6. Menyiapkan Database

Kita perlu membuat database, mengaktifkan integrasi Vertex AI, membuat objek database, dan mengimpor data.

Memberikan Izin yang Diperlukan ke AlloyDB

Tambahkan izin Vertex AI ke agen layanan AlloyDB.

Buka tab Cloud Shell lain menggunakan tanda "+" di bagian atas.

Di tab Cloud Shell baru, jalankan:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

Tutup tab dengan menjalankan perintah "exit" di tab:

exit

Buat Database

Buat database bernama quickstart.

Dalam sesi VM GCE, jalankan:

Buat database:

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"

Output konsol yang diharapkan:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"
CREATE DATABASE
student@instance-1:~$

Mengaktifkan Integrasi Vertex AI

Aktifkan integrasi Vertex AI dan ekstensi pgvector di database.

Di VM GCE, jalankan:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"

Output konsol yang diharapkan:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"
CREATE EXTENSION
CREATE EXTENSION
student@instance-1:~$

Impor Data

Download data yang telah disiapkan dan impor ke database baru.

Di VM GCE, jalankan:

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"

Output konsol yang diharapkan:

student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
SET
SET
SET
SET
SET
 set_config 
------------
 
(1 row)
SET
SET
SET
SET
SET
SET
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE SEQUENCE
ALTER TABLE
ALTER SEQUENCE
ALTER TABLE
ALTER TABLE
ALTER TABLE
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
COPY 941
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
COPY 263861
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"
COPY 4654
student@instance-1:~$

7. Membuat Embedding Vektor

Setelah mengimpor data, kita memiliki tabel berikut: cymbal_products yang menyimpan informasi tentang produk, cymbal_inventory yang melacak stok item di setiap toko, dan cymbal_stores yang merupakan daftar toko. Untuk melakukan penelusuran semantik atas produk, kita perlu membuat embedding vektor dari deskripsi produk dengan fungsi initialize_embeddings. Kita akan menggunakan integrasi Vertex AI untuk menghitung data vektor berdasarkan deskripsi produk dan menambahkannya ke tabel. Anda dapat membaca lebih lanjut teknologi yang digunakan dalam dokumentasi.

Untuk menggunakan integrasi, hubungkan ke database menggunakan psql dari VM Anda menggunakan IP instance AlloyDB dan sandi postgres:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Verifikasi versi ekstensi google_ml_integration.

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

Versinya harus 1.5.2 atau yang lebih tinggi. Berikut adalah contoh output-nya:

quickstart_db=> SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
 extversion 
------------
 1.5.2
(1 row)

Versi default harus 1.5.2 atau yang lebih tinggi, tetapi jika instance Anda menampilkan versi yang lebih lama, instance tersebut mungkin perlu diupdate. Periksa apakah pemeliharaan dinonaktifkan untuk instance.

Kami akan menggunakan pembuatan penyematan batch untuk meningkatkan efisiensi. Anda dapat membaca lebih lanjut berbagai opsi dan teknik pembuatan penyematan dalam panduan. Untuk menggunakan penyematan batch, kita harus mengaktifkan goole_ml_integration.enable_faster_embedding_generation

show google_ml_integration.enable_faster_embedding_generation;

Jika tanda berada di posisi yang benar, output yang diharapkan akan terlihat seperti ini:

quickstart_db=> show google_ml_integration.enable_faster_embedding_generation;                          
 google_ml_integration.enable_faster_embedding_generation 
----------------------------------------------------------
 on
(1 row)

Namun, jika menunjukkan "nonaktif", kita perlu mengupdate instance. Anda dapat melakukannya menggunakan konsol web atau perintah gcloud seperti yang dijelaskan dalam dokumentasi. Di sini saya menunjukkan cara melakukannya menggunakan perintah gcloud:

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Mungkin perlu waktu beberapa menit, tetapi pada akhirnya nilai tanda akan diubah menjadi "aktif". Setelah itu, Anda dapat melanjutkan ke langkah berikutnya.

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Dalam sesi psql yang terhubung ke database, buat kolom baru untuk menyimpan penyematan di cymbal_products

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

Output konsol yang diharapkan:

quickstart_db=> ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
ALTER TABLE
quickstart_db=>

Terakhir, kita juga ingin penyematan diperbarui saat nilai kolom diubah dengan menyertakan argumen incremental_refresh_mode dalam panggilan fungsi. Hal ini menimbulkan overhead pada database kami, tetapi ini adalah kompromi yang kami lakukan untuk menyinkronkan penyematan dengan konten secara otomatis. Jika ingin memperbarui penyematan secara manual, Anda dapat menemukan petunjuknya di dokumentasi.

Sekarang, untuk menggabungkan semuanya dan membuat embedding, kita menggunakan fungsi initialize_embeddings dan meneruskan batch_size sebesar 50 sebagai petunjuk batch dan menetapkan incremental_refresh_mode ke transactional

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'product_embedding',
    batch_size => 50,
    incremental_refresh_mode => 'transactional'
);

Sekarang, jika kita menyisipkan baris baru ke tabel dengan nilai NULL untuk kolom product_embedding

INSERT INTO "cymbal_products" ("uniq_id", "crawl_timestamp", "product_url", "product_name", "product_description", "list_price", "sale_price", "brand", "item_number", "gtin", "package_size", "category", "postal_code", "available", "product_embedding") VALUES ('fd604542e04b470f9e6348e640cff794', NOW(), 'https://example.com/new_product', 'New Cymbal Product', 'This is a new cymbal product description.', 199.99, 149.99, 'Example Brand', 'EB123', '1234567890', 'Single', 'Cymbals', '12345', TRUE, NULL);

Sekarang, saat kita membuat kueri baris yang baru saja kita masukkan, kita akan melihat bahwa kolom product_embedding diperbarui secara otomatis.

SELECT uniq_id, (product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';

Outputnya akan terlihat seperti berikut ini:

quickstart_db=> SELECT uniq_id,(product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';
             uniq_id              |                      product_embedding                       
----------------------------------+---------------------------------------------------------------
 fd604542e04b470f9e6348e640cff794 | {0.015003494,-0.005349732,-0.059790313,-0.0087091,-0.0271452}
(1 row)

Time: 3.295 ms

8. Membuat indeks vektor

Untuk meningkatkan performa penelusuran vektor, kita akan menambahkan indeks ScaNN.

Buat indeks ScaNN

Untuk membuat indeks SCANN, kita perlu mengaktifkan satu ekstensi lagi. Ekstensi alloydb_scann menyediakan antarmuka untuk bekerja dengan indeks vektor jenis ANN menggunakan algoritma ScaNN Google.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Output yang diharapkan:

quickstart_db=> CREATE EXTENSION IF NOT EXISTS alloydb_scann;
CREATE EXTENSION
Time: 27.468 ms
quickstart_db=>

Indeks dapat dibuat dalam mode MANUAL atau AUTO. Mode MANUAL diaktifkan secara default dan Anda dapat membuat indeks serta mengelolanya seperti indeks lainnya. Namun, jika Anda mengaktifkan mode OTOMATIS, Anda dapat membuat indeks yang tidak memerlukan pemeliharaan apa pun dari pihak Anda. Anda dapat membaca semua opsi secara mendetail dalam dokumentasi. Dalam kasus ini, kita tidak memiliki cukup baris untuk membuat indeks dalam mode AUTO - jadi kita akan membuatnya sebagai MANUAL dan menyertakan parameter penyesuaian. Anda dapat membaca tentang menyetel parameter indeks di dokumentasi.

Kita harus mengaktifkan tanda scann.enable_preview_features agar dapat mengubah parameter penyetelan. Di cloudshell

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags scann.enable_preview_features=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Mungkin perlu waktu beberapa menit, tetapi pada akhirnya nilai tanda akan diubah menjadi "aktif". Setelah tanda ditetapkan, kita dapat kembali ke sesi psql di VM dan membuat indeks dengan parameter penyesuaian.

CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (mode='MANUAL', num_leaves=31, max_num_levels = 2);

Output yang diharapkan:

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (num_leaves=31, max_num_levels = 2);
CREATE INDEX
quickstart_db=>

Memeriksa penggunaan indeks

Sekarang kita dapat menjalankan kueri penelusuran vektor dalam mode EXPLAIN dan memverifikasi apakah indeks sedang digunakan.

EXPLAIN (analyze) 
WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.product_embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

Output yang diharapkan (disamarkan agar lebih jelas):

...
Aggregate (cost=16.59..16.60 rows=1 width=32) (actual time=2.875..2.877 rows=1 loops=1)
-> Subquery Scan on trees (cost=8.42..16.59 rows=1 width=142) (actual time=2.860..2.862 rows=1 loops=1)
-> Limit (cost=8.42..16.58 rows=1 width=158) (actual time=2.855..2.856 rows=1 loops=1)
-> Nested Loop (cost=8.42..6489.19 rows=794 width=158) (actual time=2.854..2.855 rows=1 loops=1)
-> Nested Loop (cost=8.13..6466.99 rows=794 width=938) (actual time=2.742..2.743 rows=1 loops=1)
-> Index Scan using cymbal_products_embeddings_scann on cymbal_products cp (cost=7.71..111.99 rows=876 width=934) (actual time=2.724..2.724 rows=1 loops=1)
Order By: (embedding <=> '[0.008864171,0.03693164,-0.024245683,-0.00355923,0.0055611245,0.015985578,...<redacted>...5685,-0.03914233,-0.018452475,0.00826032,-0.07372604]'::vector)
...

Dari output, kita dapat melihat dengan jelas bahwa kueri menggunakan "Index Scan using cymbal_products_embeddings_scann on cymbal_products".

9. Indeks penelusuran teks lengkap

AlloyDB mendukung semua jenis indeks untuk penelusuran teks lengkap yang didukung PostgreSQL native. Pilihan indeks bergantung pada keseimbangan antara kecepatan penelusuran, waktu pembuatan indeks, kecepatan update, dan fungsi penelusuran spesifik yang diperlukan, seperti penelusuran frasa atau peringkat relevansi.

Dalam contoh ini, kita akan menggunakan ekstensi RUM untuk operasi penelusuran teks lengkap yang lebih berperforma. RUM meningkatkan indeks GIN standar dengan menyimpan informasi posisi langsung di indeks, sehingga Anda dapat melakukan penelusuran frasa dan peringkat relevansi yang lebih cepat tanpa mengakses data tabel.

Anda dapat menggunakan AlloyDB Studio atau terus menggunakan klien psql untuk mengaktifkan ekstensi rum

Buat indeks RUM

CREATE EXTENSION IF NOT EXISTS rum;

Untuk menelusuri deskripsi produk dalam tabel cymbal_products, kita perlu membuat kolom yang menyimpan deskripsi produk sebagai tsvector. Kolom ini secara otomatis menyimpan teks yang diproses dan meningkatkan performa kueri.

ALTER TABLE cymbal_products
ADD COLUMN product_search_vector tsvector
GENERATED ALWAYS AS (to_tsvector('english', product_description)) STORED;

Sekarang kita dapat membuat indeks RUM baru untuk kolom product_search_vector.

CREATE INDEX cymbal_products_rum
ON cymbal_products
USING rum (product_search_vector rum_tsvector_ops);

Untuk membuat kueri tabel menggunakan indeks, jalankan kueri berikut yang menelusuri kecocokan "pohon ceri". Operator <=> menghitung skor relevansi, atau jarak, antara dokumen dan kueri langsung dari indeks.

SELECT product_name, product_description
FROM cymbal_products
WHERE product_search_vector @@ to_tsquery('english', 'cherry <-> tree')
ORDER BY product_search_vector <=> to_tsquery('english', 'cherry <-> tree');

10. Melakukan penelusuran campuran

Fungsi google_vector_utils.hybrid_search() memungkinkan Anda menggabungkan hasil dari beberapa jenis penelusuran, seperti penelusuran vektor dan penelusuran teks lengkap. Fungsi ini menggabungkan hasil yang diberi peringkat dari setiap komponen penelusuran ke dalam satu daftar terpadu menggunakan algoritma Reciprocal Rank Fusion (RRF). Pendekatan ini memberikan hasil yang lebih relevan daripada hanya satu jenis penelusuran.

Fungsi hybrid_search() secara dinamis membuat dan menjalankan satu kueri SQL. Tindakan ini akan membuat Common Table Expression (CTE) untuk setiap komponen penelusuran yang Anda tentukan. Kemudian, fungsi ini menggabungkan hasil dari semua CTE dan menghitung skor RRF akhir untuk setiap dokumen guna menghasilkan daftar terpadu yang diberi peringkat.

Untuk menggunakan fungsi ini, kita harus mengaktifkan enable_preview_ai_functions di instance utama. Jalankan perintah berikut di cloudshell

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Kueri berikut menggabungkan pertanyaan penelusuran vektor sebelumnya dengan pertanyaan penelusuran teks lengkap. Ini adalah kueri penelusuran campuran yang sangat sederhana; Anda dapat mencoba sesuatu yang lebih kompleks seperti menggunakan "pohon yang tumbuh lebih tinggi dari rumah" di komponen penelusuran vektor dan "California" di komponen FTS.

SELECT score, id, p.product_name
FROM ai.hybrid_search(
  search_inputs => ARRAY[
      '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 5,
        "query_vector": "ai.embedding(''text-embedding-005'', ''cherry'')::vector"
      }'::JSONB,
      '{
        "data_type": "text",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "text_column": "product_search_vector",
        "limit": 5,
        "ranking_function": "<=>",
        "query_text_input": "tree"
      }'::JSONB
  ]
) JOIN cymbal_products p ON id = p.uniq_id;

Output yang diharapkan

"score","id","product_name"
"0.00819672631147241","d536e9e823296a2eba198e52dd23e712","Cherry Tree"
"0.015873015873015872","23e41a71d63d8bbc9bdfa1d118cfddc5","Apple Tree"
"0.00819672631147241","dc789a2f87b142e94e6e325689482af9","Oak Tree"
"0.008064521129029258","f5c70d62ccf3118d73863bf3b17edcbe","Cypress Tree"
"0.008064521129029258","b70c44b1a38c0a2329fa583c9109a80f","Peach Tree"

Dalam hasilnya, Anda akan menemukan id yang merupakan key_column yang ditentukan, score adalah nilai akhir yang dihitung oleh RRF. Reciprocal Rank Fusion (RRF) adalah algoritma berbasis peringkat yang menggabungkan beberapa daftar hasil penelusuran yang diberi peringkat ke dalam satu daftar yang diberi peringkat dengan menetapkan skor ke setiap dokumen. Skor ini didasarkan pada peringkat timbal balik RRF di semua daftar kontribusi, dengan dokumen yang berperingkat lebih tinggi menerima kontribusi yang lebih besar. Dengan menggunakan include_json_output => true dalam parameter, kolom detail_json akan ditampilkan yang berisi perincian penghitungan skor untuk setiap komponen.

Meskipun penelusuran teks lengkap paling baik dalam menemukan istilah tertentu atau kecocokan persis, penelusuran vektor unggul dalam menemukan sinonim dan maksud meskipun kata-katanya tidak cocok. Dengan menggabungkan kedua metode ini, penelusuran hybrid memastikan pengguna mendapatkan serangkaian hasil yang kuat, yang akurat secara harfiah dan relevan secara semantik

11. Membersihkan lingkungan

Hancurkan instance dan cluster AlloyDB setelah Anda selesai mengerjakan lab.

Hapus cluster AlloyDB dan semua instance

Jika Anda telah menggunakan versi uji coba AlloyDB. Jangan hapus cluster uji coba jika Anda berencana menguji lab dan resource lain menggunakan cluster uji coba. Anda tidak akan dapat membuat cluster uji coba lain dalam project yang sama.

Cluster tersebut dihancurkan dengan opsi paksa yang juga akan menghapus semua instance milik cluster tersebut.

Di Cloud Shell, tentukan variabel project dan lingkungan jika koneksi Anda terputus dan semua setelan sebelumnya hilang:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export PROJECT_ID=$(gcloud config get-value project)

Hapus cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

Hapus Cadangan AlloyDB

Hapus semua cadangan AlloyDB untuk cluster:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

Sekarang kita bisa menghancurkan VM

Hapus VM GCE

Di Cloud Shell, jalankan:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

12. Selamat

Selamat, Anda telah menyelesaikan codelab.

Yang telah kita bahas

Cara men-deploy cluster dan instance utama AlloyDB
Cara terhubung ke AlloyDB dari VM Google Compute Engine
Cara membuat database dan mengaktifkan AlloyDB AI
Cara memuat data ke database
Cara menggunakan AlloyDB Studio
Membuat embedding dengan Vertex AI
Cara membuat indeks vektor ScaNN untuk meningkatkan penelusuran vektor
Cara mengaktifkan dan menggunakan ekstensi RUM untuk penelusuran teks lengkap
Lakukan penelusuran campuran dengan menggabungkan penelusuran teks lengkap, penelusuran vektor, dan Reciprocal Rank Fusion (RRF)