1. Przegląd
W tym ćwiczeniu zbudujesz aplikację Neighbor Loop, która umożliwia zrównoważone udostępnianie nadwyżek i traktuje inteligencję jako podstawowy element warstwy danych.
Dzięki integracji Gemini 3.0 Flash i AlloyDB AI wyjdziesz poza podstawowe przechowywanie danych i wkroczysz w świat inteligencji w bazie danych. Dowiesz się, jak przeprowadzać analizę elementów multimodalnych i odkrywanie semantyczne bezpośrednio w SQL, co eliminuje „podatek AI” w postaci opóźnień i nadmiaru architektury.
Co utworzysz
Wysokowydajna aplikacja internetowa „przesuń, aby dopasować” do udostępniania nadwyżek w społeczności.
Czego się nauczysz
- Provisioning jednym kliknięciem: jak skonfigurować klaster i instancję AlloyDB zaprojektowane pod kątem zbiorów zadań AI.
- Wektory dystrybucyjne w bazie danych: generowanie wektorów text-embedding-005 bezpośrednio w instrukcjach INSERT.
- Rozumowanie multimodalne: używanie Gemini 3.0 Flash do „widzenia” elementów i automatycznego generowania dowcipnych opisów w stylu randkowym.
- Odkrywanie semantyczne: przeprowadzanie w zapytaniach SQL opartych na logice „sprawdzania nastroju” za pomocą funkcji ai.if() w celu filtrowania wyników na podstawie kontekstu, a nie tylko obliczeń.
Architektura
Neighbor Loop omija tradycyjne wąskie gardła warstwy aplikacji. Zamiast wyodrębniać dane do przetworzenia, używamy:
- AlloyDB AI: do generowania i przechowywania wektorów w czasie rzeczywistym.
- Google Cloud Storage: do przechowywania obrazów.
- Gemini 3.0 Flash: do przeprowadzania rozumowania w czasie poniżej sekundy na danych obrazów i tekstu bezpośrednio za pomocą SQL.
- Cloud Run: do hostowania lekkiego backendu Flask w jednym pliku.
Wymagania
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie włączone są płatności.
- 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.
- Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na Twój identyfikator projektu, używając tego polecenia:
gcloud auth list
- Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
- Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:
gcloud config set project <YOUR_PROJECT_ID>
- Włącz wymagane interfejsy API: kliknij link i włącz interfejsy API.
Możesz też użyć polecenia gcloud. Informacje o poleceniach gcloud i ich użyciu znajdziesz w dokumentacji.
Pułapki i rozwiązywanie problemów
Syndrom „projektu widma” | Uruchomiono polecenie |
Bariera rozliczeniowa | Projekt został włączony, ale zapomniano o koncie rozliczeniowym. AlloyDB to wydajny mechanizm, który nie uruchomi się, jeśli „zbiornik paliwa” (płatności) jest pusty. |
Opóźnienie propagacji interfejsu API | Kliknięto „Włącz interfejsy API”, ale w wierszu poleceń nadal widnieje symbol |
Limit Quags | Jeśli korzystasz z nowego konta próbnego, możesz osiągnąć regionalny limit instancji AlloyDB. Jeśli |
„Ukryty” agent usługi | Czasami agentowi usługi AlloyDB nie jest automatycznie przyznawana rola |
3. Konfiguracja bazy danych
W tym module użyjemy AlloyDB jako bazy danych do przechowywania danych testowych. Używa klastrów do przechowywania wszystkich zasobów, takich jak bazy danych i logi. Każdy klaster ma instancję podstawową, która zapewnia punkt dostępu do danych. Tabele będą zawierać rzeczywiste dane.
Utwórzmy klaster, instancję i tabelę AlloyDB, do których zostanie załadowany testowy zbiór danych.
- Kliknij przycisk lub skopiuj poniższy link do przeglądarki, w której zalogowany jest użytkownik konsoli Google Cloud.
- Po wykonaniu tego kroku repozytorium zostanie sklonowane do lokalnego edytora Cloud Shell i będziesz mieć możliwość uruchomienia poniższego polecenia z folderu projektu (ważne jest, aby upewnić się, że jesteś w katalogu projektu):
sh run.sh
- Teraz użyj interfejsu (kliknij link w terminalu lub link „Podgląd w internecie” w terminalu).
- Aby rozpocząć, wpisz szczegóły identyfikatora projektu, klastra i nazw instancji.
- Idź po kawę, podczas gdy dzienniki będą się przewijać. Tutaj możesz przeczytać, jak to działa w tle.
Pułapki i rozwiązywanie problemów
Problem z „cierpliwością” | Klastry baz danych to rozbudowana infrastruktura. Jeśli odświeżysz stronę lub zakończysz sesję Cloud Shell, ponieważ „utknęła”, możesz skończyć z „duchem” instancji, która jest częściowo udostępniona i niemożliwa do usunięcia bez ręcznej interwencji. |
Niezgodny region | Jeśli interfejsy API zostały włączone w regionie |
Zombie Clusters | Jeśli nazwa klastra była już wcześniej używana i nie została usunięta, skrypt może wyświetlić komunikat, że nazwa klastra już istnieje. Nazwy klastrów muszą być unikalne w projekcie. |
Limit czasu Cloud Shell | Jeśli przerwa na kawę trwa 30 minut, Cloud Shell może przejść w stan uśpienia i odłączyć proces |
4. Obsługa administracyjna schematu
Gdy klaster i instancja AlloyDB będą działać, przejdź do edytora SQL w AlloyDB Studio, aby włączyć rozszerzenia AI i udostępnić schemat.
Może być konieczne poczekanie na zakończenie tworzenia instancji. Gdy to zrobisz, zaloguj się w AlloyDB przy użyciu danych logowania utworzonych podczas tworzenia klastra. Do uwierzytelniania w PostgreSQL użyj tych danych:
- Nazwa użytkownika: „
postgres” - Baza danych: „
postgres” - Hasło: „
alloydb” (lub inne hasło ustawione podczas tworzenia)
Po pomyślnym uwierzytelnieniu w AlloyDB Studio polecenia SQL są wpisywane w Edytorze. Możesz dodać wiele okien Edytora, klikając znak plusa po prawej stronie ostatniego okna.
Polecenia dla AlloyDB będziesz wpisywać w oknach edytora, używając w razie potrzeby opcji Uruchom, Formatuj i Wyczyść.
Włącz rozszerzenia
Do utworzenia tej aplikacji użyjemy rozszerzeń pgvector i google_ml_integration. Rozszerzenie pgvector umożliwia przechowywanie wektorów dystrybucyjnych i wyszukiwanie ich. Rozszerzenie google_ml_integration udostępnia funkcje, których możesz używać do uzyskiwania dostępu do punktów końcowych prognozowania Vertex AI w celu uzyskiwania prognoz w SQL. Włącz te rozszerzenia, uruchamiając te DDL:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Tworzenie tabeli
Tabelę możesz utworzyć za pomocą instrukcji DDL poniżej w AlloyDB Studio:
-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id UUID,
provider_name TEXT,
provider_phone TEXT,
title TEXT,
bio TEXT,
category TEXT,
image_url TEXT,
item_vector VECTOR(768),
status TEXT DEFAULT 'available',
created_at TIMESTAMP DEFAULT NOW()
);
-- Swipes Table (The Interaction)
CREATE TABLE swipes (
swipe_id SERIAL PRIMARY KEY,
swiper_id UUID,
item_id UUID REFERENCES items(item_id),
direction TEXT CHECK (direction IN ('left', 'right')),
is_match BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
Kolumna item_vector będzie przechowywać wartości wektorowe tekstu.
Przyznaj uprawnienia
Aby przyznać uprawnienia do wykonywania funkcji „embedding”, uruchom to polecenie:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Przyznawanie roli Użytkownik Vertex AI kontu usługi AlloyDB
W konsoli IAM Google Cloud przyznaj kontu usługi AlloyDB (które wygląda tak: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) dostęp do roli „Użytkownik Vertex AI”. Zmienna PROJECT_NUMBER będzie zawierać numer Twojego projektu.
Możesz też uruchomić to polecenie w terminalu Cloud Shell:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
Rejestrowanie modelu Gemini 3 Flash w AlloyDB
Uruchom poniższą instrukcję SQL w edytorze zapytań AlloyDB.
CALL google_ml.create_model(
model_id => 'gemini-3-flash-preview',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
model_qualified_name => 'gemini-3-flash-preview',
model_provider => 'google',
model_type => 'llm',
model_auth_type => 'alloydb_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Pułapki i rozwiązywanie problemów
Pętla „amnezji hasła” | Jeśli używasz konfiguracji „Jedno kliknięcie” i nie pamiętasz hasła, otwórz stronę podstawowych informacji o instancji w konsoli i kliknij „Edytuj”, aby zresetować hasło |
Błąd „Nie znaleziono rozszerzenia” | Jeśli |
Opóźnienie propagacji uprawnień | Uruchomiono polecenie |
Niezgodność wymiarów wektora | Tabela |
Błąd w identyfikatorze projektu | Jeśli w wywołaniu |
5. Pamięć obrazów (Google Cloud Storage)
Do przechowywania zdjęć naszych produktów z nadwyżki wykorzystujemy zasobnik GCS. Na potrzeby tej aplikacji demonstracyjnej chcemy, aby obrazy były publicznie dostępne, dzięki czemu będą się natychmiast renderować na kartach do przesuwania.
- Utwórz zasobnik: utwórz nowy zasobnik w projekcie GCP (np. neighborloop-images), najlepiej w tym samym regionie co baza danych i aplikacja.
- Skonfiguruj dostęp publiczny: * Otwórz kartę Uprawnienia zasobnika.
- Dodaj podmiot zabezpieczeń allUsers.
- Przypisz rolę wyświetlającego obiekty Cloud Storage (aby wszyscy mogli zobaczyć zdjęcia) i rolę twórcy obiektów Cloud Storage (na potrzeby przesyłania wersji demonstracyjnej).
Alternatywa (konto usługi): jeśli nie chcesz korzystać z dostępu publicznego, upewnij się, że konto usługi aplikacji ma pełny dostęp do AlloyDB i niezbędne role Storage, aby bezpiecznie zarządzać obiektami.
Pułapki i rozwiązywanie problemów
The Region Drag | Jeśli Twoja baza danych znajduje się w |
Unikalność nazwy zasobnika | Nazwy zasobników należą do globalnej przestrzeni nazw. Jeśli spróbujesz nazwać zasobnik |
Pomylenie „twórcy” z „oglądającym” | Pomylenie „Twórcy” z „Wyświetlającym”: jeśli dodasz tylko „Wyświetlającego”, aplikacja ulegnie awarii, gdy użytkownik spróbuje dodać nowy produkt, ponieważ nie ma uprawnień do zapisywania pliku. W przypadku tej konkretnej konfiguracji wersji demonstracyjnej potrzebujesz obu tych elementów. |
6. Tworzenie aplikacji
Sklonuj to repozytorium do swojego projektu i przejdźmy przez nie.
- Aby sklonować ten projekt, uruchom to polecenie w terminalu Cloud Shell (w katalogu głównym lub w dowolnym miejscu, w którym chcesz utworzyć ten projekt):
git clone https://github.com/AbiramiSukumaran/neighbor-loop
Powinno to spowodować utworzenie projektu. Możesz to sprawdzić w edytorze Cloud Shell.
- Jak uzyskać klucz interfejsu Gemini API
- Otwórz Google AI Studio: wejdź na aistudio.google.com.
- Zaloguj się na to samo konto Google, którego używasz w projekcie Google Cloud.
- Utwórz klucz interfejsu API:
- Na pasku bocznym po lewej stronie kliknij „Uzyskaj klucz API”.
- Kliknij przycisk „Utwórz klucz interfejsu API w nowym projekcie”.
- Skopiuj klucz: po wygenerowaniu klucza kliknij ikonę kopiowania.
- Teraz ustaw zmienne środowiskowe w pliku .env.
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Zastąp wartości symboli zastępczych <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Pułapki i rozwiązywanie problemów
Wiele kont | Jeśli korzystasz z kilku kont Google (osobistego i służbowego), AI Studio może domyślnie używać niewłaściwego konta. Sprawdź awatara w prawym górnym rogu, aby upewnić się, że pasuje do konta projektu GCP. |
Wykorzystanie limitu w ramach „bezpłatnej wersji” | Jeśli korzystasz z poziomu bezpłatnego, obowiązują limity częstotliwości (RPM – liczba żądań na minutę). Jeśli w trybie sąsiedzkim przesuniesz palcem zbyt szybko, może pojawić się błąd |
Zabezpieczenia klucza publicznego | Jeśli przypadkowo |
Pustka „Przekroczenie limitu czasu połączenia” | W pliku .env używasz prywatnego adresu IP, ale próbujesz połączyć się z zewnątrz sieci VPC (np. z komputera lokalnego). Prywatne adresy IP są dostępne tylko w ramach tej samej sieci Google Cloud. Przełącz na publiczny adres IP. |
Założenie dotyczące portu 5432 | Chociaż 5432 to standardowy port PostgreSQL, AlloyDB czasami wymaga określonych konfiguracji portów, jeśli używasz serwera proxy uwierzytelniania. Na potrzeby tego modułu upewnij się, że na końcu ciągu hosta używasz portu 5432. |
Ochrona „Autoryzowane sieci” | Nawet jeśli masz publiczny adres IP, AlloyDB będzie odrzucać połączenia, chyba że dodasz adres IP maszyny, na której działa kod, do listy dozwolonych adresów.Rozwiązanie: w ustawieniach instancji AlloyDB dodaj 0.0.0.0/0 (tylko do tymczasowego testowania) lub konkretny adres IP do autoryzowanych sieci. |
Nie udało się uzgodnić połączenia za pomocą protokołu SSL/TLS | AlloyDB preferuje bezpieczne połączenia. Jeśli zmienna DATABASE_URL nie określa prawidłowo sterownika (np. używa pg8000), uzgadnianie może się nie powieść bez powiadomienia, co spowoduje wyświetlenie ogólnego błędu „Nie można nawiązać połączenia z bazą danych”. |
Zamiana „puli podstawowej” na „pulę odczytu” | Jeśli przypadkowo skopiujesz adres IP puli odczytu zamiast głównej instancji, aplikacja będzie działać podczas wyszukiwania produktów, ale ulegnie awarii z błędem „Tylko do odczytu”, gdy spróbujesz dodać nowy produkt. Zawsze używaj adresu IP instancji głównej do zapisów. |
7. Sprawdźmy kod
„Profil randkowy” Twoich rzeczy
Gdy użytkownik przesyła zdjęcie produktu, nie musi pisać długiego opisu. Używam Gemini 3 Flash, aby „zobaczyć” produkt i napisać opis.
W backendzie użytkownik podaje tylko tytuł i zdjęcie. Gemini zajmie się resztą:
prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
"bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
"category": "One-word category",
"tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
model="gemini-3-flash-preview",
contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
config=types.GenerateContentConfig(response_mime_type="application/json")
)
Wektory dystrybucyjne w bazie danych w czasie rzeczywistym
Jedną z najciekawszych funkcji AlloyDB jest możliwość generowania wektorów dystrybucyjnych bez opuszczania kontekstu SQL. Zamiast wywoływać model osadzania w Pythonie i wysyłać wektor z powrotem do bazy danych, wykonuję to wszystko w jednej instrukcji INSERT za pomocą funkcji embedding():
INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
:owner, :name, :phone, :title, :bio, :cat, :url, 'available',
embedding('text-embedding-005', :title || ' ' || :bio)::vector
)
Dzięki temu każdy element jest „wyszukiwalny” według znaczenia od momentu opublikowania. Pamiętaj, że ta część dotyczy funkcji „wystawiania produktu” w aplikacji Neighbor Loop.
Zaawansowane wyszukiwanie wektorowe i inteligentne filtrowanie z Gemini 3.0
Standardowe wyszukiwanie słów kluczowych jest ograniczone. Jeśli wyszukasz „coś do naprawy krzesła”, tradycyjna baza danych może nie zwrócić żadnych wyników, jeśli słowo „krzesło” nie występuje w tytule. Neighbor Loop rozwiązuje ten problem dzięki zaawansowanemu wyszukiwaniu wektorowemu w AlloyDB AI.
Dzięki rozszerzeniu pgvector i zoptymalizowanemu przechowywaniu w AlloyDB możemy przeprowadzać niezwykle szybkie wyszukiwania podobieństw. Prawdziwa „magia” zaczyna się jednak, gdy połączymy bliskość wektorową z logiką opartą na LLM.
AlloyDB AI umożliwia wywoływanie modeli takich jak Gemini bezpośrednio w zapytaniach SQL. Oznacza to, że możemy przeprowadzić odkrywanie semantyczne, które obejmuje oparty na logice „test poprawności” za pomocą funkcji ai.if():
SELECT item_id, title, bio, category, image_url,
1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
AND item_vector IS NOT NULL
AND ai.if(
prompt => 'Does this text: "' || bio ||'" match the user request: "' || :query || '", at least 60%? "',
model_id => 'gemini-3-flash-preview'
)
ORDER BY score DESC
LIMIT 5
To zapytanie reprezentuje znaczącą zmianę w architekturze: przenosimy logikę do danych. Zamiast pobierać tysiące wyników do kodu aplikacji, aby je filtrować, Gemini 3 Flash przeprowadza „sprawdzenie atmosfery” w silniku bazy danych. Zmniejsza to czas oczekiwania, obniża koszty wychodzące i zapewnia, że wyniki są nie tylko podobne pod względem matematycznym, ale też odpowiednie w kontekście.
Pętla „Przesuń, aby dopasować”
Interfejs użytkownika to klasyczna talia kart.
Przesuń w lewo: odrzuć.
Przesuń w prawo: to pasuje!
Gdy przesuniesz palcem w prawo, backend zarejestruje interakcję w naszej tabeli przesunięć i oznaczy element jako dopasowany. Interfejs natychmiast wyświetli okno z danymi kontaktowymi dostawcy, aby umożliwić Ci umówienie odbioru.
8. Wdróżmy go w Cloud Run
- Wdróż go w Cloud Run, uruchamiając to polecenie w terminalu Cloud Shell, w którym sklonowano projekt. Upewnij się, że jesteś w folderze głównym projektu.
Uruchom to polecenie w terminalu Cloud Shell:
gcloud beta run deploy neighbor-loop \
--source . \
--region=us-central1 \
--network=<<YOUR_NETWORK_NAME>> \
--subnet=<<YOUR_SUBNET_NAME>> \
--allow-unauthenticated \
--vpc-egress=all-traffic \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:<<PORT>>/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Zastąp wartości symboli zastępczych <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Po zakończeniu polecenia wyświetli się adres URL usługi. Skopiuj go.
- Przyznaj wykonawczemu kontu usługi Cloud Run rolę Klient AlloyDB.Umożliwi to bezserwerowej aplikacji bezpieczne tunelowanie do bazy danych.
Uruchom to polecenie w terminalu Cloud Shell:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
Teraz użyj adresu URL usługi (punktu końcowego Cloud Run skopiowanego wcześniej) i przetestuj aplikację. Prześlij zdjęcie starego elektronarzędzia i pozwól Gemini wykonać resztę.
Pułapki i rozwiązywanie problemów
Pętla „Nie udało się wprowadzić zmian” | Jeśli wdrożenie się zakończy, ale adres URL zwróci |
Rola „Shadow” w IAM | Nawet jeśli Ty masz uprawnienia do wdrożenia, konto usługi Cloud Run (zwykle |
9. Ogólne rozwiązywanie problemów
10. Prezentacja
Powinien być dostępny punkt końcowy do testów.
Jednak na potrzeby demonstracji możesz przez kilka dni wypróbować to rozwiązanie:
11. Czyszczenie danych
Po ukończeniu tego modułu nie zapomnij usunąć klastra i instancji AlloyDB.
Powinien on wyczyścić klaster wraz z instancjami.
12. Gratulacje
Udało Ci się utworzyć aplikację Neighbor Loop dla zrównoważonych społeczności za pomocą Google Cloud. Dzięki przeniesieniu logiki osadzania i AI Gemini 3 Flash do AlloyDB aplikacja działa niezwykle szybko (w zależności od ustawień wdrożenia), a kod jest wyjątkowo przejrzysty. Nie przechowujemy tylko danych, ale też intencje.
Połączenie szybkości Gemini 3 Flash i zoptymalizowanego przetwarzania wektorowego AlloyDB to prawdziwa przyszłość platform opartych na społeczności.