Compila e implementa en Google Cloud con Antigravity

1. Introducción

En este codelab, aprenderás a usar Google Antigravity para diseñar, compilar e implementar una aplicación sin servidores en Google Cloud. Compilaremos una canalización de documentos sin servidores y basada en eventos que transfiera archivos de Google Cloud Storage (GCS), los procese con Cloud Run y Gemini, y transmita sus metadatos a BigQuery.

Qué aprenderás

• Cómo usar Antigravity para la planificación y el diseño arquitectónicos
• Genera infraestructura como código (secuencias de comandos de shell) con un agente de IA.
• Compila e implementa un servicio de Cloud Run basado en Python.
• Integra Gemini en Vertex AI para el análisis multimodal de documentos.
• Verifica la canalización de extremo a extremo con el artefacto de Walkthrough de Antigravity.

Requisitos

• Google Antigravity instalado
• Un proyecto de Google Cloud con facturación habilitada
• gcloud CLI instalada y autenticada

2. Descripción general de la app

Antes de comenzar a diseñar e implementar la aplicación con Antigravity, primero describamos la aplicación que queremos crear.

Queremos crear una canalización de documentos sin servidores y basada en eventos que transfiera archivos de Google Cloud Storage (GCS), los procese con Cloud Run y Gemini, y transmita sus metadatos a BigQuery.

Un diagrama de arquitectura de alto nivel para esta aplicación podría verse de la siguiente manera:

No es necesario que sea preciso. Antigravity puede ayudarnos a definir los detalles de la arquitectura a medida que avanzamos. Sin embargo, es útil tener una idea de lo que quieres crear. Cuantos más detalles proporciones, mejores resultados obtendrás de Antigravity en términos de arquitectura y código.

3. Planifica la arquitectura

Ya podemos comenzar a planificar los detalles de la arquitectura con Antigravity.

Antigravity se destaca en la planificación de sistemas complejos. En lugar de escribir código de inmediato, podemos comenzar por definir la arquitectura de alto nivel y usar una de las funciones para ayudar a Antigravity a evaluar nuestra solicitud, hacernos preguntas adicionales y, luego, continuar con su planificación e implementación.

Suponiendo que ya iniciaste Antigravity, crearemos un proyecto nuevo para este codelab.

Haz clic en el ícono de proyecto nuevo junto al lab de Projects y, luego, en New Project, como se muestra a continuación:

Aparecerá la opción Add Folder, como se muestra a continuación:

Haz clic en el botón Agregar carpeta para agregar una carpeta a tu proyecto. En mi máquina, creé una carpeta google-cloud-serverless-app y la agregué a este proyecto.

Se abrirá una conversación en el espacio de trabajo de google-cloud-serverless-app.

Haz clic en el ícono de configuración principal ⚙️ en la parte inferior izquierda de la pantalla y ve a Configuración específica del proyecto. Configura Agent Settings / Security Present en Default y Agent Behaviour / Artifact Review Policy en Always Ask, como se muestra a continuación:

Esto garantizará que, en cada paso, puedas revisar y aprobar el plan antes de que el agente lo ejecute.

Instrucción

Ahora, ya podemos proporcionar nuestra primera instrucción a Antigravity. Usaremos un comando de barra /grill-me para evaluar nuestra solicitud.

Escribe /grill-me, ingresa la siguiente instrucción y haz clic en el botón Enviar:

/grill-me 

I want to build a serverless event-driven document processing pipeline on Google Cloud.
Architecture:
- Ingestion: Users upload files to a Cloud Storage bucket.
- Trigger: File uploads trigger a Pub/Sub message.
- Processor: A Python-based Cloud Run service receives the message, processes the file (simulated OCR), and extracts metadata.
- Storage: Stream the metadata (filename, date, tags, word_count) into a BigQuery dataset. 

El comando /grill-me hace varias preguntas adicionales que puedes intentar responder lo mejor que puedas. También sugiere Respuestas recomendadas, que puedes usar si lo deseas.

A continuación, se muestra una ejecución de muestra de mi comando /grill-me:

How would you provision and manage the Google Cloud infrastructure resources (Cloud Storage buckets, Pub/Sub topics, BigQuery datasets, Cloud Run service)?
gcloud CLI Setup Script - Shell scripts running gcloud CLI commands to create resources step-by-step

How should the Cloud Storage upload events trigger and reach your Python Cloud Run service?
(Recommended) Native Cloud Storage Pub/Sub Notifications + Pub/Sub Push subscription to Cloud Run (direct, lightweight, standard event-driven approach)

Which Python web framework would you prefer for the Cloud Run processing service?
Flask (with Gunicorn) - Standard, lightweight, and very common for simple Cloud Run services

How should the OCR and metadata extraction logic be implemented in the Cloud Run service?
(Recommended) Full local simulation - If it's a .txt file, read the contents, count words, and extract tags. For other files, generate mock OCR metadata and simulated word count. No external API calls.

Which BigQuery insertion method should the Cloud Run service use to store metadata?
(Recommended) BigQuery table.insert_rows() (Legacy Streaming API) - Extremely simple to code, clean error handling, perfect for simulation and low-to-medium volumes.

How should security/authentication be configured for the Cloud Run service?
Unauthenticated Cloud Run - Allow public requests to the Cloud Run service URL (simpler setup, but insecure for production).


What schema would you like to define for the BigQuery metadata table?
(Recommended) Extended Schema - Include filename, bucket, size, content_type, word_count, tags (as a REPEATED STRING array), ocr_text_preview, and process_timestamp.

How should the Cloud Run service handle processing failures (e.g., file not found, BigQuery write error)?
(Recommended) Fail-Fast with Retry - Log error to standard output (Cloud Logging) and return HTTP 500 to Pub/Sub, so that Pub/Sub automatically retries the message delivery.

What testing tools should we generate to verify the pipeline's functionality?
(Recommended) Both - Include a local test script (sending mock Pub/Sub POST requests to the local Flask server) and a Cloud-integrated test script (uploading a real file to GCS and verifying BigQuery).

Ten en cuenta que le pedí a Antigravity que hiciera lo siguiente:

• Una secuencia de comandos simple de la CLI de gcloud para aprovisionar recursos
• Notificaciones nativas de Cloud Storage Pub/Sub y suscripción de envío de Pub/Sub a Cloud Run
• Usa Flask (con Gunicorn) para el framework
• Solo usa la simulación local con un archivo de texto para los datos en lugar de los datos de OCR en vivo.
• Usa BigQuery table.insert_rows() para insertar filas en BigQuery
• Implementación de Cloud Run no autenticada

y otras opciones recomendadas.

Plan de implementación y lista de tareas

Antigravity comenzará a trabajar y generará un Plan de implementación. Para que lo revises, te mostrará un mensaje similar al siguiente:

Puedes hacer clic en el botón de activación del panel auxiliar en la ventana superior derecha y ver los artefactos generados, que, en este punto, son solo el Plan de implementación.

En este plan, se describe lo siguiente:

• Infraestructura: Es el bucket de GCS, el tema de Pub/Sub y el conjunto de datos de BigQuery.
• Procesador: App de Python/Flask, Dockerfile, requisitos.
• Integración: Notificaciones de GCS → Pub/Sub → Cloud Run.

Deberías ver un resultado similar al siguiente. A continuación, se muestra una lista parcial del plan de implementación en nuestra máquina:

Event-Driven Document Processing Pipeline Implementation Plan
This implementation plan describes the components and setup scripts required to build a serverless event-driven document processing pipeline on Google Cloud.

User Review Required

Please review the proposed architecture, components, and default configuration. If you agree, please approve the plan so we can proceed with creating the files and implementation.

IMPORTANT

Security Notice: As requested, the Cloud Run service is configured to allow unauthenticated invocations (--allow-unauthenticated) for simpler testing and development.

Error Handling: The service returns an HTTP 500 error code for failures to trigger Pub/Sub retries.

GCP Configuration: The provisioning scripts will use standard environment variables (e.g., GCP_PROJECT, GCP_REGION) that default to the active configuration of your local gcloud CLI.

Proposed Components and Files

The project will be organized as follows:

google-cloud-serverless-app/
├── src/
│   ├── __init__.py
│   ├── app.py              # Flask app entrypoint and routes
│   ├── processor.py        # Simulated OCR and metadata extraction engine
│   ├── gcs_helper.py       # Helper functions to read files from Cloud Storage
│   └── bq_helper.py        # Helper functions to write metadata to BigQuery
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker configuration for Cloud Run
├── deploy.sh               # gcloud CLI provisioning and deployment script
├── test_local.sh           # Script to test the Flask app locally with mock Pub/Sub events
├── test_cloud.sh           # Script to upload a real file to GCS and query BigQuery
└── README.md               # Setup and execution guide

Léelo con atención. Esta es tu oportunidad para brindar comentarios sobre la implementación. Puedes hacer clic en cualquier parte del plan de implementación y agregar comentarios. Una vez que agregues algunos comentarios, asegúrate de enviar para su revisión los cambios que quieras ver, especialmente en relación con los nombres, el ID del proyecto de Google Cloud, la región, etcétera.

Una vez que todo se vea bien, haz clic en el botón Proceed para darle permiso al agente para que continúe con el plan de implementación.

Nota: A veces, es posible que no veas el botón Continuar y que Antigravity continúe sin esperar tu entrada.

Ahora, se procede a crear otro artefacto Plan de tareas, que contiene un conjunto de tareas creadas por Antigravity. El agente los revisará uno por uno y los ejecutará. A continuación, se muestra una lista de tareas de ejemplo:

4. Genera la aplicación

Una vez que se aprueba el plan, Antigravity comienza a generar los archivos necesarios para la aplicación, desde las secuencias de comandos de aprovisionamiento hasta el código de la aplicación.

Nota: Se te solicitarán varios comandos de terminal (gcloud, secuencias de comandos de shell, etcétera) que el agente deberá usar para comprender el entorno y, luego, generar las secuencias de comandos según corresponda. Haz clic en el botón Submit para que el agente avance. Si bien este lab abarca los nombres de archivos específicos que se generaron, es posible que Antigravity genere nombres de archivos diferentes, aunque la intención y el contenido de los archivos deberían ser similares.

Antigravity creará una carpeta y comenzará a crear los archivos necesarios para el proyecto. Si revisas los artefactos, notarás que se generan varios archivos (código fuente, archivos de secuencias de comandos, etcétera).

Una vez que complete su trabajo, lo mencionará y creará un documento de recorrido que puedes consultar. En él, se menciona el siguiente paso para el usuario. A continuación, se muestra un ejemplo:

• Implementa la canalización: Asegúrate de haber accedido a tu CLI de GCP y de haber configurado tu proyecto de destino. Luego, ejecuta: ./ deploy.sh
• Ejecutar prueba de extremo a extremo: Ejecuta la secuencia de comandos de prueba de integración en la nube para verificar que la carga de un archivo active el procesamiento de Cloud Run y transmita metadatos a BigQuery:./test_cloud.sh
• Limpieza: Cuando termines de realizar las pruebas, consulta los comandos de limpieza de README.md para quitar los recursos creados y evitar que se generen cargos.

Verás que se genera un archivo de secuencia de comandos de shell deploy.sh o con un nombre similar, que automatiza la creación de recursos. Se encarga de lo siguiente:

1. Se habilitaron las APIs (run, pubsub, bigquery, storage).
2. Crear el bucket de Google Cloud Storage (document-processing-ingest-{project-id})
3. Crear el conjunto de datos y la tabla de BigQuery (document_processing.processed_metadata)
4. Configurar temas y notificaciones de Pub/Sub

5. Implemente la aplicación

Implementemos la aplicación como se mencionó con el comando ./ deploy.sh. Podemos pedirle a Antigravity que ejecute esto por nosotros, pero, antes de hacerlo, asegúrate de que la gcloud CLI esté presente y configurada para el proyecto de Google Cloud.

Podemos darle la instrucción a Antigravity "Ejecuta deploy.sh por mí". Se te pedirá permiso. Adelante, dáselo.

Inicia el proceso como una tarea en segundo plano, como se explica en el siguiente mensaje:

Ejecuté ./deploy.sh en segundo plano para iniciar el proceso de implementación. Supervisaré los registros de ejecución y te avisaré cuando finalice la implementación.

6. Verifica la aplicación

Una vez que se implementa la canalización, Antigravity verifica que la aplicación realmente funcione. Nos pregunta si puede ejecutar el archivo test_cloud.sh. Podemos darle permiso.

Finalmente, nos indica lo siguiente:

I have successfully run both ./deploy.sh and ./test_cloud.sh.
The pipeline is fully deployed to your GCP project PROJECT_ID and working end-to-end. 

Please refer to the walkthrough.md for full verification details and the query output from BigQuery showing the successfully processed document metadata.

Podemos abrir el artefacto de Walkthrough para ver los resultados:

Cloud Verification Results

The deployment and end-to-end cloud integration test (./test_cloud.sh) succeeded perfectly!

Resources Created:

GCS Bucket: gs://document-processing-ingest-gcp-experiments-349209

Pub/Sub Topic: document-uploads-topic

Pub/Sub Subscription: document-uploads-sub (pushing to Cloud Run)

Cloud Run Service: document-processor (URL: https://document-processor-ido3ocn3pq-uc.a.run.app)

BigQuery Dataset: document_processing

BigQuery Table: processed_metadata

Integration Test Run: A test file cloud_test_sample.txt was uploaded to the bucket. The pipeline processed the file and streamed the metadata record into BigQuery:

🔍 Querying BigQuery to verify metadata insertion...
<BIQUERY DATA HERE>

The pipeline successfully detected the hashtags #gcp and #serverless as tags, correctly counted the 47 words, generated the OCR preview, and wrote the entry to BigQuery under the schema.

Opcional: Verificación manual

Aunque Antigravity ya verificó la aplicación, también puedes verificar manualmente en la consola de Google Cloud que se hayan creado todos los recursos, si lo deseas, siguiendo estos pasos.

Cloud Storage

Objetivo: Verificar que el bucket exista y buscar archivos subidos

1. Navega a Cloud Storage > Buckets.
2. Ubica el bucket llamado document-processing-ingest-{project-id}.
3. Haz clic en el nombre del bucket para explorar los archivos.
4. Verifica que se muestren los archivos que subiste (p.ej.,cloud_test_sample.txt).

Pub/Sub

Objetivo: Confirma que el tema exista y tenga una suscripción de envío.

1. Navega a Pub/Sub > Temas.
2. Busca document-uploads-topic.
3. Haz clic en el ID del tema.
4. Desplázate hacia abajo hasta la pestaña Suscripciones.
5. Verifica que doc-uploads-sub aparezca con el tipo de entrega "Push".

Cloud Run

Objetivo: Comprobar el estado y los registros del servicio

1. Navega a Cloud Run.
2. Haz clic en el servicio document-processor.
3. Verifica lo que hiciste:
4. Estado: Marca de verificación verde que indica que el servicio está activo.
5. Registros: Haz clic en la pestaña Registros. Busca entradas como "Processing file: gs://…" y "Successfully inserted…".

BigQuery

Objetivo: Validar que los datos se almacenen correctamente.

1. Navega a BigQuery > SQL Workspace.
2. En el panel Explorador, expande tu proyecto > conjunto de datos document_processing.
3. Haz clic en la tabla processed_metadata.
4. Haz clic en la pestaña Query y recupera todas las filas de la tabla con la sentencia SELECT *.
5. Verifica que veas filas que contengan filename, process_timestamp, tags y word_count.

7. Explora la aplicación

En este punto, ya tienes la app básica aprovisionada y en ejecución. Antes de profundizar en la extensión de esta aplicación, tómate un momento para explorar el código. Puedes ver los artefactos y se deberían mostrar los archivos de código generados.

A continuación, se incluye un breve resumen de los archivos que puedes ver:

1. deploy.sh: Es la secuencia de comandos principal que aprovisiona todos los recursos de Google Cloud y habilita las APIs requeridas.
2. appy.py: Es el punto de entrada principal de la canalización. Esta app de Python crea un servidor web que recibe mensajes push de Pub/Sub, descarga el archivo de GCS, lo "procesa" (simula el OCR) y transmite los metadatos a BigQuery.
3. Dockerfile: Define cómo empaquetar la app en una imagen de contenedor.
4. requirements.txt: Enumera las dependencias de Python.

También es posible que veas otros archivos de texto y secuencias de comandos necesarios para las pruebas y la verificación.

8. Extiende la aplicación

Ahora que tienes una aplicación básica que funciona, puedes seguir iterando y extendiendo la aplicación. Estas son algunas ideas.

Agrega un frontend

Crea una interfaz web simple para ver los documentos procesados.

Prueba la siguiente instrucción: Create a simple Streamlit or Flask web application that connects to BigQuery. It should display a table of the processed documents (filename, upload_date, tags, word_count) and allow me to filter the results by tag

Integración con IA/AA reales

En lugar del procesamiento de OCR simulado, usa los modelos de Gemini para extraer, clasificar y traducir.

1. Reemplaza la lógica de OCR simulada. Envía la imagen o el PDF a Gemini para extraer texto y datos reales. Analiza el texto extraído para clasificar el tipo de documento (factura, contrato, currículum vitae) o extraer entidades (fechas, nombres, ubicaciones).
2. Detectar automáticamente el idioma del documento y traducirlo al inglés antes de almacenarlo También puedes usar cualquier otro idioma.

Mejora el almacenamiento y las estadísticas

Puedes configurar reglas de ciclo de vida en el bucket para trasladar archivos antiguos al almacenamiento "Coldline" o "Archive" y ahorrar costos.

Robustez y seguridad

Puedes hacer que la app sea más sólida y segura de las siguientes maneras:

1. Colas de mensajes no entregados (DLQ): Actualiza la suscripción a Pub/Sub para controlar las fallas. Si el servicio de Cloud Run no puede procesar un archivo 5 veces, envía el mensaje a un tema o bucket de "mensajes no entregados" independiente para que lo inspeccione un humano.
2. Secret Manager: Si tu app necesita claves de API o configuración sensible, almacénalas en Secret Manager y accede a ellas de forma segura desde Cloud Run en lugar de codificar cadenas de forma rígida.
3. Eventarc: Actualiza de Pub/Sub directo a Eventarc para obtener un enrutamiento de eventos más flexible, lo que te permite activar en función de registros de auditoría complejos o de otros eventos de servicios de GCP.

Por supuesto, puedes crear tus propias ideas y usar Antigravity para ayudarte a implementarlas.

9. Conclusión

Creaste correctamente una canalización de documentos escalable, sin servidores y potenciada por IA en minutos con Google Antigravity. Aprendiste todo esto:

• Planifica arquitecturas con IA.
• Dirige y administra Antigravity mientras genera la aplicación, desde la generación de código hasta la implementación y la validación.
• Verifica las implementaciones y la validación con los tutoriales.

Documentos de referencia

• Sitio oficial : https://antigravity.google/
• Documentación: https://antigravity.google/docs
• Casos de uso : https://antigravity.google/use-cases
• Descargar : https://antigravity.google/download