إنشاء سلسلة إمداد مستقلة باستخدام Gemini 3 Flash وAlloyDB AI

1. نظرة عامة

لقد انتهى عصر "برامج الدردشة التي تقرأ". نحن على أعتاب عصر الرؤية المستندة إلى الذكاء الاصطناعي الوكيل.

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

سننشئ وكيل سلسلة توريد مستقل باستخدام حلقة التفكير والتنفيذ والمراقبة الجديدة في Gemini 3 Flash. فهو لا يكتفي بالنظر، بل يبحث عن التفاصيل.

البنية الحتمية

سنبدأ بنظام "أعمى" و "فاقد للذاكرة". عليك "تنشيط" حواسه يدويًا واحدة تلو الأخرى:

‫Eyes (وكيل الرؤية): نفعّل Gemini 3 Flash من خلال تنفيذ الرموز البرمجية. بدلاً من توقّع الرموز المميزة لتخمين رقم، يكتب النموذج رمز Python البرمجي (OpenCV) لاحتساب وحدات البكسل بشكل حتمي.
الذاكرة (وكيل المورّد): نتيح استخدام AlloyDB AI مع ScaNN (البحث عن أقرب الجيران القابل للتوسيع). ويسمح ذلك للوكيل بتذكُّر المورّد الدقيق لقطعة غيار من بين ملايين الخيارات في غضون أجزاء من الثانية.
المصافحة (بروتوكول A2A): نتيح التواصل بين الوكلاء باستخدام ملف agent_card.json موحّد، ما يسمح لـ "وكيل الرؤية" بطلب المخزون بشكل مستقل من "وكيل المورّد".

ما ستنشئه

وكيل مرئي ينفّذ "عمليات حسابية مرئية" على خلاصات الكاميرا
Supplier Agent المستند إلى AlloyDB ScaNN للبحث السريع عن المتجهات
واجهة أمامية Control Tower تتضمّن تحديثات WebSocket في الوقت الفعلي لتصوّر حلقة القيادة الذاتية

أهداف الدورة التعليمية

كيفية تفعيل Agentic Vision باستخدام gemini-3-flash-preview من خلال Gemini API
كيفية تنفيذ البحث المتّجهي باستخدام عامل التشغيل <=> (مسافة جيب التمام) في AlloyDB
كيفية ربط Cloud Shell بـ AlloyDB باستخدام الخادم الوكيل للمصادقة

المتطلبات

متصفّح، مثل Chrome أو Firefox
مشروع Google Cloud تم تفعيل الفوترة فيه
مفتاح Gemini API (تتوفّر طبقة مجانية في Google AI Studio) لـ Vision Agent

2. قبل البدء

إنشاء مشروع

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

ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".

صورة زر تفعيل Cloud Shell

بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على معرّف مشروعك باستخدام الأمر التالي:

gcloud auth list

هذا كل شيء!

أنت الآن جاهز لعملية الإعداد بنقرة واحدة. سيتضمّن القسم التالي ما يلي:

فتح Cloud Shell تلقائيًا
إنشاء نسخة طبق الأصل من المستودع
إرشادك خلال عملية الإعداد بالكامل في برنامج تعليمي تفاعلي

3- الإعداد بنقرة واحدة في Cloud Shell

لقد بسّطنا عملية الإعداد لتصبح برنامجًا تعليميًا إرشاديًا في Cloud Shell. تتم أتمتة كل شيء، بما في ذلك توفير البنية الأساسية وإعداد AlloyDB وإعداد Auth Proxy وتعبئة قاعدة البيانات.

تشغيل البرنامج التعليمي الخاص بـ Cloud Shell

⚠️ ملاحظة مهمة - قبل النقر: عند النقر على الزر أدناه، سيظهر مربّع حوار أمان يسألك "هل تريد الفتح في Cloud Shell؟". يظهر هذا الخيار قبل استنساخ المستودع.

يجب تنفيذ ما يلي:

✅ ضَع علامة في المربّع: "مستودع موثوق"
✅ انقر على تأكيد

وبدون ذلك، لن يتم استنساخ المستودع.

هل أنت جاهز؟ انقر لفتح المشروع مع دليل توجيهي مفصّل:

ما سيحدث بعد ذلك:

يتم فتح Cloud Shell مع استنساخ المستودع مسبقًا
تظهر لوحة تعليمية على يسار الصفحة تتضمّن تعليمات مفصّلة
سنساعدك في تنفيذ ما يلي:

الحصول على مفتاح Gemini API (تتوفّر فئة مجانية)
ضبط مشروع Google Cloud Platform في الجهاز الطرفي
تنفيذ عملية الإعداد (التحقّق من واجهات برمجة التطبيقات وتفعيلها إذا لزم الأمر، وتوفير AlloyDB: ‏15 دقيقة تقريبًا)
إجراء تغييران رئيسيان على الرمز (تفعيل ميزة "الرؤية" و"الذاكرة")
إنشاء بطاقة الوكيل (بروتوكول A2A)
بدء جميع الخدمات

الدليل التعليمي تفاعلي، إذ يتم ترقيم كل خطوة وتتبُّع مستوى تقدّمك.

بديل: الإعداد اليدوي

إذا كنت تفضّل التحكّم يدويًا:

افتح Cloud Shell وتأكَّد من ضبط مشروعك

gcloud config get-value project

اضبط مشروعك إذا لزم الأمر

gcloud config set project YOUR_PROJECT_ID

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

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb

تشغيل عملية الإعداد

sh setup.sh

اتّبِع التعليمات الظاهرة على الشاشة من نص الإعداد البرمجي.

الخطوات التالية: يرشدك البرنامج التعليمي إلى الخطوات المتبقية. بعد اكتمال العملية، انتقِل إلى القسم 4 للتعرّف على تفاصيل العملية

4. Behind the Scenes: Auth Proxy & Database Seeding

المشكلة: يتم تشغيل AlloyDB داخل سحابة VPC خاصة. لا تندرج Cloud Shell ضمن هذه الفئة. لا يمكن إجراء اتصال مباشر.

الحلّ: ينشئ AlloyDB Auth Proxy اتصالاً نفقياً آمنًا تمت المصادقة عليه باستخدام "إدارة الهوية وإمكانية الوصول" (IAM) من 127.0.0.1:5432 على Cloud Shell إلى مثيل AlloyDB. إذا كان عنوان IP العام مفعَّلاً على الجهاز الظاهري، سيستخدمه الخادم الوكيل، وإلا سيتصل عبر عنوان IP الخاص بشبكة VPC.

الإجراءات التي نفّذها النص البرمجي setup.sh

تم رصد مثيل AlloyDB (المجموعة والمنطقة والمشروع) تلقائيًا
أنشئ ملف .env يتضمّن جميع بيانات الاعتماد (GEMINI_API_KEY وDB_PASS وتفاصيل AlloyDB).
تم تنزيل Auth Proxy وبدء تشغيله (باستخدام ‎–public-ip إذا كان ذلك منطبقًا)
تمت إضافة 8 عيّنات من أجزاء المستودع + فهرس ScaNN إلى قاعدة البيانات

ملف ‎ .env جاهز. يتم تحميل بيانات الاعتماد تلقائيًا في جميع عمليات التشغيل المستقبلية.

التأكّد من نجاح العملية

التأكّد من أنّك لا تزال في جذر المستودع

pwd  # Should end with: visual-commerce-gemini-3-alloydb

التأكّد من أنّ خادم المصادقة الوكيل يعمل

ps aux | grep alloydb-auth-proxy

ما تم إنشاؤه

جدول المستودع الذي يتضمّن 8 أجزاء وتضمينات ذات 768 بُعدًا
فهرس ScaNN (idx_inventory_scann) للبحث السريع عن المتجهات

5- الخطوة 1: الذاكرة (وكيل المورّد)

يتذكّر "وكيل المورّد" ملايين الأجزاء باستخدام AlloyDB ScaNN. نبدأ تشغيله كخادم A2A، ثم نصلح استعلام المتّجه.

The Audit: The Amnesiac

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

بدء استخدام "وكيل المورّد"

يتم تفويض خادم A2A (ملف main.py) إلى agent_executor.py، الذي يربط البروتوكول بمنطق النشاط التجاري في inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

الخطوة 1: الانتقال إلى دليل الوكيل

cd agents/supplier-agent

الخطوة 2: تثبيت التبعيات

pip install -r requirements.txt

الخطوة 3: بدء تشغيل خادم البرنامج الوكيل

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

يؤدي الأمر > /dev/null 2>&1 & إلى تشغيل الخادم في الخلفية وإخفاء الناتج حتى لا تتم مقاطعة الوحدة الطرفية.

الخطوة 4: التحقّق من أنّ الوكيل يعمل (انتظِر من ثانيتين إلى ثلاث ثوانٍ بعد البدء)

curl http://localhost:8082/.well-known/agent-card.json

الناتج المتوقّع: ملف JSON يتضمّن إعدادات الوكيل (يجب أن يتم عرضه بدون أخطاء)

Real Semantic Embeddings

أثناء عملية الإعداد، تمّت إضافة عمليات تضمين دلالية حقيقية إلى قاعدة البيانات تم إنشاؤها باستخدام نموذج text-embedding-005 من حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي من Google. يضمن ذلك مطابقة التشابه بدقة، وليس مطابقة المتجهات العشوائية. تستغرق عملية التضمين الأولي حوالي 10 ثوانٍ لـ 13 عنصرًا نموذجيًا باستخدام إنشاء التضمين المتوازي لإنشاء متجهات ذات 768 بُعدًا تعكس المعنى الدلالي لكل جزء.

استراحة مع AlloyDB: لماذا ScaNN؟

الحلّ: تنفيذ عامل التشغيل <=>

يتم شحن الوكيل مع طلب بحث عن عنصر نائب. علينا تفعيل ميزة البحث المتّجهي في ScaNN.

الخطوة 1: فتح ملف المستودع

cd agents/supplier-agent

الخطوة 2: العثور على TODO في ملف inventory.py

ابحث عن الدالة find_supplier() في الأسطر من 47 إلى 60 تقريبًا. وسترى ما يلي:

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

الخطوة 3: استبدال عنصر نائب SQL بعملية البحث المتّجهي في ScaNN

احذف هذين السطرين:

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

واستبدالها بما يلي:

