1. Descripción general
En este codelab, compilarás Neighbor Loop, una app sostenible para compartir excedentes que trata la inteligencia como un ciudadano de primera clase de la capa de datos.
Con la integración de Gemini 3.0 Flash y la integración de AA de Cloud SQL, pasarás del almacenamiento básico al ámbito de la inteligencia en la base de datos. Aprenderás a realizar análisis de elementos multimodales y descubrimiento semántico directamente en SQL.
Qué compilarás
Una aplicación web de alto rendimiento para compartir excedentes de la comunidad con la función "deslizar para encontrar coincidencias".
Qué aprenderás
- Aprovisionamiento con un solo clic: Cómo configurar una instancia y una base de datos de Cloud SQL diseñadas para cargas de trabajo de IA
- Embeddings en la base de datos: Genera vectores de text-embedding-005 directamente dentro de las instrucciones INSERT.
- Razonamiento multimodal: Uso de Gemini 3.0 Flash para "ver" elementos y generar automáticamente biografías ingeniosas al estilo de las de citas
- Descubrimiento semántico: Realiza "verificaciones de ambiente" basadas en la lógica dentro de las consultas en SQL con la función ai.if() para filtrar los resultados según el contexto, no solo las matemáticas.
La arquitectura
Neighbor Loop evita los cuellos de botella tradicionales de la capa de aplicación. En lugar de extraer los datos para procesarlos, usamos lo siguiente:
- Integración de Cloud SQL y AA: Para generar y almacenar vectores en tiempo real.
- Google Cloud Storage: Para almacenar imágenes
- Gemini 3.0 Flash: Para realizar razonamientos en menos de un segundo sobre datos de imágenes y texto directamente a través de SQL
- Cloud Run: Para alojar un backend de Flask liviano de un solo archivo
Requisitos
2. Antes de comenzar
Crea un proyecto
- En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
- Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.
- Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
- Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto con el siguiente comando:
gcloud auth list
- En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
- Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>
- Habilita las APIs necesarias: Sigue el vínculo y habilita las APIs.
Como alternativa, puedes usar el comando de gcloud para esto. Consulta la documentación para ver los comandos y el uso de gcloud.
Problemas potenciales y solución de problemas
El "Proyecto Fantasma" : Síndrome | Ejecutaste |
La barricada de facturación | Habilitaste el proyecto, pero olvidaste la cuenta de facturación. Cloud SQL no se iniciará si la facturación está vacía. |
Retraso de la propagación de la API | Hiciste clic en "Habilitar APIs", pero la línea de comandos aún dice |
3. Configuración de la base de datos
En este lab, usaremos Cloud SQL para PostgreSQL como la base de datos de los datos de prueba.
Creemos una instancia de Cloud SQL en la que se cargará el conjunto de datos de prueba.
- Haz clic en el botón o copia el siguiente vínculo en el navegador en el que accediste como usuario a la consola de Google Cloud.
- Una vez que se complete este paso, el repo se clonará en tu editor local de Cloud Shell y podrás ejecutar el siguiente comando desde la carpeta del proyecto (es importante que te asegures de estar en el directorio del proyecto):
sh run.sh
- Ahora usa la IU (haz clic en el vínculo de la terminal o en el vínculo "preview on web" de la terminal).
- Ingresa los detalles del ID del proyecto y el nombre de la instancia para comenzar.
- Ve a tomar un café mientras se desplazan los registros. Aquí puedes leer cómo se hace esto en segundo plano.
Problemas potenciales y solución de problemas
Región no coincidente | Si habilitaste tus APIs en |
Tiempo de espera de Cloud Shell | Si tu descanso para tomar café dura 30 minutos, es posible que Cloud Shell entre en modo de suspensión y desconecte el proceso |
4. Aprovisionamiento de esquemas
Una vez que tu instancia de Cloud SQL esté en funcionamiento, dirígete al editor de SQL de Cloud SQL Studio para habilitar las extensiones de IA y aprovisionar el esquema.
Es posible que debas esperar a que termine de crearse la instancia. Una vez que lo hagas, accede a la instancia de Cloud SQL con las credenciales que creaste cuando la creaste. Usa los siguientes datos para autenticarte en PostgreSQL:
- Nombre de usuario : "
postgres" - Base de datos : "
postgres" - Contraseña: “
cloudsql” (o la que hayas configurado en el momento de la creación)
Una vez que te autentiques correctamente en Cloud SQL Studio, ingresa los comandos SQL en el editor. Puedes agregar varias ventanas del editor con el signo más que se encuentra a la derecha de la última ventana.
Ingresarás comandos para Cloud SQL en ventanas del editor, y usarás las opciones Ejecutar, Formato y Borrar según sea necesario.
Habilitar extensiones
Para compilar esta app, usaremos las extensiones pgvector y google_ml_integration. La extensión pgvector te permite almacenar y buscar embeddings de vectores. La extensión google_ml_integration proporciona funciones que usas para acceder a los extremos de predicción de Vertex AI y obtener predicciones en SQL. Habilita estas extensiones ejecutando los siguientes DDL:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Crea una tabla
Puedes crear una tabla con la siguiente instrucción DDL en 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 columna item_vector permitirá el almacenamiento de los valores del vector del texto.
Otorgar permiso
Ejecuta la siguiente instrucción para otorgar permiso de ejecución en la función "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Habilitar la integración del AA
Para aprovechar las funciones de aprendizaje automático directamente en tu base de datos, debes habilitar la marca de integración de AA.
Puedes ejecutar el siguiente comando desde la terminal de 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
Otorga el ROL de usuario de Vertex AI a la cuenta de servicio de Cloud SQL
En la consola de IAM de Google Cloud, otorga a la cuenta de servicio de Cloud SQL (que se ve así: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) acceso al rol "Usuario de Vertex AI". PROJECT_NUMBER tendrá tu número de proyecto.
Como alternativa, puedes ejecutar el siguiente comando desde la terminal de 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 el modelo Gemini 3 Flash en Cloud SQL
Ejecuta la siguiente instrucción de SQL desde el editor de consultas de 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.
Problemas potenciales y solución de problemas
El bucle de "amnesia de contraseña" | Si usaste la configuración "Con un clic" y no recuerdas tu contraseña, ve a la página de información básica de la instancia en la consola y haz clic en "Editar" para restablecer la contraseña de |
El error "No se encontró la extensión" | Si |
La brecha de propagación de IAM | Ejecutaste el comando de IAM |
Vector Dimension Mismatch | La tabla |
Error de escritura en el ID del proyecto | En la llamada |
La integración en Vertex AI está inhabilitada | Ejecuta |
5. Almacenamiento de imágenes (Google Cloud Storage)
Para almacenar las fotos de nuestros artículos excedentes, usamos un bucket de GCS. Para los fines de esta app de demostración, queremos que las imágenes sean de acceso público para que se rendericen de inmediato en nuestras tarjetas deslizables.
- Crea un bucket: Crea un bucket nuevo en tu proyecto de GCP (p.ej., neighborloop-images), de preferencia en la misma región que tu base de datos y tu aplicación.
- Configura el acceso público: * Navega a la pestaña Permisos del bucket.
- Agrega el principal allUsers.
- Asigna el rol Visualizador de objetos de Storage (para que todos puedan ver las fotos) y el rol Creador de objetos de Storage (para fines de carga de demostración).
Alternativa (cuenta de servicio): Si prefieres no usar el acceso público, asegúrate de que la cuenta de servicio de tu aplicación tenga acceso completo a Cloud SQL y los roles de Storage necesarios para administrar objetos de forma segura.
Si deseas ejecutar el comando y otorgar acceso público Ejecuta los siguientes comandos en la terminal de Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Problemas potenciales y solución de problemas
The Region Drag | Si tu base de datos está en |
Unicidad del nombre del bucket | Los nombres de los buckets son un espacio de nombres global. Si intentas nombrar tu bucket |
Confusión entre "Creador" y "Visualizador" | Confusión entre "Creador" y "Visualizador": Si solo agregas "Visualizador", tu app fallará cuando un usuario intente publicar un elemento nuevo porque no tiene permiso para escribir el archivo. Necesitas ambos para esta configuración de demostración específica. |
6. Creemos la aplicación
Clona este repo en tu proyecto y analicémoslo.
- Para clonar este proyecto, desde la terminal de Cloud Shell (en el directorio raíz o desde donde quieras crear este proyecto), ejecuta los siguientes comandos uno por uno:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Esto debería crear el proyecto, y puedes verificarlo en el editor de Cloud Shell.
- Cómo obtener tu clave de API de Gemini
- Visita Google AI Studio: Ve a aistudio.google.com.
- Accede con la misma Cuenta de Google que usas para tu proyecto de Google Cloud.
- Crea una clave de API:
- En la barra lateral izquierda, haz clic en "Obtener clave de API".
- Haz clic en el botón "Crear clave de API en un proyecto nuevo".
- Copia la clave: Una vez que se genere la clave, haz clic en el ícono de copiar.
- Ahora, configura las variables de entorno en el archivo .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>>
Reemplaza los valores de los marcadores de posición <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>..
Problemas potenciales y solución de problemas
Confusión entre varias cuentas | Si accediste a varias Cuentas de Google (personales y de trabajo), es posible que AI Studio use la cuenta incorrecta de forma predeterminada. Verifica el avatar en la esquina superior derecha para asegurarte de que coincida con la cuenta de tu proyecto de GCP. |
Se alcanzó la cuota del "nivel gratuito" | Si usas el nivel sin cargo, existen límites de frecuencia (RPM: solicitudes por minuto). Si "deslizas" demasiado rápido en Neighbor Loop, es posible que recibas un error |
Seguridad de claves expuestas | Si accidentalmente |
7. Verifiquemos el código
El "Perfil de citas" de tu contenido
Cuando un usuario sube una foto de un artículo, no debería tener que escribir una descripción larga. Uso Gemini 3 Flash para "ver" el artículo y escribir la ficha por ellos.
En el backend, el usuario solo proporciona un título y una foto. Gemini se encarga 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")
)
Incorporaciones en la base de datos en tiempo real
Una de las funciones más interesantes de Cloud SQL es la capacidad de generar embeddings sin salir del contexto de SQL. En lugar de llamar a un modelo de incorporación en Python y enviar el vector de vuelta a la BD, lo hago todo en una sola sentencia INSERT con la función 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
)
Esto garantiza que cada elemento se pueda "buscar" por su significado en el momento en que se publica. Ten en cuenta que esta es la parte que abarca la función "publicar el producto" de la app de Neighbor Loop.
Búsqueda de vectores avanzada y filtrado inteligente con Gemini 3.0
La búsqueda de palabras clave estándar es limitada. Si buscas "algo para arreglar mi silla", una base de datos tradicional podría no mostrar ningún resultado si la palabra "silla" no está en un título. Neighbor Loop resuelve este problema con la búsqueda de vectores avanzada de la IA de Cloud SQL.
Con la extensión pgvector y el almacenamiento optimizado de Cloud SQL, podemos realizar búsquedas de similitud extremadamente rápidas. Pero la verdadera "magia" ocurre cuando combinamos la proximidad de vectores con la lógica basada en 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
Esta consulta representa un cambio arquitectónico importante: trasladamos la lógica a los datos. En lugar de extraer miles de resultados en el código de la aplicación para filtrarlos, Gemini 3 Flash realiza una "verificación de ambiente" dentro del motor de la base de datos. Esto reduce la latencia, disminuye los costos de salida y garantiza que los resultados no solo sean similares desde el punto de vista matemático, sino también pertinentes en el contexto.
El bucle "Desliza para encontrar pareja"
La IU es un mazo de cartas clásico.
Deslizar hacia la izquierda: Descartar.
Desliza hacia la derecha: ¡Es un match!
Cuando deslizas el dedo hacia la derecha, el backend registra la interacción en nuestra tabla de deslizamientos y marca el elemento como coincidente. El frontend activa de inmediato una ventana modal que muestra la información de contacto del proveedor para que puedas coordinar la recolección.
8. Implementémosla en Cloud Run
- Para implementarlo en Cloud Run, ejecuta el siguiente comando desde la terminal de Cloud Shell en la que se clonó el proyecto y asegúrate de estar dentro de la carpeta raíz del proyecto.
Ejecuta este comando en tu terminal de 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>>
Reemplaza los valores de los marcadores de posición <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Una vez que finalice el comando, se generará una URL de servicio. Cópiala.
Ahora, usa la URL del servicio (el extremo de Cloud Run que copiaste antes) y prueba la app. Sube una foto de esa herramienta eléctrica antigua y deja que Gemini haga el resto.
Problemas potenciales y solución de problemas
El bucle de "Revisión fallida" | Si la implementación finaliza, pero la URL muestra un |
9. Solución de problemas de alto nivel
10. Demostración
Deberías poder usar tu extremo para las pruebas.
Sin embargo, para fines de demostración durante unos días, puedes probar lo siguiente:
11. Limpia
Cuando termines este lab, no olvides borrar la instancia de Cloud SQL.
12. Felicitaciones
Compilaste correctamente la app de Neighbor Loop para comunidades sostenibles con Google Cloud. Al trasladar la lógica de la IA de Gemini 3 Flash y la incorporación a Cloud SQL, la app es increíblemente rápida (sujeta a la configuración de implementación) y el código es notablemente limpio. No solo almacenamos datos, sino también intenciones.
La combinación de la velocidad de Gemini 3 Flash y el procesamiento de vectores optimizado de Cloud SQL es realmente la próxima frontera para las plataformas impulsadas por la comunidad.