জেমিনি ৩ ফ্ল্যাশ এবং অ্যালয়ডিবি এআই দিয়ে একটি স্বায়ত্তশাসিত সরবরাহ শৃঙ্খল তৈরি করুন

1. সংক্ষিপ্ত বিবরণ

"পড়ার জন্য উপযুক্ত চ্যাটবট" এর যুগ শেষ হচ্ছে। আমরা এজেন্টিক ভিশনের যুগে প্রবেশ করছি।

এই কোডল্যাবে, আমরা ডিটারমিনিস্টিক এআই ইঞ্জিনিয়ারিং বাস্তবায়ন করব - এমন একটি অনুশীলন যা অনুমান করে না এমন এআই সিস্টেম তৈরি করে। একটি জটিল ছবিতে আইটেম গণনা করতে বলা হলে স্ট্যান্ডার্ড এআই মডেলগুলি প্রায়শই "হ্যালুসিনেট" (অনুমান) করে। একটি সরবরাহ শৃঙ্খলে, অনুমান করা বিপজ্জনক। যদি কোনও এআই অনুমান করে যে আপনার কাছে 12 টি আইটেম আছে যখন আসলে আপনার কাছে 15 টি আছে, তবে এটি ব্যয়বহুল ত্রুটির কারণ হয়।

আমরা জেমিনি ৩ ফ্ল্যাশের নতুন থিঙ্ক, অ্যাক্ট, অবজারভ লুপ ব্যবহার করে একটি অটোনোমাস সাপ্লাই চেইন এজেন্ট তৈরি করব। এটি কেবল দেখায় না; এটি তদন্ত করে।

নির্ধারক স্থাপত্য

আমরা একটি "অন্ধ" এবং "স্মৃতিভ্রংশ" সিস্টেম দিয়ে শুরু করব। আপনি একে একে এর ইন্দ্রিয়গুলিকে ম্যানুয়ালি "জাগ্রত" করবেন:

17191a91a9c54146.png সম্পর্কে

  1. চোখ (ভিশন এজেন্ট) : আমরা কোড এক্সিকিউশনের মাধ্যমে জেমিনি 3 ফ্ল্যাশ সক্ষম করি। টোকেন ব্যবহার করে সংখ্যা অনুমান করার পরিবর্তে, মডেলটি পিক্সেল নির্ধারণমূলকভাবে গণনা করার জন্য পাইথন কোড (ওপেনসিভি) লেখে।
  2. মেমোরি (সরবরাহকারী এজেন্ট) : আমরা ScaNN (স্কেলেবল নিকটতম প্রতিবেশী) দিয়ে AlloyDB AI সক্ষম করি। এটি এজেন্টকে মিলিসেকেন্ডে লক্ষ লক্ষ বিকল্প থেকে একটি অংশের জন্য সঠিক সরবরাহকারীকে প্রত্যাহার করতে দেয়।
  3. হ্যান্ডশেক (A2A প্রোটোকল) : আমরা একটি স্ট্যান্ডার্ডাইজড agent_card.json ব্যবহার করে এজেন্ট-টু-এজেন্ট যোগাযোগ সক্ষম করি, যা ভিশন এজেন্টকে সরবরাহকারী এজেন্টের কাছ থেকে স্বায়ত্তশাসিতভাবে স্টক অর্ডার করার অনুমতি দেয়।

তুমি কী তৈরি করবে

  • একটি ভিশন এজেন্ট যা ক্যামেরা ফিডে "ভিজ্যুয়াল ম্যাথ" করে।
  • উচ্চ-গতির ভেক্টর অনুসন্ধানের জন্য AlloyDB ScaNN দ্বারা সমর্থিত একটি সরবরাহকারী এজেন্ট ।
  • অটোনোমাস লুপটি কল্পনা করার জন্য রিয়েল-টাইম ওয়েবসকেট আপডেট সহ একটি কন্ট্রোল টাওয়ার ফ্রন্টএন্ড।

তুমি কি শিখবে

  • জেমিনি এপিআই ব্যবহার করে জেমিনি-৩-ফ্ল্যাশ-প্রিভিউ দিয়ে কীভাবে এজেন্টিক ভিশন সক্ষম করবেন।
  • AlloyDB-তে <=> (কোসাইন দূরত্ব) অপারেটর ব্যবহার করে ভেক্টর অনুসন্ধান কীভাবে বাস্তবায়ন করবেন।
  • Auth Proxy ব্যবহার করে AlloyDB-তে Cloud Shell কীভাবে ব্রিজ করবেন।

আবশ্যকতা

2. শুরু করার আগে

একটি প্রকল্প তৈরি করুন

  1. গুগল ক্লাউড কনসোলে , প্রজেক্ট সিলেক্টর পৃষ্ঠায়, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন।
  2. আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং সক্ষম আছে কিনা তা নিশ্চিত করুন। কোনও প্রোজেক্টে বিলিং সক্ষম আছে কিনা তা কীভাবে পরীক্ষা করবেন তা শিখুন ।
  1. আপনি ক্লাউড শেল ব্যবহার করবেন, যা গুগল ক্লাউডে চলমান একটি কমান্ড-লাইন পরিবেশ। গুগল ক্লাউড কনসোলের শীর্ষে অ্যাক্টিভেট ক্লাউড শেল ক্লিক করুন।

ক্লাউড শেল বোতামের ছবি সক্রিয় করুন

  1. ক্লাউড শেলের সাথে সংযুক্ত হয়ে গেলে, আপনি নিম্নলিখিত কমান্ড ব্যবহার করে পরীক্ষা করতে পারবেন যে আপনি ইতিমধ্যেই প্রমাণীকরণপ্রাপ্ত এবং প্রকল্পটি আপনার প্রকল্প আইডিতে সেট করা আছে কিনা: 
gcloud auth list

এটাই!

আপনি এখন এক-ক্লিক সেটআপের জন্য প্রস্তুত। পরবর্তী অংশে থাকবে:

  • স্বয়ংক্রিয়ভাবে ক্লাউড শেল খুলুন
  • সংগ্রহস্থলটি ক্লোন করুন
  • একটি ইন্টারেক্টিভ টিউটোরিয়ালে পুরো সেটআপটি আপনাকে গাইড করবে

৩. ক্লাউড শেলে এক-ক্লিক সেটআপ

আমরা সেটআপটিকে একটি নির্দেশিত ক্লাউড শেল টিউটোরিয়ালে সহজ করে তুলেছি। সবকিছুই স্বয়ংক্রিয়: অবকাঠামো প্রভিশনিং, অ্যালয়ডিবি সেটআপ, অথ প্রক্সি কনফিগারেশন এবং ডাটাবেস সিডিং।

ক্লাউড শেল টিউটোরিয়াল চালু করুন

⚠️ গুরুত্বপূর্ণ - ক্লিক করার আগে: যখন আপনি নীচের বোতামে ক্লিক করবেন, তখন আপনি "ক্লাউড শেলে খুলুন" জিজ্ঞাসা করে একটি নিরাপত্তা ডায়ালগ দেখতে পাবেন। এটি রিপোজিটরি ক্লোনের আগে প্রদর্শিত হবে।

তোমাকে অবশ্যই:

  1. ✅ " ট্রাস্ট রেপো " বাক্সটি চেক করুন।
  2. ✅ " নিশ্চিত করুন " এ ক্লিক করুন

এটি ছাড়া, সংগ্রহস্থলটি ক্লোন করা হবে না।

প্রস্তুত? ধাপে ধাপে টিউটোরিয়াল সহ প্রকল্পটি খুলতে ক্লিক করুন:

এরপর কি হবে:

  1. ক্লাউড শেল রিপোজিটরিটি আগে থেকে ক্লোন করে খোলে
  2. ডানদিকে ধাপে ধাপে নির্দেশাবলী সহ একটি টিউটোরিয়াল প্যানেল প্রদর্শিত হবে।
  3. আপনাকে নির্দেশিত করা হবে:
  • আপনার জেমিনি এপিআই কী পাওয়া (বিনামূল্যে স্তর উপলব্ধ)
  • টার্মিনালে আপনার GCP প্রকল্প সেট করা হচ্ছে
  • সেটআপ চালানো (API গুলি পরীক্ষা করে, প্রয়োজনে সক্ষম করে, AlloyDB সরবরাহ করে: ~15 মিনিট)
  • ২টি কী কোড পরিবর্তন করা হচ্ছে (দৃষ্টি + মেমোরি সক্ষম করুন)
  • এজেন্ট কার্ড তৈরি করা (A2A প্রোটোকল)
  • সকল পরিষেবা শুরু করা হচ্ছে

টিউটোরিয়ালটি ইন্টারেক্টিভ—প্রতিটি ধাপ নম্বরযুক্ত এবং আপনার অগ্রগতি ট্র্যাক করে।

বিকল্প: ম্যানুয়াল সেটআপ

যদি আপনি ম্যানুয়াল নিয়ন্ত্রণ পছন্দ করেন:

  1. ক্লাউড শেল খুলুন এবং আপনার প্রকল্পটি সেট করা আছে কিনা তা যাচাই করুন। 
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 এ যান।

৪. পর্দার আড়ালে: প্রমাণীকরণ প্রক্সি এবং ডাটাবেস বীজায়ন

সমস্যা : AlloyDB একটি প্রাইভেট VPC-এর ভেতরে থাকে। ক্লাউড শেল এর বাইরে থাকে। সরাসরি সংযোগ অসম্ভব।

সমাধান: AlloyDB Auth প্রক্সি ক্লাউড শেলের 127.0.0.1:5432 থেকে আপনার AlloyDB ইনস্ট্যান্সে একটি নিরাপদ, IAM-প্রমাণিত টানেল তৈরি করে। যদি আপনার ইনস্ট্যান্সে পাবলিক আইপি সক্রিয় থাকে, তাহলে প্রক্সি এটি ব্যবহার করে; অন্যথায় এটি VPC এর ব্যক্তিগত আইপির মাধ্যমে সংযোগ করে।

setup.sh কী করেছে?

  1. আপনার AlloyDB ইনস্ট্যান্স (ক্লাস্টার, অঞ্চল, প্রকল্প) স্বয়ংক্রিয়ভাবে সনাক্ত করা হয়েছে
  2. সমস্ত শংসাপত্র সহ .env তৈরি করা হয়েছে (GEMINI_API_KEY, DB_PASS, AlloyDB বিবরণ)
  3. Auth প্রক্সি ডাউনলোড এবং চালু করা হয়েছে (প্রযোজ্য হলে –public-ip সহ)
  4. ৮টি নমুনা ইনভেন্টরি যন্ত্রাংশ + ScaNN সূচক সহ ডাটাবেসটি সিড করা হয়েছে

আপনার .env ফাইল প্রস্তুত। ভবিষ্যতের সমস্ত রান স্বয়ংক্রিয়ভাবে শংসাপত্র লোড করবে।

এটি কাজ করেছে কিনা তা যাচাই করুন

নিশ্চিত করুন যে আপনি এখনও রেপো রুটে আছেন।

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

Auth প্রক্সি চলছে কিনা তা পরীক্ষা করুন

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

ধাপ ১: এজেন্ট ডিরেক্টরিতে নেভিগেট করুন

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 মডেলের মাধ্যমে তৈরি করা বাস্তব শব্দার্থিক এম্বেডিং দিয়ে সিড করা হয়েছিল। এটি সঠিক সাদৃশ্য ম্যাচিং নিশ্চিত করে - র্যান্ডম ভেক্টর নয়। সমান্তরাল এম্বেডিং জেনারেশন ব্যবহার করে ১৩টি নমুনা আইটেমের জন্য বীজ প্রক্রিয়াটি প্রায় ১০ সেকেন্ড সময় নেয় এবং প্রতিটি অংশের শব্দার্থিক অর্থ ধারণ করে এমন অর্থপূর্ণ ৭৬৮-মাত্রিক ভেক্টর তৈরি করে।

AlloyDB এর পথচলা: কেন ScaNN?

সমাধান: <=> অপারেটর বাস্তবায়ন করা

এজেন্ট একটি প্লেসহোল্ডার কোয়েরি পাঠায়। আমাদের ScaNN ভেক্টর অনুসন্ধান সক্ষম করতে হবে।

ধাপ ১: ইনভেন্টরি ফাইল খুলুন 

cd agents/supplier-agent

ধাপ ২: 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-এর কোসাইন দূরত্ব অপারেটর
  • 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 এজেন্ট কার্ডটি ফেরত দেয়। পাইথন স্নিপেটটি সিডেড ডেটা থেকে একটি অংশ এবং সরবরাহকারী ফেরত দেয়।

৬. ধাপ ২: চোখ (ভিশন এজেন্ট)

ডাটাবেসটি অ্যাক্সেসযোগ্য থাকাকালীন, আসুন জেমিনি 3 ফ্ল্যাশ ব্যবহার করে চোখ জাগিয়ে তুলি। ভিশন এজেন্ট কোড এক্সিকিউশনের মাধ্যমে "ভিজ্যুয়াল ম্যাথ" সম্পাদন করে। A2A সার্ভার (main.py) agent_executor.py-তে ডেলিগেট করে, যা জেমিনি বিশ্লেষণের জন্য agent.py কল করে।

নিরীক্ষা: হ্যালুসিনেশন

যদি আপনি একটি স্ট্যান্ডার্ড মাল্টিমোডাল মডেলকে জিজ্ঞাসা করেন "এই অগোছালো ছবিতে কয়টি বাক্স আছে?", এটি ছবিটিকে একটি স্ট্যাটিক স্ন্যাপশট হিসাবে প্রক্রিয়া করে এবং অনুমান করে।

  • মডেল বলেছেন: "আমি প্রায় ১২টি বাক্স দেখতে পাচ্ছি।"
  • বাস্তবতা: ১৫টি বাক্স আছে।
  • ফলাফল: সরবরাহ শৃঙ্খল ব্যর্থতা।

সমাধান: চিন্তা-কর্ম-পর্যবেক্ষণ চক্র জাগ্রত করা

আমরা কোড এক্সিকিউশন এবং থিংকনফিগ সক্ষম করি যাতে মডেলটি পাইথন (ওপেনসিভি) লিখে নির্ধারকভাবে গণনা করে।

  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" পর্যাপ্ত যুক্তি বাজেট প্রদান করে:

  • পাইথন স্ক্রিপ্ট কাঠামো পরিকল্পনা করুন
  • কোন ইমেজ প্রসেসিং পদ্ধতি ব্যবহার করবেন তা ঠিক করুন।
  • গণনাটি বাউন্ডিং বাক্সের সংখ্যার সাথে মেলে কিনা তা যাচাই করুন।

"উচ্চ" ব্যবহার করলে নির্ধারিত কাজের নির্ভুলতা উন্নত না করেই ২-৩ গুণ বিলম্ব এবং খরচ বাড়বে। জটিল বহু-পদক্ষেপের যুক্তির জন্য "উচ্চ" সংরক্ষণ করুন (যেমন, "এই সরবরাহ শৃঙ্খলের ব্যাঘাত বিশ্লেষণ করুন এবং যুক্তি সহ ৩টি বিকল্প সরবরাহকারীর সুপারিশ করুন")।

উৎপাদন কৃত্রিম বুদ্ধিমত্তা প্রকৌশলের জন্য খরচ-পারফরম্যান্স অপ্টিমাইজেশন একটি গুরুত্বপূর্ণ দক্ষতা: কাজের জটিলতার সাথে যুক্তির গভীরতা মেলানো।

ভিশন এজেন্ট শুরু করুন

🔄 পাথ চেক: যদি আপনি এখনও এজেন্ট/সরবরাহকারী-এজেন্ট/-এ থাকেন, তাহলে প্রথমে 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। ধাপ ৮-এ আপনি কন্ট্রোল টাওয়ার UI দিয়ে প্রকৃত দৃষ্টি গণনা পরীক্ষা করবেন।

dc9bc53007336472.png সম্পর্কে

৭. ধাপ ৩: হ্যান্ডশেক (A2A এজেন্ট কার্ড)

আমাদের এজেন্ট সমস্যাটি (ভিশন) দেখে এবং সরবরাহকারীকে (মেমোরি) চেনে। A2A প্রোটোকল গতিশীল আবিষ্কার সক্ষম করে — ফ্রন্টএন্ড প্রতিটি এজেন্টের কার্ড পড়ে তার সাথে কীভাবে কথা বলতে হয় তা শেখে।

A2A বনাম ঐতিহ্যবাহী REST API গুলি

দিক

ঐতিহ্যবাহী বিশ্রাম

A2A প্রোটোকল

এন্ডপয়েন্ট আবিষ্কার

কনফিগারেশনে হার্ডকোডেড URL গুলি

/.well-known/agent-card.json এর মাধ্যমে ডায়নামিক

ক্ষমতার বর্ণনা

API ডক্স (মানুষের জন্য)

দক্ষতা (মেশিন-পঠনযোগ্য)

ইন্টিগ্রেশন

প্রতিটি পরিষেবার জন্য ম্যানুয়াল কোড

শব্দার্থিক মিল: "আমার ইনভেন্টরি অনুসন্ধান দরকার" → দক্ষতা আবিষ্কার করে

নতুন এজেন্ট যোগ করা হয়েছে

সকল ক্লায়েন্টের কনফিগারেশন আপডেট করুন

শূন্য কনফিগারেশন—স্বয়ংক্রিয়ভাবে আবিষ্কৃত

বাস্তব-বিশ্বের সুবিধা: একটি ঐতিহ্যবাহী মাইক্রোসার্ভিসে, যদি আপনি তৃতীয় "লজিস্টিক এজেন্ট" যোগ করেন, তাহলে আপনাকে কন্ট্রোল টাওয়ারের কোডটি এর URL এবং API চুক্তির সাথে আপডেট করতে হবে। 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. সরবরাহকারী এজেন্ট পুনরায় চালু করুন যাতে এটি নতুন কার্ড লোড করে:

ধাপ ১: চলমান এজেন্ট বন্ধ করুন 

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।

অনুসরণ

৮. ধাপ ৪: কন্ট্রোল টাওয়ার

FastAPI + WebSockets দিয়ে কন্ট্রোল টাওয়ার ফ্রন্টএন্ড চালান। এটি A2A এর মাধ্যমে এজেন্টদের আবিষ্কার করে এবং রিয়েল-টাইম আপডেটের মাধ্যমে সম্পূর্ণ লুপ পরিচালনা করে।

সকল পরিষেবা শুরু করুন

সকল পরিষেবা শুরু করার সবচেয়ে সহজ উপায়:

আপনি রেপো রুটে আছেন কিনা তা যাচাই করুন। 

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

তারপর, 

sh run.sh

এই একক কমান্ডটি শুরু হয়:

  • AlloyDB Auth প্রক্সি (যদি চলমান না থাকে)
  • পোর্ট 8081-এ ভিশন এজেন্ট
  • পোর্ট 8082-এ সরবরাহকারী এজেন্ট
  • পোর্ট ৮০৮০-তে কন্ট্রোল টাওয়ার

সমস্ত পরিষেবা শুরু হওয়ার জন্য প্রায় ১০ সেকেন্ড অপেক্ষা করুন।

সিস্টেমটি পরীক্ষা করুন

কন্ট্রোল টাওয়ারে প্রবেশ করুন:

  1. ক্লাউড শেল টুলবারে ওয়েব প্রিভিউ বোতামে (চোখের আইকন 👁️) ক্লিক করুন।
  2. " পোর্ট 8080-এ প্রিভিউ " নির্বাচন করুন।
  3. কন্ট্রোল টাওয়ার ড্যাশবোর্ডটি একটি নতুন ট্যাবে খুলবে।

ডেমোটি চালান:

  1. উপরে ডানদিকে: সংযোগের অবস্থা (সবুজ "লাইভ" ডট), ডেমো/অটো মোড টগল এবং অডিও নিয়ন্ত্রণ
  2. কেন্দ্র : ছবি আপলোড এবং বিশ্লেষণ ভিজ্যুয়ালাইজেশন সহ প্রধান কর্মপ্রবাহ ক্যানভাস
  3. সাইড প্যানেল (বিশ্লেষণের সময় প্রদর্শিত হবে): ওয়ার্কফ্লো টাইমলাইন (বামে), অগ্রগতি ট্র্যাকিং এবং কোড ভিউয়ার (ডানে)

বিকল্প ১: দ্রুত শুরু (প্রস্তাবিত)

  1. হোমপেজে, আপনি নমুনা ছবি সহ একটি " দ্রুত শুরু " বিভাগ দেখতে পাবেন।
  2. বিশ্লেষণ স্বয়ংক্রিয়ভাবে শুরু করতে যেকোনো নমুনা ছবিতে ক্লিক করুন ।
  3. স্বায়ত্তশাসিত কর্মপ্রবাহ দেখুন (~৩০-৪৫ সেকেন্ড)

বিকল্প ২: আপনার নিজের আপলোড করুন

  1. একটি গুদাম/শেলফের ছবি টেনে আনুন এবং ছেড়ে দিন (PNG, JPG, সর্বোচ্চ 10MB পর্যন্ত) অথবা ব্রাউজ করতে ক্লিক করুন।
  2. " স্বায়ত্তশাসিত কর্মপ্রবাহ শুরু করুন " এ ক্লিক করুন।
  3. ৪-পর্যায়ের পাইপলাইনটি পর্যবেক্ষণ করুন

কি ঘটে:

  1. এজেন্ট আবিষ্কার: A2A প্রোটোকল মডেলগুলি ভিশন এজেন্ট এবং সরবরাহকারী এজেন্ট কার্ডগুলিকে তাদের দক্ষতা এবং শেষ বিন্দু সহ দেখায়।
  2. দৃষ্টি বিশ্লেষণ: জেমিনি 3 ফ্ল্যাশ আইটেম গণনা করার জন্য পাইথন কোড (ওপেনসিভি) তৈরি করে এবং কার্যকর করে। অগ্রগতি বার সাবস্টেপগুলি দেখায়। সনাক্ত করা আইটেমগুলির উপর বাউন্ডিং বাক্স ওভারলে করে। ফলাফল ব্যাজ "✓ কোড-যাচাইকৃত" বা "~ আনুমানিক" দেখায়।
  3. সরবরাহকারী মিল: AlloyDB ScaNN ভেক্টর অনুসন্ধান অ্যানিমেশন। অনুসন্ধান ক্যোয়ারী প্রদর্শন করে (যেমন, "শিল্প ধাতু বাক্স")। ফলাফল কার্ড মিলিত অংশ, সরবরাহকারী এবং আত্মবিশ্বাসের স্কোর দেখায়।
  4. অর্ডার করা হয়েছে: অর্ডার আইডি, পরিমাণ এবং বিশদ সহ রসিদ কার্ড

টিপস: উপস্থাপনার প্রতিটি পর্যায়ে বিরতি দেওয়ার জন্য ডেমো মোড (উপরে ডানদিকে) চালু রাখুন। অটো মোডে, কর্মপ্রবাহ অবিচ্ছিন্নভাবে চলে।

1a031c4fd407a183.png সম্পর্কে

কী হয়েছে

কন্ট্রোল টাওয়ার /.well-known/agent-card.json এর মাধ্যমে উভয় এজেন্ট আবিষ্কারের জন্য A2A প্রোটোকল ব্যবহার করেছে, ভিশন বিশ্লেষণ (কোড এক্সিকিউশন সহ জেমিনি 3 ফ্ল্যাশ) পরিচালনা করেছে, ভেক্টর অনুসন্ধান (AlloyDB ScaNN) সম্পাদন করেছে এবং একটি স্বায়ত্তশাসিত অর্ডার দিয়েছে—সবকিছুই রিয়েল-টাইম ওয়েবসকেট আপডেট সহ। প্রতিটি এজেন্ট A2A স্ট্যান্ডার্ডের মাধ্যমে তার ক্ষমতা প্রকাশ করে, কাস্টম 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 সংযোগ সমস্যা:

যদি আপনি 127.0.0.1 এ সার্ভারের সাথে সংযোগ দেখতে পান, তাহলে পোর্ট 5432 ব্যর্থ হয়েছে:

যদি আপনি 127.0.0.1 এ সার্ভারের সাথে সংযোগ দেখতে পান, তাহলে পোর্ট 5432 ব্যর্থ হয়েছে:

  1. Auth প্রক্সি পরীক্ষা করুন: ps aux | grep alloydb-auth-proxy
  2. পাবলিক আইপি সক্রিয় যাচাই করুন: gcloud alloydb উদাহরণগুলি INSTANCE_NAME বর্ণনা করে –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
  3. স্থানীয় উন্নয়নের জন্য (ক্লাউড শেল নয়):
  4. সমস্যা : ক্লাউড শেল স্বয়ংক্রিয়ভাবে কাজ করে, কিন্তু স্থানীয় মেশিনগুলির জন্য অনুমোদিত নেটওয়ার্ক প্রয়োজন
  5. সমাধান : sh setup.sh পুনরায় চালান এবং অনুরোধ করা হলে বিকল্প 1 (0.0.0.0/0 অনুমোদন করুন) নির্বাচন করুন।
  6. নিরাপত্তা দ্রষ্টব্য : ০.০.০.০/০ থাকা সত্ত্বেও, সংযোগের জন্য প্রয়োজন:
  7. বৈধ GCP শংসাপত্র (অ্যাপ্লিকেশন ডিফল্ট শংসাপত্র)
  8. ডাটাবেস পাসওয়ার্ড
  9. mTLS এনক্রিপশন (Auth প্রক্সি এটি পরিচালনা করে)

9. পরিষ্কার করা

চার্জ এড়াতে, স্বয়ংক্রিয় ক্লিনআপ স্ক্রিপ্ট ব্যবহার করে সমস্ত রিসোর্স ধ্বংস করুন: 

# From repo root
sh cleanup.sh

এটি নিরাপদে অপসারণ করে:

  • AlloyDB ক্লাস্টার (প্রাথমিক খরচ চালিকাশক্তি)
  • ক্লাউড রান পরিষেবা (যদি মোতায়েন করা হয়)
  • সংশ্লিষ্ট পরিষেবা অ্যাকাউন্টগুলি

স্ক্রিপ্টটি কিছু মুছে ফেলার আগে নিশ্চিতকরণের জন্য অনুরোধ করবে।

১০. তথ্যসূত্র এবং আরও পঠন

এই কোডল্যাবের সমস্ত প্রযুক্তিগত দাবি অফিসিয়াল গুগল ক্লাউড এবং গুগল এআই ডকুমেন্টেশন থেকে যাচাই করা হয়েছে।

অফিসিয়াল ডকুমেন্টেশন

জেমিনি ৩ ফ্ল্যাশ:

অ্যালয়ডিবি এআই এবং স্ক্যানএন:

মূল্য নির্ধারণের তথ্য:

যাচাইকৃত কর্মক্ষমতা দাবি

বৈশিষ্ট্য

দাবি

উৎস

ScaNN বনাম HNSW (ফিল্টার করা)

১০ গুণ দ্রুত

গুগল ক্লাউড ব্লগ (যাচাই করা হয়েছে)

ScaNN বনাম HNSW (মানক)

৪ গুণ দ্রুত

গুগল ক্লাউড ব্লগ (যাচাই করা হয়েছে)

ScaNN মেমরি ফুটপ্রিন্ট

৩-৪ গুণ ছোট

গুগল ক্লাউড ব্লগ (যাচাই করা হয়েছে)

ScaNN সূচক তৈরির সময়

৮ গুণ দ্রুত

গুগল ক্লাউড ব্লগ (যাচাই করা হয়েছে)

কোড এক্সিকিউশন টাইমআউট

সর্বোচ্চ ৩০ সেকেন্ড

গুগল ক্লাউড ডক্স (যাচাই করা হয়েছে)

কোড এক্সিকিউশন ফাইল I/O

সমর্থিত নয়

গুগল ক্লাউড ডক্স (যাচাই করা হয়েছে)

তাপমাত্রা=০ আচরণ

নির্ধারক আউটপুট

সম্প্রদায় যাচাইকৃত

অতিরিক্ত সম্পদ

এজেন্ট-টু-এজেন্ট (A2A) প্রোটোকল:

  • A2A এজেন্ট আবিষ্কার এবং যোগাযোগকে মানসম্মত করে তোলে
  • /.well-known/agent-card.json এ পরিবেশিত এজেন্ট কার্ড
  • স্বায়ত্তশাসিত এজেন্ট সহযোগিতার জন্য উদীয়মান মানদণ্ড

স্ক্যানএন গবেষণা:

  • ১২ বছরের গুগল গবেষণার উপর ভিত্তি করে
  • বিলিয়ন-স্কেলে গুগল সার্চ, ইউটিউবকে শক্তিশালী করে
  • সাধারণ উপলব্ধতার জন্য প্রকাশিত: অক্টোবর ২০২৪
  • মিলিয়ন-থেকে-বিলিয়ন ভেক্টরের জন্য উপযুক্ত প্রথম PostgreSQL ভেক্টর সূচক

১১. চ্যালেঞ্জ মোড: আপনার এজেন্টিক দক্ষতা বৃদ্ধি করুন

তুমি একটি কার্যকর স্বায়ত্তশাসিত সরবরাহ শৃঙ্খল তৈরি করেছ। আরও এগিয়ে যাওয়ার জন্য প্রস্তুত? এই চ্যালেঞ্জগুলি নতুন সমস্যাগুলির ক্ষেত্রে তোমার শেখা ধরণগুলি প্রয়োগ করে।

চ্যালেঞ্জ ১: ছবি-ভিত্তিক অনুসন্ধান (মাল্টিমোডাল এম্বেডিং)

বর্তমান প্রবাহ: ভিশন এজেন্ট আইটেম গণনা করে → টেক্সট কোয়েরি তৈরি করে → সরবরাহকারী এজেন্ট টেক্সট এম্বেড করে → AlloyDB অনুসন্ধান করে

চ্যালেঞ্জ: টেক্সট সম্পূর্ণভাবে এড়িয়ে যান—ক্রপ করা ছবিটি সরাসরি সরবরাহকারী এজেন্টের কাছে পাঠান।

ইঙ্গিত:

  1. ভিশন এজেন্টের কোড এক্সিকিউশন শেল্ফ ইমেজ থেকে পৃথক আইটেম ক্রপ করতে পারে
  2. ভার্টেক্স এআই-এর মাল্টিমোডালেম্বেডিং@০০১ মডেল সরাসরি ছবি এম্বেড করতে পারে
  3. টেক্সটের পরিবর্তে ইমেজ বাইট গ্রহণ করতে inventory.py পরিবর্তন করুন
  4. A2A দক্ষতার বিবরণ আপডেট করে "গ্রহণ করে: ছবি/জেপিইজি অথবা টেক্সট" উল্লেখ করুন।

কেন এটি গুরুত্বপূর্ণ: জটিল চেহারা (রঙের বৈচিত্র্য, ক্ষতি, প্যাকেজিং পার্থক্য) সহ যন্ত্রাংশের জন্য ভিজ্যুয়াল অনুসন্ধান আরও সঠিক।

চ্যালেঞ্জ ২: পর্যবেক্ষণযোগ্যতা—স্বচ্ছতার মাধ্যমে বিশ্বাস

বর্তমান অবস্থা: সিস্টেমটি কাজ করছে, কিন্তু আপনি "হুডের নিচে" দেখতে পাচ্ছেন না।

চ্যালেঞ্জ: ভেক্টর অনুসন্ধান কার্যকর হচ্ছে কিনা তা প্রমাণ করার জন্য AlloyDB এর কোয়েরি লগগুলি পরীক্ষা করুন।

ধাপ:

  • AlloyDB-তে ডিফল্টরূপে কোয়েরি ইনসাইট সক্রিয় থাকে। যাচাই করতে, চালান: 
gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"
  • UI এর মাধ্যমে সরবরাহকারী অনুসন্ধান চালান
  • প্রকৃত কার্যকর করা 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 কোয়েরি দেখতে পাবেন।

কেন এটি গুরুত্বপূর্ণ: পর্যবেক্ষণযোগ্যতা আস্থা তৈরি করে। যখন স্টেকহোল্ডাররা জিজ্ঞাসা করে "এই এজেন্ট কীভাবে সিদ্ধান্ত নেয়?", আপনি তাদের কেবল আউটপুট নয়, কোয়েরি প্ল্যানটিও দেখাতে পারেন।

চ্যালেঞ্জ ৩: মাল্টি-এজেন্ট রচনা

চ্যালেঞ্জ: একটি তৃতীয় এজেন্ট (লজিস্টিক এজেন্ট) যোগ করুন যা গুদামের অবস্থান এবং আইটেমের ওজনের উপর ভিত্তি করে শিপিং খরচ গণনা করবে।

স্থাপত্য:

  • ভিশন এজেন্ট আউটপুট: আইটেম সংখ্যা
  • সরবরাহকারী এজেন্টের আউটপুট: সরবরাহকারীর অবস্থান
  • লজিস্টিক এজেন্ট (নতুন) ইনপুট: গন্তব্য, ওজন → আউটপুট: শিপিং খরচ + ETA

ইঙ্গিত: A2A প্রোটোকল এটিকে তুচ্ছ করে তোলে—calculate_shipping দক্ষতার সাহায্যে একটি নতুন এজেন্ট কার্ড তৈরি করুন। কন্ট্রোল টাওয়ার এটি স্বয়ংক্রিয়ভাবে আবিষ্কার করবে।

আপনি যে প্যাটার্নটি শিখছেন: এটি এজেন্ট-ওরিয়েন্টেড আর্কিটেকচারের মূল বিষয় - ছোট, কম্পোজেবল বিশেষজ্ঞদের দ্বারা তৈরি জটিল সিস্টেম।

১২. উপসংহার

আপনি সফলভাবে জেনারেটিভ এআই থেকে এজেন্টিক এআই- তে স্থানান্তরিত হয়েছেন।

আমরা যা তৈরি করেছি:

  • দৃষ্টিভঙ্গি: আমরা "অনুমান" কে কোড এক্সিকিউশন (API কী এর মাধ্যমে জেমিনি 3 ফ্ল্যাশ) দিয়ে প্রতিস্থাপন করেছি।
  • মেমোরি: আমরা "ধীর অনুসন্ধান" এর পরিবর্তে AlloyDB ScaNN (GCP এর মাধ্যমে) ব্যবহার করেছি।
  • অ্যাকশন: আমরা "API ইন্টিগ্রেশন" কে A2A প্রোটোকল দিয়ে প্রতিস্থাপন করেছি।

হাইব্রিড স্থাপত্যের সুবিধা:

এই কোডল্যাবটি একটি হাইব্রিড পদ্ধতি প্রদর্শন করেছে:

  • ভিশন এজেন্ট: জেমিনি এপিআই (এপিআই কী) ব্যবহার করে - সহজ, বিনামূল্যের স্তর উপলব্ধ, কোনও জিসিপি বিলিং প্রয়োজন নেই।
  • সরবরাহকারী এজেন্ট: GCP (Vertex AI + AlloyDB) ব্যবহার করে - এন্টারপ্রাইজ-গ্রেড, কমপ্লায়েন্স-প্রস্তুত

এটিই স্বায়ত্তশাসিত অর্থনীতির স্থাপত্য। এই নীতিমালা আপনারই পালন করতে হবে।

পরবর্তী পদক্ষেপ