Tworzenie inteligentnego katalogu e-commerce z utrwalaniem w wielu bazach danych

1. Wprowadzenie

W nowoczesnym handlu detalicznym dane stanowią zróżnicowany, rozległy ekosystem. Masz solidne dane transakcyjne (ceny i asortyment), „nieuporządkowane” katalogi polimorficzne (specyfikacje elektroniki a rozmiary odzieży) i petabajty dzienników zachowań. Wymuszanie połączenia tych elementów w jedną całość nie tylko generuje dług techniczny, ale też pogarsza wrażenia użytkowników.

W tym ćwiczeniu zaprojektujesz wielojęzyczną platformę, która będzie harmonizować:

• AlloyDB baza danych transakcyjnych zapewniająca szybką spójność i osadzanie obrazów.
• MongoDB Atlas w Google Cloud: elastyczna warstwa katalogu niezależna od schematu.
• Cloud Storage: analityczny mózg do prognozowania trendów w czasie rzeczywistym.
• BigQuery: hurtownia cyfrowa o wysokiej rozdzielczości.

„Tajemniczy składnik”? Użyjesz zestawu narzędzi MCP dla baz danych, aby inteligentnie aranżować i ujednolicać źródła danych działające w Cloud Run jako pomost semantyczny, a następnie wdrożyć aplikację do czatu z wieloma agentami za pomocą pakietu Agent Development Kit (ADK). Nie tworzysz tylko paska wyszukiwania, ale inteligentny system, który rozumie kontekst, uwzględnia ograniczenia i łączy surowe dane z intencjami użytkowników.

Niemożliwe zapytanie użytkownika

Standardowe narzędzia do obsługi e-commerce nie radzą sobie z wielowymiarowym rozumowaniem (łączeniem ograniczeń negatywnych, podobieństwa wizualnego i stanu magazynowego w czasie rzeczywistym). Na przykład zwykle chcę rozmawiać z witryną sklepu w ten sposób:

„Hej, planuję wyjazd, żeby robić zdjęcia na dużej wysokości. Pokaż mi plecaki odporne na warunki atmosferyczne, podobne stylem do „AeroGlow Pro”, ale bez elementów skórzanych. Daj mi też znać, czy są one dostępne w magazynie i czy inni fotografowie w swoich opiniach narzekali na trwałość paska”.

Dlaczego to zapytanie jest „zabójcą agentów”:

• Podobieństwo wizualne (AlloyDB + wyszukiwanie wektorowe): „Podobny stylem do AeroGlow Pro” wymaga porównania osadzania obrazów.
• Ograniczenie negatywne (MongoDB): „Bez skóry” wymaga filtrowania elastycznych, zagnieżdżonych atrybutów, które zwykle nie występują w standardowej wersji SQL.
• Asortyment w czasie rzeczywistym (AlloyDB): „Rzeczywiście w magazynie” wymaga sprawdzenia transakcji na żywo (nie nieaktualnego indeksu wyszukiwania).
• Synteza semantyczna (BigQuery + Multi-Agent): analiza opinii dotyczących „trwałości paska” wymaga od agenta podsumowania na bieżąco nieuporządkowanych opinii z BigQuery.

Większość botów w sklepach zobaczy tylko „Plecak” i „Skóra” i wyświetli 10 skórzanych plecaków. Jak temu zapobiegamy?

Nie dopasowujemy tylko słów kluczowych. Korzystamy z MCP Toolbox, aby umożliwić naszym agentom „rozumowanie” na podstawie wszystkich tych źródeł – prawdy transakcyjnej w AlloyDB i elastycznych atrybutów w MongoDB – jednocześnie. Zbudujmy go.

Jakie zadania wykonasz

• Udostępnij klaster AlloyDB na potrzeby podstawowych danych o produktach.
• Skonfiguruj MongoDB Atlas w Google Cloud, aby przechowywać słabo ustrukturyzowane szczegóły produktu.
• Utwórz zasobnik Cloud Storage, który będzie służyć do udostępniania zdjęć produktów.
• Wdrażanie MCP Toolbox for Databases w Cloud Run w celu zapewnienia jednolitego dostępu do danych
• Uruchamiaj procesy ETL, aby przesyłać dane do BigQuery na potrzeby analizy.
• Rozmawiaj z agentem AI w języku naturalnym.

Wymagania wstępne

• przeglądarka, np. Chrome;
• projekt Google Cloud z włączonymi płatnościami;
• bezpłatne konto MongoDB Atlas w Google Cloud;

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google.
2. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Uruchamianie Cloud Shell

Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia.

1. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
2. Po połączeniu z Cloud Shell sprawdź uwierzytelnianie:

   gcloud auth list
   

3. Sprawdź, czy projekt jest skonfigurowany:

   gcloud config get project
   

4. Jeśli projekt nie jest ustawiony zgodnie z oczekiwaniami, ustaw go:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Włącz wymagane interfejsy API

Aby włączyć wszystkie wymagane interfejsy API, uruchom to polecenie:

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

Cloud Storage to ogromny magazyn nieuporządkowanych zasobów multimedialnych, takich jak zdjęcia produktów.

1. W konsoli Google Cloud otwórz Cloud Storage i kliknij Utwórz zasobnik.
2. Nadaj zasobnikowi globalnie niepowtarzalną nazwę (np. ecommerce-app-images).
3. Kliknij Utwórz.
4. Aby umożliwić aplikacji demonstracyjnej dostęp do obrazów bez uwierzytelniania, odznacz opcję Wyegzekwuj blokadę dostępu publicznego do tego zasobnika i kliknij Potwierdź.
5. Otwórz kartę Uprawnienia.
6. W sekcji Uprawnienia kliknij Przyznaj dostęp.
7. W polu Nowe podmioty zabezpieczeń wpisz allUsers.
8. W sekcji Wybierz rolę kliknij Cloud Storage > Użytkownik obiektów Cloud Storage.
9. Kliknij Zapisz, a następnie Zezwól na dostęp publiczny, aby potwierdzić, że udostępniasz zasób publicznie.

Przesyłanie obrazów zastępczych

W BRK2-149-multidb-ecommerce używane są obrazy zastępcze, aby zapewnić jak najlepsze wrażenia wizualne.

1. W Cloud Shell sklonuj repozytorium next-26-sessions:

   git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git
   

2. Przejdź do folderu UploadImages:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages
   

3. W konsoli Google Cloud otwórz Cloud Storage i kliknij Zasobniki.
4. Kliknij nazwę nowo utworzonego zasobnika.
5. Kliknij Prześlij > Prześlij pliki, wybierz pobrane przykładowe obrazy i kliknij Otwórz.

4. Konfigurowanie AlloyDB

AlloyDB jest jedynym źródłem wiarygodnych danych strukturalnych, transakcyjnych i krytycznych, takich jak identyfikatory produktów, nazwy, kody SKU, ceny i stan magazynowy. AlloyDB obsługuje też agenta AI, udostępniając mu funkcje wyszukiwania podobieństw na potrzeby rekomendacji i zapytań w języku naturalnym.

Aby szybko skonfigurować klaster, instancję i sieć dla środowiska programistycznego za pomocą interfejsu internetowego, wykonaj czynności opisane w tym samouczku.

Udostępnianie klastra AlloyDB

1. W konsoli Google Cloud otwórz AlloyDB for PostgreSQL.
2. Kliknij Utwórz klaster.
3. W polu Identyfikator klastra wpisz ecommerce-cluster.
4. Ustaw silne hasło użytkownika postgres. Na potrzeby szkoleniowe możesz użyć nazwy alloydb.
5. W polu Wersja bazy danych zachowaj wartość domyślną.
6. W polu Region wybierz us-central1 (lub preferowany region).

Konfigurowanie instancji głównej

1. W polu Identyfikator instancji wpisz ecommerce-cluster-primary.
2. W sekcji Dostępność strefowa wybierz Jedna strefa.
3. W sekcji Typ maszyny wybierz mały typ maszyny (np. N2, 4 procesory wirtualne, 32 GB pamięci RAM).
4. W sekcji Prywatne środowisko IP wybierz Prywatny dostęp do usług (PSA) i kliknij sieć default.Jeśli sieć domyślna nie jest jeszcze skonfigurowana, kliknij Potwierdź konfigurację sieci, aby ją utworzyć.
5. W sekcji Połączenia przy użyciu publicznego adresu IP zaznacz pole wyboru Włącz publiczny adres IP, aby skrzynka narzędziowa MCP mogła się prawidłowo połączyć w tym module.
6. W polu Autoryzowane sieci zewnętrzne wpisz 0.0.0.0/0. Zaznacz pole wyboru Rozumiem zagrożenia i kliknij Zapisz.
7. Kliknij Utwórz klaster.

Uwaga: zapisz swój publiczny adres IP (wygląda podobnie do 34.124.240.26).

Utworzenie klastra i instancji może potrwać do 10 minut.

Inicjowanie bazy danych

1. W menu nawigacyjnym po lewej stronie kliknij AlloyDB Studio.
2. W menu Baza danych kliknij postgres.
3. Aby zalogować się w bazie danych, wybierz Wbudowane uwierzytelnianie.
4. W polu Nazwa użytkownika wpisz użytkownika postgres.
5. W polu Hasło wpisz hasło ustawione wcześniej.
6. Kliknij Uwierzytelnij.
7. W widoku edytora otwórz nową kartę zapytania bez nazwy.
8. Skopiuj ten kod DDL i kliknij Uruchom:

   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. W Cloud Shell przejdź do folderu BRK2-149-multidb-ecommerce:

   cd next-26-sessions/BRK2-149-multidb-ecommerce
   

10. Otwórz plik alloydb_insert_queries.sql w Cloud Shell i skopiuj zapytania wstawiające.

    cat alloydb_insert_queries.sql
    

11. Na nowej karcie zapytania bez tytułu wklej tylko instrukcje INSERT i kliknij Uruchom.
12. Na nowej karcie zapytania bez tytułu skopiuj ten kod DDL i kliknij Uruchom, aby utworzyć indeks w tabeli products_core_table:

    CREATE INDEX idx_products_core_sku ON products_core_table(sku);
    

Tworzenie osadzeń obrazów, aby agent AI mógł pobierać podobne produkty

Integracja agenta AI wykorzystuje osadzanie obrazów do pobierania podobnych produktów. Wektory dystrybucyjne są generowane za pomocą modelu multimodalembedding@001 i przechowywane w bazie danych AlloyDB. Wektory dystrybucyjne to wektory 1408-wymiarowe, które są przechowywane w kolumnie img_embeddings.

Zanim będziemy mogli wygenerować wektory, musimy przyznać kontu usługi AlloyDB wymagane role, aby uzyskać dostęp do Cloud Storage.

Przyznawanie ról kontu usługi AlloyDB w celu uzyskania dostępu do Cloud Storage

Przypisujemy do konta usługi AlloyDB role użytkownika obiektów Storage i wyświetlającego obiekty Storage, aby umożliwić mu odczytywanie obiektów z zasobnika Cloud Storage.

1. Otwórz Uprawnienia i administracja.
2. Kliknij Przyznaj dostęp.
3. W polu Nowe podmioty zabezpieczeń wpisz wyszukiwane konto usługi AlloyDB. Konto usługi wygląda podobnie do [e-mail].
4. Kliknij Wybierz rolę.
5. Znajdź i wybierz rolę Użytkownik obiektów Cloud Storage.
6. Kliknij Dodaj kolejną rolę i wybierz rolę Wyświetlający obiekty Cloud Storage.
7. Kliknij Dodaj kolejną rolę i wybierz rolę Użytkownik Vertex AI.
8. Kliknij Zapisz.

Włączanie rozszerzeń

Do utworzenia tej aplikacji użyjemy rozszerzeń pgvector i google_ml_integration. Rozszerzenie pgvector umożliwia przechowywanie wektorów dystrybucyjnych i wyszukiwanie ich. Rozszerzenie google_ml_integration udostępnia funkcje, których możesz używać do uzyskiwania dostępu do punktów końcowych prognozowania Vertex AI w celu generowania prognoz w SQL. Włącz te rozszerzenia, uruchamiając te DDL:

1. W konsoli Google Cloud otwórz AlloyDB for PostgreSQL.
2. W menu nawigacyjnym po lewej stronie kliknij AlloyDB Studio.
3. W widoku edytora otwórz nową kartę zapytania bez nazwy.
4. Skopiuj ten kod DDL i kliknij Uruchom:

   CREATE EXTENSION IF NOT EXISTS vector;
   CREATE EXTENSION IF NOT EXISTS google_ml_integration;
   

Inicjowanie bazy danych za pomocą wektorów

1. Dodaj kolumnę img_embeddings do products_core_table.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Wygeneruj wektory dystrybucyjne dla obrazów i zapisz je w kolumnie 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
   );
   

   Zastąp nazwą zasobnika Cloud Storage.
3. Powtórz wcześniejsze zapytanie co najmniej 5 razy, aby wygenerować osadzenia obrazów dla całego zestawu, ponieważ Studio ma limit 5 minut. Jeśli to zapytanie przekroczy limit czasu, zmień LIMIT na 5 i uruchom je ponownie 10 razy. Wykonanie tego kroku może potrwać kilka minut.

5. Konfigurowanie MongoDB Atlas w Google Cloud

MongoDB przechowuje szczegółowe, częściowo ustrukturyzowane szczegóły produktu i elastyczne dane o zachowaniach użytkowników (np. kliknięcia i wyświetlenia).

Tworzenie klastra MongoDB

1. Otwórz MongoDB Atlas w Google Cloud i wybierz konto z poziomu bezpłatnego.
2. Wybierz poziom klastra Bezpłatny i wpisz nazwę klastra, np. ecommerce-cluster.
3. Wybierz Google Cloud jako dostawcę i upewnij się, że region jest zgodny z regionem Google Cloud (np. us-central1).
4. Kliknij Utwórz wdrożenie.
5. Kliknij Zamknij.

Konfigurowanie dostępu do sieci

1. W konsoli Atlas otwórz Database & Network Access (Dostęp do bazy danych i sieci).
2. Kliknij Lista dostępu IP.
3. Kliknij Dodaj adres IP.
4. Dodaj 0.0.0.0/0, który zezwala na dostęp z dowolnego miejsca.
5. Kliknij Potwierdź.

Użycie 0.0.0.0/0 zezwala na dostęp z dowolnego adresu IP. Jest to dopuszczalne w przypadku tymczasowej wersji demonstracyjnej, ale w wersji produkcyjnej należy ograniczyć dostęp do określonych zakresów adresów IP.

Tworzenie użytkownika bazy danych

1. W konsoli Atlas otwórz Database & Network Access (Dostęp do bazy danych i sieci).
2. Kliknij Użytkownicy bazy danych.
3. Kliknij Dodaj nowego użytkownika bazy danych.
4. Wybierz Hasło jako metodę uwierzytelniania.
5. Wpisz nazwę użytkownika jako store-user, a hasło jako storeuser.
6. Kliknij Dodaj rolę wbudowaną i wybierz Odczyt i zapis w dowolnej bazie danych.
7. Kliknij Dodaj użytkownika.

Pobieranie ciągu znaków połączenia

1. Otwórz Baza danych > Klastry > Połącz.
2. W sekcji Połącz aplikację kliknij Sterowniki.
3. Skopiuj ciąg połączenia widoczny w sekcji Dodaj ciąg połączenia do kodu aplikacji. Ciąg znaków wygląda mniej więcej tak:

   mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
   

   Zastąp db_password hasłem do MongoDB. W tym ćwiczeniu jest to storeuser.

Zapisz ten ciąg połączenia. Będzie on potrzebny później w przypadku zmiennej środowiskowej MONGODB_CONNECTION_STRING.

Tworzenie bazy danych i kolekcji

1. W konsoli Atlas kliknij Database > Clusters > Browse Collections (Baza danych > Klastry > Przeglądaj kolekcje).
2. Kliknij Utwórz bazę danych i wpisz te informacje:
   • Nazwa bazy danych: ecommerce_db
   • Nazwa kolekcji: product_details_collection
3. Kliknij Utwórz bazę danych.
4. W Eksploratorze danych wybierz nazwę zbioru.
5. Kliknij ikonę Dodaj dane (+), a potem Wstaw dokument.
6. Skopiuj zawartość pliku JSON z pliku product_details_export.json i wklej ją w oknie edytora Wstaw dokument.
7. Kliknij Wstaw, aby wstawić tablicę dokumentów, i sprawdź, czy dodano 192 dokumenty.
8. W Eksploratorze danych kliknij Utwórz kolekcję (+) obok bazy danych ecommerce_db.
9. Wpisz user_interactions_collection jako nazwę kolekcji i kliknij Utwórz kolekcję.
10. W Eksploratorze danych wybierz kolekcję user_interactions_collection.
11. Kliknij ikonę Dodaj dane (+), a potem Wstaw dokument.
12. Skopiuj zawartość pliku JSON z pliku user_interactions_export.json i wklej ją w oknie edytora Wstaw dokument.
13. Kliknij Wstaw dokument.

6. Konfigurowanie BigQuery

BigQuery agreguje i analizuje historyczne zachowania użytkowników, aby generować inteligentne raporty i rekomendacje.

Tworzenie zbioru danych

1. W konsoli Google Cloud otwórz BigQuery.
2. Obok identyfikatora projektu w panelu Eksplorator kliknij menu z 3 kropkami i wybierz Utwórz zbiór danych.
3. W polu Identyfikator zbioru danych wpisz ecommerce_analytics.
4. Kliknij Utwórz zbiór danych.

Tworzenie tabeli Analytics

1. Otwórz nowe zapytanie w obszarze roboczym BigQuery.
2. Aby utworzyć tabelę podsumowującą, która łączy użytkowników z interakcjami z produktem, uruchom następującą instrukcję SQL:

CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

Przypisywanie ról do konta usługi Compute na potrzeby MCP Toolbox

Przypisujemy role do konta usługi Compute używanego w naszym zestawie narzędzi. Jest to konieczne, aby umożliwić narzędziom MCP dostęp do BigQuery, Secret Manager i innych usług w chmurze.

Aby znaleźć numer projektu, w konsoli Google Cloud kliknij Przegląd Cloud > Panel. Zapisz numer projektu widoczny na karcie Informacje o projekcie.

Aby przyznać role, wykonaj te czynności:

1. Otwórz Uprawnienia i administracja.
2. Kliknij Przyznaj dostęp.
3. W polu Nowe podmioty zabezpieczeń wpisz domyślne konto usługi Compute o nazwie [e-mail]. Zastąp YOUR_PROJECT_NUMBER numerem projektu Google Cloud.
4. Kliknij Wybierz rolę.
5. Znajdź i wybierz rolę Edytujący dane BigQuery.
6. Kliknij Dodaj kolejną rolę i wybierz rolę Użytkownik zadań BigQuery.
7. Kliknij Dodaj kolejną rolę i wybierz rolę Dostęp do obiektu tajnego w Secret Managerze.
8. Kliknij Dodaj kolejną rolę i wybierz rolę Edytujący.
9. Kliknij Zapisz.

7. Zrozumienie działania aplikacji od początku do końca

Aby dowiedzieć się, jak poszczególne komponenty ze sobą współpracują, utworzymy prostą aplikację e-commerce, która korzysta z wielu baz danych i usług. Aplikacja ma backend w Pythonie (Flask) i integruje wiele usług i baz danych Google Cloud.

Struktura katalogu

W następnej sekcji sklonujesz repozytorium BRK2-149-multidb-ecommerce i użyjesz go do uruchomienia aplikacji lokalnie. Po przetestowaniu aplikacji lokalnie wdrożymy zarówno MCP Toolbox, jak i aplikację w Cloud Run.

Przejrzyj pobrane pliki w tym katalogu. Dostępne są te katalogi najwyższego poziomu:

• UploadImages: przechowuje komponenty z obrazami, które są używane głównie w dokumentacji lub treściach wizualnych w katalogu produktów e-commerce.
• static: przechowuje statyczne zasoby internetowe aplikacji, takie jak pliki CSS i JavaScript, które służą do nadawania stylu interfejsowi użytkownika i dodawania do niego interaktywności ( źródło).
• templates: przechowuje szablony HTML (prawdopodobnie Jinja2 dla Flask), których aplikacja w języku Python używa do dynamicznego renderowania stron internetowych na potrzeby katalogu e-commerce ( źródło).
• toolbox-implementation: przechowuje szczegóły konfiguracji i wdrożenia zestawu narzędzi Model Context Protocol (MCP), ułatwiając interakcje z bazami danych w wielu bazach danych za pomocą predefiniowanych narzędzi.

Pliki w tym repozytorium współpracują ze sobą, aby tworzyć, konfigurować i wdrażać aplikację e-commerce z wieloma bazami danych. Pliki centralne, takie jak app.py, koordynują działanie backendu, integrując różne źródła danych zdefiniowane w plikach SQL i JSON, a pliki konfiguracyjne zapewniają bezproblemowe wdrażanie w środowiskach chmurowych:

• app.py: koordynuje backend Flask i integracje z wieloma bazami danych.
• agentengine.py: podstawowa logika inicjowania i konfigurowania agentów Vertex AI.
• .env: przechowuje tajne klucze do połączeń z bazą danych i pamięcią masową.
• tools.yaml: konfiguruje Zestaw narzędzi MCP do operacji na wielu bazach danych.
• Dockerfile: definiuje obraz kontenera i konfigurację środowiska.
• requirements.txt: zawiera listę bibliotek Pythona potrzebnych do działania aplikacji.
• tools.yaml: konfiguracje Zestawu narzędzi MCP.
• Procfile: określa polecenia wykonywania w środowisku produkcyjnym na potrzeby wdrożenia.
• alloydb_insert_queries.sql: zawiera zapytania SQL dotyczące danych relacyjnych.
• product_details_export.json i user_interactions_export.json: przykładowe dane JSON dla bazy danych NoSQL.
• README.md: zawiera wskazówki dotyczące konfiguracji, wdrażania i zrozumienia projektu.

Kompletny proces aplikacji

• Konfiguracja AlloyDB: udostępnij klaster o wysokiej wydajności i użyj podanych skryptów SQL, aby utworzyć tabelę products_core_table z kolumnami wektorowymi dla wektorów dystrybucyjnych obrazów.
• Konfiguracja MongoDB Atlas: wdróż klaster w Google Cloud, aby przechowywać płynne atrybuty produktów w product_details i rejestrować strumienie kliknięć w czasie rzeczywistym w user_interactions.
• BigQuery Analytics: utwórz zbiór danych, aby agregować dzienniki interakcji, co umożliwi tworzenie złożonych zapytań analitycznych, które identyfikują 5 najpopularniejszych elementów w milionach zdarzeń.
• Repozytorium Cloud Storage: utwórz publiczny zasobnik, w którym będą przechowywane obrazy produktów w wysokiej rozdzielczości. Upewnij się, że każdy komponent jest dostępny za pomocą podpisanego lub publicznego adresu URL dla interfejsu.
• Wdrożenie MCP Toolbox: wdrożenie zestawu narzędzi w Cloud Run, aby utworzyć centralny mostek RESTful, który tłumaczy intencje wyrażone w języku naturalnym na zapytania do wielu baz danych.
• Konfiguracja pliku tools.yaml: zdefiniuj „narzędzia”, takie jak get_product_core_data lub get_top_5_views, mapując konkretne operacje SQL i NoSQL na proste nazwy, które może odczytać agent.
• Logika backendu Flask: zaimplementuj trasy app.py, które współpracują z zestawem narzędzi MCP, koordynując pobieranie danych i pełniąc funkcję interfejsu API dla interfejsu użytkownika.
• Orkiestracja wielu agentów: skonfiguruj agentów ADK w kodzie, aby analizować intencje użytkowników i wybierać odpowiednie „narzędzie” do rozwiązywania złożonych zapytań dotyczących sprzedaży detalicznej pochodzących z wielu źródeł.
• Integracja frontendu: utwórz interfejs index.html z katalogiem produktów i funkcją rejestrowania interakcji, kartą Analytics, która umożliwia analizowanie skuteczności produktów, oraz specjalną „kartą agenta” korzystającą z czatu z wieloma agentami ADK, aby zapewnić płynne zakupy konwersacyjne.

Teraz wdróżmy orkiestrację i wdrożenia.

8. Konfigurowanie MCP Toolbox i wdrażanie w Cloud Run

MCP Toolbox abstrahuje od naszych wielu źródeł danych, dzięki czemu nasza aplikacja może pobierać i zapisywać dane w jednolity sposób.

Instalowanie MCP Toolbox lokalnie

1. W Cloud Shell przejdź do folderu toolbox-implementation:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
   

2. Pobierz plik binarny narzędzi MCP i ustaw go jako wykonywalny:

   export VERSION=0.29.0
   curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
   chmod +x toolbox
   

Konfigurowanie pliku tools.yaml

Musisz zdefiniować abstrakcje dla AlloyDB, MongoDB i BigQuery. Plik tools.yaml informuje zestaw narzędzi MCP, jak ze sobą współdziałać.

1. Utwórz i edytuj plik tools.yaml za pomocą wbudowanego edytora:

   cloudshell edit tools.yaml
   

   Pełny plik tools.yaml znajdziesz w repozytorium GitHub. Skopiuj jego zawartość do nowego pliku tools.yaml.
2. Zaktualizuj hosta, użytkownika, hasła, identyfikatory projektów i ciągi połączenia, aby pasowały do infrastruktury, którą udostępniono w poprzednich krokach:

   Baza danych	Pole	Przykładowa wartość
   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:[e-mail]

Przypisywanie ról do konta usługi Compute na potrzeby MCP Toolbox

Przypisujemy role do konta usługi Compute używanego w naszym zestawie narzędzi. Jest to konieczne, aby umożliwić zestawowi narzędzi MCP dostęp do AlloyDB.

1. Otwórz Uprawnienia i administracja.
2. Kliknij Przyznaj dostęp.
3. W polu Nowe podmioty zabezpieczeń wpisz domyślne konto usługi Compute o nazwie [e-mail]. Zastąp YOUR_PROJECT_NUMBER numerem projektu Google Cloud.

   Numer projektu: aby znaleźć numer projektu, w konsoli Google Cloud kliknij Przegląd Cloud > Panel. Zapisz numer projektu widoczny na karcie Informacje o projekcie.

4. Kliknij Wybierz rolę.
5. Znajdź i wybierz rolę Edytujący dane BigQuery.
6. Kliknij Dodaj kolejną rolę i wybierz rolę Klient AlloyDB.
7. Kliknij Dodaj kolejną rolę i wybierz rolę Użytkownik wykorzystania usług.
8. Kliknij Dodaj kolejną rolę i wybierz rolę Wyświetlający obiekty Cloud Storage.
9. Kliknij Zapisz.

Testowanie interfejsu narzędzia

1. W terminalu Cloud Shell uruchom lokalnie narzędzia, aby udostępnić interfejs:

   ./toolbox --ui
   

2. Otwórz podgląd w przeglądarce w Cloud Shell na porcie 5000 i przejdź na stronę narzędzi. W zależności od adresu URL sesji możesz ją wyświetlić np. pod adresem https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui.

Dostęp do interfejsu MCP w Cloud Shell: Cloud Shell udostępnia porty lokalne za pomocą podglądu w przeglądarce. Zamiast otwierać localhost:8080, musisz użyć adresu URL podglądu w przeglądarce i dodać do niego /ui, np. https://5000-cs-.../ui?authuser=0. Bez tego wyświetli się zwykły komunikat „Hello World” zamiast załadowanego panelu interfejsu.

Wyświetli się ten interfejs narzędzi MCP:

Wdrożenie w Cloud Run

Wdróż narzędzia MCP w Cloud Run, aby udostępnić je jako bezpieczną usługę zarządzaną, z której aplikacja może korzystać do wykonywania zapytań w bazach danych. Aby chronić poufne dane połączenia, będziemy przechowywać konfigurację w usłudze Secret Manager.

1. Otwórz nową sesję Cloud Shell.
2. Przejdź do folderu toolbox-implementation:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
   

3. Prześlij konfigurację tools.yaml do usługi Google Secret Manager:

   gcloud secrets create tools --data-file=tools.yaml
   

   Uwaga: aby dodać nową wersję do istniejącego klucza tajnego, użyj tego polecenia:

   gcloud secrets versions add tools --data-file=tools.yaml
   

4. Wdrażanie za pomocą publicznego obrazu kontenera MCP Toolbox:

   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)")[e-mail] \
       --set-secrets "/app/tools.yaml=tools:latest" \
       --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui" \
       --allow-unauthenticated
   

5. Po wdrożeniu zanotuj podany adres URL usługi Cloud Run. Powinien on wyglądać tak: https://toolbox-*********-uc.a.run.app/ui.

9. Konfigurowanie aplikacji e-commerce i wdrażanie jej w Cloud Run

Po uruchomieniu baz danych i wdrożeniu abstrakcji MCP Toolbox możemy uruchomić aplikację internetową Flask.

Aby udostępnić katalog produktów, aplikacja Flask przetwarza dane, wykonując te czynności:

1. Pobierz podstawowe dane: pobiera pełną listę produktów z AlloyDB (list_products_core).
2. Pobierz szczegółowe informacje: pobiera wszystkie szczegóły produktu z MongoDB (list_all_product_details).
3. Połącz listy: łączy obie listy.
4. Wzbogać o multimedia: dodaje adres URL obrazu z Cloud Storage do każdego produktu.

Generowanie ścieżki aplikacji silnika rozumowania

Aby zainicjować i zarejestrować agenta AI za pomocą silnika wnioskowania Vertex AI od Google Cloud, uruchom to polecenie:

1. W terminalu Cloud Shell otwórz folder BRK2-149-multidb-ecommerce.

   cd next-26-sessions/BRK2-149-multidb-ecommerce
   

2. Uruchom plik requirements.txt, aby zainstalować zależności.

   pip install -r requirements.txt
   

3. Aby wygenerować ścieżkę aplikacji silnika rozumowania, uruchom skrypt agentengine.py:

   python agentengine.py
   

Dane wyjściowe będą podobne do tych:

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

Konfigurowanie zmiennych środowiskowych

1. Utwórz plik .env i go edytuj:

   cloudshell edit .env
   

2. Zastąp wartości konkretnymi połączeniami z bazą danych i nowym adresem URL Cloud Run Toolbox:

   # 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
   

   Możesz zauważyć, że nie wszystkie obrazy wczytują się od razu. Niektóre linki mogą zniknąć lub wskazywać nieprawidłowe miejsce w zależności od tego, jak właściwości są mapowane na kody SKU produktów w sklonowanym zbiorze danych aplikacji. Sprawdź zasady dostępu publicznego do zasobnika GCS i upewnij się, że nazwy plików są prawidłowo mapowane.

Wdrażanie frontendu w Cloud Run

1. Aby ukończyć architekturę, wdróż aplikację internetową w Cloud Run:

   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"
   

   Zastąp te wartości:
   • YOUR_PROJECT_ID: identyfikator Twojego projektu Google Cloud;
   • YOUR_REASONING_ENGINE_APP_PATH: wynik uruchomienia polecenia python agentengine.py, np. projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856.
   • MCP_TOOLBOX_SERVER_URL: adres URL serwera zestawu narzędzi MCP, np. https://toolbox-*********-uc.a.run.app.
   • GCS_PRODUCT_BUCKET: nazwa zasobnika Cloud Storage, np. ecommerce-app-images.
   • MONGODB_CONNECTION_STRING: ciąg znaków połączenia z bazą danych MongoDB, np. mongodb+srv://store-user:[e-mail]
   • FALLBACK_IMAGE_URL: adres URL obrazu zastępczego, np. https://storage.googleapis.com/ecommerce-app-images/fallback.jpg

   Jeśli wdrożenie się nie powiedzie, uruchom polecenie gcloud auth login, aby autoryzować wdrożenie, a potem uruchom polecenie wdrażania ponownie.

Twoja aplikacja jest już aktywna. Otwórz adres URL usługi podany przez Cloud Run, aby wyświetlić katalog Multidb Ecommerce. Adres URL będzie podobny do tego: https://polyglot-*********-uc.a.run.app/.

10. Poznaj aplikację

1. Kliknij Katalog produktów, aby wyświetlić wszystkie produkty.
   
2. Kliknij ikonę produktu, aby wyświetlić szczegóły produktu. Zauważysz, że obrazy pochodzą z Cloud Storage, szczegóły produktu są pobierane z MongoDB, a asortyment produktów jest pobierany z AlloyDB.
3. Wchodź w interakcje z katalogiem produktów, aby generować próbne wyświetlenia i zapisy wysyłane do MongoDB.
4. Kliknij ETL i Analityka, aby wyświetlić statystyki produktu. Zauważysz, że dane analityczne produktu są pobierane z BigQuery.
   
5. Aby wejść w interakcję z agentem AI, kliknij kartę Agent AI. Zadawaj pytania w języku naturalnym, np.:
   

   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.
   

   

Widać, że wyszukiwanie zwraca dokładnie to, o co prosiliśmy – plecak bez elementów skórzanych, dostępny w magazynie i bez skarg na trwałość pasków w opiniach.

11. Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.

Uruchom te polecenia Cloud Shell:

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

Opcjonalnie, aby usunąć cały projekt w chmurze Google Cloud i wszystkie jego zasoby, uruchom to polecenie:

gcloud projects delete $PROJECT_ID

Na koniec otwórz MongoDB Atlas w Google Cloud i usuń utworzony Cluster0 klaster, aby uniknąć nieużywanych zasobów w ramach bezpłatnego poziomu.

12. Gratulacje

Gratulacje! Udało Ci się utworzyć architekturę Multidb w wielu chmurach.

Pokazaliśmy, jak zestaw narzędzi MCP stanowi architektoniczny spoiwo nowoczesnej, specjalistycznej aplikacji. Dopasowując odpowiednią bazę danych do odpowiedniego zadania, udało Ci się:

• Elastyczny zapis danych: MongoDB do logów zdarzeń.
• Spójność transakcyjna: AlloyDB zapewnia integralność podstawową.
• Analytics o wysokiej wydajności: BigQuery do analizy biznesowej.
• Ujednolicone programowanie: pojedynczy backend w Pythonie, który za pomocą zestawu narzędzi MCP upraszcza wszystkie złożone procesy.

Dokumentacja

Dowiedz się więcej o powiązanych usługach Google Cloud i zapoznaj się z tymi ćwiczeniami z programowania:

• AlloyDB AI: Wprowadzenie do wektorów dystrybucyjnych z pomocą AI w AlloyDB
• AlloyDB AI: multimodalne wektory dystrybucyjne w AlloyDB
• Zestaw narzędzi MCP: instalowanie i konfigurowanie zestawu narzędzi MCP dla baz danych w AlloyDB

Więcej informacji o usługach użytych w tym laboratorium znajdziesz w tych artykułach:

• Dokumentacja AlloyDB for PostgreSQL
• Dokumentacja MongoDB Atlas w Google Cloud
• Dokumentacja BigQuery
• Dokumentacja Cloud Storage
• Dokumentacja Cloud Run
• Dokumentacja Cloud Build
• Implementacja Zestawu narzędzi MCP