Çoklu veritabanı kalıcılığı ile akıllı bir e-ticaret kataloğu oluşturma

1. Giriş

Modern perakendecilikte verileriniz, çeşitli ve geniş bir ekosistemdir. Sağlam işlem verileriniz (fiyatlandırma ve envanter), "karmaşık" polimorfik kataloglarınız (elektronik ürün özellikleri ve giyim bedenleri) ve petabaytlarca davranış günlüğünüz var. Bunları tek bir monolit içinde zorlamak yalnızca teknik borç oluşturmakla kalmaz, aynı zamanda kullanıcı deneyimini de olumsuz etkiler.

Bu codelab'de, aşağıdakileri uyumlu hale getiren bir Polyglot Powerhouse tasarlayacaksınız:

  • AlloyDB: Yüksek hızlı tutarlılık ve resim yerleştirmeleri için işlemsel temeliniz.
  • Google Cloud'da MongoDB Atlas: Esnek, şemadan bağımsız katalog katmanınız.
  • Cloud Storage: Gerçek zamanlı trend tahmini için analitik beyniniz.
  • BigQuery: Yüksek çözünürlüklü dijital deponuz.

"Sır" nedir? Cloud Run'da çalışan veri kaynaklarını semantik köprü olarak akıllıca düzenlemek ve birleştirmek için Veritabanları için MCP Araç Kutusu'nu kullanacak, ardından Agent Development Kit (ADK) kullanarak çok ajanlı bir sohbet uygulaması dağıtacaksınız. Yalnızca bir arama çubuğu oluşturmuyorsunuz. Bağlamı anlayan, kısıtlamalara uyan ve ham veriler ile kullanıcı niyeti arasındaki boşluğu kapatan akıllı bir perakende beyni oluşturuyorsunuz.

İmkansız Kullanıcı Sorgusu

Standart e-ticaret aracıları, çok boyutlu akıl yürütme (olumsuz kısıtlamaları, görsel benzerliği ve gerçek zamanlı envanteri birleştirme) konusunda başarısız olur. Örneğin, genellikle şöyle bir perakende sitesiyle konuşmak isterim:

"Merhaba, yüksek rakımlarda fotoğraf çekme gezisi planlıyorum. "AeroGlow Pro"ya benzer tarzda, ancak deri bileşenleri olmayan, hava koşullarına dayanıklı sırt çantaları göster. Ayrıca, ürünlerin stokta olup olmadığını ve diğer fotoğrafçıların yorumlarda askı dayanıklılığı hakkında şikayet edip etmediğini de öğrenmek istiyorum."

Bu sorgu neden "The Agent Killer" (Ajan Katili) olarak adlandırılıyor?

  • Görsel Benzerlik (AlloyDB + Vector Search): "AeroGlow Pro ile stil olarak benzer" ifadesi, resim yerleştirme karşılaştırması gerektirir.
  • Olumsuz Kısıtlama (MongoDB): "Deri içermeyen" ifadesi, genellikle standart SQL şemasında bulunmayan esnek, iç içe yerleştirilmiş özellikler aracılığıyla filtreleme yapılmasını gerektirir.
  • Gerçek Zamanlı Envanter (AlloyDB): "Gerçekten stokta" olması için canlı bir işlemsel kontrol (eski bir arama dizini değil) gerekir.
  • Anlamsal Sentez (BigQuery + Çoklu Aracı): "Kayış dayanıklılığı" ile ilgili yorumların analiz edilmesi için aracının, BigQuery'den gelen yapılandırılmamış geri bildirimleri anında özetlemesi gerekir.

Çoğu perakende botu yalnızca "Sırt çantası" ve "Deri" kelimelerini görür ve 10 deri sırt çantası gösterir. Bunu nasıl önlüyoruz?

Çünkü yalnızca anahtar kelimeleri eşleştirmiyoruz. Temsilcilerimizin AlloyDB'deki işlemsel gerçekleri ve MongoDB'deki esnek özellikleri aynı anda tüm bu kaynaklarda "gerekçelendirmesine" olanak tanımak için MCP Toolbox'ı kullanıyoruz. Hadi başlayalım.

Yapacaklarınız

E-ticaret çoklu veritabanı mimarisi

Ön koşullar

2. Başlamadan önce

Google Cloud projesi oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

  1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
  2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
    gcloud auth list
  3. Projenizin yapılandırıldığını onaylayın:
    gcloud config get project
  4. Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Gerekli API'leri etkinleştirme

Gerekli tüm API'leri etkinleştirmek için bu komutu çalıştırın:

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  storage.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  aiplatform.googleapis.com

3. Cloud Storage'ı ayarlama

Cloud Storage, ürün resimleri gibi yapılandırılmamış medya öğeleri için büyük bir depo görevi görür.

  1. Google Cloud Console'da Cloud Storage'a gidin ve Paket oluştur'u tıklayın.
  2. Paketinize global olarak benzersiz bir ad verin (ör. ecommerce-app-images).
  3. Oluştur'u tıklayın.
  4. Demo uygulamasının resimlere kimlik doğrulama olmadan erişmesine izin vermek için Bu pakette herkese açık erişim engeli uygula seçeneğini temizleyin ve Onayla'yı tıklayın.
  5. İzinler sekmesine gidin.
  6. İzinler bölümünde Erişim izni ver'i tıklayın.
  7. New principals (Yeni ana hesaplar) bölümüne allUsers girin.
  8. Bir rol seçin bölümünde Cloud Storage > Storage Nesne Kullanıcısı'nı seçin.
  9. Kaydet'i ve ardından kaynağı herkese açık hale getirdiğinizi onaylamak için Herkese Açık Erişime İzin Ver'i tıklayın.

Yer tutucu resimler yükleme

BRK2-149-multidb-ecommerce, en iyi görsel deneyimi sunmak için yer tutucu resimler kullanır.

  1. Cloud Shell'inizde next-26-sessions deposunu klonlayın:
    git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git
  2. UploadImages klasörüne gidin:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages
  3. Google Cloud Console'da Cloud Storage'a gidin ve Paketler'i tıklayın.
  4. Yeni oluşturduğunuz paketin adını tıklayın.
  5. Yükle > Dosyaları yükle'yi tıklayın, indirilen örnek resimleri seçin ve Aç'ı tıklayın.

4. AlloyDB'yi kurma

AlloyDB; ürün kimlikleri, adları, SKU'ları, fiyatları ve envanter gibi yapılandırılmış, işlemsel ve kritik veriler için tek doğru kaynağı olarak hizmet verir. AlloyDB, öneriler ve doğal dil sorguları için benzerlik arama özellikleriyle yapay zeka aracını da destekler.

AlloyDB kümesi sağlama

  1. Google Cloud Console'da AlloyDB for PostgreSQL'e gidin.
  2. Küme Oluştur'u tıklayın.
  3. Küme kimliği için ecommerce-cluster değerini girin.
  4. postgres kullanıcısı için güçlü bir şifre belirleyin. Öğrenme amacıyla alloydb kullanabilirsiniz.
  5. Veritabanı Sürümü için varsayılan değeri koruyun.
  6. Region (Bölge) olarak us-central1 (veya tercih ettiğiniz bölge) seçeneğini belirleyin.

Birincil örneği yapılandırma

  1. Instance ID (Örnek kimliği) alanına ecommerce-cluster-primary girin.
  2. Zonal Availability (Alt Bölge Kullanılabilirliği) bölümünde Single zone'u (Tek alt bölge) seçin.
  3. Makine Türü için küçük bir makine türü seçin (ör. N2, 4 vCPU, 32 GB RAM).
  4. Özel IP Bağlantısı bölümünde Private Services Access (PSA)'yı ve default ağını seçin.Varsayılan ağ henüz ayarlanmamışsa bir ağ oluşturmak için Ağ kurulumunu onayla'yı tıklayın.
  5. Public IP Connectivity (Herkese Açık IP Bağlantısı) bölümünde, bu codelab'de MCP araç kutusunun düzgün şekilde bağlanması için Enable Public IP (Herkese Açık IP'yi Etkinleştir) onay kutusunu işaretleyin.
  6. Yetkili harici ağlar bölümüne 0.0.0.0/0 girin. Riskleri kabul ediyorum onay kutusunu işaretleyip Kaydet'i tıklayın.
  7. Küme Oluştur'u tıklayın.

Not: Herkese açık IP adresinizi (34.124.240.26 gibi görünür) not aldığınızdan emin olun.

Veritabanını başlatma

  1. Soldaki gezinme menüsünden AlloyDB Studio'yu tıklayın.
  2. Veritabanı açılır listesinde postgres simgesini seçin.
  3. Veritabanında oturum açmak için Yerleşik kimlik doğrulama'yı seçin.
  4. Kullanıcı adı için postgres kullanıcısını kullanın.
  5. Şifre alanına, daha önce belirlediğiniz şifreyi girin.
  6. Kimliği doğrula'yı tıklayın.
  7. Düzenleyici görünümünde yeni bir adsız sorgu sekmesi açın.
  8. Aşağıdaki DDL'yi kopyalayın ve Run'ı (Çalıştır) tıklayın:
    CREATE TABLE products_core_table (
  product_id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  sku VARCHAR(50) UNIQUE NOT NULL,
  price NUMERIC(10, 2) NOT NULL,
  stock INT NOT NULL
);
  9. Cloud Shell'inizde BRK2-149-multidb-ecommerce klasörüne gidin:
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  10. Cloud Shell'inizde alloydb_insert_queries.sql dosyasını açın ve ekleme sorgularını kopyalayın.
    cat alloydb_insert_queries.sql
  11. Yeni bir adsız sorgu sekmesinde yalnızca INSERT ifadelerini yapıştırın ve Çalıştır'ı tıklayın.
  12. Yeni bir adsız sorgu sekmesinde aşağıdaki DDL'yi kopyalayın ve products_core_table tablosunda bir dizin oluşturmak için Çalıştır'ı tıklayın:
    CREATE INDEX idx_products_core_sku ON products_core_table(sku);

Yapay zeka aracısının benzer ürünleri getirmesi için resim yerleştirmeleri oluşturun

Yapay zeka ajanı entegrasyonu, benzer ürünleri getirmek için görsel yerleştirmelerini kullanır. Yerleştirmeler, multimodalembedding@001 modeli kullanılarak oluşturulur ve AlloyDB veritabanında depolanır. Yerleştirmeler 1.408 boyutlu vektörlerdir ve img_embeddings sütununda saklanır.

Yerleştirmeler oluşturabilmemiz için AlloyDB hizmet hesabına Cloud Storage'a erişmek üzere gerekli rollerin verilmesi gerekir.

Cloud Storage'a erişmek için AlloyDB hizmet hesabına roller verme

AlloyDB hizmet hesabının Cloud Storage paketindeki nesneleri okuyabilmesi için Storage Object User ve Storage Object Viewer rollerini veriyoruz.

  1. IAM ve yönetici'ye gidin.
  2. Grant access'i (Erişim izni ver) tıklayın.
  3. Yeni ana hesaplar alanına AlloyDB hizmet hesabını arayın. Hizmet hesabı, service-991742412753@gcp-sa-alloydb.iam.gserviceaccount.com hesabına benziyor.
  4. Rol seçin'i tıklayın.
  5. Depolama Alanı Nesne Kullanıcısı rolünü bulup seçin.
  6. Başka rol ekle'yi tıklayın ve Storage Nesne Görüntüleyici rolünü seçin.
  7. Başka rol ekle'yi tıklayın ve Vertex AI Kullanıcısı rolünü seçin.
  8. Kaydet'i tıklayın.

Uzantıları etkinleştirme

Bu uygulamayı oluşturmak için pgvector ve google_ml_integration uzantılarını kullanacağız. pgvector uzantısı, vektör yerleştirmelerini depolamanıza ve aramanıza olanak tanır. google_ml_integration uzantısı, SQL'de tahmin almak için Vertex AI tahmin uç noktalarına erişmek üzere kullandığınız işlevleri sağlar. Aşağıdaki DDL'leri çalıştırarak bu uzantıları etkinleştirin:

  1. Google Cloud Console'da AlloyDB for PostgreSQL'e gidin.
  2. Soldaki gezinme menüsünden AlloyDB Studio'yu tıklayın.
  3. Düzenleyici görünümünde yeni bir adsız sorgu sekmesi açın.
  4. Aşağıdaki DDL'yi kopyalayın ve Run'ı (Çalıştır) tıklayın:
    CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration;

Veritabanını yerleştirmelerle başlatma

  1. products_core_table dosyasına img_embeddings sütununu ekleyin.
    ALTER TABLE products_core_table
ADD COLUMN img_embeddings vector(1408);
  2. Resimler için gömmeler oluşturun ve bunları img_embeddings sütununda saklayın.
    UPDATE products_core_table
SET img_embeddings = google_ml.image_embedding(
    model_id => 'multimodalembedding@001',
    image => 'gs://<STORAGE_BUCKET_NAME>/' || sku || '.jpg',
    mimetype => 'image/jpeg')
WHERE sku IN (
    SELECT
    sku
    FROM
    products_core_table
    WHERE
    img_embeddings IS NULL
    AND sku IS NOT NULL
    LIMIT 10
);
    yerine Cloud Storage paketinizin adını girin.
  3. Studio'nun 5 dakikalık sınırlaması olduğundan, tüm küme için görüntü yerleştirmeleri oluşturmak üzere önceki sorguyu en az 5 kez tekrarlayın. Bu sorgunun zaman aşımı olursa LIMIT değerini 5 olarak değiştirin ve sorguyu on kez yeniden çalıştırın. Bu adımın tamamlanması birkaç dakika sürebilir.

5. Google Cloud'da MongoDB Atlas'ı kurma

MongoDB, zengin ve yarı yapılandırılmış ürün ayrıntılarını ve esnek kullanıcı davranışı verilerini (ör. tıklamalar ve görüntülemeler) depolar.

MongoDB kümesi oluşturma

  1. Google Cloud'da MongoDB Atlas'a gidin ve ücretsiz katman hesabını seçin.
  2. Ücretsiz küme katmanını seçin ve kümeye bir ad girin (ör. ecommerce-cluster).
  3. Sağlayıcı olarak Google Cloud'u seçin ve bölgenin Google Cloud bölgenizle (ör. us-central1) eşleştiğinden emin olun.
  4. Create Deployment'ı (Dağıtım Oluştur) tıklayın.
  5. Kapat'ı tıklayın.

Ağ erişimini yapılandırma

  1. Atlas konsolunda Database & Network Access'e (Veritabanı ve Ağ Erişimi) gidin.
  2. IP Erişim Listesi'ni tıklayın.
  3. IP adresi ekle'yi tıklayın.
  4. Her yerden erişime izin veren 0.0.0.0/0 değerini ekleyin.
  5. Onayla'yı tıklayın.

Veritabanı kullanıcısı oluşturma

  1. Atlas konsolunda Database & Network Access'e (Veritabanı ve Ağ Erişimi) gidin.
  2. Veritabanı Kullanıcıları'nı tıklayın.
  3. Yeni Veritabanı Kullanıcısı Ekle'yi tıklayın.
  4. Kimlik doğrulama yöntemi olarak Şifre'yi seçin.
  5. Kullanıcı adını store-user, şifreyi ise storeuser olarak girin.
  6. Add Built In Role'u (Yerleşik Rol Ekle) tıklayın, Read and write to any database'i (Herhangi bir veritabanına okuma ve yazma) seçin.
  7. Kullanıcı Ekle'yi tıklayın.

Bağlantı dizesini alma

  1. Veritabanı > Kümeler > Bağlan'a gidin.
  2. Uygulamanızı bağlayın bölümünde Sürücüler'i tıklayın.
  3. Bağlantı dizenizi uygulama kodunuza ekleyin bölümünde gösterilen bağlantı dizesini kopyalayın. Dize şu şekilde görünür:
    mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
    db_password kısmını MongoDB şifrenizle değiştirin. Bu codelab'de storeuser'dır.

Bu bağlantı dizesini kaydedin. Bu değeri daha sonra MONGODB_CONNECTION_STRING ortam değişkeni için kullanacaksınız.

Veritabanı ve Koleksiyon Oluşturma

  1. Atlas konsolunda Database > Clusters > Browse Collections'a (Veritabanı > Kümeler > Koleksiyonlara Göz At) gidin.
  2. Veritabanı oluştur'u tıklayın ve ayrıntıları girin:
    • Veritabanı Adı: ecommerce_db
    • Koleksiyon Adı: product_details_collection
  3. Veritabanı oluştur'u tıklayın.
  4. Veri Gezgini'nde Koleksiyon Adı'nı seçin.
  5. Veri Ekle (+) simgesini ve ardından Doküman ekle'yi tıklayın.
  6. product_details_export.json dosyasındaki JSON içeriğini kopyalayıp Belge Ekle düzenleyici iletişim kutusuna yapıştırın.
  7. Belge dizisini eklemek için Ekle'yi tıklayın ve 192 belgenin eklendiğini doğrulayın.
  8. Veri Gezgini'nde, ecommerce_db veritabanının yanındaki Koleksiyon oluştur (+) seçeneğini tıklayın.
  9. Koleksiyon adı için user_interactions_collection girin ve Koleksiyon Oluştur'u tıklayın.
  10. Veri Gezgini'nde user_interactions_collection koleksiyonunu seçin.
  11. Veri Ekle (+) simgesini ve ardından Doküman ekle'yi tıklayın.
  12. user_interactions_export.json dosyasındaki JSON içeriğini kopyalayıp Belge Ekle düzenleyici iletişim kutusuna yapıştırın.
  13. Belge Ekle'yi tıklayın.

6. BigQuery'yi ayarlama

BigQuery, akıllı raporlama ve öneriler oluşturmak için geçmiş kullanıcı davranışlarını toplar ve analiz eder.

Veri kümesini oluşturma

  1. Google Cloud Console'da BigQuery'ye gidin.
  2. Gezgin bölmesinde proje kimliğinizin yanındaki üç noktalı menüyü tıklayın ve Veri kümesi oluştur'u seçin.
  3. Veri kümesi kimliği için ecommerce_analytics girin.
  4. Veri kümesi oluştur'u tıklayın.

Analytics tablosunu oluşturma

  1. BigQuery çalışma alanında yeni bir sorgu açın.
  2. Kullanıcıları ürün etkileşimlerine bağlayan özet tablosunu oluşturmak için aşağıdaki SQL ifadesini çalıştırın:
CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

MCP Toolbox için Compute hizmet hesabına roller verme

Araç kutumuz için kullanılan Compute hizmet hesabına roller veriyoruz. Bu işlem, MCP Araç Kutusu'nun BigQuery, Secret Manager ve diğer bulut hizmetlerine erişmesini sağlamak için yapılır.

Rol vermek için aşağıdaki adımları tamamlayın:

  1. IAM ve yönetici'ye gidin.
  2. Grant access'i (Erişim izni ver) tıklayın.
  3. Yeni ana hesaplar alanına YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com adlı varsayılan Compute hizmet hesabını girin. YOUR_PROJECT_NUMBER kısmını Google Cloud proje numaranızla değiştirin.
  4. Rol seçin'i tıklayın.
  5. BigQuery Veri Düzenleyici rolünü bulup seçin.
  6. Başka rol ekle'yi tıklayın ve BigQuery İş Kullanıcısı rolünü seçin.
  7. Başka rol ekle'yi tıklayın ve Secret Manager Secret Accessor rolünü seçin.
  8. Başka rol ekle'yi tıklayın ve Düzenleyici rolünü seçin.
  9. Kaydet'i tıklayın.

7. Uygulamayı baştan sona anlama

Her bir bileşenin birbiriyle nasıl çalıştığını öğrenmek için birden fazla veritabanı ve hizmet kullanan basit bir e-ticaret uygulaması oluşturacağız. Uygulama, Python (Flask) arka ucuyla oluşturulmuştur ve birden fazla Google Cloud hizmeti ile veritabanını entegre eder.

Dizin yapısını anlama

Sonraki bölümde, BRK2-149-multidb-ecommerce deposunu klonlayacak ve uygulamayı yerel olarak çalıştırmak için kullanacaksınız. Uygulamayı yerel olarak test ettikten sonra hem MCP Toolbox'ı hem de uygulamayı Cloud Run'a dağıtacağız.

Bu dizindeki indirilen dosyaları inceleyin. Aşağıdaki üst düzey dizinler bulunur:

  • UploadImages: Öncelikle e-ticaret ürün kataloğunun dokümanları veya görsel içerikleri için kullanılan resim öğelerini depolar.
  • static: Kullanıcı arayüzünü stilize etmek ve etkileşim eklemek için kullanılan CSS ve JavaScript dosyaları gibi uygulamanın statik web öğelerini depolar ( kaynak).
  • templates: Python uygulaması tarafından e-ticaret kataloğu için web sayfalarını dinamik olarak oluşturmak üzere kullanılan HTML şablonlarını (Flask için büyük olasılıkla Jinja2) depolar ( kaynak).
  • toolbox-implementation: Model Context Protocol (MCP) Araç Kutusu'nun yapılandırma ve uygulama ayrıntılarını saklayarak önceden tanımlanmış araçları kullanarak çoklu veritabanı etkileşimlerini kolaylaştırır.

Bu depodaki dosyalar, çok veritabanlı bir e-ticaret uygulaması oluşturmak, yapılandırmak ve dağıtmak için birlikte çalışır. app.py gibi merkezi dosyalar, SQL ve JSON dosyalarında tanımlanan çeşitli veri kaynaklarını entegre ederek arka ucu düzenler. Yapılandırma dosyaları ise bulut ortamlarına sorunsuz dağıtım sağlar:

  • app.py: Flask arka uç ve çoklu veritabanı entegrasyonlarını düzenler.
  • agentengine.py: Vertex AI aracılarını başlatma ve yapılandırma için temel mantık.
  • .env: Veritabanı ve depolama bağlantıları için sırları saklar.
  • tools.yaml: MCP Araç Kutusu'nu çoklu veritabanı işlemleri için yapılandırır.
  • Dockerfile: Container görüntüsünü ve ortam kurulumunu tanımlar.
  • requirements.txt: Uygulama çalışma zamanı için gereken Python kitaplıklarını listeler.
  • tools.yaml: MCP Araç Kutusu'nun yapılandırmaları.
  • Procfile: Dağıtım için üretim yürütme komutlarını belirtir.
  • alloydb_insert_queries.sql: İlişkisel veriler için SQL sorguları içerir.
  • product_details_export.json ve user_interactions_export.json: NoSQL veritabanı için örnek JSON verileri sağlar.
  • README.md: Kurulum, dağıtım ve proje anlayışına rehberlik eder.

Uygulamanın Uçtan Uca Akışı

  • AlloyDB Kurulumu: Yüksek performanslı bir küme sağlayın ve resim yerleştirmeleri için vektör sütunları içeren products_core_table'ı oluşturmak üzere sağlanan SQL komut dosyalarını kullanın.
  • MongoDB Atlas Kurulumu: Ürün ayrıntılarında akışkan ürün özelliklerini depolamak ve kullanıcı etkileşimlerinde gerçek zamanlı tıklama akışlarını kaydetmek için Google Cloud'da bir küme dağıtın.
  • BigQuery Analytics: Etkileşim günlüklerini toplamak için bir veri kümesi oluşturun. Bu sayede, milyonlarca etkinlik arasında trend olan "En Çok 5" öğeyi belirleyen karmaşık analiz sorguları oluşturabilirsiniz.
  • Cloud Storage deposu: Yüksek çözünürlüklü ürün resimlerini barındırmak için herkese açık bir paket oluşturun. Her öğeye ön uç için imzalı veya herkese açık bir URL üzerinden erişilebildiğinden emin olun.
  • MCP Araç Kutusu Dağıtımı: Araç kutusunu Cloud Run'a dağıtarak doğal dil amacını çok veritabanlı sorgulara çeviren merkezi RESTful köprü olarak oluşturun.
  • Tools.yaml Yapılandırması: Belirli SQL ve NoSQL işlemlerini basit, aracı tarafından okunabilir adlarla eşleyerek "Araçlarınızı" (ör. get_product_core_data veya get_top_5_views) tanımlayın.
  • Flask Arka Uç Mantığı: MCP Araç Kutusu ile arayüz oluşturan, veri alma koordinasyonunu sağlayan ve kullanıcı arayüzü için API olarak hizmet veren app.py rotalarını uygulayın.
  • Çoklu Aracı Düzenleme: Karmaşık ve çok kaynaklı perakende sorgularını çözmek için doğru "Aracı" seçerek kullanıcı niyetini anlamak üzere kod içindeki ADK aracılarını yapılandırın.
  • Ön uç entegrasyonu: Ürün kataloğunu içeren bir index.html arayüzü oluşturun. Bu arayüzde etkileşimleri kaydetme özelliği, ürün performans analizlerini anlamak için Analytics sekmesi ve sorunsuz bir sohbetli alışveriş deneyimi sunmak üzere ADK çoklu temsilci sohbetini kullanan özel bir "Temsilci Sekmesi" yer almalıdır.

Şimdi de düzenleme ve dağıtımları uygulayalım.

8. MCP Toolbox'ı kurma ve Cloud Run'a dağıtma

MCP Toolbox, birden fazla veri kaynağımızı soyutlayarak uygulamamızın verileri tek tip şekilde getirmesine ve yazmasına olanak tanır.

MCP Toolbox'ı yerel olarak yükleme

  1. Cloud Shell'inizde toolbox-implementation klasörüne gidin:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  2. MCP Araç Kutusu ikilisini indirip yürütülebilir hale getirin:
    export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

tools.yaml dosyasını yapılandırma

AlloyDB, MongoDB ve BigQuery için soyutlamaları tanımlamanız gerekir. tools.yaml dosyası, MCP araç kutusuna birbirleriyle nasıl etkileşim kuracaklarını söyler.

  1. Yerleştirilmiş düzenleyiciyi kullanarak tools.yaml dosyasını oluşturun ve düzenleyin:
    cloudshell edit tools.yaml
    Tam tools.yaml dosyasına GitHub deposundan ulaşabilirsiniz. İçeriğini yeni tools.yaml dosyanıza kopyalayın.
  2. Barındırıcıyı, kullanıcıyı, şifreleri, proje kimliklerini ve bağlantı dizelerini önceki adımlarda sağladığınız altyapıyla eşleşecek şekilde güncelleyin:

    Veritabanı

    Alan

    Örnek Değer

    AlloyDB/BigQuery

    project_id

    YOUR_PROJECT_ID

    AlloyDB

    region

    us-central1

    AlloyDB

    cluster

    ecommerce-cluster

    AlloyDB

    instance

    ecommerce-cluster-primary

    AlloyDB

    database

    postgres

    AlloyDB

    password

    alloydb

    MongoDB

    connection_string

    mongodb+srv://store-user:storeuser@ecommerce-cluster.urcxr6q.mongodb.net

MCP Toolbox için Compute hizmet hesabına roller verme

Araç kutumuz için kullanılan Compute hizmet hesabına roller veriyoruz. Bu işlem, MCP Toolbox'ın AlloyDB'ye erişmesini sağlamak için yapılır.

  1. IAM ve yönetici'ye gidin.
  2. Grant access'i (Erişim izni ver) tıklayın.
  3. Yeni ana hesaplar alanına YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com adlı varsayılan Compute hizmet hesabını girin. YOUR_PROJECT_NUMBER kısmını Google Cloud proje numaranızla değiştirin.
  4. Rol seçin'i tıklayın.
  5. BigQuery Veri Düzenleyici rolünü bulup seçin.
  6. Başka rol ekle'yi tıklayın ve AlloyDB İstemcisi rolünü seçin.
  7. Başka rol ekle'yi tıklayın ve Hizmet Kullanımı Tüketicisi rolünü seçin.
  8. Başka rol ekle'yi tıklayın ve Storage Nesne Görüntüleyici rolünü seçin.
  9. Kaydet'i tıklayın.

Aracınızın kullanıcı arayüzünü test etme

  1. Cloud Shell terminalinizde, kullanıcı arayüzüne hizmet vermek için araç kutusunu yerel olarak çalıştırın:
    ./toolbox --ui
  2. Cloud Shell'de 5000 numaralı bağlantı noktasında Web Önizlemesi'ni açın ve araçlar sayfasına gidin. Örneğin, oturum URL'nize bağlı olarak şu adreste görüntüleyebilirsiniz: https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui

Aşağıdaki MCP araç kutusu kullanıcı arayüzü gösterilir:

MCP Araç Kutusu Kullanıcı Arayüzü

Cloud Run'a dağıt

MCP Toolbox'ı Cloud Run'a dağıtarak uygulamamızın veritabanlarını sorgulamak için kullanabileceği güvenli, yönetilen bir hizmet haline getirin. Hassas bağlantı ayrıntılarını korumak için yapılandırmayı Secret Manager'da saklarız.

  1. Yeni bir Cloud Shell oturumu açın.
  2. toolbox-implementation klasörüne gidin:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  3. tools.yaml yapılandırmasını Google Secret Manager'a yükleyin:
    gcloud secrets create tools --data-file=tools.yaml
    Not: Mevcut gizli anahtara yeni bir sürüm eklemek için aşağıdaki komutu kullanın:
    gcloud secrets versions add tools --data-file=tools.yaml
  4. Herkese açık MCP Araç Kutusu container görüntüsünü kullanarak dağıtma:
    export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.29.0
export PROJECT_ID=$(gcloud config get-value project)

gcloud run deploy toolbox \
    --image $IMAGE \
    --region us-central1 \
    --service-account $(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui" \
    --allow-unauthenticated
  5. Dağıtım tamamlandıktan sonra sağlanan Cloud Run hizmeti URL'sini not edin. https://toolbox-*********-uc.a.run.app/ui gibi görünmelidir.

9. E-ticaret uygulamasını ayarlama ve Cloud Run'a dağıtma

Veritabanlarımız çalışır durumda ve MCP Toolbox soyutlaması dağıtılmışken Flask web uygulamasını çalıştırabiliriz.

Flask uygulaması, ürün kataloğunu sunmak için aşağıdaki adımları uygulayarak verileri işler:

  1. Temel verileri getirme: AlloyDB'deki (list_products_core) ürünlerin tam listesini alır.
  2. Ayrıntıları genişletilmiş olarak getir: Tüm ürün ayrıntılarını MongoDB'den (list_all_product_details) alır.
  3. Listeleri birleştir: İki listeyi birleştirir.
  4. Medya ile zenginleştir: Cloud Storage resim URL'sini her öğeye ekler.

Akıl yürütme motoru uygulama yolu oluşturma

Google Cloud'un Vertex AI Reasoning Engine'ini kullanarak bir yapay zeka aracısını başlatmak ve kaydetmek için aşağıdaki komutu çalıştırın:

  1. Cloud Shell terminalinizde BRK2-149-multidb-ecommerce klasörüne gidin.
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  2. Bağımlılıkları yüklemek için requirements.txt dosyasını çalıştırın.
    pip install -r requirements.txt
  3. Muhakeme motoru uygulama yolunu oluşturmak için agentengine.py komut dosyasını çalıştırın:
    python agentengine.py

Çıkış şu şekilde görünür:

projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

Ortam değişkenlerini yapılandırma

  1. .env dosyası oluşturma ve düzenleme:
    cloudshell edit .env
  2. Değerleri, kendi veritabanı bağlantılarınız ve yeni Cloud Run Toolbox URL'nizle değiştirin:
    # 1. MongoDB Connection String
MONGODB_CONNECTION_STRING="mongodb+srv://<db_user>:<db_password>@cluster0.mongodb.net"

# 2. MCP Toolbox Server Location
# Must match the address where you run the toolbox server
MCP_TOOLBOX_SERVER_URL="https://toolbox-*********-uc.a.run.app"

# 3. Google Cloud Storage Bucket Name
GCS_PRODUCT_BUCKET="ecommerce-app-images"

# 4. Fallback image URL
FALLBACK_IMAGE_URL="https://storage.googleapis.com/ecommerce-media-bold-circuit-492711-n9/fallback.jpg"

# 5. Google Gen AI Vertex AI flag
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# 6. Project ID
PROJECT_ID=codelab-project-491117

# 7. Google Cloud Location of AlloyDB, BigQuery databases
GOOGLE_CLOUD_LOCATION=us-central1

# 8. Reasoning engine application path
APP_NAME=projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

# 9. Model ID
MODEL=gemini-1.5-flash-lite

Ön ucu Cloud Run'a dağıtma

  1. Mimarinin tamamlanması için web uygulamasını Cloud Run'a dağıtın:
    gcloud run deploy polyglot --source . --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars \
  MONGODB_CONNECTION_STRING="<MONGODB_CONNECTION_STRING>", \
  MCP_TOOLBOX_SERVER_URL="<MCP_TOOLBOX_SERVER_URL>", \
  GCS_PRODUCT_BUCKET="<GCS_PRODUCT_BUCKET>", \
  FALLBACK_IMAGE_URL="<FALLBACK_IMAGE_URL>", \
  GOOGLE_GENAI_USE_VERTEXAI=TRUE, \
  PROJECT_ID="YOUR_PROJECT_ID", \
  GOOGLE_CLOUD_LOCATION=us-central1, \
  APP_NAME="<YOUR_REASONING_ENGINE_APP_PATH>", \
  MODEL="gemini-1.5-flash-lite"
    Aşağıdaki değerleri değiştirin:
    • YOUR_PROJECT_ID: Google Cloud proje kimliğiniz.
    • YOUR_REASONING_ENGINE_APP_PATH: python agentengine.py komutunun çalıştırılmasından elde edilen çıkış (ör. projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856).
    • MCP_TOOLBOX_SERVER_URL: MCP Araç Kutusu sunucunuzun URL'si (örneğin, https://toolbox-*********-uc.a.run.app).
    • GCS_PRODUCT_BUCKET: Google Cloud Storage paketinizin adı (örneğin, ecommerce-app-images).
    • MONGODB_CONNECTION_STRING: MongoDB veritabanınızın bağlantı dizesi (ör. mongodb+srv://store-user:storeuser@ecommerce-cluster.g8vaekh.mongodb.net)
    • FALLBACK_IMAGE_URL: Yedek resmin URL'si (ör. https://storage.googleapis.com/ecommerce-app-images/fallback.jpg)

Uygulamanız artık yayında! Çoklu veritabanı e-ticaret kataloğunu görmek için Cloud Run tarafından sağlanan hizmet URL'sini açın. URL, https://polyglot-*********-uc.a.run.app/ adresine benzer olacaktır.

10. Uygulamayı keşfetme

  1. Tüm ürünleri görüntülemek için Ürün Kataloğu'nu tıklayın.
    Ürün Kataloğu
  2. Ürün ayrıntılarını görüntülemek için bir ürün simgesini tıklayın. Resimlerin Cloud Storage'dan, ürün ayrıntılarının MongoDB'den ve ürün envanterinin AlloyDB'den alındığını fark edeceksiniz.Ürün Bilgileri
  3. MongoDB'ye gönderilen sahte görünümler ve yazmalar oluşturmak için ürün kataloğuyla etkileşimde bulunun.
  4. Ürün analizlerini görüntülemek için ETL ve Analytics'i tıklayın. Ürün analizlerinin BigQuery'den getirildiğini görürsünüz.
    Ürün ETL&#39;si ve Analizi
  5. Yapay zeka ajanıyla etkileşim kurmak için Yapay zeka ajanı sekmesini tıklayın. Aşağıdaki gibi doğal dil soruları sorun:
    I'm planning a high-altitude photography trip. 
Show me some weather-resistant backpacks similar in style to aero glow pro 
but without any leather components. Also, let me know if they are actually in 
stock and if other photographers have complained about the strap durability 
in the reviews.
    Yapay Zeka Temsilcisi

Aramanın tam olarak istediğimiz sonucu verdiğini görebilirsiniz: Deri bileşenleri olmayan, stokta bulunan ve yorumlarda kayış dayanıklılığıyla ilgili şikayet bulunmayan bir sırt çantası.

Yapay Zeka Temsilcisi

11. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.

Aşağıdaki Cloud Shell komutlarını çalıştırın:

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete multi-db-app --region us-central1 --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://ecommerce-app-images
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

İsteğe bağlı olarak, Google Cloud projesinin tamamını ve tüm kaynaklarını silmek için aşağıdaki komutu çalıştırın:

gcloud projects delete $PROJECT_ID

12. Tebrikler

Tebrikler! Bulutlar arası bir Multidb mimarisini başarıyla oluşturdunuz.

MCP Toolbox'ın modern ve özel bir uygulama için mimari yapıştırıcı görevi gördüğünü gösterdiniz. Doğru veritabanını doğru işe eşleştirerek şunları elde ettiniz:

  • Esnek Veri Yazma İşlemleri: Etkinlik günlükleri için MongoDB.
  • İşlemsel Tutarlılık: Temel bütünlük için AlloyDB.
  • Yüksek Performanslı Analizler: İş zekası için BigQuery.
  • Birleştirilmiş geliştirme: MCP Araç Kutusu'nu kullanarak tüm karmaşıklığı ortadan kaldıran tek bir Python arka ucu.

Referans belgeleri

İlgili Google Cloud ürünleri hakkında daha fazla bilgi edinin ve şu codelab uygulamalarını inceleyin:

Bu codelab'de kullanılan ürünler hakkında daha fazla bilgi için aşağıdaki kaynaklara bakın: