Agentische RAG-Anwendung für AlloyDB mit der MCP-Toolbox

1. Einführung

In diesem Codelab erfahren Sie, wie Sie einen AlloyDB-Cluster erstellen, die MCP-Toolbox bereitstellen und sie so konfigurieren, dass AlloyDB als Datenquelle verwendet wird. Anschließend erstellen Sie eine interaktive RAG-Beispielanwendung, die die bereitgestellte Toolbox verwendet, um ihre Anfragen zu fundieren.

Weitere Informationen zur MCP Toolbox finden Sie auf der Dokumentationsseite und in der Beispielanwendung „Cymbal Air“ hier.

Dieses Lab ist Teil einer Lab-Sammlung, die sich mit AlloyDB AI-Funktionen befasst. Weitere Informationen finden Sie in der Dokumentation auf der AlloyDB AI-Seite und in den anderen Labs.

Voraussetzungen

• Grundkenntnisse der Google Cloud Console
• Grundkenntnisse in der Befehlszeile und Google Cloud Shell

Lerninhalte

• AlloyDB-Cluster mit Vertex AI-Integration bereitstellen
• Verbindung zu AlloyDB herstellen
• MCP Toolbox Service konfigurieren und bereitstellen
• Beispielanwendung mit dem bereitgestellten Dienst bereitstellen

Voraussetzungen

• Ein Google Cloud-Konto und ein Google Cloud-Projekt
• Ein Webbrowser wie Chrome

2. Einrichtung und Anforderungen

Einrichtung der Umgebung im eigenen Tempo

1. Melden Sie sich in der Google Cloud Console an und erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eins erstellen.

• Der Projektname ist der Anzeigename für die Teilnehmer dieses Projekts. Es handelt sich um einen String, der nicht von Google APIs verwendet wird. Sie können sie jederzeit aktualisieren.
• Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und unveränderlich (kann nach dem Festlegen nicht mehr geändert werden). In der Cloud Console wird automatisch ein eindeutiger String generiert. Normalerweise ist es nicht wichtig, wie dieser String aussieht. In den meisten Codelabs müssen Sie auf Ihre Projekt-ID verweisen (in der Regel als PROJECT_ID angegeben). Wenn Ihnen die generierte ID nicht gefällt, können Sie eine andere zufällige ID generieren. Alternativ können Sie es mit einem eigenen Namen versuchen und sehen, ob er verfügbar ist. Sie kann nach diesem Schritt nicht mehr geändert werden und bleibt für die Dauer des Projekts bestehen.
• Zur Information: Es gibt einen dritten Wert, die Projektnummer, die von einigen APIs verwendet wird. Weitere Informationen zu diesen drei Werten

Achtung:Eine Projekt-ID ist global eindeutig und kann nach der Auswahl nicht mehr von anderen verwendet werden. Sie sind der einzige Nutzer dieser ID. Auch wenn ein Projekt gelöscht wird, kann die ID nicht wiederverwendet werden.

Hinweis:Wenn Sie ein Gmail-Konto verwenden, können Sie den Standardspeicherort auf Keine Organisation belassen. Wenn Sie ein Google Workspace-Konto verwenden, wählen Sie einen Standort aus, der für Ihre Organisation sinnvoll ist.

2. Als Nächstes müssen Sie die Abrechnung in der Cloud Console aktivieren, um Cloud-Ressourcen/-APIs zu verwenden. Die Durchführung dieses Codelabs kostet wenig oder gar nichts. Wenn Sie Ressourcen herunterfahren möchten, um Kosten zu vermeiden, die über diese Anleitung hinausgehen, können Sie die erstellten Ressourcen oder das Projekt löschen. Neue Google Cloud-Nutzer können am Programm Kostenlose Testversion mit einem Guthaben von 300$ teilnehmen.

Cloud Shell starten

Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.

Klicken Sie in der Google Cloud Console in der Symbolleiste oben rechts auf das Cloud Shell-Symbol:

Die Bereitstellung und Verbindung mit der Umgebung dauert nur einen Moment. Anschließend sehen Sie in etwa Folgendes:

Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Alle Aufgaben in diesem Codelab können in einem Browser ausgeführt werden. Sie müssen nichts installieren.

3. Hinweis

API aktivieren

Ausgabe:

Beachten Sie, dass für einige Ressourcen, die Sie aktivieren, Kosten anfallen, wenn Sie das Angebot nicht nutzen. Unter normalen Umständen und wenn alle Ressourcen nach Abschluss des Labs gelöscht werden, überschreiten die Kosten für alle Ressourcen nicht 5 $. Wir empfehlen Ihnen, Ihre Abrechnung zu prüfen und sich zu vergewissern, dass die Gebühren für Sie akzeptabel sind.

Prüfen Sie in Cloud Shell, ob Ihre Projekt-ID eingerichtet ist:

Normalerweise wird die Projekt-ID in der Cloud Shell in der Eingabeaufforderung in Klammern angezeigt, wie im Bild zu sehen:

gcloud config set project [YOUR-PROJECT-ID]

Legen Sie dann die Umgebungsvariable PROJECT_ID auf Ihre Google Cloud-Projekt-ID fest:

PROJECT_ID=$(gcloud config get-value project)

Aktivieren Sie alle erforderlichen Dienste:

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

Erwartete Ausgabe

student@cloudshell:~ (gleb-test-short-004)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com
Operation "operations/acf.p2-404051529011-664c71ad-cb2b-4ab4-86c1-1f3157d70ba1" finished successfully.

4. AlloyDB-Cluster bereitstellen

AlloyDB-Cluster und primäre Instanz erstellen Im folgenden Verfahren wird beschrieben, wie Sie mit dem Google Cloud SDK einen AlloyDB-Cluster und eine AlloyDB-Instanz erstellen. Wenn Sie die Konsolenmethode bevorzugen, finden Sie hier die Dokumentation.

Bevor wir einen AlloyDB-Cluster erstellen, benötigen wir einen verfügbaren privaten IP-Adressbereich in unserer VPC, der von der zukünftigen AlloyDB-Instanz verwendet werden soll. Wenn wir sie nicht haben, müssen wir sie erstellen, sie für die Verwendung durch interne Google-Dienste zuweisen und erst dann können wir den Cluster und die Instanz erstellen.

Privaten IP-Bereich erstellen

Hinweis:Dieser Schritt ist nur erforderlich, wenn Sie noch keinen ungenutzten privaten IP-Bereich haben, der für die Verwendung mit internen Google-Diensten zugewiesen ist.

Wir müssen den Zugriff auf private Dienste in unserer VPC für AlloyDB konfigurieren. Wir gehen hier davon aus, dass das VPC-Standardnetzwerk im Projekt vorhanden ist und für alle Aktionen verwendet wird.

Erstellen Sie den privaten IP-Bereich:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

Erstellen Sie eine private Verbindung mit dem zugewiesenen IP-Bereich:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

Hinweis:Die Ausführung des zweiten Befehls dauert einige Minuten.

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

AlloyDB-Cluster erstellen

In diesem Abschnitt erstellen wir einen AlloyDB-Cluster in der Region „us-central1“.

Legen Sie ein Passwort für den Postgres-Nutzer fest. Sie können ein eigenes Passwort definieren oder eine Zufallsfunktion verwenden, um eines zu generieren.

export PGPASSWORD=`openssl rand -hex 12`

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

Notieren Sie sich das PostgreSQL-Passwort für die spätere Verwendung.

echo $PGPASSWORD

Sie benötigen dieses Passwort später, um als Postgres-Nutzer eine Verbindung zur Instanz herzustellen. Ich empfehle, sie aufzuschreiben oder zu kopieren, damit Sie sie später verwenden können.

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

Cluster im kostenlosen Testzeitraum erstellen

Wenn Sie AlloyDB noch nicht verwendet haben, können Sie einen kostenlosen Testcluster erstellen:

Definieren Sie die Region und den Namen des AlloyDB-Clusters. Wir verwenden die Region „us-central1“ und „alloydb-aip-01“ als Clusternamen:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Führen Sie den folgenden Befehl aus, um den Cluster zu erstellen:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL

Erwartete Konsolenausgabe:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.                                                                                                                                                                                                                                                           

Erstellen Sie in derselben Cloud Shell-Sitzung eine primäre AlloyDB-Instanz für den Cluster. Wenn die Verbindung getrennt wird, müssen Sie die Umgebungsvariablen für die Region und den Clusternamen noch einmal definieren.

Hinweis:Das Erstellen der Instanz dauert in der Regel 6 bis 10 Minuten.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.                                                                                                                                                                                                                                                     

AlloyDB Standard-Cluster erstellen

Wenn es nicht Ihr erster AlloyDB-Cluster im Projekt ist, fahren Sie mit der Erstellung eines Standardclusters fort.

Definieren Sie die Region und den Namen des AlloyDB-Clusters. Wir verwenden die Region „us-central1“ und „alloydb-aip-01“ als Clusternamen:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Führen Sie den folgenden Befehl aus, um den Cluster zu erstellen:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

Erwartete Konsolenausgabe:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.                                                                                                                                                                                                                                                           

Erstellen Sie in derselben Cloud Shell-Sitzung eine primäre AlloyDB-Instanz für den Cluster. Wenn die Verbindung getrennt wird, müssen Sie die Umgebungsvariablen für die Region und den Clusternamen noch einmal definieren.

Hinweis:Das Erstellen der Instanz dauert in der Regel 6 bis 10 Minuten.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.                                                                                                                                                                                                                                                     

Erforderliche Berechtigungen für AlloyDB erteilen

Fügen Sie dem AlloyDB-Dienst-Agent Vertex AI-Berechtigungen hinzu.

Öffnen Sie oben einen weiteren Cloud Shell-Tab, indem Sie auf das Pluszeichen (+) klicken.

Führen Sie im neuen Cloud Shell-Tab Folgendes aus:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:[e-mail]
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1
 

Schließen Sie den Tab, indem Sie entweder den Befehl „exit“ auf dem Tab ausführen:

exit

5. GCE-VM vorbereiten

Wir verwenden eine Google Compute Engine-VM (GCE-VM) als Plattform, um mit der Datenbank zu arbeiten und verschiedene Teile der Beispielanwendung bereitzustellen. Die Verwendung einer VM bietet uns mehr Flexibilität bei den installierten Komponenten und direkten Zugriff auf die private AlloyDB-IP für die Datenaufbereitungsschritte.

Dienstkonto erstellen

Da wir unsere VM verwenden, um die MCP Toolbox als Dienst bereitzustellen und die Beispielanwendung bereitzustellen oder zu hosten, müssen wir zuerst ein Google-Dienstkonto (Google Service Account, GSA) erstellen. Das GSA wird von der GCE-VM verwendet und wir müssen ihm die erforderlichen Berechtigungen für die Arbeit mit anderen Diensten erteilen.

Führen Sie in Cloud Shell Folgendes aus:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create compute-aip --project $PROJECT_ID

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.admin

GCE-VM bereitstellen

Erstellen Sie eine GCE-VM in derselben Region und VPC wie der AlloyDB-Cluster.

Führen Sie in Cloud Shell Folgendes aus:

ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com
Your active configuration is: [cloudshell-10282]
Created [https://www.googleapis.com/compute/v1/projects/gleb-test-short-002-470613/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.28.55.32
STATUS: RUNNING

Postgres-Client installieren

PostgreSQL-Clientsoftware auf der bereitgestellten VM installieren

Stellen Sie eine Verbindung zur VM her.

Hinweis:Die erste SSH-Verbindung zur VM kann länger dauern, da der Prozess die Erstellung eines RSA-Schlüssels für die sichere Verbindung und die Übertragung des öffentlichen Teils des Schlüssels an das Projekt umfasst.

gcloud compute ssh instance-1 --zone=us-central1-a

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1 5.10.0-26-cloud-amd64 #1 SMP Debian 5.10.197-1 (2023-09-29) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$ 

Installieren Sie die Software, indem Sie den folgenden Befehl in der VM ausführen:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Erwartete Konsolenausgabe:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
Get:4 file:/etc/apt/mirrors/debian-security.list Mirrorlist [39 B]
Hit:7 https://packages.cloud.google.com/apt google-compute-engine-bookworm-stable InRelease
Get:8 https://packages.cloud.google.com/apt cloud-sdk-bookworm InRelease [1652 B]
Get:2 https://deb.debian.org/debian bookworm InRelease [151 kB]
Get:3 https://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/15/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (15+248) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u7) ...

Verbindung zur AlloyDB-Instanz herstellen

Stellen Sie mit psql eine Verbindung zur primären Instanz von der VM aus her.

Fahren Sie mit der geöffneten SSH-Sitzung zur VM fort. Wenn die Verbindung getrennt wurde, stellen Sie sie mit demselben Befehl wie oben wieder her.

Verwenden Sie das zuvor notierte $PGASSWORD und den Clusternamen, um von der GCE-VM aus eine Verbindung zu AlloyDB herzustellen:

export PGPASSWORD=<Noted password>

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Erwartete Konsolenausgabe:

student@instance-1:~$ PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (15.13 (Debian 15.13-0+deb12u1), server 16.8)
WARNING: psql major version 15, server major version 16.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

Beenden Sie die psql-Sitzung, ohne die SSH-Verbindung zu trennen:

exit

Erwartete Konsolenausgabe:

postgres=> exit
student@instance-1:~$ 

6. Datenbank initialisieren

Wir verwenden unsere Client-VM als Plattform, um unsere Datenbank mit Daten zu füllen und unsere Anwendung zu hosten. Als Erstes müssen Sie eine Datenbank erstellen und mit Daten füllen.

Datenbank erstellen

Erstellen Sie eine Datenbank mit dem Namen „assistantdemo“.

Führen Sie in der GCE-VM-Sitzung Folgendes aus:

Hinweis:Wenn Ihre SSH-Sitzung beendet wurde, müssen Sie Ihre Umgebungsvariablen zurücksetzen, z. B.:

export PGPASSWORD=<The noted AlloyDB password>

export REGION=us-central1

export ADBCLUSTER=alloydb-aip-01

export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"  

Erwartete Konsolenausgabe:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"
CREATE DATABASE
student@instance-1:~$  

Python-Umgebung vorbereiten

Als Nächstes verwenden wir vorbereitete Python-Skripts aus dem GitHub-Repository. Dazu müssen wir aber zuerst die erforderliche Software installieren.

Führen Sie auf der GCE-VM Folgendes aus:

sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

Erwartete Konsolenausgabe:

student@instance-1:~$ sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl
Suggested packages:
  git-daemon-run | git-daemon-sysvinit git-doc git-email git-gui gitk gitweb git-cvs git-mediawiki git-svn ed diffutils-doc
The following NEW packages will be installed:
  git git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl python3.11-venv
0 upgraded, 9 newly installed, 0 to remove and 2 not upgraded.
Need to get 12.4 MB of archives.
After this operation, 52.2 MB of additional disk space will be used.
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
...redacted...
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 23.0.1
    Uninstalling pip-23.0.1:
      Successfully uninstalled pip-23.0.1
Successfully installed pip-24.0
(.venv) student@instance-1:~$

Python-Version prüfen

Führen Sie auf der GCE-VM Folgendes aus:

python -V

Erwartete Konsolenausgabe:

(.venv) student@instance-1:~$ python -V
Python 3.11.2
(.venv) student@instance-1:~$ 

MCP-Toolbox lokal installieren

Die MCP-Toolbox für Datenbanken (im weiteren Text als MCP-Toolbox oder Toolbox bezeichnet) ist ein Open-Source-MCP-Server, der mit verschiedenen Datenquellen funktioniert. Sie können Tools schneller entwickeln, da eine Abstraktionsebene für verschiedene Datenquellen bereitgestellt wird und Funktionen wie Authentifizierung und Verbindungspooling hinzugefügt werden. Hier finden Sie eine Übersicht über alle Funktionen.

Wir verwenden die MCP-Toolbox, um unser Beispieldataset zu initialisieren und später als MCP-Server zu verwenden, um Datenquellenanfragen von unserer Anwendung während des RAG-Ablaufs (Retrieval Augmented Generation) zu verarbeiten.

Wir installieren die MCP-Toolbox lokal, um die Datenbank „assistantdemo“ zu füllen.

Führen Sie auf der GCE-VM Folgendes aus:

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

Erwartete Konsolenausgabe:

(.venv) student@instance-1:~$ export VERSION=0.16.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  133M  100  133M    0     0   158M      0 --:--:-- --:--:-- --:--:--  158M

Toolbox für die Dateninitialisierung ausführen

Führen Sie auf der GCE-VM Folgendes aus:

Hinweis:Wenn Ihre SSH-Sitzung aufgrund von Inaktivität oder aus einem anderen Grund beendet wurde, müssen Sie Ihre Umgebungsvariablen festlegen, z. B.:

export PGPASSWORD=<Noted password>

REGION=us-central1

ADBCLUSTER=alloydb-aip-01

INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

Umgebungsvariablen für die Datenbankpopulation exportieren:

export ALLOYDB_POSTGRES_PROJECT=$(gcloud config get-value project)
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"

Starten Sie die Toolbox für die Datenbankinitialisierung. Dadurch wird der Prozess lokal gestartet. So können Sie nahtlos eine Verbindung zur Zieldatenbank in AlloyDB herstellen, um sie mit Beispieldaten zu füllen.

./toolbox --prebuilt alloydb-postgres

Erwartete Konsolenausgabe. In der letzten Zeile der Ausgabe sollte „Server ready to serve!“ angezeigt werden:

student@instance-1:~$ cexport ALLOYDB_POSTGRES_PROJECT=$PROJECT_ID
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"
student@instance-1:~$ ./toolbox --prebuilt alloydb-postgres
2025-09-02T18:30:58.957655886Z INFO "Using prebuilt tool configuration for alloydb-postgres" 
2025-09-02T18:30:59.507306664Z INFO "Initialized 1 sources." 
2025-09-02T18:30:59.50748379Z INFO "Initialized 0 authServices." 
2025-09-02T18:30:59.507618807Z INFO "Initialized 2 tools." 
2025-09-02T18:30:59.507726704Z INFO "Initialized 2 toolsets." 
2025-09-02T18:30:59.508258894Z INFO "Server ready to serve!" 

Schließen Sie diesen Tab von Cloud Shell erst, wenn die Datenübertragung abgeschlossen ist.

Datenbank füllen

Öffnen Sie oben einen weiteren Cloud Shell-Tab, indem Sie auf das Pluszeichen (+) klicken.

Stellen Sie eine Verbindung zur VM instance-1 her:

gcloud compute ssh instance-1 --zone=us-central1-a

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Linux instance-1 6.1.0-37-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.140-1 (2025-05-22) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Sep  2 21:44:07 2025 from 35.229.111.9
student@instance-1:~$ 

Klonen Sie das GitHub-Repository mit dem Code für den Abrufdienst und die Beispielanwendung.

Führen Sie auf der GCE-VM Folgendes aus:

git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git

Erwartete Konsolenausgabe:

student@instance-1:~$ git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git
Cloning into 'cymbal-air-toolbox-demo'...
remote: Enumerating objects: 3481, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 3481 (delta 16), reused 7 (delta 5), pack-reused 3434 (from 3)
Receiving objects: 100% (3481/3481), 57.96 MiB | 6.04 MiB/s, done.
Resolving deltas: 100% (2549/2549), done.
student@instance-1:~

Achten Sie darauf, ob Fehler auftreten.

Python-Umgebung vorbereiten und erforderliche Pakete installieren:

source .venv/bin/activate
cd cymbal-air-toolbox-demo
pip install -r requirements.txt

Legen Sie den Python-Pfad auf den Stammordner des Repositorys fest und führen Sie das Skript aus, um die Datenbank mit dem Beispiel-Dataset zu füllen. Mit dem ersten Befehl wird unserer Umgebung ein Pfad zu unseren Python-Modulen hinzugefügt. Mit dem zweiten Befehl wird unsere Datenbank mit den Daten gefüllt.

export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py

Erwartete Konsolenausgabe(redigiert). Am Ende sollte „database init done“ (Datenbankinitialisierung abgeschlossen) angezeigt werden:

student@instance-1:~$ source .venv/bin/activate
(.venv) student@instance-1:~$ 
(.venv) student@instance-1:~$ cd cymbal-air-toolbox-demo/
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ pip install -r requirements.txt
python run_database_init.py
Collecting fastapi==0.115.0 (from -r requirements.txt (line 1))
  Downloading fastapi-0.115.0-py3-none-any.whl.metadata (27 kB)
Collecting google-auth==2.40.3 (from -r requirements.txt (line 2))
  Downloading google_auth-2.40.3-py2.py3-none-any.whl.metadata (6.2 kB)
Collecting google-cloud-aiplatform==1.97.0 (from google-cloud-aiplatform[evaluation]==1.97.0->-r requirements.txt (line 3))
  Downloading google_cloud_aiplatform-1.97.0-py2.py3-none-any.whl.metadata (36 kB)
Collecting itsdangerous==2.2.0 (from -r requirements.txt (line 4))
  Downloading itsdangerous-2.2.0-py3-none-any.whl.metadata (1.9 kB)
Collecting jinja2==3.1.5 (from -r requirements.txt (line 5))
  Downloading jinja2-3.1.5-py3-none-any.whl.metadata (2.6 kB)
Collecting langchain-community==0.3.25 (from -r requirements.txt (line 6))
  Downloading langchain_community-0.3.25-py3-none-any.whl.metadata (2.9 kB)
Collecting langchain==0.3.25 (from -r requirements.txt (line 7))
...

(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ 
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py
Airports table initialized
Amenities table initialized
Flights table initialized
Tickets table initialized
Policies table initialized
database init done.
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ 

Sie können diesen Tab jetzt schließen.

Führen Sie in der VM-Sitzung Folgendes aus:

exit

Drücken Sie in der Cloud Shell-Sitzung Strg+D oder führen Sie Folgendes aus :

exit

Drücken Sie auf dem ersten Tab mit der laufenden MCP Toolbox Strg+C, um die Toolbox-Sitzung zu beenden.

Die Datenbank wurde mit Beispieldaten für die Anwendung gefüllt.

Sie können dies überprüfen, indem Sie eine Verbindung zur Datenbank herstellen und die Anzahl der Zeilen in der Tabelle „airports“ prüfen. Sie können das psql-Dienstprogramm wie zuvor oder AlloyDB Studio verwenden . So können Sie das mit psql prüfen:

Führen Sie in der SSH-Sitzung zur VM „instance-1“ Folgendes aus:

export PGPASSWORD=<Noted AlloyDB password>

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"  

Erwartete Konsolenausgabe:

student@instance-1:~$ REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"
 count 
-------
  7698
(1 row)

Die Datenbank ist bereit und wir können mit der Bereitstellung der MCP-Toolbox fortfahren.

7. MCP Toolbox in Cloud Run bereitstellen

Jetzt können wir die MCP Toolbox in Cloud Run bereitstellen. Es gibt verschiedene Möglichkeiten, die MCP-Toolbox bereitzustellen. Am einfachsten ist es, das Tool über die Befehlszeile auszuführen. Wenn wir es jedoch als skalierbaren und zuverlässigen Dienst nutzen möchten, ist Cloud Run die bessere Lösung.

Client-ID vorbereiten

Um die Buchungsfunktionen der Anwendung nutzen zu können, müssen wir eine OAuth 2.0-Client-ID mit der Cloud Console vorbereiten. Ohne diese können wir uns nicht mit unseren Google-Anmeldedaten in der App anmelden, um eine Buchung vorzunehmen und die Buchung in der Datenbank zu speichern.

Rufen Sie in der Cloud Console „APIs & Dienste“ auf und klicken Sie auf „OAuth-Zustimmungsbildschirm“. Hier ist ein Link zur Seite. Dadurch wird die OAuth-Übersichtsseite geöffnet. Klicken Sie dort auf „Get Started“ (Jetzt starten).

Auf der nächsten Seite geben wir den Anwendungsnamen und die E‑Mail-Adresse für den Nutzersupport an und klicken auf „Weiter“.

Wählen Sie auf dem nächsten Bildschirm „Intern“ für Ihre Anwendung aus und klicken Sie noch einmal auf „Weiter“.

Geben Sie dann noch einmal die Kontakt-E-Mail-Adresse ein und klicken Sie auf „Weiter“.

Anschließend stimmen wir den Richtlinien für Google API-Dienste zu und klicken auf die Schaltfläche „Erstellen“.

Dadurch gelangen wir auf die Seite, auf der wir einen OAuth-Client erstellen können.

Wählen Sie auf dem Bildschirm „Webanwendung“ aus dem Drop-down-Menü aus, geben Sie „Cymbal Air“ als Anwendung ein und klicken Sie auf die Schaltfläche „URI hinzufügen“.

Die URIs stellen vertrauenswürdige Quellen für die Anwendung dar und hängen davon ab, von wo aus Sie auf die Anwendung zugreifen möchten. Wir haben „http://localhost:8081“ als autorisierte URI und „http://localhost:8081/login/google“ als Weiterleitungs-URI angegeben. Diese Werte funktionieren, wenn Sie in Ihrem Browser „http://localhost:8081“ als URI für die Verbindung eingeben. Das ist beispielsweise der Fall, wenn Sie über einen SSH-Tunnel von Ihrem Computer aus eine Verbindung herstellen. Ich zeige Ihnen später, wie das geht.

Nachdem Sie auf die Schaltfläche „Erstellen“ geklickt haben, wird ein Pop-up-Fenster mit den Anmeldedaten Ihres Kunden angezeigt. Die Anmeldedaten werden im System aufgezeichnet. Sie können die Client-ID jederzeit kopieren, um sie beim Starten Ihrer Anwendung zu verwenden.

Später erfahren Sie, wo Sie diese Client-ID angeben müssen.

Dienstkonto erstellen

Wir benötigen ein dediziertes Dienstkonto für unseren Cloud Run-Dienst mit allen erforderlichen Berechtigungen. Für unseren Dienst benötigen wir Zugriff auf AlloyDB und Cloud Secret Manager. Als Namen für das Dienstkonto verwenden wir „toolbox-identity“.

Öffnen Sie oben einen weiteren Cloud Shell-Tab, indem Sie auf das Pluszeichen (+) klicken.

Führen Sie im neuen Cloud Shell-Tab Folgendes aus:

export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Achten Sie darauf, ob Fehler auftreten. Mit dem Befehl soll ein Dienstkonto für den Cloud Run-Dienst erstellt und Berechtigungen für die Arbeit mit Secret Manager, der Datenbank und Vertex AI gewährt werden.

Schließen Sie den Tab, indem Sie entweder Strg + D drücken oder den Befehl „exit“ auf dem Tab ausführen:

exit

MCP-Toolbox-Konfiguration vorbereiten

Konfigurationsdatei für die MCP Toolbox vorbereiten. Informationen zu allen Konfigurationsoptionen finden Sie in der Dokumentation. Hier verwenden wir jedoch die Beispieldatei „tools.yaml“ und ersetzen einige Werte wie Cluster- und Instanzname, AlloyDB-Passwort und Projekt-ID durch unsere tatsächlichen Werte.

AlloyDB-Passwort exportieren:

export PGPASSWORD=<noted AlloyDB password>

Exportieren Sie die Client-ID, die wir im vorherigen Schritt vorbereitet haben:

export CLIENT_ID=<noted OAuth 2.0 client ID for our application>

Konfigurationsdatei vorbereiten

PROJECT_ID=$(gcloud config get-value project)
ADBCLUSTER=alloydb-aip-01
sed -e "s/project: retrieval-app-testing/project: $(gcloud config get-value project)/g" \
-e "s/cluster: my-alloydb-cluster/cluster: $ADBCLUSTER/g" \
-e "s/instance: my-alloydb-instance/instance: $ADBCLUSTER-pr/g" \
-e "s/password: postgres/password: $PGPASSWORD\\n    ipType: private/g" \
-e "s/^ *clientId: .*/    clientId: $CLIENT_ID/g" \
cymbal-air-toolbox-demo/tools.yaml >~/tools.yaml

Wenn Sie sich den Dateibereich ansehen, in dem die Zieldatenquelle definiert ist, sehen Sie, dass wir auch eine Zeile zum Verwenden einer privaten IP-Adresse für die Verbindung hinzugefügt haben.

sources:
  my-pg-instance:
    kind: alloydb-postgres
    project: gleb-test-short-003-471020
    region: us-central1
    cluster: alloydb-aip-01
    instance: alloydb-aip-01-pr
    database: assistantdemo
    user: postgres
    password: L23F...
    ipType: private
authServices:
  my_google_service:
    kind: google
    clientId: 96828*******-***********.apps.googleusercontent.com

Erstellen Sie ein Secret mit der tools.yaml-Konfiguration als Quelle.

Führen Sie in der SSH-Konsole der VM Folgendes aus:

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

Erwartete Konsolenausgabe:

student@instance-1:~$ gcloud secrets create tools --data-file=tools.yaml
Created version [1] of the secret [tools].

MCP Toolbox als Cloud Run-Dienst bereitstellen

Jetzt ist alles bereit, um die MCP Toolbox als Dienst in Cloud Run bereitzustellen. Für lokale Tests können Sie „./toolbox –tools-file=./tools.yaml“ ausführen. Wenn die Anwendung jedoch in der Cloud ausgeführt werden soll, ist die Bereitstellung in Cloud Run viel sinnvoller.

Führen Sie in der VM-SSH-Sitzung den folgenden Befehl aus:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated

Erwartete Konsolenausgabe:

student@instance-1:~$ export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated
Deploying container to Cloud Run service [toolbox] in project [gleb-test-short-002-470613] region [us-central1]
✓ Deploying new service... Done.                                                                                                                                                                                                
  ✓ Creating Revision...                                                                                                                                                                                                        
  ✓ Routing traffic...                                                                                                                                                                                                          
Done.                                                                                                                                                                                                                           
Service [toolbox] revision [toolbox-00001-l9c] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-868691532292.us-central1.run.app

student@instance-1:~$

Dienst bestätigen

Jetzt können wir prüfen, ob der Dienst aktiv ist und wir auf den Endpunkt zugreifen können. Wir verwenden das gcloud-Tool, um den Endpunkt des Abrufdienstes und das Authentifizierungstoken abzurufen. Alternativ können Sie den Dienst-URI in der Cloud Console prüfen.

Sie können den Wert kopieren und im curl-Befehl den Teil "$(gcloud run services list –filter="(toolbox)" –format="value(URL)" ersetzen .

So rufen Sie die URL dynamisch über die Befehlszeile ab:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Erwartete Konsolenausgabe:

student@instance-1:~$ curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")
🧰 Hello, World! 🧰student@instance-1:~$

Wenn wir die Nachricht „Hello World“ sehen, ist der Dienst verfügbar und verarbeitet Anfragen.

8. Beispielanwendung bereitstellen

Nachdem der Abrufdienst nun ausgeführt wird, können wir eine Beispielanwendung bereitstellen. Die Anwendung ist ein Online-Flughafenassistent, der Ihnen Informationen zu Flügen und Flughäfen geben und sogar einen Flug auf Grundlage der Flug- und Flughafendaten aus unserer Datenbank buchen kann.

Die Anwendung kann lokal, auf einer VM in der Cloud oder in einem anderen Dienst wie Cloud Run oder Kubernetes bereitgestellt werden. Hier zeigen wir, wie Sie die Anwendung zuerst auf der VM bereitstellen.

Umgebung vorbereiten

Wir arbeiten weiterhin an unserer VM und verwenden dazu dieselbe SSH-Sitzung. Um unsere Anwendung auszuführen, benötigen wir einige Python-Module. Wir haben sie bereits hinzugefügt, als wir unsere Datenbank initialisiert haben. Wechseln wir nun zu unserer virtuellen Python-Umgebung und ändern wir unseren Standort in das App-Verzeichnis.

Führen Sie in der VM-SSH-Sitzung den folgenden Befehl aus:

source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo

Erwartete Ausgabe (redigiert):

student@instance-1:~$ source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$

Assistant-Anwendung ausführen

Bevor wir die Anwendung starten, müssen wir einige Umgebungsvariablen einrichten. Für die grundlegende Funktionalität der Anwendung, z. B. die Abfrage von Flügen und Flughafeneinrichtungen, ist nur TOOLBOX_URL erforderlich, die auf den Abrufdienst verweist. Wir können sie mit dem gcloud-Befehl abrufen .

Führen Sie in der VM-SSH-Sitzung den folgenden Befehl aus:

export TOOLBOX_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Erwartete Ausgabe (redigiert):

student@instance-1:~/cymbal-air-toolbox-demo$ export BASE_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Wenn Sie erweiterte Funktionen der Anwendung wie das Buchen und Ändern von Flügen nutzen möchten, müssen Sie sich mit Ihrem Google-Konto in der Anwendung anmelden. Dazu müssen Sie die Umgebungsvariable CLIENT_ID mit der OAuth-Client-ID aus dem Abschnitt „Client-ID vorbereiten“ angeben:

export CLIENT_ID=215....apps.googleusercontent.com

Erwartete Ausgabe (redigiert):

student@instance-1:~/cymbal-air-toolbox-demo$ export CLIENT_ID=215....apps.googleusercontent.com

Jetzt können wir unsere Anwendung ausführen:

python run_app.py

Erwartete Ausgabe:

student@instance-1:~/cymbal-air-toolbox-demo/llm_demo$ python run_app.py
INFO:     Started server process [2900]
INFO:     Waiting for application startup.
Loading application...
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

Verbindung zur Anwendung herstellen

Es gibt verschiedene Möglichkeiten, eine Verbindung zu der Anwendung herzustellen, die auf der VM ausgeführt wird. Sie können beispielsweise Port 8081 auf der VM mithilfe von Firewallregeln in der VPC öffnen oder einen Load Balancer mit einer öffentlichen IP-Adresse erstellen. Hier wird ein SSH-Tunnel zur VM verwendet, der den lokalen Port 8080 in den VM-Port 8081 übersetzt.

Verbindung von einem lokalen Computer herstellen

Wenn wir eine Verbindung von einem lokalen Computer aus herstellen möchten, müssen wir einen SSH-Tunnel ausführen. Dies kann mit gcloud compute ssh erfolgen:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8081:localhost:8081

Erwartete Ausgabe:

student-macbookpro:~ student$ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
Warning: Permanently added 'compute.7064281075337367021' (ED25519) to the list of known hosts.
Linux instance-1.us-central1-c.c.gleb-test-001.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Jetzt können wir den Browser öffnen und über http://localhost:8081 eine Verbindung zu unserer Anwendung herstellen. Der Anwendungsbildschirm sollte angezeigt werden.

Verbindung über Cloud Shell herstellen

Alternativ können wir Google Cloud Shell verwenden, um eine Verbindung herzustellen. Öffnen Sie oben einen weiteren Cloud Shell-Tab, indem Sie auf das Pluszeichen (+) klicken.

Rufen Sie auf dem neuen Tab den Ursprungs- und den Weiterleitungs-URI für Ihren Webclient ab, indem Sie den gcloud-Befehl ausführen:

echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"

Hier ist die erwartete Ausgabe:

student@cloudshell:~ echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"
origin:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev
redirect:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev/login/google

Verwenden Sie den Ursprung und die Weiterleitung von URIs als Autorisierte JavaScript-Quellen und Autorisierte Weiterleitungs-URIs für die Anmeldedaten, die im Kapitel „Client-ID vorbereiten“ erstellt wurden. Ersetzen oder ergänzen Sie die ursprünglich angegebenen http://localhost:8080-Werte.

Klicken Sie auf der Seite „OAuth 2.0-Client-IDs“ auf „Cymbal Air“.

Geben Sie die Ursprungs- und Weiterleitungs-URIs für Cloud Shell ein und klicken Sie auf „Speichern“.

Starten Sie im neuen Cloud Shell-Tab den Tunnel zu Ihrer VM, indem Sie den gcloud-Befehl ausführen:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081

Wenn der Fehler „Cannot assign requested address“ (Angeforderte Adresse kann nicht zugewiesen werden) angezeigt wird, können Sie ihn ignorieren.

Hier ist die erwartete Ausgabe:

student@cloudshell:~ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
bind [::1]:8081: Cannot assign requested address
inux instance-1.us-central1-a.c.gleb-codelive-01.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Sat May 25 19:15:46 2024 from 35.243.235.73
student@instance-1:~$

Dadurch wird Port 8080 in Ihrer Cloud Shell geöffnet, der für die „Webvorschau“ verwendet werden kann.

Klicken Sie in Cloud Shell oben rechts auf die Schaltfläche „Webvorschau“ und wählen Sie im Drop-down-Menü „Vorschau auf Port 8080“ aus.

Daraufhin wird in Ihrem Webbrowser ein neuer Tab mit der Anwendungsoberfläche geöffnet. Sie sollten die Seite „Cymbal Air Customer Service Assistant“ sehen.

In der Anwendung anmelden

Wenn alles eingerichtet ist und Ihre Anwendung geöffnet ist, können wir oben rechts auf dem Anwendungsbildschirm auf die Schaltfläche „Anmelden“ klicken, um unsere Anmeldedaten anzugeben. Das ist optional und nur erforderlich, wenn Sie die Buchungsfunktionen der Anwendung testen möchten.

Daraufhin wird ein Pop-up-Fenster geöffnet, in dem wir unsere Anmeldedaten auswählen können.

Nach der Anmeldung ist die Anwendung bereit und Sie können Ihre Anfragen in das Feld unten im Fenster eingeben.

In dieser Demo wird der Kundenservice-Assistent von Cymbal Air vorgestellt. Cymbal Air ist eine fiktive Fluggesellschaft. Der Assistent ist ein KI-Chatbot, der Reisenden hilft, Flüge zu verwalten und Informationen zum Drehkreuz von Cymbal Air am internationalen Flughafen San Francisco (SFO) abzurufen.

Ohne Anmeldung (ohne CLIENT_ID) kann sie Nutzerfragen wie die folgenden beantworten:

Wann ist der nächste Flug nach Denver?

Gibt es in der Nähe von Gate C28 Luxusgeschäfte?

Wo kann ich in der Nähe von Gate A6 einen Kaffee bekommen?

Wo kann ich ein Geschenk kaufen?

Suche einen Flug von SFO nach Denver, der heute abfliegt.

Wenn Sie in der App angemeldet sind, können Sie andere Funktionen ausprobieren, z. B. Flüge buchen oder prüfen, ob der Ihnen zugewiesene Sitzplatz ein Fenster- oder Gangplatz ist.

Die Anwendung nutzt die neuesten Foundation Models von Google, um Antworten zu generieren und sie mit Informationen zu Flügen und Flughafeneinrichtungen aus der operativen AlloyDB-Datenbank zu ergänzen. Weitere Informationen zu dieser Demoanwendung finden Sie auf der GitHub-Seite des Projekts.

9. Umgebung bereinigen

Wenn alle Aufgaben erledigt sind, können wir unsere Umgebung aufräumen.

Cloud Run-Dienst löschen

Führen Sie in Cloud Shell Folgendes aus:

gcloud run services delete toolbox --region us-central1

Erwartete Konsolenausgabe:

student@cloudshell:~ (gleb-test-short-004)$ gcloud run services delete retrieval-service --region us-central1
Service [retrieval-service] will be deleted.

Do you want to continue (Y/n)?  Y

Deleting [retrieval-service]...done.                                                                                                                                                                                                                 
Deleted service [retrieval-service].

Dienstkonto für Cloud Run-Dienst löschen

Führen Sie in Cloud Shell Folgendes aus:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet

Erwartete Konsolenausgabe:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-222]
student@cloudshell:~ (gleb-test-short-004)$ gcloud iam service-accounts delete retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$

Wenn Sie das Lab abgeschlossen haben, löschen Sie die AlloyDB-Instanzen und den Cluster.

AlloyDB-Cluster und alle Instanzen löschen

Wenn Sie die Testversion von AlloyDB verwendet haben. Löschen Sie den Testcluster nicht, wenn Sie planen, andere Labs und Ressourcen damit zu testen. Sie können keinen weiteren Testcluster im selben Projekt erstellen.

Der Cluster wird mit der Option „force“ zerstört, wodurch auch alle Instanzen gelöscht werden, die zum Cluster gehören.

Definieren Sie in Cloud Shell die Projekt- und Umgebungsvariablen, wenn die Verbindung getrennt wurde und alle vorherigen Einstellungen verloren gegangen sind:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

Löschen Sie den Cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Hinweis:Die Ausführung des Befehls dauert 3 bis 5 Minuten.

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.   

AlloyDB-Sicherungen löschen

Löschen Sie alle AlloyDB-Sicherungen für den Cluster:

Hinweis:Mit dem Befehl werden alle Datensicherungen für den Cluster mit dem in der Umgebungsvariable angegebenen Namen gelöscht.

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.                                                                                                                                                                                                                                                            

Jetzt können wir unsere VM löschen.

GCE-VM löschen

Führen Sie in Cloud Shell Folgendes aus:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted 

Dienstkonto für GCE-VM und Abrufdienst löschen

Führen Sie in Cloud Shell Folgendes aus:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet

Erwartete Konsolenausgabe:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet
Your active configuration is: [cloudshell-222]
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$ 

10. Glückwunsch

Herzlichen Glückwunsch zum Abschluss des Codelabs.

Behandelte Themen

• AlloyDB-Cluster bereitstellen
• Verbindung zu AlloyDB herstellen
• MCP Toolbox Service konfigurieren und bereitstellen
• Beispielanwendung mit dem bereitgestellten Dienst bereitstellen

11. Umfrage

Ausgabe:

Wie werden Sie diese Anleitung verwenden?

Nur lesen Lesen und Übungen machen