إنشاء فهرس ذكي للتجارة الإلكترونية مع إمكانية استمرار البيانات في قواعد بيانات متعددة

1. مقدمة

في مجال البيع بالتجزئة الحديث، تشكّل بياناتك نظامًا شاملاً متنوعًا وواسع النطاق. لديك بيانات معاملات قوية (الأسعار والمستودع)، وكتالوجات متعددة الأشكال "غير منظَّمة" (مواصفات الأجهزة الإلكترونية مقابل مقاسات الملابس)، وبيانات سلوكية بحجم بيتابايت. إنّ فرض هذه الميزات في تطبيق واحد لا يؤدي إلى تراكم الديون التقنية فحسب، بل يقضي على تجربة المستخدم.

في هذا الدرس التطبيقي حول الترميز، ستصمّم تطبيق 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 + وكلاء متعدّدون): يتطلّب تحليل المراجعات بحثًا عن "متانة الحزام" من الوكيل تلخيص الملاحظات غير المنظَّمة من BigQuery بشكل فوري.

معظم برامج التتبُّع في مجال البيع بالتجزئة ستتعرّف على كلمتَي "حقيبة ظهر" و"جلدية" فقط وتعرض 10 حقائب ظهر جلدية. كيف نمنع ذلك؟

لأنّنا لا نطابق الكلمات الرئيسية فقط. نستخدم MCP Toolbox للسماح لوكلائنا بـ "استنتاج" البيانات الصحيحة للمعاملات في AlloyDB والسمات المرنة في MongoDB في الوقت نفسه في جميع هذه المصادر. لنبدأ في إنشائه!

الإجراءات التي ستنفذّها

  • توفير مجموعة AlloyDB لبيانات المنتجات الأساسية
  • إعداد MongoDB Atlas على Google Cloud لتخزين تفاصيل المنتجات شبه المنظَّمة
  • إنشاء حزمة Cloud Storage لعرض صور المنتجات
  • نشر MCP Toolbox for Databases على Cloud Run للوصول إلى البيانات بشكل موحّد
  • تنفيذ عمليات الاستخراج والتحويل والتحميل (ETL) لإرسال البيانات إلى BigQuery من أجل تحليلها
  • التحدّث مع وكيل الذكاء الاصطناعي بلغة طبيعية

بنية قواعد بيانات متعددة للتجارة الإلكترونية

المتطلبات الأساسية

2. قبل البدء

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة أداة اختيار المشاريع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق من تفعيل الفوترة في مشروع

بدء 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

3- إعداد Cloud Storage

تُعدّ خدمة Cloud Storage مخزنًا ضخمًا لملفات الوسائط غير المنظَّمة، مثل صور المنتجات.

  1. في Google Cloud Console، انتقِل إلى Cloud Storage، وانقر على إنشاء حزمة.
  2. أدخِل اسمًا فريدًا عالميًا للحزمة، مثل -ecommerce-images.
  3. انقر على إنشاء.
  4. للسماح للتطبيق التجريبي بالوصول إلى الصور بدون مصادقة، عليك إزالة العلامة من الخيار فرض منع الوصول العام إلى هذا المستودع، ثم النقر على تأكيد.
  5. انتقِل إلى علامة التبويب الأذونات.
  6. في الأذونات، انقر على منح إذن الوصول.
  7. في حقل المستخدمون الأساسيون الجدد، أدخِل allUsers.
  8. في اختيار دور، اختَر Cloud Storage > مُشاهد عناصر مساحة التخزين.
  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/

4. إعداد AlloyDB

يُعدّ AlloyDB المصدر الوحيد للحقيقة للبيانات المنظَّمة والمعاملات والبيانات المهمة، مثل معرّفات المنتجات والأسماء وأرقام SKU والأسعار والمستودع. ويوفّر AlloyDB أيضًا لوكيل الذكاء الاصطناعي إمكانات البحث عن التشابه لتقديم الاقتراحات وطلبات البحث باللغة الطبيعية.

توفير مجموعة AlloyDB

  1. في Google Cloud Console، انتقِل إلى AlloyDB for PostgreSQL.
  2. انقر على إنشاء مجموعة.
  3. في حقل معرّف المجموعة، أدخِل ecommerce-cluster.
  4. اضبط كلمة مرور قوية للمستخدم postgres. لأغراض التعلّم، يمكنك استخدام alloydb.
  5. بالنسبة إلى إصدار قاعدة البيانات، احتفِظ بالإعداد التلقائي.
  6. في حقل المنطقة، اختَر us-central1 (أو منطقتك المفضّلة).

ضبط المثيل الأساسي

  1. في حقل رقم تعريف المثيل، أدخِل ecommerce-cluster-primary.
  2. في Zonal availability (مدى التوفّر في المنطقة)، اختَر Single zone (منطقة واحدة).
  3. بالنسبة إلى سلسلة الأجهزة، اختَر N2، وبالنسبة إلى نوع الجهاز، اختَر 4 vCPU, 32 GB.
  4. في إمكانية الاتصال عبر عنوان IP خاص، اختَر اتصال الخدمات الخاصة (PSA)، ثم اختَر شبكة default.إذا لم تكن الشبكة التلقائية مضبوطة من قبل، انقر على تأكيد إعداد الشبكة لإنشاء شبكة.
  5. في إمكانية الاتصال بعنوان IP العلني (Public IP Connectivity)، ضَع علامة في مربّع الاختيار تفعيل عنوان IP العلني (Enable Public IP) لكي يتم ربط مجموعة أدوات MCP بشكل صحيح في هذا الدرس التطبيقي حول الترميز. تفعّل وحدة التحكّم تلقائيًا العلامة password.enforce_complexity التي تتطلّبها AlloyDB لعنوان IP العام.
  6. في الشبكات الخارجية المعتمَدة، أدخِل 0.0.0.0/0. ضَع علامة في المربّع أقرّ بالمخاطر وانقر على حفظ.
  7. انقر على إنشاء مجموعة.

إعداد قاعدة البيانات

  1. انقر على AlloyDB Studio من قائمة التنقّل اليمنى.
  2. في القائمة المنسدلة قاعدة البيانات، اختَر postgres.
  3. اختَر المصادقة المضمّنة لتسجيل الدخول إلى قاعدة البيانات.
  4. بالنسبة إلى اسم المستخدم، استخدِم المستخدم postgres.
  5. في حقل Password (كلمة المرور)، أدخِل كلمة المرور التي أعددتها سابقًا.
  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. التضمينات هي متّجهات ذات 1408 بُعد ويتم تخزينها في العمود 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 Console، انتقِل إلى AlloyDB for 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، ثم انقر على تشغيل. يستغرق ذلك دقيقة واحدة تقريبًا. إذا انتهت مهلة النص البرمجي، يمكنك تشغيله مرة أخرى، وسيتم تخطّي المنتجات التي تتضمّن تضمينات.

5- إعداد MongoDB Atlas على Google Cloud

تخزّن MongoDB تفاصيل المنتجات الغنية وشبه المنظَّمة وبيانات سلوك المستخدمين المرنة (مثل النقرات والمشاهدات).

إنشاء مجموعة MongoDB

  1. سجِّل الدخول إلى MongoDB Atlas (أنشئ حسابًا مجانيًا إذا لزم الأمر).
  2. في صفحة Deploy your cluster (نشر المجموعة)، اختَر Free (مجاني). (يختار Atlas مسبقًا فئة مدفوعة، لذا تأكَّد من اختيار "مجاني").
  3. في حقل مقدّم الخدمة، اختَر Google Cloud، وفي حقل المنطقة، اختَر آيوا (us-central1).
  4. في حقل الاسم، أدخِل ecommerce-cluster، وأزِل العلامة من المربّع تحميل مجموعة بيانات نموذجية مسبقًا.
  5. انقر على إنشاء عملية نشر.

السماح بالوصول وإنشاء مستخدم قاعدة بيانات

يفتح Atlas مربّع الحوار Connect to ecommerce-cluster (الاتصال بمجموعة التجارة الإلكترونية).

  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. انقر على إنشاء قاعدة بيانات (Create Database).
  3. في "مستكشف البيانات"، اختَر "اسم المجموعة".
  4. انقر على رمز إضافة بيانات (+)، ثم انقر على إدراج مستند.
  5. انسخ محتوى JSON من product_details_export.json والصقه في مربّع حوار محرِّر إدراج مستند.
  6. يعرض Atlas بانرًا يقترح تحويل النص إلى بنية Shell. انقر على تحويل، ثم انقر على إدراج. تأكَّد من إضافة 192 مستندًا.
  7. في "مستكشف البيانات" (Data Explorer)، انقر على إنشاء مجموعة (+) بجانب قاعدة بيانات ecommerce_db.
  8. أدخِل user_interactions_collection لاسم المجموعة، وانقر على إنشاء مجموعة.
  9. في "مستكشف البيانات"، اختَر مجموعة user_interactions_collection.
  10. انقر على رمز إضافة بيانات (+)، ثم انقر على إدراج مستند.
  11. انسخ محتوى JSON من user_interactions_export.json والصقه في مربّع حوار محرِّر Insert Document (إدراج مستند).
  12. يعرض Atlas بانرًا يقترح تحويل النص إلى بنية Shell. انقر على تحويل، ثم انقر على إدراج. تأكَّد من إضافة 211 مستندًا.

6. إعداد BigQuery

تجمع BigQuery سلوك المستخدمين السابق وتحلّله لإنشاء تقارير واقتراحات ذكية.

إنشاء مجموعة البيانات

  1. في Google Cloud Console، انتقِل إلى BigQuery.
  2. بجانب رقم تعريف المشروع في لوحة "المستكشف"، انقر على قائمة الخيارات الإضافية واختَر إنشاء مجموعة بيانات.
  3. أدخِل ecommerce_analytics في حقل رقم تعريف مجموعة البيانات.
  4. في حقل موقع البيانات، اختَر US (multiple regions) (يتطلّب إعداد tools.yaml الموقع الجغرافي US).
  5. انقر على إنشاء مجموعة بيانات.

