Intelligenten E-Commerce-Katalog mit Multi-Database Persistence erstellen

1. Einführung

Im modernen Einzelhandel sind Ihre Daten eine vielfältige, weitläufige Umgebung. Sie haben solide Transaktionsdaten (Preise und Inventar), „unordentliche“ polymorphe Kataloge (Elektronikspezifikationen im Vergleich zu Bekleidungsgrößen) und Petabyte an Verhaltensprotokollen. Wenn Sie diese in einen einzigen Monolithen zwängen, entstehen nicht nur technische Schulden, sondern auch eine schlechte Nutzererfahrung.

In diesem Codelab erstellen Sie ein polyglottes Kraftpaket, das Folgendes harmonisiert:

• AlloyDB: Ihr transaktionales Rückgrat für schnelle Konsistenz und Bildeinbettungen.
• MongoDB Atlas in Google Cloud: Ihre flexible, schemaunabhängige Katalogebene.
• Cloud Storage: Ihr analytisches Gehirn für Echtzeit-Trendprognosen.
• BigQuery: Ihr hochauflösendes digitales Warehouse.

Das Geheimnis? Sie verwenden die MCP Toolbox for Databases, um die in Cloud Run ausgeführten Datenquellen als semantische Brücke intelligent zu orchestrieren und zu vereinheitlichen. Anschließend stellen Sie mit dem Agent Development Kit (ADK) eine Multi-Agenten-Chat-App bereit. Sie erstellen nicht nur eine Suchleiste, sondern ein intelligentes Einzelhandelssystem, das den Kontext versteht, Einschränkungen berücksichtigt und die Lücke zwischen Rohdaten und menschlicher Absicht schließt.

Die unmögliche Nutzeranfrage

Standard-E-Commerce-Agenten scheitern bei mehrdimensionalen Überlegungen (Kombination von negativen Einschränkungen, visueller Ähnlichkeit und Echtzeitinventar). Ich möchte beispielsweise normalerweise so mit einer Einzelhandelswebsite sprechen:

„Hey, ich plane eine Fotoreise in die Berge. Zeig mir wetterfeste Rucksäcke, die dem „AeroGlow Pro“ ähneln, aber keine Lederkomponenten haben. Lass mich auch wissen, ob sie tatsächlich auf Lager sind und ob sich andere Fotografen in den Rezensionen über die Haltbarkeit des Gurts beschwert haben.“

Warum diese Anfrage der „Agent Killer“ ist:

• Visuelle Ähnlichkeit (AlloyDB + Vektorsuche): „Ähnlich im Stil wie der AeroGlow Pro“ erfordert einen Vergleich der Bildeinbettungen.
• Negative Einschränkung (MongoDB): „Ohne Leder“ erfordert das Filtern nach flexiblen, verschachtelten Attributen, die normalerweise nicht in einem Standard-SQL-Schema enthalten sind.
• Echtzeit-Inventar (AlloyDB): „Tatsächlich auf Lager“ erfordert eine Live-Transaktionsprüfung (keinen veralteten Suchindex).
• Semantische Synthese (BigQuery + Multi-Agent): Um Rezensionen zur „Haltbarkeit des Armbands“ zu analysieren, muss der Agent unstrukturiertes Feedback aus BigQuery spontan zusammenfassen.

Die meisten Einzelhandels-Bots würden nur „Rucksack“ und „Leder“ erkennen und 10 Lederrucksäcke anzeigen. Wie verhindern wir das?

Denn wir gleichen nicht nur Keywords ab. Wir verwenden die MCP Toolbox, damit unsere Agenten gleichzeitig die Transaktionsdaten in AlloyDB und die flexiblen Attribute in MongoDB analysieren können. Lass uns das bauen!

Aufgaben

• AlloyDB-Cluster für wichtige Produktdaten bereitstellen
• MongoDB Atlas in Google Cloud konfigurieren, um halbstrukturierte Produktdetails zu speichern
• Cloud Storage-Bucket zum Bereitstellen von Produktbildern erstellen
• MCP Toolbox for Databases in Cloud Run für einheitlichen Datenzugriff bereitstellen
• ETL-Prozesse ausführen, um Daten zur Analyse in BigQuery zu übertragen
• Mit einem KI-Agenten in natürlicher Sprache kommunizieren

Vorbereitung

• Ein Webbrowser wie Chrome
• Ein Google Cloud-Projekt mit aktivierter Abrechnung
• Ein kostenloses MongoDB Atlas in Google Cloud-Konto

2. Hinweis

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und die erforderlichen Tools enthält.

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
2. Sobald die Verbindung mit der Cloud Shell hergestellt ist, prüfen Sie Ihre Authentifizierung:

   gcloud auth list
   

3. Prüfen Sie, ob Ihr Projekt konfiguriert ist:

   gcloud config get project
   

4. Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:

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

Variablen festlegen

Legen Sie in Cloud Shell Umgebungsvariablen für Ihre Projekt-ID und Projektnummer fest:

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

Wenn die Verbindung zu Ihrer Cloud Shell-Sitzung getrennt wird, führen Sie diese export-Befehle noch einmal aus (und die anderen, die Sie später in diesem Codelab hinzufügen).

Erforderliche APIs aktivieren

Führen Sie den folgenden Befehl aus, um alle erforderlichen APIs zu aktivieren:

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

3. Cloud Storage einrichten

Cloud Storage dient als riesiger Speicher für unstrukturierte Medien-Assets wie Produktbilder.

1. Rufen Sie in der Google Cloud Console Cloud Storage auf und klicken Sie auf Bucket erstellen.
2. Geben Sie Ihrem Bucket einen global eindeutigen Namen, z. B. -ecommerce-images.
3. Klicken Sie auf Erstellen.
4. Damit die Demoanwendung ohne Authentifizierung auf die Bilder zugreifen kann, deaktivieren Sie die Option Verhinderung des öffentlichen Zugriffs für diesen Bucket erzwingen und klicken Sie auf Bestätigen.
5. Wechseln Sie zum Tab Berechtigungen.
6. Klicken Sie unter Berechtigungen auf Zugriff gewähren.
7. Geben Sie unter Neue Hauptkonten allUsers ein.
8. Wählen Sie unter Rolle auswählen die Option Cloud Storage > Storage Object Viewer aus.
9. Klicken Sie auf Speichern und dann auf Öffentlichen Zugriff erlauben, um zu bestätigen, dass Sie die Ressource öffentlich machen möchten.
10. Speichern Sie den Bucket-Namen in Cloud Shell in einer Variablen:

    export BUCKET=<your-bucket-name>
    

    Ersetzen Sie durch den Namen des Buckets, den Sie erstellt haben.

Platzhalterbilder hochladen

Das Projekt verwendet Platzhalterbilder, um die visuelle Darstellung zu optimieren.

1. Klonen Sie das Repository in Cloud Shell:

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

2. Rufen Sie den UploadImages-Ordner auf:

   cd polyglot-persist-ecommerce/UploadImages
   

3. Laden Sie die Beispielbilder in den Bucket hoch:

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

4. AlloyDB einrichten

AlloyDB dient als zentrale Informationsquelle für strukturierte, transaktionale und kritische Daten wie Produkt-IDs, Namen, SKUs, Preise und Inventar. AlloyDB bietet dem KI-Agenten auch Funktionen für die Ähnlichkeitssuche für Empfehlungen und Abfragen in natürlicher Sprache.

Wenn Sie schnell einen Cluster, eine Instanz und ein Netzwerk für Ihre Entwicklungsumgebung über eine Weboberfläche einrichten möchten, folgen Sie den Schritten in diesem Codelab.

AlloyDB-Cluster bereitstellen

1. Rufen Sie in der Google Cloud Console AlloyDB for PostgreSQL auf.
2. Klicken Sie auf Cluster erstellen.
3. Geben Sie als Cluster-ID ecommerce-cluster ein.
4. Legen Sie ein starkes Passwort für den Nutzer postgres fest. Zu Lernzwecken können Sie alloydb verwenden.
5. Behalten Sie für Datenbankversion die Standardeinstellung bei.
6. Wählen Sie unter Region die Option us-central1 (oder Ihre bevorzugte Region) aus.

Primäre Instanz konfigurieren

1. Geben Sie als Instanz-ID ecommerce-cluster-primary ein.
2. Wählen Sie unter Zonale Verfügbarkeit die Option Einzelne Zone aus.
3. Wählen Sie für Maschinenreihe die Option N2 und für Maschinentyp die Option 4 vCPU, 32 GB aus.
4. Wählen Sie unter Private IP-Verbindung die Option Zugriff auf private Dienste (PSA) und dann das Netzwerk default aus.Wenn das Standardnetzwerk noch nicht festgelegt ist, klicken Sie auf Netzwerkeinrichtung bestätigen, um eines zu erstellen.
5. Wählen Sie unter Öffentliche IP-Verbindung das Kästchen Öffentliche IP-Adresse aktivieren aus, damit die MCP-Toolbox in diesem Codelab eine ordnungsgemäße Verbindung herstellen kann. In der Console wird automatisch das Flag password.enforce_complexity aktiviert, das AlloyDB für öffentliche IP-Adressen benötigt.
6. Geben Sie unter Autorisierte externe Netzwerke den Wert 0.0.0.0/0 ein. Klicken Sie das Kästchen Ich erkenne die Risiken an an und klicken Sie auf Speichern.
7. Klicken Sie auf Cluster erstellen.

Es kann bis zu 10 Minuten dauern, bis der Cluster und die Instanz erstellt sind.

Datenbank initialisieren

1. Klicken Sie im linken Navigationsmenü auf AlloyDB Studio.
2. Wählen Sie im Drop-down-Menü Datenbank die Option postgres aus.
3. Wählen Sie Integrierte Authentifizierung aus, um sich in der Datenbank anzumelden.
4. Verwenden Sie als Nutzername den Nutzer postgres.
5. Geben Sie unter Password (Passwort) das zuvor festgelegte Passwort ein.
6. Klicken Sie auf Authentifizieren.
7. Öffnen Sie in der Editoransicht einen neuen Tab für eine unbenannte Abfrage.
8. Kopieren Sie die folgende DDL und klicken Sie auf Ausführen:

   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. Wechseln Sie in Cloud Shell zum Stammordner des Projekts:

   cd ~/polyglot-persist-ecommerce
   

10. Öffnen Sie die Datei alloydb_insert_queries.sql in Cloud Shell und kopieren Sie die Einfügeabfragen.

    cat alloydb_insert_queries.sql
    

11. Fügen Sie in einem neuen unbenannten Abfrage-Tab nur die INSERT-Anweisungen ein und klicken Sie auf Ausführen.
12. Kopieren Sie die folgende DDL in einen neuen Abfrage-Tab ohne Titel und klicken Sie auf Ausführen, um einen Index für die Tabelle products_core_table zu erstellen:

    CREATE INDEX idx_products_core_sku ON products_core_table(sku);
    

Bildeinbettungen für KI-Agenten erstellen, um ähnliche Produkte abzurufen

Bei der Integration des KI-Agenten werden Bildeinbettungen verwendet, um ähnliche Produkte abzurufen. Die Einbettungen werden mit dem Modell multimodalembedding@001 generiert und in der AlloyDB-Datenbank gespeichert. Die Einbettungen sind 1408-dimensionale Vektoren und werden in der Spalte img_embeddings gespeichert.

Bevor wir Einbettungen generieren können, müssen wir dem AlloyDB-Dienstkonto die erforderlichen Rollen für den Zugriff auf Cloud Storage zuweisen.

AlloyDB-Dienstkonto Rollen für den Zugriff auf Cloud Storage zuweisen

Weisen Sie dem AlloyDB-Dienstkonto die Rollen zu, die es zum Lesen von Bildern aus Cloud Storage und zum Generieren von Vertex AI-Einbettungen benötigt:

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

Erweiterungen aktivieren

Für die Erstellung dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der Erweiterung pgvector können Sie Vektoreinbettungen speichern und durchsuchen. Die Erweiterung google_ml_integration bietet Funktionen, mit denen Sie auf Vertex AI-Vorhersageendpunkte zugreifen können, um Vorhersagen in SQL abzurufen. Aktivieren Sie diese Erweiterungen, indem Sie die folgenden DDLs ausführen:

1. Rufen Sie in der Google Cloud Console AlloyDB for PostgreSQL auf.
2. Klicken Sie im linken Navigationsmenü auf AlloyDB Studio.
3. Öffnen Sie in der Editoransicht einen neuen Tab für eine unbenannte Abfrage.
4. Kopieren Sie die folgende DDL und klicken Sie auf Ausführen:

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

Datenbank mit Einbettungen initialisieren

1. Fügen Sie die Spalte „img_embeddings“ in die products_core_table ein.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Geben Sie die Einbettungsabfrage mit Ihrem Bucket-Namen aus:

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

3. Kopieren Sie die Ausgabe, fügen Sie sie in einen neuen Abfragetab in AlloyDB Studio ein und klicken Sie auf Ausführen. Das dauert etwa eine Minute. Wenn das Zeitlimit überschritten wird, führen Sie den Befehl noch einmal aus. Produkte, die bereits Einbettungen haben, werden übersprungen.

   Das Script verarbeitet nur Produkte, die ein Bild in UploadImages/ haben.

5. MongoDB Atlas in Google Cloud einrichten

MongoDB speichert umfangreiche, semistrukturierte Produktdetails und flexible Verhaltensdaten von Nutzern (z. B. Klicks und Aufrufe).

MongoDB-Cluster erstellen

1. Melden Sie sich in MongoDB Atlas an. Erstellen Sie bei Bedarf ein kostenloses Konto.
2. Wählen Sie unter Deploy your cluster (Cluster bereitstellen) die Option Free (Kostenlos) aus. (Atlas wählt standardmäßig eine kostenpflichtige Stufe aus. Achten Sie darauf, dass „Free“ ausgewählt ist.)
3. Wählen Sie als Anbieter die Option Google Cloud und als Region die Option Iowa (us-central1) aus.
4. Geben Sie unter Name ecommerce-cluster ein und entfernen Sie das Häkchen bei Beispiel-Dataset vorab laden.
5. Klicken Sie auf Deployment erstellen.

Zugriff zulassen und Datenbanknutzer erstellen

Atlas öffnet das Dialogfeld Mit ecommerce-cluster verbinden.

1. Klicken Sie auf Andere IP-Adresse hinzufügen, geben Sie 0.0.0.0/0 ein und fügen Sie die Adresse hinzu.

   Wenn Sie 0.0.0.0/0 verwenden, ist der Zugriff von jeder IP-Adresse aus möglich. Dies ist für eine temporäre Demo akzeptabel, aber in der Produktion sollten Sie den Zugriff auf bestimmte IP-Bereiche beschränken.

2. Geben Sie store-user als Nutzername und storeuser als Passwort ein und klicken Sie dann auf Datenbanknutzer erstellen.
3. Klicken Sie auf Verbindungsmethode auswählen und dann auf Treiber und Clientbibliotheken.
4. Kopieren Sie unter Verwenden Sie diesen Verbindungsstring in Ihrer Anwendung den Verbindungsstring. Er sieht so aus: mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. Ersetzen Sie durch storeuser und speichern Sie den String. Sie benötigen ihn in tools.yaml.

Wenn Sie das Dialogfeld geschlossen haben, öffnen Sie Datenbank > Cluster und klicken Sie bei ecommerce-cluster auf Verbinden.

Datenbank und Sammlung erstellen

1. Klicken Sie im linken Navigationsbereich auf Data Explorer und dann auf Datenbank erstellen. Geben Sie die folgenden Details ein:
   • Datenbankname: ecommerce_db
   • Name der Sammlung: product_details_collection
2. Klicken Sie auf Datenbank erstellen.
3. Wählen Sie im Data Explorer den Namen der Sammlung aus.
4. Klicken Sie auf das Symbol Daten hinzufügen (+) und dann auf Dokument einfügen.
5. Kopieren Sie den JSON-Inhalt aus product_details_export.json und fügen Sie ihn in das Dialogfeld Insert Document ein.
6. Atlas zeigt ein Banner an, in dem angeboten wird, den Text in Shell-Syntax zu konvertieren. Klicken Sie auf KONVERTIEREN und dann auf Einfügen. Prüfen Sie, ob 192 Dokumente hinzugefügt wurden.
7. Klicken Sie im Data Explorer neben der Datenbank ecommerce_db auf Sammlung erstellen (+).
8. Geben Sie user_interactions_collection als Namen für die Sammlung ein und klicken Sie auf Sammlung erstellen.
9. Wählen Sie im Data Explorer die Sammlung user_interactions_collection aus.
10. Klicken Sie auf das Symbol Daten hinzufügen (+) und dann auf Dokument einfügen.
11. Kopieren Sie den JSON-Inhalt aus user_interactions_export.json und fügen Sie ihn in das Dialogfeld Dokument einfügen ein.
12. Atlas zeigt ein Banner an, in dem angeboten wird, den Text in Shell-Syntax zu konvertieren. Klicken Sie auf KONVERTIEREN und dann auf Einfügen. Prüfen Sie, ob 211 Dokumente hinzugefügt wurden.

6. BigQuery einrichten

BigQuery aggregiert und analysiert das bisherige Nutzerverhalten, um intelligente Berichte und Empfehlungen zu generieren.

Dataset erstellen

1. Rufen Sie in der Google Cloud Console BigQuery auf.
2. Klicken Sie im Bereich „Explorer“ neben Ihrer Projekt-ID auf das Dreipunkt-Menü und wählen Sie Dataset erstellen aus.
3. Geben Sie ecommerce_analytics als Dataset-ID ein.
4. Wählen Sie für Speicherort der Daten die Option US (multiple regions) aus. Die Konfiguration tools.yaml erwartet den Standort US.
5. Klicken Sie auf Dataset erstellen.

Analysetabelle erstellen

1. Öffnen Sie eine neue Abfrage im BigQuery-Arbeitsbereich.
2. Führen Sie die folgende SQL-Anweisung aus, um die Übersichtstabelle zu erstellen, in der Nutzer mit Produktinteraktionen verknüpft werden:

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

Dem Compute-Dienstkonto Rollen zuweisen

Weisen Sie dem Compute-Standarddienstkonto die Rollen zu, die die MCP Toolbox und die Anwendung benötigen:

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

Alternativ können Sie in der Console zu IAM und Verwaltung > IAM gehen, auf Zugriff gewähren klicken, das Dienstkonto eingeben und dieselben Rollen hinzufügen.

7. Anwendung von Anfang bis Ende verstehen

Um zu erfahren, wie die einzelnen Komponenten zusammenarbeiten, erstellen wir eine E-Commerce-Anwendung, die mehrere Datenbanken und Dienste verwendet. Die Anwendung basiert auf einem Python-Backend (Flask) und bindet mehrere Google Cloud-Dienste und -Datenbanken ein.

Verzeichnisstruktur

Im nächsten Abschnitt klonen Sie das Repository polyglot-persist-ecommerce und verwenden es, um die Anwendung lokal auszuführen. Nachdem wir die Anwendung lokal getestet haben, stellen wir sowohl die MCP Toolbox als auch die Anwendung in Cloud Run bereit.

Sehen Sie sich die heruntergeladenen Dateien in diesem Verzeichnis an. Die folgenden übergeordneten Verzeichnisse sind vorhanden:

• UploadImages: Speichert Bild-Assets, die hauptsächlich für Dokumentation oder visuelle Inhalte für den E-Commerce-Produktkatalog verwendet werden.
• static: Speichert die statischen Web-Assets der Anwendung, z. B. CSS- und JavaScript-Dateien, die zum Gestalten und Hinzufügen von Interaktivität zur Benutzeroberfläche verwendet werden ( Quelle).
• templates: Speichert die HTML-Vorlagen (wahrscheinlich Jinja2 für Flask), die von der Python-Anwendung verwendet werden, um Webseiten für den E-Commerce-Katalog dynamisch zu rendern ( Quelle).

Die Dateien in diesem Repository werden zusammen verwendet, um eine E-Commerce-Anwendung mit mehreren Datenbanken zu erstellen, zu konfigurieren und bereitzustellen. Zentrale Dateien wie app.py orchestrieren das Backend, indem sie verschiedene Datenquellen integrieren, die in SQL- und JSON-Dateien definiert sind. Konfigurationsdateien sorgen für eine nahtlose Bereitstellung in Cloud-Umgebungen:

• app.py: Orchestriert das Flask-Backend und die Integration mehrerer Datenbanken.
• agentengine.py: Kernlogik zum Initialisieren und Konfigurieren von Vertex AI-Agenten.
• .env: Speichert Secrets für Datenbank- und Speicherverbindungen.
• tools.yaml: Konfiguriert die MCP Toolbox für multidb-Datenbankvorgänge.
• Dockerfile: Definiert das Container-Image und die Umgebungseinrichtung.
• requirements.txt: Listet Python-Bibliotheken auf, die für die Anwendungslaufzeit erforderlich sind.
• tools.yaml: Konfigurationen für MCP Toolbox.
• Procfile: Gibt Produktionsausführungsbefehle für die Bereitstellung an.
• alloydb_insert_queries.sql: enthält SQL-Abfragen für relationale Daten.
• product_details_export.json und user_interactions_export.json: stellt JSON-Beispieldaten für die NoSQL-Datenbank bereit.
• README.md: führt durch Einrichtung, Bereitstellung und Projektverständnis.

End-to-End-Ablauf der Anwendung

• AlloyDB einrichten: Stellen Sie einen Hochleistungscluster bereit und verwenden Sie die bereitgestellten SQL-Skripts, um die products_core_table mit Vektorspalten für Bildeinbettungen zu erstellen.
• MongoDB Atlas-Einrichtung: Stellen Sie einen Cluster in Google Cloud bereit, um dynamische Produktattribute in „product_details“ zu speichern und Echtzeit-Clickstreams in „user_interactions“ zu protokollieren.
• BigQuery Analytics: Erstellen Sie ein Dataset, um Interaktionslogs zu aggregieren. So können Sie komplexe analytische Abfragen durchführen, um die „Top 5“-Trendartikel aus Millionen von Ereignissen zu ermitteln.
• Cloud Storage-Repository: Erstellen Sie einen öffentlichen Bucket für hochauflösende Produktbilder. Jedes Asset muss über eine signierte oder öffentliche URL für das Frontend zugänglich sein.
• MCP Toolbox bereitstellen: Stellen Sie die Toolbox in Cloud Run bereit, um sie als zentrale RESTful-Brücke zu etablieren, die Absichten in natürlicher Sprache in Abfragen für mehrere Datenbanken übersetzt.
• Tools.yaml-Konfiguration: Definieren Sie Ihre „Tools“, z. B. get_product_core_data oder get_top_5_views, und ordnen Sie bestimmte SQL- und NoSQL-Vorgänge einfachen, für den Agenten lesbaren Namen zu.
• Flask-Backend-Logik: Implementieren Sie app.py-Routen, die mit der MCP Toolbox interagieren, die Koordination des Datenabrufs übernehmen und als API für die Benutzeroberfläche dienen.
• Multi-Agenten-Orchestrierung: Konfigurieren Sie die ADK-Agenten im Code so, dass sie die Nutzerabsicht analysieren und das richtige „Tool“ auswählen, um komplexe Einzelhandelsanfragen aus mehreren Quellen zu beantworten.
• Frontend-Integration: Erstellen Sie eine index.html-Oberfläche mit dem Produktkatalog und einer Funktion zum Aufzeichnen von Interaktionen, einem Tab „Analytics“ für die Analyse der Produktleistung und einem speziellen Tab „Agent“, der den Multi-Agenten-Chat des ADK verwendet, um ein nahtloses konversationelles Einkaufserlebnis zu bieten.

Jetzt implementieren wir die Orchestrierung und die Bereitstellungen.

8. MCP Toolbox einrichten und in Cloud Run bereitstellen

Die MCP Toolbox abstrahiert unsere verschiedenen Datenquellen, sodass unsere Anwendung Daten einheitlich abrufen und schreiben kann.

MCP Toolbox lokal installieren

Laden Sie das MCP Toolbox-Binärprogramm in Ihr Basisverzeichnis herunter und machen Sie es ausführbar:

export VERSION=1.15.0
curl -L -o ~/toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x ~/toolbox

tools.yaml konfigurieren

Sie müssen die Abstraktionen für AlloyDB, MongoDB und BigQuery definieren. Die Datei tools.yaml gibt der MCP-Toolbox an, wie die Komponenten miteinander interagieren sollen.

1. Das Repository enthält bereits tools.yaml. Öffnen Sie die App:

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

2. Ersetzen Sie die Platzhalter ***** durch Ihre Werte:

   Datenbank	Feld	Beispielwert
   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 (fügen Sie diese Zeile unter alloydb-source hinzu, falls sie nicht vorhanden ist)
   MongoDB	uri	den Verbindungsstring, den Sie zuvor gespeichert haben

3. Verweisen Sie mit den Bildvorschauen auf Ihren Bucket:

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

Tool-UI testen

1. Führen Sie die Toolbox im Cloud Shell-Terminal lokal aus, um die Benutzeroberfläche bereitzustellen:

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

2. Klicken Sie in Cloud Shell auf Webvorschau > Port ändern, geben Sie 5000 ein und fügen Sie am Ende der URL, die geöffnet wird, /ui hinzu.

Die folgende MCP Toolbox-Benutzeroberfläche wird angezeigt:

Wenn Sie fertig sind, drücken Sie Ctrl+C, um die lokale Toolbox zu beenden.

In Cloud Run bereitstellen

Stellen Sie die MCP Toolbox in Cloud Run bereit, um sie als sicheren, verwalteten Dienst verfügbar zu machen, den unsere Anwendung zum Abfragen der Datenbanken verwenden kann. Wir speichern die Konfiguration in Secret Manager, um sensible Verbindungsdetails zu schützen.

1. Laden Sie die tools.yaml-Konfiguration in Google Secret Manager hoch:

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

   Wenn Sie tools.yaml später ändern, laden Sie eine neue Version mit folgendem Befehl hoch:

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

2. Stellen Sie die MCP Toolbox mithilfe des öffentlichen Container-Images bereit:

   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 aktiviert die REST API, die von der Webanwendung verwendet wird.
3. Speichern Sie die Toolbox-URL:

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

   Sie können $TOOLBOX_URL/ui in Ihrem Browser öffnen, um die Tools zu sehen.

9. E-Commerce-Anwendung einrichten und in Cloud Run bereitstellen

Nachdem die Datenbanken ausgeführt werden und die MCP Toolbox-Abstraktion bereitgestellt wurde, können wir die Flask-Webanwendung ausführen.

Um den Produktkatalog bereitzustellen, verarbeitet die Flask-Anwendung Daten mit den folgenden Schritten:

1. Kerndaten abrufen: Ruft die vollständige Liste der Produkte aus AlloyDB (list_products_core) ab.
2. Erweiterte Details abrufen: Ruft alle Produktdetails aus MongoDB (list_all_product_details) ab.
3. Listen kombinieren: Die beiden Listen werden verkettet.
4. Mit Medien anreichern: Fügt jedem Element die Cloud Storage-Bild-URL hinzu.

Agent Engine erstellen

1. Installieren Sie die Abhängigkeiten:

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

   Hinweis: Dieser Schritt kann einige Minuten dauern, da Pakete aufgelöst und installiert werden müssen.
2. KI-Agent mit der Vertex AI Reasoning Engine initialisieren und registrieren:

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

   Die Ausgabe sollte in etwa so aussehen:

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

Die Anwendung liest ihre Einstellungen aus Umgebungsvariablen, die Sie im folgenden Bereitstellungsbefehl übergeben. Sie müssen .env also nicht bearbeiten.

Frontend in Cloud Run bereitstellen

1. Stellen Sie die Webanwendung in Cloud Run bereit, um die Architektur zu vervollständigen:

   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"
   

   Die App verwendet gemini-3.5-flash, das vom Standort global bereitgestellt wird. Die Agent Engine bleibt in us-central1.

   Wenn die Bereitstellung fehlschlägt, führen Sie den Befehl gcloud auth login aus, um die Bereitstellung zu autorisieren, und führen Sie dann den Bereitstellungsbefehl noch einmal aus.

Ihre Anwendung ist jetzt live! Öffnen Sie die von Cloud Run bereitgestellte Dienst-URL, um den Multidb-E-Commerce-Katalog aufzurufen. Die URL sieht in etwa so aus: https://polyglot-*********-uc.a.run.app/.

10. Anwendung ansehen

1. Klicken Sie auf Produktkatalog, um alle Produkte aufzurufen.
   
2. Klicken Sie auf ein Produktsymbol, um die Produktdetails aufzurufen. Die Bilder stammen aus Cloud Storage, die Produktdetails aus MongoDB und der Produktbestand aus AlloyDB.
3. Interagieren Sie mit dem Produktkatalog, um simulierte Aufrufe und Schreibvorgänge zu generieren, die an MongoDB gesendet werden.
4. Klicken Sie auf ETL und Analyse, um die Produktanalysen aufzurufen. Die Produktanalysen werden aus BigQuery abgerufen.
   
5. Klicken Sie auf den Tab KI-Agent, um mit dem KI-Agenten zu interagieren. Stellen Sie Fragen in natürlicher Sprache, z. B.:
   

   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.
   

   

Die Suche liefert genau das, wonach wir gefragt haben: einen Rucksack ohne Lederkomponenten, der auf Lager ist und bei dem es in den Rezensionen keine Beschwerden über die Haltbarkeit der Träger gibt.

11. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Kosten für Ihr Google Cloud-Konto zu vermeiden.

Führen Sie die folgenden Cloud Shell-Befehle aus:

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

Optional: Löschen Sie die Agent Engine-Instanz:

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

Alternativ können Sie in der Google Cloud Console zu Vertex AI > Agent Engine gehen und die Instanz löschen.

Optional können Sie das gesamte Google Cloud-Projekt und alle zugehörigen Ressourcen mit dem folgenden Befehl löschen:

gcloud projects delete $PROJECT_ID

Öffnen Sie schließlich MongoDB Atlas in Google Cloud und löschen Sie den von Ihnen erstellten Cluster ecommerce-cluster, um sicherzustellen, dass keine ungenutzten Ressourcen der kostenlosen Stufe verbleiben.

12. Glückwunsch

Glückwunsch! Sie haben eine cloudübergreifende Multidb-Architektur erstellt.

Sie haben gezeigt, wie die MCP Toolbox als architektonischer Klebstoff für eine moderne, spezialisierte Anwendung dient. Durch die Zuordnung der richtigen Datenbank zur richtigen Aufgabe haben Sie Folgendes erreicht:

• Flexible Datenschreibvorgänge: MongoDB für Ereignisprotokolle.
• Transaktionskonsistenz: AlloyDB für die Kernintegrität.
• Leistungsstarke Analysen: BigQuery für Business Intelligence.
• Einheitliche Entwicklung: Ein einzelnes Python-Backend, das die gesamte Komplexität mithilfe der MCP Toolbox abstrahiert.

Referenzdokumente

Weitere Informationen zu ähnlichen Google Cloud-Produkten finden Sie in diesen Codelabs:

• AlloyDB AI: Erste Schritte mit Vektoreinbettungen in AlloyDB AI
• AlloyDB AI: Multimodale Einbettungen in AlloyDB
• MCP Toolbox: MCP Toolbox for Databases in AlloyDB installieren und einrichten

Weitere Informationen zu den in diesem Codelab verwendeten Produkten finden Sie hier:

• Dokumentation zu AlloyDB for PostgreSQL
• Dokumentation zu MongoDB Atlas in Google Cloud
• BigQuery-Dokumentation
• Cloud Storage-Dokumentation
• Cloud Run-Dokumentation
• Cloud Build-Dokumentation
• MCP Toolbox-Implementierung