ساخت یک زنجیره تأمین خودکار با Gemini 3 Flash و AlloyDB AI

۱. مرور کلی

دوران «چت‌بات‌هایی که می‌خوانند» رو به پایان است. ما در حال ورود به دوران «بینایی عامل‌محور» هستیم.

در این آزمایشگاه کد، ما مهندسی هوش مصنوعی قطعی را پیاده‌سازی خواهیم کرد - روشی برای ساخت سیستم‌های هوش مصنوعی که حدس نمی‌زنند. مدل‌های استاندارد هوش مصنوعی اغلب وقتی از آنها خواسته می‌شود اقلام را در یک تصویر پیچیده بشمارند، "توهم" (حدس) می‌کنند. در یک زنجیره تأمین، حدس زدن خطرناک است. اگر یک هوش مصنوعی حدس بزند که شما ۱۲ قلم کالا دارید در حالی که در واقع ۱۵ قلم کالا دارید، باعث خطاهای پرهزینه‌ای می‌شود.

ما یک عامل زنجیره تأمین خودکار با استفاده از حلقه جدید «فکر کن، عمل کن، مشاهده کن» در Gemini 3 Flash خواهیم ساخت. این عامل فقط نگاه نمی‌کند؛ بلکه تحقیق هم می‌کند.

معماری قطعی

ما با یک سیستم «کور» و «فراموشی» شروع خواهیم کرد. شما به صورت دستی حواس آن را یکی یکی «بیدار» خواهید کرد:

۱۷۱۹۱a۹۱a۹c۵۴۱۴۶.png

  1. چشم‌ها (عامل بینایی) : ما Gemini 3 Flash را با اجرای کد فعال می‌کنیم. به جای پیش‌بینی توکن‌ها برای حدس زدن یک عدد، مدل کد پایتون (OpenCV) را می‌نویسد تا پیکسل‌ها را به صورت قطعی بشمارد.
  2. حافظه (عامل تأمین‌کننده) : ما AlloyDB AI را با ScaNN (نزدیک‌ترین همسایه‌های مقیاس‌پذیر) فعال می‌کنیم. این به عامل اجازه می‌دهد تا تأمین‌کننده دقیق یک قطعه را از بین میلیون‌ها گزینه در عرض چند میلی‌ثانیه فراخوانی کند.
  3. دست‌دهی (پروتکل A2A) : ما ارتباط عامل به عامل را با استفاده از یک agent_card.json استاندارد فعال می‌کنیم و به عامل بینایی اجازه می‌دهیم تا به طور مستقل موجودی را از عامل تأمین‌کننده سفارش دهد.

آنچه خواهید ساخت

  • یک عامل بینایی که "محاسبات بصری" را روی فیدهای دوربین انجام می‌دهد.
  • یک عامل تأمین‌کننده با پشتیبانی AlloyDB ScaNN برای جستجوی برداری پرسرعت.
  • یک رابط کاربری برج کنترل با به‌روزرسانی‌های بلادرنگ WebSocket برای تجسم حلقه خودکار.

آنچه یاد خواهید گرفت

  • نحوه فعال کردن Agentic Vision با gemini-3-flash-preview با استفاده از رابط برنامه‌نویسی Gemini.
  • نحوه پیاده‌سازی جستجوی برداری با استفاده از عملگر <=> (فاصله کسینوسی) در AlloyDB.
  • نحوه اتصال Cloud Shell به AlloyDB با استفاده از Auth Proxy.

الزامات

  • یک مرورگر، مانند کروم یا فایرفاکس
  • یک پروژه گوگل کلود با قابلیت پرداخت.
  • یک کلید API مربوط به Gemini (نسخه رایگان در Google AI Studio موجود است) برای Vision Agent.

۲. قبل از شروع

ایجاد یک پروژه

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

تصویر دکمه فعال کردن Cloud Shell

  1. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر: 
gcloud auth list

همین!

اکنون برای راه‌اندازی با یک کلیک آماده هستید. بخش بعدی:

  • باز کردن خودکار Cloud Shell
  • مخزن را کلون کنید
  • شما را در کل مراحل راه‌اندازی در یک آموزش تعاملی راهنمایی می‌کند

۳. راه‌اندازی با یک کلیک در Cloud Shell

ما تنظیمات را به یک آموزش Cloud Shell هدایت‌شده تبدیل کرده‌ایم. همه چیز خودکار است: تأمین زیرساخت، راه‌اندازی AlloyDB، پیکربندی Auth Proxy و بارگذاری پایگاه داده.

آموزش راه‌اندازی Cloud Shell

⚠️ مهم - قبل از کلیک: وقتی روی دکمه زیر کلیک می‌کنید، یک کادر محاوره‌ای امنیتی مشاهده خواهید کرد که از شما می‌پرسد «در Cloud Shell باز کنید» . این کادر قبل از کلون‌های مخزن ظاهر می‌شود.

شما باید:

  1. ✅ کادر « اعتماد به مخزن » را علامت بزنید
  2. ✅ روی « تأیید » کلیک کنید

بدون این، مخزن کلون نمی‌شود.

آماده‌اید؟ برای باز کردن پروژه با آموزش گام به گام کلیک کنید:

چه اتفاقی می‌افتد؟

  1. Cloud Shell با مخزن از پیش کلون شده باز می‌شود.
  2. یک پنل آموزشی در سمت راست با دستورالعمل‌های گام به گام ظاهر می‌شود.
  3. شما از طریق موارد زیر راهنمایی خواهید شد:
  • دریافت کلید API جمینی (نسخه رایگان موجود است)
  • تنظیم پروژه GCP در ترمینال
  • اجرای تنظیمات (بررسی APIها، فعال‌سازی در صورت نیاز، آماده‌سازی AlloyDB: حدود ۱۵ دقیقه)
  • ایجاد دو تغییر در کد کلید (فعال کردن بینایی + حافظه)
  • ایجاد کارت عامل (پروتکل A2A)
  • راه اندازی کلیه سرویس ها

این آموزش تعاملی است - هر مرحله شماره‌گذاری شده و پیشرفت شما را پیگیری می‌کند.

جایگزین: تنظیم دستی

اگر کنترل دستی را ترجیح می‌دهید:

  1. Cloud Shell را باز کنید و تأیید کنید که پروژه شما تنظیم شده است 
gcloud config get-value project
  1. در صورت نیاز، پروژه خود را تنظیم کنید 
gcloud config set project YOUR_PROJECT_ID
  1. مخزن را کلون کنید 
git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb
  1. اجرای تنظیمات 
sh setup.sh

دستورالعمل‌های روی صفحه را از اسکریپت راه‌اندازی دنبال کنید.

مرحله بعدی: این آموزش شما را در مراحل باقی‌مانده راهنمایی می‌کند. پس از تکمیل، برای درک آنچه در پشت صحنه اتفاق افتاده است، به بخش ۴ بروید.

۴. پشت صحنه: پروکسی احراز هویت و بارگذاری پایگاه داده

مشکل : AlloyDB درون یک VPC خصوصی قرار دارد. Cloud Shell خارج از آن است. اتصال مستقیم غیرممکن است.

راه حل: پروکسی احراز هویت AlloyDB یک تونل امن و احراز هویت شده توسط IAM از آدرس 127.0.0.1:5432 در Cloud Shell به نمونه AlloyDB شما ایجاد می‌کند. اگر IP عمومی نمونه شما فعال باشد، پروکسی از آن استفاده می‌کند؛ در غیر این صورت از طریق IP خصوصی VPC متصل می‌شود.

setup.sh چه کاری انجام داد؟

  1. نمونه AlloyDB شما (خوشه، منطقه، پروژه) به طور خودکار شناسایی شد
  2. فایل .env با تمام اطلاعات احراز هویت (GEMINI_API_KEY، DB_PASS، جزئیات AlloyDB) ایجاد شد.
  3. پروکسی احراز هویت (Auth Proxy) را دانلود و اجرا کردم (در صورت وجود با –public-ip )
  4. پایگاه داده را با ۸ نمونه موجودی کالا + شاخص ScaNN بارگذاری کردیم.

فایل .env شما آماده است. تمام اجراهای بعدی به طور خودکار اعتبارنامه‌ها را بارگذاری می‌کنند.

تأیید کنید که کار کرده است

مطمئن شوید که هنوز در ریشه مخزن هستید

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

بررسی کنید که Auth Proxy در حال اجرا باشد

ps aux | grep alloydb-auth-proxy

چه چیزی خلق شد؟

  • جدول موجودی با ۸ قطعه و جاسازی‌های ۷۶۸ بعدی
  • شاخص ScaNN (idx_inventory_scann) برای جستجوی سریع بردار

۵. مرحله ۱: حافظه (عامل تأمین‌کننده)

نماینده تأمین‌کننده با استفاده از AlloyDB ScaNN میلیون‌ها قطعه را به خاطر می‌سپارد. ما آن را به عنوان یک سرور A2A راه‌اندازی می‌کنیم، سپس پرس‌وجوی برداری را اصلاح می‌کنیم.

حسابرسی: فراموشکار

اگر اکنون از نماینده تأمین‌کننده (با SQL جای‌نگهدار) پرس‌وجو کنید، اولین ردیفی را که پیدا می‌کند برمی‌گرداند - نه نزدیکترین تطابق. هیچ مفهومی از شباهت ندارد. فراموشکار است.

نماینده تأمین‌کننده را شروع کنید

سرور A2A (main.py) به agent_executor.py محول می‌شود، که پروتکل را به منطق تجاری در inventory.py متصل می‌کند.

pkill -f uvicorn #Kill all uvicorn processes

مرحله 1: به فهرست نمایندگی‌ها بروید

cd agents/supplier-agent

مرحله ۲: نصب وابستگی‌ها 

pip install -r requirements.txt

مرحله 3: سرور عامل را شروع کنید 

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

دستور ‎>/dev/null 2>&1&‎ سرور را در پس‌زمینه اجرا می‌کند و خروجی را متوقف می‌کند تا ترمینال شما را مختل نکند.

مرحله ۴: تأیید کنید که عامل در حال اجرا است (بعد از شروع ۲-۳ ثانیه صبر کنید) 

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

خروجی مورد انتظار: JSON با پیکربندی عامل (باید بدون خطا برگردانده شود)

جاسازی‌های معنایی واقعی

در طول راه‌اندازی، پایگاه داده با تعبیه‌های معنایی واقعی تولید شده از طریق مدل text-embedding-005 مربوط به Google Gen AI SDK بارگذاری شد. این امر تطابق دقیق شباهت - و نه بردارهای تصادفی - را تضمین می‌کند. فرآیند بارگذاری اولیه برای ۱۳ مورد نمونه با استفاده از تولید تعبیه موازی حدود ۱۰ ثانیه طول می‌کشد تا بردارهای معنادار ۷۶۸ بعدی ایجاد کند که معنای معنایی هر بخش را در بر می‌گیرد.

انحراف AlloyDB: چرا ScaNN؟

راه حل: پیاده‌سازی عملگر <=>

عامل با یک پرس‌وجوی مکان‌نما ارسال می‌شود. ما باید جستجوی برداری ScaNN را فعال کنیم.

مرحله 1: فایل موجودی را باز کنید 

cd agents/supplier-agent

مرحله ۲: پیدا کردن TODO در inventory.py

تابع find_supplier() را در حدود خطوط ۴۷ تا ۶۰ جستجو کنید. خواهید دید: 

# ============================================================
# 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)

مرحله ۳: جایگزین کردن 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 به طور خودکار این پرس و جو را تسریع می‌کند!

مرحله ۴: فایل را ذخیره کنید (Ctrl+S یا Cmd+S)

اکنون عامل به جای بازگرداندن نتایج تصادفی، از جستجوی معنایی استفاده خواهد کرد!

تأیید

کشف A2A و ​​موجودی را آزمایش کنید: 

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

44500cdeeca3cee8.png

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 کارت عامل را برمی‌گرداند. قطعه کد پایتون یک قطعه و تأمین‌کننده را از داده‌های اولیه برمی‌گرداند.

۶. مرحله ۲: چشم‌ها (عامل بینایی)

در حالی که پایگاه داده قابل دسترسی است، بیایید با استفاده از Gemini 3 Flash چشم‌ها را بیدار کنیم. عامل بینایی از طریق اجرای کد "محاسبات بصری" را انجام می‌دهد. سرور A2A (main.py) به agent_executor.py محول می‌شود که agent.py را برای تجزیه و تحلیل Gemini فراخوانی می‌کند.

حسابرسی: توهم

اگر از یک مدل چندوجهی استاندارد بپرسید «چند جعبه در این تصویر نامرتب وجود دارد؟»، تصویر را به عنوان یک تصویر ثابت پردازش کرده و حدس می‌زند.

  • مدل می‌گوید: «من حدود ۱۲ جعبه می‌بینم.»
  • واقعیت: ۱۵ جعبه وجود دارد.
  • نتیجه: شکست زنجیره تأمین.

راه حل: بیدار کردن حلقه فکر-عمل-مشاهده

ما اجرای کد و ThinkingConfig را فعال می‌کنیم تا مدل، پایتون (OpenCV) را طوری بنویسد که به صورت قطعی شمارش کند.

  1. فایل agents/vision-agent/agent.py را باز کنید.
  2. بخش GenerateContentConfig را پیدا کنید.
  3. هر دو بلوک thinking_config=types.ThinkingConfig(...) و tools=[types.Tool(code_execution=...)] را از حالت کامنت خارج کنید.
  4. کلاینت از قبل برای استفاده از 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"؟

برای این کار خاص (شمارش اقلام از طریق اجرای کد)، "LOW" بودجه استدلال کافی را برای موارد زیر فراهم می‌کند:

  • ساختار اسکریپت پایتون را برنامه‌ریزی کنید
  • تصمیم بگیرید که از کدام رویکرد پردازش تصویر استفاده کنید
  • تأیید کنید که تعداد با تعداد کادرهای محصورکننده مطابقت دارد

استفاده از «بالا» باعث افزایش ۲ تا ۳ برابری تأخیر و هزینه می‌شود، بدون اینکه دقت را برای وظایف قطعی بهبود بخشد. «بالا» را برای استدلال چند مرحله‌ای پیچیده نگه دارید (مثلاً «این اختلال در زنجیره تأمین را تجزیه و تحلیل کنید و ۳ تأمین‌کننده جایگزین را با توجیه پیشنهاد دهید»).

بهینه‌سازی هزینه-عملکرد یک مهارت کلیدی برای مهندسی هوش مصنوعی تولید است: عمق استدلال را با پیچیدگی وظیفه مطابقت دهید.

نماینده بینایی را شروع کنید

🔄 بررسی مسیر: اگر هنوز در مسیر agents/supplier-agent/ هستید، ابتدا با دستور cd ../.. به مخزن root برگردید.

مرحله 1: به فهرست راهنمای عامل بینایی بروید 

cd agents/vision-agent

مرحله ۲: نصب وابستگی‌ها 

pip install -r requirements.txt

مرحله 3: سرور عامل بینایی را شروع کنید 

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

دستور ‎>/dev/null 2>&1&‎ سرور را در پس‌زمینه اجرا می‌کند و خروجی را متوقف می‌کند تا ترمینال شما را مختل نکند.

تأیید

کشف A2A را آزمایش کنید: 

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

مورد انتظار: JSON با نام و مهارت‌های عامل. شمارش واقعی بینایی را با رابط کاربری برج کنترل در مرحله ۸ آزمایش خواهید کرد.

dc9bc53007336472.png

۷. مرحله ۳: دست دادن (کارت مامور A2A)

نماینده ما مشکل را می‌بیند (بینش) و تأمین‌کننده را می‌شناسد (حافظه). پروتکل A2A امکان کشف پویا را فراهم می‌کند - بخش جلویی با خواندن کارت هر نماینده یاد می‌گیرد که چگونه با آن صحبت کند.

A2A در مقابل API های REST سنتی

جنبه

REST سنتی

پروتکل A2A

کشف نقطه پایانی

URL های کدگذاری شده در پیکربندی

پویا از طریق /.well-known/agent-card.json

شرح قابلیت

اسناد API (برای انسان‌ها)

مهارت‌ها (قابل خواندن توسط ماشین)

ادغام

کد دستی برای هر سرویس

تطبیق معنایی: «من به جستجوی موجودی نیاز دارم» → مهارت را کشف می‌کند

نماینده جدید اضافه شد

به‌روزرسانی تمام پیکربندی‌های کلاینت‌ها

بدون نیاز به پیکربندی - کشف خودکار

مزیت در دنیای واقعی: در یک میکروسرویس سنتی، اگر یک "عامل لجستیک" سوم اضافه کنید، باید کد برج کنترل را با URL و قرارداد API آن به‌روزرسانی کنید. با A2A، برج کنترل آن را به طور خودکار کشف می‌کند و قابلیت‌های آن را از طریق توصیف مهارت‌های زبان طبیعی درک می‌کند.

به همین دلیل است که A2A امکان ترکیب عامل‌های Plug-and-Play - الگوی معماری برای سیستم‌های خودمختار - را فراهم می‌کند.

راه حل: کارت مامور را ایجاد کنید

ما باید مشخص کنیم که نماینده تأمین‌کننده چه کاری می‌تواند انجام دهد.

  1. فایل agents/supplier-agent/agent_card_skeleton.json را در فایل agents/supplier-agent/agent_card.json کپی کنید.
  2. فایل را برای جایگزینی متغیرهای جایگزین ویرایش کنید:

قبل (اسکلت): 

{
  "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?"]
  }]
}
  1. نماینده تأمین‌کننده را مجدداً راه‌اندازی کنید تا کارت جدید را بارگذاری کند:

مرحله ۱: عامل در حال اجرا را متوقف کنید 

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

مرحله 2: به فهرست نمایندگی‌ها بروید 

cd agents/supplier-agent

مرحله ۳: دوباره عامل را شروع کنید 

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

دستور ‎>/dev/null 2>&1&‎ سرور را در پس‌زمینه اجرا می‌کند و خروجی را متوقف می‌کند تا ترمینال شما را مختل نکند.

مرحله ۴: کارت مامور جدید را تأیید کنید (بعد از شروع ۲-۳ ثانیه صبر کنید) 

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

خروجی مورد انتظار: JSON شامل نام، توضیحات و مهارت‌های تکمیل‌شده شما.

dd352ca2e7e6109a.png

۸. مرحله ۴: برج کنترل

رابط کاربری Control Tower را با FastAPI + WebSockets اجرا کنید. این رابط، عامل‌ها را از طریق A2A کشف می‌کند و کل حلقه را با به‌روزرسانی‌های بلادرنگ هماهنگ می‌کند.

شروع همه سرویس‌ها

ساده‌ترین راه برای شروع همه سرویس‌ها:

تأیید کنید که در ریشه مخزن هستید 

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

سپس، 

sh run.sh

این دستور واحد شروع می‌شود:

  • پروکسی احراز هویت AlloyDB (اگر در حال اجرا نباشد)
  • عامل بینایی روی پورت ۸۰۸۱
  • نماینده تأمین‌کننده روی پورت ۸۰۸۲
  • برج کنترل روی پورت ۸۰۸۰

حدود ۱۰ ثانیه صبر کنید تا همه سرویس‌ها راه‌اندازی شوند.

سیستم را آزمایش کنید

دسترسی به برج کنترل:

  1. روی دکمه پیش‌نمایش وب (آیکون چشم 👁️) در نوار ابزار Cloud Shell کلیک کنید
  2. « پیش‌نمایش روی پورت ۸۰۸۰ » را انتخاب کنید
  3. داشبورد برج کنترل در یک برگه جدید باز خواهد شد

اجرای نسخه آزمایشی:

  1. بالا سمت راست: وضعیت اتصال (نقطه سبز "زنده")، ضامن حالت آزمایشی/خودکار و کنترل‌های صدا
  2. مرکز : بوم گردش کار اصلی با بارگذاری تصویر و تجسم تجزیه و تحلیل
  3. پنل‌های کناری (در حین تحلیل ظاهر می‌شوند): جدول زمانی گردش کار (چپ)، ردیابی پیشرفت و نمایشگر کد (راست)

گزینه ۱: شروع سریع (توصیه می‌شود)

  1. در صفحه اصلی، بخشی با عنوان « شروع سریع » به همراه تصاویر نمونه مشاهده خواهید کرد.
  2. برای شروع خودکار تجزیه و تحلیل، روی هر تصویر نمونه کلیک کنید
  3. گردش کار خودکار را تماشا کنید (حدود ۳۰ تا ۴۵ ثانیه)

گزینه ۲: فایل خودتان را آپلود کنید

  1. تصویر انبار/قفسه (PNG، JPG، تا 10 مگابایت) را بکشید و رها کنید یا برای مرور کلیک کنید
  2. روی « آغاز گردش کار خودکار » کلیک کنید
  3. خط لوله ۴ مرحله‌ای را مشاهده کنید

چه اتفاقی می‌افتد:

  1. کشف عامل: ماژول‌های پروتکل A2A کارت‌های عامل بینایی و عامل تأمین‌کننده را به همراه مهارت‌ها و نقاط پایانی آنها نشان می‌دهند.
  2. تحلیل بینایی: نرم‌افزار Gemini 3 Flash کد پایتون (OpenCV) را برای شمارش موارد تولید و اجرا می‌کند. نوار پیشرفت، زیرمرحله‌ها را نشان می‌دهد. کادرهای محصورکننده روی موارد شناسایی‌شده قرار می‌گیرند. نشان نتیجه عبارت «✓ Code-Verified» یا «~ Estimated» را نشان می‌دهد.
  3. تطبیق با تأمین‌کننده: انیمیشن جستجوی برداری AlloyDB ScaNN. عبارت جستجو نمایش داده می‌شود (مثلاً "جعبه‌های فلزی صنعتی"). کارت نتیجه، قطعه، تأمین‌کننده و امتیاز اطمینان تطبیق داده شده را نشان می‌دهد.
  4. سفارش ثبت شده: کارت رسید حاوی شناسه سفارش، تعداد و جزئیات

نکته: برای مکث در هر مرحله برای ارائه، حالت DEMO (بالا سمت راست) را روشن نگه دارید. در حالت AUTO، گردش کار به طور مداوم اجرا می‌شود.

۱a031c4fd407a183.png

چه اتفاقی افتاد؟

برج مراقبت از پروتکل A2A برای کشف هر دو عامل از طریق /.well-known/agent-card.json استفاده کرد، تحلیل بینایی (Gemini 3 Flash با اجرای کد) را هماهنگ کرد، جستجوی برداری (AlloyDB ScaNN) را انجام داد و یک سفارش خودکار ثبت کرد - همه اینها با به‌روزرسانی‌های WebSocket در زمان واقعی. هر عامل قابلیت‌های خود را از طریق استاندارد A2A در معرض نمایش قرار می‌دهد و امکان ترکیب plug-and-play را بدون SDK های سفارشی فراهم می‌کند. اطلاعات بیشتر: پروتکل A2A

عیب‌یابی

خطاهای مرتبط با مسیر:

  • هنگام اجرای دستورات « چنین فایل یا دایرکتوری وجود ندارد »: شما در ریشه مخزن نیستید. 
# 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 رد شد": تأیید کنید که پروکسی Auth در حال اجرا است: 
ps aux | grep alloydb-auth-proxy

مشکلات اتصال AlloyDB:

اگر اتصال به سرور در آدرس ۱۲۷.۰.۰.۱ را مشاهده می‌کنید، پورت ۵۴۳۲ ناموفق بوده است:

اگر اتصال به سرور در آدرس ۱۲۷.۰.۰.۱ را مشاهده می‌کنید، پورت ۵۴۳۲ ناموفق بوده است:

  1. بررسی پروکسی احراز هویت: ps aux | grep alloydb-auth-proxy
  2. تأیید کنید که IP عمومی فعال باشد: نمونه‌های gcloud alloydb موارد INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)" را توصیف می‌کنند.
  3. برای توسعه محلی (نه Cloud Shell):
  4. مشکل : Cloud Shell به صورت خودکار کار می‌کند، اما دستگاه‌های محلی به شبکه‌های مجاز نیاز دارند
  5. راه حل : فایل setup.sh را دوباره اجرا کنید و در صورت درخواست، گزینه ۱ (authorize 0.0.0.0/0) را انتخاب کنید.
  6. نکته امنیتی : حتی با 0.0.0.0/0، اتصال نیاز به:
  7. اعتبارنامه‌های معتبر GCP (اعتبارنامه‌های پیش‌فرض برنامه)
  8. رمز عبور پایگاه داده
  9. رمزگذاری mTLS (Auth Proxy این کار را انجام می‌دهد)

۹. پاکسازی

برای جلوگیری از تحمیل هزینه، تمام منابع را با اسکریپت پاکسازی خودکار از بین ببرید: 

# From repo root
sh cleanup.sh

این با خیال راحت حذف می کند:

  • کلاستر AlloyDB (محرک اصلی هزینه)
  • سرویس‌های Cloud Run (در صورت استقرار)
  • حساب‌های خدمات مرتبط

اسکریپت قبل از حذف هر چیزی، از شما تأیید می‌خواهد.

۱۰. منابع و مطالعات بیشتر

تمام ادعاهای فنی موجود در این آزمایشگاه کد، توسط اسناد رسمی گوگل کلود و گوگل هوش مصنوعی تأیید شده‌اند.

مستندات رسمی

فلش جمینی ۳:

هوش مصنوعی و اسکن دیجیتال آلیاژی:

اطلاعات قیمت‌گذاری:

ادعاهای عملکرد تأیید شده

ویژگی

ادعا

منبع

ScaNN در مقابل HNSW (فیلتر شده)

۱۰ برابر سریع‌تر

وبلاگ گوگل کلود (تأیید شده)

ScaNN در مقابل HNSW (استاندارد)

۴ برابر سریع‌تر

وبلاگ گوگل کلود (تأیید شده)

ردپای حافظه‌ی اسکن‌ان

۳-۴ برابر کوچکتر

وبلاگ گوگل کلود (تأیید شده)

زمان ساخت شاخص ScaNN

۸ برابر سریع‌تر

وبلاگ گوگل کلود (تأیید شده)

مهلت اجرای کد به پایان رسید

حداکثر ۳۰ ثانیه

اسناد ابری گوگل (تأیید شده)

فایل اجرای کد ورودی/خروجی

پشتیبانی نمی‌شود

اسناد ابری گوگل (تأیید شده)

دما=0 رفتار

خروجی قطعی

انجمن تأیید کرد

منابع اضافی

پروتکل عامل به عامل (A2A):

  • A2A کشف و ارتباط عامل را استاندارد می‌کند
  • کارت‌های مامور در /.well-known/agent-card.json ارائه می‌شوند
  • استاندارد نوظهور برای همکاری عامل‌های خودمختار

تحقیقات اسکن‌ان‌ان:

  • بر اساس ۱۲ سال تحقیقات گوگل
  • جستجوی گوگل و یوتیوب را در مقیاس میلیاردی تقویت می‌کند
  • عرضه عمومی: اکتبر ۲۰۲۴
  • اولین اندیس برداری PostgreSQL مناسب برای بردارهای میلیون تا میلیارد

۱۱. حالت چالش: مهارت‌های عامل خود را ارتقا دهید

شما یک زنجیره تأمین خودکار و کارآمد ایجاد کرده‌اید. آماده‌اید که بیشتر پیش بروید؟ این چالش‌ها، الگوهایی را که آموخته‌اید، برای مشکلات جدید به کار می‌گیرند.

چالش ۱: جستجوی مبتنی بر تصویر (جاسازی‌های چندوجهی)

جریان فعلی: عامل بینایی اقلام را می‌شمارد → پرس و جوی متنی ایجاد می‌کند → عامل تأمین‌کننده متن را جاسازی می‌کند → AlloyDB را جستجو می‌کند

چالش: متن را کاملاً نادیده بگیرید - تصویر برش داده شده را مستقیماً برای نماینده تأمین کننده ارسال کنید.

نکات:

  1. اجرای کد Vision Agent می‌تواند اقلام تکی را از تصویر قفسه برش دهد.
  2. مدل multimodalembedding@001 شرکت Vertex AI می‌تواند تصاویر را مستقیماً جاسازی کند.
  3. فایل inventory.py را طوری تغییر دهید که به جای متن، بایت‌های تصویر را بپذیرد.
  4. شرح مهارت A2A را به‌روزرسانی کنید تا مشخص شود «تصویر/jpeg یا متن پذیرفته می‌شود»

چرا این موضوع مهم است: جستجوی بصری برای قطعاتی با ظاهر پیچیده (تغییرات رنگ، آسیب، تفاوت‌های بسته‌بندی) دقیق‌تر است.

چالش ۲: قابلیت مشاهده - اعتماد از طریق شفافیت

وضعیت فعلی: سیستم کار می‌کند، اما نمی‌توانید «زیر کاپوت» را ببینید

چالش: لاگ‌های کوئری 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 را به همراه زمان اجرا مشاهده خواهید کرد.

چرا این موضوع مهم است: قابلیت مشاهده، اعتماد ایجاد می‌کند. وقتی ذینفعان می‌پرسند «این عامل چگونه تصمیم‌گیری می‌کند؟»، می‌توانید طرح پرس‌وجو را به آنها نشان دهید، نه فقط خروجی را.

چالش ۳: ترکیب چندعاملی

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

معماری:

  • خروجی‌های عامل بینایی: تعداد اقلام
  • خروجی‌های نماینده تأمین‌کننده: موقعیت مکانی تأمین‌کننده
  • ورودی‌های عامل لجستیک (جدید): مقصد، وزن → خروجی‌ها: هزینه ارسال + زمان تقریبی رسیدن به مقصد

راهنمایی: پروتکل A2A این کار را ساده می‌کند—یک کارت مامور جدید با مهارت calculate_shipping ایجاد کنید. برج مراقبت به طور خودکار آن را کشف خواهد کرد.

الگویی که یاد می‌گیرید: این هسته معماری عامل‌گرا است - سیستم‌های پیچیده‌ای که از متخصصان کوچک و قابل ترکیب ساخته شده‌اند.

۱۲. نتیجه‌گیری

شما با موفقیت از هوش مصنوعی مولد (Generative AI) به هوش مصنوعی عاملی (Agentic AI) منتقل شدید.

آنچه ما ساختیم:

  • چشم‌انداز: ما «حدس زدن» را با اجرای کد جایگزین کردیم (Gemini 3 Flash از طریق کلید API).
  • حافظه: ما «جستجوی آهسته» را با AlloyDB ScaNN (از طریق GCP) جایگزین کردیم.
  • اقدام: ما «ادغام API» را با پروتکل A2A جایگزین کردیم.

مزایای معماری ترکیبی:

این آزمایشگاه کد، یک رویکرد ترکیبی را نشان داد:

  • Vision Agent: از Gemini API (کلید API) استفاده می‌کند - ساده، رایگان و بدون نیاز به پرداخت GCP
  • نماینده تأمین‌کننده: از GCP (Vertex AI + AlloyDB) استفاده می‌کند - در سطح سازمانی، آماده برای انطباق

این معماری اقتصاد خودگردان است. کد متعلق به شماست و می‌توانید آن را نگه دارید.

مراحل بعدی