1. Giriş
Genel Bakış
Bu laboratuvarda, Eventarc ve Pub/Sub hizmetlerini kullanarak Cloud Run'da dağıtılan bir ADK aracısının etkinlik odaklı olarak güvenli bir şekilde nasıl çağrılacağı gösterilmektedir. Bir aracı en sık olarak doğrudan bir kullanıcı veya başka bir aracı tarafından çağrılır. Ancak bir aracı mevcut etkinlik tabanlı iş akışlarına entegre ederken doğrudan arama yapmak için mevcut yazılımda değişiklik yapılması gerekir. Bir etkinliğe dayalı olarak aracı çağırma işlemini tetiklemek, iş akışlarında değişiklik yapmadan mevcut iş akışlarına aracı dahil etmenizi sağlar.
Yapacaklarınız
Bu laboratuvarda, yapay zeka aracısı olan ve hayali hayvanat bahçesindeki hayvanlar hakkında bilgi sağlamak için birkaç araç kullanan bir ZooKeeper aracılı uygulaması oluşturacaksınız.
ZooKeeper uygulamasını, Google'ın altyapısında durum bilgisiz container'ları çalıştıran, tümüyle yönetilen sunucusuz bir bilgi işlem platformu olan Cloud Run'a hizmet olarak dağıtacaksınız. Ardından, Pub/Sub konusuna yayınlanan mesajları eşzamansız olarak işlemek için hizmet uç noktasını çağıran bir Eventarc tetikleyicisi ayarlarsınız. Dağıtımın, belirlenmiş IAM hizmet hesaplarının kullanılması, en az ayrıcalıklı erişimin verilmesi ve ZooKeeper uygulamasının uç noktasını yalnızca Eventarc'a sunarak olası bir saldırı yüzeyinin en aza indirilmesi gibi en iyi uygulamalara uygun olmasını sağlayacaksınız. Bu işlemi Cloud Shell ve Cloud Console'un yardımıyla yapacaksınız. Python için ADK ve Cloud SDK kitaplıklarını kullanacaksınız. Davranışı kontrol etmek için gcloud CLI'yı kullanacaksınız.
Neler öğreneceksiniz?
- ADK aracınızı Google Cloud Run'a dağıtın.
- Eventarc tetikleyicisini, Google Cloud Run'da çalışan ADK aracısıyla entegre edin.
- Google Cloud IAM'in yardımıyla en az ayrıcalıklı erişim ilkesini kullanarak Eventarc ile dağıtımınızı ve entegrasyonunuzu güvenli hale getirin.
- Pub/Sub'da mesaj yayınlama ve Pub/Sub'dan mesaj alma
- Google Cloud Run'a dağıtılan uygulamanızın herkese açık şekilde gösterilmesini en aza indirin.
İhtiyacınız olanlar
- Chrome web tarayıcısı †
- Kişisel Google Hesabı ‡
- Etkin bir faturalandırma hesabına bağlı bir Google Cloud projesi
Hesabınızın, kaynakları sağlamanıza ve bu kaynaklara IAM erişimini yapılandırmanıza olanak tanıyan projeye IAM erişimi olması gerektiğini unutmayın.
† Diğer tarayıcılarla kullanıcı deneyimi, laboratuvarda açıklanan deneyimden farklı olabilir.
‡ Kurumsal veya okul hesabı kullanırken laboratuvarda açıklanan bazı işlemleri yapamayabilirsiniz.
2. Ortam kurulumu
Laboratuvar için tam işlevsel bir geliştirme ortamı sağlamak amacıyla, gerekli tüm araçların önceden yüklendiği Google Cloud Shell'i kullanacaksınız. Ortamı ayarlamak için talimatları uygulayın.
Google Hesabınız yoksa Google Hesabı oluşturun.
Kurulum talimatları
- Google Cloud Console'da oturum açmak için Google Hesabınızı kullanın.
- 👉 Üst gezinme çubuğunda proje seçiciyi açın ("Proje seçin" yazabilir veya mevcut bir proje adı gösterebilir) ya da
Ctrl+Oklavye kısayolunu tıklayıp mevcut bir projeyi seçin veya yeni bir proje oluşturun.Yeni proje oluşturmak birkaç saniye sürer. Hazır olmasını bekleyin ve proje seçiciyi kullanarak projeyi seçin.
- 👉 Google Cloud Console'un üst kısmındaki Cloud Shell simgesini tıklayın. (kırmızı dikdörtgenle işaretlenmiştir):
İstenirse pop-up iletişim kutusunda **Authorize** (Yetkilendir) seçeneğini tıklayarak Cloud Shell'in hesabınızın kimlik bilgilerini kullanmasını onaylayın.
- 👉💻 gcloud KSA'nın, seçtiğiniz (veya oluşturduğunuz) projeyi kullanacak şekilde yapılandırıldığından emin olun. Yapılandırılan proje kimliğini kontrol etmek için aşağıdaki komutu çalıştırın:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID], seçtiğiniz veya oluşturduğunuz projenin kimliği olacaktır.👉💻 Başka bir değer görürseniz proje kimliğinizi gcloud CLI komutları için varsayılan proje kimliği olarak yapılandırmak üzere aşağıdaki komutu çalıştırın:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Ortam değişkenlerinde kaynak sağlama için konumu ve projenizin kimliğini ve numarasını ayarlayın:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Bu laboratuvar için gerekli Google API'lerini etkinleştirin.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. ZooKeeper demo uygulamasını dağıtma
Aşağıdaki adımlarda, aracılı yapay zeka uygulamasının dağıtımı da dahil olmak üzere kaynaklar sağlanır ve yapılandırılır.
Pub/Sub kaynaklarını ayarlama
İki Pub/Sub konusu oluşturacaksınız. Biri, üçüncü taraf hizmeti tarafından etkinlikleri yapay zeka aracısı uygulamanıza göndermek için kullanılır. Etkinlik işleme sonuçlarını yayınlamak için başka bir uygulama.
- 👉💻 Yapay zeka aracılı uygulamasını tetiklemek için kullanılan bir Pub/Sub konusu oluşturun:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Uygulamanın yanıtlarını yayınlayabileceği bir Pub/Sub konusu oluşturun:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Hizmet hesaplarını ve proje düzeyinde IAM politikalarını ayarlama
Cloud Run hizmetinin ve Eventarc tetikleyicisinin erişim kapsamını en az ayrıcalık erişimi ilkesine uygun olarak minimum düzeyde tutmak için iki hizmet hesabı oluşturacaksınız. Cloud Run hizmetinin günlük ve izleme yazma, Google Vertex AI'da Gemini LLM'yi çağırma ve sonuçları bir Pub/Sub konusuna gönderme izinleri gerekir. Eventarc tetikleyicisinin minimum erişimi, Cloud Run ZooKeeper hizmetini çağırmak ve yayınlanan etkinlikleri okumak için Pub/Sub'a erişmek üzere izinler gerektirir. Bu talimatlar, tetikleyicinin hizmet hesabına Pub/Sub sistem hizmetinin kimliğine bürünmek için gereken izinleri vermenize yardımcı olur. Eventarc tetikleyici kaynağını oluşturduktan sonra, tetikleyicinin hizmet hesabının Cloud Run hizmetini çağırmasını sağlamak için roles/run.invoker rolünü veren komutu çalıştırırsınız.
- 👉💻 Cloud Run hizmeti için bir hizmet hesabı oluşturun:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Hizmet hesabına günlük ve izleme yazma ile Vertex AI'da Gemini modellerini kullanma izni verin:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Hizmet hesabına "agent_responses" konusuna mesaj gönderme izni verin:
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Eventarc tetikleyicisi için bir hizmet hesabı oluşturun:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Pub/Sub sistem hizmet hesabına kimliği doğrulanmış anında iletme istekleri gönderme izni verin:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
ZooKeeper uygulamasını Cloud Run'a dağıtma
Demo uygulamasının kodunu GitHub'dan indireceksiniz. Ardından kodu Cloud Run'a dağıtın.
- 👉💻 Temsilci yapay zeka uygulamasını indirin:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Yapay zeka aracısı uygulamasını Cloud Run'a dağıtın:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Eventarc tetikleyicisini yapılandırma
Tüm kaynakları (Pub/Sub konuları, IAM hizmet hesapları ve Cloud Run hizmeti) hazırladıktan sonra Eventarc tetikleyici kaynağını ayarlamanın zamanı gelir. Eventarc tetikleyici kaynağını oluşturacak ve Cloud Run hizmetini çağırma izinlerini tetikleyicinin hizmet hesabına vereceksiniz.
- 👉💻 Eventarc tetikleyicisi oluşturun:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Cloud Run hizmetini çağırmak için tetikleyicinin hizmet hesabına izin verin:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Çözümün işleyiş şeklini inceleyin
Şimdi yeni dağıttığınız öğeleri inceleyin. Aşağıdaki şemada tüm kaynaklar ve bunların birbirleriyle nasıl etkileşim kurduğu gösterilmektedir. "invoke_agent" konusuna mesaj yayınlamak için gcloud KSA'yı kullanacaksınız. Bu işlem, üçüncü taraf hizmetinin, yapay zeka aracılı uygulamasını çağırmak için mesajlaşma hizmetine kaydettiği bir etkinliği simüle eder.
Dağıtım, en az ayrıcalık erişimi ilkesine uygun olarak güvenli hale getirilir. Cloud Run hizmeti kimlik doğrulamayı zorunlu kılar (önceki bölümdeki 9. adımda --no-allow-unauthenticated bağımsız değişkenine bakın). Yalnızca roles/run.invoker rolüne veya benzer izinlere sahip kimlikler hizmeti çağırabilir. Bu rol yalnızca Eventarc tetikleyicisinin hizmet hesabına verilir. Benzer şekilde, "invoke_agent" konusuna erişim, yetkisiz etkinlik yayınlanmasını engellemek için en aza indirilir. Pub/Sub konusuna yayınlamayı atlayarak doğrudan ZooKeeper aracısını çağırmak hâlâ mümkündür. Uygulamanın uç noktasını herkese açık erişimden nasıl gizleyeceğinizi öğrenmek için 6. bölüme bakın.
İş akışını çalıştırma
ZooKeeper'a doğal dilde bir soru yayınlayarak harici bir etkinliği taklit edeceksiniz.
👉💻 Pub/Sub konusuna mesaj göndermek için aşağıdaki komutu kullanın:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
Gerçekte etkinlik bilgileri muhtemelen daha az okunabilir bir biçimde olacaktır. İşleme için, bir temsilci yapay zeka uygulamasının etkinliğin biçimi, veriler ve temsilcinin etkinlik bilgileriyle ne yapması gerektiği konusunda ayrıntılı talimatlara sahip olması gerekir.
Aracının etkinliği aldığını, isteği işlediğini ve yanıtı "agent_responses" konusuna gönderdiğini kontrol edebilirsiniz. Yanıtı okumak için "agent_responses" aboneliğini kullanacaksınız (codelab, hem konu hem de yanıtlar için abonelik için aynı kimliği kullanır).
👉💻 Temsilcinin yanıtını Pub/Sub aboneliğinden okumak için aşağıdaki komutu kullanın:
gcloud pubsub subscriptions pull agent_responses --auto-ack
Çıktıda, mesaj meta verilerini ve hayvanat bahçesinde 33 tür olduğu yanıtını içeren yükü içeren bir tablo yazdırılır. --auto-ack işareti, ileti çekildikten sonra otomatik olarak onaylandığı için ileti tekrar teslim edilmez.
İşleyiş şekli
Cloud Shell Düzenleyici'yi açıp ~/zoo-keeper-lab klasöründeki dosyaları görüntüleyerek yapay zeka aracısının kaynak kodunu inceleyin. Kaynak kodunu GitHub'da da görüntüleyebilirsiniz.
- main.py, Eventarc etkinliklerini işleyen tek bir işleyiciye sahip temel bir FastAPI web uygulamasını uygular.
- processor.py, kullanıcı kimliğini ve isteği almak için etkinliğin mesajını ayrıştırır. Ardından ADK çalıştırıcısında yeni bir oturum oluşturur ve isteği işlemek için Zookeeper aracısını çağırır. Temsilciden gelen yanıt, "agent_responses" Pub/Sub konusuna gönderilir.
- zookeeper_agent alt klasöründe ADK aracısının kaynak kodu bulunur. adk CLI'yı kullanarak aracıyla etkileşimde bulunmak için uygulamanın kök klasöründen
adk run zookeeper_agentkomutunu çalıştırabilirsiniz.
Sorun giderme
Önceki komutlardan herhangi biri başarısız olursa hata mesajını dikkatlice okuyun. Cloud Run'a dağıtım başarısız olursa ilk adım, başarısızlığın işlemin hangi aşamasında gerçekleştiğini belirlemektir.
- "gcloud run deploy..." komutunun çıktısında derlemenin başarısız olduğu bildiriliyorsa çıktıda derleme günlükleri URL'sini bulun ve ayrı bir pencerede açın.
- Çıktıda "hizmet başlatılamadı" gibi bir ifade yer alıyorsa hizmet dağıtılıyor ancak yürütme sırasında sağlık kontrolü başarısız oluyor demektir. Bu durumda Günlük Gezgini'ni açın veya gcloud CLI komutu için aşağıdaki paragrafa bakın. Başarısızlığın temel nedenini bulmak için günlükleri okuyun.
Pub/Sub'a bir mesaj gönderdiyseniz ancak aracı yanıt vermiyorsa veya yanıt garip görünüyorsa ne yapmalısınız?
👉💻 Son yürütmeden yayınlanan uygulama günlüklerini okumak için aşağıdaki komutu kullanın:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Günlükler, yürütmeyi izler ve hatalı veya ayrıştırılamayan mesaj yükü, Gemini modelinden gelen geçersiz yanıt, geçersiz ortam ayarları ve olası diğer sorunlar gibi hataları bildirir.
5. Dağıtım güvenliğini güçlendirme
Dağıttığınız Cloud Run hizmeti, internetteki herkes tarafından çağrılabilen herkese açık bir uç nokta sunar. Uç nokta, yetkisiz çağrıya karşı korunsa ve isteğin yapısını titizlikle doğrulasa da hizmet reddi ve cüzdan reddi saldırılarına izin veren bu saldırı vektörünü yine de bırakır. Mevcut tasarımda hizmetin tek başlatma yolu Eventarc tetikleyicisi üzerinden olduğundan hizmetin uç noktasını internete açması gerekmez.
👉💻 Hizmete yapılan çağrıları yalnızca Eventarc tetikleyicileri de dahil olmak üzere sınırlı bir kaynak koleksiyonundan yapılacak şekilde kısıtlayarak bu saldırı vektörünü kapatın:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Artık hizmetin URL'sini yerel makinenizden çağırmaya çalıştığınızda "404 Sayfa bulunamadı" hatası alırsınız.
👉💻 Hizmet uç noktasına istek göndermek için curl'ü kullanın:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Aşağıdakine benzer bir çıkış görürsünüz:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Bu değişiklikten sonra, aynı projedeki VPC'den, düzeltmenizin trafiği gönderecek şekilde yapılandırıldığı paylaşılan VPC ağından veya VPC Hizmet Kontrolleri çevresinin bir parçası olan bir ana makineden çağrı yapmadığınız sürece Cloud Run hizmet uç noktasını çağırarak ZooKeeper'ı doğrudan çağırmak artık mümkün değildir.
6. Özet
Tebrikler! Gelen etkinlikler tarafından tetiklenen, yapay zeka destekli uygulamanızı eşzamansız olarak çağırmak için bir ortamı başarıyla oluşturdunuz.
Temizleme
Sağladığınız kaynakları tutmanın, faturalandırma hesabınızda ücretlere neden olabileceğini unutmayın. Bu ortamı başka denemeler için kullanmayı planlamıyorsanız ve yaklaşan ücretlerden kaçınmak istiyorsanız bu codelab sırasında oluşturulan kaynakları silmeniz önerilir.
Bunu yapmanın iki yolu vardır:
1. yöntem: Projeyi kapatma
Projenin kapatılması (silinmesi), projenin tüm kaynaklarını ve verilerini serbest bırakır ve faturalandırma hesabının bağlantısını kaldırır. Bu yöntemi kullandığınızda, bu codelab için kullanılan kaynaklar veya veriler için başka ücret alınmaz. Projeyi kapatmak için aşağıdaki komutu kullanın:
gcloud projects delete $(gcloud config get-value project) --quiet
2. yöntem: Projedeki kaynakları silme
Cloud Run hizmetinin silinmesi, sunucusuz platformun kullanımıyla ilgili daha fazla ücret alınmasını önler. Bu yöntemin, Cloud Build ve uygulama günlükleri, kapsayıcı görüntüleri gibi codelab sırasında oluşturulan tüm verileri tamamen kaldırmadığını unutmayın. Hizmeti silmek için aşağıdaki komutu çalıştırın:
gcloud run services delete zookeeper-agent --region=${LOCATION}
Eventarc tetikleyici tanımı ve Pub/Sub konuları yönetim maliyeti oluşturmaz (daha fazla bilgi için Eventarc fiyatlandırması ve Pub/Sub fiyatlandırması sayfalarına bakın).
Projeyi kapatma hakkında daha fazla bilgi edinin.
Sırada ne var?
- GitHub'daki demoyu inceleyerek kod hakkında daha fazla bilgi edinin.
- Farklı kurumsal sistemlere erişimi düzenleyen mimariyi inceleyin.
- Eventarc tetikleyicilerini kullanarak Cloud Run'ı nasıl tetikleyeceğinizi öğrenin.
- ADK hakkında daha fazla bilgi edinin.