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

1. Giriş

Modern perakendede verileriniz, çeşitli ve geniş bir ekosistemdir. Elinizde sağlam işlem verileri (fiyatlandırma ve envanter), "karmaşık" polimorfik kataloglar (elektronik özellikleri ve giysi bedenleri) ve petabaytlarca davranış günlüğü var. Bunları tek bir monolitik yapıya zorlamak yalnızca teknik borç yaratmakla kalmaz, aynı zamanda kullanıcı deneyimini de mahveder.

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

  • AlloyDB: Yüksek hızlı tutarlılık ve görüntü yerleştirmeleri için işlem omurganız.
  • 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.

"Gizli formül" mü? Cloud Run'da çalışan veri kaynaklarını anlamsal bir köprü olarak akıllıca düzenlemek ve birleştirmek için MCP Toolbox for Databases'i kullanacak, ardından Agent Development Kit (ADK)'i kullanarak birden fazla temsilci içeren bir sohbet uygulaması dağıtacaksınız. Yalnızca bir arama çubuğu değil, bağlamı anlayan, kısıtlamalara uyan ve ham veriler ile insan niyeti arasındaki boşluğu dolduran akıllı bir perakende beyni oluşturuyorsunuz.

İmkansız Kullanıcı Sorgusu

Standart e-ticaret temsilcileri, ç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, bir perakende sitesiyle genellikle şu şekilde konuşmak isterim:

"Merhaba, yüksek irtifada fotoğraf çekimi yapacağım bir gezi 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ünün stokta olup olmadığını ve diğer fotoğrafçıların yorumlarda kayışın dayanıklılığıyla ilgili şikayette bulunup bulunmadığını da öğrenmek istiyorum."

Bu sorgu neden "Temsilci Katili" olarak adlandırılıyor?

  • Görsel benzerlik (AlloyDB + Vektör Arama): "AeroGlow Pro'ya benzer tarzda" 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ş özelliklerin filtrelenmesini gerektirir.
  • Gerçek zamanlı envanter (AlloyDB): "Gerçekten stokta" ifadesi, eski bir arama dizini yerine canlı bir işlem kontrolü gerektirir.
  • Semantik Sentez (BigQuery + Çoklu Temsilci): "Kayış dayanıklılığı" ile ilgili yorumları analiz etmek için temsilcinin 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şlem verileri ve MongoDB'deki esnek özellikler gibi tüm bu kaynaklarda aynı anda "akıl yürütmesini" sağlamak için MCP Toolbox'ı kullanıyoruz. Haydi inşa edelim.

Yapacaklarınız

E-ticaret çoklu veritabanı mimarisi

Ön koşullar

2. Başlamadan önce

Google Cloud projesi oluşturma

  1. Google Cloud Console'da, 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ı nasıl kontrol edeceğinizi öğ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 konsolunun üst kısmından Activate Cloud Shell'i (Cloud Shell'i etkinleştir) tıklayın.
  2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı doğrulayın:
    gcloud auth list
  3. Projenizin yapılandırıldığını doğrulayın:
    gcloud config get project
  4. Projeniz beklendiği gibi ayarlanmamışsa ayarlayın:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Değişkenleri ayarlama

Cloud Shell'de proje kimliğiniz ve proje numaranız için ortam değişkenlerini ayarlayın:

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Gerekli API'leri etkinleştirme

Gerekli tüm API'leri etkinleştirmek için şu 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 devasa bir depolama alanı 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-images).
  3. Oluştur'u tıklayın.
  4. Demo uygulamasının kimlik doğrulama olmadan resimlere erişmesine izin vermek için Enforce public access prevention on this bucket (Bu pakette genel erişim engeli uygula) seçeneğinin işaretini kaldırın ve Confirm'ü (Onayla) tıklayın.
  5. İzinler sekmesine gidin.
  6. İzinler'de Erişim izni ver'i tıklayın.
  7. Yeni ana hesaplar bölümüne allUsers yazın.
  8. Select a role (Rol seçin) bölümünde Cloud Storage > Storage Object Viewer'ı (Depolama Alanı Nesne Görüntüleyici) seçin.
  9. Save'i (Kaydet) tıklayın, ardından kaynağı herkese açık hâle getirdiğinizi onaylamak için Allow Public Access'i (Genel Erişime İzin Ver) tıklayın.
  10. Cloud Shell'de paket adını bir değişkene kaydedin:
    export BUCKET=<your-bucket-name>
    ifadesini, oluşturduğunuz paketin adıyla değiştirin.

Yer tutucu resimler yükleme

Proje, en iyi görsel deneyim için yer tutucu görseller kullanır.

  1. Cloud Shell'de depoyu klonlayın:
    git clone https://github.com/AbiramiSukumaran/polyglot-persist-ecommerce.git
  2. UploadImages klasörüne gidin:
    cd polyglot-persist-ecommerce/UploadImages
  3. Örnek resimleri paketinize yükleyin:
    gcloud storage cp *.jpg gs://$BUCKET/

4. AlloyDB'yi ayarlama

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

AlloyDB kümesi temel hazırlığı yapma

  1. Google Cloud Console'da AlloyDB for PostgreSQL'e gidin.
  2. Küme Oluştur'u tıklayın.
  3. Cluster ID (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. Database Version (Veritabanı Sürümü) için varsayılan değeri değiştirmeyin.
  6. Region (Bölge) olarak us-central1 (veya tercih ettiğiniz bölgeyi) seçin.

Birincil örneği yapılandırma

  1. Instance ID (Örnek kimliği) alanına ecommerce-cluster-primary yazın.
  2. Zonal availability (Alt bölge kullanılabilirliği) bölümünde Single zone'u (Tek alt bölge) seçin.
  3. Machine series (Makine serisi) için N2, Machine type (Makine türü) için 4 vCPU, 32 GB değerini seçin.
  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 ayarlanmadıysa Ağ kurulumunu onayla'yı tıklayarak bir ağ oluşturun.
  5. Genel IP Bağlantısı bölümünde, MCP araç kutusunun bu codelab'de düzgün şekilde bağlanması için Genel IP'yi etkinleştir onay kutusunu işaretleyin. Konsol, AlloyDB'nin herkese açık IP için gerektirdiği password.enforce_complexity işaretini otomatik olarak etkinleştirir.
  6. Yetkili harici ağlar bölümüne 0.0.0.0/0 değerini girin. Riskleri kabul ediyorum onay kutusunu işaretleyin ve Kaydet'i tıklayın.
  7. Küme Oluştur'u tıklayın.

Veritabanını başlatma

  1. Soldaki gezinme menüsünden AlloyDB Studio'yu tıklayın.
  2. Veritabanı açılır menüsünde postgres seçeneğini belirleyin.
  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. Password (Şifre) alanına daha önce belirlediğiniz şifreyi girin.
  6. Kimlik 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ıp 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 projenin kök klasörüne gidin:
    cd ~/polyglot-persist-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 sekmesine 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 dizin oluşturmak için Run'ı (Çalıştır) tıklayın:
    CREATE INDEX idx_products_core_sku ON products_core_table(sku);

Yapay zeka ajanının benzer ürünleri getirmesi için resim yerleştirmeleri oluşturma

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 1408 boyutlu vektörlerdir ve img_embeddings sütununda depolanır.

Yerleştirme oluşturabilmemiz için AlloyDB hizmet hesabına Cloud Storage'a erişmek üzere gerekli rolleri vermemiz gerekir.

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

AlloyDB hizmet hesabına, Cloud Storage'dan resim okumak ve Vertex AI yerleştirmeleri oluşturmak için gereken rolleri verin:

for role in roles/storage.objectUser roles/storage.objectViewer roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role=$role --condition=None
done

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ştirmeleri 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 kullanacağı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ıp 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. img_embeddings sütununu products_core_table tablosuna ekleyin.
    ALTER TABLE products_core_table
ADD COLUMN img_embeddings vector(1408);
  2. Yerleştirme sorgusunu, paket adınız doldurulmuş şekilde yazdırın:
    cd ~/polyglot-persist-ecommerce
sed "s/<STORAGE_BUCKET_NAME>/$BUCKET/g" alloydb_generate_embeddings.sql
  3. Çıkışı kopyalayıp yeni bir AlloyDB Studio sorgu sekmesine yapıştırın ve Run'ı (Çalıştır) tıklayın. Bu işlem yaklaşık bir dakika sürer. Zaman aşımına uğrarsa tekrar çalıştırın. Yerleştirilmiş ürünler atlanır.

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 (tıklamalar ve görüntülemeler gibi) depolar.

MongoDB kümesi oluşturma

  1. MongoDB Atlas'ta oturum açın (gerekirse ücretsiz bir hesap oluşturun).
  2. Deploy your cluster (Kümenizi dağıtın) bölümünde Free'yi (Ücretsiz) seçin. (Atlas, ücretli bir katmanı önceden seçer. Ücretsiz'in seçili olduğundan emin olun.)
  3. Provider (Sağlayıcı) için Google Cloud'u, Region (Bölge) için Iowa (us-central1)'ı seçin.
  4. Name (Ad) alanına ecommerce-cluster yazın ve Preload sample dataset (Örnek veri kümesini önceden yükle) seçeneğinin işaretini kaldırın.
  5. Create Deployment'ı (Dağıtım Oluştur) tıklayın.

Erişime izin verme ve veritabanı kullanıcısı oluşturma

Atlas, Connect to ecommerce-cluster (ecommerce-cluster'a bağlan) iletişim kutusunu açar.

  1. Farklı bir IP adresi ekle'yi tıklayın, 0.0.0.0/0 adresini girin ve ekleyin.
  2. Username (Kullanıcı adı) için store-user, Password (Şifre) için storeuser değerini girip Create Database User'ı (Veritabanı Kullanıcısı Oluştur) tıklayın.
  3. Choose a connection method'ı (Bağlantı yöntemi seçin), ardından Drivers and Client Libraries'i (Sürücüler ve İstemci Kitaplıkları) tıklayın.
  4. Bu bağlantı dizesini uygulamanızda kullanın bölümünde bağlantı dizesini kopyalayın. mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/ gibi görünüyor. değerini storeuser ile değiştirip dizeyi kaydedin. Bu dizeyi tools.yaml içinde kullanacaksınız.

Veritabanı ve koleksiyon oluşturma

  1. Soldaki gezinme menüsünde Veri Gezgini'ni, ardından Veritabanı oluştur'u tıklayın ve ayrıntıları girin:
    • Veritabanı Adı: ecommerce_db
    • Koleksiyon Adı: product_details_collection
  2. Veritabanı oluştur'u tıklayın.
  3. Veri Gezgini'nde koleksiyon adını seçin.
  4. Veri ekle (+) simgesini, ardından Doküman ekle'yi tıklayın.
  5. product_details_export.json dosyasındaki JSON içeriğini kopyalayıp Insert Document (Doküman Ekle) düzenleyici iletişim kutusuna yapıştırın.
  6. Atlas, metni kabuk söz dizimine dönüştürmeyi öneren bir banner gösterir. DÖNÜŞTÜR'ü ve ardından Ekle'yi tıklayın. 192 dokümanın eklendiğini doğrulayın.
  7. Veri Gezgini'nde, ecommerce_db veritabanının yanındaki Koleksiyon oluştur (+) seçeneğini tıklayın.
  8. Koleksiyon adı olarak user_interactions_collection girin ve Create Collection'ı (Koleksiyon Oluştur) tıklayın.
  9. Veri Gezgini'nde user_interactions_collection koleksiyonunu seçin.
  10. Veri ekle (+) simgesini, ardından Doküman ekle'yi tıklayın.
  11. user_interactions_export.json dosyasındaki JSON içeriğini kopyalayıp Insert Document (Doküman Ekle) düzenleyici iletişim kutusuna yapıştırın.
  12. Atlas, metni kabuk söz dizimine dönüştürmeyi öneren bir banner gösterir. DÖNÜŞTÜR'ü ve ardından Ekle'yi tıklayın. 211 belgenin eklendiğini doğrulayın.

6. BigQuery ayarlarını yapma

BigQuery, akıllı raporlar ve öneriler oluşturmak için geçmiş kullanıcı davranışlarını birleştirir 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 üç nokta menüsünü tıklayın ve Veri kümesi oluştur'u seçin.
  3. Veri Kümesi Kimliği için ecommerce_analytics değerini girin.
  4. Veri konumu olarak US (multiple regions) seçeneğini belirleyin (tools.yaml yapılandırması US konumunu bekler).
  5. 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 tabloyu 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
);

Compute hizmet hesabına rol verme

Varsayılan Compute hizmet hesabına, MCP Toolbox ve uygulamanın ihtiyaç duyduğu rolleri verin:

for role in \
  roles/bigquery.dataEditor \
  roles/bigquery.jobUser \
  roles/secretmanager.secretAccessor \
  roles/alloydb.client \
  roles/serviceusage.serviceUsageConsumer \
  roles/storage.objectViewer \
  roles/aiplatform.user \
  roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="$role" \
    --condition=None
done

Alternatif olarak, konsolda IAM & Admin > IAM'e (IAM ve Yönetici > IAM) gidin, Grant access'i (Erişim izni ver) tıklayın, hizmet hesabını girin ve aynı rolleri ekleyin.

7. Uygulamayı uçtan uca anlama

Her bileşenin birbiriyle nasıl çalıştığını öğrenmek için birden fazla veritabanı ve hizmet kullanan 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, polyglot-persist-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ğıtırız.

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

  • UploadImages: Resim öğelerini depolar. Genellikle e-ticaret ürün kataloğu için doküman veya görsel içerik amacıyla kullanılır.
  • static: Kullanıcı arayüzünü biçimlendirmek ve etkileşimli hale getirmek için kullanılan CSS ve JavaScript dosyaları gibi uygulamanın statik web öğelerini depolar ( kaynak).
  • templates: Python uygulamasının e-ticaret kataloğu için web sayfalarını dinamik olarak oluşturmak amacıyla kullandığı HTML şablonlarını (büyük olasılıkla Flask için Jinja2) depolar ( kaynak).

Bu depodaki dosyalar, çoklu veritabanı 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 yönetir. Yapılandırma dosyaları ise bulut ortamlarına sorunsuz dağıtım sağlar:

  • app.py: Flask arka ucu ve çoklu veritabanı entegrasyonlarını yönetir.
  • agentengine.py: Vertex AI yapay zeka ajanlarını başlatmak ve yapılandırmak için temel mantık.
  • .env: Veritabanı ve depolama alanı bağlantıları için gizli anahtarları depolar.
  • tools.yaml: Multidb veritabanı işlemleri için MCP Araç Kutusu'nu 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 için 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 sağlanan SQL komut dosyalarını kullanarak resim yerleştirmeleri için vektör sütunları içeren products_core_table tablosunu oluşturun.
  • MongoDB Atlas Kurulumu: Değişken ürün özelliklerini product_details'te depolamak ve gerçek zamanlı tıklama akışlarını user_interactions'ta günlüğe kaydetmek için Google Cloud'da bir küme dağıtın.
  • BigQuery Analytics: Etkileşim günlüklerini birleştirmek için bir veri kümesi oluşturun. Böylece milyonlarca etkinlikte "En Popüler 5" öğeyi belirleyen karmaşık analiz sorguları çalıştırabilirsiniz.
  • 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 kullanarak erişilebildiğinden emin olun.
  • MCP Toolbox dağıtımı: Toolbox'ı Cloud Run'a dağıtarak doğal dil niyetini çoklu veritabanı sorgularına çeviren merkezi RESTful köprüsü olarak oluşturun.
  • Tools.yaml yapılandırması: "Araçlarınızı" (ör. get_product_core_data veya get_top_5_views) tanımlayın. Belirli SQL ve NoSQL işlemlerini, temsilci tarafından okunabilen basit adlarla eşleyin.
  • Flask arka uç mantığı: MCP Araç Kutusu ile arayüz oluşturan, veri alma koordinasyonunu yöneten ve kullanıcı arayüzü için API görevi gören app.py rotalarını uygulayın.
  • Çoklu Temsilci Düzenleme: Kod içindeki ADK temsilcilerini, kullanıcı niyetini anlamak ve karmaşık, çok kaynaklı perakende sorgularını çözmek için doğru "Aracı" seçmek üzere yapılandırın.
  • Ön uç entegrasyonu: Etkileşimleri kaydetme özelliğine sahip ürün kataloğunu içeren bir index.html arayüzü, ürün performansı analizlerini anlamak için Analytics sekmesi ve sorunsuz bir sohbet tabanlı alışveriş deneyimi sunmak için ADK çoklu temsilci sohbetini kullanan özel bir "Temsilci sekmesi" oluşturun.

Şimdi de orkestrasyonu 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 olarak alıp yazmasına olanak tanır.

MCP Toolbox'ı yerel olarak yükleme

MCP Araç Kutusu ikili programını ana dizininize indirin ve yürütülebilir hale getirin:

export VERSION=1.15.0
curl -L -o ~/toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/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 kuracağını bildirir.

  1. Depoda zaten tools.yaml var. Açın:
    cd ~/polyglot-persist-ecommerce
cloudshell edit tools.yaml
  2. ***** yer tutucularını kendi değerlerinizle değiştirin:

    Veritabanı

    Alan

    Örnek Değer

    AlloyDB/BigQuery

    project

    YOUR_PROJECT_ID

    AlloyDB

    region

    us-central1

    AlloyDB

    cluster

    ecommerce-cluster

    AlloyDB

    instance

    ecommerce-cluster-primary

    AlloyDB

    database

    postgres

    AlloyDB

    password

    alloydb

    AlloyDB

    ipType

    public (yoksa bu satırı alloydb-source altına ekleyin)

    MongoDB

    uri

    Daha önce kaydettiğiniz bağlantı dizesi

  3. Resim önizlemelerini paketinize yönlendirin:
    sed -i "s/ecommerce-app-images/$BUCKET/g" tools.yaml

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

  1. Cloud Shell terminalinizde, kullanıcı arayüzünü sunmak için araç kutusunu yerel olarak çalıştırın:
    ~/toolbox --config tools.yaml --ui --enable-api
  2. Cloud Shell'de Web Önizlemesi > Bağlantı noktasını değiştir'i tıklayın, 5000 değerini girin ve açılan URL'nin sonuna /ui ifadesini ekleyin.

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

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

İşiniz bittiğinde yerel araç kutusunu durdurmak için Ctrl+C tuşuna basın.

Cloud Run'a dağıt

MCP Toolbox'ı Cloud Run'a dağıtarak uygulamanızın veritabanlarını sorgulamak için kullanabileceği güvenli ve yönetilen bir hizmet olarak kullanılabilir hale getirin. Hassas bağlantı ayrıntılarını korumak için yapılandırmayı Secret Manager'da saklayacağız.

  1. tools.yaml yapılandırmasını Google Secret Manager'a yükleyin:
    gcloud secrets create tools --data-file=tools.yaml
    tools.yaml değerini daha sonra değiştirirseniz yeni bir sürüm yükleyin:
    gcloud secrets versions add tools --data-file=tools.yaml
  2. Herkese açık MCP Araç Kutusu container görüntüsünü kullanarak dağıtma:
    gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
    --region us-central1 \
    --service-account ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui","--enable-api" \
    --allow-unauthenticated
    --enable-api, web uygulamasının kullandığı REST API'yi etkinleştirir.
  3. Araç kutusu URL'sini kaydedin:
    export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
echo $TOOLBOX_URL
    Araçları görmek için tarayıcınızda $TOOLBOX_URL/ui adresini açabilirsiniz.

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ış olduğuna göre 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. Fetch core data: AlloyDB'den (list_products_core) ürünlerin tam listesini alır.
  2. Fetch extended details: MongoDB'den (list_all_product_details) tüm ürün ayrıntılarını alır.
  3. Listeleri birleştir: İki listeyi birleştirir.
  4. Medyayla zenginleştirme: Cloud Storage resim URL'sini her öğeye ekler.

Temsilci motorunu oluşturma

  1. Bağımlılıkları yükleyin:
    cd ~/polyglot-persist-ecommerce
pip install -r requirements.txt
    Not: Bu adımda paketlerin çözümlenmesi ve yüklenmesi birkaç dakika sürebilir.
  2. Vertex AI Akıl Yürütme Motoru'nu kullanarak yapay zeka temsilcisini başlatma ve kaydetme:
    export REASONING_ENGINE_LOCATION=us-central1
export APP_NAME=$(python agentengine.py)
echo $APP_NAME
    Çıkış aşağıdakine benzer olacaktır:
    projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

Uygulama, ayarlarını aşağıdaki dağıtım komutunda ilettiğiniz ortam değişkenlerinden okur. Bu nedenle .env dosyasını düzenlemeniz gerekmez.

Ö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 . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="MCP_TOOLBOX_SERVER_URL=$TOOLBOX_URL,GCS_PRODUCT_BUCKET=$BUCKET,FALLBACK_IMAGE_URL=https://storage.googleapis.com/$BUCKET/fallback.jpg,GOOGLE_GENAI_USE_VERTEXAI=TRUE,PROJECT_ID=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,REASONING_ENGINE_LOCATION=$REASONING_ENGINE_LOCATION,APP_NAME=$APP_NAME,MODEL=gemini-3.5-flash"

Uygulamanız artık yayında. Multidb Ecommerce 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ı göreceksiniz.Ürün Bilgileri
  3. MongoDB'ye gönderilen sahte görünümler ve yazma işlemleri oluşturmak için ürün kataloğuyla etkileşim kurun.
  4. Ürün analizlerini görüntülemek için ETL ve Analytics'i tıklayın. Ürün analizlerinin BigQuery'den alındığını göreceksiniz.
    Ürün ETL'si ve Analizleri
  5. Yapay zeka ajanıyla etkileşim kurmak için Yapay zeka ajanı sekmesini tıklayın. Doğal dilde sorular sorun. Örneğin:
    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 askı dayanıklılığıyla ilgili şikayet olmayan bir sırt çantası.

Yapay Zeka Temsilcisi

11. Temizleme

Google Cloud hesabınızdan ücret alınmaya devam etmemesi için bu codelab'de oluşturulan kaynakları silin.

Şu Cloud Shell komutlarını çalıştırın:

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete polyglot --region us-central1 --quiet
gcloud secrets delete tools --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://$BUCKET
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

İsteğe bağlı olarak Agent Engine örneğini silebilirsiniz:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1/$APP_NAME?force=true"

Alternatif olarak, Google Cloud Console'da Vertex AI > Agent Engine'a gidip örneği silebilirsiniz.

İ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 birleştirici olarak nasıl kullanıldığını gösterdiniz. Doğru veritabanını doğru işe eşleştirerek şunları başardınız:

  • Esnek Veri Yazma İşlemleri: Olay günlükleri için MongoDB.
  • İşlem tutarlılığı: Temel bütünlük için AlloyDB.
  • Yüksek performanslı analiz: İş zekası için BigQuery.
  • Birleştirilmiş geliştirme: MCP Araç Kutusu'nu kullanarak tüm karmaşıklığı soyutlayan tek bir Python arka ucu.

Referans belgeler

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

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