Gemini 3 Flash और AlloyDB AI की मदद से, ऑटोनॉमस सप्लाई चेन बनाना

1. खास जानकारी

"पढ़ने वाले चैटबॉट" का दौर खत्म हो रहा है. हम एजेंटिक विज़न के दौर में प्रवेश कर रहे हैं.

इस कोडलैब में, हम डिटरमिनिस्टिक एआई इंजीनियरिंग को लागू करेंगे. यह एआई सिस्टम बनाने का एक तरीका है, जिसमें सिस्टम अनुमान नहीं लगाता. किसी जटिल इमेज में मौजूद आइटम की गिनती करने के लिए कहने पर, स्टैंडर्ड एआई मॉडल अक्सर "हैलुसिनेट" (अनुमान लगाना) करते हैं. सप्लाई चेन में, अनुमान लगाना खतरनाक हो सकता है. अगर एआई को लगता है कि आपके पास 12 आइटम हैं, जबकि असल में आपके पास 15 आइटम हैं, तो इससे गड़बड़ियां हो सकती हैं.

हम Gemini 3 Flash में, सोचो, काम करो, देखो वाले नए लूप का इस्तेमाल करके, ऑटोनॉमस सप्लाई चेन एजेंट बनाएंगे. यह सिर्फ़ देखता नहीं, बल्कि जांच भी करता है.

डिटरमिनिस्टिक आर्किटेक्चर

हम "ब्लाइंड" और "एमनेज़ियाक" सिस्टम से शुरुआत करेंगे. आपको एक-एक करके, मैन्युअल तरीके से इसके सेंसर "चालू" करने होंगे:

17191a91a9c54146.png

  1. The Eyes (Vision Agent): हम Gemini 3 Flash को कोड एक्ज़ीक्यूशन की सुविधा के साथ उपलब्ध कराते हैं. किसी संख्या का अनुमान लगाने के लिए टोकन का अनुमान लगाने के बजाय, मॉडल पिक्सल की गिनती करने के लिए Python कोड (OpenCV) लिखता है.
  2. मेमोरी (सप्लायर एजेंट): हम AlloyDB AI को ScaNN (स्केलेबल नियरेस्ट नेबर) के साथ इस्तेमाल करते हैं. इससे एजेंट को लाखों विकल्पों में से, किसी हिस्से के लिए सही सप्लायर का पता लगाने में कुछ ही मिलीसेकंड लगते हैं.
  3. हैंडशेक (A2A प्रोटोकॉल): हम स्टैंडर्ड agent_card.json का इस्तेमाल करके, एजेंट-टू-एजेंट कम्यूनिकेशन की सुविधा चालू करते हैं. इससे विज़न एजेंट, सप्लायर एजेंट से स्टॉक अपने-आप ऑर्डर कर सकता है.

आपको क्या बनाना है

  • एक विज़न एजेंट, जो कैमरे से मिले फ़ीड पर "विज़ुअल मैथ" करता है.
  • तेज़ गति से वेक्टर खोजने के लिए, AlloyDB ScaNN की मदद से काम करने वाला सप्लायर एजेंट.
  • ऑटोनॉमस लूप को विज़ुअलाइज़ करने के लिए, रीयल-टाइम WebSocket अपडेट के साथ Control Tower फ़्रंटएंड.

आपको क्या सीखने को मिलेगा

  • Gemini API का इस्तेमाल करके, gemini-3-flash-preview के साथ Agentic Vision को चालू करने का तरीका.
  • AlloyDB में <=> (कोसाइन दूरी) ऑपरेटर का इस्तेमाल करके, वेक्टर सर्च को लागू करने का तरीका.
  • Auth प्रॉक्सी का इस्तेमाल करके, Cloud Shell को AlloyDB से ब्रिज करने का तरीका.

ज़रूरी शर्तें

  • कोई ब्राउज़र, जैसे कि Chrome या Firefox
  • बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट.
  • Vision Agent के लिए, Gemini API पासकोड (Google AI Studio पर बिना शुल्क वाला टियर उपलब्ध है).

2. शुरू करने से पहले

प्रोजेक्ट बनाना

  1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
  2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.
  1. आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है. Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.

Cloud Shell बटन की इमेज चालू करें

  1. Cloud Shell से कनेक्ट होने के बाद, यह देखने के लिए कि आपकी पुष्टि हो चुकी है और प्रोजेक्ट को आपके प्रोजेक्ट आईडी पर सेट किया गया है, इस कमांड का इस्तेमाल करें:
gcloud auth list

हो गया!

अब एक क्लिक में सेट अप करने की सुविधा का इस्तेमाल किया जा सकता है. अगले सेक्शन में यह जानकारी दी गई है:

  • Cloud Shell को अपने-आप खुलने की अनुमति देना
  • रिपॉज़िटरी को क्लोन करना
  • इंटरैक्टिव ट्यूटोरियल में, आपको पूरे सेटअप की जानकारी देना

3. Cloud Shell में एक क्लिक में सेटअप करने की सुविधा

हमने सेटअप को Cloud Shell के निर्देशों वाले ट्यूटोरियल में शामिल कर दिया है. सब कुछ अपने-आप होता है: इंफ़्रास्ट्रक्चर प्रोविज़निंग, AlloyDB सेटअप, Auth Proxy कॉन्फ़िगरेशन, और डेटाबेस सीडिंग.

Cloud Shell का ट्यूटोरियल लॉन्च करें

⚠️ अहम जानकारी - क्लिक करने से पहले: नीचे दिए गए बटन पर क्लिक करने पर, आपको एक सुरक्षा डायलॉग दिखेगा. इसमें "Cloud Shell में खोलें" का विकल्प होगा. यह रिपॉज़िटरी क्लोन करने से पहले दिखता है.

इसलिए, आपको ये करने होंगे:

  1. ✅ बॉक्स पर सही का निशान लगाएं: "ट्रस्ट रिपो"
  2. ✅ "पुष्टि करें" पर क्लिक करें

इसके बिना, रिपॉज़िटरी क्लोन नहीं की जाएगी.

क्या आप तैयार हैं? चरण-दर-चरण निर्देशों वाला प्रोजेक्ट खोलने के लिए, यहां क्लिक करें:

इसके बाद क्या होगा:

  1. Cloud Shell में, पहले से क्लोन की गई रिपॉज़िटरी खुलती है
  2. दाईं ओर एक ट्यूटोरियल पैनल दिखता है, जिसमें चरण-दर-चरण निर्देश दिए गए हैं
  3. आपको इन चीज़ों के बारे में बताया जाएगा:
  • Gemini API पासकोड पाना (बिना शुल्क वाली सुविधा उपलब्ध है)
  • टर्मिनल में अपना GCP प्रोजेक्ट सेट अप करना
  • सेटअप चल रहा है (एपीआई की जांच करता है, ज़रूरत पड़ने पर उन्हें चालू करता है, और AlloyDB उपलब्ध कराता है: ~15 मिनट)
  • दो मुख्य कोड में बदलाव करना (देखने और याद रखने की सुविधा चालू करना)
  • एजेंट कार्ड बनाना (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

सेटअप स्क्रिप्ट में दिए गए निर्देशों का पालन करें.

आगे क्या करना है: ट्यूटोरियल में, आपको बाकी चरणों के बारे में बताया गया है. यह प्रोसेस पूरी होने के बाद, सेक्शन 4 पर जाएं. इससे आपको यह समझने में मदद मिलेगी कि बिडिंग की रणनीति की परफ़ॉर्मेंस के बारे में कैसे पता चलता है

4. बिहाइंड द सीन: Auth Proxy & Database Seeding

समस्या: AlloyDB, प्राइवेट वीपीसी में मौजूद होता है. Cloud Shell इसके बाहर है. सीधे तौर पर कनेक्ट नहीं किया जा सकता.

समस्या हल करने का तरीका: AlloyDB Auth Proxy, Cloud Shell पर 127.0.0.1:5432 से आपके AlloyDB इंस्टेंस तक एक सुरक्षित, IAM से पुष्टि की गई टनल बनाता है. अगर आपके इंस्टेंस में सार्वजनिक आईपी चालू है, तो प्रॉक्सी इसका इस्तेमाल करती है. अगर ऐसा नहीं है, तो यह वीपीसी के निजी आईपी के ज़रिए कनेक्ट होती है.

setup.sh ने क्या किया

  1. AlloyDB इंस्टेंस (क्लस्टर, क्षेत्र, प्रोजेक्ट) का अपने-आप पता लगाया गया
  2. सभी क्रेडेंशियल (GEMINI_API_KEY, DB_PASS, AlloyDB की जानकारी) के साथ .env फ़ाइल बनाई गई
  3. Auth Proxy को डाउनलोड और चालू किया गया (लागू होने पर –public-ip के साथ)
  4. डेटाबेस में इन्वेंट्री के आठ सैंपल पार्ट और ScaNN इंडेक्स शामिल किए गए

आपकी .env फ़ाइल तैयार है. आने वाले समय में होने वाले सभी रन के लिए, क्रेडेंशियल अपने-आप लोड हो जाते हैं.

पुष्टि करें कि यह काम कर रहा है

पक्का करें कि आप अब भी repo root में हों

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

देखें कि Auth Proxy चालू है या नहीं

ps aux | grep alloydb-auth-proxy

क्या बनाया गया

  • आठ हिस्सों वाली इन्वेंट्री टेबल और 768 डाइमेंशनल एम्बेडिंग
  • तेज़ी से वेक्टर खोजने के लिए, ScaNN इंडेक्स (idx_inventory_scann)

5. पहला चरण: मेमोरी (सप्लायर एजेंट)

सप्लायर एजेंट, AlloyDB ScaNN का इस्तेमाल करके लाखों पार्ट्स की जानकारी याद रखता है. हम इसे A2A सर्वर के तौर पर शुरू करते हैं. इसके बाद, वेक्टर क्वेरी को ठीक करते हैं.

The Audit: The Amnesiac

अगर अब सप्लायर एजेंट से क्वेरी की जाती है (प्लेसहोल्डर एसक्यूएल के साथ), तो यह पहली पंक्ति दिखाता है, न कि सबसे नज़दीकी मैच. इसमें समानता का कोई कॉन्सेप्ट नहीं है. यह एक भूलने की बीमारी है.

सप्लायर एजेंट शुरू करना

A2A सर्वर (main.py), agent_executor.py को डेलिगेट करता है. यह inventory.py में मौजूद बिज़नेस लॉजिक के लिए प्रोटोकॉल को ब्रिज करता है.

pkill -f uvicorn #Kill all uvicorn processes

पहला चरण: एजेंट डायरेक्ट्री पर जाना

cd agents/supplier-agent

दूसरा चरण: डिपेंडेंसी इंस्टॉल करना

pip install -r requirements.txt

तीसरा चरण: एजेंट सर्वर शुरू करना

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 (इसमें कोई गड़बड़ी नहीं होनी चाहिए)

रीयल सिमैंटिक एम्बेडिंग

सेटअप के दौरान, डेटाबेस में असली सिमैंटिक एम्बेडिंग डाली गई थीं. इन्हें Google के Gen AI SDK के text-embedding-005 मॉडल से जनरेट किया गया था. इससे यह पक्का होता है कि समानता के आधार पर सटीक मैचिंग हो. इसमें रैंडम वेक्टर का इस्तेमाल नहीं किया जाता. सीडिंग की प्रोसेस में, 13 सैंपल आइटम के लिए ~10 सेकंड लगते हैं. इसमें पैरलल एम्बेडिंग जनरेशन का इस्तेमाल किया जाता है, ताकि 768 डाइमेंशन वाले काम के वेक्टर बनाए जा सकें. ये वेक्टर, हर हिस्से के सिमैंटिक मतलब को कैप्चर करते हैं.

AlloyDB Detour: ScaNN का इस्तेमाल क्यों किया जाता है?

समस्या हल करने का तरीका: <=> ऑपरेटर लागू करना

एजेंट को प्लेसहोल्डर क्वेरी के साथ शिप किया जाता है. हमें ScaNN वेक्टर सर्च चालू करनी होगी.

पहला चरण: इन्वेंट्री फ़ाइल खोलें

cd agents/supplier-agent

दूसरा चरण: inventory.py में TODO ढूंढना

लाइन 47 से 60 के बीच 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)

तीसरा चरण: प्लेसहोल्डर एसक्यूएल को 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, एजेंट कार्ड दिखाता है. Python स्निपेट, सीड किए गए डेटा से पार्ट और सप्लायर की जानकारी दिखाता है.

6. दूसरा चरण: आंखें (विजन एजेंट)

डेटाबेस ऐक्सेस किया जा सकता है. इसलिए, Gemini 3 Flash का इस्तेमाल करके, आंखों को जगाते हैं. विज़न एजेंट, कोड एक्ज़ीक्यूशन की मदद से "विज़ुअल मैथ" करता है. A2A सर्वर (main.py), agent_executor.py को काम सौंपता है. यह agent.py को कॉल करता है, ताकि Gemini विश्लेषण कर सके.

ऑडिट: मनगढ़ंत जानकारी

अगर किसी स्टैंडर्ड मल्टीमॉडल मॉडल से पूछा जाए कि "इस इमेज में कितने बॉक्स हैं?", तो वह इमेज को स्टैटिक स्नैपशॉट के तौर पर प्रोसेस करता है और अनुमान लगाता है.

  • मॉडल कहता है: "मुझे करीब 12 बॉक्स दिख रहे हैं."
  • असल में: यहां 15 बॉक्स हैं.
  • नतीजा: सप्लाई चेन से जुड़ी गड़बड़ी हुई है.

समस्या हल करने का तरीका: सोचो-काम करो-देखो लूप को चालू करना

हम कोड एक्ज़ीक्यूशन और ThinkingConfig को चालू करते हैं, ताकि मॉडल Python (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" में ये काम करने के लिए ज़रूरी बजट मिलता है:

  • Python स्क्रिप्ट के स्ट्रक्चर की योजना बनाना
  • तय करें कि इमेज प्रोसेसिंग के लिए किस तरीके का इस्तेमाल करना है
  • पुष्टि करें कि गिनती, बाउंडिंग बॉक्स की संख्या से मेल खाती हो

"HIGH" का इस्तेमाल करने से, टास्क पूरा होने में दो से तीन गुना ज़्यादा समय लगेगा और लागत भी बढ़ेगी. हालांकि, इससे डिटरमिनिस्टिक टास्क के लिए सटीकता में कोई सुधार नहीं होगा. "HIGH" का इस्तेमाल, कई चरणों में की जाने वाली मुश्किल रीज़निंग के लिए करें. उदाहरण के लिए, "सप्लाई चेन में आई इस रुकावट का विश्लेषण करो और तीन अन्य सप्लायर के नाम बताओ. साथ ही, यह भी बताओ कि उन्हें क्यों चुना जाना चाहिए").

लागत-परफ़ॉर्मेंस ऑप्टिमाइज़ेशन, प्रोडक्शन एआई इंजीनियरिंग के लिए एक अहम स्किल है: टास्क की जटिलता के हिसाब से तर्क की गहराई को मैच करना.

Vision Agent को शुरू करना

🔄 पाथ की जांच करें: अगर आप अब भी agents/supplier-agent/ में हैं, तो cd ../.. का इस्तेमाल करके, पहले repo root पर वापस जाएं

पहला चरण: विज़न एजेंट डायरेक्ट्री पर जाना

cd agents/vision-agent

दूसरा चरण: डिपेंडेंसी इंस्टॉल करना

pip install -r requirements.txt

तीसरा चरण: विज़न एजेंट सर्वर शुरू करना

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

7. तीसरा चरण: हैंडशेक (A2A एजेंट कार्ड)

हमारे एजेंट को समस्या (Vision) दिखती है और उसे सप्लायर (Memory) के बारे में पता है. A2A प्रोटोकॉल, डाइनैमिक डिस्कवरी की सुविधा देता है. इससे फ़्रंटएंड को, कार्ड पढ़कर हर एजेंट से बातचीत करने का तरीका पता चलता है.

A2A बनाम पारंपरिक REST API

Aspect

ट्रेडिशनल REST

A2A प्रोटोकॉल

एंडपॉइंट डिस्कवरी

कॉन्फ़िगरेशन में हार्डकोड किए गए यूआरएल

/.well-known/agent-card.json के ज़रिए डाइनैमिक

सुविधा की जानकारी

एपीआई दस्तावेज़ (लोगों के लिए)

कौशल (मशीन से पढ़ा जा सकता है)

इंटिग्रेशन

हर सेवा के लिए मैन्युअल कोड

सिमेंटिक मैचिंग: "मुझे इन्वेंट्री खोज की सुविधा चाहिए" → स्किल का पता चलता है

नया एजेंट जोड़ा गया

सभी क्लाइंट के कॉन्फ़िगरेशन अपडेट करें

अलग से किसी कॉन्फ़िगरेशन की ज़रूरत नहीं होती—अपने-आप पता लगाया जाता है

असल दुनिया में फ़ायदा: पारंपरिक माइक्रोसेवा में, अगर आपको तीसरा "लॉजिस्टिक्स एजेंट" जोड़ना है, तो आपको कंट्रोल टॉवर के कोड को उसके यूआरएल और एपीआई अनुबंध के साथ अपडेट करना होगा. A2A की मदद से, कंट्रोल टॉवर को इसका अपने-आप पता चल जाता है. साथ ही, यह बोलचाल की भाषा में बताई गई जानकारी से इसकी क्षमताओं को समझ लेता है.

इसलिए, A2A प्लग-एंड-प्ले एजेंट कंपोज़िशन की सुविधा देता है. यह स्वायत्त सिस्टम के लिए आर्किटेक्चरल पैटर्न है.

समस्या हल करने का तरीका: एजेंट कार्ड बनाना

हमें यह तय करना होगा कि सप्लायर एजेंट क्या-क्या कर सकता है.

  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. Supplier Agent को रीस्टार्ट करें, ताकि वह नया कार्ड लोड कर सके:

पहला चरण: चालू एजेंट को बंद करना

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

दूसरा चरण: एजेंट डायरेक्ट्री पर जाएं

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

8. चौथा चरण: कंट्रोल टावर

FastAPI + WebSockets की मदद से, Control Tower के फ़्रंटएंड को चलाएं. यह A2A के ज़रिए एजेंटों का पता लगाता है और रीयल-टाइम अपडेट के साथ पूरे लूप को व्यवस्थित करता है.

सभी सेवाएं शुरू करें

सभी सेवाओं को शुरू करने का सबसे आसान तरीका:

पुष्टि करें कि आप रेपो रूट में हैं

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

इसके बाद,

sh run.sh

इस एक निर्देश से ये काम शुरू हो जाते हैं:

  • AlloyDB Auth प्रॉक्सी (अगर चालू नहीं है)
  • पोर्ट 8081 पर विज़न एजेंट
  • पोर्ट 8082 पर सप्लायर एजेंट
  • पोर्ट 8080 पर कंट्रोल टावर

सभी सेवाओं के शुरू होने के लिए, करीब 10 सेकंड इंतज़ार करें.

सिस्टम की जांच करना

कंट्रोल टावर को ऐक्सेस करना:

  1. Cloud Shell टूलबार में मौजूद, वेब प्रीव्यू बटन (आंख वाला आइकॉन 👁️) पर क्लिक करें
  2. "पोर्ट 8080 पर झलक देखें" को चुनें
  3. Control Tower डैशबोर्ड नए टैब में खुलेगा

डेमो चलाएं:

  1. सबसे ऊपर दाईं ओर: कनेक्शन की स्थिति (हरा "लाइव" बिंदु), डेमो/ऑटो मोड टॉगल, और ऑडियो कंट्रोल
  2. सेंटर: इमेज अपलोड करने और विश्लेषण के विज़ुअलाइज़ेशन के साथ मुख्य वर्कफ़्लो कैनवस
  3. साइड पैनल (विश्लेषण के दौरान दिखते हैं): वर्कफ़्लो टाइमलाइन (बाईं ओर), प्रोग्रेस ट्रैकिंग और कोड व्यूअर (दाईं ओर)

पहला विकल्प: क्विक स्टार्ट (सुझाया गया)

  1. होम पेज पर, आपको "जल्दी शुरू करें" सेक्शन दिखेगा. इसमें सैंपल इमेज भी दिखेंगी
  2. विश्लेषण अपने-आप शुरू करने के लिए, किसी भी सैंपल इमेज पर क्लिक करें
  3. ऑटोनॉमस वर्कफ़्लो (~30 से 45 सेकंड) देखें

दूसरा विकल्प: खुद का डेटा अपलोड करना

  1. वेयरहाउस/शेल्फ़ की इमेज (PNG, JPG, 10 एमबी तक) को खींचकर छोड़ें या ब्राउज़ करने के लिए क्लिक करें
  2. "ऑटोनॉमस वर्कफ़्लो शुरू करें" पर क्लिक करें
  3. चार चरणों वाली पाइपलाइन को देखें

क्या होता है:

  1. एजेंट की खोज: A2A प्रोटोकॉल के मॉडल, विज़न एजेंट और सप्लायर एजेंट के कार्ड दिखाते हैं. इनमें उनकी क्षमताएं और एंडपॉइंट शामिल होते हैं
  2. इमेज का विश्लेषण: Gemini 3 Flash, आइटम की गिनती करने के लिए Python कोड (OpenCV) जनरेट करता है और उसे लागू करता है. प्रोग्रेस बार में उप-चरण दिखाए गए हैं. पहचाने गए आइटम पर बाउंडिंग बॉक्स ओवरले होते हैं. नतीजे वाले बैज में "✓ कोड की पुष्टि हो गई" या "~ अनुमानित" दिखता है
  3. सप्लायर मैच: AlloyDB ScaNN वेक्टर सर्च ऐनिमेशन. खोज क्वेरी डिसप्ले (उदाहरण के लिए, "इंडस्ट्रियल मेटल बॉक्स"). नतीजे वाले कार्ड में, मैच किया गया हिस्सा, सप्लायर, और कॉन्फ़िडेंस स्कोर दिखता है
  4. ऑर्डर किया गया: ऑर्डर आईडी, संख्या, और जानकारी के साथ रसीद कार्ड

सलाह: प्रज़ेंटेशन के दौरान हर चरण पर रुकने के लिए, सबसे ऊपर दाईं ओर मौजूद DEMO मोड को चालू रखें. ऑटो मोड में, वर्कफ़्लो लगातार चलता रहता है.

1a031c4fd407a183.png

यह क्या हुआ

Control Tower ने A2A प्रोटोकॉल का इस्तेमाल करके, दोनों एजेंटों का पता लगाया. इसके लिए, /.well-known/agent-card.json का इस्तेमाल किया गया. साथ ही, विज़न विश्लेषण (कोड एक्ज़ीक्यूशन के साथ Gemini 3 Flash), वेक्टर सर्च (AlloyDB ScaNN) किया गया. इसके अलावा, बिना किसी मानवीय सहायता के ऑर्डर दिया गया. इन सभी कामों के लिए, रीयल-टाइम WebSocket अपडेट का इस्तेमाल किया गया. हर एजेंट, A2A स्टैंडर्ड के ज़रिए अपनी क्षमताओं को दिखाता है. इससे कस्टम एसडीके के बिना, प्लग-एंड-प्ले कंपोज़िशन की सुविधा मिलती है. ज़्यादा जानें: 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 Proxy चल रहा है:
ps aux | grep alloydb-auth-proxy

AlloyDB से कनेक्शन बनाने में आने वाली समस्याएं:

अगर आपको 127.0.0.1 पर सर्वर से कनेक्शन नहीं बन सका, पोर्ट 5432 की गड़बड़ी दिखती है, तो:

अगर आपको 127.0.0.1 पर सर्वर से कनेक्शन नहीं बन सका, पोर्ट 5432 की गड़बड़ी दिखती है, तो:

  1. Auth Proxy की जांच करें: ps aux | grep alloydb-auth-proxy
  2. पुष्टि करें कि सार्वजनिक आईपी चालू है: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
  3. लोकल डेवलपमेंट के लिए (Cloud Shell के लिए नहीं):
  4. समस्या: Cloud Shell अपने-आप काम करता है, लेकिन लोकल मशीनों के लिए अनुमति वाले नेटवर्क की ज़रूरत होती है
  5. समाधान: sh setup.sh को फिर से चलाएं और प्रॉम्प्ट मिलने पर, पहला विकल्प (authorize 0.0.0.0/0) चुनें
  6. सुरक्षा से जुड़ी जानकारी: 0.0.0.0/0 के साथ भी कनेक्शन के लिए इनकी ज़रूरत होती है:
  7. मान्य GCP क्रेडेंशियल (ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल)
  8. डेटाबेस का पासवर्ड
  9. एमटीएलएस एन्क्रिप्शन (इसकी ज़िम्मेदारी Auth Proxy की होती है)

9. साफ़-सफ़ाई सेवा

शुल्क से बचने के लिए, अपने-आप साफ़ होने वाली स्क्रिप्ट का इस्तेमाल करके सभी संसाधनों को मिटाएं:

# From repo root
sh cleanup.sh

इससे ये चीज़ें सुरक्षित तरीके से हट जाती हैं:

  • AlloyDB क्लस्टर (लागत का मुख्य सोर्स)
  • Cloud Run की सेवाएं (अगर डिप्लॉय की गई हैं)
  • जुड़े हुए सेवा खाते

स्क्रिप्ट, किसी भी आइटम को मिटाने से पहले पुष्टि करने के लिए कहेगी.

10. रेफ़रंस और इसके बारे में ज़्यादा जानकारी

इस कोडलैब में किए गए सभी तकनीकी दावों की पुष्टि, Google Cloud और Google के एआई से जुड़े आधिकारिक दस्तावेज़ों से की गई है.

आधिकारिक दस्तावेज़

Gemini 3 Flash:

AlloyDB AI और ScaNN:

किराये की जानकारी:

परफ़ॉर्मेंस से जुड़े पुष्टि किए गए दावे

सुविधा

दावा करें

सोर्स

ScaNN बनाम HNSW (फ़िल्टर किया गया)

10 गुना तेज़ी से

Google Cloud Blog (सत्यापित)

ScaNN बनाम HNSW (स्टैंडर्ड)

चार गुना तेज़ी से

Google Cloud Blog (सत्यापित)

ScaNN का मेमोरी फ़ुटप्रिंट

3 से 4 गुना छोटा

Google Cloud Blog (सत्यापित)

ScaNN इंडेक्स बनाने में लगने वाला समय

आठ गुना तेज़ी से

Google Cloud Blog (सत्यापित)

कोड को चलाने में टाइम आउट से ज़्यादा समय लगा

ज़्यादा से ज़्यादा 30 सेकंड

Google Cloud Docs (पुष्टि की गई)

कोड एक्ज़ीक्यूशन फ़ाइल I/O

ये काम नहीं करते हैं

Google Cloud Docs (पुष्टि की गई)

Temperature=0 का व्यवहार

डिटरमिनिस्टिक आउटपुट

समुदाय ने इसकी पुष्टि की है

अतिरिक्त संसाधन

एजेंट-टू-एजेंट (A2A) प्रोटोकॉल:

  • A2A, एजेंट को खोजने और उससे कम्यूनिकेट करने की प्रोसेस को स्टैंडर्ड बनाता है
  • /.well-known/agent-card.json पर दिखाए गए एजेंट कार्ड
  • ऑटोनॉमस एजेंट के साथ मिलकर काम करने के लिए नया स्टैंडर्ड

ScaNN रिसर्च:

  • Google Research के 12 सालों के अनुभव के आधार पर
  • Google Search और YouTube पर अरबों लोगों को सेवा देता है
  • सामान्य उपलब्धता के लिए रिलीज़ किया गया: अक्टूबर 2024
  • लाखों से लेकर अरबों वेक्टर के लिए, पहला PostgreSQL वेक्टर इंडेक्स

11. चैलेंज मोड: एआई एजेंट के तौर पर काम करने की अपनी स्किल को बेहतर बनाएं

आपने एक ऐसी सप्लाई चेन बनाई है जो अपने-आप काम करती है. क्या आपको और जानकारी चाहिए? इन चुनौतियों में, आपने जो पैटर्न सीखे हैं उन्हें नई समस्याओं पर लागू किया जाता है.

पहला चैलेंज: इमेज के आधार पर खोज करना (मल्टीमॉडल एम्बेडिंग)

मौजूदा फ़्लो: विज़न एजेंट, आइटम की गिनती करता है → टेक्स्ट क्वेरी जनरेट करता है → सप्लायर एजेंट, टेक्स्ट एम्बेड करता है → AlloyDB में खोज करता है

चैलेंज: टेक्स्ट को पूरी तरह से अनदेखा करें. काटी गई इमेज को सीधे तौर पर सप्लायर एजेंट को भेजें.

संकेत:

  1. Vision Agent, कोड को लागू करके शेल्फ़ की इमेज से अलग-अलग आइटम काट सकता है
  2. Vertex AI का multimodalembedding@001 मॉडल, इमेज को सीधे तौर पर एम्बेड कर सकता है
  3. इमेज बाइट को टेक्स्ट के बजाय स्वीकार करने के लिए, inventory.py में बदलाव करें
  4. A2A की सुविधा के बारे में जानकारी देने वाले टेक्स्ट को अपडेट करें, ताकि यह बताया जा सके कि "इमेज/jpeg या टेक्स्ट स्वीकार करता है"

यह क्यों ज़रूरी है: विज़ुअल सर्च, उन हिस्सों के लिए ज़्यादा सटीक होती है जो दिखने में जटिल होते हैं. जैसे, रंग में अंतर, नुकसान, पैकेजिंग में अंतर.

दूसरी चुनौती: निगरानी—पारदर्शिता से भरोसा जीतना

मौजूदा स्थिति: सिस्टम काम करता है, लेकिन आपको "अंडर द हुड" नहीं दिखता

चैलेंज: यह साबित करने के लिए कि वेक्टर सर्च काम कर रही है, AlloyDB के क्वेरी लॉग की जांच करें.

चरण:

  • AlloyDB पर क्वेरी की अहम जानकारी देने वाली सुविधा डिफ़ॉल्ट रूप से चालू होती है. पुष्टि करने के लिए, यह कमांड चलाएं:
gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"
  • यूज़र इंटरफ़ेस (यूआई) के ज़रिए सप्लायर खोजें
  • लागू की गई एसक्यूएल क्वेरी देखें:
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 क्वेरी दिखेगी. साथ ही, इसे पूरा होने में लगने वाला समय भी दिखेगा.

यह क्यों ज़रूरी है: ऑब्ज़र्वेबिलिटी से भरोसा बढ़ता है. जब स्टेकहोल्डर पूछते हैं कि "यह एजेंट फ़ैसले कैसे लेता है?", तो उन्हें सिर्फ़ आउटपुट दिखाने के बजाय क्वेरी प्लान दिखाया जा सकता है.

तीसरी चुनौती: मल्टी-एजेंट कंपोज़िशन

चुनौती: एक तीसरे एजेंट (लॉजिस्टिक्स एजेंट) को जोड़ें. यह एजेंट, गोदाम की जगह और आइटम के वज़न के हिसाब से शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क का हिसाब लगाता है.

आर्किटेक्चर:

  • Vision Agent के आउटपुट: आइटम की संख्या
  • सप्लायर एजेंट के आउटपुट: सप्लायर की जगह की जानकारी
  • लॉजिस्टिक्स एजेंट (नया) के इनपुट: मंज़िल, वज़न → आउटपुट: शिपिंग के लिए खरीदार से लिया जाने वाला शुल्क + ईटीए

अहम जानकारी: A2A प्रोटोकॉल की मदद से, इसे आसानी से किया जा सकता है. शिपिंग के लिए शुल्क का हिसाब लगाने की सुविधा वाला नया एजेंट कार्ड बनाएं. कंट्रोल टावर इसका अपने-आप पता लगा लेगा.

सीखा जा रहा पैटर्न: यह एजेंट-ओरिएंटेड आर्किटेक्चर का मुख्य हिस्सा है. इसमें छोटे-छोटे, कंपोज़ेबल स्पेशलिस्ट से जटिल सिस्टम बनाए जाते हैं.

12. नतीजा

आपने जनरेटिव एआई से एजेंटिक एआई पर स्विच कर लिया है.

हमने क्या बनाया:

  • विजन: हमने "अनुमान लगाने" की सुविधा को कोड एक्ज़ीक्यूशन (एपीआई पासकोड के ज़रिए Gemini 3 Flash) से बदल दिया है.
  • मेमोरी: हमने "खोज में ज़्यादा समय लगना" की समस्या को AlloyDB ScaNN (GCP के ज़रिए) से बदल दिया है.
  • कार्रवाई: हमने "एपीआई इंटिग्रेशन" को A2A प्रोटोकॉल से बदल दिया है.

हाइब्रिड आर्किटेक्चर के फ़ायदे:

इस कोडलैब में, हाइब्रिड अप्रोच के बारे में बताया गया है:

  • Vision Agent: यह Gemini API (एपीआई पासकोड) का इस्तेमाल करता है. यह इस्तेमाल करने में आसान है और इसका मुफ़्त टियर उपलब्ध है. इसके लिए, GCP बिलिंग की ज़रूरत नहीं होती
  • सप्लायर एजेंट: यह GCP (Vertex AI + AlloyDB) का इस्तेमाल करता है. यह एंटरप्राइज़-ग्रेड और अनुपालन के लिए तैयार है

यह स्वायत्त अर्थव्यवस्था का आर्किटेक्चर है. यह कोड आपके पास रहेगा.

अगले चरण