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 architettonica.
- Genera l'infrastruttura come codice (script shell) con un agente AI.
- Crea ed esegui il deployment di un servizio Cloud Run basato su Python.
- Integra Gemini su Vertex AI per l'analisi multimodale dei documenti.
- Verifica 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 prima l'applicazione che vogliamo creare.
Vogliamo creare una pipeline di documenti serverless e basata su eventi che acquisisca file da Google Cloud Storage (GCS), li elabori utilizzando Cloud Run e Gemini e trasmetta in streaming i relativi metadati in BigQuery.
Un diagramma dell'architettura di alto livello per questa applicazione potrebbe avere il seguente aspetto:
Non è necessario che sia preciso. Antigravity può aiutarci a capire i dettagli dell'architettura man mano che procediamo. Tuttavia, è utile avere un'idea di cosa 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 poi 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:
Verrà visualizzata l'opzione Add Folder come mostrato di seguito:
Fai clic sul pulsante Aggiungi cartella 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 aprirà una conversazione nel workspace google-cloud-serverless-app.
Fai clic sull'icona delle impostazioni principali ⚙️ in basso a sinistra dello schermo e vai a Impostazioni specifiche 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, potrai rivedere 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 nel modo più preciso possibile. Suggerisce anche Risposte consigliate, che puoi utilizzare se vuoi.
Di seguito è riportato un esempio di esecuzione del 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).
Nota che ho chiesto ad Antigravity di utilizzare:
- Un semplice script dell'interfaccia a riga di comando gcloud per il provisioning delle risorse
- Notifiche Pub/Sub di Cloud Storage native + sottoscrizione push Pub/Sub a Cloud Run
- Utilizza Flask (con Gunicorn) per il framework
- Utilizza la simulazione locale con un file di testo per i dati anziché i dati OCR in tempo reale.
- Utilizza BigQuery table.insert_rows() 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 disposizione per la revisione inviandoti un messaggio simile a quello riportato di seguito:
Puoi fare clic sul pulsante di attivazione/disattivazione del riquadro ausiliario in alto a destra della finestra e visualizzare gli artefatti generati, che a questo punto sono solo il piano di implementazione.
Questo piano delinea:
- Infrastruttura: bucket GCS, argomento Pub/Sub, set di dati BigQuery.
- Processore: app Python/Flask, Dockerfile, Requirements.
- Integrazione: notifiche GCS → Pub/Sub → Cloud Run.
Dovresti visualizzare un risultato simile al seguente. Di seguito è riportato un elenco parziale del piano di implementazione sul nostro computer:
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
Leggi attentamente. Questa è la tua occasione per fornire un feedback sull'implementazione. Puoi fare clic su qualsiasi parte del piano di implementazione e aggiungere commenti. Una volta aggiunti alcuni commenti, assicurati di inviare per la revisione tutte le modifiche che vuoi visualizzare, in particolare quelle relative a denominazione, ID progetto Google Cloud, 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.
Ora procede con la creazione di un altro artefatto, il piano di attività, che contiene un insieme di attività create da Antigravity. L'agente li esaminerà uno alla volta e li eseguirà. Di seguito è riportato un elenco di attività di esempio:
4. Genera 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 la generazione di diversi file (codice sorgente, file di script e così via).
Una volta completata l'operazione, lo strumento lo segnalerà e creerà un documento Procedura dettagliata che potrai consultare. In questo modo viene indicato il passaggio successivo per l'utente. Di seguito è riportato un esempio:
- Esegui il deployment della pipeline:assicurati di aver eseguito l'accesso a GCP CLI e di aver impostato il progetto di destinazione, quindi esegui:
./deploy.sh - Esegui test end-to-end: esegui lo script per il test di integrazione cloud per verificare che il caricamento di un file attivi l'elaborazione di Cloud Run e trasmetta i metadati a BigQuery:
./test_cloud.sh - Pulizia:al termine del test, fai riferimento ai comandi di pulizia
README.mdper rimuovere le risorse create ed evitare addebiti.
Verrà generato un file di script shell deploy.sh o con un nome simile, che automatizza la creazione delle risorse. Gestisce:
- Abilitazione delle API (
run,pubsub,bigquery,storage). - Creazione del bucket Google Cloud Storage (
document-processing-ingest-{project-id}). - Creazione del set di dati e della tabella BigQuery (
document_processing.processed_metadata). - Configurazione di argomenti e notifiche Pub/Sub.
5. Esegui il deployment dell'applicazione
Eseguiamo il deployment dell'applicazione come indicato tramite il comando ./ deploy.sh. Possiamo chiedere ad Antigravity di eseguire questa operazione per nostro conto, ma prima di farlo, assicurati che gcloud CLI sia presente e configurata per il progetto Google Cloud.
Possiamo dare un prompt ad Antigravity "Esegui deploy.sh per me". Ti verrà chiesto di concedere l'autorizzazione. Procedi pure.
Avvia la procedura come attività in background, come spiegato nel messaggio seguente:
Ho avviato la procedura di deployment eseguendo ./deploy.sh in background. Monitorerò i log di esecuzione e ti avviserò non appena il deployment sarà completato.
6. Verifica l'applicazione
Una volta eseguito il deployment della pipeline, Antigravity procede a verificare che l'applicazione funzioni effettivamente. Ci chiede se può eseguire il file test_cloud.sh. Possiamo procedere e concedere l'autorizzazione.
Infine, ci dice quanto segue:
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.
Possiamo aprire l'artefatto della procedura dettagliata per visualizzare i risultati:
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.
(Facoltativo) Verifica manuale
Anche se Antigravity ha già verificato l'applicazione, se vuoi puoi controllare manualmente nella console Google Cloud che tutte le risorse siano state create seguendo questi passaggi.
Cloud Storage
Obiettivo: verifica che il bucket esista e controlla i file caricati.
- Vai a Cloud Storage > Bucket.
- Individua il bucket denominato
document-processing-ingest-{project-id}. - Fai clic sul nome del bucket per sfogliare i file.
- Verifica: dovresti visualizzare i file caricati (ad es.
cloud_test_sample.txt).
Pub/Sub
Obiettivo: conferma che l'argomento esista e che abbia una sottoscrizione push.
- Vai a Pub/Sub > Argomenti.
- Trova document-uploads-topic.
- Fai clic sull'ID argomento.
- Scorri verso il basso fino alla scheda Abbonamenti.
- Verifica: assicurati che doc-uploads-sub sia elencato con il tipo di distribuzione "Push".
Cloud Run
Obiettivo: controlla 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 file: gs://..." e "Successfully inserted...".
BigQuery
Obiettivo: verificare che i dati siano effettivamente archiviati.
- Vai a BigQuery > Area di lavoro SQL.
- Nel riquadro Explorer, espandi progetto > set di dati document_processing.
- Fai clic sulla tabella processed_metadata.
- Fai clic sulla scheda Query e recupera tutte le righe della tabella tramite l'istruzione SELECT *.
- Verifica: dovresti vedere righe contenenti filename, process_timestamp, tags e word_count.
7. Esplora l'applicazione
A questo punto, l'app di base è stata sottoposta al 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 dei file che potresti visualizzare:
deploy.sh: lo script principale che esegue il provisioning di tutte le risorse Google Cloud e abilita le API richieste.appy.py: il punto di ingresso principale della pipeline. Questa app Python crea un server web che riceve messaggi push Pub/Sub, scarica il file da GCS, lo "elabora" (simula l'OCR) e trasmette in streaming i metadati a BigQuery.Dockerfile: definisce come pacchettizzare l'app in un'immagine container.requirements.txt: elenca le dipendenze Python.
Potresti anche visualizzare 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 un'interfaccia web semplice 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
Integrazione con AI/ML reali
Invece dell'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 testo e dati effettivi. Analizza il testo estratto per classificare il tipo di documento (fattura, contratto, curriculum) o estrarre entità (date, nomi, località).
- Rileva automaticamente la lingua del documento e lo traduce in inglese prima di archiviarlo. 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 risparmiare sui costi.
Robustezza e sicurezza
Puoi rendere l'app più solida 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 bucket/argomento "Dead Letter" separato per l'ispezione umana.
- Secret Manager: se la tua app ha bisogno di chiavi API o di una configurazione sensibile, 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 controllo complessi o ad altri eventi di servizi GCP.
Certo, puoi inventare le tue idee e usare 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:
- Pianifica le architetture con l'AI.
- Istruisci e gestisci Antigravity mentre genera l'applicazione, dalla generazione del codice al deployment e alla convalida.
- Verifica i deployment e la convalida con le procedure dettagliate.
Documentazione 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