Membangun dan Men-deploy ke Google Cloud dengan Antigravity

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara menggunakan Google Antigravity untuk mendesain, membangun, dan men-deploy aplikasi serverless ke Google Cloud. Kita akan membangun pipeline dokumen serverless dan berbasis peristiwa yang menyerap file dari Google Cloud Storage (GCS), memprosesnya menggunakan Cloud Run dan Gemini, serta mengalirkan metadatanya ke BigQuery.

Yang akan Anda pelajari

• Cara menggunakan Antigravity untuk perencanaan dan desain arsitektur.
• Buat infrastruktur sebagai kode (skrip shell) dengan agen AI.
• Buat dan deploy layanan Cloud Run berbasis Python.
• Mengintegrasikan Gemini di Vertex AI untuk analisis dokumen multimodal.
• Verifikasi pipeline end-to-end menggunakan artefak Walkthrough Antigravity.

Yang Anda butuhkan

• Google Antigravity terinstal.
• Project Google Cloud yang mengaktifkan penagihan.
• gcloud CLI terinstal dan terautentikasi.

2. Ringkasan aplikasi

Sebelum kita mulai merancang dan menerapkan aplikasi menggunakan Antigravity, mari kita uraikan terlebih dahulu aplikasi yang ingin kita buat.

Kita ingin membangun pipeline dokumen tanpa server dan berbasis peristiwa yang menyerap file dari Google Cloud Storage (GCS), memprosesnya menggunakan Cloud Run dan Gemini, serta mengalirkan metadatanya ke BigQuery.

Diagram arsitektur tingkat tinggi untuk aplikasi ini dapat terlihat seperti ini:

Tidak harus presisi. Antigravity dapat membantu kita mencari tahu detail arsitektur saat kita melakukannya. Namun, akan lebih baik jika kita memiliki gambaran tentang apa yang ingin dibangun. Semakin banyak detail yang dapat Anda berikan, semakin baik hasil yang akan Anda dapatkan dari Antigravity dalam hal arsitektur dan kode.

3. Merencanakan arsitektur

Kita siap mulai merencanakan detail arsitektur dengan Antigravity.

Antigravity unggul dalam merencanakan sistem yang kompleks. Daripada langsung menulis kode, kita dapat memulai dengan menentukan arsitektur tingkat tinggi dan menggunakan salah satu fitur untuk membantu Antigravity mengevaluasi permintaan kita, mengajukan pertanyaan lanjutan, lalu melanjutkan perencanaan dan implementasinya.

Dengan asumsi Anda telah meluncurkan Antigravity, kita akan membuat Project baru untuk codelab ini.

Klik ikon project baru di samping lab Projects, lalu New Project seperti yang ditunjukkan di bawah:

Tindakan ini akan memunculkan opsi Add Folder seperti yang ditunjukkan di bawah:

Klik tombol Add Folder untuk menambahkan folder ke project Anda. Di komputer saya, saya membuat folder google-cloud-serverless-app dan menambahkannya ke project ini.

Tindakan ini akan membuka percakapan di ruang kerja google-cloud-serverless-app.

Klik ikon setelan utama ⚙️di kiri bawah layar, lalu buka Project specific settings. Tetapkan Agent Settings / Security Preset ke Default dan Agent Behaviour / Artifact Review Policy ke Always Ask, seperti yang ditunjukkan di bawah:

Hal ini akan memastikan bahwa di setiap langkah, Anda akan meninjau dan menyetujui rencana sebelum agen menjalankannya.

Perintah

Sekarang, kita siap memberikan perintah pertama kita ke Antigravity. Kita akan menggunakan perintah garis miring /grill-me untuk mengevaluasi permintaan kita.

Ketik /grill-me, lalu masukkan perintah berikut dan klik tombol kirim:

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

Perintah /grill-me mengajukan sejumlah pertanyaan lanjutan yang dapat Anda coba jawab sebaik mungkin. Fitur ini juga menyarankan Jawaban yang Direkomendasikan dan Anda dapat menggunakannya jika mau.

Contoh menjalankan perintah /grill-me saya ditampilkan di bawah:

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

Perhatikan bahwa saya memilih untuk meminta Antigravity menggunakan:

• Skrip gcloud CLI sederhana untuk menyediakan resource
• Notifikasi Pub/Sub Cloud Storage Native + Langganan Push Pub/Sub ke Cloud Run
• Gunakan Flask (dengan Gunicorn) untuk framework
• Cukup gunakan simulasi lokal dengan file teks untuk data, bukan data OCR langsung
• Menggunakan BigQuery table.insert_rows() untuk menyisipkan baris ke BigQuery
• Deployment Cloud Run yang tidak diautentikasi

dan opsi lain yang direkomendasikan.

Rencana Penerapan dan Daftar Tugas

Antigravity kini akan mulai bekerja dan membuat Rencana Penerapan. Google akan menampilkannya untuk Anda tinjau dengan memberi Anda pesan yang mirip dengan pesan di bawah:

Anda dapat mengklik tombol Panel Tambahan di jendela kanan atas dan melihat Artefak yang dihasilkan, yang pada saat ini hanyalah Rencana Penerapan.

Rencana ini menguraikan:

• Infrastructure: Bucket GCS, Topik Pub/Sub, Set Data BigQuery.
• Processor: Aplikasi Python/Flask, Dockerfile, Persyaratan.
• Integrasi: Notifikasi GCS → Pub/Sub → Cloud Run.

Anda akan melihat sesuatu yang mirip dengan berikut ini. Daftar sebagian rencana penerapan di mesin kami ditampilkan di bawah:

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

Baca dengan cermat. Ini adalah kesempatan Anda untuk memberikan masukan terkait penerapan fitur ini. Anda dapat mengklik bagian mana pun dari rencana penerapan dan menambahkan komentar. Setelah menambahkan beberapa komentar, pastikan untuk mengirimkan perubahan yang ingin Anda lihat untuk ditinjau, terutama terkait penamaan, ID project Google Cloud, region, dll.

Setelah semuanya terlihat baik, beri agen izin untuk melanjutkan rencana penerapan dengan mengklik tombol Proceed.

Catatan: Terkadang Anda mungkin tidak melihat tombol Lanjutkan dan Antigravity dapat dilanjutkan tanpa menunggu input Anda.

Sekarang, agen akan melanjutkan dengan membuat artefak Rencana Tugas lain, yang berisi serangkaian tugas yang telah dibuat oleh Antigravity. Agen akan meninjaunya satu per satu dan mengeksekusinya. Contoh daftar tugas ditampilkan di bawah:

4. Buat aplikasi

Setelah rencana disetujui, Antigravity akan mulai membuat file yang diperlukan untuk aplikasi, mulai dari skrip penyediaan hingga kode aplikasi.

Catatan: Anda akan diminta untuk menjalankan beberapa perintah terminal (gcloud, skrip shell, dll.) yang akan digunakan agen untuk memahami lingkungan, lalu membuat skrip yang sesuai. Klik tombol Submit untuk membuat agen melanjutkan proses. Meskipun lab ini mencakup nama file tertentu yang dihasilkan, Anda mungkin menemukan Antigravity menghasilkan nama file yang berbeda, meskipun maksud dan konten file tersebut harus serupa.

Antigravity akan membuat folder dan mulai membuat file yang diperlukan untuk project. Jika Anda memeriksa Artefak, Anda akan melihat beberapa file (kode sumber, file skrip, dll.) yang dihasilkan.

Setelah menyelesaikan tugasnya, Gemini akan menyebutkannya dan membuat dokumen Panduan yang dapat Anda lihat. Karena menyebutkan langkah berikutnya yang harus dilakukan pengguna, contohnya diberikan di bawah:

• Deploy Pipeline: Pastikan Anda telah login ke GCP CLI dan menetapkan project target, lalu jalankan: ./ deploy.sh
• Jalankan Uji Coba End-to-End: Jalankan skrip uji coba integrasi cloud untuk memverifikasi bahwa upload file memicu pemrosesan Cloud Run dan mengalirkan metadata ke BigQuery:./test_cloud.sh
• Pembersihan: Setelah selesai menguji, lihat perintah pembersihan README.md untuk menghapus resource yang dibuat dan menghindari biaya.

Anda akan menemukan file skrip shell deploy.sh atau yang namanya serupa dibuat, yang mengotomatiskan pembuatan resource. API ini menangani:

1. Mengaktifkan API (run, pubsub, bigquery, storage).
2. Membuat bucket Google Cloud Storage (document-processing-ingest-{project-id}).
3. Membuat set data dan tabel BigQuery (document_processing.processed_metadata).
4. Mengonfigurasi topik dan notifikasi Pub/Sub.

5. Men-deploy aplikasi

Mari kita deploy aplikasi seperti yang disebutkan melalui perintah ./ deploy.sh. Kita dapat meminta Antigravity untuk menjalankan ini bagi kita, tetapi sebelum melakukannya, pastikan gcloud CLI ada dan dikonfigurasi untuk Project Google Cloud.

Kita dapat memberikan perintah ke Antigravity "Run the deploy.sh for me". Anda akan diminta memberikan izin. Lanjutkan dan berikan itu.

Proses ini dimulai sebagai tugas latar belakang, seperti yang dijelaskan oleh pesan di bawah:

Saya telah memulai proses deployment dengan menjalankan ./deploy.sh di latar belakang. Kami akan memantau log eksekusi dan memberi tahu Anda segera setelah deployment selesai.

6. Verifikasi aplikasi

Setelah pipeline di-deploy, Antigravity akan memverifikasi bahwa aplikasi benar-benar berfungsi. Windows akan menanyakan apakah kita mengizinkan untuk menjalankan file test_cloud.sh. Kita dapat melanjutkan dan memberikan izin tersebut.

Pada akhirnya, kita akan mengetahui hal berikut:

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.

Kita dapat membuka artefak Panduan untuk melihat hasilnya:

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.

Opsional: Verifikasi manual

Meskipun Antigravity telah memverifikasi aplikasi, Anda juga dapat memeriksa secara manual di Konsol Google Cloud bahwa semua resource telah dibuat, jika Anda mau, dengan mengikuti langkah-langkah berikut.

Cloud Storage

Tujuan: Verifikasi keberadaan bucket dan periksa file yang diupload.

1. Buka Cloud Storage > Buckets.
2. Temukan bucket bernama document-processing-ingest-{project-id}.
3. Klik nama bucket untuk menjelajahi file.
4. Verifikasi: Anda akan melihat file yang diupload (misalnya,cloud_test_sample.txt).

Pub/Sub

Tujuan: Mengonfirmasi bahwa topik ada dan memiliki langganan push.

1. Buka Pub/Sub > Topics.
2. Temukan document-uploads-topic.
3. Klik ID topik.
4. Scroll ke bawah ke tab Langganan.
5. Verifikasi: Pastikan doc-uploads-sub tercantum dengan jenis pengiriman "Push".

Cloud Run

Tujuan: Periksa status dan log layanan.

1. Buka Cloud Run.
2. Klik layanan document-processor.
3. Verifikasi:
4. Kesehatan: Tanda centang hijau yang menunjukkan bahwa layanan aktif.
5. Log: Klik tab Logs. Cari entri seperti "Processing file: gs://..." dan "Successfully inserted...".

BigQuery

Tujuan: Memvalidasi bahwa data benar-benar disimpan.

1. Buka BigQuery > SQL Workspace.
2. Di panel Explorer, luaskan project > document_processing dataset.
3. Klik tabel processed_metadata.
4. Klik tab Query dan ambil semua baris dari tabel melalui pernyataan SELECT *.
5. Verifikasi: Anda akan melihat baris yang berisi filename, process_timestamp, tags, dan word_count.

7. Menjelajahi aplikasi

Pada tahap ini, Anda telah menyediakan dan menjalankan aplikasi dasar. Sebelum mempelajari lebih lanjut cara memperluas aplikasi ini, luangkan waktu untuk menjelajahi kode. Anda dapat melihat Artefak dan artefak tersebut akan menampilkan file kode yang dihasilkan.

Berikut ringkasan singkat file yang mungkin Anda lihat:

1. deploy.sh: Skrip utama yang menyediakan semua resource Google Cloud dan mengaktifkan API yang diperlukan.
2. appy.py: Titik entri utama pipeline. Aplikasi Python ini membuat server web yang menerima pesan push Pub/Sub, mendownload file dari GCS, "memproses" (mensimulasikan OCR), dan melakukan streaming metadata ke BigQuery.
3. Dockerfile: Menentukan cara mengemas aplikasi ke dalam image container.
4. requirements.txt: Mencantumkan dependensi Python.

Anda juga mungkin melihat skrip dan file teks lain yang diperlukan untuk pengujian dan verifikasi.

8. Memperluas aplikasi

Setelah memiliki aplikasi dasar yang berfungsi, Anda dapat terus melakukan iterasi dan memperluas aplikasi. Berikut beberapa ide.

Menambahkan frontend

Buat antarmuka web sederhana untuk melihat dokumen yang diproses.

Coba perintah berikut: 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

Terintegrasi dengan AI/ML sungguhan

Daripada pemrosesan OCR simulasi, gunakan model Gemini untuk mengekstrak, mengklasifikasikan, dan menerjemahkan.

1. Ganti logika OCR dummy. Kirim gambar/PDF ke Gemini untuk mengekstrak teks dan data yang sebenarnya. Menganalisis teks yang diekstrak untuk mengklasifikasikan jenis dokumen (invoice, kontrak, resume) atau mengekstrak entity (tanggal, nama, lokasi).
2. Mendeteksi bahasa dokumen secara otomatis dan menerjemahkannya ke dalam bahasa Inggris sebelum menyimpannya. Anda juga dapat menggunakan bahasa lain.

Meningkatkan penyimpanan & analisis

Anda dapat mengonfigurasi aturan siklus proses di bucket untuk memindahkan file lama ke penyimpanan "Coldline" atau "Archive" guna menghemat biaya.

Keandalan & Keamanan

Anda dapat membuat aplikasi lebih andal dan aman seperti:

1. Antrean Pesan yang Dihentikan Pengirimannya (DLQ): Perbarui langganan Pub/Sub untuk menangani kegagalan. Jika layanan Cloud Run gagal memproses file sebanyak 5 kali, kirim pesan ke topik/bucket "Dead Letter" terpisah untuk diperiksa oleh manusia.
2. Secret Manager: Jika aplikasi Anda memerlukan kunci API atau konfigurasi sensitif, simpan di Secret Manager dan akses dengan aman dari Cloud Run, bukan meng-hardcode string.
3. Eventarc: Lakukan upgrade dari Pub/Sub langsung ke Eventarc untuk perutean peristiwa yang lebih fleksibel, sehingga Anda dapat memicu berdasarkan log audit yang kompleks atau peristiwa layanan GCP lainnya.

Tentu saja, Anda dapat membuat ide Anda sendiri dan menggunakan Antigravitasi untuk membantu Anda menerapkannya.

9. Kesimpulan

Anda telah berhasil membangun pipeline dokumen yang skalabel, serverless, dan didukung AI dalam hitungan menit menggunakan Google Antigravity. Anda telah mempelajari cara:

• Merencanakan arsitektur dengan AI.
• Instruksikan dan kelola Antigravity saat ia bekerja melalui pembuatan aplikasi dari pembuatan kode hingga deployment dan validasi.
• Verifikasi deployment dan validasi dengan Panduan.

Dokumen referensi

• Situs Resmi : https://antigravity.google/
• Dokumentasi: https://antigravity.google/docs
• Kasus penggunaan : https://antigravity.google/use-cases
• Download : https://antigravity.google/download