شروع کار با جستجوی ترکیبی در AlloyDB و Apache Solr

۱. مقدمه

در این آزمایشگاه کد، نحوه انجام جستجوی ترکیبی در AlloyDB با استفاده از pgvector و یک شاخص نزدیکترین همسایه مقیاس‌پذیر (ScaNN) را خواهید آموخت، که با قابلیت جستجوی متن کامل از Apache Solr از طریق یک بسته‌بندی داده خارجی (FDW) ترکیب شده است. این آزمایشگاه بخشی از یک مجموعه آزمایشگاهی است که به ویژگی‌های هوش مصنوعی AlloyDB اختصاص داده شده است. می‌توانید اطلاعات بیشتر را در صفحه هوش مصنوعی AlloyDB در مستندات مطالعه کنید.

آپاچی سولر (Apache Solr) یک پلتفرم جستجوی سازمانی متن‌باز است که بر پایه آپاچی لوسن (Apache Lucene) ساخته شده و برای قابلیت جستجوی متن کامل سریع، مقیاس‌پذیر و با دسترسی بالا طراحی شده است. ادغام سولر (Solr) با AlloyDB از طریق یک بسته‌بندی داده خارجی (FDW) به کاربران این امکان را می‌دهد که شاخص‌های سولر را مستقیماً از PostgreSQL در کنار جداول پایگاه داده ساختاریافته جستجو کنند. برای کسب اطلاعات بیشتر، به مستندات آپاچی سولر مراجعه کنید.

پیش‌نیازها

  • درک اولیه از گوگل کلود، کنسول
  • مهارت‌های پایه در رابط خط فرمان و گوگل شل

آنچه یاد خواهید گرفت

  • نحوه استقرار کلاستر AlloyDB و نمونه اولیه آن
  • نحوه اتصال به AlloyDB از طریق ماشین مجازی Google Compute Engine
  • نحوه ایجاد پایگاه داده و فعال کردن AlloyDB AI
  • نحوه بارگذاری داده‌ها در پایگاه داده
  • نحوه استفاده از استودیوی AlloyDB
  • ایجاد جاسازی‌ها با Vertex AI
  • چگونه یک شاخص برداری ScaNN ایجاد کنیم تا جستجوی برداری را تقویت کنیم
  • نحوه ایجاد یک بسته‌بندی داده خارجی (FDW) برای Apache Solr
  • با ترکیب جستجوی معنایی در AlloyDB با جستجوی متن کامل در Solr، جستجوی ترکیبی انجام دهید.

آنچه نیاز دارید

  • یک حساب کاربری گوگل کلود و پروژه گوگل کلود
  • یک مرورگر وب مانند کروم

۲. تنظیمات و الزامات

راه‌اندازی پروژه

وارد کنسول ابری گوگل شوید. اگر از قبل حساب جیمیل یا گوگل ورک‌اسپیس ندارید، باید یکی ایجاد کنید .

به جای حساب کاری یا تحصیلی از حساب شخصی استفاده کنید.

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

فعال کردن صورتحساب

برای فعال کردن پرداخت، دو گزینه دارید. می‌توانید از حساب پرداخت شخصی خود استفاده کنید یا می‌توانید با مراحل زیر اعتبار خود را بازخرید کنید.

یک حساب پرداخت شخصی تنظیم کنید

اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کرده‌اید، می‌توانید از این مرحله صرف نظر کنید.

برای تنظیم یک حساب پرداخت شخصی، به اینجا بروید تا پرداخت را در کنسول ابری فعال کنید .

برخی نکات:

  • تکمیل این آزمایشگاه باید کمتر از ۳ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
  • شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
  • کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.

شروع پوسته ابری

اگرچه می‌توان از راه دور و از طریق لپ‌تاپ، گوگل کلود را مدیریت کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا می‌شود، استفاده خواهید کرد.

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
  2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید: 
    gcloud auth list
  3. تأیید کنید که پروژه شما پیکربندی شده است: 
    gcloud config get project
  4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

این ماشین مجازی با تمام ابزارهای توسعه‌ای که نیاز دارید، مجهز شده است. این ماشین مجازی یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه می‌دهد و روی فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود می‌بخشد. تمام کارهای شما در این آزمایشگاه کد را می‌توان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.

۳. قبل از شروع

فعال کردن API

خروجی:

برای استفاده از AlloyDB ، Compute Engine ، Networking services و Vertex AI ، باید API های مربوط به آنها را در پروژه Google Cloud خود فعال کنید.

فعال کردن APIها

داخل Cloud Shell در ترمینال، مطمئن شوید که شناسه پروژه شما تنظیم شده است:

gcloud config set project [YOUR-PROJECT-ID]

متغیر محیطی PROJECT_ID را تنظیم کنید:

PROJECT_ID=$(gcloud config get-value project)

فعال کردن تمام API های لازم:

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

خروجی مورد انتظار

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud config set project alloydb-hybrid-search
[environment: untagged] Read more to tag: g.co/cloud/project-env-tag.
Updated property [core/project].
student@cloudshell:~ (alloydb-hybrid-search)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-32544]
student@cloudshell:~ (alloydb-hybrid-search)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       secretmanager.googleapis.com
Operation "operations/acat.p2-350113473377-5ffc2f22-caa9-4857-b2f4-018657d8bf6e" finished successfully.

