Membangun Katalog E-commerce Cerdas dengan Persistensi Multi-database

1. Pengantar

Dalam retail modern, data Anda adalah ekosistem yang beragam dan luas. Anda memiliki data transaksional yang sangat andal (harga dan inventaris), katalog polimorfik yang "berantakan" (spesifikasi elektronik vs. ukuran pakaian), dan log perilaku dalam petabyte. Memaksakan semuanya menjadi satu monolit tidak hanya menciptakan utang teknis, tetapi juga merusak pengalaman pengguna.

Dalam codelab ini, Anda akan merancang Polyglot Powerhouse yang menyelaraskan:

  • AlloyDB: Tulang punggung transaksional Anda untuk konsistensi berkecepatan tinggi dan penyematan gambar.
  • MongoDB Atlas di Google Cloud: Lapisan katalog fleksibel dan agnostik skema Anda.
  • Cloud Storage: Otak analitis Anda untuk peramalan tren real-time.
  • BigQuery: Data warehouse digital beresolusi tinggi.

"Bumbu rahasia"? Anda akan menggunakan MCP Toolbox for Databases untuk mengorkestrasi dan menyatukan sumber data yang berjalan di Cloud Run secara cerdas sebagai jembatan semantik, lalu men-deploy aplikasi chat multi-agen menggunakan Agent Development Kit (ADK). Anda tidak hanya membangun kotak penelusuran, tetapi juga membangun otak retail cerdas yang memahami konteks, mematuhi batasan, dan menjembatani kesenjangan antara data mentah dan maksud manusia.

Kueri Pengguna yang Tidak Mungkin

Agen e-commerce standar gagal dalam penalaran multidimensi (menggabungkan batasan negatif, kemiripan visual, dan inventaris real-time). Misalnya, saya biasanya ingin berbicara dengan situs retail seperti ini:

"Hai, saya sedang merencanakan perjalanan fotografi di dataran tinggi. Tunjukkan beberapa ransel tahan cuaca yang mirip dengan 'AeroGlow Pro' dalam hal gaya, tetapi tanpa komponen kulit. Selain itu, beri tahu saya apakah produk tersebut benar-benar tersedia dan apakah fotografer lain telah mengeluhkan daya tahan tali dalam ulasan."

Alasan kueri ini disebut "The Agent Killer":

  • Kemiripan Visual (AlloyDB + Penelusuran Vektor): "Gaya serupa dengan AeroGlow Pro" memerlukan perbandingan penyematan gambar.
  • Batasan Negatif (MongoDB): "Tanpa kulit" memerlukan pemfilteran melalui atribut bertingkat yang fleksibel yang biasanya tidak ada dalam skema SQL standar.
  • Inventaris Real-Time (AlloyDB): "Tersedia" memerlukan pemeriksaan transaksional langsung (bukan indeks penelusuran yang tidak aktif).
  • Sintesis Semantik (BigQuery + Multi-Agen): Menganalisis ulasan tentang "daya tahan tali jam" mengharuskan agen meringkas masukan tidak terstruktur dari BigQuery secara langsung.

Sebagian besar bot retail hanya akan melihat 'Ransel' dan 'Kulit' lalu menampilkan 10 ransel kulit. Bagaimana cara kami menghentikannya?

Karena kami tidak hanya mencocokkan kata kunci. Kita menggunakan MCP Toolbox untuk memungkinkan agen kita'berpikir' di semua sumber ini secara bersamaan, yaitu kebenaran transaksional di AlloyDB dan atribut fleksibel di MongoDB. Mari kita buat.

Yang akan Anda lakukan

Arsitektur multi-database e-commerce

Prasyarat

2. Sebelum memulai

Buat Project Google Cloud

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

  1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
  2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
    gcloud auth list
  3. Pastikan project Anda dikonfigurasi:
    gcloud config get project
  4. Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Aktifkan API yang diperlukan

Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:

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. Menyiapkan Cloud Storage

Cloud Storage berfungsi sebagai penyimpanan besar untuk aset media tidak terstruktur, seperti gambar produk.

  1. Di Konsol Google Cloud, buka Cloud Storage, lalu klik Buat bucket.
  2. Beri nama yang unik secara global untuk bucket Anda (misalnya, ecommerce-app-images).
  3. Klik Buat.
  4. Untuk mengizinkan aplikasi demo mengakses gambar tanpa autentikasi, hapus centang pada opsi Enforce public access prevention on this bucket, lalu klik Confirm.
  5. Buka tab Izin.
  6. Di bagian Permissions, klik Grant access.
  7. Di New principals, masukkan allUsers.
  8. Di Select a role, pilih Cloud Storage > Storage Object User.
  9. Klik Simpan, lalu klik Izinkan Akses Publik untuk mengonfirmasi bahwa Anda menjadikan resource ini publik.

Mengupload gambar placeholder

BRK2-149-multidb-ecommerce menggunakan gambar placeholder untuk memberikan pengalaman visual terbaik.

  1. Di Cloud Shell, clone repositori next-26-sessions:
    git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git
  2. Buka folder UploadImages:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages
  3. Di Konsol Google Cloud, buka Cloud Storage, lalu klik Buckets.
  4. Klik nama bucket yang baru Anda buat.
  5. Klik Upload > Upload file, pilih contoh gambar yang didownload, lalu klik Buka.

4. Menyiapkan AlloyDB

AlloyDB berfungsi sebagai sumber kebenaran tunggal untuk data terstruktur, transaksional, dan penting seperti ID produk, nama, SKU, harga, dan inventaris. AlloyDB juga mendukung agen AI dengan kemampuan penelusuran kesamaan untuk rekomendasi dan kueri bahasa alami.

Menyediakan Cluster AlloyDB

  1. Di Konsol Google Cloud, buka AlloyDB for PostgreSQL.
  2. Klik Create Cluster.
  3. Untuk Cluster ID, masukkan ecommerce-cluster.
  4. Setel sandi yang kuat untuk pengguna postgres. Untuk tujuan pembelajaran, Anda dapat menggunakan alloydb.
  5. Untuk Database Version, pertahankan nilai default.
  6. Untuk Region, pilih us-central1 (atau wilayah yang Anda inginkan).

Konfigurasi Instance Utama

  1. Untuk Instance ID, masukkan ecommerce-cluster-primary.
  2. Di Zonal Availability, pilih Single zone.
  3. Untuk Machine Type, pilih jenis mesin kecil (misalnya, N2, 4 vCPU, RAM 32 GB).
  4. Di Private IP Connectivity, pilih Private Services Access (PSA), lalu pilih jaringan default.Jika jaringan default belum disetel, klik Confirm network setup untuk membuatnya.
  5. Di Public IP Connectivity, centang kotak Enable Public IP agar toolbox MCP dapat terhubung dengan benar dalam codelab ini.
  6. Di Authorised external networks, masukkan 0.0.0.0/0. Centang kotak Saya memahami risikonya, lalu klik Simpan.
  7. Klik Create Cluster.

Catatan: Pastikan Anda mencatat alamat IP publik Anda (tampilannya mirip dengan 34.124.240.26).

Melakukan Inisialisasi Database

  1. Klik AlloyDB Studio dari menu navigasi kiri.
  2. Di drop-down Database, pilih postgres.
  3. Pilih Built-in authentication untuk login ke database.
  4. Untuk Username, gunakan pengguna postgres.
  5. Untuk Password, masukkan sandi yang Anda tetapkan sebelumnya.
  6. Klik Autentikasikan.
  7. Di tampilan editor, buka tab Untitled query yang baru.
  8. Salin DDL berikut, lalu klik Run:
    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. Di Cloud Shell, buka folder BRK2-149-multidb-ecommerce:
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  10. Buka file alloydb_insert_queries.sql di Cloud Shell Anda dan salin kueri penyisipan.
    cat alloydb_insert_queries.sql
  11. Di tab kueri tanpa judul yang baru, tempelkan hanya pernyataan INSERT dan klik Run.
  12. Di tab kueri baru yang belum diberi judul, salin DDL berikut dan klik Run untuk membuat indeks pada tabel products_core_table:
    CREATE INDEX idx_products_core_sku ON products_core_table(sku);

Membuat embedding gambar untuk agen AI guna mengambil produk serupa

Integrasi agen AI menggunakan embedding gambar untuk mengambil produk serupa. Embedding dibuat menggunakan model multimodalembedding@001 dan disimpan dalam database AlloyDB. Embedding adalah vektor berdimensi 1408 dan disimpan di kolom img_embeddings.

Sebelum dapat membuat penyematan, kita harus memberikan peran yang diperlukan ke akun layanan AlloyDB untuk mengakses Cloud Storage.

Memberikan peran ke akun layanan AlloyDB untuk mengakses Cloud Storage

Kami memberikan peran Storage Object User dan Storage Object Viewer ke akun layanan AlloyDB agar dapat membaca objek dari bucket Cloud Storage.

  1. Buka IAM dan admin.
  2. Klik Grant access.
  3. Di kolom New principals, masukkan akun layanan penelusuran untuk AlloyDB. Akun layanan akan terlihat seperti service-991742412753@gcp-sa-alloydb.iam.gserviceaccount.com.
  4. Klik Pilih peran.
  5. Temukan dan pilih peran Storage Object User.
  6. Klik Tambahkan peran lain, lalu pilih peran Storage Object Viewer.
  7. Klik Add another role, lalu pilih peran Vertex AI User.
  8. Klik Simpan.

Mengaktifkan ekstensi

Untuk membangun aplikasi ini, kita akan menggunakan ekstensi pgvector dan google_ml_integration. Ekstensi pgvector memungkinkan Anda menyimpan dan menelusuri embedding vektor. Ekstensi google_ml_integration menyediakan fungsi yang Anda gunakan untuk mengakses endpoint prediksi Vertex AI guna mendapatkan prediksi di SQL. Aktifkan ekstensi ini dengan menjalankan DDL berikut:

  1. Di Konsol Google Cloud, buka AlloyDB for PostgreSQL.
  2. Klik AlloyDB Studio dari menu navigasi kiri.
  3. Di tampilan editor, buka tab Untitled query yang baru.
  4. Salin DDL berikut, lalu klik Run:
    CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration;

Melakukan inisialisasi database dengan embedding

  1. Tambahkan kolom img_embeddings ke products_core_table.
    ALTER TABLE products_core_table
ADD COLUMN img_embeddings vector(1408);
  2. Buat embedding untuk gambar dan simpan di kolom img_embeddings.
    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
);
    Ganti dengan nama bucket Cloud Storage Anda.
  3. Ulangi kueri sebelumnya setidaknya 5 kali untuk membuat sematan gambar untuk seluruh set, karena Studio memiliki batasan 5 menit. Jika kueri ini kehabisan waktu, ubah LIMIT menjadi 5 dan jalankan kembali kueri sepuluh kali. Langkah ini mungkin memerlukan waktu beberapa menit hingga selesai.

5. Menyiapkan MongoDB Atlas di Google Cloud

MongoDB menyimpan detail produk semi-terstruktur yang lengkap dan data perilaku pengguna yang fleksibel (seperti klik dan tampilan).

Membuat cluster MongoDB

  1. Buka MongoDB Atlas di Google Cloud, pilih akun paket gratis.
  2. Pilih tingkat cluster Gratis, lalu masukkan nama untuk cluster, misalnya ecommerce-cluster.
  3. Pilih Google Cloud sebagai penyedia dan pastikan regionnya sesuai dengan region Google Cloud Anda (misalnya, us-central1).
  4. Klik Create Deployment.
  5. Klik Tutup.

Mengonfigurasi Akses Jaringan

  1. Di konsol Atlas, buka Database & Network Access.
  2. Klik Daftar Akses IP.
  3. Klik Tambahkan Alamat IP.
  4. Tambahkan 0.0.0.0/0, yang memungkinkan akses dari mana saja.
  5. Klik Konfirmasi.

Membuat Pengguna Database

  1. Di konsol Atlas, buka Database & Network Access.
  2. Klik Pengguna Database.
  3. Klik Tambahkan Pengguna Database Baru.
  4. Pilih Sandi sebagai metode autentikasi.
  5. Masukkan nama pengguna sebagai store-user dan sandi sebagai storeuser.
  6. Klik Add Built In Role, lalu pilih Read and write to any database.
  7. Klik Tambahkan Pengguna.

Mendapatkan String Koneksi

  1. Buka Database > Clusters > Connect.
  2. Di Hubungkan aplikasi Anda, klik Driver.
  3. Salin string koneksi yang ditampilkan di Tambahkan string koneksi ke kode aplikasi Anda. String akan terlihat seperti ini:
    mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
    Ganti db_password dengan sandi MongoDB Anda. Dalam codelab ini, nilainya adalah storeuser.

Simpan string koneksi ini. Anda akan menggunakannya nanti untuk variabel lingkungan MONGODB_CONNECTION_STRING.

Membuat Database dan Kumpulan

  1. Di konsol Atlas, buka Database > Clusters > Browse Collections.
  2. Klik Create Database dan masukkan detailnya:
    • Nama Database: ecommerce_db
    • Nama Koleksi: product_details_collection
  3. Klik Create database.
  4. Di Data Explorer, pilih Nama Kumpulan.
  5. Klik ikon Tambahkan Data (+), lalu klik Sisipkan dokumen.
  6. Salin konten JSON dari product_details_export.json dan tempelkan ke dialog editor Insert Document.
  7. Klik Sisipkan untuk menyisipkan array dokumen dan verifikasi bahwa 192 dokumen telah ditambahkan.
  8. Di Data Explorer, klik Create collection (+) di samping database ecommerce_db.
  9. Masukkan user_interactions_collection untuk nama koleksi, lalu klik Buat Koleksi.
  10. Di Data Explorer, pilih koleksi user_interactions_collection.
  11. Klik ikon Tambahkan Data (+), lalu klik Sisipkan dokumen.
  12. Salin konten JSON dari user_interactions_export.json dan tempelkan ke dialog editor Insert Document.
  13. Klik Sisipkan Dokumen.

6. Menyiapkan BigQuery

BigQuery menggabungkan dan menganalisis perilaku pengguna historis untuk menghasilkan pelaporan dan rekomendasi yang cerdas.

Membuat Set Data

  1. Di Konsol Google Cloud, buka BigQuery.
  2. Di samping project ID Anda di panel Explorer, klik menu tiga titik, lalu pilih Create dataset.
  3. Masukkan ecommerce_analytics untuk ID Set Data.
  4. Klik Create dataset.

Membuat Tabel Analytics

  1. Buka kueri baru di ruang kerja BigQuery.
  2. Jalankan pernyataan SQL berikut untuk membuat tabel ringkasan yang menghubungkan pengguna dengan interaksi produk:
CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

Memberikan peran ke akun layanan Compute untuk MCP Toolbox

Kami memberikan peran ke akun layanan Compute yang digunakan untuk Toolbox kami. Hal ini dilakukan untuk memungkinkan Toolbox MCP mengakses BigQuery, Secret Manager, dan layanan cloud lainnya.

Untuk memberikan peran, selesaikan langkah-langkah berikut:

  1. Buka IAM dan admin.
  2. Klik Grant access.
  3. Di kolom New principals, masukkan akun layanan Compute default yang bernama YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. Ganti YOUR_PROJECT_NUMBER dengan Nomor Project Google Cloud Anda.
  4. Klik Pilih peran.
  5. Temukan dan pilih peran BigQuery Data Editor.
  6. Klik Add another role, lalu pilih peran BigQuery Job User.
  7. Klik Tambahkan peran lain, lalu pilih peran Secret Manager Secret Accessor.
  8. Klik Tambahkan peran lain, lalu pilih peran Editor.
  9. Klik Simpan.

7. Memahami Aplikasi secara Menyeluruh

Untuk mempelajari cara kerja setiap komponen satu sama lain, kita akan membuat aplikasi e-commerce sederhana yang menggunakan beberapa database dan layanan. Aplikasi ini dibangun dengan backend Python (Flask) dan mengintegrasikan beberapa layanan dan database Google Cloud.

Memahami struktur direktori

Di bagian berikutnya, Anda akan meng-clone repositori BRK2-149-multidb-ecommerce dan menggunakannya untuk menjalankan aplikasi secara lokal. Setelah menguji aplikasi secara lokal, kita akan men-deploy MCP Toolbox dan aplikasi ke Cloud Run.

Jelajahi file yang didownload di direktori ini. Direktori tingkat tinggi berikut ada:

  • UploadImages: menyimpan aset gambar, terutama digunakan untuk dokumentasi atau konten visual untuk katalog produk e-commerce.
  • static: menyimpan aset web statis aplikasi, seperti file CSS dan JavaScript, yang digunakan untuk menata gaya dan menambahkan interaktivitas ke antarmuka pengguna ( sumber).
  • templates: menyimpan template HTML (kemungkinan Jinja2 untuk Flask) yang digunakan oleh aplikasi Python untuk merender halaman web secara dinamis untuk katalog e-commerce ( sumber).
  • toolbox-implementation: menyimpan detail konfigurasi dan penerapan untuk Toolbox Model Context Protocol (MCP), sehingga memfasilitasi interaksi database multidb menggunakan alat yang telah ditentukan sebelumnya.

File dalam repositori ini bekerja sama untuk mem-build, mengonfigurasi, dan men-deploy aplikasi e-commerce multidb. File pusat seperti app.py mengatur backend dengan mengintegrasikan berbagai sumber data yang ditentukan dalam file SQL dan JSON, sementara file konfigurasi memastikan deployment yang lancar ke lingkungan cloud:

  • app.py: mengatur integrasi backend Flask dan multi-database.
  • agentengine.py: Logika inti untuk menginisialisasi dan mengonfigurasi agen Vertex AI.
  • .env: menyimpan rahasia untuk koneksi database dan penyimpanan.
  • tools.yaml: mengonfigurasi MCP Toolbox untuk operasi database multidb.
  • Dockerfile: menentukan penyiapan lingkungan dan image container.
  • requirements.txt: mencantumkan library Python yang diperlukan untuk runtime aplikasi.
  • tools.yaml: konfigurasi untuk MCP Toolbox.
  • Procfile: menentukan perintah eksekusi produksi untuk deployment.
  • alloydb_insert_queries.sql: berisi kueri SQL untuk data relasional.
  • product_details_export.json dan user_interactions_export.json: menyediakan contoh data JSON untuk database NoSQL.
  • README.md: memandu penyiapan, deployment, dan pemahaman project.

Alur Aplikasi End-to-End

  • Penyiapan AlloyDB: Sediakan cluster berperforma tinggi dan gunakan skrip SQL yang disediakan untuk membuat products_core_table dengan kolom vektor untuk embedding gambar.
  • Penyiapan MongoDB Atlas: Deploy cluster di Google Cloud untuk menyimpan atribut produk yang berubah-ubah di product_details dan mencatat clickstream real-time di user_interactions.
  • BigQuery Analytics: Buat set data untuk menggabungkan log interaksi, sehingga memungkinkan kueri analitik kompleks yang mengidentifikasi item trending "Top 5" di jutaan peristiwa.
  • Repositori Cloud Storage: Buat bucket publik untuk menampung gambar produk beresolusi tinggi, dengan memastikan setiap aset dapat diakses melalui URL bertanda tangan atau publik untuk frontend.
  • Deployment MCP Toolbox: Deploy Toolbox ke Cloud Run, menjadikannya sebagai jembatan RESTful pusat yang menerjemahkan maksud bahasa alami menjadi kueri multi-database.
  • Konfigurasi Tools.yaml: Tentukan "Alat" Anda—seperti get_product_core_data atau get_top_5_views—yang memetakan operasi SQL dan NoSQL tertentu ke nama sederhana yang dapat dibaca oleh agen.
  • Logika Backend Flask: Terapkan rute app.py yang berinteraksi dengan MCP Toolbox, menangani koordinasi pengambilan data, dan berfungsi sebagai API untuk UI.
  • Orkestrasi Multi-Agen: Konfigurasi agen ADK dalam kode untuk memahami maksud pengguna, memilih "Alat" yang tepat untuk menyelesaikan kueri retail multi-sumber yang kompleks.
  • Integrasi Frontend: Buat antarmuka index.html yang menampilkan katalog produk dengan fitur perekaman interaksi, tab Analytics untuk memahami analisis performa produk, dan "Tab Agen" khusus yang menggunakan chat multiagen ADK untuk memberikan pengalaman belanja percakapan yang lancar.

Sekarang, mari kita terapkan orkestrasi dan deployment.

8. Menyiapkan MCP Toolbox dan Men-deploy ke Cloud Run

MCP Toolbox mengabstraksi beberapa sumber data kami, sehingga aplikasi kami dapat mengambil dan menulis data secara seragam.

Menginstal MCP Toolbox Secara Lokal

  1. Di Cloud Shell, buka folder toolbox-implementation:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  2. Download program biner MCP Toolbox dan setel agar dapat dijalankan:
    export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Mengonfigurasi tools.yaml

Anda perlu menentukan abstraksi untuk AlloyDB, MongoDB, dan BigQuery. File tools.yaml memberi tahu toolbox MCP cara berinteraksi satu sama lain.

  1. Buat dan edit file tools.yaml menggunakan editor sematan:
    cloudshell edit tools.yaml
    File tools.yaml lengkap dapat ditemukan di Repositori GitHub. Salin isinya ke file tools.yaml baru Anda.
  2. Perbarui host, pengguna, sandi, project ID, dan string koneksi agar sesuai dengan infrastruktur yang Anda sediakan di langkah-langkah sebelumnya:

    Database

    Kolom

    Nilai Contoh

    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

Memberikan peran ke akun layanan Compute untuk MCP Toolbox

Kami memberikan peran ke akun layanan Compute yang digunakan untuk Toolbox kami. Hal ini dilakukan untuk mengaktifkan MCP Toolbox agar dapat mengakses AlloyDB.

  1. Buka IAM dan admin.
  2. Klik Grant access.
  3. Di kolom New principals, masukkan akun layanan Compute default yang bernama YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com. Ganti YOUR_PROJECT_NUMBER dengan Nomor Project Google Cloud Anda.
  4. Klik Pilih peran.
  5. Temukan dan pilih peran BigQuery Data Editor.
  6. Klik Tambahkan peran lain, lalu pilih peran AlloyDB Client.
  7. Klik Tambahkan peran lain, lalu pilih peran Service Usage Consumer.
  8. Klik Tambahkan peran lain, lalu pilih peran Storage Object Viewer.
  9. Klik Simpan.

Menguji UI alat Anda

  1. Di terminal cloudshell, jalankan toolbox secara lokal untuk menayangkan UI:
    ./toolbox --ui
  2. Buka Pratinjau Web di Cloud Shell pada port 5000 dan buka halaman alat. Misalnya, bergantung pada URL sesi, Anda dapat melihatnya di: https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui

UI MCP toolbox berikut akan terlihat:

UI MCP Toolbox

Men-deploy ke Cloud Run

Deploy MCP Toolbox ke Cloud Run agar tersedia sebagai layanan terkelola yang aman yang dapat digunakan aplikasi kita untuk mengkueri database. Kita akan menyimpan konfigurasi di Secret Manager untuk melindungi detail koneksi sensitif.

  1. Buka sesi Cloud Shell baru.
  2. Buka folder toolbox-implementation:
    cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
  3. Upload konfigurasi tools.yaml ke Google Secret Manager:
    gcloud secrets create tools --data-file=tools.yaml
    Catatan: Untuk menambahkan versi baru ke secret yang ada, gunakan perintah berikut:
    gcloud secrets versions add tools --data-file=tools.yaml
  4. Men-deploy menggunakan image container MCP Toolbox publik:
    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. Setelah di-deploy, catat URL Layanan Cloud Run yang diberikan. Tampilannya akan terlihat seperti https://toolbox-*********-uc.a.run.app/ui.

9. Siapkan aplikasi e-commerce dan deploy ke Cloud Run

Setelah database kita berjalan dan abstraksi MCP Toolbox di-deploy, kita dapat menjalankan aplikasi web Flask.

Untuk menayangkan katalog produk, aplikasi Flask memproses data dengan melakukan langkah-langkah berikut:

  1. Mengambil data inti: Mengambil daftar lengkap produk dari AlloyDB (list_products_core).
  2. Ambil detail tambahan: Mengambil semua detail produk dari MongoDB (list_all_product_details).
  3. Gabungkan daftar: Menggabungkan dua daftar.
  4. Perkaya dengan media: Menambahkan URL gambar Cloud Storage ke setiap item.

Buat jalur aplikasi mesin penalaran

Untuk menginisialisasi dan mendaftarkan agen AI menggunakan Vertex AI Reasoning Engine Google Cloud, jalankan perintah berikut:

  1. Di terminal cloudshell, buka folder BRK2-149-multidb-ecommerce.
    cd next-26-sessions/BRK2-149-multidb-ecommerce
  2. Jalankan requirements.txt untuk menginstal dependensi
    pip install -r requirements.txt
  3. Jalankan skrip agentengine.py untuk membuat jalur aplikasi mesin penalaran:
    python agentengine.py

Outputnya akan seperti ini:

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

Mengonfigurasi Variabel Lingkungan

  1. Buat file .env dan edit:
    cloudshell edit .env
  2. Ganti nilai dengan koneksi database spesifik dan URL Toolbox Cloud Run yang baru:
    # 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

Men-deploy Frontend ke Cloud Run

  1. Deploy aplikasi web ke Cloud Run untuk melengkapi arsitektur:
    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"
    Ganti nilai berikut:
    • YOUR_PROJECT_ID: Project ID Google Cloud Anda.
    • YOUR_REASONING_ENGINE_APP_PATH: Output dari menjalankan python agentengine.py, misalnya, projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856.
    • MCP_TOOLBOX_SERVER_URL: URL server MCP Toolbox Anda, misalnya https://toolbox-*********-uc.a.run.app.
    • GCS_PRODUCT_BUCKET: Nama bucket Google Cloud Storage Anda, misalnya ecommerce-app-images.
    • MONGODB_CONNECTION_STRING: String koneksi untuk database MongoDB Anda, misalnya mongodb+srv://store-user:storeuser@ecommerce-cluster.g8vaekh.mongodb.net
    • FALLBACK_IMAGE_URL: URL gambar pengganti, misalnya https://storage.googleapis.com/ecommerce-app-images/fallback.jpg

Aplikasi Anda kini sudah aktif. Buka URL layanan yang disediakan oleh Cloud Run untuk melihat katalog Multidb Ecommerce. URL-nya akan mirip dengan https://polyglot-*********-uc.a.run.app/.

10. Menjelajahi aplikasi

  1. Klik Katalog Produk untuk melihat semua produk.
    Katalog Produk
  2. Klik ikon produk untuk melihat detail produk. Anda akan melihat bahwa gambar berasal dari Cloud Storage, detail produk diambil dari MongoDB, dan inventaris produk diambil dari AlloyDB.Detail Produk
  3. Berinteraksi dengan katalog produk untuk membuat tampilan dan penulisan tiruan yang dikirim ke MongoDB.
  4. Klik ETL & Analytics untuk melihat analisis produk. Anda akan melihat bahwa analisis produk diambil dari BigQuery.
    ETL dan Analisis Produk
  5. Klik tab Agen AI untuk berinteraksi dengan agen AI. Ajukan pertanyaan bahasa alami seperti berikut:
    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.
    Agen AI

Anda dapat melihat bahwa penelusuran menampilkan persis apa yang kami minta - ransel tanpa komponen kulit, tersedia, dan tidak ada keluhan tentang daya tahan tali dalam ulasan.

Agen AI

11. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.

Jalankan perintah cloud shell berikut:

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

Jika ingin menghapus seluruh project Google Cloud dan semua resourcenya, jalankan perintah berikut:

gcloud projects delete $PROJECT_ID

12. Selamat

Selamat! Anda telah berhasil membangun arsitektur Multidb lintas cloud.

Anda telah menunjukkan bagaimana MCP Toolbox berfungsi sebagai perekat arsitektur untuk aplikasi modern yang terspesialisasi. Dengan mencocokkan database yang tepat dengan pekerjaan yang tepat, Anda mencapai:

  • Penulisan Data yang Fleksibel: MongoDB untuk log peristiwa.
  • Konsistensi Transaksional: AlloyDB untuk integritas inti.
  • Analytics Performa Tinggi: BigQuery untuk intelijen bisnis.
  • Pengembangan Terpadu: Backend Python tunggal yang mengabstraksi semua kompleksitas menggunakan MCP Toolbox.

Dokumen referensi

Pelajari lebih lanjut produk Google Cloud terkait dan jelajahi codelab berikut:

Untuk mengetahui informasi selengkapnya tentang produk yang digunakan dalam codelab ini, lihat: