1. Présentation
Dans cet atelier de programmation, vous allez créer Neighbor Loop, une application de partage d'excédents durables qui traite l'intelligence comme un élément à part entière de la couche de données.
En intégrant Gemini 3.0 Flash et AlloyDB AI, vous passerez du stockage de base à l'intelligence dans la base de données. Vous apprendrez à effectuer une analyse multimodale des éléments et une découverte sémantique directement dans SQL, ce qui élimine la "taxe d'IA" de latence et d'encombrement architectural.
Ce que vous allez faire
Application Web "swipe-to-match" hautes performances pour le partage des excédents de la communauté.
Points abordés
- Provisionnement en un clic : découvrez comment configurer un cluster et une instance AlloyDB conçus pour les charges de travail d'IA.
- Embeddings dans la base de données : génération de vecteurs text-embedding-005 directement dans les instructions INSERT.
- Raisonnement multimodal : utiliser Gemini 3.0 Flash pour "voir" des éléments et générer automatiquement des bios amusantes de type "rencontres".
- Découverte sémantique : effectuez des "vérifications d'ambiance" basées sur la logique dans les requêtes SQL à l'aide de la fonction ai.if() pour filtrer les résultats en fonction du contexte, et pas seulement des mathématiques.
Architecture
Neighbor Loop contourne les goulots d'étranglement traditionnels de la couche application. Au lieu d'extraire les données pour les traiter, nous utilisons :
- AlloyDB AI : pour générer et stocker des vecteurs en temps réel.
- Google Cloud Storage : pour stocker des images
- Gemini 3.0 Flash : pour effectuer un raisonnement en moins d'une seconde sur des données d'image et de texte directement via SQL.
- Cloud Run : pour héberger un backend Flask léger et monofichier.
Conditions requises
2. Avant de commencer
Créer un projet
- Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
- Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.
- Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.
- Une fois connecté à Cloud Shell, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :
gcloud auth list
- Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.
gcloud config list project
- Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :
gcloud config set project <YOUR_PROJECT_ID>
- Activez les API requises : suivez ce lien et activez les API.
Vous pouvez également utiliser la commande gcloud. Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.
Problèmes et dépannage
Syndrome du projet fantôme | Vous avez exécuté |
Barricade de facturation | Vous avez activé le projet, mais oublié le compte de facturation. AlloyDB est un moteur hautes performances. Il ne démarrera pas si le "réservoir" (la facturation) est vide. |
Décalage de la propagation de l'API | Vous avez cliqué sur "Activer les API", mais la ligne de commande indique toujours |
Quags de quota | Si vous utilisez un tout nouveau compte d'essai, vous pouvez atteindre un quota régional pour les instances AlloyDB. Si |
Agent de service"masqué" | Il arrive que le compte de service AlloyDB ne reçoive pas automatiquement le rôle |
3. Configuration de la base de données
Dans cet atelier, nous utiliserons AlloyDB comme base de données pour les données de test. Il utilise des clusters pour stocker toutes les ressources, telles que les bases de données et les journaux. Chaque cluster possède une instance principale qui fournit un point d'accès aux données. Les tables contiennent les données réelles.
Commençons par créer un cluster, une instance et une table AlloyDB dans lesquels l'ensemble de données de test sera chargé.
- Cliquez sur le bouton ou copiez le lien ci-dessous dans le navigateur dans lequel l'utilisateur de la console Google Cloud est connecté.
- Une fois cette étape terminée, le dépôt sera cloné dans votre éditeur Cloud Shell local. Vous pourrez ensuite exécuter la commande ci-dessous à partir du dossier du projet (assurez-vous d'être dans le répertoire du projet) :
sh run.sh
- Utilisez maintenant l'UI (en cliquant sur le lien dans le terminal ou sur le lien "Prévisualiser sur le Web" dans le terminal).
- Saisissez les détails de l'ID de projet, du nom du cluster et du nom de l'instance pour commencer.
- Allez prendre un café pendant que les journaux défilent. Pour en savoir plus sur le fonctionnement en coulisses, cliquez ici.
Problèmes et dépannage
Le problème de la patience | Les clusters de bases de données sont une infrastructure lourde. Si vous actualisez la page ou mettez fin à la session Cloud Shell parce qu'elle semble bloquée, vous risquez de vous retrouver avec une instance "fantôme" partiellement provisionnée et impossible à supprimer sans intervention manuelle. |
Région non concordante | Si vous avez activé vos API dans |
Clusters de zombies | Si vous avez déjà utilisé le même nom pour un cluster et que vous ne l'avez pas supprimé, le script peut indiquer que le nom du cluster existe déjà. Les noms de clusters doivent être uniques dans un projet. |
Délai d'inactivité de Cloud Shell | Si votre pause-café dure 30 minutes, Cloud Shell peut se mettre en veille et déconnecter le processus |
4. Provisionnement de schémas
Une fois votre cluster et votre instance AlloyDB en cours d'exécution, accédez à l'éditeur SQL AlloyDB Studio pour activer les extensions d'IA et provisionner le schéma.
Vous devrez peut-être attendre la fin de la création de votre instance. Une fois le cluster créé, connectez-vous à AlloyDB à l'aide des identifiants que vous avez créés. Utilisez les données suivantes pour vous authentifier auprès de PostgreSQL :
- Nom d'utilisateur : "
postgres" - Base de données : "
postgres" - Mot de passe : "
alloydb" (ou celui que vous avez défini lors de la création)
Une fois l'authentification réussie dans AlloyDB Studio, les commandes SQL sont saisies dans l'éditeur. Vous pouvez ajouter plusieurs fenêtres de l'éditeur en cliquant sur le signe plus à droite de la dernière fenêtre.
Vous saisirez des commandes pour AlloyDB dans des fenêtres d'éditeur, en utilisant les options "Exécuter", "Mettre en forme" et "Effacer" selon les besoins.
Activer les extensions
Pour créer cette application, nous allons utiliser les extensions pgvector et google_ml_integration. L'extension pgvector vous permet de stocker et de rechercher des embeddings vectoriels. L'extension google_ml_integration fournit les fonctions que vous utilisez pour accéder aux points de terminaison de prédiction Vertex AI afin d'obtenir des prédictions en SQL. Activez ces extensions en exécutant les LDD suivants :
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Créer une table
Vous pouvez créer une table à l'aide de l'instruction LDD ci-dessous dans 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()
);
La colonne item_vector permettra de stocker les valeurs vectorielles du texte.
Accorder l'autorisation
Exécutez l'instruction ci-dessous pour accorder l'exécution de la fonction "embedding" :
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Attribuer le rôle Utilisateur Vertex AI au compte de service AlloyDB
Dans la console Google Cloud IAM, accordez au compte de service AlloyDB (qui ressemble à ceci : service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) l'accès au rôle "Utilisateur Vertex AI". PROJECT_NUMBER correspondra au numéro de votre projet.
Vous pouvez également exécuter la commande ci-dessous à partir du terminal 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"
Enregistrer le modèle Gemini 3 Flash dans AlloyDB
Exécutez l'instruction SQL ci-dessous à partir de l'éditeur de requête 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.
Problèmes et dépannage
La boucle "Mot de passe oublié" | Si vous avez utilisé la configuration "En un clic" et que vous ne vous souvenez plus de votre mot de passe, accédez à la page "Informations de base sur l'instance" dans la console, puis cliquez sur "Modifier" pour réinitialiser le mot de passe |
Erreur "Extension introuvable" | Si |
Délai de propagation IAM | Vous avez exécuté la commande IAM |
Incompatibilité de la dimension du vecteur | La table |
Faute de frappe dans l'ID du projet | Dans l'appel |
5. Stockage d'images (Google Cloud Storage)
Pour stocker les photos de nos articles excédentaires, nous utilisons un bucket GCS. Pour cette application de démonstration, nous souhaitons que les images soient accessibles au public afin qu'elles s'affichent instantanément dans nos cartes à balayer.
- Créez un bucket : créez un bucket dans votre projet GCP (par exemple, neighborloop-images), de préférence dans la même région que votre base de données et votre application.
- Configurer l'accès public : accédez à l'onglet Autorisations du bucket.
- Ajoutez le compte principal allUsers.
- Attribuez le rôle Lecteur des objets Storage (pour que tout le monde puisse voir les photos) et le rôle Créateur des objets Storage (pour les besoins de l'importation de la démo).
Alternative (compte de service) : si vous préférez ne pas utiliser l'accès public, assurez-vous que le compte de service de votre application dispose d'un accès complet à AlloyDB et des rôles Storage nécessaires pour gérer les objets de manière sécurisée.
Problèmes et dépannage
The Region Drag | Si votre base de données se trouve dans |
Unicité des noms de buckets | Les noms de buckets constituent un espace de noms global. Si vous essayez de nommer votre bucket |
Confusion entre "créateur" et "lecteur" | Confusion entre "Créateur" et "Lecteur" : si vous n'ajoutez que "Lecteur", votre application plantera lorsqu'un utilisateur tentera de lister un nouvel élément, car elle n'aura pas l'autorisation d'écrire le fichier. Vous aurez besoin des deux pour cette configuration de démonstration spécifique. |
6. Créer l'application
Clonez ce dépôt dans votre projet et examinons-le.
- Pour cloner ce dépôt, exécutez la commande suivante depuis le terminal Cloud Shell (dans le répertoire racine ou à l'emplacement où vous souhaitez créer ce projet) :
git clone https://github.com/AbiramiSukumaran/neighbor-loop
Le projet devrait être créé. Vous pouvez le vérifier dans l'éditeur Cloud Shell.
- Obtenir votre clé API Gemini
- Accédez à Google AI Studio : rendez-vous sur aistudio.google.com.
- Connexion : utilisez le même compte Google que celui de votre projet Google Cloud.
- Créer une clé API :
- Dans la barre latérale de gauche, cliquez sur "Get API key" (Obtenir une clé API).
- Cliquez sur le bouton "Créer une clé API dans un nouveau projet".
- Copiez la clé : une fois la clé générée, cliquez sur l'icône de copie.
- Définissez maintenant les variables d'environnement dans le fichier .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>>
Remplacez les valeurs des espaces réservés <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>..
Problèmes et dépannage
Confusion entre plusieurs comptes | Si vous êtes connecté à plusieurs comptes Google (personnel et professionnel), il est possible qu'AI Studio soit défini par défaut sur le mauvais compte. Vérifiez l'avatar en haut à droite pour vous assurer qu'il correspond à votre compte de projet GCP. |
Dépassement du quota du niveau sans frais | Si vous utilisez le niveau sans frais, des limites de fréquence (requêtes par minute) s'appliquent. Si vous balayez trop rapidement dans la boucle de quartier, vous pouvez obtenir une erreur |
Sécurité des clés exposées | Si vous avez accidentellement |
Le vide "Délai d'inactivité de la connexion" | Vous avez utilisé l'adresse IP privée dans votre fichier .env, mais vous essayez de vous connecter depuis l'extérieur du VPC (par exemple, depuis votre machine locale). Les adresses IP privées ne sont accessibles que depuis le même réseau Google Cloud. Passez à l'adresse IP publique. |
Hypothèse concernant le port 5432 | Bien que 5432 soit le port PostgreSQL standard, AlloyDB nécessite parfois des configurations de port spécifiques si vous utilisez un proxy d'authentification. Pour cet atelier, assurez-vous d'utiliser ":5432" à la fin de votre chaîne hôte. |
Gatekeeper "Réseaux autorisés" | Même si vous disposez de l'adresse IP publique, AlloyDB refusera la connexion, sauf si vous avez ajouté l'adresse IP de la machine exécutant le code à la liste blanche.Solution : dans les paramètres de l'instance AlloyDB, ajoutez 0.0.0.0/0 (pour les tests temporaires uniquement) ou votre adresse IP spécifique aux réseaux autorisés. |
Échec du handshake SSL/TLS | AlloyDB privilégie les connexions sécurisées. Si votre DATABASE_URL ne spécifie pas correctement le pilote (par exemple, en utilisant pg8000), l'établissement de la liaison peut échouer sans message d'erreur, ce qui vous laisse avec une erreur générique "Base de données non accessible". |
Échange entre le pool principal et le pool de lecture | Si vous copiez accidentellement l'adresse IP du pool de lecture au lieu de celle de l'instance principale, votre application fonctionnera pour la recherche d'articles, mais plantera avec une erreur "Lecture seule" lorsque vous tenterez de lister un nouvel article. Utilisez toujours l'adresse IP de l'instance principale pour les opérations en écriture. |
7. Vérifions le code
Le "profil de rencontre" de vos objets
Lorsqu'un utilisateur importe la photo d'un article, il ne devrait pas avoir à écrire une longue description. J'utilise Gemini 3 Flash pour "voir" l'article et rédiger la fiche à sa place.
Dans le backend, l'utilisateur fournit simplement un titre et une photo. Gemini s'occupe du reste :
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")
)
Embeddings en temps réel dans la base de données
L'une des fonctionnalités les plus intéressantes d'AlloyDB est la possibilité de générer des embeddings sans quitter le contexte SQL. Au lieu d'appeler un modèle d'embedding en Python et de renvoyer le vecteur à la base de données, je fais tout en une seule instruction INSERT à l'aide de la fonction 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
)
Cela permet de s'assurer que chaque élément est "recherchable" par sa signification dès qu'il est publié. Notez qu'il s'agit de la partie qui couvre la fonctionnalité "listing the product" (lister le produit) de l'application Neighbor Loop.
Recherche vectorielle avancée et filtrage intelligent avec Gemini 3.0
La recherche de mots clés standards est limitée. Si vous recherchez "quelque chose pour réparer ma chaise", une base de données traditionnelle peut ne rien renvoyer si le mot "chaise" ne figure pas dans un titre. Neighbor Loop résout ce problème grâce à la recherche vectorielle avancée d'AlloyDB AI.
En utilisant l'extension pgvector et le stockage optimisé d'AlloyDB, nous pouvons effectuer des recherches de similarité extrêmement rapides. Mais la vraie "magie" opère lorsque nous combinons la proximité vectorielle avec la logique basée sur les LLM.
AlloyDB AI nous permet d'appeler des modèles comme Gemini directement dans nos requêtes SQL. Cela signifie que nous pouvons effectuer une découverte sémantique qui inclut une "vérification de cohérence" basée sur la logique à l'aide de la fonction 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
Cette requête représente un changement architectural majeur : nous déplaçons la logique vers les données. Au lieu d'extraire des milliers de résultats dans le code de l'application pour les filtrer, Gemini 3 Flash effectue une "vérification de l'ambiance" à l'intérieur du moteur de base de données. Cela réduit la latence et les coûts de sortie, et garantit que les résultats ne sont pas seulement mathématiquement similaires, mais aussi contextuellement pertinents.
La boucle "Balayer pour trouver un partenaire"
L'UI est un jeu de cartes classique.
Balayez vers la gauche : supprimez.
Balayer vers la droite : c'est un match !
Lorsque vous balayez l'écran vers la droite, le backend enregistre l'interaction dans notre tableau des balayages et marque l'élément comme correspondant. L'interface utilisateur déclenche instantanément un pop-up affichant les coordonnées du fournisseur pour que vous puissiez organiser la collecte.
8. Déployons-la sur Cloud Run.
- Déployez-le sur Cloud Run en exécutant la commande suivante à partir du terminal Cloud Shell où le projet est cloné. Assurez-vous d'être dans le dossier racine du projet.
Exécutez la commande suivante dans votre terminal 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>>
Remplacez les valeurs des espaces réservés <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Une fois la commande terminée, une URL de service est générée. Copiez-le.
- Attribuez le rôle Client AlloyDB au compte de service Cloud Run.Cela permet à votre application sans serveur de se connecter de manière sécurisée à la base de données.
Exécutez la commande suivante dans votre terminal 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"
Utilisez maintenant l'URL du service (point de terminaison Cloud Run que vous avez copié précédemment) et testez l'application. Importez une photo de cet ancien outil électrique et laissez Gemini faire le reste !
Problèmes et dépannage
La boucle "Échec de la révision" | Si le déploiement se termine, mais que l'URL renvoie une erreur |
Rôle "fantôme" IAM | Même si vous êtes autorisé à déployer, le compte de service Cloud Run (généralement |
9. Dépannage de haut niveau
10. Démo
Vous devriez pouvoir utiliser votre point de terminaison pour les tests.
Toutefois, pour les besoins de la démonstration, vous pouvez utiliser cette commande pendant quelques jours :
11. Effectuer un nettoyage
Une fois cet atelier terminé, n'oubliez pas de supprimer le cluster et l'instance AlloyDB.
Il devrait nettoyer le cluster ainsi que ses instances.
12. Félicitations
Vous avez créé l'application Neighbor Loop pour des communautés durables avec Google Cloud. En déplaçant l'intégration et la logique d'IA Gemini 3 Flash dans AlloyDB, l'application est incroyablement rapide (en fonction des paramètres de déploiement) et le code est remarquablement propre. Nous ne stockons pas seulement des données, mais aussi des intentions.
La combinaison de la vitesse de Gemini 3 Flash et du traitement vectoriel optimisé d'AlloyDB représente une véritable avancée pour les plates-formes axées sur la communauté.