1. Introduzione
In questo codelab imparerai a utilizzare Google Antigravity per progettare, creare ed eseguire il deployment di un'applicazione serverless su Google Cloud. Creeremo una pipeline di documenti serverless e basata su eventi che acquisisce file da Google Cloud Storage (GCS), li elabora utilizzando Cloud Run e Gemini e trasmette i relativi metadati in BigQuery.
Cosa imparerai a fare
- Come utilizzare Antigravity per la pianificazione e la progettazione dell'architettura.
- Generare l'infrastruttura come codice (script shell) con un agente AI.
- Creare ed eseguire il deployment di un servizio Cloud Run basato su Python.
- Integrare Gemini su Vertex AI per l'analisi multimodale dei documenti.
- Verificare la pipeline end-to-end utilizzando l'artefatto Walkthrough di Antigravity.
Che cosa ti serve
- Google Antigravity installato.
- Un progetto Google Cloud con la fatturazione abilitata.
- gcloud CLI installata e autenticata.
2. Panoramica dell'app
Prima di passare alla progettazione e all'implementazione dell'applicazione utilizzando Antigravity, definiamo l'applicazione che vogliamo creare.
Vogliamo creare una pipeline di documenti serverless e basata su eventi che acquisisce file da Google Cloud Storage (GCS), li elabora utilizzando Cloud Run e Gemini e trasmette i relativi metadati in BigQuery.
Un diagramma dell'architettura di alto livello per questa applicazione potrebbe avere il seguente aspetto:
Non deve essere preciso. Antigravity può aiutarci a capire i dettagli dell'architettura man mano che procediamo. Tuttavia, è utile avere un'idea di ciò che vuoi creare. Più dettagli fornisci, migliori saranno i risultati che otterrai da Antigravity in termini di architettura e codice.
3. Pianificare l'architettura
Siamo pronti per iniziare a pianificare i dettagli dell'architettura con Antigravity.
Antigravity eccelle nella pianificazione di sistemi complessi. Anziché scrivere subito il codice, possiamo iniziare definendo l'architettura di alto livello e utilizzare una delle funzionalità per aiutare Antigravity a valutare la nostra richiesta, porci domande aggiuntive e quindi procedere con la pianificazione e l'implementazione.
Supponendo che tu abbia avviato Antigravity, creeremo un nuovo progetto per questo codelab.
Fai clic sull'icona del nuovo progetto accanto al lab Projects e poi su New Project come mostrato di seguito:
Viene visualizzata l'opzione Add Folder come mostrato di seguito:
Fai clic sul pulsante Add Folder per aggiungere una cartella al progetto. Sul mio computer ho creato una cartella google-cloud-serverless-app e l'ho aggiunta a questo progetto.
Si apre una conversazione nel progetto google-cloud-serverless-app.
Fai clic sull'icona delle impostazioni principali ⚙️in basso a sinistra dello schermo e vai a Impostazioni specifiche del progetto. Se non vedi il progetto google-cloud-serverless-app elencato, avvia una singola conversazione e poi torna alle impostazioni del progetto.
Imposta Agent Settings / Security Preset su Default e Agent Behaviour / Artifact Review Policy su Always Ask, come mostrato di seguito:
In questo modo, a ogni passaggio potrai esaminare e approvare il piano prima che l'agente lo esegua.
Prompt
Ora siamo pronti a fornire il nostro primo prompt ad Antigravity. Utilizzeremo un comando slash /grill-me per valutare la nostra richiesta.
Digita /grill-me , inserisci il seguente prompt e fai clic sul pulsante Invia:
/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.
Il comando /grill-me pone una serie di domande aggiuntive a cui puoi provare a rispondere al meglio delle tue conoscenze. Suggerisce anche le risposte consigliate che puoi utilizzare se vuoi.
Di seguito è riportata un'esecuzione di esempio del mio comando /grill-me:
How would you like the Cloud Run service to receive events from Cloud Storage and Pub/Sub?
(Recommended) Cloud Storage Pub/Sub Notification with a Pub/Sub Push Subscription (HTTP POST to Cloud Run)
How should access to the Cloud Run service endpoint be secured for Pub/Sub push requests?
Publicly accessible Cloud Run service without authentication (for prototyping/quick testing only)
How should the Python processor handle file inspection and the simulated OCR logic?
(Recommended) Download file from GCS: if plain text/utf-8, extract actual words and tags; if binary/image/PDF, simulate OCR processing (mock latency, generate synthetic text & tags, count words)
How should the processor write metadata to BigQuery and handle table/schema provisioning?
(Recommended) Use BigQuery Streaming Inserts (`insert_rows_json`) with auto-creation of the dataset and table if they do not exist
How should the Cloud Run service handle processing failures and retries from Pub/Sub?
(Recommended) Return HTTP 500 on transient errors for Pub/Sub automatic retry; return HTTP 200/204 on non-retryable errors (e.g., file not found, bad event format) to avoid poison pill loops
Which web framework would you prefer for the Python Cloud Run service?
Flask with Gunicorn: minimal, classic lightweight standard for GCP microservices
How would you like the cloud infrastructure (Bucket, Pub/Sub, Cloud Run, BigQuery) to be provisioned and deployed?
(Recommended) Provide both: automated `gcloud` CLI setup/deploy scripts for quick manual rollout AND Terraform manifests for reproducible IaC
How would you like to handle local testing and development before deploying to Google Cloud?
(Recommended) Include a local mock test suite and script (`test_local.py`) that can simulate Pub/Sub push envelopes and test processing with both mocked GCP clients and actual files
Ho chiesto ad Antigravity di utilizzare:
- Un semplice script gcloud CLI per il provisioning delle risorse
- Notifiche Pub/Sub di Cloud Storage native + sottoscrizione push Pub/Sub a Cloud Run
- Utilizzare Flask (con Gunicorn) per il framework
- Utilizzare la simulazione locale con un file di testo per i dati anziché i dati OCR in tempo reale
- Utilizzare table.insert_rows() di BigQuery per inserire righe in BigQuery
- Deployment di Cloud Run non autenticato
e altre opzioni consigliate.
Piano di implementazione ed elenco delle attività
Antigravity inizierà a lavorare e genererà un piano di implementazione. Lo mette a tua disposizione per la revisione con un messaggio simile a quello riportato di seguito:
Puoi fare clic sul pulsante di attivazione/disattivazione del riquadro ausiliario nella finestra in alto a destra e visualizzare gli artefatti generati, che a questo punto sono solo il piano di implementazione.
Questo piano descrive:
- Infrastruttura: bucket GCS, argomento Pub/Sub, set di dati BigQuery.
- Processore: app Python/Flask, Dockerfile, requisiti.
- Integrazione: notifiche GCS → Pub/Sub → Cloud Run.
Dovresti vedere qualcosa di simile a quanto segue. Di seguito è riportato un elenco parziale del piano di implementazione sul nostro computer:
Leggilo attentamente. È la tua occasione per fornire un feedback sull'implementazione. Puoi fare clic su qualsiasi parte del piano di implementazione e aggiungere commenti. Dopo aver aggiunto alcuni commenti, assicurati di inviare per la revisione le modifiche che vuoi vedere, in particolare per quanto riguarda la denominazione, l'ID progetto Google Cloud, la regione e così via.
Quando tutto sembra a posto, concedi all'agente l'autorizzazione a procedere con il piano di implementazione facendo clic sul pulsante Proceed.
4. Generare l'applicazione
Una volta approvato il piano, Antigravity inizia a generare i file necessari per l'applicazione, dagli script di provisioning al codice dell'applicazione.
Antigravity creerà una cartella e inizierà a creare i file necessari per il progetto. Se controlli gli artefatti, noterai che vengono generati diversi file (codice sorgente, file di script e così via).
Una volta completato il lavoro, lo indicherà e creerà un documento Walkthrough che potrai consultare. Di seguito è riportato un output di esempio:
Il documento Walkthrough indica cosa è stato implementato, gli script generati e, soprattutto, la verifica e la convalida eseguite. Di seguito è riportato un output parziale del documento Walkthrough che include la verifica e la convalida:
3. Verification & Validation
Test Suite Execution
We ran the automated test suite using pytest:
bash
.venv/bin/pytest tests/ -v
tests/test_local.py::test_health_check PASSED [ 9%]
tests/test_local.py::test_invalid_pubsub_envelope PASSED [ 18%]
tests/test_local.py::test_ignore_delete_events PASSED [ 27%]
tests/test_local.py::test_gcs_file_not_found PASSED [ 36%]
tests/test_local.py::test_successful_contract_processing PASSED [ 45%]
tests/test_local.py::test_successful_pdf_ocr_processing PASSED [ 54%]
tests/test_local.py::test_transient_bq_error_triggers_500_retry PASSED [ 63%]
tests/test_processor.py::test_tag_extraction_filters_stopwords PASSED [ 72%]
tests/test_processor.py::test_process_plain_text_document PASSED [ 81%]
tests/test_processor.py::test_process_binary_pdf_simulated_ocr PASSED [ 90%]
tests/test_processor.py::test_process_empty_text_document PASSED [100%]
============================== 11 passed in 2.37s ==============================
Standalone End-to-End Simulation
We executed the standalone simulation script:
bash
.venv/bin/python tests/test_local.py
Sample Output:
=================================================================
Running Serverless Document Processing Local Simulation
=================================================================
[1] Health Check: Status=200, Payload={'service': 'document-processor', 'status': 'healthy'}
[2] Simulating GCS Event: Object Finalized 'sample_contract.txt' in 'finance-bucket'
Response: Status=200, Body={'file_name': 'sample_contract.txt', 'ocr_status': 'EXTRACTED_TEXT', 'status': 'success', 'tags': ['provider', 'cloud', 'client', 'agreement', 'shall'], 'word_count': 181}
[3] Simulating GCS Event: Object Finalized 'sample_invoice.pdf' in 'invoices-bucket'
Response: Status=200, Body={'file_name': 'sample_invoice.pdf', 'ocr_status': 'SIMULATED_OCR', 'status': 'success', 'tags': ['invoice', 'finance', 'billing', 'acme', 'pdf'], 'word_count': 62}
=================================================================
BigQuery Streamed Table Inspection (Mock Table)
=================================================================
Row #1:
File: sample_contract.txt (gs://finance-bucket)
Status: EXTRACTED_TEXT
Words: 181
Tags: ['provider', 'cloud', 'client', 'agreement', 'shall']
Processed: 2026-09-08T02:50:37.436225+00:00
Row #2:
File: sample_invoice.pdf (gs://invoices-bucket)
Status: SIMULATED_OCR
Words: 62
Tags: ['invoice', 'finance', 'billing', 'acme', 'pdf']
Processed: 2026-09-08T02:50:37.641931+00:00
Possiamo chiedere ad Antigravity come eseguire il deployment di questa applicazione su Google Cloud? Fornisce tutti i dettagli, come elencato di seguito. In sintesi, ci chiede di assicurarci che Google Cloud SDK sia installato insieme a una configurazione del progetto Google Cloud. Una volta fatto,
Passaggio 1: attiva le API Google Cloud richieste
Esegui setup_gcp.sh per attivare le API Cloud Run, Pub/Sub, Cloud Storage, BigQuery e Cloud Build: ./scripts/setup_gcp.sh
Passaggio 2: esegui il deployment dell'intera pipeline
Esegui deploy.sh:
export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1" # or your region
./scripts/deploy.sh
Cosa fa questo script dietro le quinte:
- Crea l'immagine container utilizzando Google Cloud Build ed esegue il push su Container Registry/Artifact Registry.
- Esegue il deployment del servizio su Cloud Run con le variabili di ambiente appropriate (
GCP_PROJECT,BQ_DATASET_ID,BQ_TABLE_ID). - Crea il bucket di acquisizione di Cloud Storage (
gs://<PROJECT_ID>-document-ingest). - Crea l'argomento Pub/Sub (
document-upload-events) e concede l'autorizzazione a GCS di pubblicare su di esso. - Configura una notifica GCS (
OBJECT_FINALIZE) nel bucket. - Crea una sottoscrizione push Pub/Sub che ha come target l'URL del servizio Cloud Run con backoff di ripetizione automatica.
Suggerisce anche come testare la pipeline.
Esegui test_pipeline.sh: ./scripts/test_pipeline.sh
Carica samples/sample_contract.txt e samples/sample_invoice.pdf nel bucket, attende l'elaborazione ed esegue una query SQL BigQuery che mostra i metadati, il conteggio delle parole e i tag estratti.
5. Esegui il deployment dell'applicazione
Eseguiamo il deployment dell'applicazione come indicato. Possiamo chiedere ad Antigravity di eseguire questa operazione per noi, ma prima assicurati che gcloud CLI sia presente e configurata per il progetto Google Cloud.
Possiamo dare ad Antigravity il prompt "Deploy the application for me". Ti verrà richiesta l'autorizzazione per varie operazioni e poi verrà eseguito il deployment dei file di script.
Avvia la procedura come attività in background, come spiegato nel messaggio riportato di seguito:
I have initiated the deployment of the document processing pipeline to Google Cloud project PROJECT_ID in REGION.The deployment process is currently executing in the background:
Building and publishing the container image via Cloud Build.
Configuring service account IAM permissions and deploying the Cloud Run service.
Provisioning the Cloud Storage bucket (gs://PROJECT_ID-document-ingest).
Setting up the Pub/Sub topic, GCS notification, and push subscription.
I will notify you as soon as the deployment finishes!
6. Verificare l'applicazione
Una volta eseguito il deployment della pipeline, Antigravity procede con la verifica del corretto funzionamento dell'applicazione. Ci chiede se può eseguire il file test_pipeline.sh. Possiamo concedere l'autorizzazione.
Infine, ci dice quanto segue:
🚀 Deployment Successful & Verified on Google Cloud!
The application has been deployed to Google Cloud project PROJECT_ID in REGION and end-to-end event-driven processing has been verified.
Ha anche aggiornato l'artefatto Walkthrough per visualizzare i risultati (di seguito è riportato un elenco parziale):
Riepilogo del deployment
- Progetto Google Cloud: PROJECT_ID
- Regione: REGION
- Servizio Cloud Run: document-processor
- Endpoint Cloud Run: SERVICE_URL
- Bucket Cloud Storage: gs://PROJECT_ID-document-ingest
- Argomento Pub/Sub: document-upload-events
- Sottoscrizione push Pub/Sub: document-upload-events-push-sub
- Target BigQuery: PROJECT_ID.document_processing.document_metadata
Verifica della pipeline in tempo reale
Abbiamo eseguito scripts/test_pipeline.sh nell'ambiente Google Cloud in tempo reale:
- Abbiamo caricato sample_contract.txt e sample_invoice.pdf nel bucket Cloud Storage.
- GCS ha generato eventi OBJECT_FINALIZE in Pub/Sub.
- Pub/Sub ha eseguito il push delle buste nel microservizio Cloud Run.
- Cloud Run ha estratto i metadati, elaborato l'OCR simulato e trasmesso i record in BigQuery.
Output della query BigQuery in tempo reale
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| file_name | word_count | ocr_status | tags | processed_at |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| test_invoice_1788840194.pdf | 62 | SIMULATED_OCR | ["invoice","finance","billing","acme","pdf"] | 2026-09-08 04:03:27 |
| test_contract_1788840194.txt | 181 | EXTRACTED_TEXT | ["provider","cloud","client","agreement","shall"] | 2026-09-08 04:03:22 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
Tutti i componenti della pipeline sono attivi, integri e verificati in produzione.
Facoltativo: verifica manuale
Anche se Antigravity ha già verificato l'applicazione, puoi anche controllare manualmente nella console Google Cloud che tutte le risorse siano state create, se vuoi, seguendo questi passaggi.
Cloud Storage
Obiettivo: verificare che il bucket esista e controllare i file caricati.
- Vai a Cloud Storage > Bucket.
- Individua il bucket denominato
PROJECT_ID-document-processing. - Fai clic sul nome del bucket per sfogliare i file.
- Verifica: dovresti vedere i file caricati (ad es.
sample_contract.txt).
Pub/Sub
Obiettivo: verificare che l'argomento esista e che abbia una sottoscrizione push.
- Vai a Pub/Sub > Argomenti.
- Trova document-uploads-events.
- Fai clic sull'ID argomento.
- Scorri verso il basso fino alla scheda Sottoscrizioni.
- Verifica: assicurati che doc-uploads-events-push-sub sia elencato.
Cloud Run
Obiettivo: controllare lo stato e i log del servizio.
- Vai a Cloud Run.
- Fai clic sul servizio document-processor.
- Verifica:
- Stato: segno di spunta verde che indica che il servizio è attivo.
- Log: fai clic sulla scheda Log. Cerca voci come "Processing document: gs://..." e "Successfully streamed metadata...".
BigQuery
Obiettivo: verificare che i dati siano effettivamente archiviati.
- Vai a BigQuery > Area di lavoro SQL.
- Nel riquadro Explorer, espandi il set di dati project > document_processing.
- Fai clic sulla tabella document_metadata.
- Fai clic sulla scheda Query e recupera tutte le righe della tabella tramite l'istruzione SELECT *.
- Verifica: dovresti vedere le righe contenenti file_name, process_at, tags e word_count.
7. Esplorare l'applicazione
A questo punto, l'app di base è stata sottoposta a provisioning ed è in esecuzione. Prima di approfondire l'estensione di questa applicazione, prenditi un momento per esplorare il codice. Puoi visualizzare gli artefatti e dovresti vedere i file di codice generati.
Ecco un breve riepilogo di alcuni file che potresti visualizzare:
deploy.sh: lo script principale che esegue il provisioning di tutte le risorse Google Cloud e attiva le API richieste.main.py: l'entry point principale della pipeline. Questa app Python crea un server web che riceve i messaggi push Pub/Sub, scarica il file da GCS, lo "elabora" (simula l'OCR) e trasmette i metadati a BigQuery.Dockerfile: definisce come pacchettizzare l'app in un'immagine container.requirements.txt: elenca le dipendenze Python.
Potresti anche vedere altri script e file di testo necessari per i test e la verifica.
8. Estendere l'applicazione
Ora che hai un'applicazione di base funzionante, puoi continuare a iterare ed estendere l'applicazione. Ecco alcune idee.
Aggiungere un frontend
Crea una semplice interfaccia web per visualizzare i documenti elaborati.
Prova il seguente prompt: 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
Integrare con AI/ML reali
Anziché l'elaborazione OCR simulata, utilizza i modelli Gemini per estrarre, classificare e tradurre.
- Sostituisci la logica OCR fittizia. Invia l'immagine/il PDF a Gemini per estrarre il testo e i dati effettivi. Analizza il testo estratto per classificare il tipo di documento (fattura, contratto, curriculum) o estrarre le entità (date, nomi, località).
- Rileva automaticamente la lingua del documento e traducila in inglese prima di archiviarla. Puoi utilizzare anche qualsiasi altra lingua.
Migliorare l'archiviazione e l'analisi
Puoi configurare le regole del ciclo di vita nel bucket per spostare i file meno recenti nell'archiviazione "Coldline" o "Archive" per ridurre i costi.
Robustezza e sicurezza
Puoi rendere l'app più robusta e sicura, ad esempio:
- Code di messaggi non recapitabili (DLQ): aggiorna la sottoscrizione Pub/Sub per gestire gli errori. Se il servizio Cloud Run non riesce a elaborare un file 5 volte, invia il messaggio a un argomento/bucket "Dead Letter" separato per l'ispezione umana.
- Secret Manager: se la tua app ha bisogno di chiavi API o configurazioni sensibili, archiviale in Secret Manager e accedi in modo sicuro da Cloud Run anziché codificare le stringhe.
- Eventarc: esegui l'upgrade da Pub/Sub diretto a Eventarc per un routing degli eventi più flessibile, che ti consente di attivare in base a log di audit complessi o ad altri eventi del servizio Google Cloud.
Naturalmente, puoi trovare le tue idee e utilizzare Antigravity per implementarle.
9. Conclusione
Hai creato correttamente una pipeline di documenti scalabile, serverless e basata sull'AI in pochi minuti utilizzando Google Antigravity. Hai imparato a:
- Pianificare le architetture con l'AI.
- Istruire e gestire Antigravity durante la generazione dell'applicazione, dalla generazione del codice al deployment e alla convalida.
- Verificare i deployment e la convalida con le procedure dettagliate.
Documenti di riferimento
- Sito ufficiale : https://antigravity.google/
- Documentazione: https://antigravity.google/docs
- Casi d'uso : https://antigravity.google/use-cases
- Download : https://antigravity.google/download