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 AlloyDB AI, passerai dall'archiviazione di base al regno dell'intelligenza in-database. Scoprirai come eseguire l'analisi multimodale degli elementi e l'individuazione semantica direttamente in SQL, eliminando la "tassa AI" di latenza e l'ingombro dell'architettura.
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 cluster e un'istanza AlloyDB progettati 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 app di incontri.
- 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:
- AlloyDB AI: 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. AlloyDB è un motore ad alte prestazioni; non si avvia se il "serbatoio" (fatturazione) è vuoto. |
Ritardo di propagazione dell'API | Hai fatto clic su "Abilita API", ma la riga di comando indica ancora |
Quota Quags | Se utilizzi un account di prova nuovo di zecca, potresti raggiungere una quota regionale per le istanze AlloyDB. Se |
Service Agent"Nascosto" | A volte all'agente di servizio AlloyDB non viene concesso automaticamente il ruolo |
3. Configurazione del database
In questo lab utilizzeremo AlloyDB come database per i dati di test. Utilizza i cluster per contenere tutte le risorse, come database e log. Ogni cluster ha un'istanza primaria che fornisce un punto di accesso ai dati. Le tabelle conterranno i dati effettivi.
Creiamo un cluster, un'istanza e una tabella AlloyDB 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, il cluster e i nomi delle istanze per iniziare.
- Prendi un caffè mentre scorrono i log e leggi qui come funziona dietro le quinte.
Aspetti da considerare e risoluzione dei problemi
Il problema della "pazienza" | I cluster di database sono un'infrastruttura pesante. Se aggiorni la pagina o termini la sessione Cloud Shell perché "sembra bloccata", potresti ritrovarti con un'istanza "fantasma" di cui è stato eseguito il provisioning parziale e impossibile da eliminare senza un intervento manuale. |
Regione non corrispondente | Se hai abilitato le API in |
Cluster di zombie | Se in precedenza hai utilizzato lo stesso nome per un cluster e non lo hai eliminato, lo script potrebbe indicare che il nome del cluster esiste già. I nomi dei cluster devono essere univoci all'interno di un progetto. |
Timeout di Cloud Shell | Se la pausa caffè dura 30 minuti, Cloud Shell potrebbe entrare in modalità di sospensione e disconnettere il processo |
4. Provisioning dello schema
Una volta che il cluster e l'istanza AlloyDB sono in esecuzione, vai all'editor SQL di AlloyDB Studio per attivare le estensioni AI e eseguire il provisioning dello schema.
Potrebbe essere necessario attendere il completamento della creazione dell'istanza. Una volta creato, accedi ad AlloyDB utilizzando le credenziali che hai creato durante la creazione del cluster. Utilizza i seguenti dati per l'autenticazione a PostgreSQL:
- Nome utente : "
postgres" - Database : "
postgres" - Password : "
alloydb" (o qualsiasi altra password impostata al momento della creazione)
Una volta eseguita l'autenticazione in AlloyDB 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 AlloyDB nelle finestre dell'editor, utilizzando le opzioni Esegui, Formatta e Cancella in base alle esigenze.
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 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 colonna item_vector consentirà l'archiviazione dei valori del vettore del testo.
Concedi autorizzazione
Esegui l'istruzione riportata di seguito per concedere l'esecuzione della funzione "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Concedi il ruolo Utente Vertex AI al service account AlloyDB
Dalla console Google Cloud IAM, concedi al service account AlloyDB (simile a service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.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:
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"
Registra il modello Gemini 3 Flash in AlloyDB
Esegui la seguente istruzione SQL dall'editor di query 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.
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 di |
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 |
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 il 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 ad AlloyDB e i ruoli Storage necessari per gestire gli oggetti in modo sicuro.
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 si arresterà in modo anomalo quando un utente tenta di elencare un nuovo elemento perché non dispone dell'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 questo comando dal terminale Cloud Shell (nella directory principale o da dove vuoi creare il progetto):
git clone https://github.com/AbiramiSukumaran/neighbor-loop
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 |
L'annullamento del "Timeout della connessione" | Hai utilizzato l'indirizzo IP privato nel file .env, ma stai tentando di connetterti dall'esterno del VPC (ad esempio dalla tua macchina locale). Gli IP privati sono raggiungibili solo dall'interno della stessa rete Google Cloud. Passa all'IP pubblico. |
Il presupposto della porta 5432 | Anche se 5432 è la porta PostgreSQL standard, a volte AlloyDB richiede configurazioni di porta specifiche se utilizzi un proxy di autenticazione. Per questo lab, assicurati di utilizzare :5432 alla fine della stringa host. |
Il gatekeeper "Reti autorizzate" | Anche se hai l'IP pubblico, AlloyDB "Rifiuta connessione" a meno che tu non abbia inserito l'indirizzo IP della macchina che esegue il codice nella lista consentita.Correzione: nelle impostazioni dell'istanza AlloyDB, aggiungi 0.0.0.0/0 (solo per test temporanei) o il tuo IP specifico alle reti autorizzate. |
Handshake SSL/TLS non riuscito | AlloyDB preferisce le connessioni sicure. Se DATABASE_URL non specifica correttamente il driver (ad esempio, se utilizza pg8000), l'handshake potrebbe non riuscire in modo invisibile, lasciandoti con un errore generico "Database non raggiungibile". |
Scambio tra pool primario e pool di lettura | Se copi per errore l'indirizzo IP del pool di lettura anziché quello dell'istanza principale, la tua app funzionerà per la ricerca di elementi, ma si arresterà in modo anomalo con un errore "Sola lettura" quando provi a elencare un nuovo elemento. Utilizza sempre l'IP dell'istanza principale per le scritture. |
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 AlloyDB è la possibilità di generare incorporamenti 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 AlloyDB AI.
Utilizzando l'estensione pgvector e l'archiviazione ottimizzata di AlloyDB, possiamo eseguire ricerche di similarità estremamente rapide. Ma la vera "magia" si verifica quando combiniamo la prossimità vettoriale con la logica basata su LLM.
AlloyDB AI ci consente di chiamare modelli come Gemini direttamente all'interno delle nostre query SQL. Ciò significa che possiamo eseguire una scoperta semantica che includa un "controllo di coerenza" basato sulla logica utilizzando la funzione 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
Questa query rappresenta un importante cambiamento architetturale: stiamo spostando la logica sui dati. Anziché inserire 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 riduce la latenza, si abbassano i costi di 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 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>>
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.
- Concedi il ruolo Client AlloyDB al service account Cloud Run.In questo modo, la tua applicazione serverless può eseguire il tunneling in modo sicuro nel database.
Esegui questo comando nel terminale 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"
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 viene completato, ma l'URL restituisce un errore |
Il ruolo "ombra" IAM | Anche se tu disponi dell'autorizzazione per il deployment, il service account Cloud Run (di solito |
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 il cluster e l'istanza AlloyDB.
Il cluster e le relative istanze verranno puliti.
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 AlloyDB, l'app è incredibilmente veloce (a seconda delle impostazioni di deployment) e il codice è straordinariamente pulito. Non memorizziamo solo dati, ma anche intenzioni.
La combinazione della velocità di Gemini 3 Flash e dell'elaborazione vettoriale ottimizzata di AlloyDB rappresenta davvero la nuova frontiera per le piattaforme basate sulla community.