דף זה תורגם על ידי Cloud Translation API.

AlloyDB Agentic RAG Application with MCP Toolbox

1. מבוא

ב-codelab הזה תלמדו איך ליצור אשכול AlloyDB, לפרוס את ערכת הכלים MCP ולהגדיר אותה לשימוש ב-AlloyDB כמקור נתונים. לאחר מכן תיצרו אפליקציית RAG אינטראקטיבית לדוגמה שמשתמשת בארגז הכלים שנפרס כדי לבסס את הבקשות שלה.

מידע נוסף על ערכת הכלים של MCP זמין בדף התיעוד ובדוגמה של אפליקציית Cymbal Air כאן.

ה-Lab הזה הוא חלק מאוסף של Labs שמוקדשים לתכונות של AlloyDB AI. אפשר לקרוא מידע נוסף בדף AlloyDB AI בתיעוד ולראות ניסויים נוספים.

דרישות מוקדמות

הבנה בסיסית של מסוף Google Cloud
מיומנויות בסיסיות בממשק שורת הפקודה וב-Cloud Shell של Google Cloud

מה תלמדו

איך פורסים אשכול AlloyDB עם שילוב של Vertex AI
איך מתחברים ל-AlloyDB
איך מגדירים ופורסים את MCP Tooolbox Service
איך פורסים אפליקציה לדוגמה באמצעות השירות שנפרס

מה צריך

חשבון Google Cloud ופרויקט Google Cloud
דפדפן אינטרנט כמו Chrome

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

נכנסים ל-Google Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, אתם צריכים ליצור חשבון.

שם הפרויקט הוא השם המוצג של המשתתפים בפרויקט הזה. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את הערך הזה אחרי השלב הזה, והוא יישאר כזה למשך הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

הפעלת Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-Google Cloud Console, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הפעלת Cloud Shell

יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:

צילום מסך של טרמינל Google Cloud Shell שבו מוצג שהסביבה מחוברת

המכונה הווירטואלית הזו כוללת את כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.

3. לפני שמתחילים

הפעלת ה-API

פלט:

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

אנחנו נשתמש במכונה וירטואלית (VM) של Google Compute Engine (GCE) כפלטפורמה שלנו כדי לעבוד עם מסד הנתונים ולפרוס חלקים שונים של האפליקציה לדוגמה. שימוש במכונה וירטואלית מאפשר לנו גמישות רבה יותר ברכיבים המותקנים וגישה ישירה לכתובת ה-IP הפרטית של AlloyDB לצורך שלבי הכנת הנתונים.

יצירת חשבון שירות

מכיוון שנשתמש במכונה הווירטואלית כדי לפרוס את MCP Toolbox כשירות ולפרוס או לארח את האפליקציה לדוגמה, השלב הראשון הוא ליצור חשבון שירות של Google ‏ (GSA). מכונת ה-VM של GCE תשתמש ב-GSA, ולכן נצטרך להעניק לה את ההרשאות הנדרשות כדי לעבוד עם שירותים אחרים.

ב-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 במכונה הווירטואלית שנפרסה

מתחברים ל-VM:

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

מריצים את פקודת התוכנה בתוך ה-VM:

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 הפתוח למכונה הווירטואלית. אם החיבור נותק, צריך להתחבר שוב באמצעות אותה הפקודה שצוינה למעלה.

משתמשים ב-$PGPASSWORD שצוין קודם ובשם האשכול כדי להתחבר ל-AlloyDB ממכונת GCE VM:

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 Toolbox

ערכת הכלים של 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

הפעלת 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 באמצעות הסימן '+' בחלק העליון.

מתחברים ל-VM‏ 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$

עכשיו אפשר לסגור את הכרטיסייה הזו.

בסשן של מכונת ה-VM, מריצים את הפקודה:

exit

בסשן של Cloud Shell, מקישים על Ctrl+d או מריצים את הפקודה :

exit

בכרטיסייה הראשונה שבה פועל MCP Toolbox, מקישים על Ctrl+c כדי לצאת מהסשן הפעיל של ערכת הכלים.

מסד הנתונים אוכלס בנתונים לדוגמה של האפליקציה.

כדי לוודא זאת, אפשר להתחבר למסד הנתונים ולבדוק את מספר השורות בטבלת שדות התעופה. אתם יכולים להשתמש בכלי השירות psql כמו שהשתמשנו בו קודם, או ב-AlloyDB Studio . כך אפשר לבדוק את זה באמצעות psql

בסשן ה-SSH למכונת VM‏ 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. פריסת ערכת הכלים של MCP ב-Cloud Run

עכשיו אפשר לפרוס את MCP Toolbox ב-Cloud Run. יש כמה דרכים לפרוס את ערכת הכלים של MCP. הדרך הכי פשוטה היא להריץ אותו משורת הפקודה, אבל אם רוצים שהוא יהיה שירות מהימן וניתן להרחבה, Cloud Run הוא פתרון טוב יותר.

הכנת מזהה הלקוח

כדי להשתמש בפונקציונליות של הזמנות באפליקציה, צריך להכין מזהה לקוח OAuth 2.0 באמצעות מסוף Cloud. בלי הרשאה כזו, לא נוכל להיכנס לאפליקציה עם פרטי הכניסה שלנו לחשבון Google כדי לבצע הזמנה ולתעד אותה במסד הנתונים.

במסוף Cloud, עוברים אל APIs and Services (ממשקי API ושירותים) ולוחצים על OAuth consent screen (מסך ההסכמה ל-OAuth). כאן יש קישור לדף. ייפתח דף הסקירה הכללית של Oauth, שבו לוחצים על 'תחילת העבודה'.

בדף הבא מופיעים שם האפליקציה וכתובת האימייל לתמיכה במשתמשים. לוחצים על 'הבא'.

במסך הבא בוחרים באפשרות Internal (פנימי) לאפליקציה ולוחצים שוב על Next (הבא).

לאחר מכן מזינים שוב את כתובת האימייל ליצירת קשר ולוחצים על 'הבא'.

לאחר מכן מאשרים את המדיניות של Google בנושא שירותי API ולוחצים על הלחצן 'יצירה'.

הקישור יוביל אותנו לדף שבו אפשר ליצור לקוח OAuth.

במסך בוחרים באפשרות 'אפליקציית אינטרנט' מהתפריט הנפתח, מזינים 'Cymbal Air' כאפליקציה ולוחצים על הלחצן 'הוספת 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"

חשוב לשים לב אם יש שגיאות. הפקודה אמורה ליצור חשבון שירות בשביל שירות Cloud Run ולהעניק הרשאות לעבודה עם Secret Manager, מסד נתונים ו-Vertex AI.

סוגרים את הכרטיסייה על ידי הקשה על Ctrl+D או על ידי הפעלת הפקודה exit בכרטיסייה:

exit

הכנת ההגדרה של MCP Toolbox

מכינים קובץ תצורה עבור 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.

אפשר להעתיק את הערך ולהחליף בפקודת ה-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:~$

אם אנחנו רואים את ההודעה 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$

הפעלת אפליקציית Assistant

לפני שמפעילים את האפליקציה, צריך להגדיר כמה משתני סביבה. הפונקציונליות הבסיסית של האפליקציה, כמו חיפוש טיסות ומתקנים בשדה התעופה, דורשת רק את 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 שסופקו במקור או להוסיף להם ערכים.

בדף 'מזהי לקוחות ב-OAuth 2.0', לוחצים על Cymbal Air.

מזינים את ה-URI של המקור ואת ה-URI של ההפניה האוטומטית ל-Cloud Shell ולוחצים על הלחצן Save (שמירה).

בכרטיסייה החדשה של 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 Customer Service Assistant'.

כניסה לאפליקציה

אחרי שמסיימים את ההגדרה ופותחים את האפליקציה, אפשר להשתמש בלחצן 'כניסה' שבפינה השמאלית העליונה של מסך האפליקציה כדי להזין את פרטי הכניסה. הפעולה הזו היא אופציונלית ונדרשת רק אם רוצים לנסות את פונקציית ההזמנה של האפליקציה.

ייפתח חלון קופץ שבו אפשר לבחור את פרטי הכניסה.

אחרי הכניסה לחשבון, האפליקציה מוכנה ואפשר להתחיל לפרסם את הבקשות בשדה בחלק התחתון של החלון.

ההדגמה הזו מציגה את העוזר לשירות לקוחות של Cymbal Air. Cymbal Air היא חברת תעופה פיקטיבית. העוזר הוא צ'אטבוט מבוסס-AI שעוזר לנוסעים לנהל את הטיסות שלהם ולחפש מידע על מרכז הפעילות של חברת התעופה Cymbal Air בנמל התעופה הבינלאומי של סן פרנסיסקו (SFO).

בלי להיכנס לחשבון (בלי CLIENT_ID), הוא יכול לעזור לענות על שאלות של משתמשים כמו:

מתי הטיסה הבאה לדנוור?

יש חנויות יוקרה ליד שער C28?

איפה אפשר לקנות קפה ליד שער A6?

איפה אפשר לקנות מתנה?

תמצא לי טיסה מ-SFO לדנוור שיוצאת היום

כשנכנסים לאפליקציה, אפשר לנסות יכולות אחרות כמו הזמנת טיסות או בדיקה אם המושב שהוקצה לכם הוא מושב ליד החלון או המעבר.

האפליקציה משתמשת במודלים העדכניים ביותר של 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)$

בסיום שיעור ה-Lab, צריך להשמיד את המכונות ואת האשכול של 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. מזל טוב

כל הכבוד, סיימתם את ה-Codelab.

מה למדנו

איך פורסים אשכול AlloyDB
איך מתחברים ל-AlloyDB
איך מגדירים ופורסים את MCP Toolbox Service
איך פורסים אפליקציה לדוגמה באמצעות השירות שנפרס

11. סקר

פלט:

איך תשתמשו במדריך הזה?

רק קוראים את הטקסט

קוראים את הטקסט ומבצעים את התרגילים