ساختن کاتالوگ تجارت الکترونیک هوشمند با پایداری چندپایگاه‌داده‌ای

۱. مقدمه

در خرده‌فروشی مدرن، داده‌های شما بوم‌سازگانی متنوع و گسترده است. داده‌های تراکنشی بسیار قابل‌اعتماد (قیمت‌گذاری و موجودی)، کاتالوگ‌های چندریختی «نامرتب» (مشخصات لوازم الکترونیکی درمقابل اندازه‌های پوشاک)، و پتابایت‌ها گزارش رفتاری دارید. وادار کردن این‌ها به تبدیل شدن به یک واحد یکپارچه نه‌تنها بدهی فنی ایجاد می‌کند، بلکه تجربه کاربری را نیز ازبین می‌برد.

در این codelab، یک Polyglot Powerhouse را طراحی خواهید کرد که موارد زیر را هماهنگ می‌کند:

  • AlloyDB: ستون فقرات تراکنشی شما برای سازگاری با سرعت بالا و جاسازی‌های تصویر.
  • MongoDB Atlas در Google Cloud: لایه کاتالوگ انعطاف‌پذیر و مستقل از طرح‌واره شما.
  • فضای ذخیره‌سازی ابری: مغز تحلیلی شما برای پیش‌بینی بی‌درنگ روندها.
  • BigQuery: انبار دیجیتال با وضوح بالا.

«سس مخفی»؟ از MCP Toolbox ویژه پایگاه‌های داده برای هماهنگ‌سازی و یکپارچه‌سازی هوشمندانه منابع داده درحال اجرا در Cloud Run به‌عنوان پل معنایی استفاده خواهید کرد، سپس برنامه گپ چندعاملی را بااستفاده از Agent Development Kit (ADK) مستقر خواهید کرد. شما فقط یک نوار جستجو نمی‌سازید؛ بلکه یک مغز خرده‌فروشی هوشمند می‌سازید که بافت را درک می‌کند، محدودیت‌ها را رعایت می‌کند، و شکاف بین داده‌های خام و قصد انسان را پر می‌کند.

پُرسمان غیرممکن کاربر

عوامل تجارت الکترونیک استاندارد در استدلال چندبعدی (ترکیب محدودیت‌های منفی، شباهت بصری، و موجودی هم‌زمان) ناموفق هستند. برای مثال، من معمولاً می‌خواهم با سایت خرده‌فروشی‌ای مثل این صحبت کنم:

«سلام، دارم برای سفر عکاسی در ارتفاعات برنامه‌ریزی می‌کنم. چند کوله‌پشتی مقاوم دربرابر آب‌وهوا به من نشان بده که ازنظر سبک شبیه به «AeroGlow Pro» باشند اما هیچ بخش چرمی نداشته باشند. همچنین به من بگو که آیا واقعاً در انبار موجود است یا نه و آیا عکاسان دیگر در مرورهایشان از دوام بند آن شکایت کرده‌اند یا نه.»

چرا این پُرسمان «قاتل نماینده» است:

  • شباهت دیداری (AlloyDB + جستجوی برداری): «ازنظر سبک مشابه AeroGlow Pro» نیاز به مقایسه جاسازی تصویر دارد.
  • محدودیت منفی (MongoDB): «بدون هیچ چرمی» نیاز به فیلتر کردن ازطریق مشخصه‌های تودرتو و انعطاف‌پذیری دارد که معمولاً در طرحواره SQL استاندارد وجود ندارند.
  • موجودی هم‌زمان (AlloyDB): «واقعاً در انبار موجود است» نیاز به بررسی تراکنشی زنده دارد (نه نمایه جستجوی قدیمی).
  • ترکیب معنایی (BigQuery + چندعاملی): تجزیه‌وتحلیل کردن بازخوردها برای «دوام بند» مستلزم آن است که عامل بازخورد بدون ساختار را از BigQuery به‌طور هم‌زمان خلاصه کند.

اکثر روبات‌های خرده‌فروشی فقط «کوله پشتی» و «چرم» را می‌بینند و ۱۰ کوله پشتی چرمی را نشان می‌دهند. چگونه جلوی آن را می‌گیریم؟

چون ما فقط کلیدواژه‌ها را مطابقت نمی‌دهیم. ما از MCP Toolbox استفاده می‌کنیم تا به عامل‌هایمان اجازه دهیم به‌طور هم‌زمان در همه این منابع، حقیقت تراکنشی در AlloyDB و مشخصه‌های انعطاف‌پذیر در MongoDB را «استدلال» کنند. بیایید بسازیمش!

