تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تطبيق AlloyDB Agentic RAG مع مجموعة أدوات MCP

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، سنتطرّق إلى كيفية إنشاء مجموعة AlloyDB، ونشر مجموعة أدوات MCP، وإعدادها لاستخدام AlloyDB كمصدر بيانات. بعد ذلك، ستنشئ نموذجًا لتطبيق تفاعلي من نوع "التوليد المعزّز بالاسترجاع" يستخدم مجموعة الأدوات التي تم نشرها لتحديد مصدر طلباته.

يمكنك الحصول على مزيد من المعلومات حول "مجموعة أدوات MCP" في صفحة المستندات وعن نموذج تطبيق Cymbal Air هنا.

يشكّل هذا المختبر جزءًا من مجموعة مختبرات مخصّصة لميزات AlloyDB AI. يمكنك الاطّلاع على مزيد من المعلومات في صفحة AlloyDB AI ضمن المستندات، والاطّلاع على مختبرات أخرى.

المتطلبات الأساسية

فهم أساسي لـ Google Cloud Console
مهارات أساسية في واجهة سطر الأوامر وCloud Shell من Google

ما ستتعلمه

كيفية نشر مجموعة AlloyDB مع دمج Vertex AI
كيفية الاتصال بـ AlloyDB
كيفية إعداد خدمة MCP Tooolbox ونشرها
كيفية نشر تطبيق نموذجي باستخدام الخدمة المنشورة

المتطلبات

حساب Google Cloud ومشروع Google Cloud
متصفّح ويب، مثل Chrome

2. الإعداد والمتطلبات

إعداد البيئة بالسرعة التي تناسبك

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
معرّف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس البرمجي الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تكبُّد رسوم فوترة تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن للمستخدمين الجدد في Google Cloud الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس العملي Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

تفعيل Cloud Shell

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

لقطة شاشة لواجهة سطر الأوامر في Google Cloud Shell توضّح أنّه تم ربط البيئة

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا ثابتًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. ليس عليك تثبيت أي تطبيق.

3- قبل البدء

تفعيل واجهة برمجة التطبيقات

إخراج:

داخل Cloud Shell، تأكَّد من إعداد رقم تعريف مشروعك:

يظهر عادةً رقم تعريف المشروع بين قوسين في موجّه الأوامر في 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.

4. نشر مجموعة AlloyDB

أنشئ مجموعة AlloyDB ومثيلًا أساسيًا. يوضّح الإجراء التالي كيفية إنشاء مجموعة ومثيل AlloyDB باستخدام Google Cloud SDK. إذا كنت تفضّل استخدام وحدة التحكّم، يمكنك اتّباع التعليمات الواردة في المستندات هنا.

قبل إنشاء مجموعة AlloyDB، نحتاج إلى نطاق عناوين IP خاصة متاح في شبكة السحابة الافتراضية الخاصة (VPC) لاستخدامه في مثيل AlloyDB المستقبلي. إذا لم يكن لدينا، علينا إنشاؤه وتعيينه ليتم استخدامه من قِبل خدمات Google الداخلية، وبعد ذلك سنتمكّن من إنشاء المجموعة والمثيل.

إنشاء نطاق عناوين IP خاص

علينا ضبط إعدادات ميزة "الوصول إلى الخدمات الخاصة" في شبكة 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 لمجموعتك في جلسة Cloud Shell نفسها. في حال انقطاع الاتصال، عليك تحديد متغيرات بيئة اسم المنطقة واسم المجموعة مرة أخرى.

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 Standard

إذا لم تكن هذه هي مجموعة 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

5- إعداد جهاز GCE الافتراضي

سنستخدم جهازًا افتراضيًا على Google Compute Engine (GCE) كمنصتنا للعمل مع قاعدة البيانات ونشر أجزاء مختلفة من التطبيق النموذجي. يمنحنا استخدام الآلة الافتراضية مرونة أكبر في المكوّنات المثبَّتة وإمكانية الوصول المباشر إلى عنوان IP الخاص بـ AlloyDB لتنفيذ خطوات إعداد البيانات.

إنشاء حساب خدمة

بما أنّنا سنستخدم جهازنا الظاهري لنشر MCP Toolbox كخدمة ونشر التطبيق النموذجي أو استضافته، فإنّ الخطوة الأولى هي إنشاء حساب خدمة Google (GSA). سيتم استخدام حساب الخدمة على Google (GSA) من خلال الجهاز الافتراضي على Google Compute Engine (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 Client

تثبيت برنامج عميل 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 المفتوحة إلى جهازك الظاهري. إذا تم قطع الاتصال، أعِد الاتصال باستخدام الأمر نفسه المذكور أعلاه.

استخدِم $PGASSWORD واسم المجموعة اللذين دوّنتهما سابقًا للاتصال بـ AlloyDB من الجهاز الافتراضي على GCE:

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

6. تهيئة قاعدة البيانات

سنستخدم الجهاز الظاهري للعميل كمنصة لتعبئة قاعدة البيانات بالبيانات واستضافة تطبيقنا. تتمثل الخطوة الأولى في إنشاء قاعدة بيانات وملؤها بالبيانات.

إنشاء قاعدة بيانات

أنشئ قاعدة بيانات باسم "assistantdemo".

في جلسة الجهاز الافتراضي على GCE، نفِّذ ما يلي:

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

إعداد بيئة Python

للمتابعة، سنستخدم نصوص Python البرمجية المُعدّة من مستودع GitHub، ولكن قبل ذلك، علينا تثبيت البرنامج المطلوب.

في جهاز 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:~$

تحقَّق من إصدار Python.

في جهاز GCE الافتراضي، نفِّذ ما يلي:

python -V

الناتج المتوقّع في وحدة التحكّم:

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

تثبيت "مجموعة أدوات MCP" على الجهاز

‫MCP Toolbox for Databases (يُشار إليها لاحقًا في النص باسم MCP toolbox أو toolbox) هي خادم 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

تشغيل أداة Toolbox لتهيئة البيانات

في جهاز 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"

ابدأ استخدام مجموعة الأدوات لبدء قاعدة البيانات. ستبدأ العملية محليًا، ما سيساعدك في الاتصال بسلاسة بقاعدة البيانات الوجهة على AlloyDB لملئها ببيانات نموذجية.

./toolbox --prebuilt alloydb-postgres

الناتج المتوقّع في وحدة التحكّم من المفترض أن يظهر لك في السطر الأخير من الناتج "الخادم جاهز للعمل":

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

استنسِخ مستودع GitHub الذي يتضمّن الرمز البرمجي لخدمة الاسترجاع والتطبيق النموذجي.

في جهاز 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:~

يُرجى الانتباه إذا ظهرت لك أي أخطاء.

إعداد بيئة Python وتثبيت حِزم المتطلبات:

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

اضبط مسار Python على مجلد الجذر للمستودع وشغِّل البرنامج النصي لتعبئة قاعدة البيانات بمجموعة البيانات النموذجية. يتمثل الأمر الأول في إضافة مسار إلى وحدات Python النمطية في بيئتنا، ويتمثل الأمر الثاني في ملء قاعدة البيانات بالبيانات.

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 للخروج من جلسة تشغيل مجموعة الأدوات.

تمت تعبئة قاعدة البيانات ببيانات نموذجية للتطبيق.

يمكنك التأكّد من ذلك من خلال الاتصال بقاعدة البيانات والتحقّق من عدد الصفوف في جدول المطارات. يمكنك استخدام أداة 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 Toolbox.

7. نشر "مجموعة أدوات إدارة العملاء المتعددين" على Cloud Run

يمكننا الآن نشر MCP Toolbox على Cloud Run. تتوفّر طرق مختلفة لنشر مجموعة أدوات MCP. أبسط طريقة هي تشغيلها من سطر الأوامر، ولكن إذا أردنا أن تكون خدمة قابلة للتوسيع وموثوقة، فإنّ Cloud Run هو الحلّ الأفضل.

إعداد معرّف العميل

لاستخدام وظيفة الحجز في التطبيق، علينا إعداد معرّف عميل OAuth 2.0 باستخدام Cloud Console. وبدونها، لا يمكننا تسجيل الدخول إلى التطبيق باستخدام بيانات اعتماد Google لإجراء حجز وتسجيله في قاعدة البيانات.

في Cloud Console، انتقِل إلى "واجهات برمجة التطبيقات والخدمات" (APIs and Services) وانقر على "شاشة موافقة OAuth" (OAuth consent screen). إليك رابط يؤدي إلى الصفحة. سيتم فتح صفحة "نظرة عامة على OAuth" حيث ننقر على "البدء".

في الصفحة التالية، نقدّم اسم التطبيق وعنوان البريد الإلكتروني المخصّص لدعم المستخدمين، ثم ننقر على "التالي".

في الشاشة التالية، نختار "داخلي" لتطبيقنا وننقر على "التالي" مرة أخرى.

ثم نقدّم مرة أخرى عنوان البريد الإلكتروني المخصّص للتواصل وننقر على "التالي".

بعد ذلك، نوافق على سياسات خدمات Google API ونضغط على الزر "إنشاء".

سيؤدي ذلك إلى الانتقال إلى الصفحة التي يمكننا فيها إنشاء عميل OAuth.

في الشاشة، نختار "تطبيق ويب" من القائمة المنسدلة، ونكتب "Cymbal Air" كتطبيق، ثم نضغط على زر "إضافة معرّف الموارد المنتظم (URI)".

تمثّل عناوين URI مصادر موثوقة للتطبيق، وتعتمد على المكان الذي تحاول الوصول إلى التطبيق منه. أدخلنا "http://localhost:8081" كمعرّف موارد منتظم (URI) معتمَد و "http://localhost:8081/login/google" كمعرّف موارد منتظم (URI) لإعادة التوجيه. ستعمل هذه القيم إذا أدخلت في المتصفّح "http://localhost:8081" كمعرّف موارد منتظم للاتصال. على سبيل المثال، عند الاتصال من خلال نفق 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"

يُرجى الانتباه إذا ظهرت لك أي أخطاء. من المفترض أن ينشئ الأمر حساب خدمة لخدمة Cloud Run ويمنح أذونات للعمل مع Secret Manager وقاعدة البيانات وVertex AI.

أغلِق علامة التبويب إما بالضغط على ctrl+d أو بتنفيذ الأمر "exit" في علامة التبويب:

exit

إعداد "مجموعة أدوات إدارة الشركاء المتعدّدين"

إعداد ملف الضبط لأداة MCP Toolbox يمكنك الاطّلاع على جميع خيارات الإعداد في المستندات، ولكننا سنستخدم هنا ملف 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 Toolbox كخدمة Cloud Run

أصبح كل شيء جاهزًا الآن لنشر MCP Toolbox كخدمة على 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) للخدمة في Cloud Console.

يمكنك نسخ القيمة واستبدال الجزء "$(gcloud run services list –filter="(toolbox)" –format="value(URL)" في أمر curl .

في ما يلي كيفية الحصول على عنوان 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:~$

إذا ظهرت الرسالة "Hello World"، يعني ذلك أنّ خدمتنا تعمل وتستجيب للطلبات.

8. نشر نموذج التطبيق

الآن، بعد أن أصبحت خدمة الاسترجاع جاهزة للعمل، يمكننا نشر نموذج تطبيق. يمثّل التطبيق مساعدًا في المطار على الإنترنت يمكنه تقديم معلومات عن الرحلات الجوية والمطارات، ويمكنه حتى حجز رحلة جوية استنادًا إلى بيانات الرحلات الجوية والمطارات من قاعدة البيانات الخاصة بنا.

يمكن نشر التطبيق محليًا أو على جهاز افتراضي في السحابة الإلكترونية أو أي خدمة أخرى، مثل Cloud Run أو Kubernetes. سنوضّح هنا كيفية نشرها على الجهاز الظاهري أولاً.

إعداد البيئة

نواصل العمل على الجهاز الظاهري باستخدام جلسة SSH نفسها. لتشغيل تطبيقنا، نحتاج إلى بعض وحدات Python، وقد أضفناها بالفعل عند بدء قاعدة البيانات في وقت سابق. لننتقل إلى بيئة Python الافتراضية ونغيّر موقعنا الجغرافي إلى دليل التطبيق.

في جلسة 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$

تشغيل تطبيق "مساعد Google"

قبل بدء التطبيق، علينا إعداد بعض متغيّرات البيئة. لا تتطلّب الوظيفة الأساسية للتطبيق، مثل البحث عن رحلات جوية ووسائل الراحة في المطار، سوى 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)")

لاستخدام إمكانات أكثر تقدّمًا في التطبيق، مثل حجز الرحلات الجوية وتغييرها، علينا تسجيل الدخول إلى التطبيق باستخدام حساب Google، ولهذا الغرض، علينا تقديم متغيّر بيئة CLIENT_ID باستخدام معرّف عميل OAuth من قسم "إعداد معرّف العميل":

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)

الربط بالتطبيق

تتوفّر عدة طرق للاتصال بالتطبيق الذي يتم تشغيله على الجهاز الافتراضي. على سبيل المثال، يمكنك فتح المنفذ 8081 على الجهاز الظاهري باستخدام قواعد جدار الحماية في شبكة VPC أو إنشاء موازن تحميل باستخدام عنوان IP عام. سنستخدم هنا نفق SSH للجهاز الظاهري من خلال ترجمة المنفذ المحلي 8080 إلى منفذ الجهاز الظاهري 8081.

الاتصال من جهاز محلي

عندما نريد الاتصال من جهاز محلي، علينا تشغيل نفق 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 باستخدام علامة "+" في أعلى الصفحة.

في علامة التبويب الجديدة، احصل على المصدر ومعرّف الموارد المنتظم (URI) لإعادة التوجيه لعميل الويب الذي ينفّذ أمر gcloud:

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) كـ مصادر JavaScript المسموح بها ومعرّفات الموارد المنتظمة (URI) المسموح بها لإعادة التوجيه لبيانات الاعتماد التي تم إنشاؤها في فصل "إعداد معرّف العميل"، وذلك من خلال استبدال القيم http://localhost:8080 التي تم تقديمها في الأصل أو إضافتها.

انقر على "Cymbal Air" في صفحة "معرّفات العميل لبروتوكول OAuth 2.0".

أدخِل معرّفات الموارد المنتظمة (URI) الخاصة بالمصدر وإعادة التوجيه في Cloud Shell، ثم انقر على الزر "حفظ".

في علامة التبويب الجديدة الخاصة بـ 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:~$

يفتح هذا الأمر المنفذ 8080 على Cloud Shell الذي يمكن استخدامه في "معاينة الويب".

انقر على الزر "معاينة الويب" في أعلى يسار Cloud Shell، ثم اختَر "المعاينة على المنفذ 8080" من القائمة المنسدلة.

يتم فتح علامة تبويب جديدة في متصفّح الويب تتضمّن واجهة التطبيق. من المفترض أن تظهر لك صفحة "مساعد خدمة العملاء في Cymbal Air".

تسجيل الدخول إلى التطبيق

بعد إعداد كل شيء وفتح التطبيق، يمكننا استخدام الزر "تسجيل الدخول" في أعلى يسار شاشة التطبيق لتقديم بيانات الاعتماد. هذا الإجراء اختياري ويجب اتّخاذه فقط إذا كنت تريد تجربة وظيفة الحجز في التطبيق.

سيتم فتح نافذة منبثقة حيث يمكننا اختيار بيانات الاعتماد.

بعد تسجيل الدخول، يصبح التطبيق جاهزًا ويمكنك البدء في نشر طلباتك في الحقل أسفل النافذة.

يعرض هذا العرض التوضيحي مساعد خدمة العملاء من Cymbal Air. ‫Cymbal Air هي شركة طيران خيالية لنقل الركاب. المساعد هو برنامج دردشة آلي مستند إلى الذكاء الاصطناعي يساعد المسافرين في إدارة رحلاتهم الجوية والبحث عن معلومات حول مركز شركة Cymbal Air في مطار سان فرانسيسكو الدولي (SFO).

بدون تسجيل الدخول (بدون CLIENT_ID)، يمكن أن يساعد في الإجابة عن أسئلة المستخدمين، مثل:

متى موعد الرحلة الجوية التالية إلى دنفر؟

هل هناك أي متاجر فاخرة بالقرب من البوابة C28؟

أين يمكنني الحصول على قهوة بالقرب من البوابة A6؟

أين يمكنني شراء هدية؟

أريد العثور على رحلة جوية من سان فرانسيسكو إلى دنفر تغادر اليوم

عند تسجيل الدخول إلى التطبيق، يمكنك تجربة إمكانات أخرى، مثل حجز رحلات جوية أو التحقّق مما إذا كان المقعد المخصّص لك بجانب النافذة أو الممر.

يستخدم التطبيق أحدث نماذج Google الأساسية لإنشاء الردود وتعزيزها بمعلومات عن الرحلات الجوية ووسائل الراحة من قاعدة بيانات AlloyDB التشغيلية. يمكنك الاطّلاع على مزيد من المعلومات حول هذا التطبيق التجريبي في صفحة Github الخاصة بالمشروع.

9- تنظيف البيئة

الآن، بعد إكمال جميع المهام، يمكننا تنظيف بيئتنا

حذف خدمة 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 Run

في 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 الذي يؤدي أيضًا إلى حذف جميع المثيلات التابعة للمجموعة.

في Cloud Shell، حدِّد متغيرات المشروع والبيئة إذا تم قطع الاتصال وفقدت جميع الإعدادات السابقة:

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

حذف حساب الخدمة الخاص بالجهاز الافتراضي على GCE وخدمة الاسترداد

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

10. تهانينا

تهانينا على إكمال هذا الدرس العملي.

المواضيع التي تناولناها

كيفية نشر مجموعة AlloyDB
كيفية الاتصال بـ AlloyDB
كيفية إعداد خدمة MCP Toolbox ونشرها
كيفية نشر تطبيق نموذجي باستخدام الخدمة المنشورة

11. استطلاع

إخراج:

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط

قراءة المحتوى وإكمال التمارين