این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

برنامه AlloyDB Agentic RAG با جعبه ابزار MCP

۱. مقدمه

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

می‌توانید اطلاعات بیشتری در مورد جعبه ابزار MCP را در صفحه مستندات و نمونه برنامه Cymbal Air را اینجا دریافت کنید.

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

پیش‌نیازها

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

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

نحوه استقرار AlloyDB Cluster با ادغام Vertex AI
نحوه اتصال به AlloyDB
نحوه پیکربندی و استقرار سرویس MCP Tooolbox
نحوه استقرار یک برنامه نمونه با استفاده از سرویس مستقر شده

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

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

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

تنظیم محیط خودتنظیم

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

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

در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینه‌ای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

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

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

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

فعال کردن پوسته ابری

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

تصویر صفحه ترمینال Google Cloud Shell که نشان می‌دهد محیط متصل شده است

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

۳. قبل از شروع

فعال کردن API

خروجی:

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

معمولاً شناسه پروژه در خط فرمان در پوسته ابری، همانطور که در تصویر نشان داده شده است، در داخل پرانتز نشان داده می‌شود:

gcloud config set project [YOUR-PROJECT-ID]

سپس متغیر محیطی PROJECT_ID را روی شناسه پروژه Google Cloud خود تنظیم کنید:

PROJECT_ID=$(gcloud config get-value project)

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

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

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

student@cloudshell:~ (gleb-test-short-004)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com
Operation "operations/acf.p2-404051529011-664c71ad-cb2b-4ab4-86c1-1f3157d70ba1" finished successfully.

۴. استقرار کلاستر AlloyDB

ایجاد کلاستر و نمونه اولیه AlloyDB. روش زیر نحوه ایجاد یک کلاستر و نمونه AlloyDB را با استفاده از Google Cloud SDK شرح می‌دهد. اگر رویکرد کنسول را ترجیح می‌دهید، می‌توانید مستندات اینجا را دنبال کنید.

قبل از ایجاد یک کلاستر 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

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

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 برای کلاستر ما در همان جلسه پوسته ابری ایجاد کنید. اگر اتصال شما قطع شد، باید متغیرهای محیطی منطقه و نام کلاستر را دوباره تعریف کنید.

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.

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 اعطا کنید

مجوزهای 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:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

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

exit

۵. آماده‌سازی ماشین مجازی GCE

ما قصد داریم از یک ماشین مجازی Google Compute Engine (GCE) به عنوان پلتفرم خود برای کار با پایگاه داده و استقرار بخش‌های مختلف برنامه نمونه استفاده کنیم. استفاده از یک ماشین مجازی به ما انعطاف‌پذیری بیشتری در اجزای نصب شده و دسترسی مستقیم به IP خصوصی AlloyDB برای مراحل آماده‌سازی داده‌ها می‌دهد.

ایجاد حساب کاربری سرویس

از آنجایی که ما از ماشین مجازی خود برای استقرار جعبه ابزار MCP به عنوان یک سرویس و استقرار یا میزبانی برنامه نمونه استفاده خواهیم کرد، اولین قدم ایجاد یک حساب سرویس گوگل (GSA) است. GSA توسط ماشین مجازی GCE استفاده خواهد شد و ما باید امتیازات لازم را برای کار با سایر سرویس‌ها به آن اعطا کنیم.

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

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create compute-aip --project $PROJECT_ID

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.admin

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

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

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

ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
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 \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com

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

student@cloudshell:~ (test-project-402417)$ ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
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 \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com
Your active configuration is: [cloudshell-10282]
Created [https://www.googleapis.com/compute/v1/projects/gleb-test-short-002-470613/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.28.55.32
STATUS: RUNNING

نصب کلاینت Postgres

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

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

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 5.10.0-26-cloud-amd64 #1 SMP Debian 5.10.197-1 (2023-09-29) 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 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
Get:4 file:/etc/apt/mirrors/debian-security.list Mirrorlist [39 B]
Hit:7 https://packages.cloud.google.com/apt google-compute-engine-bookworm-stable InRelease
Get:8 https://packages.cloud.google.com/apt cloud-sdk-bookworm InRelease [1652 B]
Get:2 https://deb.debian.org/debian bookworm InRelease [151 kB]
Get:3 https://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/15/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (15+248) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u7) ...

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

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

با استفاده از جلسه SSH باز شده به ماشین مجازی خود ادامه دهید. اگر اتصال شما قطع شده است، دوباره با استفاده از همان دستور بالا متصل شوید.

برای اتصال به AlloyDB از ماشین مجازی GCE، از متغیر $PGASSWORD که قبلاً ذکر شد و نام کلاستر استفاده کنید:

export PGPASSWORD=<Noted password>

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
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:~$ PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
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.13 (Debian 15.13-0+deb12u1), server 16.8)
WARNING: psql major version 15, server major version 16.
         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 با حفظ اتصال SSH:

exit

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

postgres=> exit
student@instance-1:~$

۶. مقداردهی اولیه پایگاه داده

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

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

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

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

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

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

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

آماده‌سازی محیط پایتون

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

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

sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

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

student@instance-1:~$ sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl
Suggested packages:
  git-daemon-run | git-daemon-sysvinit git-doc git-email git-gui gitk gitweb git-cvs git-mediawiki git-svn ed diffutils-doc
The following NEW packages will be installed:
  git git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl python3.11-venv
0 upgraded, 9 newly installed, 0 to remove and 2 not upgraded.
Need to get 12.4 MB of archives.
After this operation, 52.2 MB of additional disk space will be used.
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
...redacted...
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 23.0.1
    Uninstalling pip-23.0.1:
      Successfully uninstalled pip-23.0.1
Successfully installed pip-24.0
(.venv) student@instance-1:~$

نسخه پایتون را تأیید کنید.

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

python -V

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

(.venv) student@instance-1:~$ python -V
Python 3.11.2
(.venv) student@instance-1:~$

جعبه ابزار MCP را به صورت محلی نصب کنید

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

ما قصد داریم از جعبه ابزار MCP برای شروع مجموعه داده نمونه خود استفاده کنیم و بعداً از آن به عنوان سرور MCP برای مدیریت درخواست‌های منبع داده از برنامه خود در طول جریان بازیابی افزوده نسل (RAG) استفاده کنیم.

بیایید جعبه ابزار MCP را به صورت محلی نصب کنیم تا پایگاه داده assistantdemo را پر کنیم.

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

export VERSION=0.16.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

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

(.venv) student@instance-1:~$ export VERSION=0.16.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  133M  100  133M    0     0   158M      0 --:--:-- --:--:-- --:--:--  158M

اجرای جعبه ابزار برای مقداردهی اولیه داده‌ها

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

متغیرهای محیطی را برای جمعیت پایگاه داده صادر کنید:

export ALLOYDB_POSTGRES_PROJECT=$(gcloud config get-value project)
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"

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

./toolbox --prebuilt alloydb-postgres

خروجی مورد انتظار کنسول. شما باید در آخرین خط خروجی عبارت "Server ready to service!" را ببینید:

student@instance-1:~$ cexport ALLOYDB_POSTGRES_PROJECT=$PROJECT_ID
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"
student@instance-1:~$ ./toolbox --prebuilt alloydb-postgres
2025-09-02T18:30:58.957655886Z INFO "Using prebuilt tool configuration for alloydb-postgres" 
2025-09-02T18:30:59.507306664Z INFO "Initialized 1 sources." 
2025-09-02T18:30:59.50748379Z INFO "Initialized 0 authServices." 
2025-09-02T18:30:59.507618807Z INFO "Initialized 2 tools." 
2025-09-02T18:30:59.507726704Z INFO "Initialized 2 toolsets." 
2025-09-02T18:30:59.508258894Z INFO "Server ready to serve!"

تا زمانی که جمع‌آوری داده‌ها تکمیل نشده است، از این برگه Cloud Shell خارج نشوید یا آن را نبندید.

پایگاه داده را پر کنید

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

و به ماشین مجازی instance-1 متصل شوید:

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

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

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Linux instance-1 6.1.0-37-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.140-1 (2025-05-22) 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.
Last login: Tue Sep  2 21:44:07 2025 from 35.229.111.9
student@instance-1:~$

مخزن گیت‌هاب را به همراه کد سرویس بازیابی و برنامه نمونه، کلون کنید.

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

git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git

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

student@instance-1:~$ git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git
Cloning into 'cymbal-air-toolbox-demo'...
remote: Enumerating objects: 3481, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 3481 (delta 16), reused 7 (delta 5), pack-reused 3434 (from 3)
Receiving objects: 100% (3481/3481), 57.96 MiB | 6.04 MiB/s, done.
Resolving deltas: 100% (2549/2549), done.
student@instance-1:~

لطفا در صورت وجود هرگونه خطا، توجه فرمایید.

آماده‌سازی محیط پایتون و نصب بسته‌های مورد نیاز:

source .venv/bin/activate
cd cymbal-air-toolbox-demo
pip install -r requirements.txt

مسیر پایتون را روی پوشه ریشه مخزن تنظیم کنید و اسکریپت را برای پر کردن پایگاه داده با مجموعه داده نمونه اجرا کنید. دستور اول مسیری را برای ماژول‌های پایتون به محیط ما اضافه می‌کند و دستور دوم پایگاه داده ما را با داده‌ها پر می‌کند.

export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py

خروجی مورد انتظار کنسول (حذف شده). در انتها باید عبارت "database init done" را ببینید:

student@instance-1:~$ source .venv/bin/activate
(.venv) student@instance-1:~$ 
(.venv) student@instance-1:~$ cd cymbal-air-toolbox-demo/
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ pip install -r requirements.txt
python run_database_init.py
Collecting fastapi==0.115.0 (from -r requirements.txt (line 1))
  Downloading fastapi-0.115.0-py3-none-any.whl.metadata (27 kB)
Collecting google-auth==2.40.3 (from -r requirements.txt (line 2))
  Downloading google_auth-2.40.3-py2.py3-none-any.whl.metadata (6.2 kB)
Collecting google-cloud-aiplatform==1.97.0 (from google-cloud-aiplatform[evaluation]==1.97.0->-r requirements.txt (line 3))
  Downloading google_cloud_aiplatform-1.97.0-py2.py3-none-any.whl.metadata (36 kB)
Collecting itsdangerous==2.2.0 (from -r requirements.txt (line 4))
  Downloading itsdangerous-2.2.0-py3-none-any.whl.metadata (1.9 kB)
Collecting jinja2==3.1.5 (from -r requirements.txt (line 5))
  Downloading jinja2-3.1.5-py3-none-any.whl.metadata (2.6 kB)
Collecting langchain-community==0.3.25 (from -r requirements.txt (line 6))
  Downloading langchain_community-0.3.25-py3-none-any.whl.metadata (2.9 kB)
Collecting langchain==0.3.25 (from -r requirements.txt (line 7))
...

(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ 
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py
Airports table initialized
Amenities table initialized
Flights table initialized
Tickets table initialized
Policies table initialized
database init done.
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$

اکنون می‌توانید این تب را ببندید.

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

exit

و در جلسه Cloud Shell، کلیدهای ctrl+d را فشار دهید یا دستور زیر را اجرا کنید:

exit

در اولین تب با اجرای MCP Toolbox، برای خروج از جلسه اجرای جعبه ابزار، کلیدهای ctrl+c را فشار دهید.

پایگاه داده با داده‌های نمونه برای برنامه پر شده است.

می‌توانید با اتصال به پایگاه داده و بررسی تعداد ردیف‌های جدول airports، آن را تأیید کنید. می‌توانید از ابزار psql همانطور که قبلاً استفاده کردیم یا AlloyDB Studio استفاده کنید. در اینجا نحوه بررسی آن با استفاده از psql آمده است.

در جلسه ssh به ماشین مجازی instance-1 دستور زیر را اجرا کنید:

export PGPASSWORD=<Noted AlloyDB password>

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"

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

student@instance-1:~$ REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"
 count 
-------
  7698
(1 row)

پایگاه داده آماده است و می‌توانیم به سراغ استقرار جعبه ابزار MCP برویم.

۷. جعبه ابزار MCP را در Cloud Run مستقر کنید

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

آماده‌سازی شناسه مشتری

برای استفاده از قابلیت رزرو برنامه، باید شناسه کلاینت OAuth 2.0 را با استفاده از Cloud Console آماده کنیم. بدون آن نمی‌توانیم با اعتبارنامه‌های گوگل خود وارد برنامه شویم تا رزرو انجام دهیم و رزرو را در پایگاه داده ثبت کنیم.

در کنسول ابری، به بخش APIها و سرویس‌ها بروید و روی «صفحه رضایت OAuth» کلیک کنید. در اینجا لینکی به صفحه وجود دارد. این لینک ، صفحه نمای کلی Oauth را باز می‌کند که در آن روی «شروع به کار» کلیک می‌کنیم.

در صفحه بعد نام برنامه، ایمیل پشتیبانی کاربر را ارائه می‌دهیم و روی Next کلیک می‌کنیم.

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

سپس دوباره ایمیل مخاطب را ارائه می‌دهیم و روی Next کلیک می‌کنیم.

سپس ما با سیاست‌های خدمات API گوگل موافقت می‌کنیم و دکمه ایجاد را فشار می‌دهیم.

این ما را به صفحه‌ای هدایت می‌کند که می‌توانیم در آن یک کلاینت OAuth ایجاد کنیم.

در صفحه نمایش، از منوی کشویی «Web Application» را انتخاب می‌کنیم، «Cymbal Air» را به عنوان application قرار می‌دهیم و دکمه Add URI را فشار می‌دهیم.

URI ها منابع معتبری برای برنامه هستند و به جایی که سعی دارید از آن به برنامه دسترسی پیدا کنید بستگی دارند. ما "http://localhost:8081" را به عنوان URI مجاز و "http://localhost:8081/login/google" را به عنوان URI تغییر مسیر قرار می‌دهیم. این مقادیر در صورتی کار می‌کنند که در مرورگر خود "http://localhost:8081" را به عنوان URI برای اتصال وارد کنید. به عنوان مثال، وقتی از طریق یک تونل SSH از رایانه خود متصل می‌شوید. بعداً به شما نشان خواهم داد که چگونه این کار را انجام دهید.

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

بعداً خواهید دید که آن شناسه کلاینت را کجا ارائه می‌دهید.

ایجاد حساب کاربری سرویس

ما به یک حساب کاربری اختصاصی برای سرویس Cloud Run خود با تمام امتیازات لازم نیاز داریم. برای سرویس خود به دسترسی به AlloyDB و Cloud Secret Manager نیاز داریم. در مورد نام حساب کاربری سرویس، از toolbox-identity استفاده خواهیم کرد.

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

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

export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

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

با فشردن کلیدهای ctrl+d یا اجرای دستور "exit" در همان تب، تب را ببندید:

exit

آماده‌سازی پیکربندی جعبه ابزار MCP

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

رمز عبور AlloyDB را صادر کنید:

export PGPASSWORD=<noted AlloyDB password>

شناسه کلاینت را که در مرحله قبل آماده کردیم، صادر کنید:

export CLIENT_ID=<noted OAuth 2.0 client ID for our application>

فایل پیکربندی را آماده کنید.

PROJECT_ID=$(gcloud config get-value project)
ADBCLUSTER=alloydb-aip-01
sed -e "s/project: retrieval-app-testing/project: $(gcloud config get-value project)/g" \
-e "s/cluster: my-alloydb-cluster/cluster: $ADBCLUSTER/g" \
-e "s/instance: my-alloydb-instance/instance: $ADBCLUSTER-pr/g" \
-e "s/password: postgres/password: $PGPASSWORD\\n    ipType: private/g" \
-e "s/^ *clientId: .*/    clientId: $CLIENT_ID/g" \
cymbal-air-toolbox-demo/tools.yaml >~/tools.yaml

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

sources:
  my-pg-instance:
    kind: alloydb-postgres
    project: gleb-test-short-003-471020
    region: us-central1
    cluster: alloydb-aip-01
    instance: alloydb-aip-01-pr
    database: assistantdemo
    user: postgres
    password: L23F...
    ipType: private
authServices:
  my_google_service:
    kind: google
    clientId: 96828*******-***********.apps.googleusercontent.com

با استفاده از پیکربندی tools.yaml به عنوان منبع، یک راز ایجاد کنید.

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

gcloud secrets create tools --data-file=tools.yaml

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

student@instance-1:~$ gcloud secrets create tools --data-file=tools.yaml
Created version [1] of the secret [tools].

جعبه ابزار MCP را به عنوان یک سرویس ابری اجرا کنید

اکنون همه چیز برای استقرار جعبه ابزار MCP به عنوان یک سرویس در Cloud Run آماده است. برای آزمایش محلی می‌توانید "./toolbox –tools-file=./tools.yaml" را اجرا کنید، اما اگر می‌خواهیم برنامه ما در فضای ابری اجرا شود، استقرار در Cloud Run بسیار منطقی‌تر است.

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

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated

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

student@instance-1:~$ export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated
Deploying container to Cloud Run service [toolbox] in project [gleb-test-short-002-470613] region [us-central1]
✓ Deploying new service... Done.                                                                                                                                                                                                
  ✓ Creating Revision...                                                                                                                                                                                                        
  ✓ Routing traffic...                                                                                                                                                                                                          
Done.                                                                                                                                                                                                                           
Service [toolbox] revision [toolbox-00001-l9c] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-868691532292.us-central1.run.app

student@instance-1:~$

سرویس را تأیید کنید

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

می‌توانید مقدار را کپی کرده و در دستور curl بخش "$(gcloud run services list –filter="(toolbox)" –format="value(URL)"" را جایگزین کنید.

در اینجا نحوه دریافت URL به صورت پویا از خط فرمان آمده است:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

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

student@instance-1:~$ curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")
🧰 Hello, World! 🧰student@instance-1:~$

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

۸. پیاده‌سازی نمونه برنامه

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

این برنامه می‌تواند به صورت محلی، روی یک ماشین مجازی در فضای ابری یا هر سرویس دیگری مانند Cloud Run یا Kubernetes مستقر شود. در اینجا قصد داریم نحوه استقرار آن را ابتدا روی ماشین مجازی نشان دهیم.

محیط را آماده کنید

ما با استفاده از همان جلسه SSH به کار روی ماشین مجازی خود ادامه می‌دهیم. برای اجرای برنامه خود به برخی ماژول‌های پایتون نیاز داریم و قبلاً آنها را هنگام راه‌اندازی پایگاه داده خود اضافه کرده‌ایم. بیایید به محیط مجازی پایتون خود برویم و مکان خود را به دایرکتوری app تغییر دهیم.

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

source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo

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

student@instance-1:~$ source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$

اجرای برنامه دستیار

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

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

export TOOLBOX_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

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

student@instance-1:~/cymbal-air-toolbox-demo$ export BASE_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

برای استفاده از قابلیت‌های پیشرفته‌تر برنامه مانند رزرو و تغییر پرواز، باید با استفاده از حساب گوگل خود وارد برنامه شویم و برای این منظور باید متغیر محیطی CLIENT_ID را با استفاده از شناسه کلاینت OAuth از فصل Prepare Client ID ارائه دهیم:

export CLIENT_ID=215....apps.googleusercontent.com

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

student@instance-1:~/cymbal-air-toolbox-demo$ export CLIENT_ID=215....apps.googleusercontent.com

و حالا می‌توانیم برنامه‌ی خود را اجرا کنیم:

python run_app.py

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

student@instance-1:~/cymbal-air-toolbox-demo/llm_demo$ python run_app.py
INFO:     Started server process [2900]
INFO:     Waiting for application startup.
Loading application...
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

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

شما چندین راه برای اتصال به برنامه در حال اجرا روی ماشین مجازی دارید. به عنوان مثال می‌توانید با استفاده از قوانین فایروال در VPC، پورت ۸۰۸۱ را روی ماشین مجازی باز کنید یا یک متعادل‌کننده بار با IP عمومی ایجاد کنید. در اینجا ما قصد داریم از یک تونل SSH به ماشین مجازی استفاده کنیم که پورت محلی ۸۰۸۰ را به پورت ۸۰۸۱ ماشین مجازی ترجمه می‌کند.

اتصال از دستگاه محلی

وقتی می‌خواهیم از یک دستگاه محلی متصل شویم، باید یک تونل SSH اجرا کنیم. این کار را می‌توان با استفاده از gcloud compute ssh انجام داد:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8081:localhost:8081

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

student-macbookpro:~ student$ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
Warning: Permanently added 'compute.7064281075337367021' (ED25519) to the list of known hosts.
Linux instance-1.us-central1-c.c.gleb-test-001.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) 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:~$

حالا می‌توانیم مرورگر را باز کنیم و از http://localhost:8081 برای اتصال به برنامه خود استفاده کنیم. باید صفحه برنامه را ببینیم.

اتصال از طریق Cloud Shell

به عنوان یک روش جایگزین، می‌توانیم از Google Cloud Shell برای اتصال استفاده کنیم. با استفاده از علامت "+" در بالا، یک تب Cloud Shell دیگر باز کنید.

در برگه جدید، با اجرای دستور gcloud، آدرس مبدا و مسیر URL را برای کلاینت وب خود دریافت کنید:

echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"

خروجی مورد انتظار به شرح زیر است:

student@cloudshell:~ echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"
origin:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev
redirect:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev/login/google

و از مبدا و تغییر مسیر URI ها به عنوان " منشاهای مجاز جاوا اسکریپت " و "URI های تغییر مسیر مجاز " برای اعتبارنامه های ما که در فصل "آماده سازی شناسه مشتری" ایجاد شده اند، استفاده کنید و مقادیر http://localhost:8080 ارائه شده در ابتدا را جایگزین یا اضافه کنید.

در صفحه شناسه‌های کلاینت OAuth 2.0 روی «Cymbal Air» کلیک کنید.

آدرس‌های مبدا و تغییر مسیر را برای پوسته ابری وارد کنید و دکمه ذخیره را فشار دهید.

در تب new cloud shell، با اجرای دستور gcloud، تونل به ماشین مجازی خود را آغاز کنید:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081

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

خروجی مورد انتظار به شرح زیر است:

student@cloudshell:~ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
bind [::1]:8081: Cannot assign requested address
inux instance-1.us-central1-a.c.gleb-codelive-01.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) 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.
Last login: Sat May 25 19:15:46 2024 from 35.243.235.73
student@instance-1:~$

این پورت ۸۰۸۰ را روی پوسته ابری شما باز می‌کند که می‌تواند برای «پیش‌نمایش وب» استفاده شود.

روی دکمه‌ی «پیش‌نمایش وب» در سمت راست بالای Cloud Shell خود کلیک کنید و از منوی کشویی «پیش‌نمایش روی پورت ۸۰۸۰» را انتخاب کنید.

۴۴۴fbf54dcd4d160.png

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

وارد برنامه شوید

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

یک پنجره بازشو باز می‌شود که می‌توانیم اعتبارنامه‌های خود را انتخاب کنیم.

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

این نسخه آزمایشی، دستیار خدمات مشتری سیمبال ایر را به نمایش می‌گذارد. سیمبال ایر یک شرکت هواپیمایی مسافربری خیالی است. این دستیار یک چت‌بات هوش مصنوعی است که به مسافران کمک می‌کند تا پروازها را مدیریت کنند و اطلاعات مربوط به مرکز سیمبال ایر در فرودگاه بین‌المللی سانفرانسیسکو (SFO) را جستجو کنند.

بدون ورود به سیستم (بدون CLIENT_ID) می‌تواند به سوالات کاربران مانند موارد زیر پاسخ دهد:

پرواز بعدی به دنور چه زمانی است؟

آیا مغازه‌های لوکسی اطراف دروازه C28 وجود دارد؟

از کجا می‌توانم نزدیک گیت A6 قهوه تهیه کنم؟

از کجا می‌توانم هدیه بخرم؟

لطفا پروازی از SFO به دنور که امروز حرکت می‌کند را پیدا کنید.

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

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

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

حالا که همه کارها انجام شد، می‌توانیم محیط اطرافمان را تمیز کنیم.

سرویس Cloud Run را حذف کنید

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

gcloud run services delete toolbox --region us-central1

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

student@cloudshell:~ (gleb-test-short-004)$ gcloud run services delete retrieval-service --region us-central1
Service [retrieval-service] will be deleted.

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

Deleting [retrieval-service]...done.                                                                                                                                                                                                                 
Deleted service [retrieval-service].

حساب سرویس را برای سرویس ابری حذف کنید

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

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet

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

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-222]
student@cloudshell:~ (gleb-test-short-004)$ gcloud iam service-accounts delete retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet
deleted service account [retrieval-identity@gleb-test-short-004.iam.gserviceaccount.com]
student@cloudshell:~ (gleb-test-short-004)$

وقتی کار آزمایشگاهی‌تان تمام شد، نمونه‌ها و کلاستر 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

حساب کاربری سرویس (Service Account) مربوط به ماشین مجازی GCE و سرویس بازیابی (The Retrieval) را حذف کنید.

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

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet

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

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet
Your active configuration is: [cloudshell-222]
deleted service account [compute-aip@gleb-test-short-004.iam.gserviceaccount.com]
student@cloudshell:~ (gleb-test-short-004)$

۱۰. تبریک

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

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

نحوه استقرار کلاستر AlloyDB
نحوه اتصال به AlloyDB
نحوه پیکربندی و استقرار سرویس جعبه ابزار MCP
نحوه استقرار یک برنامه نمونه با استفاده از سرویس مستقر شده

۱۱. نظرسنجی

خروجی:

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

فقط آن را بخوانید

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