آنچه انجام خواهید داد

  • خوشه AlloyDB را برای داده‌های محصول اصلی آماده کنید
  • پیکربندی MongoDB Atlas در Google Cloud برای ذخیره جزئیات نیمه‌ساختاریافته محصول
  • ایجاد کردن مخزن Cloud Storage برای ارائه تصاویر محصول
  • مستقر کردن MCP Toolbox برای پایگاه‌های داده در Cloud Run برای دسترسی یکنواخت به داده‌ها
  • اجرای فرایندهای ETL برای ارسال داده‌ها به BigQuery برای تجزیه‌وتحلیل
  • با عامل هوشواره‌ای به زبان طبیعی مکالمه کنید.

معماری چند پایگاه داده تجارت الکترونیک

پیش‌نیازها

۲. قبل‌از شروع

ایجاد پروژه Google Cloud

  1. در کنسول Google Cloud، در صفحه انتخابگر پروژه، پروژه Google Cloud را انتخاب یا ایجاد کنید.
  2. مطمئن شوید که صورت‌حساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.

شروع Cloud Shell

Cloud Shell محیطی با خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم ازقبل در آن بار شده است.

  1. روی فعال‌سازی 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)")

فعال کردن میاناهای برنامه‌سازی کاربردی لازم

این فرمان را برای فعال کردن همه میاناهای برنامه‌سازی کاربردی لازم اجرا کنید:

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

۳. راه‌اندازی فضای ذخیره‌سازی ابری

‫Cloud Storage به‌عنوان یک فضای ذخیره‌سازی عظیم برای دارایی‌های رسانه‌ای ساختارنیافته، مانند تصاویر محصول، عمل می‌کند.

  1. در «کنسول Google Cloud»، به Cloud Storage بروید و روی ایجاد کردن سطل کلیک کنید.
  2. نامی یکتا درسطح جهانی برای باکت خود انتخاب کنید، برای مثال -ecommerce-images.
  3. روی ایجاد کردن کلیک کنید.
  4. برای اینکه برنامه نمایشی بتواند بدون اصالت‌سنجی به تصاویر دسترسی داشته باشد، گزینه اجرای جلوگیری از دسترسی عمومی در این سطل را پاک کنید و روی تأیید کلیک کنید.
  5. به برگه اجازه‌ها بروید.
  6. در اجازه‌ها، روی اجازه دسترسی دادن کلیک کنید.
  7. در اصول جدید، allUsers را وارد کنید.
  8. در انتخاب نقش، فضای ذخیره‌سازی ابری > نمایشگر شیء فضای ذخیره‌سازی را انتخاب کنید.
  9. روی ذخیره کلیک کنید، و سپس روی مجاز کردن دسترسی عمومی کلیک کنید تا تأیید کنید که منبع را عمومی می‌کنید.
  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/

۴. راه‌اندازی AlloyDB

AlloyDB به‌عنوان منبع واحد حقیقت برای داده‌های ساختاریافته، تراکنشی، و حیاتی مانند شناسه‌های محصول، نام‌ها، SKU، قیمت‌ها، و موجودی عمل می‌کند. AlloyDB همچنین عامل هوشواره‌ای را با قابلیت‌های جستجوی شباهت برای توصیه‌ها و پُرسمان‌های زبان طبیعی تقویت می‌کند.

تأمین کردن خوشه AlloyDB

  1. در «کنسول Google Cloud»، به AlloyDB برای PostgreSQL بروید.
  2. روی ایجاد خوشه کلیک کنید.
  3. برای شناسه خوشه، ecommerce-cluster را وارد کنید.
  4. گذرواژه قوی برای کاربر postgres تنظیم کنید. برای اهداف یادگیری، می‌توانید از alloydb استفاده کنید.
  5. برای نسخه پایگاه داده، پیش‌فرض را حفظ کنید.
  6. برای منطقه، us-central1 (یا منطقه ترجیحی‌تان) را انتخاب کنید.

