1. Panoramica
In questo codelab, creerai Neighbor Loop, un'app sostenibile per la condivisione delle eccedenze che considera l'intelligenza come un cittadino di prima classe del livello dati.
Integrando Gemini 3.0 Flash e l'integrazione ML di Cloud SQL, passerai dall'archiviazione di base al regno dell'intelligence in-database. Scoprirai come eseguire l'analisi multimodale degli elementi e il rilevamento semantico direttamente in SQL.
Cosa creerai
Un'applicazione web "scorri e abbina" ad alte prestazioni per la condivisione delle eccedenze della community.
Obiettivi didattici
- Provisioning con un clic: come configurare un'istanza Cloud SQL progettata per i carichi di lavoro di AI.
- Incorporamenti nel database: generazione di vettori text-embedding-005 direttamente all'interno delle istruzioni INSERT.
- Ragionamento multimodale: utilizza Gemini 3.0 Flash per "vedere" gli elementi e generare automaticamente biografie spiritose in stile dating.
- Rilevamento semantico: esecuzione di "vibe check" basati sulla logica all'interno delle query SQL utilizzando la funzione ai.if() per filtrare i risultati in base al contesto, non solo alla matematica.
L'architettura
Neighbor Loop aggira i colli di bottiglia tradizionali a livello di applicazione. Invece di estrarre i dati per elaborarli, utilizziamo:
- Integrazione di Cloud SQL e ML:per generare e archiviare i vettori in tempo reale.
- Google Cloud Storage:per archiviare le immagini
- Gemini 3.0 Flash:per eseguire ragionamenti in meno di un secondo su dati di immagini e testo direttamente tramite SQL.
- Cloud Run: per ospitare un backend Flask leggero e a file singolo.
Requisiti
2. Prima di iniziare
Crea un progetto
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.
- Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
- Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
- Abilita le API richieste: segui il link e abilita le API.
In alternativa, puoi utilizzare il comando gcloud. Consulta la documentazione per i comandi e l'utilizzo di gcloud.
Aspetti da considerare e risoluzione dei problemi
La sindrome del "progetto fantasma" | Hai eseguito |
La barriera di fatturazione | Hai attivato il progetto, ma hai dimenticato l'account di fatturazione. Cloud SQL non verrà avviato se la fatturazione è vuota. |
Ritardo di propagazione dell'API | Hai fatto clic su "Abilita API", ma la riga di comando indica ancora |
3. Configurazione del database
In questo lab utilizzeremo Cloud SQL per PostgreSQL come database per i dati di test.
Creiamo un'istanza Cloud SQL in cui verrà caricato il set di dati di test.
- Fai clic sul pulsante o copia il link riportato di seguito nel browser in cui hai eseguito l'accesso all'utente della console Google Cloud.
- Una volta completato questo passaggio, il repository verrà clonato nell'editor Cloud Shell locale e potrai eseguire il comando riportato di seguito dalla cartella del progetto (è importante assicurarsi di trovarsi nella directory del progetto):
sh run.sh
- Ora utilizza la UI (facendo clic sul link nel terminale o sul link "Anteprima sul web" nel terminale).
- Inserisci i tuoi dati per l'ID progetto e il nome dell'istanza per iniziare.
- Prendi un caffè mentre scorrono i log e leggi qui come funziona dietro le quinte.
Aspetti da considerare e risoluzione dei problemi
Regione non corrispondente | Se hai abilitato le API in |
Timeout di Cloud Shell | Se la pausa caffè dura 30 minuti, Cloud Shell potrebbe entrare in modalità sospensione e disconnettere il processo |
4. Provisioning dello schema
Una volta che l'istanza Cloud SQL è in esecuzione, vai all'editor SQL di Cloud SQL Studio per abilitare le estensioni AI e eseguire il provisioning dello schema.
Potrebbe essere necessario attendere il completamento della creazione dell'istanza. Una volta fatto, accedi all'istanza Cloud SQL utilizzando le credenziali che hai creato. Utilizza i seguenti dati per l'autenticazione a PostgreSQL:
- Nome utente : "
postgres" - Database : "
postgres" - Password : "
cloudsql" (o qualsiasi altra password impostata al momento della creazione)
Una volta eseguita l'autenticazione in Cloud SQL Studio, i comandi SQL vengono inseriti nell'editor. Puoi aggiungere più finestre dell'editor utilizzando il segno più a destra dell'ultima finestra.
Inserirai i comandi per Cloud SQL nelle finestre dell'editor, utilizzando le opzioni Esegui, Formatta e Cancella in base alle necessità.
Attivare le estensioni
Per creare questa app, utilizzeremo le estensioni pgvector e google_ml_integration. L'estensione pgvector consente di archiviare ed eseguire ricerche di vector embedding. L'estensione google_ml_integration fornisce funzioni che utilizzi per accedere agli endpoint di previsione Vertex AI per ottenere previsioni in SQL. Attiva queste estensioni eseguendo i seguenti DDL:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Creare una tabella
Puoi creare una tabella utilizzando l'istruzione DDL riportata di seguito in 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()
);
La colonna item_vector consentirà l'archiviazione dei valori vettoriali del testo.
Concedi autorizzazione
Esegui l'istruzione riportata di seguito per concedere l'esecuzione della funzione "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Attiva integrazione ML
Per sfruttare le funzionalità di machine learning direttamente nel database, devi attivare il flag di integrazione ML.
Puoi eseguire il comando riportato di seguito dal terminale 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
Concedi il ruolo Utente Vertex AI al service account Cloud SQL
Dalla console Google Cloud IAM, concedi all'account di servizio Cloud SQL (simile a service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) l'accesso al ruolo "Utente Vertex AI". PROJECT_NUMBER conterrà il numero del tuo progetto.
In alternativa, puoi eseguire il comando riportato di seguito dal terminale 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"
Registra il modello Gemini 3 Flash in Cloud SQL
Esegui la seguente istruzione SQL dall'editor di query 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.
Aspetti da considerare e risoluzione dei problemi
Il ciclo "Amnesia della password" | Se hai utilizzato la configurazione "One Click" e non ricordi la password, vai alla pagina delle informazioni di base dell'istanza nella console e fai clic su "Modifica" per reimpostare la password |
Errore "Estensione non trovata" | Se |
Il divario di propagazione IAM | Hai eseguito il comando IAM |
Mancata corrispondenza delle dimensioni del vettore | La tabella |
Errore di battitura nell'ID progetto | Nella chiamata |
L'integrazione di Vertex AI è disabilitata | Esegui |
5. Archiviazione immagini (Google Cloud Storage)
Per archiviare le foto dei nostri articoli in eccedenza, utilizziamo un bucket GCS. Ai fini di questa app demo, vogliamo che le immagini siano accessibili pubblicamente in modo che vengano visualizzate immediatamente nelle nostre schede di scorrimento.
- Crea un bucket: crea un nuovo bucket nel tuo progetto GCP (ad es. neighborloop-images), preferibilmente nella stessa regione del database e dell'applicazione.
- Configura l'accesso pubblico: * Vai alla scheda Autorizzazioni del bucket.
- Aggiungi l'entità allUsers.
- Assegna il ruolo Storage Object Viewer (in modo che tutti possano vedere le foto) e il ruolo Storage Object Creator (per scopi di caricamento della demo).
Alternativa (service account): se preferisci non utilizzare l'accesso pubblico, assicurati che al service account della tua applicazione sia concesso l'accesso completo a Cloud SQL e i ruoli Storage necessari per gestire gli oggetti in modo sicuro.
Se vuoi eseguire il comando e concedere l'accesso pubblico. Esegui i comandi riportati di seguito nel terminale Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Aspetti da considerare e risoluzione dei problemi
The Region Drag | Se il tuo database si trova in |
Unicità del nome del bucket | I nomi dei bucket sono uno spazio dei nomi globale. Se provi a chiamare il tuo bucket |
Confusione tra "Creator" e "Spettatore" | Confusione tra "Creatore" e "Visualizzatore": se aggiungi solo "Visualizzatore", la tua app andrà in crash quando un utente tenta di elencare un nuovo elemento perché non ha l'autorizzazione per scrivere il file. Per questa configurazione demo specifica, sono necessari entrambi. |
6. Creiamo l'applicazione
Clona questo repository nel tuo progetto e analizziamolo.
- Per clonare questo progetto, esegui i seguenti comandi uno alla volta dal terminale Cloud Shell (nella directory principale o da dove vuoi creare il progetto):
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
In questo modo dovrebbe essere creato il progetto, che puoi verificare nell'editor di Cloud Shell.
- Come ottenere la chiave API Gemini
- Visita Google AI Studio: vai su aistudio.google.com.
- Accedi: utilizza lo stesso Account Google che utilizzi per il tuo progetto Google Cloud.
- Crea chiave API:
- Nella barra laterale a sinistra, fai clic su "Ottieni chiave API".
- Fai clic sul pulsante "Crea chiave API nel nuovo progetto".
- Copia la chiave: una volta generata la chiave, fai clic sull'icona di copia.
- Ora imposta le variabili di ambiente nel file .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>>
Sostituisci i valori dei segnaposto <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Aspetti da considerare e risoluzione dei problemi
Confusione tra più account | Se hai eseguito l'accesso a più Account Google (personale e di lavoro), AI Studio potrebbe impostare come predefinito quello sbagliato. Controlla l'avatar nell'angolo in alto a destra per assicurarti che corrisponda al tuo account progetto Google Cloud. |
Superamento della quota del "livello senza costi" | Se utilizzi il livello senza costi, sono previsti limiti di frequenza (RPM - Richieste al minuto). Se scorri troppo velocemente in Neighbor Loop, potresti visualizzare l'errore |
Exposed Key Security | Se hai |
7. Controlliamo il codice
Il "Profilo di incontri" per le tue cose
Quando un utente carica la foto di un articolo, non deve scrivere una descrizione lunga. Utilizzo Gemini 3 Flash per "vedere" l'articolo e scrivere la scheda.
Nel backend, l'utente fornisce solo un titolo e una foto. Gemini si occupa del resto:
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")
)
Incorporamenti in tempo reale nel database
Una delle funzionalità più interessanti di Cloud SQL è la possibilità di generare embedding senza uscire dal contesto SQL. Anziché chiamare un modello di embedding in Python e inviare il vettore al database, faccio tutto in un'unica istruzione INSERT utilizzando la funzione 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
)
In questo modo, ogni elemento è "ricercabile" in base al suo significato nel momento in cui viene pubblicato. Tieni presente che questa parte riguarda la funzionalità "Elenca il prodotto" dell'app Neighbor Loop.
Ricerca vettoriale avanzata e filtri intelligenti con Gemini 3.0
La ricerca standard di parole chiave è limitata. Se cerchi "qualcosa per riparare la mia sedia", un database tradizionale potrebbe non restituire nulla se la parola "sedia" non è presente in un titolo. Neighbor Loop risolve questo problema con la ricerca vettoriale avanzata di Cloud SQL AI.
Utilizzando l'estensione pgvector e l'archiviazione ottimizzata di Cloud SQL, possiamo eseguire ricerche di somiglianza estremamente rapide. Ma la vera "magia" si verifica quando combiniamo la prossimità vettoriale con la logica basata su 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
Questa query rappresenta un importante cambiamento architetturale: stiamo spostando la logica sui dati. Anziché estrarre migliaia di risultati nel codice dell'applicazione per filtrarli, Gemini 3 Flash esegue un "vibe check" all'interno del motore del database. In questo modo si riducono la latenza e i costi di traffico in uscita e si garantisce che i risultati non siano solo simili dal punto di vista matematico, ma anche pertinenti dal punto di vista contestuale.
Il loop "Scorri per trovare una corrispondenza"
L'interfaccia utente è un classico mazzo di carte.
Scorri verso sinistra: scarta.
Scorri verso destra: è una corrispondenza.
Quando scorri verso destra, il backend registra l'interazione nella nostra tabella degli swipe e contrassegna l'elemento come abbinato. Il frontend attiva immediatamente una finestra modale che mostra i dati di contatto del fornitore, in modo che tu possa organizzare il ritiro.
8. Eseguiamo il deployment in Cloud Run
- Esegui il deployment su Cloud Run eseguendo questo comando dal terminale Cloud Shell in cui il progetto è clonato e assicurati di trovarti nella cartella principale del progetto.
Esegui questo comando nel terminale 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>>
Sostituisci i valori dei segnaposto <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Al termine del comando, verrà visualizzato un URL del servizio. Copialo.
Ora utilizza l'URL del servizio (l'endpoint Cloud Run che hai copiato in precedenza) e testa l'app. Carica una foto del vecchio utensile elettrico e lascia che Gemini faccia il resto.
Aspetti da considerare e risoluzione dei problemi
Il ciclo "Revisione non riuscita" | Se il deployment termina, ma l'URL restituisce un errore |
9. Risoluzione dei problemi di alto livello
10. Demo
Dovresti essere in grado di utilizzare l'endpoint per i test.
Tuttavia, a scopo dimostrativo per alcuni giorni, puoi provare questo:
11. Esegui la pulizia
Una volta completato questo lab, non dimenticare di eliminare l'istanza Cloud SQL.
12. Complimenti
Hai creato correttamente l'app Neighbor Loop per comunità sostenibili con Google Cloud. Spostando la logica di incorporamento e dell'AI Gemini 3 Flash in Cloud SQL, l'app è incredibilmente veloce (a seconda delle impostazioni di deployment) e il codice è notevolmente pulito. Non memorizziamo solo dati, ma anche intenzioni.
La combinazione della velocità di Gemini 3 Flash e dell'elaborazione vettoriale ottimizzata di Cloud SQL rappresenta davvero la prossima frontiera per le piattaforme basate sulla community.