Tworzenie autonomicznego łańcucha dostaw za pomocą Gemini 3 Flash i AlloyDB AI

1. Przegląd

Era „chatbotów, które czytają” dobiega końca. Wkraczamy w erę wizji opartej na agentach.

W tym ćwiczeniu z programowania wdrożymy deterministyczne inżynierowanie AI, czyli praktykę tworzenia systemów AI, które nie zgadują. Standardowe modele AI często „halucynują” (zgadują), gdy są proszone o policzenie elementów na złożonym obrazie. W łańcuchu dostaw zgadywanie jest niebezpieczne. Jeśli AI zgadnie, że masz 12 produktów, a w rzeczywistości masz ich 15, spowoduje to kosztowne błędy.

Stworzymy autonomicznego agenta łańcucha dostaw, który będzie korzystać z nowej pętli myślenie, działanie, obserwacja w Gemini 3 Flash. Nie tylko wygląda, ale też bada.

Architektura deterministyczna

Zaczniemy od systemu „ślepego” i „z amnezją”. Będziesz ręcznie „budzić” jego zmysły jeden po drugim:

17191a91a9c54146.png

  1. The Eyes (Vision Agent): udostępniamy Gemini 3 Flash z wykonywaniem kodu. Zamiast przewidywać tokeny, aby odgadnąć liczbę, model pisze kod w języku Python (OpenCV), aby deterministycznie zliczać piksele.
  2. Pamięć (agent dostawcy): włączamy AlloyDB AI z ScaNN (Scalable Nearest Neighbors). Dzięki temu agent może w milisekundach przywołać dokładnego dostawcę części spośród milionów opcji.
  3. Uzgadnianie połączenia (protokół A2A): umożliwiamy komunikację między agentami za pomocą standardowego pliku agent_card.json , dzięki czemu agent Vision może samodzielnie zamawiać towar od agenta dostawcy.

Co utworzysz

  • Agent wizyjny, który wykonuje „obliczenia wizualne” na podstawie obrazu z kamery.
  • Agent dostawcy oparty na AlloyDB ScaNN do szybkiego wyszukiwania wektorowego.
  • Interfejs Control Tower z aktualizacjami WebSocket w czasie rzeczywistym, który umożliwia wizualizację pętli autonomicznej.

Czego się nauczysz

  • Jak włączyć Agentic Vision w przypadku modelu gemini-3-flash-preview za pomocą Gemini API.
  • Jak wdrożyć wyszukiwanie wektorowe za pomocą operatora <=> (odległość cosinusowa) w AlloyDB.
  • Jak połączyć Cloud Shell z AlloyDB za pomocą serwera proxy uwierzytelniania.

Wymagania

  • przeglądarka, np. Chrome lub Firefox;
  • Projekt Google Cloud z włączonymi płatnościami.
  • Klucz interfejsu Gemini API (bezpłatny poziom dostępny w Google AI Studio) dla agenta Vision.

2. Zanim zaczniesz

Utwórz projekt

  1. W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
  2. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie włączone są płatności.
  1. Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.

Obraz przycisku aktywowania Cloud Shell

  1. Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu, używając tego polecenia:
gcloud auth list

To wszystko.

Możesz teraz przeprowadzić konfigurację jednym kliknięciem. W następnej sekcji:

  • Automatyczne otwieranie Cloud Shell
  • Klonowanie repozytorium
  • przeprowadzić Cię przez cały proces konfiguracji w interaktywnym samouczku,

3. Konfiguracja jednym kliknięciem w Cloud Shell

Uprościliśmy konfigurację, tworząc samouczek w Cloud Shell. Wszystko jest zautomatyzowane: udostępnianie infrastruktury, konfigurowanie AlloyDB, konfigurowanie serwera proxy uwierzytelniania i wypełnianie bazy danych.

Samouczek dotyczący uruchamiania Cloud Shell

⚠️ WAŻNE – zanim klikniesz: gdy klikniesz przycisk poniżej, pojawi się okno dialogowe z prośbą o potwierdzenie „Otwórz w Cloud Shell”. Pojawia się PRZED sklonowaniem repozytorium.

Musisz:

  1. ✅ Zaznacz pole „Zaufaj repozytorium”.
  2. ✅ Kliknij Potwierdź.

Bez tego repozytorium nie zostanie sklonowane.

Chcesz przystąpić do działania? Kliknij, aby otworzyć projekt z samouczkiem krok po kroku:

Co dalej:

  1. Otworzy się Cloud Shell z wstępnie sklonowanym repozytorium.
  2. Po prawej stronie pojawi się panel z samouczkiem zawierający instrukcje krok po kroku.
  3. Przeprowadzimy Cię przez:
  • Uzyskiwanie klucza interfejsu Gemini API (dostępny bezpłatny poziom)
  • Ustawianie projektu GCP w terminalu
  • Uruchamianie konfiguracji (sprawdzanie interfejsów API, włączanie ich w razie potrzeby, udostępnianie AlloyDB: ok. 15 minut)
  • Wprowadzanie 2 kluczowych zmian w kodzie (włączenie funkcji widzenia i pamięci)
  • Tworzenie karty agenta (protokół A2A)
  • Uruchamianie wszystkich usług

Samouczek jest interaktywny – każdy krok jest ponumerowany i śledzi Twoje postępy.

Alternatywa: konfiguracja ręczna

Jeśli wolisz ręczną kontrolę:

  1. Otwieranie Cloud Shell i sprawdzanie, czy projekt jest ustawiony
gcloud config get-value project
  1. W razie potrzeby skonfiguruj projekt.
gcloud config set project YOUR_PROJECT_ID
  1. Klonowanie repozytorium
git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb
  1. Uruchom konfigurację
sh setup.sh

Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie przez skrypt konfiguracji.

Co dalej: samouczek przeprowadzi Cię przez pozostałe kroki. Po zakończeniu przejdź do sekcji 4, aby dowiedzieć się, co się stało.

4. Za kulisami: serwer proxy uwierzytelniania i wypełnianie bazy danych

Problem: AlloyDB znajduje się w prywatnej sieci VPC. Cloud Shell znajduje się poza nim. Połączenie bezpośrednie jest niemożliwe.

Rozwiązanie: serwer proxy uwierzytelniania AlloyDB tworzy bezpieczny tunel uwierzytelniony przez IAM z 127.0.0.1:5432 w Cloud Shell do instancji AlloyDB. Jeśli na instancji jest włączony publiczny adres IP, proxy go używa. W przeciwnym razie łączy się przez prywatny adres IP sieci VPC.

Co zrobił skrypt setup.sh

  1. Automatyczne wykrywanie instancji AlloyDB (klastra, regionu, projektu)
  2. Utworzono plik .env ze wszystkimi danymi logowania (GEMINI_API_KEY, DB_PASS, szczegóły AlloyDB).
  3. Pobrano i uruchomiono serwer proxy uwierzytelniania (w razie potrzeby z parametrem –public-ip).
  4. Wypełnienie bazy danych 8 przykładowymi częściami asortymentu + indeks ScaNN

Plik .env jest gotowy. Wszystkie przyszłe uruchomienia będą automatycznie wczytywać dane logowania.

Sprawdź, czy wszystko działa

Upewnij się, że nadal jesteś w katalogu głównym repozytorium.

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

Sprawdzanie, czy serwer proxy uwierzytelniania jest uruchomiony

ps aux | grep alloydb-auth-proxy

Co zostało utworzone

  • tabela zasobów reklamowych z 8 częściami i 768-wymiarowymi osadzaniami,
  • Indeks ScaNN (idx_inventory_scann) do szybkiego wyszukiwania wektorowego

5. Krok 1. Pamięć (agent dostawcy)

Agent dostawcy zapamiętuje miliony części za pomocą AlloyDB ScaNN. Zaczynamy od serwera A2A, a potem poprawiamy zapytanie wektorowe.

The Audit: The Amnesiac

Jeśli teraz wyślesz zapytanie do agenta dostawcy (z SQL-em zastępczym), zwróci on pierwszy znaleziony wiersz, a nie najbliższe dopasowanie. Nie ma pojęcia podobieństwa. To osoba z amnezją.

Uruchomienie agenta dostawcy

Serwer A2A (main.py) przekazuje zadania do agent_executor.py, który łączy protokół z logiką biznesową w inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Krok 1. Otwórz katalog agentów

cd agents/supplier-agent

Krok 2. Zainstaluj zależności

pip install -r requirements.txt

Krok 3. Uruchom serwer agenta

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Krok 4. Sprawdź, czy agent działa (odczekaj 2–3 sekundy po uruchomieniu)

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

Oczekiwane dane wyjściowe: JSON z konfiguracją agenta (powinien być zwracany bez błędów)

Rzeczywiste semantyczne wektory dystrybucyjne

Podczas konfiguracji baza danych została wypełniona prawdziwymi osadzaniami semantycznymi wygenerowanymi za pomocą modelu text-embedding-005 z pakietu Google Gen AI SDK. Dzięki temu dopasowanie podobieństwa będzie dokładne, a nie oparte na losowych wektorach. Proces początkowy trwa około 10 sekund w przypadku 13 przykładowych produktów. Wykorzystuje on równoległe generowanie osadzania, aby tworzyć przydatne wektory 768-wymiarowe, które odzwierciedlają znaczenie semantyczne każdej części.

AlloyDB Detour: dlaczego ScaNN?

Rozwiązanie: wdrożenie operatora <=>

Agent jest dostarczany z zapytaniem zastępczym. Musimy włączyć wyszukiwanie wektorowe ScaNN.

Krok 1. Otwórz plik asortymentu

cd agents/supplier-agent

Krok 2. Znajdź w pliku inventory.py komentarz TODO

Znajdź funkcję find_supplier() w wierszach 47–60. Zobaczysz:

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

Krok 3. Zastąp zastępczy kod SQL wyszukiwaniem wektorowym ScaNN

Usuń te 2 wiersze:

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

Zastąp je tymi:

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

Co to robi:

  • <=> to operator odległości kosinusowej w PostgreSQL.
  • ORDER BY part_embedding <=> %s::vector znajduje najbliższe dopasowanie (najmniejsza odległość = najbliższe znaczenie semantyczne).
  • %s::vector przekształca tablicę wektorów dystrybucyjnych na typ wektora PostgreSQL.
  • LIMIT 1 zwraca tylko najbliższe dopasowanie.
  • Indeks ScaNN automatycznie przyspiesza to zapytanie.

Krok 4. Zapisz plik (Ctrl+S lub Cmd+S)

Agent będzie teraz używać wyszukiwania semantycznego zamiast zwracać losowe wyniki.

Weryfikacja

Sprawdź wykrywanie A2A i zasoby reklamowe:

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')
"

Oczekiwano: plik agent-card.json zwraca kartę agenta. Fragment kodu w Pythonie zwraca część i dostawcę z danych początkowych.

6. Krok 2. Oczy (Vision Agent)

Baza danych jest dostępna, więc użyjmy Gemini 3 Flash, aby otworzyć oczy. Agent Vision wykonuje „matematykę wizualną” za pomocą wykonywania kodu. Serwer A2A (main.py) przekazuje zadania do pliku agent_executor.py, który wywołuje plik agent.py w celu przeprowadzenia analizy za pomocą Gemini.

Kontrola: halucynacja

Jeśli zapytasz standardowy model multimodalny: „Ile pudełek jest na tym nieuporządkowanym obrazie?”, przetworzy on obraz jako statyczną migawkę i spróbuje zgadnąć.

  • Model mówi: „Widzę około 12 pudełek”.
  • Rzeczywistość: jest 15 pudełek.
  • Wynik: awaria łańcucha dostaw.

Rozwiązanie: pobudzenie pętli myślenie–działanie–obserwacja

Włączamy wykonywanie kodu i konfigurację myślenia, aby model pisał w Pythonie (OpenCV) i dokonywał deterministycznego zliczania.

  1. Otwórz plik agents/vision-agent/agent.py .
  2. Znajdź sekcję GenerateContentConfig.
  3. Odkomentuj blok thinking_config=types.ThinkingConfig(...) i tools=[types.Tool(code_execution=...)] .
  4. Klient jest już skonfigurowany tak, aby używać klucza GEMINI_API_KEY ze środowiska.

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

Dlaczego thinking_level="LOW"?

W przypadku tego konkretnego zadania (zliczania elementów za pomocą wykonania kodu) poziom „NISKI” zapewnia wystarczający budżet na uzasadnienie, aby:

  • Zaplanuj strukturę skryptu w Pythonie
  • Wybieranie metody przetwarzania obrazów
  • Sprawdź, czy liczba jest zgodna z liczbą ramek ograniczających.

Użycie ustawienia „HIGH” zwiększy opóźnienie i koszt 2–3 razy bez poprawy dokładności w przypadku zadań deterministycznych. Wartość „HIGH” zarezerwuj dla złożonego wnioskowania wieloetapowego (np. „Przeanalizuj to zakłócenie w łańcuchu dostaw i zaproponuj 3 alternatywnych dostawców wraz z uzasadnieniem”.

Optymalizacja kosztów i wydajności to kluczowa umiejętność w inżynierii AI w środowisku produkcyjnym: dopasowywanie głębokości rozumowania do złożoności zadania.

Uruchamianie agenta Vision

🔄 Sprawdź ścieżkę: jeśli nadal jesteś w folderze agents/supplier-agent/, najpierw wróć do głównego katalogu repozytorium za pomocą polecenia cd ../..

Krok 1. Otwórz katalog agentów wizyjnych

cd agents/vision-agent

Krok 2. Zainstaluj zależności

pip install -r requirements.txt

Krok 3. Uruchom serwer agenta wizyjnego

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Weryfikacja

Testowanie wykrywania A2A:

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

Oczekiwano: plik JSON z nazwą agenta i jego umiejętnościami. W kroku 8 przetestujesz rzeczywiste zliczanie za pomocą interfejsu Control Tower.

dc9bc53007336472.png

7. Krok 3. Uścisk dłoni (karta agenta A2A)

Agent widzi problem (Vision) i zna dostawcę (Memory). Protokół A2A umożliwia dynamiczne wykrywanie – interfejs uczy się komunikować z każdym agentem, odczytując jego kartę.

A2A a tradycyjne interfejsy API REST

Aspekt

Tradycyjny interfejs REST

Protokół A2A

Wykrywanie punktów końcowych

Adresy URL zakodowane na stałe w konfiguracji

Dynamiczne za pomocą pliku /.well-known/agent-card.json

Opis funkcji

Dokumentacja interfejsu API (dla ludzi)

Umiejętności (czytelne dla komputera)

Integracja

Ręczny kod na usługę

Dopasowanie semantyczne: „Potrzebuję wyszukiwania zasobów reklamowych” → wykrywa umiejętność

Dodano nowego agenta

Aktualizowanie konfiguracji wszystkich klientów

Brak konieczności konfigurowania – automatyczne wykrywanie

Praktyczne zastosowanie: w tradycyjnej mikroserwisowej architekturze, jeśli dodasz trzeciego „agenta logistycznego”, musisz zaktualizować kod wieży kontrolnej, podając jego adres URL i kontrakt API. Dzięki A2A wieża kontrolna automatycznie wykrywa usługę i rozumie jej możliwości na podstawie opisów umiejętności w języku naturalnym.

Dlatego A2A umożliwia komponowanie agentów typu plug-and-play, czyli wzorzec architektury systemów autonomicznych.

Rozwiązanie: utwórz kartę agenta

Musimy określić, co może robić agent dostawcy.

  1. Skopiuj plik agents/supplier-agent/agent_card_skeleton.json do folderu agents/supplier-agent/agent_card.json.
  2. Edytuj plik, aby zastąpić symbole zastępcze:

Przed (szkielet):

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

Po (Twoje zmiany):

{
  "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. Uruchom ponownie agenta dostawcy, aby załadować nową kartę:

Krok 1. Zatrzymaj działającego agenta

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

Krok 2. Przejdź do katalogu agentów

cd agents/supplier-agent

Krok 3. Ponownie uruchom agenta

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Krok 4. Sprawdź nową kartę agenta (odczekaj 2–3 sekundy po rozpoczęciu)

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

Oczekiwane dane wyjściowe: plik JSON z wypełnionymi informacjami o Twoim imieniu i nazwisku, opisie i umiejętnościach.

dd352ca2e7e6109a.png

8. Krok 4. Centrum sterowania

Uruchom interfejs Control Tower za pomocą FastAPI i WebSockets. Wykrywa agentów za pomocą A2A i koordynuje cały proces, przekazując aktualizacje w czasie rzeczywistym.

Uruchom wszystkie usługi

Najłatwiejszy sposób uruchomienia wszystkich usług:

Sprawdź, czy jesteś w katalogu głównym repozytorium.

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

Następnie:

sh run.sh

To pojedyncze polecenie rozpoczyna:

  • Serwer proxy uwierzytelniania AlloyDB (jeśli nie działa)
  • Agent Vision na porcie 8081
  • Agent dostawcy na porcie 8082
  • Control Tower na porcie 8080

Poczekaj około 10 sekund, aż wszystkie usługi zostaną zainicjowane.

Testowanie systemu

Otwórz Control Tower:

  1. Na pasku narzędzi Cloud Shell kliknij przycisk Podgląd w przeglądarce (ikona oka 👁️).
  2. Wybierz „Podejrzyj na porcie 8080”.
  3. Panel Control Tower otworzy się w nowej karcie.

Uruchomienie wersji demonstracyjnej:

  1. Prawy górny róg: stan połączenia (zielona kropka „Na żywo”), przełącznik trybu DEMO/AUTO i elementy sterujące dźwiękiem.
  2. Środek: główny obszar roboczy przepływu pracy z przesyłaniem obrazów i wizualizacją analizy.
  3. Panele boczne (wyświetlane podczas analizy): oś czasu przepływu pracy (po lewej), śledzenie postępów i przeglądarka kodu (po prawej).

Opcja 1. Szybki start (zalecane)

  1. Na stronie głównej zobaczysz sekcję „Szybki start” z przykładowymi obrazami.
  2. Kliknij dowolny przykładowy obraz, aby automatycznie rozpocząć analizę.
  3. Obserwuj autonomiczny przepływ pracy (ok. 30–45 sekund)

Opcja 2. Prześlij własne

  1. Przeciągnij i upuść obraz magazynu lub półki (PNG, JPG, maks. 10 MB) albo kliknij, aby go wyszukać.
  2. Kliknij „Initiate Autonomous Workflow” (Uruchom autonomiczny proces).
  3. Obserwowanie 4-etapowego potoku

Co się stanie:

  1. Odkrywanie agentów: w modalach protokołu A2A wyświetlają się karty agenta Vision i agenta dostawcy z ich umiejętnościami i punktami końcowymi.
  2. Analiza obrazu: Gemini 3 Flash generuje i wykonuje kod w Pythonie (OpenCV), aby zliczać elementy. Pasek postępu pokazuje podetapy. Ramki ograniczające nakładane na wykryte elementy. Plakietka wyniku wyświetla „✓ Zweryfikowano kodem” lub „~ Szacunkowo”.
  3. Dopasowanie dostawcy: animacja wyszukiwania wektorowego ScaNN w AlloyDB. Wyświetlenia zapytań (np. „industrial metal boxes”). Karta wyników zawiera dopasowaną część, dostawcę i wskaźnik ufności.
  4. Złożono zamówienie: karta z potwierdzeniem zawierająca identyfikator zamówienia, ilość i szczegóły

Wskazówka: aby wstrzymywać prezentację na każdym etapie, włącz tryb DEMO (w prawym górnym rogu). W trybie AUTOMATYCZNYM przepływ pracy jest uruchamiany w sposób ciągły.

1a031c4fd407a183.png

Co się właśnie stało

Wieża kontrolna użyła protokołu A2A do wykrycia obu agentów za pomocą pliku /.well-known/agent-card.json, przeprowadziła analizę obrazu (Gemini 3 Flash z wykonywaniem kodu), wyszukała wektory (AlloyDB ScaNN) i złożyła autonomiczne zamówienie – wszystko to z aktualizacjami w czasie rzeczywistym za pomocą protokołu WebSocket. Każdy agent udostępnia swoje możliwości za pomocą standardu A2A, co umożliwia kompozycję typu plug-and-play bez niestandardowych pakietów SDK. Więcej informacji: protokół A2A

Rozwiązywanie problemów

Błędy związane ze ścieżką:

  • „No such file or directory” (Brak takiego pliku lub katalogu) podczas wykonywania poleceń: nie znajdujesz się w katalogu głównym repozytorium.
# Check where you are
pwd

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

Błędy usługi:

  • „Adres jest już używany”: procesy z poprzednich uruchomień są nadal aktywne.
# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents
  • Usługi nie uruchamiają się: sprawdź, czy porty są zajęte:
# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent
  • „Odmowa połączenia” z AlloyDB: sprawdź, czy działa serwer proxy uwierzytelniania:
ps aux | grep alloydb-auth-proxy

Problemy z połączeniem z AlloyDB:

Jeśli zobaczysz komunikat „Nie udało się połączyć z serwerem pod adresem 127.0.0.1, port 5432”:

Jeśli widzisz komunikat o nieudanym połączeniu z serwerem pod adresem 127.0.0.1, port 5432:

  1. Sprawdź serwer proxy uwierzytelniania: ps aux | grep alloydb-auth-proxy
  2. Sprawdź, czy włączono publiczny adres IP: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
  3. W przypadku programowania lokalnego (nie w Cloud Shell):
  4. Problem: Cloud Shell działa automatycznie, ale komputery lokalne wymagają autoryzowanych sieci
  5. Rozwiązanie: ponownie uruchom skrypt sh setup.sh i gdy pojawi się odpowiedni komunikat, wybierz opcję 1 (autoryzuj 0.0.0.0/0).
  6. Uwaga dotycząca bezpieczeństwa: nawet w przypadku zakresu 0.0.0.0/0 połączenie wymaga:
  7. prawidłowe dane logowania do GCP (domyślne dane logowania aplikacji);
  8. Hasło do bazy danych
  9. Szyfrowanie mTLS (obsługiwane przez serwer proxy uwierzytelniania)

9. Czyszczenie

Aby uniknąć obciążenia konta opłatami, usuń wszystkie zasoby za pomocą automatycznego skryptu czyszczącego:

# From repo root
sh cleanup.sh

Bezpiecznie usuwa:

  • klaster AlloyDB (główny czynnik kosztowy);
  • usługi Cloud Run (jeśli zostały wdrożone);
  • Powiązane konta usługi

Przed usunięciem czegokolwiek skrypt poprosi o potwierdzenie.

10. Źródła i dodatkowe informacje

Wszystkie twierdzenia techniczne w tym laboratorium są weryfikowane na podstawie oficjalnej dokumentacji Google Cloud i Google AI.

Oficjalna dokumentacja

Gemini 3 Flash:

AlloyDB AI i ScaNN:

Informacje o cenach:

Zweryfikowane deklaracje dotyczące skuteczności

Funkcja

Wykorzystaj

Źródło

ScaNN a HNSW (filtrowane)

10 razy szybciej

Blog Google Cloud (zweryfikowany)

ScaNN a HNSW (standard)

4 razy szybciej

Blog Google Cloud (zweryfikowany)

Wykorzystanie pamięci przez ScaNN

3–4 razy mniejszy

Blog Google Cloud (zweryfikowany)

Czas tworzenia indeksu ScaNN

8 razy szybciej

Blog Google Cloud (zweryfikowany)

Limit czasu wykonania kodu

Maksymalnie 30 sekund

Dokumenty Google Cloud (zweryfikowane)

Plikowe wejście/wyjście podczas wykonywania kodu

Nieobsługiwane

Dokumenty Google Cloud (zweryfikowane)

Działanie przy temperaturze 0

Deterministyczne dane wyjściowe

Zweryfikowane przez społeczność

Dodatkowe materiały

Protokół Agent-to-Agent (A2A):

  • A2A standaryzuje wykrywanie agentów i komunikację z nimi
  • Karty agentów wyświetlane w /.well-known/agent-card.json
  • Nowy standard współpracy autonomicznych agentów

ScaNN Research:

  • Na podstawie 12 lat badań w Google
  • Umożliwia wyszukiwanie w Google i YouTube na ogromną skalę
  • Ogólnodostępna od: października 2024 r.
  • Pierwszy indeks wektorowy PostgreSQL odpowiedni dla milionów i miliardów wektorów

11. Tryb wyzwania: rozwijaj umiejętności agenta

Udało Ci się stworzyć działający autonomiczny łańcuch dostaw. Chcesz iść dalej? Te wyzwania pozwalają zastosować poznane wzorce do nowych problemów.

Zadanie 1. Wyszukiwanie na podstawie obrazu (multimodalne wektory dystrybucyjne)

Obecny proces: agent Vision zlicza produkty → generuje zapytanie tekstowe → agent dostawcy osadza tekst → wyszukuje w AlloyDB

Wyzwanie: całkowite pominięcie tekstu – wysłanie przyciętego obrazu bezpośrednio do agenta dostawcy.

Wskazówki:

  1. Wykonywanie kodu przez agenta Vision może przycinać poszczególne produkty z obrazu półki.
  2. Model multimodalembedding@001 w Vertex AI może bezpośrednio osadzać obrazy.
  3. Zmiana pliku inventory.py, aby akceptował bajty obrazu zamiast tekstu
  4. Zaktualizuj opis umiejętności A2A, aby wskazać „Akceptuje: obraz/jpeg lub tekst”.

Dlaczego to jest ważne: wyszukiwanie wizualne jest dokładniejsze w przypadku części o złożonym wyglądzie (różnice w kolorze, uszkodzenia, różnice w opakowaniu).

Problem 2. Obserwacja – zaufanie dzięki przejrzystości

Obecny stan: system działa, ale nie widać „pod maską”.

Wyzwanie: sprawdź dzienniki zapytań AlloyDB, aby potwierdzić, że wyszukiwanie wektorowe jest wykonywane.

Instrukcje:

  • Statystyki zapytań są domyślnie włączone w AlloyDB. Aby to sprawdzić, uruchom:
gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"
  • Przeprowadzanie wyszukiwania dostawców w interfejsie
  • Wyświetl rzeczywiste wykonane zapytanie SQL:
gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Oczekiwane dane wyjściowe: zobaczysz dokładne zapytanie ORDER BY part_embedding <=> $1::vector LIMIT 1 wraz z czasem wykonania.

Dlaczego to jest ważne: obserwowalność buduje zaufanie. Gdy interesariusze zapytają: „Jak ten agent podejmuje decyzje?”, możesz pokazać im plan zapytania, a nie tylko dane wyjściowe.

Wyzwanie 3. Kompozycja wielu agentów

Wyzwanie: dodaj trzeciego agenta (Logistics Agent), który oblicza koszty dostawy na podstawie lokalizacji magazynu i wagi produktu.

Architektura:

  • Dane wyjściowe Vision Agent: liczba elementów
  • Dane wyjściowe agenta dostawcy: lokalizacja dostawcy
  • Dane wejściowe agenta logistycznego (NOWOŚĆ): miejsce docelowe, waga → dane wyjściowe: koszt dostawy + szacowany czas dostawy

Wskazówka: protokół A2A ułatwia to zadanie – utwórz nową kartę agenta z umiejętnością calculate_shipping. Wieża kontrolna wykryje go automatycznie.

Wzorzec, którego się uczysz: to podstawa architektury zorientowanej na agentów – złożonych systemów zbudowanych z małych, dających się łączyć specjalistów.

12. Podsumowanie

Udało Ci się przejść z generatywnej AI na AI z agentami.

Co stworzyliśmy:

  • Vision: zastąpiliśmy „zgadywanie” wykonywaniem kodu (Gemini 3 Flash za pomocą klucza API).
  • Pamięć: zastąpiliśmy „wolne wyszukiwanie” AlloyDB ScaNN (za pomocą GCP).
  • Działanie: zastąpiliśmy „Integrację interfejsu API” protokołem A2A.

Zalety architektury hybrydowej:

W tym laboratorium pokazaliśmy podejście hybrydowe:

  • Agent Vision: korzysta z Gemini API (klucz interfejsu API) – dostępny jest prosty, bezpłatny poziom, nie wymaga rozliczeń GCP.
  • Agent dostawcy: korzysta z GCP (Vertex AI + AlloyDB) – rozwiązanie klasy korporacyjnej, zgodne z przepisami.

To jest architektura autonomicznej gospodarki. Kod jest Twój.

Następne kroki