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

1. Wprowadzenie

fca14bb9f4bb74f4.png

Z tego ćwiczenia dowiesz się, jak używać Google Antigravity do projektowania, tworzenia i wdrażania aplikacji bezserwerowej w Google Cloud. Utworzymy bezserwerowy potok dokumentów oparty na zdarzeniach, który będzie pozyskiwać pliki z Google Cloud Storage (GCS), przetwarzać je za pomocą Cloud Run i Gemini oraz przesyłać ich metadane do BigQuery.

Czego się nauczysz

  • Jak używać Antigravity do planowania i projektowania architektury.
  • Jak generować infrastrukturę jako kod (skrypty powłoki) za pomocą agenta AI.
  • Jak tworzyć i wdrażać usługę Cloud Run opartą na Pythonie.
  • Jak integrować Gemini w Vertex AI na potrzeby multimodalnej analizy dokumentów.
  • Jak weryfikować potok kompleksowy za pomocą artefaktu Walkthrough w Antigravity.

Czego potrzebujesz

2. Omówienie aplikacji

Zanim zaczniemy projektować i wdrażać aplikację za pomocą Antigravity, najpierw opiszmy aplikację, którą chcemy utworzyć.

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

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

3bd519cfab38258d.png

Nie musi być dokładny. Antigravity może nam pomóc w ustaleniu szczegółów architektury w trakcie pracy. Warto jednak mieć pomysł na to, co chcesz zbudować. Im więcej szczegółów podasz, tym lepsze wyniki uzyskasz w Antigravity w zakresie architektury i kodu.

3. Planowanie architektury

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

Antigravity świetnie sprawdza się w planowaniu złożonych systemów. Zamiast od razu pisać kod, możemy zacząć od zdefiniowania ogólnej architektury i użyć jednej z funkcji, aby pomóc Antigravity w ocenie naszego żądania, zadaniu nam dodatkowych pytań, a następnie w planowaniu i wdrażaniu.

Zakładając, że masz już uruchomione Antigravity, utworzymy nowy projekt na potrzeby tego ćwiczenia.

Kliknij ikonę nowego projektu obok ćwiczenia Projects (Projekty), a następnie New Project (Nowy projekt), jak pokazano poniżej:

949cd615a1ce8dc3.png

Wyświetli się opcja Add Folder (Dodaj folder), jak pokazano poniżej:

ee8ff88b71c10e9f.png

Kliknij przycisk Add Folder (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 projekcie google-cloud-serverless-app.

W lewym dolnym rogu ekranu kliknij ikonę ustawień głównych ⚙️ i otwórz ustawienia specyficzne dla projektu. Jeśli nie widzisz projektu google-cloud-serverless-app na liście, po prostu rozpocznij jedną rozmowę, a potem wróć do ustawień projektu.

Ustaw Agent Settings / Security Preset (Ustawienia agenta / Ustawienia zabezpieczeń) na Default (Domyślne), a Agent Behaviour / Artifact Review Policy (Zachowanie agenta / Zasady sprawdzania artefaktów) na Always Ask (Zawsze pytaj), jak pokazano poniżej:

b28e175be64f4390.png

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

Prompt

Możemy teraz wysł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 Prześlij:

/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 odpowiedzieć najlepiej, jak potrafisz. Sugeruje też Recommended Answers (Zalecane odpowiedzi), które możesz wybrać, jeśli chcesz.

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

Zwróć uwagę, że poprosiłem Antigravity o:

  • prosty skrypt gcloud CLI do obsługi administracyjnej zasobów,
  • natywne powiadomienia Cloud Storage Pub/Sub + subskrypcja push Pub/Sub do Cloud Run,
  • użycie Flaska (z Gunicorn) jako frameworka,
  • użycie symulacji lokalnej z plikiem tekstowym jako danych zamiast danych OCR na żywo,
  • użycie table.insert_rows() do wstawiania wierszy do BigQuery,
  • wdrożenie Cloud Run bez uwierzytelniania.

oraz inne zalecane opcje.

Plan wdrożenia i lista zadań

Antigravity zacznie teraz działać i wygeneruje Implementation Plan (Plan wdrożenia). Wyświetli komunikat podobny do tego poniżej, aby umożliwić Ci sprawdzenie:

3cc503e352eee935.png

W prawym górnym rogu okna możesz kliknąć przełącznik Auxiliary Pane (Panel pomocniczy) i wyświetlić wygenerowane artefakty, które w tym momencie obejmują tylko Implementation Plan (Plan wdrożenia).

883adedf0157a073.png

Ten plan zawiera:

  • Infrastructure (Infrastruktura): zasobnik GCS, temat Pub/Sub, zbiór danych BigQuery.
  • Processor (Procesor): aplikacja Python/Flask, Dockerfile, wymagania.
  • Integration (Integracja): powiadomienia GCS → Pub/Sub → Cloud Run.

Powinno się wyświetlić coś podobnego do tego. Poniżej znajdziesz częściową listę planu wdrożenia na naszym komputerze:

5fb0baef49bdb8b1.png

Przeczytaj go uważnie. To Twoja szansa na przekazanie opinii na temat wdrożenia. 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 (Kontynuuj), aby zezwolić agentowi na kontynuowanie planu wdrożenia.

4. Generowanie aplikacji

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

Antigravity utworzy folder i zacznie tworzyć pliki niezbędne do projektu. Jeśli sprawdzisz artefakty, zobaczysz, że generuje się kilka plików (kod źródłowy, pliki skryptów itp.).

f6f4e4473fb2a8b3.png

Gdy skończy pracę, poinformuje o tym i utworzy dokument Walkthrough (Przewodnik), który możesz przejrzeć. Poniżej znajdziesz przykładowe dane wyjściowe:

752ebdb9767a82c9.png

Dokument Walkthrough (Przewodnik) zawiera informacje o tym, co zostało wdrożone, jakie skrypty zostały wygenerowane, a co najważniejsze – jakie weryfikacje i walidacje zostały przeprowadzone. Poniżej znajdziesz częściowe dane wyjściowe dokumentu Walkthrough (Przewodnik), które obejmują weryfikację i walidację:

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

Możemy zapytać Antigravity, jak wdrożyć tę aplikację w Google Cloud. Odpowie, podając wszystkie szczegóły wymienione poniżej. Podsumowując, prosi nas o sprawdzenie, czy pakiet SDK Google Cloud jest zainstalowany i skonfigurowany w projekcie w chmurze Google Cloud. Gdy to zrobisz:

Krok 1. Włącz wymagane interfejsy GCP API

Uruchom setup_gcp.sh, aby włączyć interfejsy Cloud Run, Pub/Sub, Cloud Storage, BigQuery i Cloud Build API: ./scripts/setup_gcp.sh

Krok 2. Wdróż cały potok

Uruchom deploy.sh:

export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1"               # or your region
./scripts/deploy.sh

Co ten skrypt robi w tle:

  1. Tworzy obraz kontenera za pomocą Google Cloud Build i przenosi go do Container/Artifact Registry.
  2. Wdraża usługę w Cloud Run z odpowiednimi zmiennymi środowiskowymi (GCP_PROJECT, BQ_DATASET_ID, BQ_TABLE_ID).
  3. Tworzy zasobnik pozyskiwania Cloud Storage (gs://<PROJECT_ID>-document-ingest).
  4. Tworzy temat Pub/Sub (document-upload-events) i przyznaje GCS uprawnienia do publikowania w nim.
  5. Konfiguruje powiadomienie GCS (OBJECT_FINALIZE) w zasobniku.
  6. Tworzy subskrypcję push Pub/Sub kierowaną na adres URL usługi Cloud Run z automatycznym wycofywaniem ponownych prób.

Sugeruje też, jak przetestować potok.

Uruchom test_pipeline.sh: ./scripts/test_pipeline.sh

Spowoduje to przesłanie plików samples/sample_contract.txt i samples/sample_invoice.pdf do zasobnika, poczekanie na ich przetworzenie i uruchomienie zapytania SQL BigQuery, które wyświetli wyodrębnione metadane, liczbę słów i tagi.

5. Wdrażanie aplikacji

Wdróżmy aplikację zgodnie z instrukcjami. Możemy poprosić Antigravity o uruchomienie tego za nas, ale zanim to zrobimy, upewnij się, że gcloud CLI jest obecny i skonfigurowany w projekcie Google Cloud.

Możemy wysłać do Antigravity prompt "Deploy the application for me" (Wdróż aplikację za mnie). Spowoduje to wyświetlenie prośby o różne uprawnienia, a następnie wykonanie plików skryptów.

Rozpocznie proces jako zadanie w tle, jak wyjaśniono w wiadomości poniżej:

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

Po wdrożeniu potoku Antigravity sprawdza, czy aplikacja rzeczywiście działa. Pyta nas, czy może uruchomić plik test_pipeline.sh. Możemy zezwolić na to.

Na koniec informuje nas o tym:

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

Zaktualizował też artefakt Walkthrough (Przewodnik), aby wyświetlić wyniki (częściowa lista poniżej):

Podsumowanie wdrożenia

  • Projekt w GCP: PROJECT_ID
  • Region: REGION
  • Usługa Cloud Run: document-processor
  • Punkt końcowy Cloud Run: SERVICE_URL
  • Zasobnik Cloud Storage: gs://PROJECT_ID-document-ingest
  • Temat Pub/Sub: document-upload-events
  • Subskrypcja push Pub/Sub: document-upload-events-push-sub
  • Cel BigQuery: PROJECT_ID.document_processing.document_metadata

Weryfikacja potoku na żywo

Uruchomiliśmy skrypty/test_pipeline.sh w środowisku Google Cloud na żywo:

  1. Przesłaliśmy pliki sample_contract.txt i sample_invoice.pdf do zasobnika Cloud Storage.
  2. GCS wygenerował zdarzenia OBJECT_FINALIZE w Pub/Sub.
  3. Pub/Sub przesłał koperty do mikrousługi Cloud Run.
  4. Cloud Run wyodrębnił metadane, przetworzył symulowany OCR i przesłał strumieniowo rekordy do BigQuery.

Dane wyjściowe zapytania BigQuery na żywo

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

Wszystkie komponenty potoku są aktywne, sprawne i zweryfikowane w środowisku produkcyjnym.

Opcjonalnie: weryfikacja ręczna

Mimo że Antigravity już zweryfikował 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 poszukaj przesłanych plików.

  1. Otwórz Cloud Storage > Zasobniki.
  2. Znajdź zasobnik o nazwie PROJECT_ID-document-processing.
  3. Kliknij nazwę zasobnika, aby przejrzeć pliki.
  4. Sprawdź: powinny się wyświetlić przesłane pliki (np. sample_contract.txt).

Pub/Sub

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

  1. Otwórz Pub/Sub > Tematy.
  2. Znajdź document-uploads-events.
  3. Kliknij identyfikator tematu.
  4. Przewiń w dół do karty Subskrypcje.
  5. Sprawdź: upewnij się, że na liście znajduje się doc-uploads-events-push-sub.

Cloud Run

Cel: sprawdź stan usługi i dzienniki.

  1. Otwórz Cloud Run.
  2. Kliknij usługę document-processor.
  3. Sprawdź:
  4. Stan: zielony znacznik wyboru oznacza, że usługa jest aktywna.
  5. Dzienniki: kliknij kartę Dzienniki. Poszukaj wpisów takich jak „Processing document: gs://...” (Przetwarzanie dokumentu: gs://...) i „Successfully streamed metadata...” (Metadane zostały przesłane strumieniowo).

BigQuery

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

  1. Otwórz BigQuery > Obszar roboczy SQL.
  2. W panelu Eksplorator rozwiń projekt > document_processing.
  3. Kliknij tabelę document_metadata.
  4. Kliknij kartę Zapytanie i pobierz wszystkie wiersze z tabeli za pomocą instrukcji SELECT *.
  5. Sprawdź: powinny się wyświetlić wiersze zawierające file_name (nazwa_pliku), process_at (przetwarzanie_w), tags (tagi) i word_count (liczba_słów).

7. Szczegóły aplikacji

W tym momencie masz już podstawową aplikację, która jest obsługiwana administracyjnie i działa. Zanim zaczniesz rozszerzać tę aplikację, poświęć chwilę na zapoznanie się z kodem. Możesz wyświetlić artefakty, które powinny pokazywać wygenerowane pliki kodu.

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

  1. deploy.sh: skrypt główny, który obsługuje administracyjnie wszystkie zasoby Google Cloud i włącza wymagane interfejsy API.
  2. main.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 przesyła metadane do BigQuery.
  3. Dockerfile: określa, jak spakować aplikację w obraz kontenera.
  4. requirements.txt: zawiera listę 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 frontendu

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 (Utwórz prostą aplikację internetową Streamlit lub Flask, która łączy się z BigQuery. Powinna wyświetlać tabelę przetworzonych dokumentów (nazwa_pliku, data_przesłania, tagi, liczba_słów) i umożliwiać filtrowanie wyników według tagu).

Integracja z prawdziwą AI/ML

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

  1. Zastąp logikę fikcyjnego OCR. Wyślij obraz lub plik PDF do Gemini, aby wyodrębnić rzeczywisty tekst i dane. Przeanalizuj wyodrębniony tekst, aby sklasyfikować typ dokumentu (faktura, umowa, CV) lub wyodrębnić encje (daty, nazwy, lokalizacje).
  2. Automatycznie wykrywaj język dokumentu i tłumacz go na angielski przed zapisaniem. Możesz też użyć dowolnego innego języka.

Ulepszanie przechowywania i analizy

Możesz skonfigurować reguły cyklu życia w zasobniku, aby przenosić stare pliki do pamięci „Coldline” lub „Archive”, co pozwoli Ci zaoszczędzić.

Niezawodność i bezpieczeństwo

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

  1. Kolejki niedostarczonych wiadomości (DLQ): zaktualizuj subskrypcję Pub/Sub, aby obsługiwać awarie. Jeśli usługa Cloud Run nie przetworzy pliku 5 razy, wyślij wiadomość do osobnego tematu lub zasobnika „Dead Letter” (Niedostarczone wiadomości) w celu sprawdzenia przez człowieka.
  2. Secret Manager: jeśli Twoja aplikacja potrzebuje kluczy interfejsu API lub poufnej konfiguracji, przechowuj je w Secret Manager i bezpiecznie uzyskuj do nich dostęp z Cloud Run zamiast zakodowywać ciągi.
  3. Eventarc: przejdź z bezpośredniego Pub/Sub na Eventarc, aby uzyskać bardziej elastyczne routing zdarzeń, co pozwoli Ci wywoływać zdarzenia na podstawie złożonych dzienników audytu lub innych zdarzeń usługi GCP.

Oczywiście możesz też wymyślić własne pomysły i użyć Antigravity, aby je zrealizować.

9. Podsumowanie

Udało Ci się utworzyć skalowalny, bezserwerowy potok dokumentów oparty na AI w ciągu kilku minut za pomocą Google Antigravity. Dowiedziałeś(-aś) się, jak:

  • planować architektury za pomocą AI,
  • instruować Antigravity i zarządzać nim podczas generowania aplikacji, od generowania kodu po wdrożenie i walidację,
  • sprawdzać wdrożenia i walidację za pomocą przewodników.

Dokumentacja referencyjna