Antigravity ile Google Cloud'da Derleme ve Dağıtım

1. Giriş

Bu codelab'de, Google Cloud'da sunucusuz bir uygulama tasarlamak, oluşturmak ve dağıtmak için Google Antigravity'yi nasıl kullanacağınızı öğreneceksiniz. Google Cloud Storage'dan (GCS) dosyaları alan, Cloud Run ve Gemini kullanarak işleyen ve meta verilerini BigQuery'ye aktaran sunucusuz ve olaya dayalı bir belge ardışık düzeni oluşturacağız.

Neler öğreneceksiniz?

• Mimari planlama ve tasarım için Antigravity'yi kullanma
• Yapay zeka ajanıyla kod olarak altyapı (kabuk komut dosyaları) oluşturun.
• Python tabanlı bir Cloud Run hizmeti oluşturup dağıtın.
• Çok formatlı belge analizi için Vertex AI'da Gemini'ı entegre edin.
• Antigravity'nin adım adım açıklamalı kılavuz yapısını kullanarak uçtan uca ardışık düzeni doğrulayın.

Gerekenler

• Google Antigravity yüklü olmalıdır.
• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• gcloud CLI yüklü ve kimliği doğrulanmış olmalıdır.

2. Uygulamaya genel bakış

Antigravity kullanarak uygulamayı tasarlayıp uygulamaya geçmeden önce, kendimiz için oluşturmak istediğimiz uygulamayı ana hatlarıyla açıklayalım.

Google Cloud Storage'dan (GCS) dosyaları alan, Cloud Run ve Gemini kullanarak işleyen ve meta verilerini BigQuery'ye aktaran sunucusuz ve etkinliğe dayalı bir doküman ardışık düzeni oluşturmak istiyoruz.

Bu uygulama için üst düzey bir mimari şeması şu şekilde görünebilir:

Bu bilgi kesin olmak zorunda değildir. Antigravity, ilerledikçe mimari ayrıntıları anlamamıza yardımcı olabilir. Ancak ne oluşturmak istediğiniz konusunda bir fikrinizin olması faydalıdır. Ne kadar çok ayrıntı verirseniz Antigravity'den mimari ve kod açısından o kadar iyi sonuçlar alırsınız.

3. Mimarinin planlanması

Antigravity ile mimari ayrıntılarını planlamaya başlamaya hazırız.

Antigravity, karmaşık sistemleri planlama konusunda uzmandır. Hemen kod yazmak yerine, üst düzey mimariyi tanımlayarak başlayabiliriz. Antigravity'nin isteğimizi değerlendirmesine, bize ek sorular sormasına ve ardından planlama ve uygulama aşamasına geçmesine yardımcı olmak için özelliklerden birini kullanabiliriz.

Antigravity'yi başlattığınızı varsayarak bu codelab için yeni bir proje oluşturacağız.

Aşağıda gösterildiği gibi Projects laboratuvarının yanındaki yeni proje simgesini ve ardından New Project simgesini tıklayın:

Bu işlemle, aşağıdaki resimde gösterildiği gibi Add Folder seçeneği gösterilir:

Projenize klasör eklemek için Klasör Ekle düğmesini tıklayın. Makinemde google-cloud-serverless-app klasörü oluşturdum ve bu klasörü projeye ekledim.

Bu işlem, google-cloud-serverless-app çalışma alanında bir görüşme açar.

Ekranın sol alt kısmındaki ana ayarlar simgesini ⚙️ tıklayın ve projeye özel ayarlara gidin. Aşağıda gösterildiği gibi Agent Settings / Security Preset değerini Default, Agent Behaviour / Artifact Review Policy değerini ise Always Ask olarak ayarlayın:

Bu sayede, temsilci planı uygulamadan önce her adımda planı inceleyip onaylayabilirsiniz.

İstem

Şimdi Antigravity'ye ilk istemimizi göndermeye hazırız. İsteğimizi değerlendirmek için eğik çizgi komutunu /grill-me kullanacağız.

/grill-me yazın, ardından aşağıdaki istemi girip gönder düğmesini tıklayın:

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

/grill-me komutu, bilginiz dahilinde yanıtlamaya çalışabileceğiniz bir dizi ek soru sorar. Ayrıca Önerilen Yanıtlar da sunar. İsterseniz bu yanıtları kullanabilirsiniz.

/grill-me komutumun örnek bir çalıştırılması aşağıda gösterilmiştir:

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

Antigravity'den şunları yapmasını istediğimi fark edin:

• Kaynak sağlamak için basit bir gcloud CLI komut dosyası
• Yerel Cloud Storage Pub/Sub bildirimleri + Cloud Run'a Pub/Sub Push aboneliği
• Çerçeve için Flask'ı (Gunicorn ile) kullanın.
• Canlı OCR verileri yerine veriler için yalnızca bir metin dosyasıyla yerel simülasyon kullanın.
• BigQuery'ye satır eklemek için BigQuery table.insert_rows() işlevini kullanma
• Kimliği doğrulanmamış Cloud Run dağıtımı

ve diğer önerilen seçenekler.

Uygulama planı ve görev listesi

Antigravity çalışmaya başlayarak bir Uygulama Planı oluşturur. Aşağıdakine benzer bir mesaj vererek planı incelemenize sunar:

Sağ üstteki pencerede Yardımcı Bölme açma/kapatma düğmesini tıklayabilir ve oluşturulan yapay nesneleri (şu anda yalnızca Uygulama Planı) görüntüleyebilirsiniz.

Bu planda şunlar belirtilir:

• Altyapı: GCS paketi, Pub/Sub konusu, BigQuery veri kümesi.
• İşlemci: Python/Flask uygulaması, Dockerfile, Requirements.
• Entegrasyon: GCS Bildirimleri → Pub/Sub → Cloud Run.

Aşağıdakine benzer bir şey görmeniz gerekir. Makinemizdeki uygulama planının kısmi bir listesi aşağıda gösterilmektedir:

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

Uygulama planını dikkatlice okuyun. Bu, uygulama hakkındaki geri bildiriminizi paylaşma fırsatınızdır. Uygulama planının herhangi bir bölümünü tıklayıp yorum ekleyebilirsiniz. Yorum ekledikten sonra, özellikle adlandırma, Google Cloud proje kimliği ve bölgeyle ilgili olarak görmek istediğiniz değişiklikleri incelemeye göndermeyi unutmayın.

Her şey yolunda göründüğünde Proceed düğmesini tıklayarak temsilciye uygulama planına devam etme izni verin.

Şimdi de Antigravity tarafından oluşturulan bir dizi görevi içeren başka bir yapay nesne olan Görev Planı'nı oluşturmaya devam ediyor. Ajan, bu görevleri tek tek inceleyip uygulayacak. Örnek bir görev listesi aşağıda gösterilmiştir:

4. Uygulamayı oluşturma

Plan onaylandıktan sonra Antigravity, temel hazırlık komut dosyalarından uygulama koduna kadar uygulama için gerekli dosyaları oluşturmaya başlar.

Antigravity bir klasör oluşturur ve proje için gerekli dosyaları oluşturmaya başlar. Yapıları kontrol ettiğinizde birkaç dosyanın (kaynak kodu, komut dosyaları vb.) oluşturulduğunu görürsünüz.

Çalışmasını tamamladığında bunu belirtir ve inceleyebileceğiniz bir Walkthrough belgesi oluşturur. Kullanıcının bir sonraki adımını belirtir. Aşağıda bir örnek verilmiştir:

• Ardışık düzeni dağıtma: GCP KSA'nıza giriş yaptığınızdan ve hedef projenizi ayarladığınızdan emin olun, ardından şu komutu çalıştırın: ./ deploy.sh
• Uçtan Uca Testi Çalıştırma: Bir dosya yüklemenin Cloud Run işleme sürecini tetiklediğini ve meta verileri BigQuery'ye aktardığını doğrulamak için bulut entegrasyonu test komut dosyasını yürütün:./test_cloud.sh
• Temizleme: Testi tamamladıktan sonra, oluşturulan kaynakları kaldırmak ve ücretlendirilmemek için README.md temizleme komutlarına bakın.

Kaynak oluşturma işlemini otomatikleştiren deploy.sh veya benzer şekilde adlandırılmış bir kabuk komut dosyası oluşturulur. Şunları işler:

1. API'leri etkinleştirme (run, pubsub, bigquery, storage).
2. Google Cloud Storage paketi oluşturuluyor (document-processing-ingest-{project-id}).
3. BigQuery veri kümesi ve tablosunu oluşturma (document_processing.processed_metadata).
4. Pub/Sub konularını ve bildirimlerini yapılandırma

5. Uygulamayı dağıtın

Uygulamayı, belirtildiği şekilde ./ deploy.sh komutuyla dağıtalım. Antigravity'den bunu bizim için çalıştırmasını isteyebiliriz ancak bunu yapmadan önce gcloud CLI'nın mevcut olduğundan ve Google Cloud projesi için yapılandırıldığından emin olun.

Antigravity'ye "deploy.sh dosyasını benim için çalıştır" istemini verebiliriz. Bu işlem için sizden izin istenir. Devam edin ve bunu verin.

Aşağıdaki mesajda açıklandığı gibi, işlemi arka plan görevi olarak başlatır:

Arka planda ./deploy.sh komutunu çalıştırarak dağıtım sürecini başlattım. Yürütme günlüklerini izleyecek ve dağıtım tamamlanır tamamlanmaz sizi bilgilendireceğim.

6. Uygulamayı doğrulama

İşlem hattı dağıtıldıktan sonra Antigravity, uygulamanın gerçekten çalıştığını doğrulamaya devam eder. test_cloud.sh dosyasını çalıştırıp çalıştıramayacağını sorar. İzin verebiliriz.

Son olarak, bize şunları söyler:

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.

Sonuçları görüntülemek için Walkthrough yapay nesnesini açabiliriz:

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.

İsteğe bağlı: Manuel doğrulama

Antigravity uygulamayı doğrulamış olsa da dilerseniz aşağıdaki adımları uygulayarak Google Cloud Console'da tüm kaynakların oluşturulup oluşturulmadığını manuel olarak da kontrol edebilirsiniz.

Cloud Storage

Amaç: Bucket'ın mevcut olduğunu doğrulayın ve yüklenen dosyaları kontrol edin.

1. Cloud Storage > Buckets'a (Cloud Storage > Paketler) gidin.
2. document-processing-ingest-{project-id} adlı paketi bulun.
3. Dosyalara göz atmak için paket adını tıklayın.
4. Doğrulama: Yüklediğiniz dosyaları (ör. cloud_test_sample.txt) görmelisiniz.

Pub/Sub

Hedef: Konunun mevcut olduğunu ve push aboneliği olduğunu doğrulayın.

1. Pub/Sub > Konular'a gidin.
2. document-uploads-topic konusunu bulun.
3. Konu kimliğini tıklayın.
4. Aşağı kaydırarak Abonelikler sekmesine gidin.
5. Doğrulama: doc-uploads-sub'ın "Push" teslimat türüyle listelendiğinden emin olun.

Cloud Run

Amaç: Hizmet durumunu ve günlüklerini kontrol edin.

1. Cloud Run'a gidin.
2. document-processor hizmetini tıklayın.
3. Doğrulama:
4. Durum: Hizmetin etkin olduğunu gösteren yeşil onay işareti.
5. Günlükler: Günlükler sekmesini tıklayın. "Processing file: gs://..." (Dosya işleniyor: gs://...) ve "Successfully inserted..." (Başarıyla eklendi...) gibi girişleri bulun.

BigQuery

Hedef: Verilerin gerçekten depolandığını doğrulayın.

1. BigQuery > SQL Çalışma Alanı'na gidin.
2. Gezgin bölmesinde proje > document_processing veri kümenizi genişletin.
3. processed_metadata tablosunu tıklayın.
4. Sorgu sekmesini tıklayın ve SELECT * ifadesiyle tablodaki tüm satırları alın.
5. Doğrulama: filename, process_timestamp, tags ve word_count içeren satırlar görmelisiniz.

7. Uygulamayı keşfetme

Bu noktada, temel uygulama sağlanmış ve çalışıyor durumdadır. Bu uygulamayı daha fazla genişletmeye başlamadan önce kodu inceleyin. Artifacts'i görüntüleyebilirsiniz. Burada oluşturulan kod dosyaları gösterilir.

Görebileceğiniz dosyaların kısa bir özetini aşağıda bulabilirsiniz:

1. deploy.sh: Tüm Google Cloud kaynaklarını sağlayan ve gerekli API'leri etkinleştiren ana komut dosyası.
2. appy.py: Ardışık düzenin ana giriş noktası. Bu Python uygulaması, Pub/Sub anlık iletilerini alan, dosyayı GCS'den indiren, "işleyen" (OCR'yi simüle eden) ve meta verileri BigQuery'ye aktaran bir web sunucusu oluşturur.
3. Dockerfile: Uygulamanın bir kapsayıcı resmine nasıl paketleneceğini tanımlar.
4. requirements.txt: Python bağımlılıklarını listeler.

Test ve doğrulama için gereken diğer komut dosyalarını ve metin dosyalarını da görebilirsiniz.

8. Uygulamayı genişletme

Çalışan bir temel uygulamanız olduğuna göre, uygulamayı yinelemeye ve genişletmeye devam edebilirsiniz. Aşağıdaki önerilerden yararlanabilirsiniz.

Ön uç ekleme

İşlenen dokümanları görüntülemek için basit bir web arayüzü oluşturun.

Aşağıdaki istemi deneyin: 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

Gerçek yapay zeka/makine öğrenimi ile entegrasyon

Simüle edilmiş OCR işleme yerine, ayıklama, sınıflandırma ve çeviri için Gemini modellerini kullanın.

1. Sahte OCR mantığını değiştirin. Gerçek metin ve verileri ayıklamak için resmi/PDF'yi Gemini'a gönderin. Belge türünü (fatura, sözleşme, özgeçmiş) sınıflandırmak veya varlıkları (tarihler, adlar, konumlar) ayıklamak için ayıklanan metni analiz edin.
2. Dokümanın dilini otomatik olarak algılayıp depolamadan önce İngilizceye çevirir. Diğer dilleri de kullanabilirsiniz.

Depolama ve analiz özelliklerini geliştirme

Maliyetten tasarruf etmek için eski dosyaları "Coldline" veya "Archive" depolama alanına taşıyacak şekilde pakette yaşam döngüsü kuralları yapılandırabilirsiniz.

Sağlamlık ve Güvenlik

Uygulamayı daha sağlam ve güvenli hale getirebilirsiniz. Örneğin:

1. Ölü Mektup Kuyrukları (DLQ): Hataları işlemek için Pub/Sub aboneliğini güncelleyin. Cloud Run hizmeti bir dosyayı 5 kez işleyemezse iletiyi insan incelemesi için ayrı bir "Ölü Mektup" konusuna/paketine gönderin.
2. Secret Manager: Uygulamanızın API anahtarlarına veya hassas yapılandırmaya ihtiyacı varsa bunları Secret Manager'da depolayın ve dizeleri sabit kodlamak yerine Cloud Run'dan güvenli bir şekilde erişin.
3. Eventarc: Daha esnek etkinlik yönlendirme için doğrudan Pub/Sub'dan Eventarc'a yükseltin. Bu sayede, karmaşık denetim günlüklerine veya diğer GCP hizmeti etkinliklerine göre tetikleme yapabilirsiniz.

Elbette kendi fikirlerinizi de üretebilir ve bunları uygulamak için Antigravity'den yardım alabilirsiniz.

9. Sonuç

Google Antigravity'yi kullanarak dakikalar içinde ölçeklenebilir, sunucusuz ve yapay zeka destekli bir doküman ardışık düzeni oluşturdunuz. Şunları öğrendiniz:

• Yapay zeka ile mimariler planlayın.
• Antigravity'yi, kod oluşturmadan dağıtıma ve doğrulamaya kadar uygulama oluşturma sürecinde yönlendirin ve yönetin.
• Dağıtımları ve doğrulamayı adım adım açıklamalarla doğrulayın.

Referans belgeler

• Resmi site : https://antigravity.google/
• Belgeler: https://antigravity.google/docs
• Kullanım alanları : https://antigravity.google/use-cases
• İndirme : https://antigravity.google/download