sql = """
SELECT part_name, supplier_name
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_vector,))

وظيفة هذا الإعداد:

‫<=> هو عامل تشغيل مسافة جيب التمام في PostgreSQL
يؤدي ORDER BY part_embedding <=> %s::vector إلى العثور على أقرب تطابق (أقل مسافة = أقرب معنى دلالي).
يحوّل %s::vector مصفوفة التضمين إلى نوع المتّجه في PostgreSQL
تعرض LIMIT 1 أقرب نتيجة مطابِقة فقط
يعمل فهرس ScaNN تلقائيًا على تسريع عملية البحث هذه.

الخطوة 4: حفظ الملف (Ctrl+S أو Cmd+S)

سيستخدم الوكيل الآن البحث الدلالي بدلاً من عرض نتائج عشوائية.

التحقّق

اختبِر ميزة "التطبيق إلى التطبيق" والمستودع على النحو التالي:

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

النتيجة المتوقّعة: يعرض الملف agent-card.json بطاقة الوكيل. تعرض مقتطفة Python جزءًا ومورّدًا من البيانات الأولية.

الأخطاء الشائعة:

"لا وجود لمثل هذا الملف أو الدليل": أنت لست في جذر المستودع. نفِّذ الأمر cd للانتقال إلى الصفحة الرئيسية، ثم نفِّذ الأمر cd visual-commerce-gemini-3-alloydb، أو استخدِم الأمر pwd لمعرفة مكانك.
المنفذ 8082 قيد الاستخدام: إنهاء العملية الحالية: lsof -ti:8082 | xargs kill -9
ModuleNotFoundError: ثبِّت العناصر التابعة: pip install -r requirements.txt
تعذّر الاتصال بقاعدة البيانات: تأكَّد من أنّ الخادم الوكيل للمصادقة لا يزال قيد التشغيل
تعذُّر تنفيذ نص التحقّق: تأكَّد من إكمال عملية إنشاء القيمة الأولية بنجاح في الخطوة 4

6. الخطوة 2: العيون (Vision Agent)

بما أنّ قاعدة البيانات متاحة، لنوقظ العينَين باستخدام Gemini 3 Flash. يُجري Vision Agent "عمليات حسابية مرئية" من خلال ميزة "تنفيذ الرموز البرمجية". يتم تفويض خادم A2A (main.py) إلى agent_executor.py، الذي يستدعي agent.py لتحليل Gemini.

التدقيق: الهلوسة

إذا طلبت من نموذج عادي متعدد الوسائط "كم عدد المربّعات في هذه الصورة غير المرتبة؟"، سيعالج الصورة كلقطة ثابتة ويخمّن الإجابة.

يقول النموذج: "أرى حوالي 12 مربعًا".
الواقع: هناك 15 صندوقًا.
النتيجة: تعذُّر إكمال سلسلة الإمداد.

الحلّ: إحياء حلقة "التفكير، واتخاذ الإجراءات، والمراقبة"

نفعِّل تنفيذ الرمز وThinkingConfig لكي يكتب النموذج رمز Python (OpenCV) من أجل إجراء عملية العد بشكل حتمي.

افتح الملف agents/vision-agent/agent.py .
ابحث عن قسم GenerateContentConfig.
أزِل التعليق من كلّ من كتلة thinking_config=types.ThinkingConfig(...) وtools=[types.Tool(code_execution=...)] .
تمّت إعداد العميل مسبقًا لاستخدام مفتاح GEMINI_API_KEY من البيئة.

الملف: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

لماذا thinking_level="LOW"؟

بالنسبة إلى هذه المهمة المحدّدة (احتساب العناصر من خلال تنفيذ الرمز البرمجي)، يوفّر المستوى "منخفض" ميزانية كافية للاستدلال من أجل:

تخطيط بنية نص Python البرمجي
تحديد طريقة معالجة الصور التي تريد استخدامها
تأكَّد من أنّ العدد يطابق عدد المربّعات المحيطة

سيؤدي استخدام القيمة "عالية" إلى زيادة وقت الاستجابة والتكلفة بمقدار 2 إلى 3 مرّات بدون تحسين الدقة في المهام المحدّدة. احجز القيمة "عالية" للاستدلال المعقّد المتعدّد الخطوات (مثل "حلِّل هذا التعطيل في سلسلة الإمداد واقتَرِح 3 مورّدين بديلين مع تقديم مبرّرات").

تحسين التكلفة والأداء: هذه مهارة أساسية في هندسة الذكاء الاصطناعي في مرحلة الإنتاج، وهي تتطلّب مطابقة عمق الاستدلال مع مدى تعقيد المهمة.

بدء استخدام "الوكيل البصري"

🔄 التحقّق من المسار: إذا كنت لا تزال في agents/supplier-agent/، عليك أولاً الرجوع إلى جذر المستودع باستخدام cd ../..

الخطوة 1: الانتقال إلى دليل وكيل Vision

cd agents/vision-agent

الخطوة 2: تثبيت التبعيات

pip install -r requirements.txt

الخطوة 3: بدء تشغيل خادم البرنامج الوكيل للرؤية

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

يؤدي الأمر > /dev/null 2>&1 & إلى تشغيل الخادم في الخلفية وإخفاء الناتج حتى لا تتم مقاطعة الوحدة الطرفية.

التحقّق

اختبار ميزة "التطبيقات أثناء الاستخدام":

curl http://localhost:8081/.well-known/agent-card.json

المتوقّع: ملف JSON يتضمّن اسم الوكيل ومهاراته ستختبر عملية احتساب عدد الزيارات الفعلية باستخدام واجهة مستخدم "برج التحكّم" في الخطوة 8.

الأخطاء الشائعة:

"لا وجود لمثل هذا الملف أو الدليل": أنت لست في جذر المستودع. استخدِم cd ../.. للرجوع إلى جذر المستودع، أو تحقَّق من موقعك الجغرافي باستخدام pwd.
المنفذ 8081 قيد الاستخدام: إنهاء العملية الحالية: lsof -ti:8081 | xargs kill -9
لم يتم ضبط GEMINI_API_KEY: تأكَّد من أنّ ملف ‎ .env موجود في جذر المستودع باستخدام cat .env | grep GEMINI_API_KEY
مفتاح واجهة برمجة التطبيقات غير صالح: تأكَّد من أنّ المفتاح صحيح ولم تنتهِ صلاحيته
لم يتم العثور على google-genai: ثبِّت التبعيات: pip install -r requirements.txt

7. الخطوة 3: المصافحة (بطاقة وكيل A2A)

يرى الوكيل المشكلة (الرؤية) ويعرف المورّد (الذاكرة). يتيح بروتوكول A2A الاكتشاف الديناميكي، حيث يتعرّف الواجهة الأمامية على كيفية التواصل مع كل وكيل من خلال قراءة بطاقته.

مقارنة بين واجهات برمجة التطبيقات A2A وواجهات برمجة تطبيقات REST التقليدية

Aspect	REST التقليدي	بروتوكول A2A
استكشاف نقاط النهاية	عناوين URL المرمّزة في الإعداد	ديناميكية من خلال ‎ /.well-known/agent-card.json
وصف الإذن	مستندات واجهة برمجة التطبيقات (للمستخدمين)	المهارات (يمكن معالجتها آليًا)
التكامل	رمز يدوي لكل خدمة	المطابقة الدلالية: "أحتاج إلى البحث في المستودع" → اكتشاف مهارة
تمت إضافة وكيل جديد	تعديل جميع إعدادات العملاء	بدون إعدادات، يتم اكتشافها تلقائيًا

الميزة في الواقع العملي: في الخدمة المصغّرة التقليدية، إذا أضفت "وكيل لوجستي" ثالثًا، عليك تعديل رمز "برج المراقبة" باستخدام عنوان URL وعقد واجهة برمجة التطبيقات. باستخدام A2A، يكتشف Control Tower الجهاز تلقائيًا ويفهم إمكاناته من خلال أوصاف المهارات باللغة الطبيعية.

لهذا السبب، تتيح بنية A2A تركيب وكيل التوصيل والتشغيل، وهو النمط المعماري للأنظمة المستقلة.

الحلّ: إنشاء بطاقة الوكيل

علينا تحديد الإجراءات التي يمكن أن ينفّذها "وكيل المورّد".

انسخ الملف agents/supplier-agent/agent_card_skeleton.json إلى agents/supplier-agent/agent_card.json.
عدِّل الملف لاستبدال العناصر النائبة:

قبل (المخطط):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

بعد (تعديلاتك):

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

أعِد تشغيل Supplier Agent ليتم تحميل البطاقة الجديدة:

الخطوة 1: إيقاف العامل قيد التشغيل

pkill -f "uvicorn main:app.*8082"

الخطوة 2: الانتقال إلى دليل الوكلاء

cd agents/supplier-agent

الخطوة 3: إعادة تشغيل الوكيل

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

يؤدي الأمر > /dev/null 2>&1 & إلى تشغيل الخادم في الخلفية وإخفاء الناتج حتى لا تتم مقاطعة الوحدة الطرفية.

الخطوة 4: التحقّق من بطاقة الوكيل الجديدة (انتظِر من ثانيتين إلى ثلاث ثوانٍ بعد البدء)

curl http://localhost:8082/.well-known/agent-card.json

الناتج المتوقّع: ملف JSON يتضمّن الاسم والوصف والمهارات التي أدخلتها.

8. الخطوة 4: "برج المراقبة"

تشغيل الواجهة الأمامية لخدمة Control Tower باستخدام FastAPI + WebSockets تكتشف هذه المنصة الوكلاء من خلال A2A وتنسّق العملية الكاملة مع إرسال إشعارات في الوقت الفعلي.

بدء جميع الخدمات

أسهل طريقة لبدء جميع الخدمات:

التأكّد من أنّك في جذر المستودع

pwd  # Should end with: visual-commerce-gemini-3-alloydb

بعد ذلك، يُرجى اتّباع الخطوات التالية:

sh run.sh

يبدأ هذا الأمر الفردي:

AlloyDB Auth Proxy (في حال عدم تشغيله)
Vision Agent على المنفذ 8081
وكيل المورّد على المنفذ 8082
Control Tower على المنفذ 8080

انتظِر لمدة 10 ثوانٍ تقريبًا حتى يتم إعداد جميع الخدمات.

اختبار النظام

الوصول إلى Control Tower:

انقر على الزر معاينة الويب (رمز العين 👁️) في شريط أدوات Cloud Shell
انقر على المعاينة على المنفذ 8080.
سيتم فتح لوحة بيانات Control Tower في علامة تبويب جديدة.

تشغيل العرض التوضيحي:

أعلى يسار الشاشة: حالة الاتصال (نقطة خضراء "مباشر")، زر تبديل وضع العرض التوضيحي/التلقائي، وعناصر التحكّم في الصوت
المركز: لوحة عرض سير العمل الرئيسية التي تتضمّن تحميل الصور وعرض التحليل
اللوحات الجانبية (تظهر أثناء التحليل): المخطط الزمني لسير العمل (على اليمين)، وتتبُّع مستوى التقدّم وعارض الرموز (على اليسار)

الخيار 1: البدء السريع (مقترَح)

في الصفحة الرئيسية، سيظهر قسم البدء السريع يتضمّن صورًا نموذجية.
انقر على أي صورة نموذجية لبدء التحليل تلقائيًا
مشاهدة سير العمل المستقل (من 30 إلى 45 ثانية تقريبًا)

الخيار 2: تحميل ملفك الخاص

سحب صورة مستودع أو رف وإفلاتها (PNG أو JPG، حتى 10 ميغابايت) أو النقر للتصفّح
انقر على بدء سير العمل المستقل
مراقبة مسار الإحالة الناجحة المكوّن من 4 مراحل

ما يحدث:

اكتشاف الوكيل: تعرض النوافذ المنبثقة لبروتوكول A2A بطاقات Vision Agent وSupplier Agent مع مهاراتهما ونقاط النهاية
تحليل الصور: ينشئ Gemini 3 Flash رموز Python البرمجية (OpenCV) وينفّذها لاحتساب عدد العناصر. يعرض شريط التقدّم الخطوات الفرعية. تتراكب مربّعات الحدود على العناصر التي تم رصدها. تظهر شارة النتيجة "✓ تم التحقّق من الرمز" أو "~ تقديرية"
مطابقة المورّد: صورة متحرّكة للبحث المتّجه في AlloyDB ScaNN عمليات عرض طلب البحث (مثل "industrial metal boxes"). تعرض بطاقة النتائج الجزء المطابق والمورّد ونسبة التطابق
تم تقديم الطلب: بطاقة إيصال تتضمّن رقم تعريف الطلب والكمية والتفاصيل

ملاحظة: أبقِ "وضع العرض التوضيحي" مفعّلاً (أعلى يسار الشاشة) للإيقاف مؤقتًا في كل مرحلة من مراحل العروض التقديمية. في الوضع AUTO، يتم تشغيل سير العمل بشكل مستمر.

ما الذي حدث للتو؟

استخدمت Control Tower بروتوكول A2A لاكتشاف كلا الوكيلين من خلال ‎ /.well-known/agent-card.json، ونظّمت عملية تحليل الصور (Gemini 3 Flash مع تنفيذ التعليمات البرمجية)، وأجرت بحثًا متّجهًا (AlloyDB ScaNN)، وقدّمت طلبًا مستقلاً، وكل ذلك مع تلقّي إشعارات WebSocket في الوقت الفعلي. يعرض كل وكيل إمكاناته من خلال معيار A2A، ما يتيح إنشاء تركيبات جاهزة للاستخدام بدون حِزم SDK مخصّصة. مزيد من المعلومات: بروتوكول A2A

تحديد المشاكل وحلّها

الأخطاء المتعلّقة بالمسار:

يظهر الخطأ "No such file or directory" عند تنفيذ الأوامر: أنت لست في جذر المستودع.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

أخطاء الخدمة:

"العنوان قيد الاستخدام": لا تزال العمليات من عمليات التشغيل السابقة نشطة.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

عدم بدء الخدمات: تحقَّق مما إذا كانت المنافذ مشغولة:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

"تم رفض الاتصال" بـ AlloyDB: تأكَّد من أنّ الخادم الوكيل للمصادقة يعمل:

ps aux | grep alloydb-auth-proxy

مشاكل الاتصال بـ AlloyDB:

إذا ظهرت لك الرسالة "تعذّر الاتصال بالخادم على العنوان 127.0.0.1، المنفذ 5432":

إذا ظهرت لك الرسالة "تعذّر الاتصال بالخادم على العنوان 127.0.0.1، المنفذ 5432"، اتّبِع الخطوات التالية:

التحقّق من خادم وكيل المصادقة: ps aux | grep alloydb-auth-proxy
التحقّق من تفعيل عنوان IP العام: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
للتطوير المحلي (وليس Cloud Shell):
المشكلة: يعمل Cloud Shell تلقائيًا، ولكن تحتاج الأجهزة المحلية إلى شبكات معتمَدة
الحلّ: أعِد تشغيل sh setup.sh واختَر الخيار 1 (السماح لـ 0.0.0.0/0) عند الطلب.
ملاحظة بشأن الأمان: حتى مع استخدام 0.0.0.0/0، يتطلّب الاتصال ما يلي:
بيانات اعتماد Google Cloud Platform صالحة (بيانات الاعتماد التلقائية للتطبيق)
كلمة مرور قاعدة البيانات
تشفير TLS المتبادل (يتولّى الخادم الوكيل للمصادقة هذه العملية)

9- تنظيف

لتجنُّب تحمّل رسوم، يجب إتلاف جميع الموارد باستخدام النص البرمجي المبرمَج للتنظيف:

# From repo root
sh cleanup.sh

تؤدي هذه الخطوة إلى إزالة ما يلي بشكل آمن:

مجموعة AlloyDB (المحدّد الأساسي للتكلفة)
خدمات Cloud Run (في حال نشرها)
حسابات الخدمة المرتبطة

سيطلب منك النص البرمجي التأكيد قبل حذف أي شيء.

10. المراجع والمحتوى الإضافي للقراءة

تم التحقّق من جميع الادعاءات الفنية الواردة في هذا الدرس العملي من مستندات Google Cloud وGoogle AI الرسمية.

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

‫Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
دليل المطوّرين: https://ai.google.dev/gemini-api/docs/gemini-3
مستندات النموذج: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
بطاقة النموذج: https://deepmind.google/models/gemini/flash/

‫AlloyDB AI وScaNN:

معايير أداء ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
التعرّف على فهرس ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
نظرة تفصيلية على AlloyDB AI: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
أفضل الممارسات في الضبط: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
مستندات AlloyDB: ‏ https://cloud.google.com/alloydb/docs

معلومات التسعير:

أسعار Gemini API: https://ai.google.dev/gemini-api/docs/pricing
أسعار AlloyDB: https://cloud.google.com/alloydb/pricing
أسعار Vertex AI: https://cloud.google.com/vertex-ai/pricing

مطالبات الأداء التي تم التحقّق منها

الميزة	المطالبة	المصدر
مقارنة بين ScaNN وHNSW (تمت فلترتها)	أسرع بـ 10 مرّات	مدونة Google Cloud (تم التحقّق منها)
مقارنة بين ScaNN وHNSW (عادي)	أسرع 4 مرات	مدونة Google Cloud (تم التحقّق منها)
استهلاك ذاكرة ScaNN	أصغر بمقدار 3 إلى 4 مرات	مدونة Google Cloud (تم التحقّق منها)
مدة إنشاء فهرس ScaNN	أسرع بـ 8 مرّات	مدونة Google Cloud (تم التحقّق منها)
مهلة تنفيذ الرمز البرمجي	‫30 ثانية كحد أقصى	مستندات Google Cloud (تم التحقّق منها)
ملف إدخال/إخراج لتنفيذ الرموز البرمجية	غير متاح	مستندات Google Cloud (تم التحقّق منها)
سلوك درجة الحرارة=0	الناتج الحتمي	تم التحقّق من صحة المعلومات بواسطة المنتدى

موارد إضافية

بروتوكول التواصل بين الوكلاء (A2A):

تعمل A2A على توحيد طريقة اكتشاف الوكلاء والتواصل معهم
بطاقات الوكلاء المعروضة في /.well-known/agent-card.json
معيار جديد للتعاون بين البرامج المستقلة

أبحاث ScaNN:

استنادًا إلى 12 عامًا من أبحاث Google
يتوافق مع "بحث Google" وYouTube على نطاق واسع
تاريخ الإصدار المتاح للجميع: أكتوبر 2024
أول فهرس متّجه في PostgreSQL مناسب للملايين إلى المليارات من المتّجهات

11. وضع "التحدي": حسِّن مهاراتك في استخدام الذكاء الاصطناعي

لقد أنشأت سلسلة توريد مستقلة تعمل بشكل جيد. هل أنت مستعد للمضي قدمًا؟ تطبّق هذه التحديات الأنماط التي تعلّمتها على مشاكل جديدة.

التحدي 1: البحث المستند إلى الصور (عمليات التضمين المتعدّدة الوسائط)

المسار الحالي: يحسب Vision Agent عدد العناصر → ينشئ طلب بحث نصيًا → يضمّن Supplier Agent النص → يبحث في AlloyDB

التحدي: تخطّي النص بالكامل وإرسال الصورة التي تم اقتصاصها مباشرةً إلى "وكيل المورّد"

تلميحات:

يمكن أن يؤدي تنفيذ رمز Vision Agent إلى اقتصاص عناصر فردية من صورة الرف.
يمكن لنموذج multimodalembedding@001 في Vertex AI تضمين الصور مباشرةً
تعديل ملف inventory.py لقبول وحدات بايت للصور بدلاً من النص
تعديل وصف مهارة "التطبيق إلى التطبيق" للإشارة إلى "يقبل: صورة/jpeg أو نص"

أهمية ذلك: يكون البحث المرئي أكثر دقةً للأجزاء التي لها مظاهر معقّدة (اختلافات في الألوان، وتلف، واختلافات في التغليف).

التحدّي 2: إمكانية المراقبة، أي الثقة من خلال الشفافية

الحالة الحالية: يعمل النظام، ولكن لا يمكنك الاطّلاع على التفاصيل

التحدي: افحص سجلّات طلبات البحث في AlloyDB لإثبات أنّ البحث المتّجه يتم تنفيذه.

الخطوات:

يتم تفعيل "إحصاءات الطلبات" تلقائيًا على AlloyDB. لإثبات الملكية، نفِّذ الأمر التالي:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

إجراء بحث عن المورّد من خلال واجهة المستخدم
عرض لغة الاستعلامات البنيوية (SQL) التي تم تنفيذها:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

الناتج المتوقّع: سيظهر لك الجزء ORDER BY part_embedding <=> $1::vector LIMIT 1 من طلب البحث مع وقت التنفيذ.

أهمية ذلك: تساهم إمكانية المراقبة في بناء الثقة. عندما يسأل أصحاب المصلحة "كيف يتخذ هذا الوكيل القرارات؟"، يمكنك عرض خطة الطلب عليهم، وليس الناتج فقط.

التحدي 3: التركيب المتعدد للوكلاء

التحدي: أضِف وكيلاً ثالثًا (وكيل الخدمات اللوجستية) يحتسب تكاليف الشحن استنادًا إلى الموقع الجغرافي للمستودع ووزن السلعة.

البنية:

نتائج Vision Agent: عدد العناصر
نتائج Supplier Agent: موقع المورّد
مدخلات "وكيل الخدمات اللوجستية" (جديد): الوجهة والوزن → المخرجات: تكلفة الشحن + وقت الوصول المقدَّر

تلميح: يسهّل بروتوكول A2A هذه العملية، إذ يمكنك إنشاء بطاقة وكيل جديدة تتضمّن مهارة calculate_shipping. سيرصدها "مركز التحكّم" تلقائيًا.

النمط الذي تتعلّمه: هذا هو جوهر البنية المستندة إلى الوكلاء، أي الأنظمة المعقّدة التي يتم إنشاؤها من متخصصين صغار وقابلين للتركيب.

12. الخاتمة

لقد انتقلت بنجاح من الذكاء الاصطناعي التوليدي إلى الذكاء الاصطناعي المستند إلى الوكلاء.

ما أنشأناه:

الرؤية: استبدلنا "التخمين" بتنفيذ الرموز البرمجية (Gemini 3 Flash من خلال مفتاح واجهة برمجة التطبيقات).
الذاكرة: استبدلنا "البحث البطيء" بـ AlloyDB ScaNN (عبر Google Cloud Platform).
الإجراء: استبدلنا "دمج واجهة برمجة التطبيقات" ببروتوكول A2A.

مزايا الهندسة المختلطة:

عرض هذا الدرس التطبيقي حول الترميز نهجًا مختلطًا:

Vision Agent: يستخدم Gemini API (مفتاح واجهة برمجة التطبيقات) - درجة تسعير بسيطة ومجانية متاحة، ولا يلزم توفّر فوترة على Google Cloud Platform
وكيل المورّد: يستخدم منصة Google Cloud (‫Vertex AI + AlloyDB) - مصمّم للمؤسسات وجاهز للامتثال

هذه هي بنية الاقتصاد المستقل. يمكنك الاحتفاظ بالرمز.

الخطوات التالية

الحصول على مفتاح Gemini API (تتوفّر درجة مجانية)
استكشاف مستندات Gemini API
الاطّلاع على مستندات AlloyDB AI
استكشاف ميزة "تنفيذ التعليمات البرمجية" في Gemini