Build an Intelligent Ecommerce Catalog with Multi-database Persistence

1. מבוא

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

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

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

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

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

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

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

למה השאילתה הזו נקראת 'הסוכן הקטלני':

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

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

כי אנחנו לא מתאימים רק מילות מפתח. אנחנו משתמשים ב-MCP Toolbox כדי לאפשר לסוכנים שלנו'להסיק מסקנות' מכל המקורות האלה, מהנתונים העסקיים ב-AlloyDB וממאפיינים גמישים ב-MongoDB בו-זמנית. בואו נבנה אותו.

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

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

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

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

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

יצירת פרויקט ב-Google Cloud

  1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-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

הפעלת ממשקי ה-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 Console, עוברים אל Cloud Storage ולוחצים על Create bucket.
  2. נותנים לקטגוריה שם ייחודי באופן גלובלי (לדוגמה, ecommerce-app-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 User.
  9. לוחצים על שמירה ואז על מתן גישה לכולם כדי לאשר שהמשאב יהיה ציבורי.

העלאת תמונות placeholder

בסרטון BRK2-149-multidb-ecommerce נעשה שימוש בתמונות placeholder כדי להעניק חוויה חזותית מיטבית.

  1. ב-Cloud Shell, משכפלים את המאגר next-26-sessions:
    git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git
  2. עוברים לתיקייה UploadImages:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages
  3. במסוף Google Cloud, עוברים אל Cloud Storage ולוחצים על Buckets.
  4. לוחצים על השם של הקטגוריה החדשה שיצרתם.
  5. לוחצים על העלאה > העלאת קבצים, בוחרים את תמונות הדוגמה שהורדתם ולוחצים על פתיחה.

4. הגדרת AlloyDB

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

הקצאת משאבים לאשכול AlloyDB

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

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

  1. בשדה Instance ID, מזינים ecommerce-cluster-primary.
  2. בקטע זמינות אזורית, בוחרים באפשרות אזור יחיד.
  3. בקטע Machine Type (סוג המכונה), בוחרים סוג מכונה קטן (למשל, N2, ‏ 4 vCPU, ‏ 32 GB RAM).
  4. בקטע Private IP Connectivity (קישוריות של כתובות IP פרטיות), בוחרים באפשרות Private Services Access (PSA) (גישה לשירותים פרטיים) ובוחרים את הרשת default.אם לא מוגדרת רשת ברירת מחדל, לוחצים על Confirm network setup (אישור הגדרת הרשת) כדי ליצור רשת כזו.
  5. בקטע Public IP Connectivity, מסמנים את התיבה Enable Public IP כדי שכלי ה-MCP יתחברו בצורה תקינה ב-codelab הזה.
  6. בקטע Authorised external networks, מזינים את הערך 0.0.0.0/0. מסמנים את תיבת הסימון I acknowledge the risks (אני מאשר/ת את הסיכונים) ולוחצים על Save (שמירה).
  7. לוחצים על יצירת אשכול.

הערה: חשוב לרשום את כתובת ה-IP הציבורית (היא נראית בערך כך: 34.124.240.26).

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

  1. בתפריט הניווט הימני, לוחצים על AlloyDB Studio.
  2. בתפריט הנפתח Database, בוחרים באפשרות postgres.
  3. בוחרים באפשרות אימות מובנה כדי להיכנס למסד הנתונים.
  4. בשדה שם משתמש, משתמשים בערך postgres user.
  5. בקטע סיסמה, מזינים את הסיסמה שהגדרתם קודם.
  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, עוברים לתיקייה BRK2-149-multidb-ecommerce:
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  10. פותחים את הקובץ alloydb_insert_queries.sql ב-Cloud Shell ומעתיקים את שאילתות ההוספה.
    cat alloydb_insert_queries.sql
  11. בכרטיסייה חדשה של שאילתה ללא שם, מדביקים רק את ההצהרות INSERT ולוחצים על הפעלה.
  12. בכרטיסייה חדשה של שאילתה ללא שם, מעתיקים את ה-DDL הבא ולוחצים על הפעלה כדי ליצור אינדקס בטבלה 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.

  1. עוברים אל IAM and admin (ניהול הרשאות גישה).
  2. לוחצים על הענקת גישה.
  3. בשדה New principals, מזינים את חשבון השירות של AlloyDB. חשבון השירות נראה דומה ל-service-991742412753@gcp-sa-alloydb.iam.gserviceaccount.com.
  4. לוחצים על בחירת תפקיד.
  5. מחפשים את התפקיד משתמש באובייקט אחסון ובוחרים בו.
  6. לוחצים על Add another role ובוחרים את התפקיד Storage Object Viewer.
  7. לוחצים על Add another role ובוחרים את התפקיד Vertex AI User.
  8. לוחצים על שמירה.

הפעלת תוספים

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

  1. במסוף Google Cloud, עוברים אל AlloyDB ל-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. יוצרים הטמעות לתמונות ומאחסנים אותן בעמודה img_embeddings.
    ‫
    UPDATE products_core_table
SET img_embeddings = google_ml.image_embedding(
    model_id => 'multimodalembedding@001',
    image => 'gs://<STORAGE_BUCKET_NAME>/' || sku || '.jpg',
    mimetype => 'image/jpeg')
WHERE sku IN (
    SELECT
    sku
    FROM
    products_core_table
    WHERE
    img_embeddings IS NULL
    AND sku IS NOT NULL
    LIMIT 10
);
    מחליפים את בשם הקטגוריה שלכם ב-Cloud Storage.
  3. כדי ליצור הטמעות של תמונות לכל קבוצת התמונות, צריך לחזור על השאילתה הקודמת לפחות 5 פעמים, כי יש מגבלה של 5 דקות ב-Studio. אם חלף הזמן הקצוב לתפוגה של השאילתה הזו, משנים את LIMIT ל-5 ומריצים מחדש את השאילתה עשר פעמים. השלב הזה עשוי להימשך כמה דקות.

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

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

יצירת אשכול MongoDB

  1. עוברים אל MongoDB Atlas ב-Google Cloud ובוחרים חשבון ברמת שירות חינמית.
  2. בוחרים את רמת האשכול Free (חינם) ומזינים שם לאשכול, למשל ecommerce-cluster.
  3. בוחרים באפשרות Google Cloud כספק ומוודאים שהאזור תואם לאזור Google Cloud (למשל, us-central1).
  4. לוחצים על יצירת פריסה.
  5. לוחצים על סגירה.

הגדרת גישה לרשת

  1. במסוף Atlas, עוברים אל Database & Network Access (גישה למסד נתונים ולרשת).
  2. לוחצים על רשימת כתובות IP לגישה.
  3. לוחצים על הוספת כתובת IP.
  4. מוסיפים את 0.0.0.0/0, שמאפשר גישה מכל מקום.
  5. לוחצים על אישור.

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

  1. במסוף Atlas, עוברים אל Database & Network Access (גישה למסד נתונים ולרשת).
  2. לוחצים על משתמשי מסד נתונים.
  3. לוחצים על הוספת משתמש חדש במסד הנתונים.
  4. בוחרים באפשרות סיסמה כשיטת האימות.
  5. מזינים שם משתמש store-user וסיסמה storeuser.
  6. לוחצים על Add Built In Role (הוספת תפקיד מובנה) ובוחרים באפשרות Read and write to any database (קריאה וכתיבה בכל מסד נתונים).
  7. לוחצים על הוספת משתמש.

קבלת מחרוזת החיבור

  1. עוברים אל מסד נתונים > אשכולות > התחברות.
  2. בקטע Connect your application (חיבור האפליקציה), לוחצים על Drivers (דרייברים).
  3. מעתינים את מחרוזת החיבור שמוצגת בקטע הוספת מחרוזת החיבור לקוד האפליקציה. המחרוזת נראית בערך כך:
    ‫
    mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
    מחליפים את db_password בסיסמה שלכם ל-MongoDB. ב-Codelab הזה, הוא storeuser.

שומרים את מחרוזת החיבור. תשתמשו בו בהמשך בשביל משתנה הסביבה MONGODB_CONNECTION_STRING.

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

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

6. הגדרת BigQuery

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

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

  1. ב-Google Cloud Console, עוברים אל BigQuery.
  2. לצד מזהה הפרויקט בחלונית Explorer, לוחצים על סמל האפשרויות הנוספות (3 נקודות) ובוחרים באפשרות Create dataset (יצירת קבוצת נתונים).
  3. מזינים ecommerce_analytics בשדה Dataset ID.
  4. לוחצים על יצירת מערך נתונים.

יצירת טבלת Analytics

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

הענקת תפקידים לחשבון השירות של Compute עבור MCP Toolbox

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

כדי להקצות תפקידים:

  1. עוברים אל IAM and admin (ניהול הרשאות גישה).
  2. לוחצים על הענקת גישה.
  3. בשדה New principals, מזינים את חשבון השירות שמוגדר כברירת מחדל של Compute, שנקרא YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. מחליפים את YOUR_PROJECT_NUMBER במספר הפרויקט ב-Google Cloud.
  4. לוחצים על בחירת תפקיד.
  5. מחפשים את התפקיד BigQuery Data Editor ובוחרים אותו.
  6. לוחצים על Add another role ובוחרים את התפקיד BigQuery Job User.
  7. לוחצים על Add another role ובוחרים את התפקיד Secret Manager Secret Accessor.
  8. לוחצים על Add another role ובוחרים את התפקיד Editor.
  9. לוחצים על שמירה.

7. הסבר על התהליך המלא של הגשת הבקשה

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

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

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

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

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

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

  • ‫app.py: מתאם בין קצה העורפי של Flask ושילובים של מסדי נתונים מרובים.
  • ‫agentengine.py: לוגיקה מרכזית לאתחול ולהגדרה של סוכני Vertex AI.
  • ‫.env: מאחסן סודות לחיבורים למסד נתונים ולאחסון.
  • ‫tools.yaml: הגדרת MCP Toolbox לפעולות במסדי נתונים מרובים.
  • ‫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 Analytics: יצירת מערך נתונים לצורך צבירה של יומני אינטראקציות, כדי לאפשר שאילתות אנליטיות מורכבות שמזהות את 5 הפריטים המובילים במגמת עלייה מתוך מיליוני אירועים.
  • מאגר Cloud Storage: יוצרים קטגוריה ציבורית לאחסון תמונות מוצרים ברזולוציה גבוהה, ומוודאים שכל נכס נגיש דרך כתובת URL חתומה או ציבורית לקצה הקדמי.
  • פריסת MCP Toolbox: פריסת Toolbox ב-Cloud Run, והגדרתו כגשר מרכזי מבוסס-RESTful שמתרגם כוונות בשפה טבעית לשאילתות במספר מסדי נתונים.
  • הגדרה של Tools.yaml: מגדירים את הכלים, כמו get_product_core_data או get_top_5_views, וממפים פעולות ספציפיות ב-SQL וב-NoSQL לשמות פשוטים שהסוכן יכול לקרוא.
  • לוגיקת קצה עורפי של Flask: הטמעת מסלולים ב-app.py שמקיימים אינטראקציה עם MCP Toolbox, ניהול התיאום של אחזור הנתונים ושימוש כ-API לממשק המשתמש.
  • Multi-Agent Orchestration: הגדרת סוכני ADK בקוד כדי להסיק את כוונת המשתמש, ולבחור את ה'כלי' המתאים לפתרון שאילתות מורכבות של קמעונאים שמגיעות ממקורות שונים.
  • שילוב קצה קדמי: יוצרים ממשק index.html שכולל את קטלוג המוצרים עם תכונת תיעוד האינטראקציות, כרטיסיית Analytics להבנת ניתוח ביצועי המוצרים וכרטיסייה ייעודית של סוכן שמשתמשת בצ'אט מרובה סוכנים של ADK כדי לספק חוויית קנייה חלקה בשיחה.

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

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

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

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

  1. ב-Cloud Shell, עוברים לתיקייה toolbox-implementation:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  2. מורידים את הקובץ הבינארי של MCP Toolbox והופכים אותו לקובץ הפעלה:
    export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

הגדרת הקובץ tools.yaml

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

  1. יוצרים ועורכים את הקובץ tools.yaml באמצעות העורך המוטמע:
    cloudshell edit tools.yaml
    אפשר למצוא את קובץ tools.yaml המלא במאגר GitHub. מעתיקים את התוכן שלו לקובץ tools.yaml החדש.
  2. מעדכנים את המארח, המשתמש, הסיסמאות, מזהי הפרויקטים ומחרוזות החיבור כך שיתאימו לתשתית שהקציתם בשלבים הקודמים:

    מסד נתונים

    שדה

    ערך לדוגמה

    ‫AlloyDB/BigQuery

    project_id

    YOUR_PROJECT_ID

    AlloyDB

    region

    us-central1

    AlloyDB

    cluster

    ecommerce-cluster

    AlloyDB

    instance

    ecommerce-cluster-primary

    AlloyDB

    database

    postgres

    AlloyDB

    password

    alloydb

    MongoDB

    connection_string

    mongodb+srv://store-user:storeuser@ecommerce-cluster.urcxr6q.mongodb.net

הענקת תפקידים לחשבון השירות של Compute עבור MCP Toolbox

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

  1. עוברים אל IAM and admin (ניהול הרשאות גישה).
  2. לוחצים על הענקת גישה.
  3. בשדה New principals, מזינים את חשבון השירות שמוגדר כברירת מחדל של Compute, שנקרא YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. מחליפים את YOUR_PROJECT_NUMBER במספר הפרויקט ב-Google Cloud.
  4. לוחצים על בחירת תפקיד.
  5. מחפשים את התפקיד BigQuery Data Editor ובוחרים אותו.
  6. לוחצים על Add another role ובוחרים את התפקיד AlloyDB Client.
  7. לוחצים על Add another role ובוחרים את התפקיד Service Usage Consumer.
  8. לוחצים על Add another role ובוחרים את התפקיד Storage Object Viewer.
  9. לוחצים על שמירה.

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

  1. בטרמינל של Cloud Shell, מריצים את ארגז הכלים באופן מקומי כדי להציג את ממשק המשתמש:
    ./toolbox --ui
  2. פותחים את התצוגה המקדימה באינטרנט ב-Cloud Shell ביציאה 5000 ועוברים לדף הכלים. לדוגמה, בהתאם לכתובת ה-URL של הסשן, אפשר לראות אותה בכתובת: https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui

ממשק המשתמש של כלי ה-MCP נראה כך:

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

פריסה ב-Cloud Run

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

  1. פותחים סשן חדש ב-Cloud Shell.
  2. עוברים לתיקייה toolbox-implementation:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  3. מעלים את קובץ ההגדרות tools.yaml אל Google Secret Manager:
    gcloud secrets create tools --data-file=tools.yaml
    הערה: כדי להוסיף גרסה חדשה לסוד הקיים, משתמשים בפקודה הבאה:
    gcloud secrets versions add tools --data-file=tools.yaml
  4. פריסה באמצעות קובץ האימג' הציבורי של קונטיינר MCP Toolbox:
    export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.29.0
export PROJECT_ID=$(gcloud config get-value project)

gcloud run deploy toolbox \
    --image $IMAGE \
    --region us-central1 \
    --service-account $(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui" \
    --allow-unauthenticated
  5. אחרי הפריסה, רושמים את כתובת ה-URL של שירות Cloud Run שמופיעה. הוא אמור להיראות כך: https://toolbox-*********-uc.a.run.app/ui

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

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

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

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

יצירת נתיב אפליקציה של מנוע נימוקים

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

  1. בטרמינל של Cloud Shell, עוברים לתיקייה BRK2-149-multidb-ecommerce.
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  2. מריצים את הקובץ requirements.txt כדי להתקין את יחסי התלות
    pip install -r requirements.txt
  3. מריצים את הסקריפט agentengine.py כדי ליצור את נתיב האפליקציה של מנוע הנימוקים:
    python agentengine.py

הפלט ייראה כך:

projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

הגדרת משתני הסביבה

  1. יוצרים קובץ .env ועורכים אותו:
    cloudshell edit .env
  2. מחליפים את הערכים בחיבורי מסד הנתונים הספציפיים ובכתובת ה-URL החדשה של Cloud Run Toolbox:
    # 1. MongoDB Connection String
MONGODB_CONNECTION_STRING="mongodb+srv://<db_user>:<db_password>@cluster0.mongodb.net"

# 2. MCP Toolbox Server Location
# Must match the address where you run the toolbox server
MCP_TOOLBOX_SERVER_URL="https://toolbox-*********-uc.a.run.app"

# 3. Google Cloud Storage Bucket Name
GCS_PRODUCT_BUCKET="ecommerce-app-images"

# 4. Fallback image URL
FALLBACK_IMAGE_URL="https://storage.googleapis.com/ecommerce-media-bold-circuit-492711-n9/fallback.jpg"

# 5. Google Gen AI Vertex AI flag
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# 6. Project ID
PROJECT_ID=codelab-project-491117

# 7. Google Cloud Location of AlloyDB, BigQuery databases
GOOGLE_CLOUD_LOCATION=us-central1

# 8. Reasoning engine application path
APP_NAME=projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

# 9. Model ID
MODEL=gemini-1.5-flash-lite

פריסת חזית האתר ב-Cloud Run

  1. כדי להשלים את הארכיטקטורה, פורסים את אפליקציית האינטרנט ב-Cloud Run:
    gcloud run deploy polyglot --source . --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars \
  MONGODB_CONNECTION_STRING="<MONGODB_CONNECTION_STRING>", \
  MCP_TOOLBOX_SERVER_URL="<MCP_TOOLBOX_SERVER_URL>", \
  GCS_PRODUCT_BUCKET="<GCS_PRODUCT_BUCKET>", \
  FALLBACK_IMAGE_URL="<FALLBACK_IMAGE_URL>", \
  GOOGLE_GENAI_USE_VERTEXAI=TRUE, \
  PROJECT_ID="YOUR_PROJECT_ID", \
  GOOGLE_CLOUD_LOCATION=us-central1, \
  APP_NAME="<YOUR_REASONING_ENGINE_APP_PATH>", \
  MODEL="gemini-1.5-flash-lite"
    מחליפים את הערכים הבאים:
    • YOUR_PROJECT_ID: מזהה הפרויקט ב-Google Cloud.
    • ‫YOUR_REASONING_ENGINE_APP_PATH: הפלט מהרצת python agentengine.py, לדוגמה, projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856.
    • ‫MCP_TOOLBOX_SERVER_URL: כתובת ה-URL של שרת ארגז הכלים של ה-MCP, לדוגמה https://toolbox-*********-uc.a.run.app.
    • ‫GCS_PRODUCT_BUCKET: השם של קטגוריית Google Cloud Storage, לדוגמה ecommerce-app-images.
    • ‫MONGODB_CONNECTION_STRING: מחרוזת החיבור למסד הנתונים שלכם ב-MongoDB, לדוגמה mongodb+srv://store-user:storeuser@ecommerce-cluster.g8vaekh.mongodb.net
    • ‫FALLBACK_IMAGE_URL: כתובת ה-URL של תמונת הגיבוי, לדוגמה https://storage.googleapis.com/ecommerce-app-images/fallback.jpg

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

10. סקירת האפליקציה

  1. לוחצים על קטלוג מוצרים כדי לראות את כל המוצרים.
    קטלוג מוצרים
  2. לוחצים על סמל של מוצר כדי לראות את פרטי המוצר. אפשר לראות שהתמונות מגיעות מ-Cloud Storage, פרטי המוצרים מגיעים מ-MongoDB ומלאי המוצרים מגיע מ-AlloyDB.פרטי המוצר
  3. אינטראקציה עם קטלוג המוצרים כדי ליצור תצוגות ופעולות כתיבה מדומה שנשלחות אל MongoDB.
  4. לוחצים על ETL וניתוח נתונים כדי לראות את ניתוח הנתונים של המוצר. תראו שהניתוח של המוצר נשלף מ-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 multi-db-app --region us-central1 --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://ecommerce-app-images
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

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

gcloud projects delete $PROJECT_ID

12. מזל טוב

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

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

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

מסמכים לדוגמה

מידע נוסף על מוצרים קשורים של Google Cloud ועל סדנאות ה-codelab האלה:

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