معرفی API ها

  • رابط برنامه‌نویسی کاربردی AlloyDB ( alloydb.googleapis.com ) به شما امکان می‌دهد AlloyDB را برای خوشه‌های PostgreSQL ایجاد، مدیریت و مقیاس‌بندی کنید. این رابط، یک سرویس پایگاه داده کاملاً مدیریت‌شده و سازگار با PostgreSQL را ارائه می‌دهد که برای حجم کاری تراکنشی و تحلیلی سازمانی طراحی شده است.
  • رابط برنامه‌نویسی کاربردی موتور محاسبات (compute Engine API ) ( compute.googleapis.com ) به شما امکان می‌دهد ماشین‌های مجازی (VM)، دیسک‌های پایدار و تنظیمات شبکه را ایجاد و مدیریت کنید. این رابط، پایه و اساس زیرساخت به عنوان سرویس (IaaS) مورد نیاز برای اجرای بارهای کاری شما و میزبانی زیرساخت‌های اساسی برای بسیاری از سرویس‌های مدیریت‌شده را فراهم می‌کند.
  • رابط برنامه‌نویسی کاربردی مدیریت منابع ابری ( cloudresourcemanager.googleapis.com ) به شما امکان می‌دهد تا به صورت برنامه‌نویسی، فراداده‌ها و پیکربندی پروژه گوگل کلود خود را مدیریت کنید. این رابط به شما امکان می‌دهد منابع را سازماندهی کنید، سیاست‌های مدیریت هویت و دسترسی (IAM) را مدیریت کنید و مجوزها را در سلسله مراتب پروژه اعتبارسنجی کنید.
  • API شبکه‌سازی سرویس ( servicenetworking.googleapis.com ) به شما امکان می‌دهد تا راه‌اندازی اتصال خصوصی بین شبکه ابر خصوصی مجازی (VPC) و سرویس‌های مدیریت‌شده گوگل را خودکار کنید. این API به‌طور خاص برای ایجاد دسترسی IP خصوصی برای سرویس‌هایی مانند AlloyDB لازم است تا بتوانند به‌طور ایمن با سایر منابع شما ارتباط برقرار کنند.
  • رابط برنامه‌نویسی کاربردی هوش مصنوعی ورتکس ( aiplatform.googleapis.com ) به برنامه‌های شما امکان ساخت، استقرار و مقیاس‌بندی مدل‌های یادگیری ماشین را می‌دهد. این رابط، رابط یکپارچه‌ای را برای همه سرویس‌های هوش مصنوعی گوگل کلود، از جمله دسترسی به مدل‌های هوش مصنوعی مولد (مانند Gemini) و آموزش مدل‌های سفارشی، فراهم می‌کند.
  • رابط برنامه‌نویسی کاربردی مدیریت راز ( secretmanager.googleapis.com ) یک سرویس مدیریت رازها و اطلاعات کاربری است که به شما امکان می‌دهد داده‌های حساس مانند کلیدهای API، نام‌های کاربری، رمزهای عبور، گواهی‌ها و موارد دیگر را ذخیره و مدیریت کنید.

به صورت اختیاری می‌توانید منطقه پیش‌فرض خود را برای استفاده از مدل‌های تعبیه‌شده Vertex AI پیکربندی کنید. درباره مکان‌های موجود برای Vertex AI بیشتر بخوانید. در مثال ما از منطقه us-central1 استفاده می‌کنیم.

gcloud config set compute/region us-central1

۴. استقرار AlloyDB

قبل از ایجاد یک کلاستر AlloyDB، به یک محدوده IP خصوصی در VPC خود نیاز داریم تا توسط نمونه AlloyDB آینده مورد استفاده قرار گیرد. اگر آن را نداریم، باید آن را ایجاد کنیم، آن را به سرویس‌های داخلی گوگل اختصاص دهیم و پس از آن می‌توانیم کلاستر و نمونه را ایجاد کنیم.

ایجاد محدوده IP خصوصی

ما باید پیکربندی دسترسی به سرویس خصوصی (Private Service Access) را در VPC خود برای AlloyDB پیکربندی کنیم. فرض بر این است که ما شبکه VPC "پیش‌فرض" را در پروژه داریم و قرار است برای همه اقدامات از آن استفاده شود.

ایجاد محدوده IP خصوصی:

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

ایجاد اتصال خصوصی با استفاده از محدوده IP اختصاص داده شده: 

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

پس از اتصال، peering را برای خروجی گرفتن از مسیرهای سفارشی به‌روزرسانی کنید: 

gcloud compute networks peerings update servicenetworking-googleapis-com \
    --network=default \
    --export-custom-routes

خروجی مورد انتظار کنسول: 

student@cloudshell:~ (alloydb-hybrid-search)$ 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/alloydb-hybrid-search/global/addresses/psa-range].

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-350113473377-fadad49e-7e14-472a-8888-26951e40a1f7" finished successfully.

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud compute networks peerings update servicenetworking-googleapis-com \
    --network=default \
    --export-custom-routes
Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search/global/networks/default].

ایجاد کلاستر AlloyDB

در این بخش، ما یک کلاستر AlloyDB در ناحیه us-central1 ایجاد می‌کنیم.

برای کاربر postgres رمز عبور تعریف کنید. می‌توانید رمز عبور خودتان را تعریف کنید یا از یک تابع تصادفی برای تولید آن استفاده کنید. 

export PGPASSWORD=`openssl rand -hex 12`

خروجی مورد انتظار کنسول: 

student@cloudshell:~ (alloydb-hybrid-search)$ export PGPASSWORD=`openssl rand -hex 12`

رمز عبور PostgreSQL را برای استفاده‌های بعدی یادداشت کنید. 

echo $PGPASSWORD

در آینده برای اتصال به نمونه به عنوان کاربر postgres به آن رمز عبور نیاز خواهید داشت. پیشنهاد می‌کنم آن را در یک مکان امن (مثلاً در نرم‌افزار مدیریت رمز عبور) کپی کنید.

خروجی مورد انتظار کنسول: 

student@cloudshell:~ (alloydb-hybrid-search)$ echo $PGPASSWORD
<generated password>

ایجاد کلاستر AlloyDB

منطقه و نام خوشه AlloyDB را تعریف کنید. ما قصد داریم از us-central1 region و alloydb-hybrid-search به عنوان نام خوشه استفاده کنیم: 

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

دستور زیر را برای ایجاد خوشه اجرا کنید: 

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

خروجی مورد انتظار کنسول: 

student@cloudshell:~ (alloydb-hybrid-search)$ export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
student@cloudshell:~ (alloydb-hybrid-search)$ gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --database-version=POSTGRES_17
Creating cluster...done.

یک نمونه اصلی AlloyDB برای کلاستر ما در همان جلسه پوسته ابری ایجاد کنید. اگر اتصال شما قطع شد، باید متغیرهای محیطی منطقه و نام کلاستر را دوباره تعریف کنید.

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

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1784244706986-656c2d7f3c8f2-59a9e52a-1e7b1b01
Creating instance...done.

۵. به AlloyDB متصل شوید

AlloyDB با استفاده از یک اتصال خصوصی مستقر می‌شود، بنابراین برای کار با پایگاه داده به یک ماشین مجازی با کلاینت PostgreSQL نصب شده نیاز داریم. همچنین از این ماشین مجازی برای اجرای یک نمونه Apache Solr استفاده خواهیم کرد.

استقرار ماشین مجازی GCE

یک ماشین مجازی GCE در همان ناحیه و VPC به عنوان کلاستر AlloyDB ایجاد کنید، مطمئن شوید که دیسک بوت به اندازه کافی بزرگ است تا Solr را اجرا کند. در اینجا ما یک دیسک بوت 20 گیگابایتی را در فلگ --create-disk مشخص می‌کنیم.

در Cloud Shell اجرا کنید: 

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,size=20,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

خروجی مورد انتظار کنسول: 

student@cloudshell:~ (alloydb-hybrid-search)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --network=default \
    --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: X.X.X.X
EXTERNAL_IP: X.X.X.X
STATUS: RUNNING

نصب کلاینت Postgres

نرم‌افزار کلاینت PostgreSQL را روی ماشین مجازی مستقر شده نصب کنید.

اتصال به ماشین مجازی:

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

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ 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.

دستور اجرای نرم‌افزار را درون ماشین مجازی نصب کنید: 

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

خروجی مورد انتظار کنسول: 

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...
Setting up postgresql-client (15+248+deb12u1) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u14) ...

اتصال به نمونه

با استفاده از psql از ماشین مجازی به نمونه اصلی متصل شوید.

در همان تب Cloud Shell که جلسه SSH به ماشین مجازی instance-1 شما باز است.

از مقدار رمز عبور ذکر شده AlloyDB (PGPASSWORD) و شناسه خوشه AlloyDB برای اتصال به AlloyDB از ماشین مجازی 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"

خروجی مورد انتظار کنسول: 

student@instance-1:~$ 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"
psql (15.18 (Debian 15.18-0+deb12u1), server 17.9)
WARNING: psql major version 15, server major version 17.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

جلسه psql را ببندید: 

exit

۶. آماده‌سازی پایگاه داده

ما باید یک پایگاه داده ایجاد کنیم، ادغام Vertex AI را فعال کنیم، اشیاء پایگاه داده را ایجاد کنیم و داده‌ها را وارد کنیم.

مجوزهای لازم را به AlloyDB اعطا کنید

مجوزهای Vertex AI را به عامل سرویس AlloyDB اضافه کنید.

با استفاده از علامت "+" در بالا، یک تب Cloud Shell دیگر باز کنید.

abc1.png

در تب جدید cloud shell دستور زیر را اجرا کنید: 

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"

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ 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"
Your active configuration is: [cloudshell-30137]

Updated IAM policy for project [my-project-93954-gke].
bindings:
- members:
<redacted>
version: 1

با کلیک روی "X" یا اجرای دستور زیر، تب را ببندید: 

exit

ایجاد پایگاه داده

یک پایگاه داده با نام quickstart ایجاد کنید.

در جلسه GCE VM دستور زیر را اجرا کنید:

ایجاد پایگاه داده: 

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

خروجی مورد انتظار کنسول: 

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

ادغام هوش مصنوعی Vertex را فعال کنید

ادغام Vertex AI و افزونه‌های pgvector را در پایگاه داده فعال کنید.

در ماشین مجازی GCE دستور زیر را اجرا کنید: 

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"

خروجی مورد انتظار کنسول: 

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"
NOTICE:  extension "google_ml_integration" already exists, skipping
CREATE EXTENSION
CREATE EXTENSION

وارد کردن داده

داده‌های آماده‌شده را دانلود کرده و در پایگاه داده جدید وارد کنید.

در ماشین مجازی GCE دستور زیر را اجرا کنید: 

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"

خروجی مورد انتظار کنسول: 

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"
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"
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
COPY 941
COPY 263861
COPY 4654

در مرحله بعد، بیایید پرچم‌های لازم پایگاه داده را تنظیم کنیم. می‌توانید از کنسول وب استفاده کنید و پرچم‌ها را در نمونه اصلی مدیریت کنید یا از دستور 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,scann.enable_preview_features=on,google_ml_integration.enable_preview_ai_functions=on,google_ml_integration.enable_ai_query_engine=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

خروجی کنسول مورد انتظار 

student@cloudshell:~ (alloydb-hybrid-search)$ 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,scann.enable_preview_features=on,google_ml_integration.enable_preview_ai_functions=on,google_ml_integration.enable_ai_query_engine=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY
Your active configuration is: [cloudshell-30137]
Operation ID: operation-1784245853151-656c31c44e12b-6084eb8b-d6611419

فعال کردن پرچم‌های پایگاه داده نیاز به راه‌اندازی مجدد نمونه دارد و چند دقیقه طول می‌کشد. پس از اتمام، وضعیت نمونه AlloyDB به صورت "آماده" نمایش داده می‌شود.

۷. ایجاد جاسازی‌های برداری

پس از وارد کردن داده‌ها، جداول زیر را داریم: cymbal_products که اطلاعات مربوط به محصولات را ذخیره می‌کند، cymbal_inventory که موجودی کالا را در هر فروشگاه ردیابی می‌کند، و cymbal_stores که لیستی از فروشگاه‌ها است. برای انجام جستجوی معنایی روی محصولات، باید جاسازی‌های برداری از توضیحات محصول خود را با تابع initialize_embeddings ایجاد کنیم. ما از ادغام Vertex AI برای محاسبه داده‌های برداری بر اساس توضیحات محصول و اضافه کردن آن به جدول استفاده خواهیم کرد. می‌توانید اطلاعات بیشتر در مورد فناوری مورد استفاده را در مستندات بخوانید.

برای استفاده از این یکپارچه‌سازی، با AlloyDB studio یا با استفاده از psql از ماشین مجازی خود و با استفاده از IP نمونه AlloyDB و رمز عبور postgres به پایگاه داده متصل شوید: 

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

نسخه افزونه google_ml_integration را تأیید کنید. 

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

نسخه باید ۱.۵.۲ یا بالاتر باشد. در اینجا نمونه‌ای از خروجی آمده است: 

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

نسخه پیش‌فرض باید ۱.۵.۲ یا بالاتر باشد، اما اگر نمونه شما نسخه قدیمی‌تری را نشان می‌دهد، احتمالاً باید به‌روزرسانی شود. بررسی کنید که آیا قابلیت تعمیر و نگهداری برای نمونه غیرفعال شده است یا خیر.

افزونه‌ی vector را نصب کنید و یک ستون جدید برای ذخیره‌ی embeddingها در cymbal_products ایجاد کنید. 

CREATE EXTENSION IF NOT EXISTS vector;
ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

خروجی مورد انتظار کنسول: 

quickstart_db=> CREATE EXTENSION IF NOT EXISTS vector;
ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
NOTICE:  extension "vector" already exists, skipping
CREATE EXTENSION
ALTER TABLE

ما از تولید جاسازی دسته‌ای برای بهبود کارایی استفاده خواهیم کرد. می‌توانید اطلاعات بیشتر در مورد گزینه‌ها و تکنیک‌های مختلف تولید جاسازی را در راهنما بخوانید. ما قبلاً پرچم google_ml_integration.enable_faster_embedding_generation را فعال کرده‌ایم که به ما امکان تولید جاسازی دسته‌ای را می‌دهد.

در نهایت، ما همچنین می‌خواهیم که با تغییر مقادیر ستون‌ها، با وارد کردن آرگومان incremental_refresh_mode در فراخوانی تابع، جاسازی‌ها نیز به‌روزرسانی شوند. این کار باعث ایجاد سربار برای پایگاه داده ما می‌شود، اما این یک بده‌بستان است که ما انجام می‌دهیم تا جاسازی‌ها به طور خودکار با محتوا همگام باشند. اگر می‌خواهید جاسازی‌ها را به صورت دستی به‌روزرسانی کنید، می‌توانید دستورالعمل‌ها را در مستندات پیدا کنید.

حالا که همه اینها را کنار هم قرار دادیم و جاسازی‌ها را ایجاد کردیم، از تابع initialize_embeddings استفاده می‌کنیم و batch_size با مقدار ۵۰ به عنوان راهنمای دسته‌ای ارسال می‌کنیم و incremental_refresh_mode روی 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'
);

و حالا اگر یک ردیف جدید به جدول اضافه کنیم که مقدار NULL برای ستون 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);

حالا وقتی ردیفی را که تازه درج کرده‌ایم، کوئری می‌کنیم، خواهیم دید که ستون product_embedding به طور خودکار به‌روزرسانی می‌شود. 

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

خروجی باید شبیه زیر باشد: 

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)

۸. ایجاد یک اندیس برداری

برای بهبود عملکرد جستجوی برداری، یک شاخص ScaNN اضافه خواهیم کرد.

ایجاد شاخص ScanNN

برای ساخت شاخص SCANN باید یک افزونه دیگر را فعال کنیم. افزونه alloydb_scann رابطی برای کار با شاخص برداری از نوع ANN با استفاده از الگوریتم ScaNN گوگل فراهم می‌کند. 

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

خروجی مورد انتظار: 

quickstart_db=> CREATE EXTENSION IF NOT EXISTS alloydb_scann;
CREATE EXTENSION

این شاخص می‌تواند در حالت دستی یا خودکار ایجاد شود. حالت دستی به طور پیش‌فرض فعال است و می‌توانید یک شاخص ایجاد کنید و آن را مانند هر شاخص دیگری نگهداری کنید. اما اگر حالت خودکار را فعال کنید، می‌توانید شاخصی ایجاد کنید که نیازی به هیچ گونه نگهداری از طرف شما نداشته باشد. می‌توانید جزئیات مربوط به همه گزینه‌ها را در مستندات مطالعه کنید. در مورد ما، ردیف‌های کافی برای ایجاد شاخص در حالت خودکار نداریم - بنابراین آن را به صورت دستی ایجاد می‌کنیم و پارامترهای تنظیم را نیز لحاظ می‌کنیم. می‌توانید در مورد تنظیم پارامترهای شاخص در مستندات مطالعه کنید. 

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

خروجی مورد انتظار: 

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

بررسی استفاده از ایندکس

اکنون می‌توانیم کوئری جستجوی برداری را در حالت EXPLAIN اجرا کنیم و بررسی کنیم که آیا از ایندکس استفاده می‌شود یا خیر. 

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;

خروجی مورد انتظار (برای وضوح بیشتر، حذف شده است): 

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

از خروجی می‌توانیم به وضوح ببینیم که کوئری از «اسکن شاخص با استفاده از cymbal_products_embeddings_scann روی cymbal_products» استفاده کرده است.

۹. ایجاد یک نمونه Solr

ما از Apache Solr برای بخش جستجوی متن کامل (FTS) در جستجوی ترکیبی استفاده خواهیم کرد. در این مرحله، یک نمونه مستقل Solr را در ماشین مجازی که قبلاً ایجاد کرده‌اید، مستقر خواهید کرد.

برای ایمن‌سازی دسترسی به Solr، احراز هویت پایه (Basic Authentication) را فعال خواهیم کرد. این کار را با ارائه یک فایل پیکربندی security.json ، نصب آن و شروع کانتینر داکر Solr انجام خواهیم داد.

با SSH به ماشین مجازی متصل شوید و داکر را نصب کنید: 

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

اکنون می‌توانید دستور docker را طوری تغییر دهید که توسط کاربر شما اجرا شود: 

sudo usermod -aG docker $USER
newgrp docker

اکنون، فایل security.json را برای فعال کردن احراز هویت پایه با نام کاربری solr و رمز عبور SolrRocks ایجاد کنید. 

nano security.json

در فایل، JSON زیر را وارد کنید: 

{
  "authentication": {
    "blockUnknown": true,
    "class": "solr.BasicAuthPlugin",
    "credentials": {
      "solr": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="
    }
  },
  "authorization": {
    "class": "solr.RuleBasedAuthorizationPlugin",
    "permissions": [
      { "name": "security-edit", "role": "admin" }
    ],
    "user-role": { "solr": "admin" }
  }
}

ذخیره کنید و از نانو خارج شوید (Ctrl + O، Enter، Ctrl + X).

کانتینر داکر Solr را با استفاده از docker run اجرا کنید و فایل security.json را روی کانتینر نصب کنید: 

docker run -d -p 8983:8983 --name solr --user root -v "$(pwd)/security.json:/var/solr/data/security.json" solr:9 -c -force

تأیید کنید که کانتینر در حال اجرا است: 

docker ps

خروجی مورد انتظار: 

student@instance-1:~$ docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS         PORTS                                         NAMES
90db3c73835e   solr:9    "docker-entrypoint.s..."   7 seconds ago   Up 3 seconds   0.0.0.0:8983->8983/tcp, [::]:8983->8983/tcp   solr

چند ثانیه به Solr فرصت دهید تا راه‌اندازی شود، سپس با وارد کردن اطلاعات احراز هویت اولیه خود در رابط برنامه‌نویسی کاربردی Solr، یک مجموعه جدید به نام solrindexdemo ایجاد کنید: 

curl --user solr:SolrRocks -X POST "http://localhost:8983/solr/admin/collections?action=CREATE&name=solrindexdemo&numShards=1&replicationFactor=1"

خروجی مورد انتظار: 

student@instance-1:~$ curl --user solr:SolrRocks -X POST "http://localhost:8983/solr/admin/collections?action=CREATE&name=solrindexdemo&numShards=1&replicationFactor=1"
{
  "responseHeader":{
    "status":0,
    "QTime":3586
  },
  "success":{
    "172.17.0.2:8983_solr":{
      "responseHeader":{
        "status":0,
        "QTime":2405
      },
      "core":"solrindexdemo_shard1_replica_n1"
    }
  },
  "warning":"Using _default configset. Data driven schema functionality is enabled by default, which is NOT RECOMMENDED for production use. To turn it off: curl http://{host:port}/solr/solrindexdemo/config -d '{\"set-user-property\": {\"update.autoCreateFields\":\"false\"}}'"

حالا، نمونه Solr را با توضیحات و نام محصولات پر می‌کنیم. فایل CSV محصولات را از فضای ذخیره‌سازی ابری به ماشین مجازی کپی کنید. 

gcloud storage cp gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv .

حالا یک اسکریپت پایتون برای استخراج CSV و قالب‌بندی داده‌ها در یک لیست JSON برای به‌روزرسانی انبوه ایجاد کنید. 

nano convert.py

در فایل، موارد زیر را وارد کنید: 

import csv
import json

# Configuration
input_file = 'cymbal_products.csv'
output_file = 'products.json'

def convert():
    try:
        with open(input_file, mode='r', encoding='utf-8') as f_in, \
             open(output_file, mode='w', encoding='utf-8') as f_out:
            
            reader = csv.DictReader(f_in)
            
            products = []
            for row in reader:
                products.append({
                    "id": row['uniq_id'].strip(),
                    "product_name": row['product_name'].strip(),
                    "product_description": row['product_description'].strip()
                })
                
            json.dump(products, f_out, indent=2)
            print(f"Success: Processed {len(products)} products.")
            print(f"Output saved to: {output_file}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    convert()

فایل را ذخیره و اجرا کنید: 

python3 convert.py

خروجی مورد انتظار: 

admin_gopalbhutada_altostrat_com@instance-1:~$ python3 convert.py
Success: Processed 941 products.
Output saved to: products.json

حالا داده‌های JSON را با استفاده از update handler به Apache Solr ارسال کنید: 

curl --user solr:SolrRocks -X POST -H 'Content-Type: application/json' \
  'http://localhost:8983/solr/solrindexdemo/update?commit=true' \
  --data-binary "@products.json"

خروجی مورد انتظار: 

admin_gopalbhutada_altostrat_com@instance-1:~$ curl --user solr:SolrRocks -X POST -H 'Content-Type: application/json' \
  'http://localhost:8983/solr/solrindexdemo/update?commit=true' \
  --data-binary "@products.json"
{
  "responseHeader":{
    "rf":1,
    "status":0,
    "QTime":3220
  }
}

حالا باید یک راز در Secret Manager ایجاد کنیم که اعتبارنامه‌های Solr ما را ذخیره کند. از آنجایی که AlloyDB برای احراز هویت Basic با استفاده از مقادیر username:password کدگذاری شده با base64 به FDW جستجوی خارجی لینک می‌دهد، ابتدا رشته کدگذاری شده با base64 را برای solr:SolrRocks دریافت می‌کنیم: 

echo -n "solr:SolrRocks" | base64

خروجی: 

admin_gopalbhutada_altostrat_com@instance-1:~$ echo -n "solr:SolrRocks" | base64
c29scjpTb2xyUm9ja3M=

با استفاده از این اعتبارنامه کدگذاری شده با base64، یک راز در Google Secret Manager ایجاد کنید. در Cloud Shell، دستور زیر را اجرا کنید: 

echo -n "c29scjpTb2xyUm9ja3M=" | \
gcloud secrets create solr-credentials \
    --replication-policy="automatic" \
    --data-file=-

۱۰. ایجاد یک بسته‌بندی داده خارجی در AlloyDB

مدت زمان ۱۰:۰۰

برای جستجوی داده‌های ذخیره شده در Apache Solr از AlloyDB، باید یک بسته‌بندی داده خارجی (FDW) برای Solr و یک جدول خارجی ایجاد کنیم. قبلاً اعتبارنامه‌های Solr را در Secret Manager ذخیره می‌کردید. برای اینکه AlloyDB به راز دسترسی داشته باشد، مجوز لازم را به حساب سرویس اعطا کنید.

در Cloudshell، به حساب کاربری سرویس، دسترسی به رمز solr-credentials را اعطا کنید: 

gcloud secrets add-iam-policy-binding solr-credentials \
    --member="serviceAccount:service-$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

خروجی مورد انتظار: 

admin_@cloudshell:~ (my-project-93954-gke)$ gcloud secrets add-iam-policy-binding solr-credentials \
    --member="serviceAccount:service-$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"
Your active configuration is: [cloudshell-13031]
Updated IAM policy for secret [solr-credentials].
bindings:
- members:
  - serviceAccount:service-350113473377@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/secretmanager.secretAccessor
etag: BwZWyKlkx6Q=
version: 1

با AlloyDB Studio به پایگاه داده متصل شوید (یا با استفاده از psql از طریق ماشین مجازی متصل شوید). با کاربر postgres به quickstart_db وارد شوید.

افزونه FDW را فعال کنید: 

CREATE EXTENSION IF NOT EXISTS external_search_fdw;

خروجی مورد انتظار: 

CREATE EXTENSION

دریافت پارامترهای اتصال

قبل از پیکربندی سرور داده خارجی در AlloyDB، به آدرس IP داخلی ماشین مجازی (جایی که Solr در حال اجرا است) و مسیر مخفی آن نیاز دارید.

برای چاپ IP داخلی ماشین مجازی، دستور زیر را در Cloud Shell اجرا کنید: 

gcloud compute instances describe instance-1 \
    --zone=us-central1-a \
    --format="value(networkInterfaces[0].networkIP)"

خروجی مورد انتظار: 

10.X.X.X

برای چاپ مسیر منبع مخفی در Secret Manager، دستور زیر را اجرا کنید: 

gcloud secrets describe solr-credentials --format="value(name)"

خروجی مورد انتظار: 

projects/<project_id>/secrets/solr-credentials

برای دسترسی به آپاچی سولر، یک سرور داده خارجی ایجاد کنید. جایگزین کنید و در کوئری زیر با مقادیری که بازیابی کرده‌اید. مطمئن شوید که /versions/latest را به مسیر مخفی خود اضافه می‌کنید تا جدیدترین نسخه مخفی را دریافت کنید: 

CREATE SERVER solr_demo_server
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS(
    server 'http://<VM_INTERNAL_IP_ADDRESS>:8983',
    search_provider 'solr',
    auth_mode 'secret_manager',
    auth_method 'Basic',
    secret_path '<SECRET_PATH>/versions/latest'
);

خروجی مورد انتظار: 

CREATE SERVER

سپس، جدول خارجی را تعریف کنید. پس از فراداده، تعریف طرحواره فیلد Solr را برای مطابقت با داده‌های بارگذاری شده قبلی ارائه دهید. در جدول راه دور، نام مجموعه Solr را مشخص کنید. 

CREATE FOREIGN TABLE solrindexdemo (
    metadata external_search_fdw_schema.OpaqueMetadata,
    id TEXT,
    product_name TEXT,
    product_description TEXT
)
SERVER solr_demo_server
OPTIONS(
    remote_table_name 'solrindexdemo'
);

یک نگاشت کاربر برای سرور ایجاد کنید: 

CREATE USER MAPPING FOR CURRENT_USER SERVER solr_demo_server;

حالا می‌توانید جدول خارجی را آزمایش کنید:

SELECT id, product_name
FROM solrindexdemo
ORDER BY metadata <@> 'product_description:cherry' DESC
limit 10;

خروجی مورد انتظار: 

"id","product_name"
"d536e9e823296a2eba198e52dd23e712","Cherry Tree"
"390cf08feac229e7b752709fd1f943b3","Woven Round Placemat, Set of Twelve, Grass"
"2c9aa7ac98c30abf78dd9c62a68a34e6","48 Scented Wax Melts Wax Cubes: Jelly Belly Jelly Beans Candy Bulk Soy Wax Melts For Candle Warmer, Wax Warmers, Wax Melt Warmers In 8 Pack Set"

۱۱. استفاده از جستجوی ترکیبی

مدت زمان ۱۰:۰۰

اکنون که همه چیز تنظیم شده است، می‌توانیم از تابع ai.hybrid_search() برای ترکیب جستجوی برداری و جستجوی متن کامل استفاده کنیم. می‌توانید اطلاعات بیشتر در مورد جستجوی ترکیبی را در مستندات بخوانید. هنگام استفاده از جستجوی ترکیبی، به طور پیش‌فرض نتایج پرس‌وجو از الگوریتم Reciprocal Rank Fusion برای مرتب‌سازی نتایج رتبه‌بندی از چندین پرس‌وجو استفاده می‌کنند. ابتدا، بیایید جستجوی برداری و جستجوی ترکیبی را به طور مستقل امتحان کنیم تا تفاوت‌های آنها را تجزیه و تحلیل کنیم.

پرس و جوی زیر جستجوی برداری را برای یافتن محصولاتی که مشابه cherry هستند انجام می‌دهد. آرایه لیستی از جستجوها را برای انجام ارائه می‌دهد. در این مورد، ما فقط از جستجوی برداری استفاده می‌کنیم، اما بعداً هم جستجوی برداری و هم جستجوی FTS را ارائه خواهیم داد. 

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

در خروجی، درخت گیلاس اولین نتیجه است، اما توجه داشته باشید که دو درخت بعدی نیز درختان میوه هستند. دلیل این امر این است که وقتی از جستجوی برداری در ستون product_description استفاده می‌کنیم، تطابق‌های معنایی با شرط جستجوی خود پیدا می‌کنیم. 

"id","score","product_name","product_description"
"d536e9e823296a2eba198e52dd23e712","0.01639344262295082","Cherry Tree","This is a beautiful cherry tree that will produce delicious cherries. It is an deciduous tree that grows to be about 15 feet tall. The leaves are dark green in the summer and turn a beautiful red in the fall. Cherry trees are known for their beauty and their ability to provide shade and privacy. Cherry trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 4-9."
"b70c44b1a38c0a2329fa583c9109a80f","0.016129032258064516","Peach Tree","This is a beautiful peach tree that will produce delicious peaches. It is an evergreen tree that grows to be about 20 feet tall. The leaves are dark green in the summer and turn a beautiful yellow in the fall. Peach trees are known for their beauty and their ability to provide shade and privacy. Peach trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 2-9."
"23e41a71d63d8bbc9bdfa1d118cfddc5","0.015873015873015872","Apple Tree","This is a beautiful apple tree that will produce delicious apples. It is a deciduous tree that grows to be about 30 feet tall. The leaves are dark green in the summer and turn a beautiful red, orange, and yellow in the fall. Apple trees are known for their strength and durability. They are also a popular choice for shade trees. Apple trees prefer a cool, moist climate and loamy soil. They are best suited for USDA zones 4-8."

برای انجام جستجوی متن کامل با استفاده از Apache Solr FDW، کوئری زیر را اجرا کنید: 

SELECT id, score, cymbal_products.product_name, cymbal_products.product_description
FROM ai.hybrid_search(
  ARRAY[
      '{
        "limit": 3,
        "data_type": "external_search_fdw",
        "table_name": "solrindexdemo",
        "key_column": "id",
        "query_text_input": "product_description:cherry"
      }'::JSONB
  ]
) JOIN cymbal_products ON id = cymbal_products.uniq_id;

به نتایج توجه کنید، از آنجایی که جستجوی متن کامل از تطبیق توکن استفاده می‌کند، نتایج هر چیزی را که شامل کلمه "cherry" در توضیحات محصول باشد، برمی‌گرداند. 

"id","score","product_name","product_description"
"d536e9e823296a2eba198e52dd23e712","0.01639344262295082","Cherry Tree","This is a beautiful cherry tree that will produce delicious cherries. It is an deciduous tree that grows to be about 15 feet tall. The leaves are dark green in the summer and turn a beautiful red in the fall. Cherry trees are known for their beauty and their ability to provide shade and privacy. Cherry trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 4-9."
"390cf08feac229e7b752709fd1f943b3","0.016129032258064516","Woven Round Placemat, Set of Twelve, Grass","...These placemats are great for special occasions and holidays, but are also perfect to accessorize your everyday place settings.|Measurements. 15-inch round diameter is the perfect size for most table sizes and shapes.|Pop Colors. Choose from 7 pop woven color placemats including: Black, Cherry, Grass, Taupe, Navy, Sun and Graphite."
"2c9aa7ac98c30abf78dd9c62a68a34e6","0.015873015873015872","48 Scented Wax Melts Wax Cubes: Jelly Belly Jelly Beans Candy Bulk Soy Wax Melts For Candle Warmer, Wax Warmers, Wax Melt Warmers In 8 Pack Set","...From These Flavors: Lemon Drop, Mixed Berry Smoothie, Sizzling Cinnamon, Crushed Pineapple, Juicy Pear, Cotton Candy, Toasted Marshmallow, French Vanilla, Watermelon, Red Apple, Very Cherry, Buttered Popcorn..."

حالا می‌توانید جستجوی معنایی و FTS را با هم ترکیب کنید تا به نتایج معنادارتری برسید. فرض کنید می‌خواهیم درختی را جستجو کنیم که می‌تواند از یک خانه بلندتر شود و می‌خواهیم از کالیفرنیا باشد. ما عبارت جستجو را تقسیم می‌کنیم تا از هدف معنایی در مقابل تطبیق تحت‌اللفظی بهره ببریم. جستجوی برداری بخش توصیفی را مدیریت می‌کند: «درختی که می‌تواند از یک خانه بلندتر شود» زیرا مفهوم مقیاس را بدون نیاز به کلمات کلیدی دقیق درک می‌کند. در همین حال، جستجوی متن کامل «کالیفرنیا» را به عنوان یک فیلتر دقیق مدیریت می‌کند تا اطمینان حاصل شود که ما یک تطابق جغرافیایی دقیق به جای چیزی که از نظر مفهومی مشابه است، دریافت می‌کنیم. 

SELECT id, score, cymbal_products.product_name, cymbal_products.product_description
FROM ai.hybrid_search(
  ARRAY[
    '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 3,
        "query_vector": "ai.embedding(''text-embedding-005'', ''tree that can grow taller than a house'')::vector"
      }'::JSONB,
      '{
        "limit": 3,
        "data_type": "external_search_fdw",
        "table_name": "solrindexdemo",
        "key_column": "id",
        "query_text_input": "product_description:California"
      }'::JSONB
  ]
) JOIN cymbal_products ON id = cymbal_products.uniq_id;

نتایج مورد انتظار: 

"id","score","product_name","product_description"
"a589fd36a8a20fd9472d2403d6ed692a","0.00819672631147241","California Redwood","This is a beautiful redwood tree that can grow to be over 300 feet tall. It is an evergreen tree that grows in the coastal forests of California. Redwoods are known for their beauty and their strength. They are best suited for USDA zones 7-10."
"ef9432802da24041594c2cf368dfb4d2","0.008064521129029258","Madrone","This is a beautiful madrona tree that can grow to be over 80 feet tall. It is an evergreen tree that grows in the coastal forests of California. Madronas are known for their beauty and their bark. They are best suited for USDA zones 7-10."
"1360d8642bc218e4ea28e9c32b2e1721","0.007936512936504936","California Sycamore","This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is an deciduous tree that grows in the valleys and foothills of California. California sycamores are known for their beauty and their shade. They are best suited for USDA zones 7-10."

۱۲. محیط را تمیز کنید

وقتی کار آزمایشگاهی‌تان تمام شد، نمونه‌ها و کلاستر AlloyDB را از بین ببرید.

کلاستر AlloyDB و تمام نمونه‌های آن را حذف کنید.

اگر از نسخه آزمایشی AlloyDB استفاده کرده‌اید. اگر قصد دارید آزمایشگاه‌ها و منابع دیگری را با استفاده از خوشه آزمایشی آزمایش کنید، خوشه آزمایشی را حذف نکنید. شما قادر به ایجاد خوشه آزمایشی دیگری در همان پروژه نخواهید بود.

خوشه با استفاده از گزینه‌ی Force از بین می‌رود که تمام نمونه‌های متعلق به خوشه را نیز حذف می‌کند.

در پوسته ابری، اگر اتصال شما قطع شده و تمام تنظیمات قبلی از بین رفته است، متغیرهای پروژه و محیط را تعریف کنید: 

gcloud config set project <your project id>

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

حذف خوشه: 

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

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ 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-1784270790060-656c8ea9fea06-1b93001f-846543e0
Deleting cluster...done.

حذف پشتیبان‌های AlloyDB

تمام پشتیبان‌های AlloyDB را برای کلاستر حذف کنید:

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

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ 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-1784271231983-656c904f71e05-1389a145-f101ceee
Deleting backup...done.

حالا می‌توانیم ماشین مجازی خود را نابود کنیم

حذف ماشین مجازی GCE

در Cloud Shell اجرا کنید: 

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

خروجی مورد انتظار کنسول: 

admin_@cloudshell:~ (my-project-93954-gke)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

۱۳. تبریک

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

آنچه ما پوشش داده‌ایم

  • نحوه استقرار کلاستر AlloyDB و نمونه اولیه آن
  • نحوه اتصال به AlloyDB از طریق ماشین مجازی Google Compute Engine
  • نحوه ایجاد پایگاه داده و فعال کردن AlloyDB AI
  • نحوه بارگذاری داده‌ها در پایگاه داده
  • نحوه استفاده از استودیوی AlloyDB
  • ایجاد جاسازی‌ها با Vertex AI
  • چگونه یک شاخص برداری ScaNN ایجاد کنیم تا جستجوی برداری را تقویت کنیم
  • نحوه ایجاد یک بسته‌بندی داده خارجی (FDW) برای Apache Solr
  • با ترکیب جستجوی معنایی در AlloyDB با جستجوی متن کامل در Solr، جستجوی ترکیبی انجام دهید.

مراحل بعدی

می‌توانید آزمایشگاه‌های کد AlloyDB بیشتری را در سایت رسمی codelab (.postgresql) جستجو کنید.