1. Übersicht
In diesem Codelab entwickeln Sie Neighbor Loop, eine nachhaltige App zum Teilen von Überschüssen, in der Intelligenz als wichtiger Bestandteil der Datenschicht behandelt wird.
Durch die Integration von Gemini 3.0 Flash und der ML-Integration von Cloud SQL können Sie über die grundlegende Speicherung hinausgehen und In-Database Intelligence nutzen. Sie erfahren, wie Sie multimodale Artikelanalysen und semantische Ermittlungen direkt in SQL durchführen.
Aufgaben
Eine leistungsstarke Webanwendung mit „Wischen zum Matchen“ für das Teilen von Community-Überschüssen.
Lerninhalte
- One-Click Provisioning: So richten Sie eine Cloud SQL-Instanz ein, die für KI-Arbeitslasten konzipiert ist.
- In-Database Embeddings: Generieren von text-embedding-005-Vektoren direkt in INSERT-Anweisungen.
- Multimodales Reasoning: Gemini 3.0 Flash kann Elemente „sehen“ und automatisch witzige Biografien im Dating-Stil generieren.
- Semantische Ermittlung: Logikbasierte „Vibe-Checks“ in SQL-Abfragen mit der Funktion „ai.if()“ durchführen, um Ergebnisse basierend auf dem Kontext und nicht nur auf mathematischen Berechnungen zu filtern.
Die Architektur
Neighbor Loop umgeht herkömmliche Engpässe auf Anwendungsebene. Anstatt Daten zur Verarbeitung zu extrahieren, verwenden wir:
- Cloud SQL + ML-Integration:Zum Generieren und Speichern von Vektoren in Echtzeit.
- Google Cloud Storage:zum Speichern von Bildern
- Gemini 3.0 Flash:Damit können Sie in weniger als einer Sekunde Schlussfolgerungen aus Bild- und Textdaten direkt über SQL ziehen.
- Cloud Run:Zum Hosten eines einfachen Flask-Back-Ends mit einer einzigen Datei.
Voraussetzungen
2. Hinweis
Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
- Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.
- Sobald die Verbindung mit der Cloud Shell hergestellt ist, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt ist:
gcloud auth list
- Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt.
gcloud config list project
- Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:
gcloud config set project <YOUR_PROJECT_ID>
- Aktivieren Sie die erforderlichen APIs: Folgen Sie dem Link und aktivieren Sie die APIs.
Alternativ können Sie dazu den gcloud-Befehl verwenden. Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.
Wichtige Hinweise und Fehlerbehebung
Das „Ghost Project“-Syndrom | Sie haben |
Die Abrechnungsbarrikade | Sie haben das Projekt aktiviert, aber das Rechnungskonto vergessen. Cloud SQL wird nicht gestartet, wenn die Abrechnung leer ist. |
Verzögerung bei der API-Weitergabe | Sie haben auf „APIs aktivieren“ geklickt, aber in der Befehlszeile wird weiterhin |
3. Datenbank einrichten
In diesem Lab verwenden wir Cloud SQL for PostgreSQL als Datenbank für die Testdaten.
Erstellen wir eine Cloud SQL-Instanz, in die das Test-Dataset geladen wird.
- Klicken Sie auf die Schaltfläche oder kopieren Sie den Link unten in den Browser, in dem der Google Cloud Console-Nutzer angemeldet ist.
- Sobald dieser Schritt abgeschlossen ist, wird das Repository in Ihren lokalen Cloud Shell-Editor geklont und Sie können den folgenden Befehl über den Projektordner ausführen. Achten Sie darauf, dass Sie sich im Projektverzeichnis befinden:
sh run.sh
- Verwenden Sie jetzt die Benutzeroberfläche (klicken Sie auf den Link im Terminal oder auf den Link „Vorschau im Web“ im Terminal).
- Geben Sie Ihre Daten für die Projekt-ID und den Instanznamen ein, um zu beginnen.
- Holen Sie sich einen Kaffee, während die Logs durchlaufen. Hier können Sie nachlesen, wie das im Hintergrund funktioniert.
Wichtige Hinweise und Fehlerbehebung
Region stimmt nicht überein | Wenn Sie Ihre APIs in |
Cloud Shell-Zeitüberschreitung | Wenn Ihre Kaffeepause 30 Minuten dauert, wechselt Cloud Shell möglicherweise in den Ruhemodus und trennt die Verbindung zum |
4. Schemabereitstellung
Sobald Ihre Cloud SQL-Instanz ausgeführt wird, rufen Sie den SQL-Editor von Cloud SQL Studio auf, um die KI-Erweiterungen zu aktivieren und das Schema bereitzustellen.
Möglicherweise müssen Sie warten, bis die Instanz erstellt wurde. Melden Sie sich dann mit den Anmeldedaten, die Sie beim Erstellen der Instanz erstellt haben, in der Cloud SQL-Instanz an. Verwenden Sie die folgenden Daten für die Authentifizierung bei PostgreSQL:
- Nutzername: „
postgres“ - Datenbank: „
postgres“ - Passwort: „
cloudsql“ (oder das Passwort, das Sie bei der Erstellung festgelegt haben)
Nachdem Sie sich erfolgreich in Cloud SQL Studio authentifiziert haben, werden SQL-Befehle im Editor eingegeben. Sie können mehrere Editorfenster hinzufügen, indem Sie auf das Pluszeichen rechts neben dem letzten Fenster klicken.
Sie geben Befehle für Cloud SQL in Editorfenstern ein und verwenden bei Bedarf die Optionen „Ausführen“, „Formatieren“ und „Löschen“.
Erweiterungen aktivieren
Für die Entwicklung dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der pgvector-Erweiterung können Sie Vektoreinbettungen speichern und durchsuchen. Die Erweiterung google_ml_integration bietet Funktionen, mit denen Sie auf Vertex AI-Vorhersageendpunkte zugreifen können, um Vorhersagen in SQL zu erhalten. Aktivieren Sie diese Erweiterungen, indem Sie die folgenden DDLs ausführen:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Tabelle erstellen
Sie können eine Tabelle mit der folgenden DDL-Anweisung in Cloud SQL Studio erstellen:
-- 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()
);
In der Spalte item_vector können die Vektorwerte des Texts gespeichert werden.
Berechtigung gewähren
Führen Sie die folgende Anweisung aus, um die Ausführung der Funktion „embedding“ zu gewähren:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
ML-Integration aktivieren
Wenn Sie Machine-Learning-Funktionen direkt in Ihrer Datenbank nutzen möchten, müssen Sie das Flag für die ML-Integration aktivieren.
Sie können den folgenden Befehl im Cloud Shell-Terminal ausführen:
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
Cloud SQL-Dienstkonto die Rolle „Vertex AI User“ gewähren
Gewähren Sie in der Google Cloud IAM-Konsole dem Cloud SQL-Dienstkonto (das so aussieht: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) Zugriff auf die Rolle „Vertex AI-Nutzer“. PROJECT_NUMBER enthält Ihre Projektnummer.
Alternativ können Sie den folgenden Befehl im Cloud Shell-Terminal ausführen:
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"
Gemini 3 Flash-Modell in Cloud SQL registrieren
Führen Sie die folgende SQL-Anweisung im Cloud SQL-Abfrageeditor aus.
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.
Wichtige Hinweise und Fehlerbehebung
Die „Passwort vergessen“-Schleife | Wenn Sie die Einrichtung mit nur einem Klick verwendet haben und sich nicht mehr an Ihr Passwort erinnern, rufen Sie in der Konsole die Seite mit den grundlegenden Informationen zur Instanz auf und klicken Sie auf „Bearbeiten“, um das |
Fehler „Erweiterung nicht gefunden“ | Wenn |
IAM-Weitergabeverzögerung | Sie haben den IAM-Befehl |
Falsche Vektordimension | Die Tabelle |
Tippfehler in der Projekt-ID | Wenn Sie im |
Vertex AI-Einbindung ist deaktiviert | Führen Sie |
5. Bildspeicher (Google Cloud Storage)
Zum Speichern der Fotos unserer Überschussartikel verwenden wir einen GCS-Bucket. Für diese Demo-App sollen die Bilder öffentlich zugänglich sein, damit sie sofort auf unseren Wischkarten gerendert werden.
- Bucket erstellen: Erstellen Sie einen neuen Bucket in Ihrem GCP-Projekt (z.B. „neighborloop-images“), vorzugsweise in derselben Region wie Ihre Datenbank und Anwendung.
- Öffentlichen Zugriff konfigurieren: * Rufen Sie den Tab Berechtigungen des Buckets auf.
- Fügen Sie das Hauptkonto allUsers hinzu.
- Weisen Sie die Rolle Storage-Objekt-Betrachter (damit jeder die Fotos sehen kann) und die Rolle Storage-Objekt-Ersteller (für Demo-Uploads) zu.
Alternative (Dienstkonto): Wenn Sie keinen öffentlichen Zugriff verwenden möchten, müssen Sie dem Dienstkonto Ihrer Anwendung vollen Zugriff auf Cloud SQL und die erforderlichen Speicherrollen gewähren, um Objekte sicher zu verwalten.
Wenn Sie den Befehl ausführen und öffentlichen Zugriff gewähren möchten. Führen Sie die folgenden Befehle im Cloud Shell-Terminal aus:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Wichtige Hinweise und Fehlerbehebung
Der Region Drag | Wenn sich Ihre Datenbank in |
Eindeutigkeit von Bucket-Namen | Bucket-Namen sind ein globaler Namespace. Wenn Sie versuchen, Ihren Bucket |
Verwechslung von „Creator“ und „Zuschauer“ | Verwechslung von „Ersteller“ und „Betrachter“:Wenn Sie nur „Betrachter“ hinzufügen, stürzt Ihre App ab, wenn ein Nutzer versucht, einen neuen Artikel aufzulisten, da sie keine Berechtigung zum Schreiben der Datei hat. Für diese spezielle Demoeinrichtung benötigen Sie beide. |
6. Anwendung erstellen
Klonen Sie dieses Repository in Ihr Projekt und sehen wir uns die einzelnen Schritte an.
- Führen Sie zum Klonen dieses Projekts im Cloud Shell-Terminal (im Stammverzeichnis oder an einem beliebigen anderen Ort, an dem Sie das Projekt erstellen möchten) die folgenden Befehle nacheinander aus:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Dadurch sollte das Projekt erstellt werden. Sie können dies im Cloud Shell Editor überprüfen.
- Gemini API-Schlüssel abrufen
- Google AI Studio aufrufen: Rufen Sie aistudio.google.com auf.
- Anmelden: Verwenden Sie dasselbe Google-Konto, das Sie für Ihr Google Cloud-Projekt verwenden.
- API-Schlüssel erstellen:
- Klicken Sie in der linken Seitenleiste auf „API-Schlüssel abrufen“.
- Klicken Sie auf die Schaltfläche „API-Schlüssel in neuem Projekt erstellen“.
- Schlüssel kopieren: Klicken Sie nach dem Generieren des Schlüssels auf das Symbol zum Kopieren.
- Legen Sie nun die Umgebungsvariablen in der Datei „.env“ fest.
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Ersetzen Sie die Werte für die Platzhalter <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>..
Wichtige Hinweise und Fehlerbehebung
Verwirrung durch mehrere Konten | Wenn Sie in mehreren Google-Konten angemeldet sind (privat und geschäftlich), wird in AI Studio möglicherweise das falsche Konto verwendet. Prüfen Sie den Avatar rechts oben, um sicherzugehen, dass er mit dem Konto für Ihr GCP-Projekt übereinstimmt. |
Kontingentüberschreitung bei kostenlosem Kontingent | Wenn Sie die kostenlose Stufe verwenden, gelten Ratenbegrenzungen (RPM – Anfragen pro Minute). Wenn Sie in Neighbor Loop zu schnell wischen, erhalten Sie möglicherweise den Fehler |
Sicherheit von offengelegten Schlüsseln | Wenn Sie Ihre |
7. Sehen wir uns den Code an
Das „Dating-Profil“ für deine Sachen
Wenn ein Nutzer ein Foto eines Artikels hochlädt, sollte er keine lange Beschreibung schreiben müssen. Ich verwende Gemini 3 Flash, um den Artikel zu „sehen“ und das Angebot zu schreiben.
Im Backend gibt der Nutzer nur einen Titel und ein Foto an. Gemini erledigt den Rest:
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")
)
In-Database-Einbettungen in Echtzeit
Eines der besten Features von Cloud SQL ist die Möglichkeit, Einbettungen zu generieren, ohne den SQL-Kontext zu verlassen. Anstatt ein Einbettungsmodell in Python aufzurufen und den Vektor zurück an die Datenbank zu senden, erledige ich alles in einer INSERT-Anweisung mit der Funktion „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
)
So wird sichergestellt, dass jeder Artikel sofort nach dem Posten nach seiner Bedeutung „durchsuchbar“ ist. Dieser Teil deckt die Funktion „Produkt auflisten“ der Neighbor Loop App ab.
Erweiterte Vektorsuche und intelligentes Filtern mit Gemini 3.0
Die Standardsuche nach Keywords ist eingeschränkt. Wenn Sie nach „etwas, um meinen Stuhl zu reparieren“ suchen, gibt eine herkömmliche Datenbank möglicherweise nichts zurück, wenn das Wort „Stuhl“ nicht in einem Titel enthalten ist. Neighbor Loop löst dieses Problem mit der erweiterten Vektorsuche von Cloud SQL AI.
Durch die Verwendung der pgvector-Erweiterung und des für Cloud SQL optimierten Speichers können wir extrem schnelle Ähnlichkeitssuchen durchführen. Das volle Potenzial entfaltet sich aber erst, wenn wir die Vektornähe mit LLM-basierter Logik kombinieren.
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
Diese Abfrage stellt eine wichtige architektonische Änderung dar: Wir verlagern die Logik zu den Daten. Anstatt Tausende von Ergebnissen in den Anwendungscode zu ziehen, um sie zu filtern, führt Gemini 3 Flash eine „Vibe-Prüfung“ in der Datenbank-Engine durch. Dadurch werden die Latenz und die Kosten für ausgehenden Traffic gesenkt und die Ergebnisse sind nicht nur mathematisch ähnlich, sondern auch kontextbezogen relevant.
Der „Swipe to Match“-Loop
Die Benutzeroberfläche ist ein klassisches Kartendeck.
Nach links wischen: Verwerfen.
Nach rechts wischen: Es passt!
Wenn Sie nach rechts wischen, wird die Interaktion im Backend in unserer Tabelle für Wischvorgänge aufgezeichnet und das Element als „gematcht“ markiert. Im Frontend wird sofort ein Pop-up-Fenster mit den Kontaktdaten des Anbieters angezeigt, damit Sie die Abholung vereinbaren können.
8. In Cloud Run bereitstellen
- Stellen Sie die App in Cloud Run bereit, indem Sie den folgenden Befehl im Cloud Shell-Terminal ausführen, in dem das Projekt geklont wurde. Achten Sie darauf, dass Sie sich im Stammordner des Projekts befinden.
Führen Sie diesen Befehl in Ihrem Cloud Shell-Terminal aus:
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>>
Ersetzen Sie die Werte für die Platzhalter <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Nach Abschluss des Befehls wird eine Dienst-URL ausgegeben. Kopieren.
Verwenden Sie jetzt die Dienst-URL (den zuvor kopierten Cloud Run-Endpunkt) und testen Sie die App. Laden Sie ein Foto des alten Elektrowerkzeugs hoch und lassen Sie Gemini den Rest erledigen.
Wichtige Hinweise und Fehlerbehebung
Die Schleife „Überarbeitung fehlgeschlagen“ | Wenn die Bereitstellung abgeschlossen ist, die URL aber |
9. Allgemeine Fehlerbehebung
10. Demo
Sie sollten Ihren Endpunkt für Tests verwenden können.
Für Demozwecke können Sie aber einige Tage lang Folgendes ausprobieren:
11. Bereinigen
Vergessen Sie nicht, die Cloud SQL-Instanz zu löschen, wenn Sie dieses Lab abgeschlossen haben.
12. Glückwunsch
Sie haben die Neighbor Loop-App für nachhaltige Communities mit Google Cloud erfolgreich erstellt. Durch die Verlagerung der Einbettung und der Gemini 3 Flash-KI-Logik in Cloud SQL ist die App unglaublich schnell (abhängig von den Bereitstellungseinstellungen) und der Code ist bemerkenswert übersichtlich. Wir speichern nicht nur Daten, sondern auch Intentionen.
Die Kombination aus der Geschwindigkeit von Gemini 3 Flash und der optimierten Vektorverarbeitung von Cloud SQL ist wirklich die nächste Dimension für communitybasierte Plattformen.