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 + חיפוש וקטורי): כדי ליצור תמונה בסגנון דומה ל-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 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. בקטע Zonal Availability (זמינות אזורית), בוחרים באפשרות Single zone (אזור יחיד).
  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 (קישוריות של IP ציבורי), מסמנים את התיבה Enable Public IP (הפעלת IP ציבורי) כדי שכלי ה-MCP יתחברו בצורה תקינה בסדנת התכנות הזו.
  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. בוחרים באפשרות Built-in authentication כדי להיכנס למסד הנתונים.
  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 נקודות) ובוחרים באפשרות יצירת מערך נתונים.
  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: מאחסן פרטים על ההגדרה וההטמעה של 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.
  • ‫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, והגדרתו כגשר מרכזי מבוסס-REST שתפקידו לתרגם כוונות בשפה טבעית לשאילתות במספר מסדי נתונים.
  • הגדרה של tools.yaml: מגדירים את הכלים, כמו get_product_core_data או get_top_5_views, וממפים פעולות ספציפיות ב-SQL וב-NoSQL לשמות פשוטים שהסוכן יכול לקרוא.
  • לוגיקה של קצה עורפי ב-Flask: הטמעת מסלולים ב-app.py שמתקשרים עם MCP Toolbox, טיפול בתיאום של אחזור נתונים ושימוש כ-API לממשק המשתמש.
  • תיאום בין סוכנים: אפשר להגדיר את סוכני ה-ADK בקוד כדי להסיק את כוונת המשתמש ולבחור את ה'כלי' המתאים לפתרון שאילתות מורכבות של קמעונאים ממקורות שונים.
  • שילוב קצה קדמי: יוצרים ממשק HTML שכולל את קטלוג המוצרים עם תכונת תיעוד האינטראקציות, כרטיסיית Analytics להבנת ניתוח הביצועים של המוצרים וכרטיסייה ייעודית של סוכן שמשתמשת בצ'אט מרובה סוכנים של ADK כדי לספק חוויית קנייה חלקה.

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

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

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

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

  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

פריסה ב-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: השם של קטגוריה של 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 הזו, אפשר לעיין במקורות הבאים: