Gemini 3 Flash ve AlloyDB AI ile bağımsız bir tedarik zinciri oluşturma

1. Genel Bakış

"Okuyan Chatbotlar" dönemi sona eriyor. Temsilci tabanlı vizyon çağına giriyoruz.

Bu Codelab'de, tahmin yürütmeyen yapay zeka sistemleri oluşturma uygulaması olan Belirleyici Yapay Zeka Mühendisliği'ni uygulayacağız. Standart yapay zeka modelleri, karmaşık bir resimdeki öğeleri saymaları istendiğinde genellikle "halüsinasyon" (tahmin) yapar. Tedarik zincirinde tahmin yapmak tehlikelidir. Bir yapay zeka, 15 öğeniz olduğu halde 12 öğeniz olduğunu tahmin ederse maliyetli hatalara yol açar.

Gemini 3 Flash'taki yeni Düşün, Hareket Et, Gözlemle döngüsünü kullanarak bir Özerk Tedarik Zinciri Temsilcisi oluşturacağız. Sadece bakmaz, araştırır.

Belirleyici Mimari

"Kör" ve "hafızasız" bir sistemle başlayacağız. Duyularını tek tek manuel olarak "uyandıracaksınız":

The Eyes (Vision Agent): Kod Yürütme ile Gemini 3 Flash'i etkinleştiriyoruz. Model, bir sayıyı tahmin etmek için jetonları tahmin etmek yerine pikselleri deterministik olarak saymak için Python kodu (OpenCV) yazar.
Hafıza (Tedarikçi Aracısı): ScaNN (Ölçeklenebilir En Yakın Komşular) ile AlloyDB AI'yı etkinleştiriyoruz. Bu sayede aracı, milyonlarca seçenek arasından bir parçanın tam tedarikçisini milisaniyeler içinde hatırlayabilir.
El Sıkışma (A2A Protokolü): Standartlaştırılmış bir agent_card.json kullanarak Aracıdan Aracıya iletişimi etkinleştiririz. Bu sayede Vision Aracısı , Tedarikçi Aracı'dan bağımsız olarak stok siparişi verebilir.

Ne oluşturacaksınız?

Kamera feed'lerinde "görsel matematik" işlemleri yapan bir Vision Agent.
Yüksek hızlı vektör araması için AlloyDB ScaNN tarafından desteklenen bir Tedarikçi Temsilcisi.
Özerk döngüyü görselleştirmek için gerçek zamanlı WebSocket güncellemeleri içeren bir Control Tower ön ucu.

Neler öğreneceksiniz?

Gemini API'yi kullanarak gemini-3-flash-preview ile Agentic Vision'ı etkinleştirme
AlloyDB'de <=> (kosinüs uzaklığı) operatörünü kullanarak vektör araması uygulama
Auth Proxy'yi kullanarak Cloud Shell'i AlloyDB'ye bağlama

Şartlar

Chrome veya Firefox gibi bir tarayıcı
Faturalandırmanın etkin olduğu bir Google Cloud projesi.
Vision Agent için Gemini API anahtarı (ücretsiz katman Google AI Studio'da mevcuttur).

2. Başlamadan önce

Proje oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

Cloud Shell'i etkinleştir düğmesinin resmi

Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:

gcloud auth list

İşte bu kadar.

Artık tek tıklamayla kuruluma hazırsınız. Bir sonraki bölümde:

Cloud Shell'i otomatik olarak açma
Depoyu klonlama
Etkileşimli bir eğitimle kurulumun tamamında size yol gösterir.

3. Cloud Shell'de Tek Tıklamayla Kurulum

Kurulumu rehberli Cloud Shell eğitimine dönüştürerek basitleştirdik. Altyapı temel hazırlığı, AlloyDB kurulumu, Auth Proxy yapılandırması ve veritabanı doldurma gibi tüm işlemler otomatiktir.

Cloud Shell Eğitici'sini başlatma

⚠️ ÖNEMLİ - Tıklamadan önce: Aşağıdaki düğmeyi tıkladığınızda "Cloud Shell'de aç" sorusunu içeren bir güvenlik iletişim kutusu görürsünüz. Bu, depo klonlanmadan ÖNCE görünür.

Bu politika uyarınca:

✅ "Güvenilir depo" kutusunu işaretleyin.
✅ "Onayla"yı tıklayın.

Bu olmadan depo klonlanmaz.

Hazır mısınız? Projeyi adım adım eğitimle açmak için tıklayın:

Bundan sonraki adımlar:

Cloud Shell, önceden klonlanmış depoyla açılır.
Sağ tarafta adım adım talimatlar içeren bir eğitim paneli gösterilir.
Aşağıdaki konularda size yol göstereceğiz:

Gemini API anahtarınızı alma (ücretsiz katman mevcuttur)
GCP projenizi terminalde ayarlama
Kurulumu çalıştırma (API'leri kontrol eder, gerekirse etkinleştirir, AlloyDB'yi sağlar: ~15 dakika)
2 temel kod değişikliği yapma (görme ve hafızayı etkinleştirme)
Ajan kartı oluşturma (A2A protokolü)
Tüm hizmetleri başlatma

Eğitim etkileşimlidir. Her adım numaralandırılmıştır ve ilerlemenizi takip eder.

Alternatif: Manuel Kurulum

Manuel kontrolü tercih ediyorsanız:

Cloud Shell'i açın ve projenizin ayarlandığını doğrulayın

gcloud config get-value project

Gerekirse projenizi

gcloud config set project YOUR_PROJECT_ID

Depoyu klonlama

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

Kurulumu çalıştırma

sh setup.sh

Kurulum komut dosyasındaki ekrandaki talimatları uygulayın.

Sonraki Adımlar: Eğitim, kalan adımlarda size rehberlik eder. İşlem tamamlandıktan sonra, arka planda neler olduğunu anlamak için 4. Bölüm'e geçin.

4. Kamera Arkası: Kimlik Doğrulama Proxy'si ve Veritabanı Doldurma

Sorun: AlloyDB, özel bir VPC'de bulunur. Cloud Shell bu kapsamın dışındadır. Doğrudan bağlantı kurmak mümkün değildir.

Çözüm: AlloyDB Auth Proxy, Cloud Shell'deki 127.0.0.1:5432 adresinden AlloyDB örneğinize güvenli ve IAM kimlik doğrulamalı bir tünel oluşturur. Örneğinizde genel IP etkinse proxy bunu kullanır. Aksi takdirde, VPC'nin özel IP'si üzerinden bağlanır.

setup.sh Ne Yaptı?

AlloyDB örneğiniz (küme, bölge, proje) otomatik olarak algılandı.
Tüm kimlik bilgilerini (GEMINI_API_KEY, DB_PASS, AlloyDB ayrıntıları) içeren .env dosyasını oluşturun.
Auth Proxy'yi indirip başlattı (varsa –public-ip ile)
Veritabanına 8 örnek envanter parçası ve ScaNN dizini yerleştirildi.

.env dosyanız hazır. Gelecekteki tüm çalıştırmalarda kimlik bilgileri otomatik olarak yüklenir.

İşlemin Başarılı Olduğunu Doğrulama

Depo kök dizininde olduğunuzdan emin olun.

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

Auth Proxy'nin çalıştığını kontrol edin.

ps aux | grep alloydb-auth-proxy

Oluşturulan İçerikler

8 bölüm ve 768 boyutlu yerleştirmeler içeren envanter tablosu
Hızlı vektör araması için ScaNN dizini (idx_inventory_scann)

5. 1. adım: Bellek (Tedarikçi Temsilcisi)

Tedarikçi Temsilcisi, AlloyDB ScaNN'yi kullanarak milyonlarca parçayı hatırlar. A2A sunucusu olarak başlatırız ve ardından vektör sorgusunu düzeltiriz.

The Audit: The Amnesiac

Tedarikçi aracısına şimdi (yer tutucu SQL ile) sorgu gönderirseniz en yakın eşleşmeyi değil, bulduğu ilk satırı döndürür. Benzerlik kavramı yoktur. Bu kişi hafıza kaybı yaşıyor.

Tedarikçi Temsilcisi'ni başlatma

A2A sunucusu (main.py), protokolü inventory.py'deki iş mantığına bağlayan agent_executor.py'ye yetki verir.

pkill -f uvicorn #Kill all uvicorn processes

1. adım: Aracı dizinine gidin

cd agents/supplier-agent

2. adım: Bağımlılıkları yükleyin

pip install -r requirements.txt

3. adım: Aracı sunucusunu başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

4. adım: Temsilcinin çalıştığını doğrulayın (başlattıktan sonra 2-3 saniye bekleyin)

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

Beklenen Çıkış: Aracı yapılandırması içeren JSON (hatasız döndürülmelidir)

Gerçek Semantik Yerleştirmeler

Kurulum sırasında veritabanı, Google Gen AI SDK'nın text-embedding-005 modeli aracılığıyla oluşturulan gerçek anlamsal yerleştirmelerle doldurulmuştur. Bu, rastgele vektörler yerine doğru benzerlik eşleşmesi sağlar. Başlangıç süreci, her bölümün semantik anlamını yakalayan anlamlı 768 boyutlu vektörler oluşturmak için paralel yerleştirme oluşturma kullanılarak 13 örnek öğe için yaklaşık 10 saniye sürer.

AlloyDB Detour: Why ScaNN?

Çözüm: <=> operatörünü uygulama

Temsilci, yer tutucu sorguyla birlikte gönderilir. ScaNN vektör aramasını etkinleştirmemiz gerekir.

1. adım: Envanter dosyasını açın

cd agents/supplier-agent

2. adım: inventory.py dosyasında TODO'yu bulun

47-60. satırlar arasında find_supplier() işlevini bulun. Şunları görürsünüz:

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

3. adım: Yer tutucu SQL'i ScaNN vektör aramasıyla değiştirin

Şu iki satırı silin:

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

Şunlarla değiştirin:

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

Bu işlem ne yapar?

<=>, PostgreSQL'deki kosinüs uzaklığı operatörüdür.
ORDER BY part_embedding <=> %s::vector, en yakın eşleşmeyi (en düşük mesafe = en yakın anlamsal anlam) bulur.
%s::vector, yerleştirme dizinizi PostgreSQL'in vektör türüne dönüştürür.
LIMIT 1 yalnızca en yakın eşleşmeyi döndürür
ScaNN dizini bu sorguyu otomatik olarak hızlandırır.

4. adım: Dosyayı kaydedin (Ctrl+S veya Cmd+S)

Artık rastgele sonuçlar döndürmek yerine semantik arama kullanacak.

Doğrulama

A2A keşfini ve envanteri test edin:

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

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Beklenen: agent-card.json, temsilci kartını döndürür. Python snippet'i, başlangıç verilerinden bir parça ve tedarikçi döndürür.

6. 2. adım: Gözler (Vision Agent)

Veritabanına erişilebilirken Gemini 3 Flash'ı kullanarak gözleri uyandıralım. Vision Agent, kod yürütme yoluyla "görsel matematik" işlemini gerçekleştirir. A2A sunucusu (main.py), Gemini analizi için agent.py'yi çağıran agent_executor.py'ye yetki verir.

Denetim: Halüsinasyon

Standart bir çok formatlı modele "Bu dağınık resimde kaç kutu var?" diye sorarsanız resmi statik bir anlık görüntü olarak işler ve tahminde bulunur.

Modelin yanıtı: "Yaklaşık 12 kutu görüyorum."
Gerçek: 15 kutu var.
Sonuç: Tedarik zinciri hatası.

Çözüm: Düşünme-Eyleme Geçme-Gözlemleme Döngüsünü Uyandırma

Modelin deterministik olarak sayması için Code Execution (Kod Yürütme) ve ThinkingConfig'i (Düşünme Yapılandırması) etkinleştiriyoruz.

Open agents/vision-agent/agent.py dosyasını açın .
GenerateContentConfig bölümünü bulun.
Hem thinking_config=types.ThinkingConfig(...) bloğunun hem de tools=[types.Tool(code_execution=...)] satırının yorum işaretini kaldırın.
İstemci, ortamdan GEMINI_API_KEY'nizi kullanacak şekilde zaten yapılandırılmış.

Dosya: 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)]
)

Neden thinking_level="LOW"?

Bu özel görev (kod yürütme yoluyla öğeleri sayma) için "DÜŞÜK" seçeneği, aşağıdakiler için yeterli muhakeme bütçesi sağlar:

Python komut dosyası yapısını planlama
Hangi görüntü işleme yaklaşımının kullanılacağına karar verme
Sayının sınırlayıcı kutu sayısıyla eşleştiğini doğrulayın.

"YÜKSEK" ayarını kullanmak, deterministik görevlerde doğruluğu artırmadan 2-3 kat gecikme ve maliyet ekler. "YÜKSEK"i karmaşık çok adımlı akıl yürütme (ör. "Bu tedarik zinciri aksaklığını analiz et ve gerekçelendirerek 3 alternatif tedarikçi öner").

Maliyet-Performans Optimizasyonu, üretimde yapay zeka mühendisliği için önemli bir beceridir: Muhakeme derinliğini görev karmaşıklığıyla eşleştirin.

Vision Agent'ı başlatma

🔄 Yol Kontrolü: Hâlâ agents/supplier-agent/ dizinindeyseniz önce cd ../.. komutuyla depo köküne geri dönün.

1. adım: Vision aracısı dizinine gidin

cd agents/vision-agent

2. adım: Bağımlılıkları yükleyin

pip install -r requirements.txt

3. adım: Vision Agent sunucusunu başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

Doğrulama

A2A keşfini test etme:

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

Beklenen: Temsilci adı ve becerilerini içeren JSON. 8. adımda, Kontrol Kulesi kullanıcı arayüzü ile gerçek görüntü sayımını test edeceksiniz.

7. 3. adım: El sıkışma (A2A Agent Card)

Ajanımız sorunu görüyor (Vision) ve tedarikçiyi biliyor (Memory). A2A protokolü, dinamik keşfe olanak tanır. Ön uç, kartını okuyarak her aracıyla nasıl iletişim kuracağını öğrenir.

A2A ve geleneksel REST API'leri

Aspect	Geleneksel REST	A2A Protokolü
Uç nokta keşfi	Yapılandırmadaki sabit kodlu URL'ler	/.well-known/agent-card.json üzerinden dinamik
Özellik Açıklaması	API belgeleri (insanlar için)	Beceriler (makine tarafından okunabilir)
Entegrasyon	Hizmet başına manuel kod	Anlamsal eşleşme: "Envanter araması yapmam gerekiyor" → beceriyi keşfeder
Yeni Temsilci Eklendi	Tüm istemcilerin yapılandırmalarını güncelleme	Sıfır yapılandırma: otomatik olarak keşfedilir

Gerçek Dünyadaki Faydası: Geleneksel bir mikro hizmette üçüncü bir "Lojistik Acentesi" eklediğinizde, Kontrol Kulesi'nin kodunu URL'si ve API sözleşmesiyle güncellemeniz gerekir. A2A ile Control Tower, bunu otomatik olarak keşfeder ve doğal dil beceri açıklamaları aracılığıyla özelliklerini anlar.

Bu nedenle A2A, otonom sistemler için mimari bir model olan Plug-and-Play Agent Composition'ı etkinleştirir.

Çözüm: Temsilci kartı oluşturun

Tedarikçi Temsilcisi'nin neler yapabileceğini tanımlamamız gerekiyor.

agents/supplier-agent/agent_card_skeleton.json dosyasını agents/supplier-agent/agent_card.json olarak kopyalayın.
Yer tutucuları değiştirmek için dosyayı düzenleyin:

Önce (iskelet):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

Sonra (düzenlemeleriniz):

{
  "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?"]
  }]
}

Yeni kartın yüklenmesi için Tedarikçi Temsilcisi'ni yeniden başlatın:

1. adım: Çalışan aracıyı durdurun

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

2. adım: Aracı dizinine gidin

cd agents/supplier-agent

3. adım: Aracıyı tekrar başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

4. adım: Yeni temsilci kartını doğrulayın (başlattıktan sonra 2-3 saniye bekleyin)

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

Beklenen Çıkış: Doldurulmuş adınız, açıklamanız ve becerilerinizle ilgili JSON.

8. 4. adım: Kontrol Kulesi

Control Tower ön ucunu FastAPI + WebSockets ile çalıştırın. A2A aracılığıyla aracıları keşfeder ve gerçek zamanlı güncellemelerle tam döngüyü düzenler.

Tüm Hizmetleri Başlat

Tüm hizmetleri başlatmanın en kolay yolu:

Depo kök dizininde olduğunuzu doğrulayın

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

Ardından:

sh run.sh

Bu tek komut şunları başlatır:

AlloyDB Auth Proxy (çalışmıyorsa)
8081 bağlantı noktasındaki Vision Agent
8082 numaralı bağlantı noktasında tedarikçi aracısı
8080 numaralı bağlantı noktasında Control Tower

Tüm hizmetlerin başlatılması için yaklaşık 10 saniye bekleyin.

Sistemi Test Etme

Kontrol Kulesi'ne erişme:

Cloud Shell araç çubuğunda Web Önizlemesi düğmesini (göz simgesi 👁️) tıklayın.
"8080 numaralı bağlantı noktasında önizle"yi seçin.
Control Tower kontrol paneli yeni bir sekmede açılır.

Demoyu Çalıştırma:

Sağ üst: Bağlantı durumu (yeşil "Canlı" nokta), DEMO/AUTO modu açma/kapatma düğmesi ve ses kontrolleri
Merkez: Resim yükleme ve analiz görselleştirmesi içeren ana iş akışı tuvali
Yan paneller (analiz sırasında görünür): İş akışı zaman çizelgesi (sol), ilerleme durumu takibi ve kod görüntüleyici (sağ)

1. seçenek: Hızlı Başlangıç (Önerilir)

Ana sayfada, örnek resimlerin yer aldığı "Hızlı başlangıç" bölümünü görürsünüz.
Analizi otomatik olarak başlatmak için herhangi bir örnek resmi tıklayın.
Otonom iş akışını izleyin (~30-45 saniye).

2. seçenek: Kendi öğenizi yükleme

Bir depo/raf resmi (PNG, JPG, en fazla 10 MB) sürükleyip bırakın veya göz atmak için tıklayın.
"Initiate Autonomous Workflow" (Bağımsız İş Akışı Başlat) seçeneğini tıklayın.
4 aşamalı ardışık düzeni inceleyin

Ne olur?

Aracı Keşfi: A2A protokolü modalları, Vision Agent ve Supplier Agent kartlarını becerileri ve uç noktalarıyla birlikte gösterir.
Görsel Analizi: Gemini 3 Flash, öğeleri saymak için Python kodu (OpenCV) oluşturur ve yürütür. İlerleme çubuğunda alt adımlar gösterilir. Sınırlayıcı kutular, algılanan öğelerin üzerine yerleştirilir. Sonuç rozetinde "✓ Kod Doğrulandı" veya "~ Tahmini" gösteriliyor
Tedarikçi Eşleştirme: AlloyDB ScaNN vektör arama animasyonu. Arama sorgusu görüntüleri (ör. "industrial metal boxes"). Sonuç kartında eşleşen parça, tedarikçi ve güven puanı gösterilir.
Sipariş Verildi: Sipariş kimliği, miktar ve ayrıntıların yer aldığı makbuz kartı

İpucu: Sunularda her aşamada duraklatmak için DEMO modunu (sağ üstte) açık tutun. AUTO modunda iş akışı sürekli olarak çalışır.

Ne oldu?

Kontrol Kulesi, /.well-known/agent-card.json üzerinden her iki aracı da bulmak için A2A Protokolü'nü kullandı, görsel analizini (kod yürütme özellikli Gemini 3 Flash) düzenledi, vektör araması (AlloyDB ScaNN) gerçekleştirdi ve gerçek zamanlı WebSocket güncellemeleriyle tüm bunları yaparak bağımsız bir sipariş verdi. Her aracı, A2A standardı aracılığıyla özelliklerini kullanıma sunar. Bu sayede, özel SDK'lar olmadan tak ve çalıştır bileşenleri oluşturulabilir. Daha fazla bilgi: A2A Protokolü

Sorun giderme

Yolla İlgili Hatalar:

Komutlar çalıştırılırken "No such file or directory" (Böyle bir dosya veya dizin yok) hatası: Depo kök dizininde değilsiniz.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Hizmet Hataları:

"Adres zaten kullanılıyor": Önceki çalıştırmalardan kalan işlemler hâlâ etkin.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

Hizmetler başlatılmıyor: Bağlantı noktalarının kullanılıp kullanılmadığını kontrol edin:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

AlloyDB'ye "Connection refused" (Bağlantı reddedildi): Auth Proxy'nin çalıştığını doğrulayın:

ps aux | grep alloydb-auth-proxy

AlloyDB Bağlantı Sorunları:

127.0.0.1 adresindeki sunucuya bağlantı, 5432 bağlantı noktasında başarısız oldu hatasıyla karşılaşırsanız:

127.0.0.1 adresindeki sunucuya bağlantı, 5432 bağlantı noktasında başarısız oldu hatasıyla karşılaşırsanız:

Yetkilendirme proxy'sini kontrol edin: ps aux | grep alloydb-auth-proxy
Herkese açık IP'nin etkinleştirildiğini doğrulayın: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
Yerel geliştirme için (Cloud Shell değil):
Sorun: Cloud Shell otomatik olarak çalışır ancak yerel makineler için yetkili ağlar gerekir
Çözüm: sh setup.sh dosyasını yeniden çalıştırın ve istendiğinde 1. seçeneği (0.0.0.0/0 yetkilendir) belirleyin.
Güvenlik Notu: 0.0.0.0/0 ile bile bağlantı için şunlar gerekir:
Geçerli GCP kimlik bilgileri (Uygulama Varsayılan Kimlik Bilgileri)
Veritabanı şifresi
mTLS şifrelemesi (Auth Proxy bunu işler)

9. Temizleme

Ücretlendirilmemek için otomatik temizleme komut dosyasıyla tüm kaynakları yok edin:

# From repo root
sh cleanup.sh

Bu işlem aşağıdakileri güvenli bir şekilde kaldırır:

AlloyDB kümesi (birincil maliyet sürücüsü)
Cloud Run hizmetleri (dağıtılmışsa)
İlişkilendirilmiş hizmet hesapları

Komut dosyası, herhangi bir şeyi silmeden önce onay ister.

10. Referanslar ve Ek Okuma Materyalleri

Bu codelab'deki tüm teknik iddialar, resmi Google Cloud ve Google Yapay Zeka belgelerinden doğrulanmıştır.

Resmi Belgeler

Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Geliştirici Kılavuzu: https://ai.google.dev/gemini-api/docs/gemini-3
Model Belgeleri: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Model Kartı: https://deepmind.google/models/gemini/flash/

AlloyDB AI ve ScaNN:

ScaNN Performans Karşılaştırmaları: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
ScaNN dizinini anlama: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
AlloyDB AI Deep Dive: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
İnce Ayar Yapmayla İlgili En İyi Uygulamalar: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
AlloyDB Belgeleri: https://cloud.google.com/alloydb/docs

Fiyatlandırma bilgileri:

Gemini API Fiyatlandırması: https://ai.google.dev/gemini-api/docs/pricing
AlloyDB Fiyatlandırması: https://cloud.google.com/alloydb/pricing
Vertex AI fiyatlandırması: https://cloud.google.com/vertex-ai/pricing

Doğrulanmış Performans İddiaları

Özellik	Kullan	Kaynak
ScaNN ve HNSW (filtrelenmiş) karşılaştırması	10 kat daha hızlı	Google Cloud Blogu (doğrulanmış)
ScaNN ve HNSW (standart) karşılaştırması	4 kat daha hızlı	Google Cloud Blogu (doğrulanmış)
ScaNN bellekte kaplanan yer	3-4 kat daha küçük	Google Cloud Blogu (doğrulanmış)
ScaNN dizini oluşturma süresi	8 kat daha hızlı	Google Cloud Blogu (doğrulanmış)
Kod yürütme zaman aşımı	Maksimum 30 saniye	Google Cloud belgeleri (doğrulanmış)
Kod yürütme dosyası G/Ç	Desteklenmiyor	Google Cloud belgeleri (doğrulanmış)
Sıcaklık=0 davranışı	Belirleyici çıkış	Topluluk tarafından doğrulanmış

Ek Kaynaklar

Temsilciden Temsilciye (A2A) Protokolü:

A2A, aracı keşfini ve iletişimi standartlaştırır
/.well-known/agent-card.json konumunda sunulan müşteri temsilcisi kartları
Otonom aracıların ortak çalışması için gelişmekte olan standart

ScaNN Araştırması:

12 yıllık Google Araştırma verilerine dayalıdır.
Milyarlarca ölçekte Google Arama ve YouTube'u destekler
Genel kullanıma sunulma tarihi: Ekim 2024
Milyonlarca ila milyarlarca vektör için uygun ilk PostgreSQL vektör dizini

11. Meydan Okuma Modu: Agentic Becerilerinizi Geliştirin

Çalışan bir özerk tedarik zinciri oluşturdunuz. Daha da ileri gitmeye hazır mısınız? Bu zorluklarda öğrendiğiniz kalıpları yeni sorunlara uygularsınız.

1. Görev: Resme Dayalı Arama (Çok Formatlı Yerleştirmeler)

Mevcut akış: Vision Agent öğeleri sayar → metin sorgusu oluşturur → Supplier Agent metni yerleştirir → AlloyDB'de arama yapar

Sorun: Metni tamamen atlayın. Kırpılmış resmi doğrudan tedarikçi temsilcisine gönderin.

İpuçları:

Vision Agent'ın kod yürütme özelliği, raftaki resimden tek tek öğeleri kırpabilir.
Vertex AI'ın multimodalembedding@001 modeli, görüntüleri doğrudan yerleştirebilir.
inventory.py dosyasını metin yerine görüntü baytlarını kabul edecek şekilde değiştirin.
A2A beceri açıklamasını "Kabul eder: image/jpeg veya text" şeklinde güncelleyin.

Neden Önemli? Görsel arama, karmaşık görünümlere (renk varyasyonları, hasar, ambalaj farklılıkları) sahip parçalar için daha doğrudur.

2. zorluk: Gözlemlenebilirlik: Şeffaflık sayesinde güven

Mevcut Durum: Sistem çalışıyor ancak "kaputun altını" göremiyorsunuz.

Zorluk: Vektör aramasının yürütüldüğünü kanıtlamak için AlloyDB'nin sorgu günlüklerini inceleyin.

Adımlar:

Sorgu analizleri, AlloyDB'de varsayılan olarak etkindir. Doğrulamak için şunu çalıştırın:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

Kullanıcı arayüzü üzerinden tedarikçi araması yapma
Yürütülen gerçek SQL'i görüntüleyin:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Beklenen Çıktı: Tam olarak ORDER BY part_embedding <=> $1::vector LIMIT 1 sorgusunu yürütme süresiyle birlikte görürsünüz.

Bu Neden Önemli? Gözlemlenebilirlik güven oluşturur. Paydaşlar "Bu aracı nasıl karar veriyor?" diye sorduğunda onlara yalnızca çıkışı değil, sorgu planını da gösterebilirsiniz.

3. zorluk: Çoklu aracı kompozisyonu

Sorun: Kargo maliyetlerini depo konumuna ve öğe ağırlığına göre hesaplayan üçüncü bir aracı (Lojistik Aracı) ekleyin.

Mimari:

Vision Agent çıktıları: öğe sayısı
Tedarikçi temsilcisi çıkışları: tedarikçi konumu
Lojistik Ajanı (YENİ) girişleri: hedef, ağırlık → çıkışları: kargo maliyeti + tahmini varış zamanı

İpucu: A2A protokolü bu işlemi kolaylaştırır. calculate_shipping becerisine sahip yeni bir aracı kartı oluşturun. Kontrol Kulesi, cihazı otomatik olarak keşfeder.

Öğrendiğiniz Kalıp: Bu, Agent-Oriented Architecture'ın (Agent Odaklı Mimari) temelini oluşturur. Bu mimari, küçük ve birleştirilebilir uzmanlardan oluşturulmuş karmaşık sistemleri ifade eder.

12. Sonuç

Üretken yapay zeka'dan Agentic AI'ya başarıyla geçiş yaptınız.

Geliştirdiğimiz özellikler:

Vision: "Tahmin etme" yerine Kod Yürütme (API anahtarı aracılığıyla Gemini 3 Flash) özelliğini ekledik.
Bellek: "Yavaş arama" yerine AlloyDB ScaNN (GCP aracılığıyla) kullanmaya başladık.
İşlem: "API entegrasyonu" ifadesini A2A Protokolü ile değiştirdik.

Karma mimarinin avantajları:

Bu codelab'de hibrit bir yaklaşım gösterildi:

Vision Agent: Gemini API'yi (API anahtarı) kullanır. Basit ve ücretsiz katman mevcuttur. GCP faturalandırması gerekmez.
Tedarikçi Temsilcisi: GCP'yi (Vertex AI + AlloyDB) kullanır. Kurumsal düzeyde ve uyumluluğa hazırdır.

Bu, otonom ekonominin mimarisidir. Kod size aittir.

Sonraki Adımlar

Gemini API anahtarınızı alın (ücretsiz katman mevcuttur)
Gemini API belgelerini keşfedin
AlloyDB AI belgelerine göz atın.
Gemini Code Execution'ı keşfedin