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

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

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

لأنّنا لا نكتفي بمطابقة الكلمات الرئيسية. نستخدم "مجموعة أدوات MCP" للسماح لموظفي الدعم لدينا "بالتفكير" في جميع هذه المصادر، أي في صحة المعاملات في 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

تفعيل واجهات برمجة التطبيقات المطلوبة

نفِّذ الأمر التالي لتفعيل جميع واجهات برمجة التطبيقات المطلوبة:

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 كمستودع ضخم لأصول الوسائط غير المنظَّمة، مثل صور المنتجات.

  1. في Google Cloud Console، انتقِل إلى Cloud Storage، ثم انقر على إنشاء حزمة.
  2. امنح الحزمة اسمًا فريدًا على مستوى العالم (مثل ecommerce-app-images).
  3. انقر على إنشاء.
  4. للسماح لتطبيق العرض التوضيحي بالوصول إلى الصور بدون مصادقة، أزِل العلامة من الخيار فرض منع الوصول العام إلى هذا الحزمة، ثم انقر على تأكيد.
  5. انتقِل إلى علامة التبويب الأذونات.
  6. في الأذونات، انقر على منح الوصول.
  7. في الأعضاء الجدد، أدخِل allUsers.
  8. في اختيار دور، اختَر Cloud Storage > مستخدم كائنات في Cloud Storage.
  9. انقر على حفظ، ثم انقر على السماح بالوصول العام لتأكيد أنّك ستتيح الوصول إلى المرجع للجميع.

تحميل صور العناصر النائبة

يستخدم BRK2-149-multidb-ecommerce صورًا نائبة لضمان أفضل تجربة مرئية.

  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 Console، انتقِل إلى Cloud Storage، ثم انقر على الحِزم.
  4. انقر على اسم الحِزمة التي أنشأتها حديثًا.
  5. انقر على تحميل > تحميل ملفات، واختَر الصور النموذجية التي تم تنزيلها، ثم انقر على فتح.

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. في التوفّر على مستوى المنطقة، اختَر منطقة واحدة.
  3. بالنسبة إلى نوع الجهاز، اختَر نوع جهاز صغيرًا (مثل N2، و4 وحدات معالجة مركزية افتراضية، و32 غيغابايت من ذاكرة الوصول العشوائي).
  4. في الاتصال عبر عنوان IP خاص، اختَر اتصال الخدمات الخاصة (PSA)، ثم اختَر شبكة default.إذا لم يتم ضبط الشبكة التلقائية من قبل، انقر على تأكيد إعداد الشبكة لإنشاء شبكة.
  5. في إمكانية الاتصال بعنوان IP العلني، ضَع علامة في مربّع الاختيار تفعيل عنوان IP العلني لكي تتصل مجموعة أدوات MCP بشكلٍ سليم في هذا الدرس العملي.
  6. في الشبكات الخارجية المعتمَدة، أدخِل 0.0.0.0/0. ضَع علامة في مربّع الاختيار أقرّ بالمخاطر وانقر على حفظ.
  7. انقر على إنشاء مجموعة.

ملاحظة: احرص على تدوين عنوان IP العام (يبدو مشابهًا لـ 34.124.240.26).

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

  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، انتقِل إلى المجلد 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);

إنشاء تضمينات صور ليتمكّن وكيل الذكاء الاصطناعي من استرداد منتجات مشابهة

يستخدم دمج وكيل الذكاء الاصطناعي تضمينات الصور لجلب منتجات مشابهة. يتم إنشاء عمليات التضمين باستخدام نموذج multimodalembedding@001 وتخزينها في قاعدة بيانات AlloyDB. تكون عمليات التضمين عبارة عن متّجهات ذات 1408 بُعد ويتم تخزينها في العمود img_embeddings.

قبل أن نتمكّن من إنشاء التضمينات، يجب منح الأدوار المطلوبة لحساب خدمة AlloyDB للوصول إلى Cloud Storage.

منح أدوار لحساب خدمة AlloyDB للوصول إلى Cloud Storage

نمنح حساب خدمة AlloyDB دورَي "مستخدم عنصر في مساحة التخزين" و"مشاهد عنصر في مساحة التخزين" لتمكينه من قراءة العناصر من حزمة Cloud Storage.

  1. انتقِل إلى إدارة الهوية وإمكانية الوصول (IAM) والمشرف.
  2. انقر على منح إذن الوصول.
  3. في حقل المشرفون الجدد، أدخِل عبارة البحث عن حساب خدمة AlloyDB. يبدو حساب الخدمة مشابهًا لـ service-991742412753@gcp-sa-alloydb.iam.gserviceaccount.com.
  4. انقر على اختيار دور.
  5. ابحث عن دور مستخدم كائنات التخزين واختَره.
  6. انقر على إضافة دور آخر واختَر دور الاطّلاع على الكائنات في Cloud Storage.
  7. انقر على إضافة دور آخر واختَر دور مستخدم Vertex AI.
  8. انقر على حفظ.