إنشاء جدول الإحصاءات

  1. افتح طلب بحث جديدًا في مساحة عمل BigQuery.
  2. نفِّذ عبارة SQL التالية لإنشاء جدول الملخّص الذي يربط المستخدمين بالتفاعلات مع المنتجات:
CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

منح الأدوار لحساب خدمة Compute Engine

امنح حساب خدمة Compute Engine التلقائي الأدوار التي يحتاجها 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

بدلاً من ذلك، في وحدة التحكّم، انتقِل إلى إدارة الهوية وإمكانية الوصول والمشرف > إدارة الهوية وإمكانية الوصول، وانقر على منح إذن الوصول، وأدخِل حساب الخدمة، وأضِف الأدوار نفسها.

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 لعمليات قواعد البيانات المتعددة.
  • ‫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: يمكنك نشر Toolbox على Cloud Run، ما يجعله جسر RESTful مركزيًا يترجم طلبات اللغة الطبيعية إلى طلبات بحث في قواعد بيانات متعددة.
  • إعدادات Tools.yaml: حدِّد "الأدوات"، مثل get_product_core_data أو get_top_5_views، لربط عمليات SQL وNoSQL محدّدة بأسماء بسيطة يمكن للوكيل قراءتها.
  • منطق الخلفية في Flask: يمكنك تنفيذ مسارات app.py التي تتفاعل مع MCP Toolbox، والتعامل مع تنسيق استرداد البيانات والعمل كواجهة برمجة تطبيقات لواجهة المستخدم.
  • تنسيق الوكلاء المتعدّدين: يمكنك ضبط وكلاء ADK ضمن الرمز البرمجي للاستدلال من خلال نية المستخدم، واختيار "الأداة" المناسبة لحلّ طلبات البحث المعقّدة والمتعدّدة المصادر في مجال البيع بالتجزئة.
  • دمج الواجهة الأمامية: أنشِئ واجهة index.html تتضمّن كتالوج المنتجات مع ميزة تسجيل التفاعلات، وعلامة التبويب "الإحصاءات" لفهم إحصاءات أداء المنتجات، و"علامة تبويب الوكيل" المخصّصة التي تستخدم محادثة 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. استبدِل العناصر النائبة ***** بقيمك:

    قاعدة البيانات

    الحقل

    مثال للقيمة

    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 إلى نهاية عنوان URL الذي يفتح.

تظهر واجهة مستخدم مجموعة أدوات 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. احفظ عنوان 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 إلى كل عنصر.

إنشاء "محرك الوكيل"

  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.

نشر الواجهة الأمامية على 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. انقر على علامة التبويب وكيل الذكاء الاصطناعي للتفاعل مع وكيل الذكاء الاصطناعي. اطرح أسئلة بلغة طبيعية، مثل:
    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.
    وكيل الذكاء الاصطناعي

يمكنك ملاحظة أنّ البحث يعرض بالضبط ما طلبناه: حقيبة ظهر بدون مكوّنات جلدية، متوفّرة في المخزون، ولا تتضمّن المراجعات أي شكاوى بشأن متانة أحزمتها.

وكيل الذكاء الاصطناعي

11. تَنظيم

لتجنُّب تحصيل رسوم مستمرة من حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها خلال هذا الدرس التطبيقي حول الترميز.

نفِّذ أوامر 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 Console، انتقِل إلى Vertex AI > Agent Engine واحذف المثيل.

اختياريًا، لحذف مشروع Google Cloud بالكامل وجميع موارده، نفِّذ الأمر التالي:

gcloud projects delete $PROJECT_ID

12. تهانينا

تهانينا! لقد نجحت في إنشاء بنية Multidb متعددة السحابة الإلكترونية.

لقد أوضحت كيف تعمل حزمة MCP Toolbox كعنصر ربط في بنية تطبيق حديث ومتخصّص. ومن خلال مطابقة قاعدة البيانات المناسبة مع المهمة المناسبة، حقّقت ما يلي:

  • عمليات كتابة البيانات المرنة: MongoDB لسجلات الأحداث.
  • اتساق المعاملات: AlloyDB لضمان سلامة البيانات الأساسية
  • إحصاءات عالية الأداء: BigQuery لذكاء الأعمال
  • التطوير الموحّد: واجهة خلفية واحدة بلغة Python تبسّط جميع التعقيدات باستخدام MCP Toolbox.

المستندات المرجعية

يمكنك الاطّلاع على مزيد من المعلومات حول منتجات Google Cloud ذات الصلة واستكشاف هذه الدروس التطبيقية حول الترميز:

لمزيد من المعلومات عن المنتجات المستخدَمة في هذا الدرس التطبيقي، يُرجى الاطّلاع على: