Kompilowanie i wdrażanie w Google Cloud za pomocą Antigravity

1. Wprowadzenie

Z tego ćwiczenia dowiesz się, jak za pomocą Google Antigravity zaprojektować, utworzyć i wdrożyć w Google Cloud aplikację bezserwerową. Utworzymy bezserwerowy potok dokumentów oparty na zdarzeniach, który będzie pobierać pliki z Google Cloud Storage (GCS), przetwarzać je za pomocą Cloud Run i Gemini oraz przesyłać strumieniowo ich metadane do BigQuery.

Czego się nauczysz

• Jak korzystać z Antigravity do planowania i projektowania architektonicznego.
• Generowanie infrastruktury jako kodu (skryptów powłoki) za pomocą agenta AI.
• skompilować i wdrożyć usługę Cloud Run opartą na Pythonie;
• Integrowanie Gemini w Vertex AI na potrzeby multimodalnej analizy dokumentów.
• Sprawdź kompleksową ścieżkę za pomocą artefaktu Antigravity Walkthrough.

Czego potrzebujesz

• Google Antigravity jest zainstalowana.
• Projekt Google Cloud z włączonymi płatnościami.
• Zainstalowany i uwierzytelniony gcloud CLI.

2. Omówienie aplikacji

Zanim przejdziemy do projektowania i wdrażania aplikacji za pomocą Antigravity, najpierw opiszemy aplikację, którą chcemy utworzyć.

Chcemy utworzyć bezserwerowy potok dokumentów oparty na zdarzeniach, który będzie pobierać pliki z Google Cloud Storage (GCS), przetwarzać je za pomocą Cloud Run i Gemini oraz przesyłać strumieniowo ich metadane do BigQuery.

Ogólny schemat architektury tej aplikacji może wyglądać tak:

Nie musi to być precyzyjne. Antigravity pomoże nam określić szczegóły architektury w trakcie pracy. Warto jednak mieć pomysł na to, co chcesz zbudować. Im więcej szczegółów podasz, tym lepsze wyniki uzyskasz z Antigravity w zakresie architektury i kodu.

3. Zaplanuj architekturę

Możemy zacząć planować szczegóły architektury za pomocą Antigravity.

Antigravity świetnie radzi sobie z planowaniem złożonych systemów. Zamiast od razu pisać kod, możemy zacząć od zdefiniowania architektury wysokiego poziomu i użyć jednej z funkcji, aby pomóc Antigravity ocenić naszą prośbę, zadać nam dodatkowe pytania, a następnie przejść do planowania i wdrażania.

Zakładamy, że Antigravity jest już uruchomiony. W tym samouczku utworzymy nowy projekt.

Kliknij ikonę nowego projektu obok laboratorium Projects, a potem New Project, jak pokazano poniżej:

Spowoduje to wyświetlenie opcji Add Folder, jak pokazano poniżej:

Kliknij przycisk Dodaj folder, aby dodać folder do projektu. Na moim komputerze utworzyłem folder google-cloud-serverless-app i dodałem go do tego projektu.

Spowoduje to otwarcie rozmowy w obszarze roboczym google-cloud-serverless-app.

W lewym dolnym rogu ekranu kliknij ikonę ustawień głównych ⚙️ i otwórz ustawienia projektu. Ustaw Agent Settings / Security Preset na Default, a Agent Behaviour / Artifact Review Policy na Always Ask, jak pokazano poniżej:

Dzięki temu na każdym etapie będziesz mieć możliwość sprawdzenia i zatwierdzenia planu przed jego wykonaniem przez agenta.

Prompt

Teraz możemy przesłać pierwszy prompt do Antigravity. Aby ocenić nasze żądanie, użyjemy polecenia po ukośniku /grill-me.

Wpisz /grill-me, a potem ten prompt i kliknij przycisk przesyłania:

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

Polecenie /grill-me zadaje kilka dodatkowych pytań, na które możesz spróbować odpowiedzieć najlepiej, jak potrafisz. Sugeruje też rekomendowane odpowiedzi, z których możesz skorzystać.

Poniżej znajdziesz przykładowe wykonanie polecenia /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).

Zwróć uwagę, że poprosiłem Antigravity o wykonanie tych czynności:

• Prosty skrypt interfejsu wiersza poleceń gcloud do udostępniania zasobów
• Natywne powiadomienia Cloud Storage Pub/Sub + subskrypcja push Pub/Sub w Cloud Run
• Używanie platformy Flask (z Gunicorn)
• Zamiast danych OCR na żywo używaj lokalnej symulacji z plikiem tekstowym zawierającym dane.
• Użyj funkcji table.insert_rows() w BigQuery, aby wstawić wiersze do BigQuery
• Nieuwierzytelnione wdrożenie Cloud Run

i inne zalecane opcje.

Plan wdrożenia i lista zadań

Antigravity zacznie teraz generować plan wdrożenia. Wyświetli się komunikat podobny do tego:

W prawym górnym rogu okna możesz kliknąć przełącznik panelu pomocniczego i wyświetlić wygenerowane artefakty, czyli w tym momencie tylko plan wdrożenia.

Ten plan zawiera:

• Infrastruktura: zasobnik GCS, temat Pub/Sub, zbiór danych BigQuery.
• Procesor: aplikacja w języku Python/Flask, Dockerfile, wymagania.
• Integracja: powiadomienia GCS → Pub/Sub → Cloud Run.

Powinna pojawić się informacja podobna do tej. Poniżej znajduje się częściowa lista planu wdrożenia na naszym urządzeniu:

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

Przeczytaj go uważnie. To Twoja szansa na przekazanie opinii o wdrożeniu. Możesz kliknąć dowolną część planu wdrożenia i dodać komentarze. Po dodaniu komentarzy prześlij do sprawdzenia wszelkie zmiany, które chcesz wprowadzić, zwłaszcza dotyczące nazewnictwa, identyfikatora projektu Google Cloud, regionu itp.

Gdy wszystko będzie w porządku, kliknij przycisk Proceed, aby zezwolić agentowi na realizację planu wdrożenia.

Teraz tworzy kolejny artefakt, Plan zadania, który zawiera zestaw zadań utworzonych przez Antigravity. Agent będzie je wykonywać po kolei. Przykładowa lista zadań:

4. Generowanie aplikacji

Po zatwierdzeniu planu Antigravity zaczyna generować pliki wymagane do aplikacji, od skryptów do obsługi po kod aplikacji.

Antigravity utworzy folder i rozpocznie tworzenie plików niezbędnych do projektu. Jeśli sprawdzisz artefakty, zobaczysz kilka wygenerowanych plików (kod źródłowy, pliki skryptów itp.).

Po zakończeniu pracy poinformuje o tym i utworzy dokument Przewodnik, który możesz przejrzeć. Zawiera on następny krok dla użytkownika. Przykładowy dokument znajdziesz poniżej:

• Wdróż potok: zaloguj się w interfejsie wiersza poleceń GCP i ustaw projekt docelowy, a następnie uruchom to polecenie: ./ deploy.sh
• Uruchom test kompleksowy: wykonaj scenariusz testowania integracji z chmurą, aby sprawdzić, czy przesłanie pliku wywołuje przetwarzanie w Cloud Run i przesyła strumieniowo metadane do BigQuery:./test_cloud.sh
• Czyszczenie: po zakończeniu testowania zapoznaj się z README.md poleceniami czyszczenia, aby usunąć utworzone zasoby i uniknąć opłat.

Zostanie wygenerowany plik skryptu powłoki o nazwie deploy.sh lub podobnej, który automatyzuje tworzenie zasobów. Zajmuje się on:

1. Włączanie interfejsów API (run, pubsub, bigquery, storage).
2. Tworzenie zasobnika Google Cloud Storage (document-processing-ingest-{project-id}).
3. Utworzenie zbioru danych i tabeli BigQuery (document_processing.processed_metadata).
4. Konfigurowanie tematów i powiadomień Pub/Sub.

5. Wdrażanie aplikacji

Wdróżmy aplikację w sposób opisany w poleceniu ./ deploy.sh. Możemy poprosić Antigravity o uruchomienie tego za nas, ale zanim to zrobimy, upewnijmy się, że gcloud CLI jest obecny i skonfigurowany dla projektu Google Cloud.

Możemy poprosić Antigravity o wykonanie polecenia „Uruchom deploy.sh”. Pojawi się prośba o uprawnienia. Śmiało, zrób to.

Rozpoczyna proces jako zadanie w tle, o czym informuje poniższy komunikat:

Rozpocząłem proces wdrażania, uruchamiając w tle polecenie ./deploy.sh. Będę monitorować dzienniki wykonania i dam Ci znać, gdy wdrażanie się zakończy.

6. Weryfikowanie aplikacji

Po wdrożeniu potoku Antigravity sprawdza, czy aplikacja działa. Pyta, czy może uruchomić plik test_cloud.sh. Możemy udzielić jej na to pozwolenia.

W końcu dowiadujemy się, że:

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.

Możemy otworzyć artefakt Przewodnik, aby wyświetlić wyniki:

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.

Opcjonalnie: weryfikacja ręczna

Nawet jeśli Antigravity zweryfikuje aplikację, możesz też ręcznie sprawdzić w konsoli Google Cloud, czy wszystkie zasoby zostały utworzone. Aby to zrobić, wykonaj te czynności.

Cloud Storage

Cel: sprawdź, czy zasobnik istnieje, i czy są w nim przesłane pliki.

1. Otwórz Cloud Storage > Zasobniki.
2. Znajdź zasobnik o nazwie document-processing-ingest-{project-id}.
3. Kliknij nazwę zasobnika, aby przejrzeć pliki.
4. Sprawdź: powinny być widoczne przesłane pliki (np.cloud_test_sample.txt).

Pub/Sub

Cel: sprawdź, czy temat istnieje i ma subskrypcję push.

1. Otwórz Pub/Sub > Tematy.
2. Znajdź document-uploads-topic.
3. Kliknij identyfikator tematu.
4. Przewiń w dół do karty Subskrypcje.
5. Sprawdź, czy na liście znajduje się doc-uploads-sub z typem dostawy „Push”.

Cloud Run

Cel: sprawdź stan usługi i dzienniki.

1. Otwórz Cloud Run.
2. Kliknij usługę document-processor.
3. Zweryfikuj:
4. Stan: zielony znacznik wyboru oznaczający, że usługa jest aktywna.
5. Logi: kliknij kartę Logi. Poszukaj wpisów takich jak „Przetwarzanie pliku: gs://...” i „Pomyślnie wstawiono...”.

BigQuery

Cel: sprawdź, czy dane są rzeczywiście przechowywane.

1. Otwórz BigQuery > Obszar roboczy SQL.
2. W panelu Eksplorator rozwiń projekt > zbiór danych document_processing.
3. Kliknij tabelę processed_metadata.
4. Kliknij kartę Zapytanie i pobierz wszystkie wiersze z tabeli za pomocą instrukcji SELECT *.
5. Sprawdź: powinny pojawić się wiersze zawierające filename, process_timestamp, tags i word_count.

7. Poznaj aplikację

W tym momencie podstawowa aplikacja jest już udostępniona i działa. Zanim zaczniesz rozszerzać tę aplikację, poświęć chwilę na zapoznanie się z kodem. Możesz wyświetlić artefakty. Powinny się w nich znajdować wygenerowane pliki kodu.

Oto krótkie podsumowanie plików, które możesz zobaczyć:

1. deploy.sh: skrypt główny, który udostępnia wszystkie zasoby Google Cloud i włącza wymagane interfejsy API.
2. appy.py: główny punkt wejścia potoku. Ta aplikacja w Pythonie tworzy serwer WWW, który odbiera wiadomości push Pub/Sub, pobiera plik z GCS, „przetwarza” go (symuluje OCR) i strumieniuje metadane do BigQuery.
3. Dockerfile: określa sposób pakowania aplikacji w obraz kontenera.
4. requirements.txt: wyświetla zależności Pythona.

Możesz też zobaczyć inne skrypty i pliki tekstowe potrzebne do testowania i weryfikacji.

8. Rozszerzanie aplikacji

Teraz, gdy masz już działającą podstawową aplikację, możesz ją dalej rozwijać i rozszerzać. Oto kilka pomysłów.

Dodawanie interfejsu

Utwórz prosty interfejs internetowy do wyświetlania przetworzonych dokumentów.

Wypróbuj ten 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

Integracja z prawdziwą AI/ML

Zamiast symulowanego przetwarzania OCR używaj modeli Gemini do wyodrębniania, klasyfikowania i tłumaczenia.

1. Zastąp logikę testową OCR. Wyślij obraz lub plik PDF do Gemini, aby wyodrębnić tekst i dane. Analizuj wyodrębniony tekst, aby klasyfikować typ dokumentu (faktura, umowa, CV) lub wyodrębniać encje (daty, imiona i nazwiska, lokalizacje).
2. automatycznie wykrywać język dokumentu i tłumaczyć go na angielski przed zapisaniem; Możesz też użyć dowolnego innego języka.

Ulepszanie miejsca na dane i analiz

Możesz skonfigurować reguły cyklu życia w zasobniku, aby przenosić stare pliki do pamięci „Coldline” lub „Archive” i obniżyć koszty.

Odporność i bezpieczeństwo

Możesz zwiększyć niezawodność i bezpieczeństwo aplikacji, na przykład:

1. Kolejki wiadomości niedostarczonych: zaktualizuj subskrypcję Pub/Sub, aby obsługiwać błędy. Jeśli usługa Cloud Run nie przetworzy pliku 5 razy, wyślij wiadomość do osobnego tematu lub zasobnika „Niedostarczone komunikaty” w celu sprawdzenia przez człowieka.
2. Secret Manager: jeśli aplikacja potrzebuje kluczy interfejsu API lub poufnej konfiguracji, przechowuj je w Secret Manager i uzyskuj do nich bezpieczny dostęp z Cloud Run zamiast zakodowywać ciągi znaków.
3. Eventarc: uaktualnij bezpośrednie Pub/Sub do Eventarc, aby uzyskać bardziej elastyczne kierowanie zdarzeń, które umożliwia wywoływanie na podstawie złożonych dzienników audytu lub innych zdarzeń usługi GCP.

Możesz oczywiście wymyślić własne pomysły i wykorzystać Antigravity, aby je zrealizować.

9. Podsumowanie

W kilka minut udało Ci się utworzyć skalowalny, bezserwerowy potok dokumentów oparty na AI za pomocą Google Antigravity. Z tego modułu dowiedziałeś(-aś) się, jak:

• Planuj architektury z pomocą AI.
• Wydawaj instrukcje i zarządzaj Antigravity podczas generowania aplikacji od tworzenia kodu po wdrażanie i weryfikację.
• Sprawdzaj wdrożenia i weryfikację za pomocą przewodników.

Dokumentacja

• Oficjalna strona : https://antigravity.google/
• Dokumentacja: https://antigravity.google/docs
• Przykłady zastosowania : https://antigravity.google/use-cases
• Pobierz : https://antigravity.google/download