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 desde 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 de la arquitectura
- Generar infraestructura como código (secuencias de comandos de shell) con un agente de IA
- Compilar e implementar un servicio de Cloud Run basado en Python
- Integrar Gemini en Vertex AI para el análisis multimodal de documentos
- Verificar la canalización de extremo a extremo con el artefacto 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 compilar.
Queremos compilar una canalización de documentos sin servidores y basada en eventos que transfiera archivos desde 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 determinar los detalles de la arquitectura a medida que avanzamos. Sin embargo, es útil tener una idea de lo que quieres compilar. Cuanto más detalles puedas proporcionar, mejores resultados obtendrás de Antigravity en términos de arquitectura y código.
3. Planifica la arquitectura
Ya estamos listos para 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 definiendo 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 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 Add Folder 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 google-cloud-serverless-app.
Haz clic en el ícono de configuración principal ⚙️ en la parte inferior izquierda de la pantalla y ve a Project specific settings. Configura Agent Settings / Security Preset 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, está todo listo para proporcionar nuestra primera instrucción a Antigravity. Usaremos un comando de barra diagonal /grill-me para evaluar nuestra solicitud.
Escribe /grill-me y, luego, 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 de seguimiento que puedes intentar responder de la mejor manera posible. También sugiere Recommended Answers , y puedes elegir esa opción 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 usara lo siguiente:
- Una secuencia de comandos simple de la CLI de gcloud para aprovisionar recursos
- Notificaciones nativas de Cloud Storage Pub/Sub + suscripción de envío de Pub/Sub a Cloud Run
- Usar Flask (con Gunicorn) para el framework
- Usar solo la simulación local con un archivo de texto para los datos en lugar de datos de OCR en vivo
- Usar BigQuery table.insert_rows() para insertar filas en BigQuery
- Implementación no autenticada de Cloud Run
y otras opciones recomendadas.
Plan de implementación y lista de tareas
Antigravity ahora comenzará a trabajar y generará un Plan de implementación. Para que lo revises, te enviará un mensaje similar al siguiente:
Puedes hacer clic en el botón de alternancia Auxiliary Pane 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: Bucket de GCS, tema de Pub/Sub, conjunto de datos de BigQuery
- Procesador: App de Python/Flask, Dockerfile, requisitos
- Integración: Notificaciones de GCS → Pub/Sub → Cloud Run.
Deberías ver algo similar a lo 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 de proporcionar comentarios para 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 te gustaría ver, en especial en lo que respecta a la asignación de 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 otorgarle al agente el permiso para continuar con el plan de implementación.
Ahora, continúa con la creación de otro artefacto Task Plan, que contiene un conjunto de tareas que creó Antigravity. El agente las revisará una por una y las ejecutará. A continuación, se muestra una lista de tareas de muestra:
4. Genera la aplicación
Una vez que se aprueba el plan, Antigravity comienza a generar los archivos necesarios para la aplicación, desde secuencias de comandos de aprovisionamiento hasta código de la aplicación.
Antigravity creará una carpeta y comenzará a crear los archivos necesarios para el proyecto. Si verificas los artefactos, notarás que se generan varios archivos (código fuente, archivos de secuencia de comandos, etcétera).
Una vez que complete su trabajo, lo mencionará y creará un documento Walkthrough que puedes consultar. En él, se menciona el siguiente paso para el usuario. A continuación, se muestra un ejemplo:
- Deploy the Pipeline: Asegúrate de haber accedido a tu CLI de GCP y de haber configurado tu proyecto de destino. Luego, ejecuta:
./deploy.sh - Ejecuta la prueba de extremo a extremo: Ejecuta la secuencia de comandos de prueba de integración en la nube para verificar que una carga de archivos active el procesamiento de Cloud Run y transmita metadatos a BigQuery:
./test_cloud.sh - Clean Up: Una vez que termines de realizar las pruebas, consulta los comandos de limpieza
README.mdpara quitar los recursos creados y evitar cargos.
Se generará un archivo deploy.sh o un archivo de secuencia de comandos de shell con un nombre similar, que automatiza la creación de recursos. Se encarga de lo siguiente:
- Habilitar las APIs (
run,pubsub,bigquery,storage) - Crear el bucket de Google Cloud Storage (
document-processing-ingest-{project-id}) - Crear el conjunto de datos y la tabla de BigQuery (
document_processing.processed_metadata) - Configurar temas y notificaciones de Pub/Sub
5. Implemente la aplicación
Implementemos la aplicación como se mencionó con el ./ deploy.sh. Podemos pedirle a Antigravity que lo ejecute 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 una instrucción a Antigravity: "Run the deploy.sh for me". Se te solicitará permiso. Continúa y otórgale el permiso.
Inicia el proceso como una tarea en segundo plano, como se explica en el siguiente mensaje:
I have started the deployment process by running ./deploy.sh in the background. I will monitor the execution logs and let you know as soon as the deployment finishes!
6. Verifica la aplicación
Una vez que se implementa la canalización, Antigravity continúa para verificar que la aplicación funcione. Nos pregunta si puede ejecutar el archivo test_cloud.sh. Podemos continuar y otorgarle el permiso.
Por último, nos dice 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 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. Para ello, sigue estos pasos.
Cloud Storage
Objetivo: Verifica que exista el bucket y comprueba si hay archivos subidos.
- Navega a Cloud Storage > Buckets.
- Busca el bucket llamado
document-processing-ingest-{project-id}. - Haz clic en el nombre del bucket para explorar los archivos.
- Verifica lo que hiciste: Deberías ver 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.
- Navega a Pub/Sub > Temas.
- Busca document-uploads-topic.
- Haz clic en el ID del tema.
- Desplázate hacia abajo hasta la pestaña Suscripciones.
- Verifica lo que hiciste: Asegúrate de que doc-uploads-sub aparezca en la lista con el tipo de entrega "Push".
Cloud Run
Objetivo: Verifica el estado y los registros del servicio.
- Navega a Cloud Run.
- Haz clic en el servicio document-processor.
- Verifica lo que hiciste:
- Estado: Marca de verificación verde que indica que el servicio está activo
- Registros: Haz clic en la pestaña Registros. Busca entradas como "Processing file: gs://..." y "Successfully inserted...".
BigQuery
Objetivo: Valida que los datos estén almacenados.
- Navega a BigQuery > SQL Workspace.
- En el panel Explorador, expande tu proyecto > conjunto de datos document_processing.
- Haz clic en la tabla processed_metadata.
- Haz clic en la pestaña Consulta y recupera todas las filas de la tabla con la instrucción SELECT *.
- Verifica lo que hiciste: Deberías ver 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 debería mostrarte los archivos de código generados.
A continuación, se incluye un breve resumen de los archivos que podrías ver:
deploy.sh: Es la secuencia de comandos principal que aprovisiona todos los recursos de Google Cloud y habilita las APIs necesarias.appy.py: Es el punto de entrada principal de la canalización. Esta app de Python crea un servidor web que recibe mensajes de envío de Pub/Sub, descarga el archivo de GCS, lo "procesa" (simula OCR) y transmite los metadatos a BigQuery.Dockerfile: Define cómo empaquetar la app en una imagen de contenedor.requirements.txt: Enumera las dependencias de Python.
También es posible que veas otras secuencias de comandos y archivos de texto necesarios para las pruebas y la verificación.
8. Extiende la aplicación
Ahora que tienes una aplicación básica en funcionamiento, puedes seguir iterando y extendiendo la aplicación. Estas son algunas ideas.
Agrega un frontend
Compila 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
Integra IA y AA reales
En lugar del procesamiento de OCR simulado, usa modelos de Gemini para extraer, clasificar y traducir.
- Reemplaza la lógica de OCR ficticia. 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) o extraer entidades (fechas, nombres, ubicaciones).
- Detecta automáticamente el idioma del documento y tradúcelo al inglés antes de almacenarlo. También puedes usar cualquier otro idioma.
Mejora el almacenamiento y el análisis
Puedes configurar reglas de ciclo de vida en el bucket para mover archivos antiguos al almacenamiento "Coldline" o "Archive" para ahorrar costos.
Robustez y seguridad
Puedes hacer que la app sea más sólida y segura, por ejemplo:
- 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 "Dead Letter" separado para la inspección humana.
- 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.
- Eventarc: Actualiza de Pub/Sub directo a Eventarc para obtener un enrutamiento de eventos más flexible, lo que te permite activar según registros de auditoría complejos o eventos de otros servicios de GCP.
Por supuesto, puedes generar tus propias ideas y usar Antigravity para ayudarte a implementarlas.
9. Conclusión
Compilaste correctamente una canalización de documentos escalable, sin servidores y potenciada por IA en minutos con Google Antigravity. Aprendiste todo esto:
- Planificar arquitecturas con IA
- Dar instrucciones a Antigravity y administrarlo mientras genera la aplicación desde la generación de código hasta la implementación y la validación
- Verificar las implementaciones y la validación con Walkthroughs
Documentos de referencia
- Sitio oficial : https://antigravity.google/
- Documentación: https://antigravity.google/docs
- Casos de uso : https://antigravity.google/use-cases
- Descarga : https://antigravity.google/download