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 z integracją ML w Cloud SQL wyjdziesz poza podstawowe przechowywanie danych i wejdziesz w sferę inteligencji w bazie danych. Dowiesz się, jak przeprowadzać analizę elementów multimodalnych i odkrywanie semantyczne bezpośrednio w SQL.
Co utworzysz
Wysokowydajna aplikacja internetowa „przesuń, aby dopasować” do udostępniania nadwyżek w społeczności.
Czego się nauczysz
- Konfigurowanie jednym kliknięciem: jak skonfigurować Cloud SQL i instancję zaprojektowaną 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(), aby filtrować wyniki na podstawie kontekstu, a nie tylko obliczeń.
Architektura
Neighbor Loop omija tradycyjne wąskie gardła w warstwie aplikacji. Zamiast wyodrębniać dane do przetworzenia, używamy:
- Integracja Cloud SQL z ML: do generowania i przechowywania wektorów w czasie rzeczywistym.
- Google Cloud Storage: do przechowywania obrazów.
- Gemini 3.0 Flash: do wykonywania w mniej niż sekundę wnioskowania na podstawie danych w postaci 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 wyboru projektu 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 uwierzytelnianie zostało już przeprowadzone, a projekt jest już 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. Cloud SQL nie uruchomi się, jeśli nie ma informacji o płatnościach. |
Opóźnienie propagacji interfejsu API | Kliknięto „Włącz interfejsy API”, ale w wierszu poleceń nadal widnieje symbol |
3. Konfiguracja bazy danych
W tym module użyjemy Cloud SQL for PostgreSQL jako bazy danych na potrzeby danych testowych.
Utwórzmy instancję Cloud SQL, do której zostanie wczytany testowy zbiór danych.
- Kliknij przycisk lub skopiuj poniższy link do przeglądarki, w której zalogowany jest użytkownik Google Cloud Console.
- 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 przeglądarce” w terminalu).
- Aby rozpocząć, wpisz szczegóły identyfikatora projektu i nazwy 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
Niezgodny region | Jeśli interfejsy API zostały włączone w regionie |
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. Provisioning schematu
Po uruchomieniu instancji Cloud SQL przejdź do edytora SQL w Cloud SQL 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 instancji Cloud SQL przy użyciu danych logowania utworzonych podczas jej tworzenia. Do uwierzytelniania w PostgreSQL użyj tych danych:
- Nazwa użytkownika: „
postgres” - Baza danych: „
postgres” - Hasło: „
cloudsql” (lub inne hasło ustawione podczas tworzenia)
Po pomyślnym uwierzytelnieniu w Cloud SQL Studio polecenia SQL są wpisywane w Edytorze. Możesz dodać wiele okien Edytora, klikając znak plusa po prawej stronie ostatniego okna.
Polecenia Cloud SQL będziesz wpisywać w oknach edytora, korzystając w razie potrzeby z 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ą poniższej instrukcji DDL w Cloud SQL 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;
Włącz integrację z ML
Aby korzystać z funkcji uczenia maszynowego bezpośrednio w bazie danych, musisz włączyć flagę integracji uczenia maszynowego.
Poniższe polecenie możesz uruchomić w terminalu Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840
gcloud sql instances patch $INSTANCE_NAME \
--database-flags=cloudsql.enable_google_ml_integration=on
gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration
Przypisywanie roli Użytkownik Vertex AI do konta usługi Cloud SQL
W konsoli IAM Google Cloud przyznaj kontu usługi Cloud SQL (które wygląda tak: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.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:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_EMAIL" \
--role="roles/aiplatform.user"
Rejestrowanie modelu Gemini 3 Flash w Cloud SQL
Uruchom poniższą instrukcję SQL w edytorze zapytań Cloud SQL.
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 => 'generic',
model_auth_type => 'cloudsql_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 |
Integracja z Vertex AI jest wyłączona | Uruchom |
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.
- 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ę tworzącego obiekty 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 Twojej aplikacji ma pełny dostęp do Cloud SQL i niezbędne role Storage do bezpiecznego zarządzania obiektami.
Jeśli chcesz uruchomić polecenie i przyznać dostęp publiczny. Uruchom te polecenia w terminalu Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
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 element, ponieważ nie ma uprawnień do zapisu pliku. W tym konkretnym przypadku potrzebujesz obu tych elementów. |
6. Tworzenie aplikacji
Sklonuj to repozytorium do swojego projektu i przejdźmy przez nie.
- Aby sklonować ten projekt, w terminalu Cloud Shell (w katalogu głównym lub w dowolnym miejscu, w którym chcesz utworzyć ten projekt) uruchom kolejno te polecenia:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
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 stronę 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. 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 szybkości (RPM – liczba żądań na minutę). Jeśli w pętli sąsiedzkiej „przesuniesz” zbyt szybko, może pojawić się błąd |
Zabezpieczenia klucza publicznego | Jeśli przypadkowo |
7. Sprawdźmy kod
„Profil randkowy” Twoich rzeczy
Gdy użytkownik przesyła zdjęcie produktu, nie powinien musieć 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 Cloud SQL 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, robię 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 Cloud SQL AI.
Dzięki rozszerzeniu pgvector i zoptymalizowanej pamięci masowej Cloud SQL możemy przeprowadzać bardzo szybkie wyszukiwania podobieństw. Prawdziwa „magia” zaczyna się jednak, gdy połączymy bliskość wektorową z logiką opartą na LLM.
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
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 „wstępną weryfikację” 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 to klasyczna talia kart.
Przesuń w lewo: odrzuć.
Przesuń w prawo: udało się!
Gdy przesuniesz palcem w prawo, backend zarejestruje interakcję w 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 run deploy neighbor-loop-cloud-sql \
--source . \
--region=us-central1 \
--allow-unauthenticated \
--network=easy-cloudsql-vpc \
--subnet=easy-cloudsql-subnet \
--vpc-egress=private-ranges-only \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/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.
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ę pracy.
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 |
9. Ogólne rozwiązywanie problemów
10. Prezentacja
Powinno być możliwe używanie punktu końcowego do testów.
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ąć instancji Cloud SQL.
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 Cloud SQL aplikacja działa niezwykle szybko (w zależności od ustawień wdrożenia), a kod jest wyjątkowo przejrzysty. Nie tylko przechowujemy dane, ale też intencje.
Połączenie szybkości Gemini 3 Flash i zoptymalizowanego przetwarzania wektorowego Cloud SQL to prawdziwa nowość w przypadku platform społecznościowych.