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

1. Einführung

Im modernen Einzelhandel sind Ihre Daten ein vielfältiges, weitläufiges Ökosystem. Sie haben solide Transaktionsdaten (Preise und Inventar), „unsaubere“ polymorphe Kataloge (Elektronikspezifikationen im Vergleich zu Bekleidungsgrößen) und Petabyte an Verhaltensprotokollen. Wenn Sie diese in einen einzelnen Monolithen zwingen, entsteht nicht nur technische Schuld, sondern auch eine schlechte Nutzererfahrung.

In diesem Codelab entwickeln Sie ein Polyglot Powerhouse, das Folgendes vereint:

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

Die „Geheimzutat“? Sie verwenden die MCP Toolbox for Databases, um die in Cloud Run ausgeführten Datenquellen intelligent zu orchestrieren und als semantische Brücke zu vereinheitlichen. Anschließend stellen Sie eine Chat-App mit mehreren Agenten mit dem Agent Development Kit (ADK) bereit. Sie entwickeln nicht nur eine Suchleiste, sondern ein intelligentes Einzelhandels-Tool, 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-Agents scheitern bei der mehrdimensionalen Argumentation (Kombination von negativen Einschränkungen, visueller Ähnlichkeit und Echtzeitinventar). Normalerweise möchte ich mit einer Einzelhandelswebsite so interagieren:

„Hallo, ich plane eine Fotoreise in die Berge. Zeige mir einige wetterfeste Rucksäcke, die dem „AeroGlow Pro“ ähneln, aber keine Lederkomponenten haben. Sag mir bitte auch, ob sie tatsächlich auf Lager sind und ob sich andere Fotografen in den Rezensionen über die Haltbarkeit des Tragegurts beschwert haben.“

Warum diese Anfrage als „Agent Killer“ bezeichnet wird:

• Visuelle Ähnlichkeit (AlloyDB + Vector Search): „Ähnlich im Stil wie AeroGlow Pro“ erfordert einen Vergleich von Bildeinbettungen.
• Negative Einschränkung (MongoDB): „Ohne Leder“ erfordert das Filtern über flexible, verschachtelte Attribute, die normalerweise nicht in einem Standard-SQL-Schema enthalten sind.
• Echtzeitinventar (AlloyDB): Für „Tatsächlich auf Lager“ ist eine Live-Transaktionsprüfung erforderlich (kein veralteter Suchindex).
• Semantische Synthese (BigQuery + Multi-Agent): Um Rezensionen zur „Strapazierfähigkeit des Armbands“ zu analysieren, muss der Agent unstrukturiertes Feedback aus BigQuery spontan zusammenfassen.

Die meisten Einzelhandelsbots würden nur „Rucksack“ und „Leder“ sehen und 10 Lederrucksäcke anzeigen. Wie verhindern wir das?

Wir gleichen nicht nur Keywords ab. Wir verwenden die MCP Toolbox, damit unsere Kundenservicemitarbeiter gleichzeitig auf alle diese Quellen zugreifen können, um die transaktionale Wahrheit in AlloyDB und die flexiblen Attribute in MongoDB zu analysieren. Lass uns das erstellen.

Aufgaben

• AlloyDB-Cluster für Kernproduktdaten bereitstellen
• MongoDB Atlas in Google Cloud zum Speichern von halbstrukturierten Produktdetails konfigurieren
• Cloud Storage-Bucket zum Bereitstellen von Produktbildern erstellen
• MCP Toolbox for Databases in Cloud Run bereitstellen, um einheitlichen Datenzugriff zu ermöglichen
• 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 zur 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 mit den erforderlichen Tools vorinstalliert ist.

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
2. Prüfen Sie nach der Verbindung mit Cloud Shell 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
   

Erforderliche APIs aktivieren

Führen Sie diesen 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 umfassender Speicher für unstrukturierte Media-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-app-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 User aus.
9. Klicken Sie auf Speichern und dann auf Öffentlichen Zugriff erlauben, um zu bestätigen, dass Sie die Ressource öffentlich machen.

Platzhalterbilder hochladen

Im Beispiel BRK2-149-multidb-ecommerce werden Platzhalterbilder verwendet, um eine optimale Darstellung zu gewährleisten.

1. Klonen Sie in Cloud Shell das Repository next-26-sessions:

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

2. Rufen Sie den UploadImages-Ordner auf:

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

3. Rufen Sie in der Google Cloud Console Cloud Storage auf und klicken Sie auf Buckets.
4. Klicken Sie auf den Namen des neu erstellten Buckets.
5. Klicken Sie auf Hochladen > Dateien hochladen, wählen Sie die heruntergeladenen Beispielbilder aus und klicken Sie auf Öffnen.

4. AlloyDB einrichten

AlloyDB dient als Single Source of Truth für strukturierte, transaktionale und kritische Daten wie Produkt-IDs, Namen, Artikelnummern, 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 der Codelab-Anleitung.

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 bei 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 als Maschinentyp einen kleinen Maschinentyp aus, z.B. N2, 4 vCPUs, 32 GB RAM.
4. Wählen Sie unter Private IP Connectivity (Private IP-Verbindung) die Option Private Services Access (PSA) (Zugriff auf private Dienste) und das default-Netzwerk aus.Wenn das Standardnetzwerk noch nicht festgelegt ist, klicken Sie auf Confirm network setup (Netzwerkeinrichtung bestätigen), um es zu erstellen.
5. Wählen Sie unter Verbindung über öffentliche IP-Adresse das Kästchen Öffentliche IP-Adresse aktivieren aus, damit die MCP-Toolbox in diesem Codelab eine Verbindung herstellen kann.
6. Geben Sie unter Autorisierte externe Netzwerke den Wert 0.0.0.0/0 ein. Klicken Sie das Kästchen Ich bin mir der Risiken bewusst an und klicken Sie auf Speichern.
7. Klicken Sie auf Cluster erstellen.

Hinweis: Notieren Sie sich Ihre öffentliche IP-Adresse (sie sieht ähnlich aus wie 34.124.240.26).

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 für Nutzername den Nutzer postgres.
5. Geben Sie unter Passwort das Passwort ein, das Sie zuvor festgelegt haben.
6. Klicken Sie auf Authentifizieren.
7. Öffnen Sie in der Editoransicht einen neuen Tab „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 Ordner BRK2-149-multidb-ecommerce:

   cd next-26-sessions/BRK2-149-multidb-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 in einen neuen unbenannten Abfragetab die folgende DDL 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, damit ähnliche Produkte abgerufen werden können

Bei der Integration von KI‑Agents 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 Embeddings generieren können, müssen wir dem AlloyDB-Dienstkonto die erforderlichen Rollen für den Zugriff auf Cloud Storage gewähren.

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

Wir weisen dem AlloyDB-Dienstkonto die Rolle „Storage-Objekt-Nutzer“ und „Storage-Objekt-Betrachter“ zu, damit es Objekte aus dem Cloud Storage-Bucket lesen kann.

1. Rufen Sie IAM und Verwaltung auf.
2. Klicken Sie auf Zugriff erlauben.
3. Geben Sie im Feld Neue Hauptkonten das Dienstkonto für die Suche nach AlloyDB ein. Das Dienstkonto sieht in etwa so aus: [e-mail].
4. Klicken Sie auf Rolle auswählen.
5. Suchen Sie die Rolle Storage Object User und wählen Sie sie aus.
6. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Storage-Objekt-Betrachter aus.
7. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Vertex AI User aus.
8. Klicken Sie auf Speichern.

Erweiterungen aktivieren

Für die Entwicklung dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der Erweiterung pgvector können Sie Vektoreinbettungen speichern und durchsuchen. Die google_ml_integration-Erweiterung bietet Funktionen, mit denen Sie auf Vertex AI Prediction-Endpunkte zugreifen können, um Vorhersagen in SQL zu erhalten. 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 „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 der products_core_table die Spalte „img_embeddings“ hinzu.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Generieren Sie Einbettungen für die Bilder und speichern Sie sie in der Spalte 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
   );
   

   Ersetzen Sie durch den Namen Ihres Cloud Storage-Buckets.
3. Wiederholen Sie die vorherige Abfrage mindestens fünfmal, um Bild-Embeddings für das gesamte Set zu generieren, da Studio eine Zeitbeschränkung von fünf Minuten hat. Wenn das Zeitlimit für diese Abfrage überschritten wird, ändern Sie LIMIT in 5 und führen Sie die Abfrage zehnmal aus. Dieser Schritt kann einige Minuten dauern.

5. MongoDB Atlas in Google Cloud einrichten

In MongoDB werden umfangreiche, semistrukturierte Produktdetails und flexible Daten zum Nutzerverhalten (z. B. Klicks und Aufrufe) gespeichert.\

MongoDB-Cluster erstellen

1. Rufen Sie MongoDB Atlas in Google Cloud auf und wählen Sie ein Konto für die kostenlose Stufe aus.
2. Wählen Sie die Clusterstufe Kostenlos aus und geben Sie einen Namen für den Cluster ein, z. B. ecommerce-cluster.
3. Wählen Sie Google Cloud als Anbieter aus und achten Sie darauf, dass die Region mit Ihrer Google Cloud-Region übereinstimmt (z.B. us-central1).
4. Klicken Sie auf Deployment erstellen.
5. Klicken Sie auf Schließen.

Netzwerkzugriff konfigurieren

1. Rufen Sie in der Atlas-Konsole Database & Network Access (Datenbank- und Netzwerkzugriff) auf.
2. Klicken Sie auf IP-Zugriffsliste.
3. Klicken Sie auf IP-Adresse hinzufügen.
4. Fügen Sie 0.0.0.0/0 hinzu, um den Zugriff von überall aus zu ermöglichen.
5. Klicken Sie auf Bestätigen.

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

Datenbanknutzer erstellen

1. Rufen Sie in der Atlas-Konsole Database & Network Access (Datenbank- und Netzwerkzugriff) auf.
2. Klicken Sie auf Datenbanknutzer.
3. Klicken Sie auf Neuen Datenbanknutzer hinzufügen.
4. Wählen Sie Passwort als Authentifizierungsmethode aus.
5. Geben Sie den Nutzernamen als store-user und das Passwort als storeuser ein.
6. Klicken Sie auf Integrierte Rolle hinzufügen und wählen Sie Lesen und Schreiben in beliebige Datenbanken aus.
7. Klicken Sie auf Nutzer hinzufügen.

Verbindungsstring abrufen

1. Klicken Sie auf Database > Clusters > Connect (Datenbank > Cluster > Verbinden).
2. Klicken Sie unter Anwendung verbinden auf Treiber.
3. Kopieren Sie den Verbindungsstring, der unter Verbindungsstring in den Anwendungscode einfügen angezeigt wird. Der String sieht in etwa so aus:

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

   Ersetzen Sie db_password durch Ihr MongoDB-Passwort. In diesem Codelab ist das storeuser.

Speichern Sie diese Verbindungszeichenfolge. Sie verwenden sie später für die Umgebungsvariable MONGODB_CONNECTION_STRING.

Datenbank und Sammlung erstellen

1. Rufen Sie in der Atlas-Konsole Database > Clusters > Browse Collections auf.
2. Klicken Sie auf Datenbank erstellen und geben Sie die Details ein:
   • Datenbankname : ecommerce_db
   • Name der Sammlung: product_details_collection
3. Klicken Sie auf Datenbank erstellen.
4. Wählen Sie im Data Explorer den Sammlungsnamen aus.
5. Klicken Sie auf das Symbol Daten hinzufügen (+) und dann auf Dokument einfügen.
6. Kopieren Sie den JSON-Inhalt aus product_details_export.json und fügen Sie ihn in den Editor für Dokument einfügen ein.
7. Klicken Sie auf Einfügen, um das Array von Dokumenten einzufügen, und prüfen Sie, ob 192 Dokumente hinzugefügt wurden.
8. Klicken Sie im Data Explorer neben der Datenbank ecommerce_db auf Sammlung erstellen (+).
9. Geben Sie user_interactions_collection als Namen für die Sammlung ein und klicken Sie auf Sammlung erstellen.
10. Wählen Sie im Data Explorer die Sammlung user_interactions_collection aus.
11. Klicken Sie auf das Symbol Daten hinzufügen (+) und dann auf Dokument einfügen.
12. Kopieren Sie den JSON-Inhalt aus user_interactions_export.json und fügen Sie ihn in das Dialogfeld Dokument einfügen ein.
13. Klicken Sie auf Dokument einfügen.

6. BigQuery einrichten

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

Dataset erstellen

1. Rufen Sie in der Google Cloud Console BigQuery auf.
2. Klicken Sie im Explorer-Bereich neben Ihrer Projekt-ID auf das Dreipunkt-Menü und wählen Sie Dataset erstellen aus.
3. Geben Sie als Dataset-ID ecommerce_analytics ein.
4. Klicken Sie auf Dataset erstellen.

Analytics-Tabelle erstellen

1. Öffnen Sie eine neue Abfrage im BigQuery-Arbeitsbereich.
2. Führen Sie die folgende SQL-Anweisung aus, um die Zusammenfassungstabelle 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
);

Compute-Dienstkonto für die MCP Toolbox Rollen zuweisen

Wir weisen dem Compute-Dienstkonto, das für unsere Toolbox verwendet wird, Rollen zu. Dies ist erforderlich, damit die MCP Toolbox auf BigQuery, Secret Manager und andere Cloud-Dienste zugreifen kann.

Klicken Sie in der Google Cloud Console auf Cloud-Übersicht > Dashboard, um die Projektnummer zu finden. Notieren Sie sich die Projektnummer auf der Karte Projektinformationen.

So weisen Sie Rollen zu:

1. Rufen Sie IAM und Verwaltung auf.
2. Klicken Sie auf Zugriff erlauben.
3. Geben Sie im Feld Neue Hauptkonten das standardmäßige Compute-Dienstkonto mit dem Namen [e-mail] ein. Ersetzen Sie YOUR_PROJECT_NUMBER durch Ihre Google Cloud-Projektnummer.
4. Klicken Sie auf Rolle auswählen.
5. Suchen Sie nach der Rolle BigQuery-Datenbearbeiter und wählen Sie sie aus.
6. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle BigQuery-Jobnutzer aus.
7. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Secret Manager Secret Accessor aus.
8. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Editor aus.
9. Klicken Sie auf Speichern.

7. Anwendung von Anfang bis Ende verstehen

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

Verzeichnisstruktur

Im nächsten Abschnitt klonen Sie das Repository BRK2-149-multidb-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 Verzeichnisse sind vorhanden:

• UploadImages: Hier werden Bild-Assets gespeichert, die hauptsächlich für die Dokumentation oder visuelle Inhalte für den E-Commerce-Produktkatalog verwendet werden.
• static: Hier werden die statischen Web-Assets der Anwendung gespeichert, z. B. CSS- und JavaScript-Dateien, die zum Gestalten und Hinzufügen von Interaktivität zur Benutzeroberfläche verwendet werden ( Quelle).
• templates: Hier werden die HTML-Vorlagen (wahrscheinlich Jinja2 für Flask) gespeichert, die von der Python-Anwendung verwendet werden, um Webseiten für den E-Commerce-Katalog dynamisch zu rendern ( Quelle).
• toolbox-implementation: Speichert Konfigurations- und Implementierungsdetails für die MCP-Toolbox (Model Context Protocol) und ermöglicht die Interaktion mit mehreren Datenbanken mithilfe vordefinierter Tools.

Die Dateien in diesem Repository arbeiten zusammen, 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 Integrationen mehrerer Datenbanken.
• agentengine.py: Kernlogik zum Initialisieren und Konfigurieren von Vertex AI-Agents.
• .env: Speichert Secrets für Datenbank- und Speicherverbindungen.
• tools.yaml: Konfiguriert die MCP Toolbox für Datenbankvorgänge mit mehreren Datenbanken.
• Dockerfile: Definiert das Container-Image und die Umgebungseinrichtung.
• requirements.txt: Listet die Python-Bibliotheken auf, die für die Ausführung der Anwendung erforderlich sind.
• tools.yaml: Konfigurationen für die MCP Toolbox.
• Procfile: Gibt Befehle für die Produktionsausführung für das Deployment an.
• alloydb_insert_queries.sql: Enthält SQL-Abfragen für relationale Daten.
• product_details_export.json und user_interactions_export.json: Hier finden Sie JSON-Beispieldaten für die NoSQL-Datenbank.
• README.md: bietet Anleitungen für Einrichtung, Bereitstellung und Projektverständnis.

End-to-End-Ablauf der Anwendung

• AlloyDB-Einrichtung: Stellen Sie einen leistungsstarken Cluster bereit und verwenden Sie die bereitgestellten SQL-Scripts, um die Tabelle „products_core_table“ mit Vektorspalten für Bildeinbettungen zu erstellen.
• MongoDB Atlas einrichten: Stellen Sie einen Cluster in Google Cloud bereit, um flexible Produktattribute in „product_details“ zu speichern und Clickstreams in Echtzeit in „user_interactions“ zu protokollieren.
• BigQuery Analytics: Erstellen Sie ein Dataset, um Interaktionslogs zusammenzufassen. So können Sie komplexe analytische Abfragen ausführen, mit denen sich die fünf beliebtesten Trendartikel aus Millionen von Ereignissen ermitteln lassen.
• 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-Bereitstellung: Stellen Sie die Toolbox in Cloud Run bereit. Sie dient als zentrale RESTful-Brücke, die Absichten in natürlicher Sprache in Datenbankabfragen ü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 Agent lesbaren Namen zu.
• Flask-Backend-Logik: Implementieren Sie app.py-Routen, die mit der MCP Toolbox interagieren und die Koordination des Datenabrufs sowie die Bereitstellung als API für die Benutzeroberfläche übernehmen.
• Multiagenten-Orchestrierung: Konfigurieren Sie die ADK-Agents im Code, um die Nutzerabsicht zu analysieren und das richtige Tool auszuwählen, um komplexe Einzelhandelsanfragen mit mehreren Quellen zu beantworten.
• Frontend-Integration: Erstellen Sie eine index.html-Oberfläche mit dem Produktkatalog und einer Funktion zum Aufzeichnen von Interaktionen, einem Analytics-Tab, um die Produktleistung zu analysieren, und einem speziellen „Agent-Tab“, in dem der ADK-Multi-Agent-Chat für ein nahtloses Shoppingerlebnis genutzt wird.

Jetzt implementieren wir die Orchestrierung und die Deployments.

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

1. Wechseln Sie in Cloud Shell zum Ordner toolbox-implementation:

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

2. Laden Sie das MCP Toolbox-Binärprogramm herunter und machen Sie es ausführbar:

   export VERSION=0.29.0
   curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/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 an, wie die MCP-Toolbox miteinander interagieren soll.

1. Erstellen und bearbeiten Sie die Datei tools.yaml mit dem eingebetteten Editor:

   cloudshell edit tools.yaml
   

   Die vollständige tools.yaml-Datei finden Sie im GitHub-Repository. Kopieren Sie den Inhalt in Ihre neue tools.yaml-Datei.
2. Aktualisieren Sie den Host, den Nutzer, die Passwörter, die Projekt-IDs und die Verbindungsstrings entsprechend der Infrastruktur, die Sie in den vorherigen Schritten bereitgestellt haben:

   Datenbank	Feld	Beispielwert
   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]

Compute-Dienstkonto für die MCP Toolbox Rollen zuweisen

Wir weisen dem Compute-Dienstkonto, das für unsere Toolbox verwendet wird, Rollen zu. Dies ist erforderlich, damit die MCP Toolbox auf AlloyDB zugreifen kann.

1. Rufen Sie IAM und Verwaltung auf.
2. Klicken Sie auf Zugriff erlauben.
3. Geben Sie im Feld Neue Hauptkonten das standardmäßige Compute-Dienstkonto mit dem Namen [e-mail] ein. Ersetzen Sie YOUR_PROJECT_NUMBER durch Ihre Google Cloud-Projektnummer.

   Projektnummer:Klicken Sie in der Google Cloud Console auf Cloud-Übersicht > Dashboard, um die Projektnummer zu finden. Notieren Sie sich die Projektnummer auf der Karte Projektinformationen.

4. Klicken Sie auf Rolle auswählen.
5. Suchen Sie nach der Rolle BigQuery-Datenbearbeiter und wählen Sie sie aus.
6. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle AlloyDB Client aus.
7. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Service Usage Consumer aus.
8. Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Storage-Objekt-Betrachter aus.
9. Klicken Sie auf Speichern.

Tool-Benutzeroberfläche testen

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

   ./toolbox --ui
   

2. Öffnen Sie die Webvorschau in Cloud Shell auf Port 5000 und rufen Sie die Seite „Tools“ auf. Je nach Sitzungs-URL können Sie sie beispielsweise unter https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui aufrufen.

Auf die MCP-Benutzeroberfläche in Cloud Shell zugreifen:In Cloud Shell werden lokale Ports über die Webvorschau verfügbar gemacht. Anstatt localhost:8080 zu öffnen, müssen Sie die Webvorschau-URL verwenden und /ui anhängen, z. B. https://5000-cs-.../ui?authuser=0. Andernfalls wird nur eine einfache „Hello World“-Nachricht anstelle des geladenen UI-Dashboards angezeigt.

Die folgende Benutzeroberfläche der MCP Toolbox wird angezeigt:

In Cloud Run bereitstellen

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

1. Öffnen Sie eine neue Cloud Shell-Sitzung.
2. Rufen Sie den toolbox-implementation-Ordner auf:

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

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

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

   Hinweis: Wenn Sie dem vorhandenen Secret eine neue Version hinzufügen möchten, verwenden Sie den folgenden Befehl:

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

4. Bereitstellung mit dem öffentlichen MCP-Toolbox-Container-Image:

   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. Notieren Sie sich nach der Bereitstellung die bereitgestellte Cloud Run-Dienst-URL. Sie sollte etwa so https://toolbox-*********-uc.a.run.app/ui aussehen:

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

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

Zum Bereitstellen des Produktkatalogs verarbeitet die Flask-Anwendung Daten in 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 Media anreichern: Die Cloud Storage-Bild-URL wird jedem Element hinzugefügt.

Anwendungspfad für Reasoning Engine generieren

Führen Sie den folgenden Befehl aus, um einen KI-Agenten mit der Vertex AI Reasoning Engine von Google Cloud zu initialisieren und zu registrieren:

1. Wechseln Sie im Cloud Shell-Terminal zum Ordner BRK2-149-multidb-ecommerce.

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

2. Führen Sie „requirements.txt“ aus, um die Abhängigkeiten zu installieren.

   pip install -r requirements.txt
   

3. Führen Sie das Skript agentengine.py aus, um den Anwendungspfad der Reasoning Engine zu generieren:

   python agentengine.py
   

Die Ausgabe sollte in etwa so aussehen:

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

Umgebungsvariablen konfigurieren

1. .env-Datei erstellen und bearbeiten:

   cloudshell edit .env
   

2. Ersetzen Sie die Werte durch Ihre spezifischen Datenbankverbindungen und Ihre neue Cloud Run Toolbox-URL:

   # 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
   

   Möglicherweise werden nicht alle Bilder sofort geladen. Einige Links fehlen möglicherweise oder sind falsch, je nachdem, wie Eigenschaften Produkt-SKUs im geklonten Anwendungs-Dataset zugeordnet werden. Prüfen Sie die Richtlinien für den öffentlichen Zugriff Ihres GCS-Buckets und achten Sie darauf, dass die Dateinamen richtig zugeordnet sind.

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 . --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"
   

   Ersetzen Sie die folgenden Werte:
   • YOUR_PROJECT_ID: Ihre Google Cloud-Projekt-ID.
   • YOUR_REASONING_ENGINE_APP_PATH: Die Ausgabe nach dem Ausführen von python agentengine.py, z. B. projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856.
   • MCP_TOOLBOX_SERVER_URL: Die URL Ihres MCP Toolbox-Servers, z. B. https://toolbox-*********-uc.a.run.app.
   • GCS_PRODUCT_BUCKET: Der Name Ihres Google Cloud Storage-Buckets, z. B. ecommerce-app-images.
   • MONGODB_CONNECTION_STRING: Der Verbindungsstring für Ihre MongoDB-Datenbank, z. B. mongodb+srv://store-user:[e-mail]
   • FALLBACK_IMAGE_URL: Die URL des Fallback-Bildes, z. B. https://storage.googleapis.com/ecommerce-app-images/fallback.jpg

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

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

10. Anwendung ausprobieren

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 werden aus MongoDB und der Produktbestand aus AlloyDB abgerufen.
3. Interagieren Sie mit dem Produktkatalog, um Mock-Ansichten und ‑Schreibvorgänge zu generieren, die an MongoDB gesendet werden.
4. Klicken Sie auf ETL & Analytics, 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 Lederbestandteile, der auf Lager ist und bei dem es in den Rezensionen keine Beschwerden über die Haltbarkeit der Tragegurte gibt.

11. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren 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 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

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 Cluster0-Cluster, den Sie erstellt haben, um eine nicht genutzte kostenlose Stufe zu vermeiden.

12. Glückwunsch

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

Sie haben gezeigt, wie die MCP-Toolbox als architektonisches Bindemittel für eine moderne, spezialisierte Anwendung dient. Durch die Zuordnung der richtigen Datenbank zum richtigen Job haben Sie Folgendes erreicht:

• Flexible Data Writes: MongoDB für Ereignisprotokolle.
• Transaktionale Konsistenz: AlloyDB für die Kernintegrität.
• Leistungsstarke Analysen: BigQuery für Business Intelligence.
• Einheitliche Entwicklung: Ein einzelnes Python-Backend, das mithilfe der MCP Toolbox alle Komplexität abstrahiert.

Referenzdokumente

Weitere Informationen zu den zugehörigen Google Cloud-Produkten und Codelabs:

• AlloyDB AI: Erste Schritte mit Vektoreinbettungen in AlloyDB AI
• AlloyDB AI: Multimodale Einbettungen in AlloyDB
• MCP Toolbox: Installation und Einrichtung der MCP Toolbox for Databases in AlloyDB

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

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