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

1. Wprowadzenie

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

W tym ćwiczeniu utworzysz wielojęzyczną aplikację, która harmonijnie łączy:

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

„Sekretny składnik”? Użyjesz MCP Toolbox for Databases, aby inteligentnie koordynować i ujednolicać źródła danych działające w Cloud Run jako most semantyczny, a następnie wdrożysz aplikację do obsługi czatu z wieloma agentami za pomocą pakietu Agent Development Kit (ADK). Nie tworzysz tylko paska wyszukiwania, ale inteligentny system handlu detalicznego, który rozumie kontekst, uwzględnia ograniczenia i łączy nieprzetworzone dane z intencjami użytkowników.

Niemożliwe zapytanie użytkownika

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

„Cześć, planuję wyjazd fotograficzny w wysokie góry. Pokaż mi kilka wodoodpornych plecaków w stylu „AeroGlow Pro”, ale bez elementów skórzanych. Daj mi też znać, czy są one dostępne w magazynie i czy inni fotografowie narzekali w opiniach na trwałość paska”.

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

• Podobieństwo wizualne (AlloyDB + wyszukiwanie wektorowe): „Podobny styl do AeroGlow Pro” wymaga porównania wektorów dystrybucyjnych obrazu.
• Ograniczenie negatywne (MongoDB): „Bez skóry” wymaga filtrowania za pomocą 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 (a nie nieaktualnego indeksu wyszukiwania).
• Synteza semantyczna (BigQuery + wiele agentów): analiza opinii pod kątem „trwałości paska” wymaga od agenta podsumowania nieuporządkowanych opinii z BigQuery na bieżąco.

Większość botów handlowych zobaczy tylko „plecak” i „skórzany” i pokaże 10 skórzanych plecaków. Jak temu zapobiegamy?

Nie tylko dopasowujemy słowa kluczowe. Używamy MCP Toolbox, aby umożliwić naszym agentom „wnioskowanie” na podstawie wszystkich tych źródeł – danych transakcyjnych w AlloyDB i elastycznych atrybutów w MongoDB jednocześnie. Zbudujmy go.

Jakie zadania wykonasz

• udostępnić klaster AlloyDB na potrzeby podstawowych danych o produktach,
• skonfigurować MongoDB Atlas w Google Cloud do przechowywania częściowo ustrukturyzowanych szczegółów produktu,
• utworzyć zasobnik Cloud Storage do wyświetlania zdjęć produktów,
• Wdróż MCP Toolbox for Databases w Cloud Run, aby zapewnić jednolity dostęp do danych.
• uruchamiać procesy ETL, aby przesyłać dane do BigQuery na potrzeby analizy;
• Rozmawiaj z agentem AI w języku naturalnym.

Wymagania wstępne

• przeglądarkę internetową, np. Chrome;
• projekt Google Cloud z włączonymi rozliczeniami,
• bezpłatne konto MongoDB Atlas w Google Cloud,

2. Zanim zaczniesz

Utwórz projekt Google Cloud

1. W Google Cloud Console na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
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 na górze konsoli Google Cloud.
2. Po połączeniu z Cloud Shell sprawdź uwierzytelnianie:

   gcloud auth list
   

3. Potwierdź, że 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
   

Ustawianie zmiennych

W Cloud Shell ustaw zmienne środowiskowe dla identyfikatora i numeru projektu:

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

Jeśli sesja Cloud Shell zostanie rozłączona, uruchom ponownie te polecenia export (oraz inne, które dodasz później w tym ćwiczeniu).

Włącz wymagane interfejsy API

Uruchom to polecenie, aby włączyć wszystkie wymagane interfejsy API:

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 służy jako 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ę, na przykład -ecommerce-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 > Wyświetlający obiekty Cloud Storage.
9. Kliknij Zapisz, a następnie Zezwalaj na dostęp publiczny, aby potwierdzić, że udostępniasz zasób publicznie.
10. W Cloud Shell zapisz nazwę zasobnika w zmiennej:

    export BUCKET=<your-bucket-name>
    

    Zastąp nazwą utworzonego zasobnika.

Przesyłanie obrazów zastępczych

W projekcie używane są obrazy zastępcze, aby zapewnić jak najlepsze wrażenia wizualne.

1. W Cloud Shell sklonuj repozytorium:

   git clone https://github.com/AbiramiSukumaran/polyglot-persist-ecommerce.git
   

2. Przejdź do folderu UploadImages:

   cd polyglot-persist-ecommerce/UploadImages
   

3. Prześlij przykładowe obrazy do zasobnika:

   gcloud storage cp *.jpg gs://$BUCKET/
   

4. Konfigurowanie AlloyDB

AlloyDB służy jako jedno źródło wiarygodnych danych w przypadku uporządkowanych, transakcyjnych i krytycznych danych, takich jak identyfikatory produktów, nazwy, kody SKU, ceny i asortyment. AlloyDB zapewnia też agentowi AI 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 ćwiczeniu z programowania.

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 dla użytkownika postgres. W celach szkoleniowych możesz użyć nazwy alloydb.
5. W polu Wersja bazy danych pozostaw wartość domyślną.
6. W polu Region wybierz us-central1 (lub preferowany region).

Skonfiguruj instancję główną

1. W polu Identyfikator instancji wpisz ecommerce-cluster-primary.
2. W sekcji Dostępność strefowa wybierz 1 strefa.
3. W polu Seria maszyn wybierz N2, a w polu Typ maszyny wybierz 4 vCPU, 32 GB.
4. W sekcji Prywatne połączenie po IP wybierz Prywatny dostęp do usług (PSA) i sieć default.Jeśli sieć domyślna nie jest jeszcze ustawiona, 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 zestaw narzędzi MCP mógł się prawidłowo połączyć w tym ćwiczeniu. Konsola automatycznie włącza flagę password.enforce_complexity, której AlloyDB wymaga w przypadku publicznego adresu IP.
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.

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 wybierz postgres.
3. Wybierz Wbudowane uwierzytelnianie, aby zalogować się w bazie danych.
4. W polu Nazwa użytkownika wpisz postgres.
5. W polu Password (Hasło) wpisz ustawione wcześniej hasło.
6. Kliknij Uwierzytelnij.
7. W widoku edytora otwórz nową kartę zapytania bez tytułu.
8. Skopiuj poniższy 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 głównego projektu:

   cd ~/polyglot-persist-ecommerce
   

10. Otwórz plik alloydb_insert_queries.sql w Cloud Shell i skopiuj zapytania wstawiania.

    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 wektorów dystrybucyjnych obrazów, aby agent AI mógł pobierać podobne produkty

Integracja agenta AI wykorzystuje wektory dystrybucyjne 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 o 1408 wymiarach, które są przechowywane w kolumnie img_embeddings.

Zanim wygenerujemy wektory dystrybucyjne, musimy przyznać kontu usługi AlloyDB wymagane role, aby umożliwić mu dostęp do Cloud Storage.

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

Przyznaj kontu usługi AlloyDB role, których potrzebuje do odczytywania obrazów z Cloud Storage i generowania wektorów dystrybucyjnych Vertex AI:

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

Włączanie rozszerzeń

Do utworzenia tej aplikacji użyjemy rozszerzeń pgvector i google_ml_integration. Rozszerzenie pgvector umożliwia przechowywanie i wyszukiwanie wektorów dystrybucyjnych. Rozszerzenie google_ml_integration udostępnia funkcje, których możesz używać do uzyskiwania dostępu do punktów końcowych prognoz Vertex AI w celu generowania prognoz w SQL. Włącz te rozszerzenia, uruchamiając te instrukcje 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 tytułu.
4. Skopiuj poniższy kod DDL i kliknij Uruchom:

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

Inicjowanie bazy danych z umieszczonymi elementami

1. Dodaj kolumnę img_embeddings do tabeli products_core_table.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Wyświetl zapytanie o wektory dystrybucyjne z wypełnioną nazwą zasobnika:

   cd ~/polyglot-persist-ecommerce
   sed "s/<STORAGE_BUCKET_NAME>/$BUCKET/g" alloydb_generate_embeddings.sql
   

3. Skopiuj dane wyjściowe, wklej je na nowej karcie zapytania w AlloyDB Studio i kliknij Uruchom. Zajmie to około minuty. Jeśli upłynie limit czasu, uruchom go ponownie. Produkty, które mają już wektory dystrybucyjne, zostaną pominięte.

   Skrypt przetwarza tylko produkty, które mają obraz w kolumnie UploadImages/.

5. Konfigurowanie MongoDB Atlas w Google Cloud

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

Tworzenie klastra MongoDB

1. Zaloguj się w MongoDB Atlas (w razie potrzeby utwórz bezpłatne konto).
2. W sekcji Deploy your cluster (Wdróż klaster) wybierz Free (Bezpłatny). (Atlas wstępnie wybiera płatny poziom; upewnij się, że wybrany jest poziom bezpłatny).
3. W polu Dostawca wybierz Google Cloud, a w polu Region wybierz Iowa (us-central1).
4. W polu Nazwa wpisz ecommerce-cluster i odznacz Wstępnie załaduj przykładowy zbiór danych.
5. Kliknij Utwórz wdrożenie.

Zezwalanie na dostęp i tworzenie użytkownika bazy danych

Atlas otworzy okno Connect to ecommerce-cluster (Połącz z klastrem e-commerce).

1. Kliknij Dodaj inny adres IP, wpisz 0.0.0.0/0 i dodaj go.

   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 środowisku produkcyjnym należy ograniczyć dostęp do określonych zakresów adresów IP.

2. Wpisz store-user w polu Nazwa użytkownika i storeuser w polu Hasło, a następnie kliknij Utwórz użytkownika bazy danych.
3. Kliknij Wybierz metodę połączenia, a następnie Sterowniki i biblioteki klienta.
4. W sekcji Użyj tego ciągu znaków połączenia w aplikacji skopiuj ciąg znaków połączenia. Wygląda na to, że mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. Zastąp ciągiem storeuser i zapisz ciąg. Użyjesz go w tools.yaml.

Jeśli okno zostało zamknięte, otwórz Baza danych > Klastry i kliknij Połącz w ecommerce-cluster.

Tworzenie bazy danych i kolekcji

1. W panelu nawigacyjnym po lewej stronie kliknij Eksplorator danych, a następnie Utwórz bazę danych i podaj te informacje:
   • Nazwa bazy danych: ecommerce_db
   • Nazwa kolekcji: product_details_collection
2. Kliknij Utwórz bazę danych.
3. W Eksploratorze danych wybierz nazwę kolekcji.
4. Kliknij ikonę Dodaj dane (+), a następnie Wstaw dokument.
5. Skopiuj zawartość JSON z pliku product_details_export.json i wklej ją w oknie edytora Insert Document (Wstaw dokument).
6. Atlas wyświetli baner z propozycją przekonwertowania tekstu na składnię powłoki. Kliknij KONWERTUJ, a następnie Wstaw. Sprawdź, czy dodano 192 dokumenty.
7. W Eksploratorze danych kliknij Utwórz kolekcję (+) obok bazy danych ecommerce_db.
8. Wpisz user_interactions_collection jako nazwę kolekcji i kliknij Create Collection (Utwórz kolekcję).
9. W Eksploratorze danych wybierz kolekcję user_interactions_collection.
10. Kliknij ikonę Dodaj dane (+), a następnie Wstaw dokument.
11. Skopiuj zawartość JSON z pliku user_interactions_export.json i wklej ją w oknie dialogowym edytora Insert Document (Wstaw dokument).
12. Atlas wyświetla baner z propozycją przekonwertowania tekstu na składnię powłoki. Kliknij KONWERTUJ, a następnie Wstaw. Sprawdź, czy dodano 211 dokumentów.

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. W panelu Eksplorator obok identyfikatora projektu kliknij menu z 3 kropkami i wybierz Utwórz zbiór danych.
3. W polu Identyfikator zbioru danych wpisz ecommerce_analytics.
4. W polu Lokalizacja danych wybierz US (multiple regions) (konfiguracja tools.yaml oczekuje lokalizacji US).
5. Kliknij Utwórz zbiór danych.

Tworzenie tabeli Analytics

1. Otwórz nowe zapytanie w obszarze roboczym BigQuery.
2. Uruchom tę instrukcję SQL, aby utworzyć tabelę podsumowania łączącą użytkowników z interakcjami z produktami:

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

Przypisz role do konta usługi Compute

Przyznaj domyślnemu kontu usługi Compute role, których potrzebują MCP Toolbox i aplikacja:

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}[e-mail]" \
    --role="$role" \
    --condition=None
done

Możesz też w konsoli kliknąć Administracja > Uprawnienia, wybrać Przyznaj dostęp, wpisać konto usługi i dodać te same role.

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

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

Struktura katalogów

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

Przejrzyj pobrane pliki w tym katalogu. Znajdują się tam te katalogi wysokiego poziomu:

• UploadImages: przechowuje komponenty z obrazem, które są używane głównie do dokumentacji lub treści wizualnych w katalogu produktów e-commerce.
• static: przechowuje statyczne zasoby internetowe aplikacji, takie jak pliki CSS i JavaScript, które służą do stylizowania interfejsu użytkownika i dodawania do niego interaktywności ( źródło).
• templates: przechowuje szablony HTML (prawdopodobnie Jinja2 dla Flask) używane przez aplikację w Pythonie do dynamicznego renderowania stron internetowych katalogu e-commerce ( źródło).

Pliki w tym repozytorium współpracują ze sobą, aby utworzyć, skonfigurować i wdrożyć aplikację e-commerce z wieloma bazami danych. Pliki centralne, takie jak app.py, zarządzają backendem, integrując różne źródła danych zdefiniowane w plikach SQL i JSON, a pliki konfiguracji 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 obiekty tajne dotyczące połączeń z bazą danych i pamięcią masową.
• tools.yaml: konfiguruje MCP Toolbox do operacji na bazach danych multidb.
• Dockerfile: definiuje obraz kontenera i konfigurację środowiska.
• requirements.txt: zawiera listę bibliotek Pythona potrzebnych do działania aplikacji.
• tools.yaml: konfiguracje MCP Toolbox.
• 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: zawierają przykładowe dane JSON dla bazy danych NoSQL.
• README.md: zawiera wskazówki dotyczące konfiguracji, wdrażania i zrozumienia projektu.

Kompleksowy przepływ aplikacji

• Konfiguracja AlloyDB: udostępnij klaster o wysokiej wydajności i użyj dostarczonych 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ć zmienne atrybuty produktów w tabeli product_details i rejestrować w czasie rzeczywistym ciągi kliknięć w tabeli user_interactions.
• BigQuery Analytics: utwórz zbiór danych, aby agregować logi interakcji, co umożliwi wykonywanie złożonych zapytań analitycznych, które identyfikują „5 najpopularniejszych” elementów trendów wśród milionów zdarzeń.
• Repozytorium Cloud Storage: utwórz publiczny zasobnik, w którym będą przechowywane zdjęcia produktów w wysokiej rozdzielczości, i upewnij się, że każdy zasób jest dostępny za pomocą podpisanego lub publicznego adresu URL dla frontendu.
• Wdrażanie zestawu narzędzi MCP: wdróż zestaw narzędzi w Cloud Run, aby utworzyć centralny mostek RESTful, który tłumaczy intencje w języku naturalnym na zapytania do wielu baz danych.
• Konfiguracja 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, czytelne dla agenta nazwy.
• Logika backendu Flask: implementacja tras app.py, które łączą się z MCP Toolbox, obsługują koordynację pobierania danych i służą jako interfejs API dla interfejsu użytkownika.
• Orkiestracja wielu agentów: skonfiguruj agentów ADK w kodzie, aby analizowali intencje użytkownika i wybierali odpowiednie „narzędzie” do rozwiązywania złożonych zapytań dotyczących sprzedaży detalicznej z wielu źródeł.
• Integracja frontendu: utwórz interfejs index.html zawierający katalog produktów z funkcją rejestrowania interakcji, kartę Analytics do analizowania skuteczności produktów oraz specjalną kartę „Agent”, która korzysta z czatu wieloagentowego ADK, aby zapewnić płynne zakupy w formie rozmowy.

Teraz wdrożymy orkiestrację i wdrożenia.

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

MCP Toolbox abstrakcyjnie przedstawia nasze liczne źródła danych, umożliwiając aplikacji pobieranie i zapisywanie danych w jednolity sposób.

Instalowanie MCP Toolbox lokalnie

Pobierz plik binarny MCP Toolbox do katalogu głównego i ustaw go jako wykonywalny:

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

Konfigurowanie pliku tools.yaml

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

1. Repozytorium zawiera już tools.yaml. Otwórz go:

   cd ~/polyglot-persist-ecommerce
   cloudshell edit tools.yaml
   

2. Zastąp obiekty zastępcze ***** swoimi wartościami:

   Baza danych	Pole	Przykładowa wartość
   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 (dodaj ten wiersz pod alloydb-source, jeśli go tam nie ma)
   MongoDB	uri	ciąg znaków połączenia zapisany wcześniej,

3. Skieruj podglądy obrazów na zasobnik:

   sed -i "s/ecommerce-app-images/$BUCKET/g" tools.yaml
   

Testowanie interfejsu narzędzia

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

   ~/toolbox --config tools.yaml --ui --enable-api
   

2. W Cloud Shell kliknij Podgląd w przeglądarce > Zmień port, wpisz 5000 i dodaj /ui na końcu adresu URL, który się otworzy.

Pojawi się ten interfejs zestawu narzędzi MCP:

Gdy skończysz, naciśnij Ctrl+C, aby zatrzymać lokalny zestaw narzędzi.

Wdrożenie w Cloud Run

Wdróż MCP Toolbox w Cloud Run, aby udostępnić go jako bezpieczną usługę zarządzaną, której nasza aplikacja może używać do wysyłania zapytań do baz danych. Konfigurację będziemy przechowywać w usłudze Secret Manager, aby chronić poufne szczegóły połączenia.

1. Prześlij konfigurację tools.yaml do Google Secret Managera:

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

   Jeśli później zmienisz tools.yaml, prześlij nową wersję z:

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

2. Wdróż za pomocą publicznego obrazu kontenera MCP Toolbox:

   gcloud run deploy toolbox \
       --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
       --region us-central1 \
       --service-account ${PROJECT_NUMBER}[e-mail] \
       --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 włącza interfejs API typu REST, którego używa aplikacja internetowa.
3. Zapisz adres URL skrzynki narzędziowej:

   export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
   echo $TOOLBOX_URL
   

   Aby zobaczyć narzędzia, możesz otworzyć $TOOLBOX_URL/ui w przeglądarce.

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

Gdy bazy danych są uruchomione, a abstrakcja MCP Toolbox wdrożona, możemy uruchomić aplikację internetową Flask.

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

1. Pobieranie danych podstawowych: pobiera pełną listę produktów z AlloyDB (list_products_core).
2. Fetch extended details (Pobierz rozszerzone szczegóły): pobiera wszystkie szczegóły produktu z MongoDB (list_all_product_details).
3. Połącz listy: łączy 2 listy.
4. Wzbogać o multimedia: dodaje adres URL obrazu w Cloud Storage do każdego elementu.

Tworzenie silnika agenta

1. Zainstaluj zależności:

   cd ~/polyglot-persist-ecommerce
   pip install -r requirements.txt
   

   Uwaga: ten krok może potrwać kilka minut, podczas których pakiety zostaną rozpoznane i zainstalowane.
2. Zainicjuj i zarejestruj agenta AI za pomocą silnika rozumowania Vertex AI:

   export REASONING_ENGINE_LOCATION=us-central1
   export APP_NAME=$(python agentengine.py)
   echo $APP_NAME
   

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

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

Aplikacja odczytuje ustawienia ze zmiennych środowiskowych, które przekazujesz w poleceniu wdrażania poniżej, więc nie musisz edytować pliku .env.

Wdrażanie frontendu w Cloud Run

1. Wdróż aplikację internetową w Cloud Run, aby dokończyć architekturę:

   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"
   

   Aplikacja używa gemini-3.5-flash, który jest obsługiwany z lokalizacji global. Agent Engine pozostaje w us-central1.

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

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

10. Poznawanie aplikacji

1. Kliknij Katalog produktów, aby wyświetlić wszystkie produkty.
   
2. Kliknij ikonę usługi, aby wyświetlić jej szczegóły. Zauważysz, że obrazy pochodzą z Cloud Storage, szczegóły produktu są pobierane z MongoDB, a asortyment produktów jest pobierany z AlloyDB.
3. Wejdź w interakcję z katalogiem produktów, aby wygenerować próbne wyświetlenia i zapisy wysyłane do MongoDB.
4. Kliknij ETL i analityka, aby wyświetlić statystyki usługi. Zauważysz, że statystyki dotyczące usług są pobierane z BigQuery.
   
5. Kliknij kartę Agent AI, aby wejść w interakcję z agentem AI. Zadawaj pytania w języku naturalnym, takie jak:
   

   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.
   

   

Jak widać, 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ąć bieżących opłat na koncie Google Cloud, usuń zasoby utworzone podczas tego ćwiczenia.

Uruchom te polecenia Cloud Shell:

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

Opcjonalnie usuń instancję Agent Engine:

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

Możesz też w konsoli Google Cloud kliknąć Vertex AI > Agent Engine i usunąć instancję.

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 klaster ecommerce-cluster, aby upewnić się, że nie korzystasz już z poziomu bezpłatnego.

12. Gratulacje

Gratulacje! Udało Ci się utworzyć międzychmurową architekturę Multidb.

Pokazaliśmy, jak zestaw narzędzi MCP służy jako spoiwo architektoniczne nowoczesnej, wyspecjalizowanej aplikacji. Dzięki dopasowaniu odpowiedniej bazy danych do odpowiedniego zadania udało Ci się:

• Elastyczne zapisywanie danych: MongoDB do dzienników zdarzeń.
• Spójność transakcyjna: AlloyDB zapewnia integralność podstawowych danych.
• Wysokowydajna analityka: BigQuery na potrzeby analizy biznesowej.
• Ujednolicony proces programowania: pojedynczy backend w Pythonie, który dzięki zestawowi narzędzi MCP ukrywa całą złożoność.

Dokumentacja referencyjna

Więcej informacji o powiązanych usługach Google Cloud znajdziesz w tych ćwiczeniach:

• 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żywanych w tym ćwiczeniu znajdziesz tutaj:

• Dokumentacja AlloyDB for PostgreSQL
• Dokumentacja MongoDB Atlas w Google Cloud
• Dokumentacja BigQuery
• Dokumentacja Cloud Storage
• Dokumentacja Cloud Run
• Dokumentacja Cloud Build
• Implementacja MCP Toolbox