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

1. نظرة عامة

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

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

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

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

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

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

ما ستنشئه

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

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

كيفية إعداد AlloyDB مع عمليات تضمين المتّجهات وفهارس ScaNN
كيفية تفعيل Agentic Vision باستخدام gemini-3-flash-preview من خلال Gemini API
كيفية تنفيذ البحث المتّجهي باستخدام عامل التشغيل <=> (مسافة جيب التمام) في AlloyDB
كيفية ربط العملاء الافتراضيين بـ AlloyDB باستخدام AlloyDB Python Connector
كيفية استخدام بروتوكول A2A لاكتشاف الوكلاء الديناميكي.

المتطلبات

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

2. قبل البدء

إنشاء مشروع

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

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

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

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

gcloud auth list

إعداد قاعدة البيانات [AlloyDB]

قبل أي شيء آخر، لنوفّر قاعدة البيانات، ويستغرق ذلك حوالي 15 دقيقة، لذا سنبدأ بهذه الخطوة أولاً.

انقر على الزر أدناه لفتح أداة إعداد AlloyDB في Cloud Shell:

نفِّذ عملية الإعداد:

Sh run.sh

استخدِم "معاينة الويب" (رمز العين 👁️ → المعاينة على المنفذ 8080) لفتح واجهة مستخدم الإعداد.
أدخِل رقم تعريف مشروعك، واختَر منطقة (مثل us-central1)، وأنشئ كلمة مرور لقاعدة البيانات.

⚠️ احفظ كلمة المرور هذه، لأنّك ستحتاج إليها عندما يطلبها منك نص الإعداد البرمجي.

انقر على "بدء النشر" (Start Deployment) وانتظِر حوالي 15 دقيقة إلى أن يتم توفير المجموعة.

الحصول على الرمز

أثناء توفير AlloyDB (أو بعد الانتهاء من ذلك)، افتح مستودع codelab في Cloud Shell:

⚠️ ملاحظة مهمة: عند النقر على الزر، سيظهر لك مربّع حوار الأمان. ضَع علامة في المربّع "الوثوق بالمستودع" وانقر على "تأكيد".

بدلاً من ذلك، يمكنك نسخ المستودع يدويًا باتّباع الخطوات التالية:

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

cd visual-commerce-gemini-3-alloydb

تحديد مشروعك

في نافذة Cloud Shell، تأكَّد من ضبط مشروعك على النحو التالي:

gcloud config set project <YOUR_PROJECT_ID>

تفعيل عنوان IP العلني على AlloyDB

بعد اكتمال عملية توفير AlloyDB، فعِّل عنوان IP العلني ليتمكّن Python Connector من الاتصال من Cloud Shell:

انتقِل إلى وحدة تحكّم AlloyDB.
انقر على مجموعتك → انقر على مثيلك الأساسي
انقر على "تعديل".
انتقِل إلى "إمكانية الاتصال بعنوان IP العلني" (Public IP Connectivity) وضَع علامة في المربّع بجانب "تفعيل عنوان IP العلني" (Enable Public IP).
انقر على "تعديل المثيل".

💡 ملاحظة: يتعامل AlloyDB Python Connector مع المصادقة والتشفير، لذا لن تحتاج إلى إضافة أي شبكات خارجية معتمَدة.

منح أذونات Vertex AI

يحتاج حساب خدمة AlloyDB إلى إذن الوصول إلى Vertex AI لإنشاء التضمينات. نفِّذ الأمر التالي في نافذة Cloud Shell نفسها:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

تشغيل نص الإعداد البرمجي

الآن، شغِّل نص الإعداد البرمجي، وسيتعرّف تلقائيًا على آلة AlloyDB الافتراضية:

sh setup.sh

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

التحقّق من gcloud CLI والمصادقة والمشروع وPython 3
التحقّق من واجهات برمجة التطبيقات المطلوبة وتفعيلها (AlloyDB وVertex AI وCompute وService Networking)
طلبات مفتاح Gemini API
رصد آلة AlloyDB الافتراضية تلقائيًا واستخراج المنطقة والمجموعة واسم الآلة الافتراضية
يطلب كلمة مرور قاعدة البيانات
إنشاء ملف الإعداد ‎ .env
تثبيت التبعيات في Python

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

في صميم تطبيقنا، تقع AlloyDB for PostgreSQL. سنستخدم إمكانات المتجهات الفعّالة وفهرس ScaNN لتمكين البحث الدلالي شبه الفوري، ما يسمح لبرامجنا للعثور على تطابقات في المستودع ضمن آلاف السجلات في أجزاء من الثانية.

في هذا القسم، ستوفّر المخطط والبيانات الأولية وتنشئ التضمينات، وكل ذلك من AlloyDB Studio.

الاتصال بـ AlloyDB Studio

انتقِل إلى آلة AlloyDB الافتراضية في AlloyDB Console.
انقر على AlloyDB Studio في شريط التنقّل الأيمن.
المصادقة باستخدام:
اسم المستخدم: postgres
قاعدة البيانات: postgres
كلمة المرور: كلمة المرور التي ضبطتها أثناء إنشاء المجموعة

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

توفّر AlloyDB إضافات مدمجة للمتّجهات والذكاء الاصطناعي. نفِّذ طلب SQL التالي في AlloyDB Studio:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

google_ml_integration: تتيح هذه السمة استخدام الدالة ai.embedding() لاستدعاء Vertex AI مباشرةً من SQL.
المتّجه: يخزِّن تضمينات المتّجهات ذات 768 بُعدًا ويستعلم عنها.
alloydb_scann: تفعّل فهرس ScaNN من Google لإجراء عمليات بحث متّجه فائقة السرعة.

إنشاء جدول المستودع

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

يخزّن عمود part_embedding متّجهات ذات 768 بُعدًا من نموذج text-embedding-005. وهذا ما يتيح البحث الدلالي.

إدراج نموذج للبيانات

أدرِج 20 منتجًا من مستودعك:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

منح أذونات التضمين

GRANT EXECUTE ON FUNCTION embedding TO postgres;

إنشاء عمليات تضمين متجهة

يستخدم هذا المثال الدالة المضمّنة ai.embedding() في AlloyDB لاستدعاء نموذج text-embedding-005 من Vertex AI مباشرةً من SQL، بدون الحاجة إلى رمز Python:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

يؤدي ذلك إلى إنشاء متّجهات ذات 768 بُعدًا تلتقط المعنى الدلالي لاسم كل جزء ووصفه. سيستخدم فهرس ScaNN هذه البيانات لإجراء عمليات بحث عن التشابه بسرعة فائقة. [سيستغرق استكمال هذا الاستطلاع حوالي 3 إلى 5 دقائق]

إنشاء فهرس ScaNN

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

التأكّد من أنّ كل شيء يعمل

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

من المفترض أن تظهر 20 صفًا، وكلها تتضمّن has_embedding = true.

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

"لم يتم العثور على الإضافة"؟ قد يكون المثيل لا يزال قيد التحديث. يُرجى الانتظار بضع ثوانٍ ثم إعادة المحاولة.
هل تظهر الرسالة"تم رفض الإذن" عند تضمين المحتوى؟ تستغرق عملية نشر IAM مدة تصل إلى 60 ثانية. أعِد تنفيذ عبارتَي GRANT وUPDATE.
عدم تطابق أبعاد المتّجه؟ يستخدم الجدول vector(768)، لذا عليك الالتزام بنموذج text-embedding-005. تتضمّن الطُرز الأخرى أبعادًا مختلفة.
هل تعرض عملية التضمين القيمة NULL؟ تأكَّد من منح دور "مستخدم Vertex AI" في "إدارة الهوية وإمكانية الوصول" إلى حساب خدمة AlloyDB (راجِع القسم السابق).

4. فهم البنية

قبل إجراء تغييرات على الرمز، دعنا نتعرّف على طريقة إنشاء النظام. تتّبع البنية النمط التدريجي التالي:

The Agent Stack

Vision Agent (agents/vision-agent/)

agent.py: منطق Gemini 3 Flash الأساسي يرسل الصور إلى النموذج مع تفعيل ميزة "تنفيذ الرمز البرمجي"، وبالتالي يكتب رمز Python (OpenCV) لاحتساب العناصر بشكل حتمي.
‫agent_executor.py: يربط طلبات بروتوكول A2A بمنطق الوكيل.
‫main.py: خادم Uvicorn A2A الذي يعرض ‎ /.well-known/agent-card.json ويتعامل مع الطلبات

وكيل المورّد (agents/supplier-agent/)

‫inventory.py: يتصل بـ AlloyDB من خلال AlloyDB Python Connector (لا حاجة إلى Auth Proxy). يحتوي على الدالة find_supplier() التي تنفّذ البحث المتّجهي في ScaNN.
‫agent_executor.py: يربط بروتوكول A2A بمنطق البحث في المستودع.
‫main.py: خادم Uvicorn A2A مع بطاقة الوكيل ونقطة نهاية الصحة

Control Tower (frontend/)

‫app.py: خادم FastAPI + WebSocket يكتشف الوكلاء من خلال A2A، وينسّق مسار الرؤية ← البحث ← الطلب، ويبثّ التحديثات في الوقت الفعلي إلى المتصفّح.

مسار A2A

يقرأ Control Tower الملف ‎ /.well-known/agent-card.json من كل وكيل
اكتشاف الإمكانات (المهارات ونقاط النهاية) بدون عناوين URL مبرمَجة
إرسال الصورة إلى Vision Agent → الحصول على عدد العناصر + الوصف
إرسال الوصف كطلب بحث مضمّن إلى "وكيل المورّد" → الحصول على تطابق جزئي
تقديم الطلب بشكل مستقل

اتصال AlloyDB

يستخدم Supplier Agent AlloyDB Python Connector بدلاً من Auth Proxy التقليدي:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

يتولّى ذلك معالجة مصادقة إدارة الهوية وإمكانية الوصول (IAM) وبروتوكول أمان طبقة النقل/طبقة المقابس الآمنة وتوجيه الاتصال تلقائيًا. عند النشر على Cloud Run لاحقًا، ما عليك سوى تغيير ip_type إلى "PRIVATE" للوصول إلى شبكة VPC.

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

يتذكّر "وكيل المورّد" ملايين الأجزاء باستخدام AlloyDB ScaNN. في الوقت الحالي، يتم شحنها مع طلب بحث نائب، وهو عبارة عن أداة لا تحتفظ بالذاكرة وتعرض الصف الأول الذي تعثر عليه، بغض النظر عن ما تبحث عنه.

The Audit: The Amnesiac

إذا أرسلت طلبًا إلى Supplier Agent الآن، سيعرض نتيجة عشوائية. ولا يتضمّن مفهوم التشابه. لنحاول إصلاح هذه المشكلة.

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

يُفوّض خادم 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 يتضمّن إعدادات الوكيل (يجب أن يتم عرضه بدون أخطاء)

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

افتح الملف agents/supplier-agent/inventory.py وابحث عن الدالة find_supplier() في السطر 60-70. سيظهر لك العنصر النائب التالي:

# TODO: Replace this placeholder query with ScaNN vector search

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

استبدِل هذين السطرَين بما يلي:

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

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

‫<=> هو عامل تشغيل مسافة جيب التمام في PostgreSQL
يؤدي ORDER BY part_embedding <=> %s::vector إلى العثور على أقرب تطابق (أقل مسافة = أقرب معنى دلالي).
يحوّل %s::vector مصفوفة التضمين إلى نوع المتّجه في PostgreSQL
يعمل فهرس 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
تعذّر الاتصال بقاعدة البيانات: يُرجى التحقّق من ملف ‎ .env وملء الحقول ALLOYDB_REGION وALLOYDB_CLUSTER وALLOYDB_INSTANCE
تم رفض الاتصال: تأكَّد من تفعيل عنوان IP العلني على مثيل AlloyDB
تعذُّر تنفيذ نص التحقّق: تأكَّد من إكمال عملية إنشاء القيمة الأولية بنجاح في الخطوة 4

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

بما أنّ قاعدة البيانات متاحة، لنوقظ العينَين باستخدام Gemini 3 Flash. يُجري Vision Agent "عمليات حسابية مرئية" من خلال ميزة "تنفيذ الرموز البرمجية".

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

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

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

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

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

افتح الملف agents/vision-agent/agent.py .
ابحث عن قسم GenerateContentConfig (حوالي السطر 68-78).
أزِل التعليق من كلّ من كتلة 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="MINIMAL",  # 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="MINIMAL"؟

بالنسبة إلى هذه المهمة (احتساب العناصر من خلال تنفيذ الرمز)، يقدّم المستوى "الحد الأدنى" استدلالاً كافيًا لتخطيط النص البرمجي والتحقّق من العدد. سيؤدي استخدام القيمة "عالية" إلى إضافة فترة تأخير بمقدار 2 إلى 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 يتضمّن اسم الوكيل ومهاراته ستختبر عملية احتساب عدد الزيارات الفعلية باستخدام واجهة مستخدم Control Tower في الخطوة 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/vision-agent/‎، عليك أولاً الرجوع إلى جذر المستودع باستخدام cd ../..‎

تمت إضافة بطاقة الوكيل في agents/supplier-agent/agent_card.json. افتحها وراجِع ما يلي:

{
  "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

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

Vision Agent على المنفذ 8081
وكيل المورّد على المنفذ 8082
Control Tower على المنفذ 8080

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

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

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

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

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

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

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

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

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

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

ما يحدث:

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

ملاحظة: أبقِ "وضع العرض التوضيحي" مفعّلاً (أعلى يسار الشاشة) للإيقاف مؤقتًا في كل مرحلة من مراحل العروض التقديمية. في الوضع 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: تأكَّد من تفعيل عنوان IP العام على مثيل AlloyDB

9- 🎁 مكافأة: النشر على Cloud Run

اختياري: تعمل كل الميزات محليًا. إذا أردت مشاركة المحتوى الذي أنشأته باستخدام عنوان URL متاح للجميع، اتّبِع الخطوات التالية:

# From repo root
sh deploy/deploy.sh

ما يحدث:

قراءة إعدادات .env
يطلب اسمك (يظهر في التطبيق الذي تم نشره)
يتم نشر جميع الخدمات الثلاث كحاوية Cloud Run واحدة
يمنح أدوار IAM للوصول إلى AlloyDB
إخراج عنوان URL قابل للمشاركة

سيظهر للزوّار الذين يفتحون عنوان URL نافذة منبثقة:

10. تنظيف

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

# From repo root
sh deploy/cleanup.sh

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

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

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

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

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

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

‫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

MCP Toolbox for Databases (طريقة بديلة):

مجموعة أدوات MCP: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

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

أسعار 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	النتائج الحتمية	تم التحقّق من صحة المعلومات بواسطة المنتدى

موارد إضافية

بروتوكول Agent-to-Agent (A2A):

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

أبحاث ScaNN:

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

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

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

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

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

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

تلميحات:

يمكن أن يؤدي تنفيذ رمز Vision Agent إلى اقتصاص عناصر فردية من صورة الرف
يمكن لنموذج multimodalembedding@001 من Vertex AI تضمين الصور مباشرةً
تعديل inventory.py لقبول وحدات بايت للصور بدلاً من النص
تعديل وصف مهارة A2A للإشارة إلى "يقبل: image/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. سيرصدها "مركز التحكّم" تلقائيًا.

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

13. الخاتمة

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

ما أنشأناه:

الرؤية: استبدلنا "التخمين" بتنفيذ الرموز البرمجية (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

إنشاء سلسلة إمداد مستقلة باستخدام Gemini 3 Flash وAlloyDB AI تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

1. نظرة عامة

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

ما ستنشئه

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

المتطلبات

2. قبل البدء

إنشاء مشروع

إعداد قاعدة البيانات [AlloyDB]

الحصول على الرمز

تحديد مشروعك

تفعيل عنوان IP العلني على AlloyDB

منح أذونات Vertex AI

تشغيل نص الإعداد البرمجي

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

الاتصال بـ AlloyDB Studio

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

إنشاء جدول المستودع

يخزّن عمود part_embedding متّجهات ذات 768 بُعدًا من نموذج text-embedding-005. وهذا ما يتيح البحث الدلالي.

إدراج نموذج للبيانات

منح أذونات التضمين

إنشاء عمليات تضمين متجهة

إنشاء فهرس ScaNN

التأكّد من أنّ كل شيء يعمل

4. فهم البنية

The Agent Stack

Vision Agent (agents/vision-agent/)

وكيل المورّد (agents/supplier-agent/)

Control Tower (frontend/)

مسار A2A

اتصال AlloyDB

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

The Audit: The Amnesiac

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

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

التحقّق

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

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

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

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

التحقّق

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

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

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

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

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

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

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

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

9- 🎁 مكافأة: النشر على Cloud Run

10. تنظيف

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

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

موارد إضافية

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

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

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

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

13. الخاتمة

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