شروع کار با Vector Embeddings با AlloyDB AI

۱. مقدمه

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

پیش‌نیازها

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

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

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

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

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

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

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

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

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

احتیاط: حساب‌های کاربری محل کار و مدرسه ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه یا دسترسی به برخی منابع توسط شما شود.

2. یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. برای ایجاد یک پروژه جدید در کنسول Google Cloud، در سربرگ، روی دکمه «انتخاب پروژه» کلیک کنید که یک پنجره بازشو باز می‌شود.

در پنجره انتخاب پروژه، دکمه «پروژه جدید» را فشار دهید که یک کادر محاوره‌ای برای پروژه جدید باز می‌کند.

در کادر محاوره‌ای، نام پروژه مورد نظر خود را وارد کرده و مکان را انتخاب کنید.

• نام پروژه ، نام نمایشی برای شرکت‌کنندگان این پروژه است. نام پروژه توسط APIهای گوگل استفاده نمی‌شود و می‌توان آن را در هر زمانی تغییر داد.
• شناسه پروژه در تمام پروژه‌های گوگل کلود منحصر به فرد و غیرقابل تغییر است (پس از تنظیم، دیگر قابل تغییر نیست). کنسول گوگل کلود به طور خودکار یک شناسه منحصر به فرد تولید می‌کند، اما می‌توانید آن را سفارشی کنید. اگر شناسه تولید شده را دوست ندارید، می‌توانید یک شناسه تصادفی دیگر ایجاد کنید یا شناسه خودتان را برای بررسی در دسترس بودن آن ارائه دهید. در اکثر آزمایشگاه‌های کد، باید شناسه پروژه خود را که معمولاً با عبارت PROJECT_ID مشخص می‌شود، ارجاع دهید.
• برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده می‌کنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.

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

توجه: اگر از حساب Gmail استفاده می‌کنید، می‌توانید مکان پیش‌فرض را روی «بدون سازمان» تنظیم کنید. اگر از حساب Google Workspace استفاده می‌کنید، مکانی را انتخاب کنید که برای سازمان شما منطقی باشد.

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

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

استفاده از اعتبار ۵ دلاری گوگل کلود (اختیاری)

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

1. روی این لینک کلیک کنید و با یک حساب گوگل شخصی وارد شوید.
2. چیزی شبیه به این خواهید دید:

3. روی دکمه‌ی «برای دسترسی به اعتبارات خود اینجا کلیک کنید» کلیک کنید. این کار شما را به صفحه‌ای می‌برد که می‌توانید پروفایل صورتحساب خود را تنظیم کنید. اگر با صفحه‌ی ثبت‌نام آزمایشی رایگان مواجه شدید، روی لغو کلیک کنید و به پیوند صورتحساب ادامه دهید.

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

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

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

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

برخی نکات:

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

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

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

از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

همچنین می‌توانید دکمه‌های G و سپس S را فشار دهید. اگر در کنسول ابری گوگل باشید یا از این لینک استفاده کنید، این توالی، Cloud Shell را فعال می‌کند.

آماده‌سازی و اتصال به محیط فقط چند لحظه طول می‌کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

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

۳. قبل از شروع

فعال کردن API

خروجی:

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

برای استفاده از 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

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

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 ها

• رابط برنامه‌نویسی کاربردی 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) و آموزش مدل‌های سفارشی، فراهم می‌کند.

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

gcloud config set compute/region us-central1

۴. استقرار AlloyDB

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

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

توجه: این مرحله فقط در صورتی لازم است که از قبل یک محدوده 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

نکته: اجرای دستور دوم چند دقیقه طول می‌کشد

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

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

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

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

export PGPASSWORD=`openssl rand -hex 12`

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

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

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

echo $PGPASSWORD

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

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

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

یک خوشه آزمایشی رایگان ایجاد کنید

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

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

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

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

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

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

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

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

توجه: ایجاد نمونه معمولاً 6 تا 10 دقیقه طول می‌کشد.

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

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

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

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

اگر این اولین کلاستر AlloyDB شما در پروژه نیست، با ایجاد یک کلاستر استاندارد ادامه دهید.

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

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

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

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

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

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

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

توجه: ایجاد نمونه معمولاً 6 تا 10 دقیقه طول می‌کشد.

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

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

student@cloudshell:~ (test-project-402417)$ 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.                                                                                                                                                                                                                                                     

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

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

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

یک ماشین مجازی GCE در همان ناحیه و VPC به عنوان کلاستر AlloyDB ایجاد کنید.

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

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

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

student@cloudshell:~ (test-project-402417)$ export ZONE=us-central1-a
student@cloudshell:~ (test-project-402417)$ 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

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

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

توجه: اولین اتصال SSH به ماشین مجازی می‌تواند بیشتر طول بکشد زیرا این فرآیند شامل ایجاد کلید RSA برای اتصال امن و انتشار بخش عمومی کلید به پروژه است.

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

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

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
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:~$ 

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

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

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

با استفاده از 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-aip-01
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 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 را ببندید:

exit

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

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

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

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

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

در تب جدید 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"

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

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:[e-mail]
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1
 

با اجرای هر یک از دستورهای "exit" در تب، تب را ببندید:

exit

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

ایجاد پایگاه داده با شروع سریع

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

توجه: اگر جلسه SSH شما خاتمه یافته است، باید متغیرهای محیطی خود را مانند موارد زیر تنظیم مجدد کنید:

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)

export REGION=us-central1

export ADBCLUSTER=alloydb-aip-01

export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

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

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
student@instance-1:~$  

ادغام هوش مصنوعی 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"
CREATE EXTENSION
CREATE EXTENSION
student@instance-1:~$ 

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

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

در ماشین مجازی 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:~$ gsutil 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:~$ gsutil 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:~$ gsutil 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:~$ gsutil 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:~$

۷. محاسبه‌ی جایگذاری‌ها

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

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

فعال کردن تولید سریع جاسازی

با استفاده از 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.2
(1 row)

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

نکته: نسخه افزونه به طور خودکار در backend مدیریت می‌شود. می‌توانید با اجرای دستور زیر در جلسه psql خود، افزونه را به‌روزرسانی کنید:

ALTER EXTENSION google_ml_integration UPDATE;

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

CALL google_ml.upgrade_to_preview_version();

سپس باید پرچم پایگاه داده را تأیید کنیم. ما باید پرچم google_ml_integration.enable_faster_embedding_generation را فعال کنیم. در همان جلسه psql، مقدار پرچم را بررسی کنید.

show google_ml_integration.enable_faster_embedding_generation;

اگر پرچم در موقعیت صحیح قرار داشته باشد، خروجی مورد انتظار به این شکل خواهد بود:

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

اما اگر "خاموش" نشان داده شود، باید نمونه را به‌روزرسانی کنیم. می‌توانید این کار را با استفاده از کنسول وب یا دستور gcloud همانطور که در مستندات توضیح داده شده است، انجام دهید. در اینجا نحوه انجام این کار با استفاده از دستور gcloud را نشان می‌دهم:

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
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

ممکن است چند دقیقه طول بکشد، اما در نهایت مقدار پرچم باید به "روشن" تغییر کند. پس از آن می‌توانید مراحل بعدی را ادامه دهید.

ایجاد ستون جاسازی

با استفاده از psql به پایگاه داده متصل شوید و با استفاده از تابع embedding در جدول cymbal_products، یک ستون مجازی با داده‌های برداری ایجاد کنید. تابع embedding، داده‌های برداری را از Vertex AI بر اساس داده‌های ارائه شده از ستون product_description برمی‌گرداند.

توجه: اگر جلسه SSH شما خاتمه یافته است، باید متغیرهای محیطی خود را مانند موارد زیر تنظیم مجدد کنید:

export PGPASSWORD=<Noted password>

export INSTANCE_IP=<AlloyDB Instance IP>

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

در جلسه psql پس از اتصال به پایگاه داده، دستور زیر را اجرا کنید:

ALTER TABLE cymbal_products ADD COLUMN embedding vector(768);

این دستور ستون مجازی را ایجاد کرده و آن را با داده‌های برداری پر می‌کند.

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

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

اکنون می‌توانیم با استفاده از دسته‌هایی با ۵۰ ردیف، جاسازی‌ها را تولید کنیم. می‌توانید با اندازه‌های مختلف دسته آزمایش کنید و ببینید آیا زمان اجرا تغییر می‌کند یا خیر. در همان جلسه psql دستور زیر را اجرا کنید:

فعال کردن زمان‌بندی برای اندازه‌گیری مدت زمان مورد نیاز:

\timing

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

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

و خروجی کنسول نشان می‌دهد که زمان تولید جاسازی کمتر از ۲ ثانیه است:

quickstart_db=> CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'embedding',
    batch_size => 50
);
NOTICE:  Initialize embedding completed successfully for table cymbal_products
CALL
Time: 1458.704 ms (00:01.459)
quickstart_db=>

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

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
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'
);

و حالا اگر یک ردیف جدید به جدول اضافه کنیم.

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", "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, NULL);

می‌توانیم با استفاده از پرس‌وجو، تفاوت ستون‌ها را مقایسه کنیم:

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

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

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

Time: 3.295 ms

۸. جستجوی شباهت را اجرا کنید

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

کوئری SQL را می‌توان از همان رابط خط فرمان psql یا به عنوان جایگزین، از AlloyDB Studio اجرا کرد. هر خروجی چند ردیفی و پیچیده ممکن است در AlloyDB Studio بهتر به نظر برسد.

اتصال به استودیوی AlloyDB

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

سپس در سمت چپ روی AlloyDB Studio کلیک کنید:

پایگاه داده quickstart_db و کاربر postgres را انتخاب کنید و رمز عبوری که هنگام ایجاد کلاستر یادداشت کردید را وارد کنید. سپس روی دکمه "Authenticate" کلیک کنید.

رابط کاربری AlloyDB Studio باز خواهد شد. برای اجرای دستورات در پایگاه داده، روی تب "Editor 1" در سمت راست کلیک کنید.

رابطی را باز می‌کند که می‌توانید دستورات SQL را در آن اجرا کنید

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

اجرای جستجوی شباهت از psql

اگر اتصال پایگاه داده شما قطع شده است، دوباره با استفاده از psql یا AlloyDB Studio به پایگاه داده متصل شوید.

اتصال به پایگاه داده:

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

یک کوئری اجرا کنید تا لیستی از محصولات موجود که بیشترین ارتباط را با درخواست مشتری دارند، دریافت کنید. درخواستی که قرار است برای دریافت مقدار بردار به Vertex AI ارسال کنیم، چیزی شبیه به این است: «چه نوع درختان میوه‌ای اینجا خوب رشد می‌کنند؟»

این کوئری است که می‌توانید برای انتخاب ۱۰ مورد اول که برای درخواست ما مناسب‌تر هستند، اجرا کنید:

SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) as distance
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
        distance ASC
LIMIT 10;

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

quickstart_db=> SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) as distance
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
        distance ASC
LIMIT 10;
      product_name       |                                   description                                    | sale_price | zip_code |      distance       
-------------------------+----------------------------------------------------------------------------------+------------+----------+---------------------
 Cherry Tree             | This is a beautiful cherry tree that will produce delicious cherries. It is an d |      75.00 |    93230 | 0.43922018972266397
 Meyer Lemon Tree        | Meyer Lemon trees are California's favorite lemon tree! Grow your own lemons by  |         34 |    93230 |  0.4685112926118228
 Toyon                   | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e |      10.00 |    93230 |  0.4835677149651668
 California Lilac        | This is a beautiful lilac tree that can grow to be over 10 feet tall. It is an d |       5.00 |    93230 |  0.4947204525907498
 California Peppertree   | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e |      25.00 |    93230 |  0.5054166905547247
 California Black Walnut | This is a beautiful walnut tree that can grow to be over 80 feet tall. It is a d |     100.00 |    93230 |  0.5084219510932597
 California Sycamore     | This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is  |     300.00 |    93230 |  0.5140519790508755
 Coast Live Oak          | This is a beautiful oak tree that can grow to be over 100 feet tall. It is an ev |     500.00 |    93230 |  0.5143126438081371
 Fremont Cottonwood      | This is a beautiful cottonwood tree that can grow to be over 100 feet tall. It i |     200.00 |    93230 |  0.5174774727252058
 Madrone                 | This is a beautiful madrona tree that can grow to be over 80 feet tall. It is an |      50.00 |    93230 |  0.5227400803389093

۹. بهبود واکنش

شما می‌توانید با استفاده از نتیجه‌ی پرس‌وجو، پاسخ به یک برنامه‌ی کلاینت را بهبود بخشید و با استفاده از نتایج پرس‌وجوی ارائه شده به عنوان بخشی از اعلان به مدل زبان پایه‌ی مولد Vertex AI، یک خروجی معنادار تهیه کنید.

برای دستیابی به این هدف، قصد داریم با نتایج حاصل از جستجوی برداری، یک JSON تولید کنیم، سپس از آن JSON تولید شده به عنوان یک اعلان برای مدل LLM متنی در Vertex AI استفاده کنیم تا یک خروجی معنادار ایجاد کنیم. در مرحله اول، JSON را تولید می‌کنیم، سپس آن را در Vertex AI Studio آزمایش می‌کنیم و در مرحله آخر، آن را در یک عبارت SQL که می‌تواند در یک برنامه استفاده شود، قرار می‌دهیم.

تولید خروجی با فرمت JSON

پرس‌وجو را طوری تغییر دهید که خروجی را با فرمت JSON تولید کند و فقط یک ردیف برای ارسال به Vertex AI برگرداند.

در اینجا مثالی از پرس و جو آمده است:

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.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

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

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

اجرای اعلان در Vertex AI Studio

ما می‌توانیم از JSON تولید شده برای ارائه آن به عنوان بخشی از prompt به مدل متنی هوش مصنوعی مولد در Vertex AI Studio استفاده کنیم.

استودیوی هوش مصنوعی ورتکس را در کنسول ابری باز کنید.

اگر قبلاً از آن استفاده نکرده‌اید، ممکن است از شما بخواهد که با شرایط استفاده موافقت کنید. دکمه «موافقت و ادامه» را فشار دهید.

دستور خود را در رابط کاربری بنویسید.

توجه: در مثال، ما از تمام پارامترهای پیش‌فرض برای اعلان متن فرم آزاد و آخرین مدل Gemini (در آن زمان) که به صورت پیش‌فرض و با پارامترهای پیش‌فرض پیشنهاد شده است، استفاده کردیم. خروجی شما ممکن است بسته به نسخه مدل و پارامترها متفاوت باشد. برای اطلاعات بیشتر در مورد Vertex AI و مدل‌های زبان مولد، به مستندات مراجعه کنید.

ممکن است از شما بخواهد APIهای اضافی را فعال کنید، اما می‌توانید این درخواست را نادیده بگیرید. ما برای تکمیل آزمایش خود به هیچ API اضافی نیاز نداریم.

این اعلانی است که قرار است با خروجی JSON مربوط به کوئری اولیه در مورد درختان استفاده کنیم:

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

بر اساس درخواست مشتری، لیستی از محصولات مرتبط با جستجو را بارگذاری کرده‌ایم.

لیست در قالب JSON با لیستی از مقادیر مانند {"product_name":"name","description":"some description","sale_price":10,"zip_code": 10234, "produt_id": "02056727942aeb714dc9a2313654e1b0"}

در اینجا لیست محصولات آمده است:

{"product_name":"درخت گیلاس","description":"این یک درخت گیلاس زیباست که گیلاس‌های خوشمزه‌ای تولید می‌کند. این یک درخت d است,"sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}

مشتری پرسید: «کدام درخت اینجا بهتر رشد می‌کند؟»

شما باید اطلاعاتی در مورد محصول، قیمت و برخی اطلاعات تکمیلی ارائه دهید

و این نتیجه‌ای است که وقتی اعلان را با مقادیر JSON خود و با استفاده از مدل gemini-2.5-flash-light اجرا می‌کنیم، حاصل می‌شود:

پاسخی که از مدل در این مثال دریافت کردیم به شرح زیر است. توجه داشته باشید که پاسخ شما ممکن است به دلیل تغییرات مدل و پارامترها در طول زمان متفاوت باشد:

بر اساس محصولات موجود، می‌توانم در مورد «درخت گیلاس» به شما بگویم:

محصول: درخت گیلاس

قیمت: ۷۵٫۰۰ دلار

توضیحات: این یک درخت گیلاس زیبا است که گیلاس‌های خوشمزه‌ای تولید می‌کند.

برای تعیین اینکه کدام درخت «بهترین رشد را در اینجا دارد»، به اطلاعات بیشتری نیاز دارم. آیا درختان دیگری را در فهرست خود دارید که بتوانیم آنها را با هم مقایسه کنیم، یا جنبه خاصی از «بهترین رشد» مد نظر شماست (مثلاً سریع‌ترین رشد، بیشترین تولید میوه، مقاومت در آب و هوای خاص شما)؟

اجرای اعلان در PSQL

ما می‌توانیم از ادغام هوش مصنوعی AlloyDB با Vertex AI برای دریافت پاسخ یکسان از یک مدل مولد با استفاده از SQL مستقیماً در پایگاه داده استفاده کنیم. اما برای استفاده از مدل gemini-1.5-flash ابتدا باید آن را ثبت کنیم.

افزونه google_ml_integration را بررسی کنید. باید نسخه ۱.۴.۲ یا جدیدتر داشته باشد.

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

SELECT extversion from pg_extension where extname='google_ml_integration';

پرچم پایگاه داده google_ml_integration.enable_model_support را بررسی کنید.

show google_ml_integration.enable_model_support;

خروجی مورد انتظار از جلسه psql "روشن" است:

postgres=> show google_ml_integration.enable_model_support;
 google_ml_integration.enable_model_support 
--------------------------------------------
 on
(1 row)

اگر "خاموش" را نشان می‌دهد، باید پرچم پایگاه داده google_ml_integration.enable_model_support را روی "روشن" تنظیم کنیم. برای انجام این کار می‌توانید از رابط کنسول وب AlloyDB استفاده کنید یا دستور gcloud زیر را اجرا کنید.

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

اجرای این دستور در پس‌زمینه حدود ۱ تا ۳ دقیقه طول می‌کشد. سپس می‌توانید دوباره پرچم را تأیید کنید.

برای کوئری خود به دو مدل نیاز داریم. مدل اول، مدل text-embedding-005 است که از قبل استفاده می‌شود و مدل دوم یکی از مدل‌های عمومی گوگل جمینی است.

توجه: اکثر مدل‌های عمومی گوگل یا مدل‌های جاسازی متن گوگل نیازی به ثبت ندارند و به صورت پیش‌فرض کار می‌کنند، اما در این مثال ما هر دو مدل را ثبت می‌کنیم تا گردش کار کلی کار با مدل‌های مستقر در Vertex AI را نشان دهیم.

این مثال از تمام پارامترهای پیش‌فرض برای اعلان متن فرم آزاد و آخرین مدل Gemini (در آن زمان) که به صورت پیش‌فرض پیشنهاد شده است، و با پارامترهای پیش‌فرض استفاده می‌کند. خروجی شما ممکن است بسته به نسخه مدل و پارامترها متفاوت باشد. برای اطلاعات بیشتر در مورد Vertex AI و مدل‌های زبان مولد به مستندات مراجعه کنید.

ما از مدل جاسازی متن شروع می‌کنیم. برای ثبت مدل، کد زیر را در psql یا AlloyDB Studio اجرا کنید:

CALL
  google_ml.create_model(
    model_id => 'text-embedding-005',
    model_provider => 'google',
    model_qualified_name => 'text-embedding-005',
    model_type => 'text_embedding',
    model_auth_type => 'alloydb_service_agent_iam',
    model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
    model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

و مدل بعدی که باید ثبت کنیم gemini-2.0-flash-001 است که برای تولید خروجی کاربرپسند استفاده خواهد شد.

لطفاً قبل از اجرای دستور زیر، مقادیر $PROJECT_ID را با شناسه پروژه خود و $REGION را با منطقه خود جایگزین کنید.

CALL
  google_ml.create_model(
    model_id => 'gemini-2.5-flash',
    model_request_url => 'publishers/google/models/gemini-2.5-flash:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'alloydb_service_agent_iam');

شما همیشه می‌توانید با انتخاب اطلاعات از google_ml.model_info_view، لیست مدل‌های ثبت‌شده را تأیید کنید.

select model_id,model_type from google_ml.model_info_view;

در اینجا خروجی نمونه آمده است

quickstart_db=> select model_id,model_type from google_ml.model_info_view;
        model_id         |   model_type   
-------------------------+----------------
 textembedding-gecko     | text_embedding
 textembedding-gecko@001 | text_embedding
 text-embedding-005      | text_embedding
 gemini-2.5-flash        | generic
(4 rows)

اکنون می‌توانیم از JSON تولید شده در یک subquery برای ارائه آن به عنوان بخشی از prompt به مدل متنی هوش مصنوعی مولد با استفاده از SQL استفاده کنیم.

در جلسه psql یا AlloyDB Studio به پایگاه داده، پرس و جو را اجرا کنید

WITH trees AS (
SELECT
        cp.product_name,
        cp.product_description 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.embedding <=> embedding('text-embedding-005',
        'What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1),
prompt AS (
SELECT
        'You are a friendly advisor helping to find a product based on the customer''s needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","product_description":"some description","sale_price":10}
Here is the list of products:' || json_agg(trees) || 'The customer asked "What kind of fruit trees grow well here?"
You should give information about the product, price and some supplemental information' AS prompt_text
FROM
        trees),
response AS (
SELECT
        json_array_elements(google_ml.predict_row( model_id =>'gemini-2.5-flash',
        request_body => json_build_object('contents',
        json_build_object('role',
        'user',
        'parts',
        json_build_object('text',
        prompt_text)))))->'candidates'->0->'content'->'parts'->0->'text' AS resp
FROM
        prompt)
SELECT
        string_agg(resp::text,
        ' ')
FROM
        response;

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

"Hello there! I can certainly help you with finding a great fruit tree for your area.\n\nBased on what grows well, we have a wonderful **Cherry Tree** that could be a perfect fit!\n\nThis beautiful cherry tree is an excellent choice for producing delicious cherries right in your garden. It's an deciduous tree that typically" " grows to about 15 feet tall. Beyond its fruit, it offers lovely aesthetics with dark green leaves in the summer that transition to a beautiful red in the fall, making it great for shade and privacy too.\n\nCherry trees generally prefer a cool, moist climate and sandy soil, and they are best suited for USDA Zones" " 4-9. Given the zip code you're inquiring about (93230), which is typically in USDA Zone 9, this Cherry Tree should thrive wonderfully!\n\nYou can get this magnificent tree for just **$75.00**.\n\nLet me know if you have any other questions!" "

۱۰. ایجاد اندیس برداری

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

ایجاد شاخص ScanNN

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

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

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

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

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

در مثال زیر، بیشتر پارامترها را به صورت پیش‌فرض رها می‌کنم و فقط تعدادی پارتیشن (num_leaves) برای اندیس ارائه می‌دهم:

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

می‌توانید در مورد تنظیم پارامترهای شاخص در مستندات مطالعه کنید.

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

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (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.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)
-> Index Scan using walmart_inventory_pkey on cymbal_inventory ci (cost=0.42..7.26 rows=1 width=37) (actual time=0.015..0.015 rows=1 loops=1)
Index Cond: ((store_id = 1583) AND (uniq_id = (cp.uniq_id)::text))
...

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

و اگر کوئری را بدون توضیح اجرا کنیم:

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.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

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

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

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

می‌توانید شاخص‌های مختلف موجود برای بردارها و آزمایش‌ها و مثال‌های بیشتر با ادغام langchain را که در صفحه مستندات موجود است، امتحان کنید.

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

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

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

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

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

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

gcloud config set project <your project id>

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

حذف خوشه:

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

توجه: اجرای این دستور ۳ تا ۵ دقیقه طول می‌کشد.

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

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

تمام پشتیبان‌های 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

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

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.                                                                                                                                                                                                                                                            

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

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

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

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

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

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

۱۲. تبریک

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

این آزمایشگاه بخشی از پروژه «هوش مصنوعی آماده تولید با مسیر یادگیری ابری گوگل» است.

• برای پر کردن شکاف بین نمونه اولیه و تولید، برنامه درسی کامل را بررسی کنید .
• پیشرفت خود را با هشتگ #ProductionReadyAI به اشتراک بگذارید.

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

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

۱۳. نظرسنجی

خروجی:

چگونه از این آموزش استفاده خواهید کرد؟

فقط آن را بخوانید آن را بخوانید و تمرین‌ها را انجام دهید