تفعيل الإضافات

لإنشاء هذا التطبيق، سنستخدم الإضافتين 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. أنشئ تضمينات للصور وخزِّنها في العمود 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 مرات على الأقل لإنشاء تضمينات صور للمجموعة بأكملها، لأنّ مدة استخدام Studio محدودة بـ 5 دقائق. إذا انتهت مهلة طلب البحث هذا، غيِّر LIMIT إلى 5 وأعِد تشغيل طلب البحث عشر مرات. قد يستغرق إكمال هذه الخطوة بضع دقائق.

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

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

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

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

ضبط إعدادات الوصول إلى الشبكة

  1. في وحدة تحكّم Atlas، انتقِل إلى الوصول إلى قاعدة البيانات والشبكة.
  2. انقر على قائمة عناوين IP المسموح لها بالوصول.
  3. انقر على إضافة عنوان IP.
  4. أضِف 0.0.0.0/0، ما يتيح الوصول إلى الموقع من أي مكان.
  5. انقر على تأكيد.

إنشاء مستخدم قاعدة بيانات

  1. في وحدة تحكّم Atlas، انتقِل إلى الوصول إلى قاعدة البيانات والشبكة.
  2. انقر على مستخدمو قاعدة البيانات.
  3. انقر على إضافة مستخدم جديد لقاعدة البيانات.
  4. اختَر كلمة المرور كطريقة المصادقة.
  5. أدخِل اسم المستخدم store-user وكلمة المرور storeuser.
  6. انقر على إضافة دور مضمّن، ثم اختَر القراءة والكتابة في أي قاعدة بيانات.
  7. انقر على إضافة مستخدم.

الحصول على سلسلة الاتصال

  1. انتقِل إلى قاعدة البيانات > المجموعات > ربط.
  2. في قسم ربط تطبيقك، انقر على برامج التشغيل.
  3. انسخ سلسلة الاتصال المعروضة في إضافة سلسلة الاتصال إلى الرمز البرمجي للتطبيق. يبدو السلسلة على النحو التالي:
    mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
    استبدِل db_password بكلمة مرور MongoDB. في هذا الدرس التطبيقي حول الترميز، تكون القيمة storeuser.

احفظ سلسلة الاتصال هذه. ستستخدمها لاحقًا لمتغيّر البيئة MONGODB_CONNECTION_STRING.

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

  1. في وحدة تحكّم Atlas، انتقِل إلى قاعدة البيانات > المجموعات > تصفُّح المجموعات.
  2. انقر على إنشاء قاعدة بيانات وأدخِل التفاصيل:
    • اسم قاعدة البيانات: ecommerce_db
    • اسم المجموعة: product_details_collection
  3. انقر على إنشاء قاعدة بيانات.
  4. في "مستكشف البيانات"، اختَر "اسم المجموعة".
  5. انقر على رمز إضافة بيانات (+)، ثم انقر على إدراج مستند.
  6. انسخ محتوى JSON من product_details_export.json والصقه في مربّع الحوار الخاص بمحرّر إدراج مستند.
  7. انقر على إدراج لإدراج مجموعة المستندات وتأكَّد من إضافة 192 مستندًا.
  8. في "مستكشف البيانات"، انقر على إنشاء مجموعة (+) بجانب قاعدة بيانات ecommerce_db.
  9. أدخِل user_interactions_collection لاسم المجموعة، ثم انقر على إنشاء مجموعة.
  10. في "مستكشف البيانات"، اختَر المجموعة user_interactions_collection.
  11. انقر على رمز إضافة بيانات (+)، ثم انقر على إدراج مستند.
  12. انسخ محتوى JSON من user_interactions_export.json والصقه في مربّع الحوار الخاص بمحرّر إدراج مستند.
  13. انقر على إدراج مستند.

6. إعداد BigQuery

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

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

  1. في Google Cloud Console، انتقِل إلى BigQuery.
  2. بجانب رقم تعريف مشروعك في جزء "المستكشف"، انقر على قائمة النقاط الثلاث ثم على إنشاء مجموعة بيانات.
  3. أدخِل ecommerce_analytics في حقل معرّف مجموعة البيانات.
  4. انقر على إنشاء مجموعة بيانات.

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

  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 المستخدَم في "أدوات Google للمطوّرين". يتم ذلك للسماح لأداة MCP Toolbox بالوصول إلى BigQuery وSecret Manager وخدمات السحابة الإلكترونية الأخرى.

لمنح الأدوار، أكمِل الخطوات التالية:

  1. انتقِل إلى إدارة الهوية وإمكانية الوصول (IAM) والمشرف.
  2. انقر على منح إذن الوصول.
  3. في حقل المشرفون الجدد، أدخِل حساب خدمة Compute التلقائي باسم YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. استبدِل YOUR_PROJECT_NUMBER برقم مشروعك على Google Cloud.
  4. انقر على اختيار دور.
  5. ابحث عن دور محرِّر بيانات في BigQuery واختَره.
  6. انقر على إضافة دور آخر واختَر دور مستخدم وظائف BigQuery.
  7. انقر على إضافة دور آخر واختَر دور Secret Manager Secret Accessor.
  8. انقروا على إضافة دور آخر واختاروا الدور محرِّر.
  9. انقر على حفظ.

7. فهم عملية تقديم الطلب من البداية إلى النهاية

للتعرّف على كيفية عمل كل مكوّن مع المكوّنات الأخرى، سننشئ تطبيقًا بسيطًا للتجارة الإلكترونية يستخدم قواعد بيانات وخدمات متعددة. تم إنشاء التطبيق باستخدام الخلفية البرمجية 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"
  • ‫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 منتجات" على مستوى ملايين الأحداث.
  • مستودع التخزين السحابي: أنشئ حزمة عامة لتخزين صور المنتجات العالية الدقة، مع التأكّد من إمكانية الوصول إلى كل مادة عرض من خلال عنوان 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" مصادر البيانات المتعددة لدينا، ما يتيح لتطبيقنا جلب البيانات وكتابتها بشكل موحّد.

تثبيت 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 المستخدَم في "أدوات Google للمطوّرين". يتم ذلك للسماح لمجموعة أدوات MCP بالوصول إلى AlloyDB.

  1. انتقِل إلى إدارة الهوية وإمكانية الوصول (IAM) والمشرف.
  2. انقر على منح إذن الوصول.
  3. في حقل المشرفون الجدد، أدخِل حساب خدمة Compute التلقائي باسم YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. استبدِل YOUR_PROJECT_NUMBER برقم مشروعك على Google Cloud.
  4. انقر على اختيار دور.
  5. ابحث عن دور محرِّر بيانات في BigQuery واختَره.
  6. انقر على إضافة دور آخر واختَر دور عميل AlloyDB.
  7. انقر على إضافة دور آخر واختَر دور مستهلك استخدام الخدمة.
  8. انقر على إضافة دور آخر واختَر دور الاطّلاع على الكائنات في Cloud Storage.
  9. انقر على حفظ.

اختبار واجهة مستخدم الأداة

  1. في وحدة Cloudshell الطرفية، شغِّل مجموعة الأدوات محليًا لعرض واجهة المستخدِم:
    ./toolbox --ui
  2. افتح "معاينة الويب" في Cloud Shell على المنفذ 5000 وانتقِل إلى صفحة الأدوات. على سبيل المثال، استنادًا إلى عنوان URL الخاص بالجلسة، يمكنك الاطّلاع عليه على: https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui

تظهر واجهة مستخدم صندوق أدوات MCP التالية:

واجهة مستخدم &quot;مجموعة أدوات MCP&quot;

النشر على 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 إلى كل عنصر.

إنشاء مسار تطبيق محرّك الاستدلال

لتهيئة وكيل الذكاء الاصطناعي وتسجيله باستخدام Vertex AI Reasoning Engine من Google Cloud، نفِّذ الأمر التالي:

  1. في وحدة Cloudshell الطرفية، انتقِل إلى المجلد 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:
    # 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 Ecommerce. سيكون عنوان URL مشابهًا لـ https://polyglot-*********-uc.a.run.app/.

10. استكشاف التطبيق

  1. انقر على كتالوج المنتجات لعرض جميع المنتجات.
    كتالوج المنتجات
  2. انقر على رمز المنتج لعرض تفاصيله. ستلاحظ أنّ الصور مصدرها Cloud Storage، ويتم استرداد تفاصيل المنتج من MongoDB، ويتم استرداد مستودع المنتجات من AlloyDB.تفاصيل المنتج
  3. التفاعل مع كتالوج المنتجات لإنشاء عمليات قراءة وكتابة وهمية يتم إرسالها إلى MongoDB
  4. انقر على استخراج البيانات وتحويلها وتحميلها والإحصاءات لعرض إحصاءات المنتج. ستلاحظ أنّه يتم جلب إحصاءات المنتج من 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 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 Cloud بأكمله وجميع موارده، نفِّذ الأمر التالي:

gcloud projects delete $PROJECT_ID

12. تهانينا

تهانينا! لقد أنشأت بنجاح بنية Multidb متوافقة مع عدة خدمات سحابية.

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

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

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

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

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