پیکربندی نمونه اصلی

  1. برای شناسه نمونه، ecommerce-cluster-primary را وارد کنید.
  2. در دردسترس بودن منطقه‌ای، تک‌منطقه‌ای را انتخاب کنید.
  3. برای سری ماشین، N2 را انتخاب کنید و برای نوع ماشین، 4 vCPU, 32 GB را انتخاب کنید.
  4. در اتصال‌پذیری IP خصوصی، دسترسی به سرویس‌های خصوصی (PSA) را انتخاب کنید و شبکه default را انتخاب کنید.اگر شبکه پیش‌فرض ازقبل تنظیم نشده است، روی تأیید راه‌اندازی شبکه کلیک کنید تا شبکه‌ای ایجاد شود.
  5. در اتصال IP عمومی، چارگوش انتخاب فعال کردن IP عمومی را انتخاب کنید تا جعبه‌ابزار MCP به‌درستی در این codelab متصل شود. کنسول به‌طور خودکار پرچم password.enforce_complexity را فعال می‌کند که AlloyDB برای IP عمومی به آن نیاز دارد.
  6. در شبکه‌های خارجی مجاز، 0.0.0.0/0 را وارد کنید. چارگوش خطرات را می‌پذیرم را انتخاب کنید و روی ذخیره کلیک کنید.
  7. روی ایجاد خوشه کلیک کنید.

مقداردهی اولیه پایگاه داده

  1. در منو پیمایش سمت راست، روی AlloyDB Studio کلیک کنید.
  2. در منو کرکره‌ای پایگاه داده، postgres را انتخاب کنید.
  3. برای ورود به سیستم پایگاه داده، اصالت‌سنجی داخلی را انتخاب کنید.
  4. برای نام کاربری، از کاربر postgres استفاده کنید.
  5. برای گذرواژه، گذرواژه‌ای را که قبلاً تنظیم کرده‌اید وارد کنید.
  6. روی اصالت‌سنجی کلیک کنید.
  7. در نمای ویرایشگر، برگه پُرسمان بدون عنوان جدیدی باز کنید.
  8. DDL زیر را کپی کنید و روی اجرا کلیک کنید:
    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 را جای‌گذاری کنید و روی اجرا کلیک کنید.
  12. در برگه پُرسمان بدون عنوان جدید، DDL زیر را کپی کنید و روی اجرا کلیک کنید تا نمایه‌ای در جدول products_core_table ایجاد شود:
    CREATE INDEX idx_products_core_sku ON products_core_table(sku);

ایجاد جاسازی‌های تصویر برای عامل هوش مصنوعی جهت واکشی محصولات مشابه

ادغام عامل هوش مصنوعی از جاسازی‌های تصویر برای واکشی محصولات مشابه استفاده می‌کند. جاسازی‌ها بااستفاده از مدل multimodalembedding@001 تولید می‌شوند و در پایگاه داده AlloyDB ذخیره می‌شوند. جاسازی‌ها بردارهای ۱۴۰۸ بعدی هستند و در ستون img_embeddings ذخیره می‌شوند.

قبل‌از اینکه بتوانیم جاسازی‌ها را تولید کنیم، باید نقش‌های لازم را به حساب سرویس AlloyDB اعطا کنیم تا به Cloud Storage دسترسی پیدا کند.

اعطا کردن نقش‌ها به حساب سرویس AlloyDB برای دسترسی به Cloud Storage

نقش‌هایی را که حساب سرویس AlloyDB برای خواندن تصاویر از «فضای ذخیره‌سازی ابری» و تولید جاسازی‌های 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 برای PostgreSQL بروید.
  2. در منو پیمایش سمت راست، روی AlloyDB Studio کلیک کنید.
  3. در نمای ویرایشگر، برگه پُرسمان بدون عنوان جدیدی باز کنید.
  4. DDL زیر را کپی کنید و روی اجرا کلیک کنید:
    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 جای‌گذاری کنید، و روی اجرا کلیک کنید. حدود یک دقیقه طول می‌کشد. اگر زمان آن تمام شد، دوباره آن را اجرا کنید؛ محصولاتی که ازقبل جاسازی دارند رد می‌شوند.

۵. راه‌اندازی MongoDB Atlas در Google Cloud

MongoDB جزئیات غنی و نیمه‌ساختاریافته محصول و داده‌های انعطاف‌پذیر رفتار کاربر (مانند کلیک‌ها و بازدیدها) را ذخیره می‌کند.

ایجاد خوشه MongoDB

  1. به سیستم MongoDB Atlas وارد شوید (درصورت نیاز، حساب رایگان ایجاد کنید).
  2. در استقرار خوشه، رایگان را انتخاب کنید. (Atlas ازقبل یک ردیف پولی را انتخاب می‌کند؛ مطمئن شوید «رایگان» انتخاب شده باشد.)
  3. برای ارائه‌دهنده، Google Cloud را انتخاب کنید و برای منطقه، آیووا (us-central1) را انتخاب کنید.
  4. برای نام، ecommerce-cluster را وارد کنید و پیش‌بار کردن مجموعه داده نمونه را پاک کنید.
  5. روی ایجاد استقرار کلیک کنید.

اجازه دادن به دسترسی و ایجاد کاربر پایگاه داده

Atlas کادر گفتگوی اتصال به خوشه تجارت الکترونیک را باز می‌کند.

  1. روی افزودن نشانی IP دیگر کلیک کنید، 0.0.0.0/0 را وارد کنید، و آن را اضافه کنید.
  2. store-user را برای نام کاربری و storeuser را برای گذرواژه وارد کنید، سپس روی ایجاد کاربر پایگاه داده کلیک کنید.
  3. روی انتخاب روش اتصال کلیک کنید، سپس روی کتابخانه‌های مشتری و درایورها کلیک کنید.
  4. در بخش از این رشته اتصال در برنامه‌تان استفاده کنید، رشته اتصال را کپی کنید. به‌نظر می‌رسد mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. را با storeuser جایگزین کنید و رشته را ذخیره کنید؛ از آن در tools.yaml استفاده خواهید کرد.

ایجاد پایگاه داده و مجموعه

  1. در پیمایش سمت راست، روی کاوشگر داده کلیک کنید، سپس روی ایجاد پایگاه داده کلیک کنید و جزئیات را وارد کنید:
    • نام پایگاه داده: ecommerce_db
    • نام مجموعه: product_details_collection
  2. روی ایجاد پایگاه داده کلیک کنید.
  3. در «کاوشگر داده»، «نام مجموعه» را انتخاب کنید.
  4. روی نماد افزودن داده (+) کلیک کنید، سپس روی درج سند کلیک کنید.
  5. محتوای JSON را از product_details_export.json کپی کنید و آن را در کادر گفتگوی ویرایشگر درج سند جای‌گذاری کنید.
  6. Atlas برنمایی را نشان می‌دهد که پیشنهاد می‌کند نوشتار به نحو پوسته تبدیل شود. روی تبدیل و سپس روی درج کلیک کنید. تأیید کنید که ۱۹۲ سند اضافه شده است.
  7. در «کاوشگر داده»، روی ایجاد مجموعه (+) در کنار پایگاه داده ecommerce_db کلیک کنید.
  8. user_interactions_collection را برای نام مجموعه وارد کنید و روی ایجاد مجموعه کلیک کنید.
  9. در «کاوشگر داده»، مجموعه user_interactions_collection را انتخاب کنید.
  10. روی نماد افزودن داده (+) کلیک کنید، سپس روی درج سند کلیک کنید.
  11. محتوای JSON را از user_interactions_export.json کپی کنید و آن را در کادر گفتگوی ویرایشگر درج سند جای‌گذاری کنید.
  12. Atlas برنمایی را نشان می‌دهد که پیشنهاد می‌کند نوشتار به نحو پوسته تبدیل شود. روی تبدیل و سپس روی درج کلیک کنید. تأیید کنید که ۲۱۱ سند اضافه شده است.

‫۶. راه‌اندازی BigQuery

‫BigQuery رفتار گذشته کاربر را تجمیع و تجزیه‌وتحلیل می‌کند تا گزارش‌دهی و توصیه‌های هوشمند تولید کند.

ساختن مجموعه داده

  1. در Google Cloud Console، به BigQuery بروید.
  2. در کنار شناسه پروژه در قاب «کاوشگر»، روی منوِ سه‌نقطه‌ای کلیک کنید و ایجاد مجموعه داده را انتخاب کنید.
  3. ecommerce_analytics را برای شناسه مجموعه داده وارد کنید.
  4. برای مکان داده، US (multiple regions) را انتخاب کنید (پیکربندی tools.yaml انتظار مکان US را دارد).
  5. روی ایجاد مجموعه داده کلیک کنید.

ایجاد کردن جدول 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 پیش‌فرض اعطا کنید:

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 کلیک کنید، حساب سرویس را وارد کنید، و همان نقش‌ها را اضافه کنید.

‫۷. آشنایی با برنامه از ابتدا تا انتها

برای آشنایی با نحوه عملکرد هر مؤلفه با مؤلفه‌های دیگر، یک برنامه تجارت الکترونیک ایجاد خواهیم کرد که از چندین پایگاه داده و سرویس استفاده می‌کند. این برنامه با باطن Python (Flask) ساخته شده است و چندین سرویس و پایگاه داده Google Cloud را ادغام می‌کند.

آشنایی با ساختار دایرکتوری

در بخش بعدی، مخزن polyglot-persist-ecommerce را شبیه‌سازی خواهید کرد و از آن برای اجرای برنامه به‌صورت محلی استفاده خواهید کرد. پس‌از آزمایش برنامه به‌صورت محلی، هم MCP Toolbox و هم برنامه را در Cloud Run مستقر خواهیم کرد.

فایل‌های بارگیری‌شده را در این فهرست کاوش کنید. فهرست‌های سطح بالای زیر وجود دارند:

  • ‫UploadImages: دارایی‌های تصویری را ذخیره می‌کند که عمدتاً برای مستندسازی یا محتوای دیداری برای کاتالوگ محصولات تجارت الکترونیک استفاده می‌شود.
  • static: دارایی‌های وب ایستا برنامه را ذخیره می‌کند، مانند فایل‌های CSS و جاوا اسکریپت، که برای سبک‌دهی و افزودن تعامل به میانای کاربر استفاده می‌شود ( منبع).
  • ‫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».
  • 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: مجموعه‌داده‌ای برای جمع‌آوری گزارش‌های تعامل ایجاد کنید تا امکان اجرای پُرسمان‌های تحلیلی پیچیده برای شناسایی «۵ مورد برتر» پرطرفدار در میان میلیون‌ها رویداد فراهم شود.
  • مخزن Cloud Storage: یک مخزن عمومی برای نگهداری تصاویر محصول با وضوح بالا ایجاد کنید و مطمئن شوید که هر دارایی بااستفاده از یک نشانی وب امضاشده یا عمومی برای بخش کاربری قابل‌دسترسی است.
  • استقرار MCP Toolbox: Toolbox را در Cloud Run مستقر کنید و آن را به‌عنوان پل مرکزی RESTful که قصد زبان طبیعی را به پُرسمان‌های چند پایگاه داده ترجمه می‌کند، ایجاد کنید.
  • پیکربندی Tools.yaml: «ابزارها» را تعریف کنید—مثل get_product_core_data یا get_top_5_views—و عملیات SQL و NoSQL خاص را به نام‌های ساده و قابل‌خواندن برای عامل نگاشت کنید.
  • منطق Flask Backend: مسیرهای app.py را که با MCP Toolbox تعامل دارند پیاده‌سازی کنید و هماهنگی بازیابی داده‌ها را مدیریت کنید و به‌عنوان API برای میانای کاربر عمل کنید.
  • سازمان‌دهی چندعاملی: عامل‌های ADK را در کد پیکربندی کنید تا ازطریق قصد کاربر استدلال کنند و «ابزار» مناسب را برای حل پرسمان‌های پیچیده و چندمنبعی خرده‌فروشی انتخاب کنند.
  • ادغام میانای کاربری: ساختن میانای index.html که کاتالوگ محصول را با ویژگی ضبط تعاملات، برگه Analytics برای درک تجزیه‌وتحلیل عملکرد محصول، و «برگه عامل» اختصاصی که از گپ چندعاملی ADK برای ارائه تجربه خرید مکالمه‌ای یکپارچه استفاده می‌کند نشان می‌دهد.

اکنون بیایید هماهنگ‌سازی و استقرار را پیاده‌سازی کنیم.

‫۸. راه‌اندازی MCP Toolbox و مستقر کردن در Cloud Run

«جعبه‌ابزار MCP» منابع داده چندگانه ما را خلاصه می‌کند و به برنامه ما اجازه می‌دهد داده‌ها را به‌طور یکنواخت واکشی و ثبت کند.

نصب محلی 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. جای‌بان‌های ***** را با مقادیر خودتان جایگزین کنید:

    پایگاه داده

    فیلد

    مقدار نمونه

    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، روی پیش‌نمایش وب > تغییر درگاه کلیک کنید، 5000 را وارد کنید، و /ui را به انتهای نشانی وب بازشده اضافه کنید.

میانای کاربری جعبه‌ابزار MCP زیر دیده می‌شود:

واسط کاربر جعبه‌ابزار MCP

وقتی کارتان تمام شد، 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 REST API را که برنامه وب استفاده می‌کند روشن می‌کند.
  3. نشانی وب جعبه ابزار را ذخیره کنید:
    export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
echo $TOOLBOX_URL
    می‌توانید $TOOLBOX_URL/ui را در مرورگرتان باز کنید تا ابزارها را ببینید.

‫۹. راه‌اندازی کردن برنامه تجارت الکترونیک و مستقر کردن آن در Cloud Run

با اجرای پایگاه‌های داده و استقرار انتزاع MCP Toolbox، می‌توانیم برنامه وب Flask را اجرا کنیم!

برای ارائه کاتالوگ محصول، برنامه Flask داده‌ها را با انجام مراحل زیر پردازش می‌کند:

  1. واکشی داده‌های اصلی: فهرست کامل محصولات را از AlloyDB بازیابی می‌کند (list_products_core).
  2. واکشی جزئیات گسترده: همه جزئیات محصول را از MongoDB بازیابی می‌کند (list_all_product_details).
  3. ترکیب کردن فهرست‌ها: دو فهرست را به‌هم متصل می‌کند.
  4. غنی‌سازی با رسانه: نشانی وب تصویر Cloud Storage را به هر مورد اضافه می‌کند.

ایجاد کردن «موتور عامل»

  1. وابستگی‌ها را نصب کنید:
    cd ~/polyglot-persist-ecommerce
pip install -r requirements.txt
    توجه: این مرحله ممکن است چند دقیقه طول بکشد تا بسته‌ها را حل‌وفصل و نصب کند.
  2. عامل هوش مصنوعی را بااستفاده از 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 ندارید.

مستقر کردن Frontend در 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"

برنامه‌تان اکنون فعال است! نشانی وب سرویس ارائه‌شده توسط Cloud Run را باز کنید تا کاتالوگ Multidb Ecommerce را ببینید. نشانی وب شبیه https://polyglot-*********-uc.a.run.app/ خواهد بود.

‫۱۰. کاوش برنامه

  1. برای مشاهده همه محصولات، روی کاتالوگ محصول کلیک کنید.
    کاتالوگ محصول
  2. برای مشاهده جزئیات محصول، روی نماد محصول کلیک کنید. متوجه خواهید شد که تصاویر از Cloud Storage منبع‌یابی می‌شوند، جزئیات محصول از MongoDB واکشی می‌شود، و موجودی محصول از AlloyDB واکشی می‌شود.جزئیات محصول
  3. با کاتالوگ محصول تعامل کنید تا نماهای ساختگی و نوشتن‌های ارسال‌شده به MongoDB را تولید کنید.
  4. برای مشاهده تجزیه‌وتحلیل محصول، روی ETL و Analytics کلیک کنید. متوجه خواهید شد که تجزیه‌وتحلیل محصول از BigQuery واکشی می‌شود.
    Product ETL and Analytics
  5. روی برگه عامل هوش مصنوعی کلیک کنید تا با عامل هوش مصنوعی تعامل کنید. سؤالات زبان طبیعی مانند موارد زیر بپرسید:
    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.
    عامل هوش مصنوعی

می‌بینید که جستجو دقیقاً همان چیزی را که خواسته بودیم برمی‌گرداند - کوله‌پشتی بدون اجزای چرمی، موجود در انبار، و بدون شکایت درباره دوام بند در مرورها.

عامل هوش مصنوعی

‫۱۱. مرتب‌سازی

برای جلوگیری از کسر هزینه‌های جاری از حساب Google Cloud خود، منابع ایجادشده درطول این codelab را حذف کنید.

این فرمان‌های پوسته ابری را اجرا کنید:

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

‫۱۲. تبریک می‌گوییم

تبریک! باموفقیت معماری Multidb بین‌ابری ساختید.

شما نشان دادید که چگونه MCP Toolbox به‌عنوان چسب معماری برای یک برنامه مدرن و تخصصی عمل می‌کند. با مطابقت دادن پایگاه داده مناسب با کار مناسب، به این موارد دست یافتید:

  • نوشتن داده‌های انعطاف‌پذیر: MongoDB برای گزارش‌های رویداد.
  • سازگاری تراکنشی: AlloyDB برای یکپارچگی هسته.
  • تحلیل با عملکرد بالا: BigQuery برای هوش تجاری.
  • توسعه یکپارچه: یک باطن Python واحد که همه پیچیدگی‌ها را بااستفاده از MCP Toolbox خلاصه می‌کند.

اسناد مرجع

درباره محصولات مرتبط Google Cloud بیشتر بدانید و این codelabs را کاوش کنید:

برای اطلاعات بیشتر درباره محصولات استفاده‌شده در این codelab، به موارد زیر مراجعه کنید: