Build an Intelligent Ecommerce Catalog with Multi-database Persistence

1. מבוא

בעולם הקמעונאות המודרני, הנתונים שלכם הם סביבה עסקית מגוונת ורחבה. יש לכם נתוני עסקאות יציבים (תמחור ומלאי), קטלוגים פולימורפיים "מבולגנים" (מפרטים של מוצרי אלקטרוניקה לעומת מידות של בגדים) ויומני התנהגות בנפח של פטה-בייטים. אם תנסו לדחוס את כל אלה למערכת אחת, לא רק שתצברו חוב טכני, אלא גם תפגעו בחוויית המשתמש.

ב-Codelab הזה תלמדו איך ליצור מערכת Polyglot שמשלבת בין:

  • ‫AlloyDB: עמוד השדרה של הטרנזקציות, שמאפשר עקביות במהירות גבוהה והטמעות של תמונות.
  • ‫MongoDB Atlas ב-Google Cloud: שכבת הקטלוג הגמישה, שלא תלויה בסכימה.
  • ‫Cloud Storage: המוח האנליטי שלכם לחיזוי מגמות בזמן אמת.
  • BigQuery: מחסן דיגיטלי ברזולוציה גבוהה.

מהו "הרוטב הסודי"? תשתמשו ב-MCP Toolbox for Databases כדי לתזמר ולאחד בצורה חכמה את מקורות הנתונים שפועלים ב-Cloud Run כגשר סמנטי, ואז תפרסו אפליקציית צ'אט עם כמה סוכנים באמצעות ערכה לפיתוח סוכנים (ADK). אתם לא רק בונים סרגל חיפוש, אתם בונים מוח קמעונאי חכם שמבין את ההקשר, מכבד את המגבלות ומגשר על הפער בין נתונים גולמיים לבין כוונת המשתמש.

שאילתת המשתמש הבלתי אפשרית

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

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

למה השאילתה הזו היא "הסיוט של הסוכנים":

  • דמיון חזותי (AlloyDB + חיפוש וקטורי): כדי לענות על שאלה כמו "נעליים בסגנון דומה ל-AeroGlow Pro", צריך להשוות בין הטמעות של תמונות.
  • אילוץ שלילי (MongoDB): כדי למצוא מוצרים "בלי עור", צריך לסנן לפי מאפיינים גמישים ומקוננים שבדרך כלל לא קיימים בסכימת SQL סטנדרטי.
  • מלאי בזמן אמת (AlloyDB): כדי לדעת אם מוצר באמת נמצא במלאי, צריך לבצע בדיקה של העסקאות בזמן אמת (ולא להסתמך על אינדקס חיפוש מיושן).
  • סינתזה סמנטית (BigQuery + כמה סוכנים): כדי לנתח ביקורות בנושא "עמידות הרצועה", הסוכן צריך לסכם בזמן אמת משוב לא מובנה מ-BigQuery.

רוב הבוטים של קמעונאים יזהו רק את המילים "תרמיל" ו"עור" ויציגו 10 תרמילי עור. איך אנחנו מונעים את זה?

כי אנחנו לא רק מתאימים מילות מפתח. אנחנו משתמשים ב-MCP Toolbox כדי לאפשר לנציגים שלנו "להסיק מסקנות" מכל המקורות האלה – המידע האמין על העסקאות ב-AlloyDB והמאפיינים הגמישים ב-MongoDB – בו-זמנית. שנתחיל לבנות?

הפעולות שתבצעו:

  • הקצאת אשכול AlloyDB לנתוני המוצרים העיקריים
  • הגדרת MongoDB Atlas ב-Google Cloud לאחסון פרטי מוצר חצי-מובנים
  • יוצרים קטגוריה של Cloud Storage כדי להציג תמונות של מוצרים.
  • פורסים את MCP Toolbox for Databases ב-Cloud Run כדי לקבל גישה אחידה לנתונים.
  • להריץ תהליכי ETL כדי להעביר נתונים ל-BigQuery לצורך ניתוח
  • לשוחח עם סוכן AI בשפה טבעית.

ארכיטקטורה של מסדי נתונים מרובים למסחר אלקטרוני

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

‫2. לפני שמתחילים

יצירת פרויקט בענן של Google

  1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט קיים או יוצרים פרויקט חדש.
  2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud, וכוללת כלים נחוצים שנטענים מראש.

  1. לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
  2. אחרי שמתחברים ל-Cloud Shell, מאמתים את הזהות:
    gcloud auth list
  3. מוודאים שהפרויקט מוגדר:
    gcloud config get project
  4. אם הפרויקט לא מוגדר כמו שצריך, מגדירים אותו:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

הגדרת משתנים

ב-Cloud Shell, מגדירים משתני סביבה למזהה הפרויקט ולמספר הפרויקט:

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

הפעלת ממשקי ה-API הנדרשים

מריצים את הפקודה הבאה כדי להפעיל את כל ממשקי ה-API הנדרשים:

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

3. הגדרת Cloud Storage

‫Cloud Storage משמש כמאגר עצום לנכסי מדיה לא מובְנים, כמו תמונות של מוצרים.

  1. במסוף Google Cloud, נכנסים ל-Cloud Storage ולוחצים על Create bucket.
  2. נותנים לקטגוריה שם ייחודי באופן גלובלי, לדוגמה -ecommerce-images.
  3. לוחצים על יצירה.
  4. כדי לאפשר לאפליקציית ההדגמה לגשת לתמונות בלי אימות, מבטלים את הסימון של האפשרות Enforce public access prevention on this bucket ולוחצים על Confirm.
  5. עוברים לכרטיסייה Permissions.
  6. בקטע הרשאות, לוחצים על מתן גישה.
  7. בשדה New principals, מזינים allUsers.
  8. בשדה Select a role, בוחרים באפשרות Cloud Storage > Storage Object Viewer.
  9. לוחצים על Save ואז על Allow Public Access כדי לאשר שהמשאב יהיה גלוי לכולם.
  10. ב-Cloud Shell, שומרים את שם הקטגוריה במשתנה:
    export BUCKET=<your-bucket-name>
    מחליפים את בשם הקטגוריה שיצרתם.

העלאת תמונות לדוגמה

הפרויקט משתמש בתמונות לדוגמה כדי לספק את החוויה החזותית הטובה ביותר.

  1. משכפלים את המאגר ב-Cloud Shell:
    git clone https://github.com/AbiramiSukumaran/polyglot-persist-ecommerce.git
  2. עוברים לתיקייה UploadImages:
    cd polyglot-persist-ecommerce/UploadImages
  3. מעלים את התמונות לדוגמה לקטגוריה:
    gcloud storage cp *.jpg gs://$BUCKET/

4. הגדרת AlloyDB

‫AlloyDB משמש כמקור האמת היחיד (SSOT) לנתונים מובְנים, נתוני עסקאות ונתונים קריטיים כמו מזהי מוצרים, שמות, מק"טים, מחירים ומלאי. ‫AlloyDB גם מספק לסוכן ה-AI יכולות חיפוש דמיון להמלצות ושאילתות בשפה טבעית.

הקצאת אשכול AlloyDB

  1. במסוף Google Cloud, נכנסים לדף AlloyDB for PostgreSQL.
  2. לוחצים על Create Cluster.
  3. בשדה Cluster ID, מזינים ecommerce-cluster.
  4. מגדירים סיסמה חזקה למשתמש postgres. למטרות למידה, אפשר להשתמש ב-alloydb.
  5. בשדה Database Version, משאירים את ברירת המחדל.
  6. בשדה Region, בוחרים באפשרות us-central1 (או באזור המועדף).

הגדרת המכונה הראשית

  1. בשדה Instance ID, מזינים ecommerce-cluster-primary.
  2. בקטע Zonal availability, בוחרים באפשרות Single zone.
  3. בשדה סדרת מכונות בוחרים באפשרות N2, ובשדה סוג מכונה בוחרים באפשרות 4 vCPU, 32 GB.
  4. בקטע קישור דרך IP פרטי, בוחרים באפשרות Private Services Access (PSA) וברשת default.אם רשת ברירת המחדל עדיין לא מוגדרת, לוחצים על Confirm network setup כדי ליצור אותה.
  5. בקטע Public IP Connectivity, מסמנים את התיבה Enable Public IP כדי שארגז הכלים של MCP יתחבר כמו שצריך ב-Codelab הזה. המסוף מפעיל באופן אוטומטי את הדגל password.enforce_complexity, שנדרש ב-AlloyDB לכתובת IP ציבורית.
  6. בשדה Authorized external networks, מזינים את הערך 0.0.0.0/0. מסמנים את התיבה אני מאשר/ת את הסיכונים ולוחצים על שמירה.
  7. לוחצים על Create Cluster.

הפעלת מסד הנתונים

  1. בתפריט הניווט שמימין, לוחצים על AlloyDB Studio.
  2. בתפריט הנפתח Database, בוחרים באפשרות postgres.
  3. כדי להיכנס למסד הנתונים, בוחרים באפשרות Built-in authentication.
  4. בשדה Username, משתמשים במשתמש postgres.
  5. בשדה Password, מזינים את הסיסמה שהגדרתם קודם.
  6. לוחצים על אימות.
  7. בתצוגת העורך, פותחים כרטיסייה חדשה של שאילתה ללא שם.
  8. מעתיקים את ה-DDL הבא ולוחצים על Run:
    CREATE TABLE products_core_table (
  product_id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  sku VARCHAR(50) UNIQUE NOT NULL,
  price NUMERIC(10, 2) NOT NULL,
  stock INT NOT NULL
);
  9. ב-Cloud Shell, עוברים לתיקיית הבסיס של הפרויקט:
    cd ~/polyglot-persist-ecommerce
  10. פותחים את הקובץ alloydb_insert_queries.sql ב-Cloud Shell ומעתיקים את שאילתות ההוספה.
    cat alloydb_insert_queries.sql
  11. בכרטיסיית שאילתה חדשה ללא שם, מדביקים רק את ההצהרות של INSERT ולוחצים על Run.
  12. בכרטיסייה חדשה של שאילתה ללא שם, מעתיקים את ה-DDL הבא ולוחצים על Run כדי ליצור אינדקס בטבלה products_core_table:
    CREATE INDEX idx_products_core_sku ON products_core_table(sku);

יצירת הטמעות של תמונות כדי שסוכן ה-AI יוכל לאחזר מוצרים דומים

השילוב של סוכן ה-AI משתמש בהטמעות של תמונות כדי לאחזר מוצרים דומים. ההטמעות נוצרות באמצעות המודל multimodalembedding@001 ונשמרות במסד הנתונים של AlloyDB. ההטמעות הן וקטורים עם 1,408 ממדים, והן מאוחסנות בעמודה img_embeddings.

כדי ליצור הטמעות, צריך לתת לחשבון השירות של AlloyDB את התפקידים הנדרשים לגישה ל-Cloud Storage.

הקצאת תפקידים לחשבון השירות של AlloyDB כדי לגשת ל-Cloud Storage

נותנים לחשבון השירות של AlloyDB את התפקידים שנדרשים כדי לקרוא תמונות מ-Cloud Storage וליצור הטמעות של Vertex AI:

for role in roles/storage.objectUser roles/storage.objectViewer roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role=$role --condition=None
done

הפעלת תוספים

כדי ליצור את האפליקציה הזו, נשתמש בתוספים pgvector ו-google_ml_integration. התוסף pgvector מאפשר לאחסן ולחפש הטמעות וקטורים. התוסף google_ml_integration מספק פונקציות שמשמשות לגישה לנקודות קצה של חיזוי ב-Vertex AI כדי לקבל חיזויים ב-SQL. כדי להפעיל את התוספים האלה, מריצים את פקודות ה-DDL הבאות:

  1. במסוף Google Cloud, נכנסים לדף AlloyDB for PostgreSQL.
  2. בתפריט הניווט שמימין, לוחצים על AlloyDB Studio.
  3. בתצוגת העורך, פותחים כרטיסייה חדשה של שאילתה ללא שם.
  4. מעתיקים את ה-DDL הבא ולוחצים על Run:
    CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration;

אתחול מסד הנתונים באמצעות הטמעות

  1. מוסיפים את העמודה img_embeddings ל-products_core_table.
    ALTER TABLE products_core_table
ADD COLUMN img_embeddings vector(1408);
  2. מדפיסים את שאילתת ההטמעות עם שם הקטגוריה:
    cd ~/polyglot-persist-ecommerce
sed "s/<STORAGE_BUCKET_NAME>/$BUCKET/g" alloydb_generate_embeddings.sql
  3. מעתיקים את הפלט, מדביקים אותו בכרטיסיית שאילתה חדשה ב-AlloyDB Studio ולוחצים על Run. זה לוקח בערך דקה. אם הזמן הקצוב לתפוגה חלף, מריצים אותו שוב. המערכת מדלגת על מוצרים שכבר יש להם הטמעות.

5. הגדרת MongoDB Atlas ב-Google Cloud

ב-MongoDB מאוחסנים פרטי מוצרים עשירים וחצי-מובְנים ונתוני התנהגות גמישים של המשתמשים (כמו קליקים וצפיות).

יצירת אשכול MongoDB

  1. נכנסים ל-MongoDB Atlas (אם צריך, יוצרים חשבון בחינם).
  2. בקטע Deploy your cluster, בוחרים באפשרות Free. ‫(ב-Atlas נבחרת מראש רמה בתשלום. ודאו שהאפשרות Free מסומנת).
  3. בשדה Provider בוחרים באפשרות Google Cloud, ובשדה Region בוחרים באפשרות Iowa (us-central1).
  4. בשדה Name, מזינים ecommerce-cluster ומבטלים את הבחירה באפשרות Preload sample dataset.
  5. לוחצים על Create Deployment.

מתן גישה ויצירת משתמש במסד הנתונים

‫Atlas פותח את תיבת הדו-שיח Connect to ecommerce-cluster.

  1. לוחצים על הוספת כתובת IP אחרת, מזינים את 0.0.0.0/0 ומוסיפים אותה.
  2. מזינים store-user בשדה Username ו-storeuser בשדה Password, ולוחצים על Create Database User.
  3. לוחצים על Choose a connection method ואז על Drivers and Client Libraries.
  4. בקטע Use this connection string in your application, מעתיקים את מחרוזת החיבור. נראה שmongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. מחליפים את ב-storeuser ושומרים את המחרוזת. תשתמשו בה ב-tools.yaml.

יצירת מסד נתונים ואוסף

  1. בתפריט הניווט הימני, לוחצים על Data Explorer, ואז על Create database ומזינים את הפרטים:
    • שם מסד הנתונים: ecommerce_db
    • שם האוסף: product_details_collection
  2. לוחצים על Create Database.
  3. ב-Data Explorer, בוחרים את שם האוסף.
  4. לוחצים על הסמל הוספת נתונים (+) ואז על הוספת מסמך.
  5. מעתיקים את תוכן ה-JSON מהקובץ product_details_export.json ומדביקים אותו בתיבת הדו-שיח של העורך Insert Document.
  6. ‫Atlas מציג באנר עם הצעה להמיר את הטקסט לתחביר מעטפת. לוחצים על המר ואז על הוספה. מוודאים שנוספו 192 מסמכים.
  7. ב-Data Explorer, לוחצים על Create collection (+) לצד מסד הנתונים ecommerce_db.
  8. מזינים user_interactions_collection בתור שם האוסף ולוחצים על Create Collection.
  9. ב-Data Explorer, בוחרים את האוסף user_interactions_collection.
  10. לוחצים על הסמל הוספת נתונים (+) ואז על הוספת מסמך.
  11. מעתיקים את תוכן ה-JSON מהקובץ user_interactions_export.json ומדביקים אותו בתיבת הדו-שיח של העורך Insert Document.
  12. ‫Atlas מציג באנר עם הצעה להמיר את הטקסט לתחביר מעטפת. לוחצים על המר ואז על הוספה. מוודאים שנוספו 211 מסמכים.

6. הגדרת BigQuery

כדי ליצור דוחות והמלצות חכמים, BigQuery צובר ומנתח את ההתנהגות ההיסטורית של המשתמשים.

יצירת מערך הנתונים

  1. במסוף Google Cloud, עוברים אל BigQuery.
  2. ליד מזהה הפרויקט בחלונית Explorer, לוחצים על סמל האפשרויות הנוספות (3 נקודות) ובוחרים באפשרות Create dataset.
  3. מזינים ecommerce_analytics בשדה Dataset ID.
  4. בקטע Data location, בוחרים באפשרות US (multiple regions) (ההגדרה של tools.yaml מצפה למיקום US).
  5. לוחצים על Create dataset.

יצירת טבלת הניתוח

  1. פותחים שאילתה חדשה בסביבת העבודה של BigQuery.
  2. מריצים את הצהרת ה-SQL הבאה כדי ליצור את טבלת הסיכום שמקשרת בין המשתמשים לאינטראקציות עם המוצרים:
CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

הקצאת תפקידים לחשבון השירות של Compute

מקצים לחשבון השירות שמוגדר כברירת מחדל ב-Compute את התפקידים שנדרשים ל-MCP Toolbox ולאפליקציה:

for role in \
  roles/bigquery.dataEditor \
  roles/bigquery.jobUser \
  roles/secretmanager.secretAccessor \
  roles/alloydb.client \
  roles/serviceusage.serviceUsageConsumer \
  roles/storage.objectViewer \
  roles/aiplatform.user \
  roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="$role" \
    --condition=None
done

לחלופין, במסוף נכנסים לדף IAM & Admin > IAM, לוחצים על Grant access, מזינים את חשבון השירות ומוסיפים את אותם תפקידים.

7. הבנת האפליקציה מקצה לקצה

כדי להבין איך כל רכיב פועל עם הרכיבים האחרים, ניצור אפליקציה למסחר אלקטרוני שמשתמשת בכמה מסדי נתונים ושירותים. האפליקציה מבוססת על קצה עורפי של Python (Flask) ומשלבת כמה שירותים ומסדי נתונים של Google Cloud.

הסבר על מבנה הספרייה

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

בודקים את הקבצים שהורדו בספרייה הזו. הספריות הבאות ברמה העליונה קיימות:

  • ‫UploadImages: מאחסן נכסי תמונות, שמשמשים בעיקר לתיעוד או לתוכן חזותי בקטלוג המוצרים של המסחר האלקטרוני.
  • ‫static: מאחסן את נכסי האינטרנט הסטטיים של האפליקציה, כמו קובצי CSS ו-JavaScript, שמשמשים לעיצוב ולהוספת אינטראקטיביות לממשק המשתמש ( מקור).
  • ‫templates: מאחסנת את תבניות ה-HTML (כנראה Jinja2 ל-Flask) שבהן משתמשת אפליקציית Python כדי ליצור באופן דינמי דפי אינטרנט לקטלוג המסחר האלקטרוני ( מקור).

הקבצים במאגר הזה פועלים יחד כדי ליצור, להגדיר ולפרוס אפליקציית מסחר אלקטרוני עם כמה מסדי נתונים. קבצים מרכזיים כמו app.py מתזמרים את הקצה העורפי על ידי שילוב של מקורות נתונים מגוונים שמוגדרים בקובצי SQL ו-JSON, וקובצי תצורה מבטיחים פריסה חלקה בסביבות ענן:

  • ‫app.py: מתזמר את הקצה העורפי של Flask ואת השילובים של מסדי נתונים מרובים.
  • ‫agentengine.py: הלוגיקה העיקרית להפעלה ולהגדרה של סוכני Vertex AI.
  • ‫.env: מאחסן סודות לחיבורים של מסד נתונים ואחסון.
  • ‫tools.yaml: מגדיר את MCP Toolbox לפעולות במסדי נתונים מסוג multidb.
  • ‫Dockerfile: מגדיר את קובץ האימג' של הקונטיינר ואת הגדרת הסביבה.
  • ‫requirements.txt: רשימה של ספריות Python שנדרשות לזמן הריצה של האפליקציה.
  • ‫tools.yaml: הגדרות ל-MCP Toolbox.
  • ‫Procfile: מציין פקודות להרצה בסביבת הייצור לצורך פריסה.
  • alloydb_insert_queries.sql: מכיל שאילתות SQL לנתונים יחסיים.
  • ‫product_details_export.json ו-user_interactions_export.json: מספקות נתוני JSON לדוגמה למסד נתונים NoSQL.
  • ‫README.md: מדריך להגדרה, לפריסה ולהבנת הפרויקט.

תהליך מקצה לקצה של האפליקציה

  • הגדרת AlloyDB: מקצים אשכול עם ביצועים גבוהים ומשתמשים בסקריפטים של SQL שסופקו כדי ליצור את products_core_table עם עמודות וקטוריות להטמעות של תמונות.
  • הגדרת MongoDB Atlas: פורסים אשכול ב-Google Cloud כדי לאחסן מאפייני מוצרים משתנים ב-product_details ולתעד קליקים בזמן אמת ב-user_interactions.
  • ניתוח נתונים ב-BigQuery: יוצרים מערך נתונים כדי לצבור יומני אינטראקציות, וכך אפשר להריץ שאילתות ניתוח מורכבות שמזהות את "5 הפריטים המובילים" במיליוני אירועים.
  • מאגר Cloud Storage: יוצרים קטגוריה ציבורית שתכיל תמונות מוצרים ברזולוציה גבוהה, ומוודאים שכל נכס נגיש באמצעות כתובת URL חתומה או ציבורית לממשק הקצה.
  • ‫MCP Toolbox Deployment: פריסת ארגז הכלים ב-Cloud Run, והגדרתו כגשר RESTful מרכזי שמתרגם כוונה בשפה טבעית לשאילתות בכמה מסדי נתונים.
  • הגדרת Tools.yaml: מגדירים את הכלים, כמו get_product_core_data או get_top_5_views, וממפים פעולות ספציפיות של SQL ו-NoSQL לשמות פשוטים שהנציג יכול לקרוא.
  • ‫Flask Backend Logic: מטמיעים נתיבי app.py שמתממשקים עם MCP Toolbox, מטפלים בתיאום של אחזור הנתונים ומשמשים כ-API לממשק המשתמש.
  • תזמור של כמה סוכנים: מגדירים את סוכני ה-ADK בתוך הקוד כדי להסיק מסקנות לגבי כוונת המשתמש (Intent), ובוחרים את "הכלי" המתאים לפתרון שאילתות קמעונאיות מורכבות ממקורות מרובים.
  • שילוב ממשק קצה (Frontend): יוצרים ממשק index.html שכולל את קטלוג המוצרים עם תכונה להקלטת אינטראקציות, כרטיסיית Analytics כדי להבין את ניתוח הביצועים של המוצרים, ו"כרטיסיית סוכן" ייעודית שמשתמשת בצ'אט עם כמה סוכנים של ADK כדי לספק חוויית קנייה חלקה באמצעות שיחה.

עכשיו נטמיע את התזמור והפריסות.

8. הגדרת MCP Toolbox ופריסה ב-Cloud Run

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

התקנה מקומית של MCP Toolbox

מורידים את הקובץ הבינארי של MCP Toolbox לספריית הבית והופכים אותו לקובץ הפעלה:

export VERSION=1.15.0
curl -L -o ~/toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x ~/toolbox

הגדרת tools.yaml

צריך להגדיר את ההפשטות של AlloyDB,‏ MongoDB ו-BigQuery. הקובץ tools.yaml מסביר לארגז הכלים של MCP איך לקיים אינטראקציה עם כל אחד מהם.

  1. המאגר כבר כולל את tools.yaml. כדי לפתוח אותו:
    cd ~/polyglot-persist-ecommerce
cloudshell edit tools.yaml
  2. מחליפים את ה-placeholders ***** בערכים שלכם:

    מסד נתונים

    שדה

    ערך לדוגמה

    ‫AlloyDB או BigQuery

    project

    YOUR_PROJECT_ID

    AlloyDB

    region

    us-central1

    AlloyDB

    cluster

    ecommerce-cluster

    AlloyDB

    instance

    ecommerce-cluster-primary

    AlloyDB

    database

    postgres

    AlloyDB

    password

    alloydb

    AlloyDB

    ipType

    public (מוסיפים את השורה הזו מתחת ל-alloydb-source אם היא לא קיימת)

    MongoDB

    uri

    מחרוזת החיבור ששמרתם קודם

  3. מפנים את התצוגות המקדימות של התמונות לקטגוריה:
    sed -i "s/ecommerce-app-images/$BUCKET/g" tools.yaml

בדיקת ממשק המשתמש של הכלי

  1. בטרמינל של Cloud Shell, מריצים את ארגז הכלים באופן מקומי כדי להציג את ממשק המשתמש:
    ~/toolbox --config tools.yaml --ui --enable-api
  2. ב-Cloud Shell, לוחצים על Web Preview > Change port, מזינים 5000 ומוסיפים את /ui בסוף כתובת ה-URL שנפתחת.

מופיע ממשק המשתמש הבא של MCP Toolbox:

ממשק המשתמש של MCP Toolbox

כשמסיימים, לוחצים על Ctrl+C כדי לעצור את ארגז הכלים המקומי.

פריסה ב-Cloud Run

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

  1. מעלים את קובץ התצורה של tools.yaml ל-Google Secret Manager:
    gcloud secrets create tools --data-file=tools.yaml
    אם משנים את tools.yaml מאוחר יותר, מעלים גרסה חדשה עם:
    gcloud secrets versions add tools --data-file=tools.yaml
  2. פורסים באמצעות קובץ האימג' הציבורי של קונטיינר MCP Toolbox:
    gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
    --region us-central1 \
    --service-account ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui","--enable-api" \
    --allow-unauthenticated
    ‫--enable-api מפעיל את ה-API בארכיטקטורת REST שבו משתמשת אפליקציית האינטרנט.
  3. שומרים את כתובת ה-URL של ארגז הכלים:
    export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
echo $TOOLBOX_URL
    אפשר לפתוח את $TOOLBOX_URL/ui בדפדפן כדי לראות את הכלים.

9. הגדרת אפליקציית המסחר האלקטרוני ופריסה ב-Cloud Run

עכשיו, כשמסדי הנתונים פועלים וההפשטה של MCP Toolbox פרוסה, אפשר להריץ את אפליקציית האינטרנט Flask.

כדי להציג את קטלוג המוצרים, אפליקציית Flask מעבדת את הנתונים לפי השלבים הבאים:

  1. אחזור נתוני ליבה: אחזור של רשימת המוצרים המלאה מ-AlloyDB‏ (list_products_core).
  2. אחזור פרטים מורחבים: אחזור של כל פרטי המוצר מ-MongoDB‏ (list_all_product_details).
  3. שילוב רשימות: שרשור של שתי הרשימות.
  4. העשרה באמצעות מדיה: הוספה של כתובת ה-URL של התמונה ב-Cloud Storage לכל פריט.

יצירת Agent Engine

  1. מתקינים את יחסי התלות:
    cd ~/polyglot-persist-ecommerce
pip install -r requirements.txt
    הערה: השלב הזה יכול להימשך כמה דקות עד שהחבילות יותקנו.
  2. מאתחלים ורושמים את סוכן ה-AI באמצעות Vertex AI Reasoning Engine:
    export REASONING_ENGINE_LOCATION=us-central1
export APP_NAME=$(python agentengine.py)
echo $APP_NAME
    הפלט אמור להיראות כך:
    projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

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

פריסת ממשק המשתמש ב-Cloud Run

  1. כדי להשלים את הארכיטקטורה, פורסים את אפליקציית האינטרנט ב-Cloud Run:
    gcloud run deploy polyglot --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="MCP_TOOLBOX_SERVER_URL=$TOOLBOX_URL,GCS_PRODUCT_BUCKET=$BUCKET,FALLBACK_IMAGE_URL=https://storage.googleapis.com/$BUCKET/fallback.jpg,GOOGLE_GENAI_USE_VERTEXAI=TRUE,PROJECT_ID=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,REASONING_ENGINE_LOCATION=$REASONING_ENGINE_LOCATION,APP_NAME=$APP_NAME,MODEL=gemini-3.5-flash"

האפליקציה שלך פעילה עכשיו! פותחים את כתובת ה-URL של השירות שסופקה על ידי Cloud Run כדי לראות את הקטלוג של Multidb Ecommerce. כתובת ה-URL תהיה דומה לכתובת https://polyglot-*********-uc.a.run.app/.

10. היכרות עם האפליקציה

  1. לוחצים על קטלוג המוצרים כדי לראות את כל המוצרים.
    קטלוג מוצרים
  2. כדי לראות את פרטי המוצר, לוחצים על סמל המוצר. שימו לב שהתמונות נשלפות מ-Cloud Storage, פרטי המוצרים נשלפים מ-MongoDB ומלאי המוצרים נשלף מ-AlloyDB.פרטי המוצר
  3. מקיימים אינטראקציה עם קטלוג המוצרים כדי ליצור תצוגות מדומה ופעולות כתיבה שנשלחות אל MongoDB.
  4. לוחצים על ETL & Analytics כדי לראות את ניתוח הנתונים של המוצר. תבחינו שהניתוח של נתוני המוצרים מאוחזר מ-BigQuery.
    ‫ETL וניתוח נתונים של מוצרים
  5. לוחצים על הכרטיסייה סוכן AI כדי לתקשר עם סוכן ה-AI. אפשר לשאול שאלות בשפה טבעית, כמו:
    I'm planning a high-altitude photography trip.
Show me some weather-resistant backpacks similar in style to aero glow pro
but without any leather components. Also, let me know if they are actually in
stock and if other photographers have complained about the strap durability
in the reviews.
    סוכן AI

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

סוכן AI

11. הסרת המשאבים

כדי להימנע מחיובים מתמשכים בחשבון Google Cloud, מחקו את המשאבים שנוצרו במהלך ה-Codelab הזה.

מריצים את הפקודות הבאות ב-Cloud Shell:

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete polyglot --region us-central1 --quiet
gcloud secrets delete tools --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://$BUCKET
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

אם רוצים, אפשר למחוק את המכונה של Agent Engine:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1/$APP_NAME?force=true"

לחלופין, במסוף Google Cloud, עוברים אל Vertex AI‏ > Agent Engine ומוחקים את המכונה.

לחלופין, כדי למחוק את כל הפרויקט בענן ב-Google Cloud ואת כל המשאבים שלו, מריצים את הפקודה הבאה:

gcloud projects delete $PROJECT_ID

12. מזל טוב

מעולה! יצרתם בהצלחה ארכיטקטורת Multidb חוצת-עננים.

הדגמתם איך MCP Toolbox משמש כדבק הארכיטקטוני של אפליקציה מודרנית ומתמחה. התאמת מסד הנתונים הנכון למשימה הנכונה מאפשרת לכם:

  • כתיבת נתונים גמישה: MongoDB ליומני אירועים.
  • עקביות טרנזקציות: AlloyDB לתקינות הליבה.
  • ניתוח נתונים עם ביצועים גבוהים: BigQuery לבינה עסקית.
  • פיתוח מאוחד: קצה עורפי אחד של Python שמפשט את כל המורכבות באמצעות MCP Toolbox.

מסמכי עזר

מידע נוסף על מוצרים קשורים של Google Cloud ושיעורי Lab לתרגול:

מידע נוסף על המוצרים שבהם משתמשים ב-Codelab הזה זמין במאמרים הבאים: