Mit Antigravity in Google Cloud entwickeln und bereitstellen

1. Einführung

In diesem Codelab erfahren Sie, wie Sie mit Google Antigravity eine serverlose Anwendung entwerfen, erstellen und in Google Cloud bereitstellen. Wir erstellen eine serverlose und ereignisgesteuerte Dokumentpipeline, die Dateien aus Google Cloud Storage (GCS) aufnimmt, sie mit Cloud Run und Gemini verarbeitet und ihre Metadaten in BigQuery streamt.

Lerninhalte

• Antigravity für die Architekturplanung und das Design verwenden
• Infrastruktur als Code (Shell-Skripts) mit einem KI-Agenten generieren
• Einen Cloud Run-Dienst auf Python-Basis erstellen und bereitstellen
• Gemini auf Vertex AI für die multimodale Dokumentanalyse einbinden
• Die End-to-End-Pipeline mit dem Walkthrough-Artefakt von Antigravity überprüfen

Voraussetzungen

• Google Antigravity ist installiert.
• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion
• gcloud CLI ist installiert und authentifiziert.

2. Übersicht über die App

Bevor wir mit der Architektur und Implementierung der Anwendung mit Antigravity beginnen, skizzieren wir zuerst die Anwendung, die wir erstellen möchten.

Wir möchten eine serverlose und ereignisgesteuerte Dokumentpipeline erstellen, die Dateien aus Google Cloud Storage (GCS) aufnimmt, sie mit Cloud Run und Gemini verarbeitet und ihre Metadaten in BigQuery streamt.

Ein Architekturdiagramm auf hoher Ebene für diese Anwendung könnte so aussehen:

Das muss nicht genau sein. Antigravity kann uns helfen, die Architekturdetails im Laufe der Zeit zu ermitteln. Es ist jedoch hilfreich, eine Vorstellung davon zu haben, was Sie erstellen möchten. Je detaillierter Sie sind, desto bessere Ergebnisse erhalten Sie von Antigravity in Bezug auf Architektur und Code.

3. Architektur planen

Wir sind bereit, mit der Planung der Architekturdetails mit Antigravity zu beginnen.

Antigravity eignet sich hervorragend für die Planung komplexer Systeme. Anstatt sofort Code zu schreiben, können wir zuerst die Architektur auf hoher Ebene definieren und eine der Funktionen verwenden, damit Antigravity unsere Anfrage bewerten, uns weiterführende Fragen stellen und dann mit der Planung und Implementierung fortfahren kann.

Angenommen, Sie haben Antigravity gestartet, erstellen wir ein neues Projekt für dieses Codelab.

Klicken Sie neben dem Lab Projects auf das Symbol für ein neues Projekt und dann auf New Project , wie unten gezeigt:

Dadurch wird die Option Add Folder angezeigt, wie unten gezeigt:

Klicken Sie auf die Schaltfläche Add Folder , um Ihrem Projekt einen Ordner hinzuzufügen. Auf meinem Computer habe ich den Ordner google-cloud-serverless-app erstellt und ihn diesem Projekt hinzugefügt.

Dadurch wird eine Unterhaltung im Arbeitsbereich google-cloud-serverless-app geöffnet.

Klicken Sie links unten auf dem Bildschirm auf das Symbol für die Haupteinstellungen ⚙️ und rufen Sie die projektspezifischen Einstellungen auf. Legen Sie für Agent Settings / Security Preset die Option Default und für Agent Behaviour / Artifact Review Policy die Option Always Ask fest, wie unten gezeigt:

So können Sie in jedem Schritt den Plan überprüfen und genehmigen, bevor der Agent ihn ausführt.

Prompt

Jetzt können wir Antigravity unseren ersten Prompt geben. Wir verwenden den Slash-Befehl /grill-me , um unsere Anfrage zu bewerten.

Geben Sie /grill-me ein, geben Sie dann den folgenden Prompt ein und klicken Sie auf die Schaltfläche „Senden“:

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

Der Befehl /grill-me stellt eine Reihe von weiterführenden Fragen, die Sie nach bestem Wissen beantworten können. Außerdem werden Recommended Answers (Empfohlene Antworten) vorgeschlagen, die Sie verwenden können.

Ein Beispiel für die Ausführung meines Befehls /grill-me ist unten dargestellt:

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

Ich habe Antigravity gebeten, Folgendes zu verwenden:

• Ein einfaches gcloud CLI-Skript zum Bereitstellen von Ressourcen
• Native Cloud Storage Pub/Sub-Benachrichtigungen + Pub/Sub-Push-Abo für Cloud Run
• Flask (mit Gunicorn) für das Framework verwenden
• Anstelle von Live-OCR-Daten nur eine lokale Simulation mit einer Textdatei für die Daten verwenden
• Mit BigQuery table.insert_rows() Zeilen in BigQuery einfügen
• Nicht authentifizierte Cloud Run-Bereitstellung

und andere empfohlene Optionen.

Implementierungsplan und Aufgabenliste

Antigravity beginnt nun mit der Arbeit und generiert einen Implementierungsplan. Er wird Ihnen zur Überprüfung vorgelegt, indem Sie eine Nachricht ähnlich der folgenden erhalten:

Sie können oben rechts im Fenster auf den Ein/Aus-Button für den Hilfsbereich klicken und die generierten Artefakte ansehen. Derzeit ist das nur der Implementierungsplan.

Dieser Plan enthält Folgendes:

• Infrastruktur: GCS-Bucket, Pub/Sub-Thema, BigQuery-Dataset
• Prozessor: Python/Flask-App, Dockerfile, Anforderungen
• Integration: GCS-Benachrichtigungen → Pub/Sub → Cloud Run

Die Ausgabe sollte in etwa so aussehen: Unten sehen Sie eine Teilliste des Implementierungsplans auf unserem 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

Lesen Sie ihn sorgfältig durch. Hier haben Sie die Möglichkeit, Feedback zur Implementierung zu geben. Sie können auf einen beliebigen Teil des Implementierungsplans klicken und Kommentare hinzufügen. Nachdem Sie Kommentare hinzugefügt haben, senden Sie alle Änderungen zur Überprüfung ein, die Sie vornehmen möchten, insbesondere in Bezug auf die Benennung, die Google Cloud-Projekt-ID, die Region usw.

Wenn alles in Ordnung ist, geben Sie dem Agenten die Berechtigung, mit dem Implementierungsplan fortzufahren, indem Sie auf die Schaltfläche Proceed (Fortfahren) klicken.

Hinweis:Manchmal wird die Schaltfläche Proceed (Fortfahren) nicht angezeigt und Antigravity fährt fort, ohne auf Ihre Eingabe zu warten.

Jetzt wird ein weiteres Artefakt erstellt, der Aufgabenplan , der eine Reihe von Aufgaben enthält, die von Antigravity erstellt wurden. Der Agent geht sie einzeln durch und führt sie aus. Ein Beispiel für eine Aufgabenliste ist unten dargestellt:

4. Anwendung generieren

Sobald der Plan genehmigt wurde, beginnt Antigravity mit dem Generieren der für die Anwendung erforderlichen Dateien, von Bereitstellungsskripts bis hin zum Anwendungscode.

Hinweis: Sie werden aufgefordert, mehrere Terminalbefehle (gcloud, Shell-Skripts usw.) einzugeben, die der Agent benötigt, um die Umgebung zu verstehen und die Skripts entsprechend zu generieren. Klicken Sie auf die Schaltfläche Submit, damit der Agent fortfahren kann. In diesem Lab werden die spezifischen Dateinamen behandelt, die generiert wurden. Antigravity generiert möglicherweise andere Dateinamen, die Absicht und der Inhalt der Dateien sollten jedoch ähnlich sein.

Antigravity erstellt einen Ordner und beginnt mit dem Erstellen der für das Projekt erforderlichen Dateien. Wenn Sie die Artefakte prüfen, sehen Sie, dass mehrere Dateien (Quellcode, Skriptdateien usw.) generiert werden.

Sobald die Arbeit abgeschlossen ist, wird dies erwähnt und ein Walkthrough -Dokument erstellt, das Sie sich ansehen können. Darin wird der nächste Schritt für den Nutzer erwähnt. Ein Beispiel ist unten dargestellt:

• Pipeline bereitstellen:Achten Sie darauf, dass Sie in der GCP CLI angemeldet sind und Ihr Zielprojekt festgelegt haben. Führen Sie dann Folgendes aus: ./ deploy.sh
• End-to-End-Test ausführen: Führen Sie das Cloud-Integrationstestskript aus, um zu prüfen, ob ein Dateiupload die Cloud Run-Verarbeitung auslöst und Metadaten in BigQuery streamt:./test_cloud.sh
• Bereinigen:Wenn Sie mit dem Testen fertig sind, verwenden Sie die Bereinigungsbefehle in der Datei README.md, um die erstellten Ressourcen zu entfernen und Gebühren zu vermeiden.

Es wird eine deploy.sh-Datei oder eine ähnlich benannte Shell-Skriptdatei generiert, die die Ressourcenerstellung automatisiert. Sie übernimmt Folgendes:

1. APIs aktivieren (run, pubsub, bigquery, storage)
2. Google Cloud Storage-Bucket erstellen (document-processing-ingest-{project-id})
3. BigQuery-Dataset und ‑Tabelle erstellen (document_processing.processed_metadata)
4. Pub/Sub-Themen und ‑Benachrichtigungen konfigurieren

5. Anwendung bereitstellen

Wir stellen die Anwendung wie erwähnt mit dem ./ deploy.sh Befehl bereit. Wir können Antigravity bitten, dies für uns auszuführen. Bevor wir das tun, müssen wir jedoch prüfen, ob die gcloud CLI vorhanden und für das Google Cloud-Projekt konfiguriert ist.

Wir können Antigravity den Prompt „Run the deploy.sh for me“ geben. Sie werden dann um die Berechtigung gebeten. Geben Sie sie.

Der Prozess wird als Hintergrundaufgabe gestartet, wie in der folgenden Nachricht erläutert:

Ich habe den Bereitstellungsprozess gestartet, indem ich ./deploy.sh im Hintergrund ausgeführt habe. Ich beobachte die Ausführungsprotokolle und informiere Sie, sobald die Bereitstellung abgeschlossen ist.

6. Anwendung überprüfen

Sobald die Pipeline bereitgestellt wurde, überprüft Antigravity, ob die Anwendung tatsächlich funktioniert. Wir werden gefragt, ob die Datei „test_cloud.sh“ ausgeführt werden kann. Wir können die Berechtigung erteilen.

Schließlich wird Folgendes angezeigt:

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.

Wir können das Walkthrough-Artefakt öffnen, um die Ergebnisse zu sehen:

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.

Optional: Manuelle Bestätigung

Obwohl Antigravity die Anwendung bereits überprüft hat, können Sie in der Google Cloud Console auch manuell prüfen, ob alle Ressourcen erstellt wurden. Folgen Sie dazu dieser Anleitung.

Cloud Storage

Ziel: Prüfen, ob der Bucket vorhanden ist, und nach hochgeladenen Dateien suchen.

1. Rufen Sie Cloud Storage > Buckets auf.
2. Suchen Sie den Bucket mit dem Namen document-processing-ingest-{project-id}.
3. Klicken Sie auf den Bucket-Namen, um die Dateien zu durchsuchen.
4. Prüfen Sie, ob die hochgeladenen Dateien angezeigt werden (z.B. cloud_test_sample.txt).

Pub/Sub

Ziel: Prüfen, ob das Thema vorhanden ist und ein Push-Abo hat.

1. Rufen Sie Pub/Sub > Themen auf.
2. Suchen Sie nach document-uploads-topic.
3. Klicken Sie auf die Themen-ID.
4. Scrollen Sie nach unten zum Tab Abos.
5. Prüfen Sie, ob doc-uploads-sub mit dem Zustellungstyp "Push" aufgeführt ist.

Cloud Run

Ziel: Dienststatus und Logs prüfen.

1. Rufen Sie Cloud Run auf.
2. Klicken Sie auf den Dienst document-processor.
3. Prüfen Sie Folgendes:
4. Status: Ein grünes Häkchen zeigt an, dass der Dienst aktiv ist.
5. Logs: Klicken Sie auf den Tab „Logs“. Suchen Sie nach Einträgen wie "Processing file: gs://..." und "Successfully inserted...".

BigQuery

Ziel: Prüfen, ob die Daten tatsächlich gespeichert sind.

1. Rufen Sie BigQuery > SQL-Arbeitsbereich auf.
2. Maximieren Sie im Bereich „Explorer“ Ihr Projekt > Dataset „document_processing“.
3. Klicken Sie auf die Tabelle processed_metadata.
4. Klicken Sie auf den Tab Abfrage und rufen Sie alle Zeilen aus der Tabelle mit der Anweisung SELECT * ab.
5. Prüfen Sie, ob Zeilen mit filename, process_timestamp, tags und word_count angezeigt werden.

7. Anwendung kennenlernen

An diesem Punkt haben Sie die grundlegende App bereitgestellt und sie wird ausgeführt. Bevor Sie diese Anwendung weiter erweitern, nehmen Sie sich einen Moment Zeit, um den Code zu untersuchen. Sie können die Artefakte ansehen und die generierten Codedateien sollten angezeigt werden.

Hier eine kurze Zusammenfassung der Dateien, die Sie möglicherweise sehen:

1. deploy.sh: Das Hauptskript, das alle Google Cloud-Ressourcen bereitstellt und die erforderlichen APIs aktiviert.
2. appy.py: Der Haupteinstiegspunkt der Pipeline. Diese Python-App erstellt einen Webserver, der Pub/Sub-Push-Nachrichten empfängt, die Datei aus GCS herunterlädt, sie „verarbeitet“ (simuliert OCR) und die Metadaten in BigQuery streamt.
3. Dockerfile: Definiert, wie die App in ein Container-Image verpackt wird.
4. requirements.txt: Listet die Python-Abhängigkeiten auf.

Möglicherweise werden auch andere Skripts und Textdateien angezeigt, die für Tests und die Bestätigung erforderlich sind.

8. Anwendung erweitern

Nachdem Sie nun eine funktionierende grundlegende Anwendung haben, können Sie sie weiter iterieren und erweitern. Hier einige Ideen:

Frontend hinzufügen

Erstellen Sie eine einfache Weboberfläche, um die verarbeiteten Dokumente anzusehen.

Probieren Sie den folgenden Prompt aus: 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

Mit echter KI/ML integrieren

Verwenden Sie anstelle der simulierten OCR-Verarbeitung Gemini-Modelle, um Text zu extrahieren, zu klassifizieren und zu übersetzen.

1. Ersetzen Sie die Dummy-OCR-Logik. Senden Sie das Bild/die PDF-Datei an Gemini, um den tatsächlichen Text und die Daten zu extrahieren. Analysieren Sie den extrahierten Text, um den Dokumenttyp zu klassifizieren (Rechnung, Vertrag, Lebenslauf) oder Entitäten zu extrahieren (Daten, Namen, Orte).
2. Erkennen Sie automatisch die Sprache des Dokuments und übersetzen Sie es ins Englische, bevor Sie es speichern. Sie können auch eine andere Sprache verwenden.

Speicher und Analysen verbessern

Sie können Lebenszyklusregeln für den Bucket konfigurieren, um alte Dateien in den Speicher „Coldline“ oder „Archiv“ zu verschieben und so Kosten zu sparen.

Robustheit und Sicherheit

Sie können die App robuster und sicherer machen, z. B. so:

1. Dead-Letter-Warteschlangen (DLQ): Aktualisieren Sie das Pub/Sub-Abo, um Fehler zu verarbeiten. Wenn der Cloud Run-Dienst eine Datei fünfmal nicht verarbeiten kann, senden Sie die Nachricht zur manuellen Überprüfung an ein separates Dead-Letter-Thema oder einen separaten Dead-Letter-Bucket.
2. Secret Manager: Wenn Ihre App API-Schlüssel oder vertrauliche Konfigurationen benötigt, speichern Sie sie in Secret Manager und greifen Sie sicher von Cloud Run aus darauf zu, anstatt Strings fest zu codieren.
3. Eventarc: Führen Sie ein Upgrade von direktem Pub/Sub auf Eventarc durch, um eine flexiblere Ereignisweiterleitung zu ermöglichen. So können Sie Ereignisse basierend auf komplexen Audit-Logs oder anderen GCP-Dienstereignissen auslösen.

Natürlich können Sie sich eigene Ideen einfallen lassen und Antigravity verwenden, um sie zu implementieren.

9. Fazit

Sie haben mit Google Antigravity in wenigen Minuten eine skalierbare, serverlose, KI-gestützte Dokumentpipeline erstellt. Sie haben Folgendes gelernt:

• Architekturen mit KI planen
• Antigravity anweisen und verwalten, während es die Anwendung generiert, von der Codegenerierung über die Bereitstellung bis hin zur Validierung
• Bereitstellungen und Validierungen mit Walkthroughs überprüfen

Referenzdokumente

• Offizielle Website : https://antigravity.google/
• Dokumentation: https://antigravity.google/docs
• Anwendungsbeispiele : https://antigravity.google/use-cases
• Download : https://antigravity.google/download