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

1. Giriş

Bu codelab'de, Google Cloud'da sunucusuz bir uygulamayı 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 etkinliğe 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şturun ve 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. Antigravity'yi yükleme ve temel bilgileri anlama konusunda yardıma ihtiyacınız varsa Google Antigravity'ye Giriş adlı codelab'i tamamlamanız önerilir.
• 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 değerin tam olması gerekmez. 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 planlamada mükemmeldir. Hemen kod yazmak yerine, üst düzey mimariyi tanımlayarak başlayabiliriz.

Öncelikle, Agent Manager'da olduğunuzdan emin olun. Antigravity'yi yeni açtıysanız ortadaki Open Agent Manager düğmesini tıklayabilir veya sağ üst köşede aynı Open Agent Manager düğmesini görebilirsiniz.

Öncelikle uygulama için bir klasör oluşturun (ör. document-pipeline) ve bunu Agent Manager'da çalışma alanı olarak ekleyin:

Ajan Yöneticisi'nde document-pipeline çalışma alanında bir görüşme başlatın. Plan modunun da etkinleştirildiğinden emin olun:

Sağ üst köşedeki ayarlar simgesini ⚙️ tıklayın ve Artifact bölümündeki Review Policy seçeneğini Asks for Review, Terminal bölümündeki Terminal Command Auto Execution seçeneğini ise Request Review olarak ayarlayın. Bu sayede, temsilci planı uygulamadan önce her adımda planı inceleyip onaylayabilirsiniz.

İstem

Artık Antigravity'ye ilk istemimizi göndermeye hazırız.

Öncelikle, Antigravity'nin Plan modunda olduğundan emin olun. Model olarak Gemini Pro (High) modelini seçelim (ancak diğer modellerle deneme yapmaktan çekinmeyin).

Aşağıdaki istemi girin ve gönder düğmesini tıklayın:

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. 

Görev Listesi ve Uygulama Planı

Antigravity, isteğinizi analiz ederek bir Görev listesi ve Uygulama Planı oluşturur.

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 ifade görürsünüz:

Task satırının yanındaki Open düğmesini tıklayın. Bu işlem, Antigravity tarafından oluşturulan bir dizi görevi gösterir. Temsilci bunları tek tek inceleyecektir:

Bir sonraki adım, uygulama planını incelemek ve temsilciye devam etmesi için izin vermektir.

Ayrıntılarını görmek için uygulama planını tıklayın. Bu makaleyi dikkatlice okuyun. Bu, uygulama hakkında geri bildirimde bulunabileceğiniz bir fırsattır. Uygulama planının herhangi bir bölümünü tıklayıp yorum ekleyebilirsiniz. Bazı yorumlar ekledikten sonra, özellikle adlandırma, Google Cloud proje kimliği ve bölgeyle ilgili olmak üzere görmek istediğiniz tüm değişiklikleri incelemeye gönderdiğinizden emin olun.

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

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.

Not: Aracı, ortamı anlamak ve komut dosyalarını buna göre oluşturmak için kullanması gereken çeşitli terminal komutları (gcloud, kabuk komut dosyaları vb.) ile ilgili istemler gösterir. Ajanın ilerlemesini sağlamak için Accept düğmesini tıklayın. Bu laboratuvarda oluşturulan belirli dosya adları ele alınsa da Antigravity'nin farklı dosya adları oluşturduğunu görebilirsiniz. Ancak dosyaların amacı ve içeriği benzer olmalıdır.

Antigravity bir klasör oluşturur ve proje için gerekli dosyaları oluşturmaya başlar. Örnek çalıştırmamızda şunları gördük:

Kaynak oluşturma işlemini otomatikleştiren bir setup.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şturma (doc-ingestion-{project-id}).
3. BigQuery veri kümesi ve tablosunu oluşturma (pipeline_data.processed_docs).
4. Pub/Sub konularını ve bildirimlerini yapılandırma

Temsilci, Pub/Sub anlık iletilerini dinleyen bir Python uygulaması (main.py) oluşturmalıdır. Bu işlev, rastgele kelime sayıları ve etiketler oluşturup bunları BigQuery'de kalıcı hale getiren simüle edilmiş bir OCR mantığı kullanır.

Bu kurulum komut dosyası oluşturulduktan sonra Antigravity, komut dosyasını sizin adınıza çalıştırmanızı ister. Örnek ekran aşağıda gösterilmiştir:

Gerekirse Accept simgesini tıklayın.

Sağlama komut dosyası, kaynakları oluşturur ve oluşturulduklarını doğrular. Kontrol başarılı olursa kapsayıcı oluşturulur ve Cloud Run'da hizmet olarak (main.py içinde) dağıtılır. Örnek bir çıkış aşağıda gösterilmektedir:

Hizmetin dağıtılması kapsamında, bu ardışık düzenin çalışması için gereken Pub/Sub abonelikleri ve diğer yapıştırıcılar da ayarlanır. Tüm bu işlemler birkaç dakika sürer.

Bu sırada, sol üst köşeden Inbox simgesine geçebilir ve girişinizi bekleyen Pending görevleri kontrol edebilirsiniz:

Bu, temsilci geri bildirim isterken görevleri onaylamanızı sağlayan iyi bir yöntemdir.

5. Uygulamayı doğrulama

Antigravity, ardışık düzen dağıtıldıktan sonra uygulamanın gerçekten çalıştığını doğrular. Antigravity, görev listesindeki doğrulama adımlarıyla bu işlemi otomatikleştirir. Örnek ekran aşağıda gösterilmiştir:

Test yapısı (test.txt) oluşturur ve bunu Google Cloud Storage paketine yüklemek ister. Devam etmek için Accept simgesini tıklayın.

Kendi başınıza başka testler yapmak isterseniz Cloud Storage paketine örnek bir dosya yüklemeyi deneyebilirsiniz:

gcloud storage cp <some-test-doc>.txt gs://doc-ingestion-{project-id}/

Sonuçları BigQuery'de kontrol etme

Doğrulama süreci kapsamında, verilerin BigQuery'de kalıcı hale getirilip getirilmediği de kontrol edilir.

Dokümanları kontrol etmek için kullanılan SQL sorgusunu not edin.

Doğrulama tamamlandığında görev listesinin tamamlandığını görürsünüz:

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

Antigravity uygulamayı doğrulamış olsa da isterseniz 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. [PROJECT_ID]-doc-uploads adlı paketi bulun.
3. Dosyalara göz atmak için paket adını tıklayın.
4. Doğrulama: Yüklediğiniz dosyaları (ör. test.txt) görmeniz gerekir.

Pub/Sub

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

1. Pub/Sub > Konular'a gidin.
2. doc-processing-topic konusunu bulun.
3. Konu kimliğini tıklayın.
4. Aşağı kaydırarak Abonelikler sekmesine gidin.
5. Doğrulama: doc-processing-sub'un "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. doc-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 processed..." (Başarıyla işlendi...) 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 project > pipeline_data veri kümenizi genişletin.
3. processed_docs tablosunu tıklayın.
4. Önizleme sekmesini tıklayın.
5. Doğrulama: filename, upload_date, tags ve word_count değerlerini içeren satırlar görmelisiniz.

Adım adım açıklamalı kılavuz

Son adım olarak Antigravity, bir rehberlik artefaktı oluşturur. Bu yapı, aşağıdakileri özetler:

• Değişiklikler yapıldı.
• Doğrulama komutları çalıştırılır.
• Gerçek sonuçlar (Gemini'ın ayıkladığı meta verileri gösteren sorgu çıkışı).

Bu bilgiyi görmek için Open simgesini tıklayabilirsiniz. Örnek bir çıkış aşağıda gösterilmektedir:

6. 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. Sağ üst köşedeki Open Editor düğmesini kullanarak düzenleyiciye geçebilirsiniz.

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

1. setup.sh: Tüm Google Cloud kaynaklarını sağlayan ve gerekli API'leri etkinleştiren ana komut dosyası.
2. main.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.

7. Uygulamayı genişletme

Çalışan bir temel uygulamanız olduğuna göre yinelemeye ve uygulamayı 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. Dead Letter Queues (DLQ): Hataları işlemek için Pub/Sub aboneliğini güncelleyin. Cloud Run hizmeti bir dosyayı 5 kez işlemeyi başarısız olursa iletiyi ayrı bir "Dead Letter" konusuna/paketine göndererek insan incelemesine sunun.
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 üretebilir ve bunları uygulamak için Antigravity'den yardım alabilirsiniz.

8. Sonuç

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

• Yapay zeka ile mimarileri planlayın.
• Antigravity'yi, kod oluşturmadan dağıtıma ve doğrulamaya kadar uygulama oluşturma sürecinde yönlendirin ve yönetin.
• Adım adım açıklamalarla dağıtımları ve doğrulamayı 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
• Codelab : Google Antigravity'ye Giriş