AlloyDB'de karma aramayı kullanmaya başlama

1. Giriş

Bu codelab'de, (sıralama güncelleme yöntemi) RUM uzantısını ve ölçeklenebilir en yakın komşu (ScaNN) dizinini kullanarak AlloyDB'de karma arama yapmayı öğreneceksiniz. Bu laboratuvar, AlloyDB AI özelliklerine ayrılmış bir laboratuvar koleksiyonunun parçasıdır. Belgelerdeki AlloyDB AI sayfasında daha fazla bilgi edinebilirsiniz.

Ön koşullar

Google Cloud Console hakkında temel bilgiler
Komut satırı arayüzü ve Google Shell'de temel beceriler

Neler öğreneceksiniz?

AlloyDB kümesi ve birincil örneği dağıtma
Google Compute Engine sanal makinesinden AlloyDB'ye bağlanma
Veritabanı oluşturma ve AlloyDB AI'yı etkinleştirme
Veritabanına veri yükleme
AlloyDB Studio'yu kullanma
Vertex AI ile yerleştirmeler oluşturma
Vektör aramasını hızlandırmak için ScaNN vektör dizini oluşturma
Tam metin araması için RUM uzantısını etkinleştirme ve kullanma
Tam metin araması, vektör araması ve Karşılıklı Sıralama Karışımı (RRF)'nı birleştirerek karma arama gerçekleştirme

Gerekenler

Google Cloud hesabı ve Google Cloud projesi
Chrome gibi bir web tarayıcısı

2. Kurulum ve Gereksinimler

Proje Kurulumu

Google Cloud Console'da oturum açın. Gmail veya Google Workspace hesabınız yoksa hesap oluşturmanız gerekir.

İş veya okul hesabı yerine kişisel hesap kullanıyorsanız.

Google Cloud projesi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Faturalandırmayı etkinleştirme

Faturalandırmayı etkinleştirmek için iki seçeneğiniz vardır. Kişisel faturalandırma hesabınızı kullanabilir veya aşağıdaki adımları uygulayarak kredileri kullanabilirsiniz.

Kişisel faturalandırma hesabı oluşturma

Faturalandırmayı Google Cloud kredilerini kullanarak ayarladıysanız bu adımı atlayabilirsiniz.

Kişisel faturalandırma hesabı oluşturmak için Cloud Console'da faturalandırmayı etkinleştirmek üzere buraya gidin.

Bazı notlar:

Bu laboratuvarı tamamlamak için 3 ABD dolarından daha az tutarda bulut kaynağı kullanmanız gerekir.
Daha fazla ücret ödememek için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
Yeni kullanıcılar 300 ABD doları değerinde ücretsiz deneme sürümünden yararlanabilir.

Cloud Shell'i başlatma

Google Cloud, dizüstü bilgisayarınızdan uzaktan çalıştırılabilir. Ancak bu codelab'de, Cloud'da çalışan bir komut satırı ortamı olan Google Cloud Shell'i kullanacaksınız.

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
```
gcloud auth list
```
Projenizin yapılandırıldığını onaylayın:
```
gcloud config get project
```

Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:

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

Bu sanal makine, ihtiyaç duyacağınız tüm geliştirme araçlarını içerir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud üzerinde çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde güçlenir. Bu codelab'deki tüm çalışmalarınızı tarayıcıda yapabilirsiniz. Herhangi bir şey yüklemeniz gerekmez.

3. Başlamadan önce

API'yi etkinleştirme

Çıkış:

AlloyDB, Compute Engine, ağ hizmetleri ve Vertex AI'ı kullanmak için Google Cloud projenizde ilgili API'leri etkinleştirmeniz gerekir.

API'leri etkinleştirme

Terminaldeki Cloud Shell'de proje kimliğinizin ayarlandığından emin olun:

gcloud config set project [YOUR-PROJECT-ID]

PROJECT_ID ortam değişkenini ayarlayın:

PROJECT_ID=$(gcloud config get-value project)

Gerekli tüm API'leri etkinleştirin:

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

Beklenen çıktı

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.

API'lerle tanışın

AlloyDB API (alloydb.googleapis.com), PostgreSQL için AlloyDB kümeleri oluşturmanıza, yönetmenize ve ölçeklendirmenize olanak tanır. Talepkar kurumsal işlemsel ve analitik iş yükleri için tasarlanmış, tümüyle yönetilen ve PostgreSQL ile uyumlu bir veritabanı hizmeti sunar.
Compute Engine API (compute.googleapis.com), sanal makineler (VM'ler), kalıcı diskler ve ağ ayarları oluşturup yönetmenize olanak tanır. İş yüklerinizi çalıştırmak ve birçok yönetilen hizmetin temel altyapısını barındırmak için gereken temel Hizmet Olarak Altyapı (IaaS) temelini sağlar.
Cloud Resource Manager API (cloudresourcemanager.googleapis.com), Google Cloud projenizin meta verilerini ve yapılandırmasını programatik olarak yönetmenize olanak tanır. Kaynakları düzenlemenize, Identity and Access Management (IAM) politikalarını yönetmenize ve proje hiyerarşisi genelinde izinleri doğrulamanıza olanak tanır.
Service Networking API (servicenetworking.googleapis.com), sanal özel bulut (VPC) ağınız ile Google'ın yönetilen hizmetleri arasındaki özel bağlantının kurulumunu otomatikleştirmenize olanak tanır. AlloyDB gibi hizmetlerin diğer kaynaklarınızla güvenli bir şekilde iletişim kurabilmesi için özel IP erişimi oluşturmak özellikle gereklidir.
Vertex AI API (aiplatform.googleapis.com), uygulamalarınızın makine öğrenimi modelleri oluşturmasına, dağıtmasına ve ölçeklendirmesine olanak tanır. Üretken yapay zeka modellerine (ör. Gemini) erişim ve özel model eğitimi de dahil olmak üzere Google Cloud'un tüm yapay zeka hizmetleri için birleşik bir arayüz sağlar.

İsteğe bağlı olarak, varsayılan bölgenizi Vertex AI yerleştirme modellerini kullanacak şekilde yapılandırabilirsiniz. Vertex AI'ın kullanılabildiği yerler hakkında daha fazla bilgi edinin. Örnekte us-central1 bölgesi kullanılmaktadır.

gcloud config set compute/region us-central1

4. AlloyDB'yi dağıtma

AlloyDB kümesi oluşturmadan önce, gelecekteki AlloyDB örneği tarafından kullanılacak VPC'mizde kullanılabilir bir özel IP aralığına ihtiyacımız vardır. Bu kimlik yoksa oluşturmamız, dahili Google hizmetleri tarafından kullanılacak şekilde atamamız ve ardından küme ile örneği oluşturabilmemiz gerekir.

Özel IP aralığı oluşturma

AlloyDB için VPC'mizde özel hizmet erişimi yapılandırması yapmamız gerekiyor. Buradaki varsayım, projede "varsayılan" VPC ağının olduğu ve tüm işlemler için bu ağın kullanılacağıdır.

Özel IP aralığını oluşturun:

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

Ayrılan IP aralığını kullanarak özel bağlantı oluşturma:

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

Beklenen konsol çıkışı:

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)$

AlloyDB kümesi oluşturma

Bu bölümde, us-central1 bölgesinde bir AlloyDB kümesi oluşturuyoruz.

Postgres kullanıcısı için şifre tanımlayın. Kendi şifrenizi tanımlayabilir veya rastgele bir işlev kullanarak şifre oluşturabilirsiniz.

export PGPASSWORD=`openssl rand -hex 12`

Beklenen konsol çıkışı:

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

PostgreSQL şifresini ileride kullanmak üzere not edin.

echo $PGPASSWORD

Gelecekte postgres kullanıcısı olarak örneğe bağlanmak için bu şifreye ihtiyacınız olacak. Daha sonra kullanabilmek için bu kodu bir yere yazmanızı veya kopyalamanızı öneririz.

Beklenen konsol çıkışı:

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

AlloyDB kümesi oluşturma

Bölgeyi ve AlloyDB küme adını tanımlayın. us-central1 bölgesini ve küme adı olarak alloydb-hybrid-search'ü kullanacağız:

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

Kümeyi oluşturmak için komutu çalıştırın:

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

Beklenen konsol çıkışı:

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.

Aynı Cloud Shell oturumunda kümemiz için bir AlloyDB birincil örneği oluşturun. Bağlantınız kesilirse bölge ve küme adı ortam değişkenlerini tekrar tanımlamanız gerekir.

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

Beklenen konsol çıkışı:

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. AlloyDB'ye bağlanma

AlloyDB yalnızca özel bağlantı kullanılarak dağıtıldığından veritabanıyla çalışmak için PostgreSQL istemcisinin yüklü olduğu bir sanal makineye ihtiyacımız var.

GCE sanal makinesi dağıtma

AlloyDB kümesiyle aynı bölgede ve VPC'de bir GCE VM oluşturun.

Cloud Shell'de şunu çalıştırın:

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

Beklenen konsol çıkışı:

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

Postgres istemcisini yükleme

Dağıtılan sanal makineye PostgreSQL istemci yazılımını yükleyin.

Sanal makineye bağlanın:

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

Beklenen konsol çıkışı:

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:~$

Sanal makinenin içinde aşağıdaki komutu çalıştırarak yazılımı yükleyin:

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

Beklenen konsol çıkışı:

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) ...

Örneğe bağlanma

psql kullanarak sanal makineden birincil örneğe bağlanın.

instance-1 sanal makinenize açılan SSH oturumunun bulunduğu Cloud Shell sekmesinde.

GCE sanal makinesinden AlloyDB'ye bağlanmak için belirtilen AlloyDB şifresi (PGPASSWORD) değerini ve AlloyDB küme kimliğini kullanın:

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"

Beklenen konsol çıkışı:

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

psql oturumunu kapatın:

exit

6. Veritabanını Hazırlama

Veritabanı oluşturmamız, Vertex AI entegrasyonunu etkinleştirmemiz, veritabanı nesneleri oluşturmamız ve verileri içe aktarmamız gerekiyor.

AlloyDB'ye Gerekli İzinleri Verme

AlloyDB hizmet aracısına Vertex AI izinleri ekleyin.

En üstteki "+" işaretini kullanarak başka bir Cloud Shell sekmesi açın.

Yeni Cloud Shell sekmesinde şunu çalıştırın:

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"

Beklenen konsol çıkışı:

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

Sekmede "exit" komutunu çalıştırarak sekmeyi kapatın:

exit

Veritabanı Oluşturma

quickstart adlı bir veritabanı oluşturun.

GCE sanal makine oturumunda şunu çalıştırın:

Veritabanı oluşturma:

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

Beklenen konsol çıkışı:

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

Vertex AI entegrasyonunu etkinleştirme

Vertex AI entegrasyonunu ve veritabanındaki pgvector uzantılarını etkinleştirin.

GCE sanal makinesinde şunu çalıştırın:

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"

Beklenen konsol çıkışı:

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:~$

Verileri İçe Aktarma

Hazırlanan verileri indirip yeni veritabanına aktarın.

GCE sanal makinesinde şunu çalıştırın:

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"

Beklenen konsol çıkışı:

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. Vektör yerleştirmeleri oluşturma

Verileri içe aktardıktan sonra aşağıdaki tabloları elde ederiz: cymbal_products (ürünlerle ilgili bilgileri saklar), cymbal_inventory (her mağazadaki ürün stokunu izler) ve cymbal_stores (mağazaların listesidir). Ürünlerimizde anlamsal arama yapmak için initialize_embeddings işleviyle ürün açıklamalarımızın vektör yerleştirmelerini oluşturmamız gerekir. Ürün açıklamalarımıza göre vektör verilerini hesaplamak ve tabloya eklemek için Vertex AI entegrasyonunu kullanacağız. Kullanılan teknoloji hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.

Entegrasyonu kullanmak için AlloyDB örneği IP'sini ve postgres şifresini kullanarak sanal makinenizden psql ile veritabanına bağlanın:

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

google_ml_integration uzantısının sürümünü doğrulayın.

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

Sürüm 1.5.2 veya daha yeni olmalıdır. Çıkış örneğini aşağıda görebilirsiniz:

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

Varsayılan sürüm 1.5.2 veya daha yeni olmalıdır. Ancak örneğinizde daha eski bir sürüm gösteriliyorsa muhtemelen güncellenmesi gerekir. Örnek için bakımın devre dışı bırakılıp bırakılmadığını kontrol edin.

Verimliliği artırmak için toplu yerleştirme oluşturma özelliğini kullanacağız. Farklı yerleştirme oluşturma seçenekleri ve teknikleri hakkında daha fazla bilgiyi rehberde bulabilirsiniz. Toplu yerleştirme özelliğini kullanmak için goole_ml_integration.enable_faster_embedding_generation

show google_ml_integration.enable_faster_embedding_generation;

İşaret doğru konumdaysa beklenen çıkış şu şekilde görünür:

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

Ancak "kapalı" gösteriyorsa örneği güncellememiz gerekir. Bu işlemi, dokümanlarda açıklandığı gibi web konsolunu veya gcloud komutunu kullanarak yapabilirsiniz. Burada, gcloud komutu kullanılarak bu işlemin nasıl yapılacağı gösterilmektedir:

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

Bu işlem birkaç dakika sürebilir ancak sonunda işaret değeri "açık" olarak değiştirilir. Ardından, sonraki adımlara geçebilirsiniz.

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

Veritabanına bağlı psql oturumunda, yerleştirmeleri depolamak için yeni bir sütun oluşturun cymbal_products

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

Beklenen konsol çıkışı:

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

Son olarak, işlev çağrısına incremental_refresh_mode bağımsız değişkeni eklenerek sütun değerleri değiştirildiğinde yerleştirmelerin de yenilenmesini istiyoruz. Bu durum, veritabanımıza ek yük getirir ancak yerleştirmelerin içerikle otomatik olarak senkronize kalmasını sağlamak için bu ek yükü kabul ederiz. Yerleştirmeleri manuel olarak güncellemek isterseniz talimatları belgelerde bulabilirsiniz.

Şimdi hepsini bir araya getirip yerleştirmeler oluşturmak için initialize_embeddings işlevini kullanıyoruz ve toplu ipucu olarak 50 değerini iletiyor, incremental_refresh_mode değerini transactional olarak ayarlıyoruz.batch_size

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

Şimdi de product_embedding sütunu için NULL değeriyle tabloya yeni bir satır ekleyelim.

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

Şimdi yeni eklediğimiz satırı sorguladığımızda product_embedding sütununun otomatik olarak güncellendiğini görüyoruz.

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

Çıkış şu şekilde görünmelidir:

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. Vektör dizini oluşturma

Vektör arama performansını artırmak için ScaNN dizini ekleyeceğiz.

ScaNN dizini oluşturma

SCANN dizinini oluşturmak için bir uzantı daha etkinleştirmemiz gerekiyor. alloydb_scann uzantısı, Google'ın ScaNN algoritmasını kullanarak ANN türü vektör diziniyle çalışmak için bir arayüz sağlar.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Beklenen çıktı:

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

Dizin, MANUAL (MANUEL) veya AUTO (OTOMATİK) modda oluşturulabilir. MANUEL modu varsayılan olarak etkindir. Bu modda, diğer indekslerde olduğu gibi bir indeks oluşturup bunu koruyabilirsiniz. Ancak AUTO modunu etkinleştirirseniz sizden herhangi bir bakım gerektirmeyen dizin oluşturabilirsiniz. Tüm seçenekler hakkında ayrıntılı bilgiyi dokümanlarda bulabilirsiniz. Bizim durumumuzda, dizini AUTO modunda oluşturmak için yeterli satır yok. Bu nedenle, dizini MANUAL olarak oluşturup ayarlama parametrelerini ekleyeceğiz. Dizin parametrelerini ayarlama hakkında bilgiyi belgelerde bulabilirsiniz.

Ayarlama parametrelerini değiştirebilmek için scann.enable_preview_features işaretini etkinleştirmemiz gerekir. Cloud Shell'de

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

Bu işlem birkaç dakika sürebilir ancak sonunda işaret değeri "açık" olarak değiştirilir. İşaret ayarlandıktan sonra sanal makinedeki psql oturumumuza geri dönebilir ve ayarlama parametreleriyle dizini oluşturabiliriz.

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

Beklenen çıktı:

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

Dizin kullanımını inceleme

Artık vektör arama sorgusunu EXPLAIN (AÇIKLA) modunda çalıştırabilir ve dizinin kullanılıp kullanılmadığını doğrulayabiliriz.

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;

Beklenen çıktı (netlik için sansürlenmiştir):

...
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)
...

Çıktıdan, sorgunun "cymbal_products_embeddings_scann üzerinde cymbal_products kullanılarak yapılan dizin taraması" kullandığı açıkça görülüyor.

9. Tam metin arama dizini

AlloyDB, tam metin arama için yerel PostgreSQL'in desteklediği tüm dizin türlerini destekler. Dizin seçimi; arama hızı, dizin oluşturma süresi, güncelleme hızı ve gerekli özel arama işlevleri (ör. ifade arama veya alaka düzeyi sıralaması) arasındaki dengeye bağlıdır.

Örneğimizde, daha iyi performans gösteren tam metin arama işlemleri için RUM uzantısını kullanacağız. RUM, konumsal bilgileri doğrudan dizinde depolayarak standart GIN dizinlerini iyileştirir. Böylece, tablo verilerine erişmeden daha hızlı ifade aramaları ve alaka düzeyi sıralaması yapabilirsiniz.

AlloyDB Studio'yu kullanabilir veya psql istemcisini kullanarak rum uzantısını etkinleştirmeye devam edebilirsiniz.

RUM dizini oluşturma

CREATE EXTENSION IF NOT EXISTS rum;

cymbal_products tablosundaki ürün açıklamalarında arama yapmak için ürün açıklamasını tsvector olarak depolayan bir sütun oluşturmamız gerekir. Bu sütun, işlenen metni otomatik olarak depolar ve sorgu performansını artırır.

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

Artık product_search_vector sütunu için yeni bir RUM dizini oluşturabiliriz.

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

Tabloyu dizini kullanarak sorgulamak için "kiraz ağacı" eşleşmelerini arayan aşağıdaki sorguyu çalıştırın. <=> operatörü, doküman ile sorgu arasındaki alaka düzeyini veya mesafeyi doğrudan dizinden hesaplar.

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. Karma arama gerçekleştirme

google_vector_utils.hybrid_search() işlevi, vektör araması ve tam metin araması gibi birden fazla arama türünden sonuçları birleştirmenize olanak tanır. Bu işlev, Karşılıklı Sıralama Karışımı (RRF) algoritmasını kullanarak her arama bileşeninden elde edilen sıralanmış sonuçları tek bir birleştirilmiş listede birleştirir. Bu yaklaşım, tek bir arama türüne kıyasla daha alakalı sonuçlar sağlar.

hybrid_search() işlevi, tek bir SQL sorgusunu dinamik olarak oluşturur ve yürütür. Tanımladığınız her arama bileşeni için bir Ortak Tablo İfadesi (CTE) oluşturur. Ardından işlev, tüm CTE'lerden gelen sonuçları birleştirir ve birleşik, sıralanmış bir liste oluşturmak için her belgeye yönelik nihai bir RRF puanı hesaplar.

İşlevi kullanmak için birincil örnekte enable_preview_ai_functions seçeneğini etkinleştirmemiz gerekir. Cloud Shell'de aşağıdaki komutu çalıştırın:

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

Aşağıdaki sorgu, önceki vektör arama sorumuzu tam metin arama sorumuzla birleştirir. Bu, çok basit bir karma arama sorgusudur. Vektör arama bileşeninde "bir evden daha uzun büyüyen ağaçlar" ve FTS bileşeninde "Kaliforniya" gibi daha karmaşık bir sorgu deneyebilirsiniz.

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;

Beklenen çıktı

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

Sonuçlarda, id belirtilen key_column, score ise RRF tarafından hesaplanan nihai değerdir. Karşılıklı Sıra Füzyonu (RRF), her belgeye bir puan atayarak birden fazla sıralanmış arama sonucu listesini tek bir sıralanmış listede birleştiren, sıralamaya dayalı bir algoritmadır. Bu puan, RRF'nin katkıda bulunan tüm listelerdeki karşılıklı sıralamasına dayanır. Daha yüksek sıralamaya sahip dokümanlar daha fazla katkı sağlar. Parametrede include_json_output => true kullanıldığında, her bileşenin puan hesaplamasının dökümünü içeren bir detail_json sütunu döndürülür.

Tam metin araması, belirli terimleri veya tam eşleşmeleri bulmada en iyisidir. Vektör araması ise kelimeler eşleşmese bile eş anlamlıları ve amacı bulmada daha iyidir. Bu iki yöntemi birleştiren karma arama, kullanıcılara hem kelime anlamı olarak doğru hem de anlamsal olarak alakalı olan sağlam bir sonuç grubu sunar.

11. Ortamı temizleme

Laboratuvarı tamamladığınızda AlloyDB örneklerini ve kümeyi yok edin.

AlloyDB kümesini ve tüm örnekleri silme

AlloyDB'nin deneme sürümünü kullandıysanız Deneme kümesini kullanarak diğer laboratuvarları ve kaynakları test etmeyi planlıyorsanız deneme kümesini silmeyin. Aynı projede başka bir deneme kümesi oluşturamazsınız.

Küme, zorlama seçeneğiyle yok edilir. Bu seçenek, kümeye ait tüm örnekleri de siler.

Bağlantınız kesildiyse ve önceki tüm ayarlar kaybolduysa Cloud Shell'de proje ve ortam değişkenlerini tanımlayın:

gcloud config set project <your project id>

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

Kümeyi silme:

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

Beklenen konsol çıkışı:

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.

AlloyDB Yedeklemelerini Silme

Kümenin tüm AlloyDB yedeklerini silin:

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

Beklenen konsol çıkışı:

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.

Artık sanal makinemizi kaldırabiliriz.

GCE sanal makinesini silme

Cloud Shell'de şunu çalıştırın:

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

Beklenen konsol çıkışı:

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. Tebrikler

Codelab'i tamamladığınız için tebrik ederiz.

İşlediğimiz konular

AlloyDB kümesi ve birincil örneği dağıtma
Google Compute Engine sanal makinesinden AlloyDB'ye bağlanma
Veritabanı oluşturma ve AlloyDB AI'yı etkinleştirme
Veritabanına veri yükleme
AlloyDB Studio'yu kullanma
Vertex AI ile yerleştirmeler oluşturma
Vektör aramasını hızlandırmak için ScaNN vektör dizini oluşturma
Tam metin araması için RUM uzantısını etkinleştirme ve kullanma
Tam metin araması, vektör araması ve Karşılıklı Sıralama Karışımı (RRF)'nı birleştirerek karma arama gerçekleştirme