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

1. Giriş

Bu codelab'de, sunucusuz bir uygulamayı Google Cloud'da tasarlamak, oluşturmak ve dağıtmak için Google Antigravity'yi (belgenin geri kalanında Antigravity olarak anılacaktır) 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.

Google Cloud kredileri için: Antigravity'yi Google Cloud projeleriyle kullanmanıza yardımcı olmak için bu bağlantıyı kullanarak ücretsiz Google Cloud kredilerinizi kullanın. Krediyi etkinleştirmek ve yeni bir proje oluşturmak için buradaki talimatları uygulayabilirsiniz.

Neler öğreneceksiniz?

• Mimari planlama ve tasarım için Antigravity'yi kullanma
• Yapay zeka temsilcisiyle 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 Walkthrough yapay nesnesini kullanarak uçtan uca işlem hattını 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'yi Kullanmaya Başlama 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 başlamadan ö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ğinize dair bir fikriniz 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 mükemmeldir. Hemen kod yazmak yerine, üst düzey mimariyi tanımlayarak başlayabiliriz.

Öncelikle, Aracı Yöneticisi'nde 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.

Aracı Yöneticisi'nde bir çalışma alanı açabilir veya hızlı prototipler ve denemeler için bağımsız bir çalışma alanı olan Playground'u kullanabilirsiniz. Playground ile başlayalım.

Playground'da yeni bir görüşme başlatmak için + düğmesini tıklayın:

Bu işlem, istemi aşağıdaki gibi girebileceğiniz bir arayüz açar:

Sağ üst köşedeki ayarlar simgesini ⚙️ tıklayın ve Review Policy bölümündeki Artifact ile Terminal Command Auto Execution bölümündeki Terminal ayarlarını Request Review olarak belirleyin. 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 Planning modunda olduğundan emin olun. Model olarak Gemini Pro (High) modelini kullanacağız (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. Aracı bunları tek tek inceler:

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. 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 buna göre komut dosyaları oluşturmak için kullanması gereken çeşitli terminal komutları (gcloud, kabuk komut dosyaları vb.) ile karşılaşacaksınız. Temsilcinin 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şturma ve Cloud Run'da (main.py içinde) hizmet olarak dağıtma işlemine geçilir. Örnek bir çıkış aşağıda gösterilmektedir:

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

Bu sırada, Inbox simgesine geçebilir (sol üst köşeden) 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, işlem hattı 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 istiyorsanız Antigravity'nin doğrulama adımından ipucu alabilirsiniz. Bu adımda, Cloud Storage paketine örnek dosya yüklemek için gsutil yardımcı programı kullanılır. Örnek komut aşağıda gösterilmiştir:

gsutil cp <some-test-doc>.txt gs://<bucket-name>/

Sonuçları BigQuery'de kontrol etme

Doğrulama sürecinde, verilerin BigQuery'de kalıcı hale gelip gelmediğ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 dilerseniz aşağıdaki adımları uygulayarak Google Cloud Console'da tüm kaynakların oluşturulduğunu manuel olarak da kontrol edebilirsiniz.

Cloud Storage

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

1. Cloud Storage > Paketler'e 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).

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 öğesinin "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. "Dosya işleniyor: gs://..." ve "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 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.

Bu noktada, Playground'dan özel bir çalışma alanına/klasöre geçmek de isteyebilirsiniz. Sağ üst köşedeki ilgili düğmeyi tıklayarak bu işlemi yapabilirsiniz:

Bir klasör seçtiğinizde tüm kodlar bu klasöre taşınır ve klasör ile sohbet geçmişi kullanılarak yeni bir çalışma alanı oluşturulur.

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

İşlenmiş 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şımak üzere 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 insan incelemesi için ayrı bir "Dead Letter" 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 ü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 işlem hattı oluşturdunuz. Öğrendikleriniz:

• 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
• Codelab : Getting Started with Google Antigravity (Google Antigravity'yi Kullanmaya Başlama)