Creare ed eseguire il deployment su Google Cloud con Antigravity

1. Introduzione

In questo codelab, imparerai a utilizzare Google Antigravity (denominato Antigravity per il resto del documento) 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.

Per i crediti Google Cloud:per aiutarti a utilizzare Antigravity con i progetti Google Cloud, riscatta i tuoi crediti Google Cloud senza costi utilizzando questo link. Puoi seguire le istruzioni qui per attivare il credito e creare un nuovo progetto.

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. Se hai bisogno di aiuto per installare Antigravity e comprendere le nozioni di base, ti consigliamo di completare il codelab Introduzione a Google Antigravity.
• 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 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 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. Invece di scrivere subito il codice, possiamo iniziare definendo l'architettura di alto livello.

Innanzitutto, assicurati di trovarti in Agent Manager. Se hai appena aperto Antigravity, puoi fare clic sul pulsante Open Agent Manager al centro oppure dovresti vedere lo stesso pulsante Open Agent Manager nell'angolo in alto a destra.

In Agent Manager, puoi aprire uno spazio di lavoro o utilizzare semplicemente Playground, uno spazio di lavoro indipendente per prototipi ed esperimenti rapidi. Iniziamo con il Playground.

Fai clic sul pulsante + per avviare una nuova conversazione in Playground:

Viene visualizzata un'interfaccia in cui puoi fornire il prompt come mostrato di seguito:

Nell'angolo in alto a destra, fai clic sull'icona delle impostazioni ⚙️ e imposta Review Policy in Artifact e Terminal Command Auto Execution in Terminal su Request Review. 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.

Innanzitutto, assicurati che Antigravity sia in modalità Planning e, per il modello, scegliamo Gemini Pro (High) (ma puoi sperimentare anche con altri modelli).

Inserisci il seguente prompt e fai clic sul pulsante Invia:

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. 

Elenco attività e piano di implementazione

Antigravity analizzerà la tua richiesta e genererà un elenco di attività e un 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:

Fai clic sul pulsante Open accanto alla riga Task. Dovresti visualizzare un insieme di attività create da Antigravity. L'agente li esaminerà uno alla volta:

Il passaggio successivo consiste nel rivedere il piano di implementazione e concedere all'agente l'autorizzazione a procedere.

Fai clic sul piano di implementazione per visualizzarne i dettagli. 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 alla denominazione, all'ID progetto Google Cloud, alla 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. 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.

Nota: ti verranno richiesti diversi comandi del terminale (gcloud, script shell e così via) che l'agente dovrà utilizzare per comprendere l'ambiente e generare gli script di conseguenza. Fai clic sul pulsante Accept per far avanzare l'agente. Sebbene questo lab copra i nomi file specifici generati, potresti notare che Antigravity genera nomi file diversi, anche se l'intento e il contenuto dei file dovrebbero essere simili.

Antigravity creerà una cartella e inizierà a creare i file necessari per il progetto. Nella nostra esecuzione di esempio, abbiamo visto quanto segue:

Viene generato un file di script della shell setup.sh o con un nome simile, che automatizza la creazione delle risorse. Gestisce:

1. Abilitazione delle API (run, pubsub, bigquery, storage).
2. Creazione del bucket Google Cloud Storage (doc-ingestion-{project-id}).
3. Creazione del set di dati e della tabella BigQuery (pipeline_data.processed_docs).
4. Configurazione di argomenti e notifiche Pub/Sub.

L'agente deve generare un'applicazione Python (main.py) in attesa di messaggi push Pub/Sub. Utilizza una logica OCR simulata, generando conteggi di parole e tag casuali e salvandoli in BigQuery.

Una volta generato questo script di configurazione, Antigravity dovrebbe chiederti di eseguirlo per tuo conto. Di seguito è mostrata una schermata di esempio:

Procedi e fai clic su Accept in base alle necessità.

Lo script di provisioning creerà le risorse e ne convaliderà la creazione. Se il controllo va a buon fine, si procederà alla creazione del container e al suo deployment come servizio (in main.py) in Cloud Run. Di seguito è riportato un output di esempio:

Nell'ambito del deployment del servizio, verranno configurate anche le sottoscrizioni Pub/Sub e altri elementi di collegamento necessari per il funzionamento di questa pipeline. Tutto ciò dovrebbe richiedere alcuni minuti.

Nel frattempo, puoi passare a Inbox (dall'angolo in alto a sinistra) e controllare le attività Pending in attesa del tuo intervento:

In questo modo, puoi approvare le attività mentre l'agente cerca il tuo feedback.

5. Verifica l'applicazione

Una volta eseguito il deployment della pipeline, Antigravity procede a verificare che l'applicazione funzioni effettivamente. Antigravity automatizza questa operazione con i passaggi di verifica nell'elenco delle attività. Di seguito è mostrata una schermata di esempio:

Crea un artefatto di test (test.txt) e vuole caricarlo nel bucket Google Cloud Storage. Fai clic su Accept per continuare.

Se vuoi eseguire altri test in autonomia, puoi prendere spunto dal passaggio di convalida di Antigravity, in cui utilizza l'utilità gsutil per caricare un file di esempio nel bucket Cloud Storage. Il comando di esempio è mostrato di seguito:

gsutil cp <some-test-doc>.txt gs://<bucket-name>/

Controllare i risultati in BigQuery

Nell'ambito della procedura di verifica, verrà anche controllato che i dati siano stati salvati in BigQuery.

Prendi nota della query SQL utilizzata per controllare i documenti.

Una volta completata la verifica, dovresti vedere che l'elenco delle attività è stato completato:

(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.

1. Vai a Cloud Storage > Bucket.
2. Individua il bucket denominato [PROJECT_ID]-doc-uploads.
3. Fai clic sul nome del bucket per sfogliare i file.
4. Verifica: dovresti visualizzare i file caricati (ad es. test.txt).

Pub/Sub

Obiettivo: verificare che l'argomento esista e che abbia un abbonamento push.

1. Vai a Pub/Sub > Argomenti.
2. Trova doc-processing-topic.
3. Fai clic sull'ID argomento.
4. Scorri verso il basso fino alla scheda Abbonamenti.
5. Verifica: assicurati che doc-processing-sub sia elencato con il tipo di distribuzione "Push".

Cloud Run

Obiettivo: controlla lo stato e i log del servizio.

1. Vai a Cloud Run.
2. Fai clic sul servizio doc-processor.
3. Verifica:
4. Stato: segno di spunta verde che indica che il servizio è attivo.
5. Log: fai clic sulla scheda Log. Cerca voci come "Elaborazione file: gs://..." e "Elaborazione riuscita...".

BigQuery

Obiettivo: verificare che i dati siano effettivamente archiviati.

1. Vai a BigQuery > Area di lavoro SQL.
2. Nel riquadro Explorer, espandi progetto > set di dati pipeline_data.
3. Fai clic sulla tabella processed_docs.
4. Fai clic sulla scheda Anteprima.
5. Verifica: dovresti visualizzare righe contenenti filename, upload_date, tags e word_count.

Procedura dettagliata

Come passaggio finale, Antigravity genera un artefatto di procedura dettagliata. Questo elemento riepiloga:

• Modifiche apportate.
• I comandi di verifica vengono eseguiti.
• Risultati effettivi (output della query che mostra i metadati estratti da Gemini).

Puoi fare clic su Open per visualizzarlo. Di seguito è riportato un output di esempio:

6. Esplorare 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 passare all'editor con il pulsante Open Editor nell'angolo in alto a destra.

Ecco un breve riepilogo dei file che potresti visualizzare:

1. setup.sh: lo script principale che esegue il provisioning di tutte le risorse Google Cloud e attiva le API richieste.
2. main.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.
3. Dockerfile: definisce come pacchettizzare l'app in un'immagine container.
4. requirements.txt: elenca le dipendenze Python.

Potresti anche vedere altri script e file di testo necessari per i test e la verifica.

A questo punto, potresti anche voler passare da Playground a uno spazio di lavoro/cartella dedicato. Per farlo, fai clic sul pulsante pertinente nell'angolo in alto a destra:

Una volta scelta una cartella, tutto il codice verrà spostato in quella cartella e verrà creato un nuovo spazio di lavoro con la cartella e la cronologia della conversazione.

7. 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.

1. 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à).
2. Rileva automaticamente la lingua del documento e la 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:

1. 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.
2. 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.
3. Eventarc: esegui l'upgrade da Pub/Sub diretto a Eventarc per un routing degli eventi più flessibile, che ti consente di attivare trigger in base a log di controllo complessi o ad altri eventi di servizi GCP.

Ovviamente, puoi inventare le tue idee e usare Antigravity per aiutarti a implementarle.

8. 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.

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
• Codelab : Guida introduttiva a Google Antigravity