ساخت یک زنجیره تأمین خودکار با 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 برای تجسم حلقه خودکار.

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

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

الزامات

  • یک مرورگر، مانند کروم یا فایرفاکس
  • یک پروژه گوگل کلود با قابلیت پرداخت.
  • یک کلید 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

راه‌اندازی پایگاه داده [AlloyDB]

قبل از هر چیز دیگری، بیایید پایگاه داده را آماده کنیم - این کار حدود ۱۵ دقیقه طول می‌کشد، بنابراین ابتدا آن را شروع می‌کنیم.

  1. برای باز کردن ابزار راه‌اندازی AlloyDB در Cloud Shell، روی دکمه زیر کلیک کنید:

  1. تنظیمات را اجرا کنید: 
Sh run.sh
  1. برای باز کردن رابط کاربری تنظیمات، از پیش‌نمایش وب (آیکون چشم 👁️ → پیش‌نمایش روی پورت ۸۰۸۰) استفاده کنید.
  2. شناسه پروژه خود را وارد کنید، یک منطقه (مثلاً us-central1) انتخاب کنید و یک رمز عبور پایگاه داده ایجاد کنید.

⚠️ این رمز عبور را ذخیره کنید - وقتی اسکریپت راه‌اندازی آن را درخواست کند، به آن نیاز خواهید داشت.

  1. روی Start Deployment کلیک کنید و حدود ۱۵ دقیقه صبر کنید تا کلاستر آماده شود.

کد را دریافت کنید

در حین آماده‌سازی 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، Public IP را فعال کنید تا Python Connector بتواند از Cloud Shell متصل شود:

  1. به کنسول AlloyDB بروید
  2. روی کلاستر خود کلیک کنید → روی نمونه اصلی خود کلیک کنید
  3. روی ویرایش کلیک کنید
  4. به بخش اتصال به IP عمومی بروید و گزینه فعال کردن IP عمومی را تیک بزنید.
  5. روی به‌روزرسانی نمونه کلیک کنید

💡 توجه: رابط پایتون AlloyDB احراز هویت و رمزگذاری را مدیریت می‌کند — نیازی به اضافه کردن هیچ شبکه خارجی مجاز ندارید.

مجوزهای هوش مصنوعی Vertex را اعطا کنید

حساب کاربری سرویس 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، احراز هویت، پروژه و پایتون ۳
  • بررسی و فعال‌سازی APIهای مورد نیاز (AlloyDB، Vertex AI، Compute، Service Networking)
  • درخواست‌های مربوط به کلید API جمینی شما
  • به طور خودکار نمونه AlloyDB شما را شناسایی کرده و منطقه، خوشه و نام نمونه را استخراج می‌کند.
  • رمز عبور پایگاه داده شما را درخواست می‌کند
  • فایل پیکربندی ‎.env‎ را تولید می‌کند.
  • وابستگی‌های پایتون را نصب می‌کند

۳. راه‌اندازی پایگاه داده

در قلب برنامه ما AlloyDB برای PostgreSQL قرار دارد. ما از قابلیت‌های برداری قدرتمند و شاخص ScaNN آن برای فعال کردن جستجوی معنایی تقریباً بلادرنگ استفاده خواهیم کرد و به عوامل ما اجازه می‌دهیم تا در عرض چند میلی‌ثانیه، تطابق‌های موجودی را در بین هزاران رکورد پیدا کنند.

در این بخش، شما طرحواره را تهیه خواهید کرد، داده‌ها را بازیابی می‌کنید و جاسازی‌ها را ایجاد خواهید کرد - همه اینها از AlloyDB Studio.

اتصال به استودیوی AlloyDB

  1. به نمونه AlloyDB خود در کنسول AlloyDB بروید
  2. در منوی سمت چپ، روی AlloyDB Studio کلیک کنید.
  3. احراز هویت با:
  4. نام کاربری : postgres
  5. پایگاه داده : پستگرس
  6. رمز عبور : رمز عبوری که هنگام ایجاد خوشه تنظیم کرده‌اید

فعال کردن افزونه‌ها

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 فعال می‌کند.
  • بردار: جاسازی‌های برداری ۷۶۸ بعدی را ذخیره و جستجو می‌کند.
  • alloydb_scann : ایندکس ScaNN گوگل را برای جستجوی برداری فوق سریع فعال می‌کند.

جدول موجودی را ایجاد کنید 

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 بردارهای ۷۶۸ بعدی را از text-embedding-005 ذخیره می‌کند. این همان چیزی است که جستجوی معنایی را تقویت می‌کند.

درج داده‌های نمونه

۲۰ قلم موجودی انبار را وارد کنید:

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 استفاده می‌کند - هیچ کد پایتونی لازم نیست: 

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

این کار بردارهای ۷۶۸ بعدی تولید می‌کند که معنای معنایی نام و توضیحات هر بخش را در بر می‌گیرد. شاخص ScaNN از این بردارها برای جستجوی سریع شباهت استفاده می‌کند. [تکمیل این کار تقریباً ۳ تا ۵ دقیقه طول می‌کشد]

ایجاد شاخص 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 هستند.

۴. درک معماری

قبل از ایجاد تغییرات در کد، بیایید نحوه ساخت سیستم را درک کنیم. معماری از یک الگوی «بیداری» پیش‌رونده پیروی می‌کند:

پشته عامل

نماینده بینایی (agents/vision-agent/)

  • agent.py — منطق فلش Core Gemini 3. تصاویر را با اجرای کد فعال به مدل ارسال می‌کند، بنابراین پایتون (OpenCV) را طوری می‌نویسد که موارد را به صورت قطعی بشمارد.
  • agent_executor.py — درخواست‌های پروتکل A2A را به منطق عامل متصل می‌کند.
  • main.py — سرور A2A شرکت Uvicorn که فایل /.well-known/agent-card.json را ارائه می‌دهد و درخواست‌ها را مدیریت می‌کند.

نماینده تأمین‌کننده (نمایندگان/نماینده تأمین‌کننده/)

  • inventory.py — از طریق رابط پایتون AlloyDB به AlloyDB متصل می‌شود (نیازی به Auth Proxy نیست). شامل تابع find_supplier() است که جستجوی برداری ScaNN را انجام می‌دهد.
  • agent_executor.py — پروتکل A2A را به منطق جستجوی موجودی متصل می‌کند.
  • main.py — سرور Uvicorn A2A با کارت عامل و نقطه پایانی سلامت.

برج مراقبت (جلو/)

  • app.py — سرور FastAPI + WebSocket که از طریق A2A عامل‌ها را کشف می‌کند، خط لوله بینایی → جستجو → سفارش را هماهنگ می‌کند و به‌روزرسانی‌های بلادرنگ را به مرورگر ارسال می‌کند.

جریان A2A

  • برج کنترل فایل /.well-known/agent-card.json را از هر عامل می‌خواند.
  • قابلیت‌ها (مهارت‌ها، نقاط پایانی) را کشف می‌کند - بدون URLهای کدگذاری‌شده‌ی سخت
  • تصویر را به Vision Agent ارسال می‌کند → تعداد اقلام + توضیحات را دریافت می‌کند
  • توضیحات را به عنوان درخواست جاسازی به نماینده تأمین‌کننده ارسال می‌کند → تطابق قطعه را دریافت می‌کند
  • سفارش را به صورت خودکار ثبت می‌کند

اتصال AlloyDB

نماینده تأمین‌کننده به جای پروکسی احراز هویت سنتی، از رابط پایتون AlloyDB استفاده می‌کند: 

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، SSL/TLS و مسیریابی اتصال را به طور خودکار مدیریت می‌کند. هنگام استقرار در Cloud Run، کافیست ip_type را برای دسترسی VPC به "PRIVATE" تغییر دهید.

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

نماینده تأمین‌کننده با استفاده از AlloyDB ScaNN میلیون‌ها قطعه را به خاطر می‌سپارد. در حال حاضر، این سرویس با یک پرس‌وجوی placeholder ارسال می‌شود - یک فراموشکار که صرف نظر از آنچه شما جستجو می‌کنید، اولین ردیفی را که پیدا می‌کند، برمی‌گرداند.

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

اگر اکنون از نماینده تأمین‌کننده پرس‌وجو کنید، یک نتیجه تصادفی برمی‌گرداند. هیچ مفهومی از شباهت ندارد. بیایید این مشکل را حل کنیم.

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

سرور 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 با پیکربندی عامل (باید بدون خطا برگردانده شود)

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

فایل agents/supplier-agent/inventory.py را باز کنید و تابع find_supplier() را در حدود خطوط ۶۰-۷۰ پیدا کنید. عبارت زیر را مشاهده خواهید کرد: 

# 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 به طور خودکار این پرس و جو را تسریع می‌کند!

مرحله ۴: فایل را ذخیره کنید (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 چشم‌ها را بیدار کنیم. عامل بینایی از طریق اجرای کد، "محاسبات بصری" را انجام می‌دهد.

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

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

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

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

ما اجرای کد و 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="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"؟

برای این کار (شمارش اقلام از طریق اجرای کد)، "MINIMAL" استدلال کافی برای برنامه‌ریزی اسکریپت و تأیید شمارش را فراهم می‌کند. استفاده از "HIGH" باعث افزایش 2 تا 3 برابری تأخیر بدون بهبود دقت برای کارهای قطعی می‌شود. بهینه‌سازی هزینه-عملکرد - عمق استدلال را با پیچیدگی کار مطابقت دهید.

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

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

🔄 بررسی مسیر: اگر هنوز در مسیر 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 - الگوی معماری برای سیستم‌های خودمختار - را فراهم می‌کند.

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

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

کارت عامل از قبل در 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?"]
  }]
}

می‌توانید نام، توضیحات یا مثال‌ها را متناسب با مورد استفاده خود سفارشی کنید.

برای بارگذاری کارت، نماینده تأمین‌کننده را مجدداً راه‌اندازی کنید:

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

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

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

  • عامل بینایی روی پورت ۸۰۸۱
  • نماینده تأمین‌کننده روی پورت ۸۰۸۲
  • برج کنترل روی پورت ۸۰۸۰

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

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

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

  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: تأیید کنید که IP عمومی در نمونه AlloyDB شما فعال است

۹. 🎁 جایزه: استقرار در Cloud Run

اختیاری — همه چیز به صورت محلی کار می‌کند! اما اگر می‌خواهید ساخته‌ی خود را با یک URL عمومی به اشتراک بگذارید: 

# From repo root
sh deploy/deploy.sh

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

  1. پیکربندی .env شما را می‌خواند
  2. نام شما را می‌پرسد (در برنامه‌ی اجرا شده نمایش داده می‌شود)
  3. هر 3 سرویس را به عنوان یک کانتینر Cloud Run واحد مستقر می‌کند
  4. نقش‌های IAM را برای دسترسی به AlloyDB اعطا می‌کند.
  5. یک URL قابل اشتراک‌گذاری را خروجی می‌دهد

بازدیدکنندگانی که URL شما را باز می‌کنند، یک پنجره بازشو (popup) مشاهده خواهند کرد:

۱۰. پاکسازی

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

# From repo root
sh deploy/cleanup.sh

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

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

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

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

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

مستندات رسمی

فلش جمینی ۳:

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

جعبه ابزار MCP برای پایگاه‌های داده (رویکرد جایگزین):

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

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

ویژگی

ادعا

منبع

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) استفاده می‌کند - در سطح سازمانی، آماده برای انطباق

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

مراحل بعدی