Aplikacja AlloyDB Agentic RAG z zestawem narzędzi MCP

1. Wprowadzenie

Z tego ćwiczenia w Codelabs dowiesz się, jak utworzyć klaster AlloyDB, wdrożyć zestaw narzędzi MCP i skonfigurować go tak, aby używał AlloyDB jako źródła danych. Następnie utworzysz przykładową interaktywną aplikację RAG, która będzie wykorzystywać wdrożony zestaw narzędzi do uzasadniania swoich żądań.

Więcej informacji o MCP Toolbox znajdziesz na stronie dokumentacji, a przykładową aplikację Cymbal Air – tutaj.

Ten moduł należy do kolekcji modułów poświęconych funkcjom AlloyDB AI. Więcej informacji znajdziesz na stronie AlloyDB AI w dokumentacji. Możesz też zobaczyć inne laboratoria.

Wymagania wstępne

• Podstawowa znajomość konsoli Google Cloud
• Podstawowe umiejętności w zakresie interfejsu wiersza poleceń i Cloud Shell w Google Cloud

Czego się nauczysz

• Wdrażanie klastra AlloyDB z integracją z Vertex AI
• Jak połączyć się z AlloyDB
• Jak skonfigurować i wdrożyć usługę MCP Toolbox
• Jak wdrożyć przykładową aplikację za pomocą wdrożonej usługi

Czego potrzebujesz

• Konto Google Cloud i projekt Google Cloud
• przeglądarka, np. Chrome;

2. Konfiguracja i wymagania

Samodzielne konfigurowanie środowiska

1. Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz utworzyć je.

• Nazwa projektu to wyświetlana nazwa uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Zawsze możesz ją zaktualizować.
• Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i nie można go zmienić po ustawieniu. Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się tym przejmować. W większości ćwiczeń z programowania musisz odwoływać się do identyfikatora projektu (zwykle oznaczanego jako PROJECT_ID). Jeśli wygenerowany identyfikator Ci się nie podoba, możesz wygenerować inny losowy identyfikator. Możesz też spróbować własnej nazwy i sprawdzić, czy jest dostępna. Po tym kroku nie można go zmienić i pozostaje on taki przez cały czas trwania projektu.
• Warto wiedzieć, że istnieje trzecia wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.

Ostrzeżenie: identyfikator projektu jest globalnie niepowtarzalny i po jego wybraniu nie może być używany przez nikogo innego. Jesteś jedynym użytkownikiem tego identyfikatora. Nawet po usunięciu projektu nie można ponownie użyć jego identyfikatora.

Uwaga: jeśli używasz konta Gmail, możesz pozostawić domyślną lokalizację ustawioną na Brak organizacji. Jeśli używasz konta Google Workspace, wybierz lokalizację odpowiednią dla Twojej organizacji.

2. Następnie musisz włączyć płatności w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Wykonanie tego laboratorium nie będzie kosztować dużo, a może nawet nic. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub projekt. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

Uruchamianie Cloud Shell

Google Cloud można obsługiwać zdalnie z laptopa, ale w tym module praktycznym będziesz używać Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.

W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:

Udostępnienie środowiska i połączenie się z nim może zająć tylko kilka chwil. Po zakończeniu powinno wyświetlić się coś takiego:

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i uwierzytelniania. Wszystkie zadania w tym laboratorium możesz wykonać w przeglądarce. Nie musisz niczego instalować.

3. Zanim zaczniesz

Włącz API

Dane wyjściowe:

Pamiętaj, że jeśli nie korzystasz z poziomu promocyjnego, włączenie niektórych zasobów wiąże się z kosztami. W normalnych okolicznościach, jeśli po zakończeniu modułu wszystkie zasoby zostaną zniszczone, koszt wszystkich zasobów nie przekroczy 5 USD. Sprawdź rozliczenia i upewnij się, że ta opcja jest dla Ciebie odpowiednia.

W Cloud Shell sprawdź, czy identyfikator projektu jest skonfigurowany:

Identyfikator projektu jest zwykle wyświetlany w nawiasach w wierszu poleceń w Cloud Shell, jak pokazano na ilustracji:

gcloud config set project [YOUR-PROJECT-ID]

Następnie ustaw zmienną środowiskową PROJECT_ID na identyfikator projektu Google Cloud:

PROJECT_ID=$(gcloud config get-value project)

Włącz wszystkie niezbędne usługi:

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

Oczekiwane dane wyjściowe

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. Wdrażanie klastra AlloyDB

Utwórz klaster AlloyDB i instancję główną. Poniższa procedura opisuje, jak utworzyć klaster i instancję AlloyDB za pomocą pakietu Google Cloud SDK. Jeśli wolisz korzystać z konsoli, zapoznaj się z dokumentacją tutaj.

Przed utworzeniem klastra AlloyDB potrzebujemy dostępnego zakresu prywatnych adresów IP w sieci VPC, który będzie używany przez przyszłą instancję AlloyDB. Jeśli go nie mamy, musimy go utworzyć i przypisać do użytku przez wewnętrzne usługi Google. Dopiero wtedy będziemy mogli utworzyć klaster i instancję.

Tworzenie prywatnego zakresu adresów IP

Uwaga: ten krok jest wymagany tylko wtedy, gdy nie masz jeszcze nieużywanego zakresu prywatnych adresów IP przypisanego do pracy z usługami wewnętrznymi Google.

Musimy skonfigurować prywatny dostęp do usług w naszej sieci VPC dla AlloyDB. Zakładamy, że w projekcie mamy sieć VPC „default”, która będzie używana do wszystkich działań.

Utwórz zakres prywatnych adresów IP:

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

Utwórz połączenie prywatne, używając przydzielonego zakresu adresów IP:

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

Uwaga: wykonanie drugiego polecenia zajmuje kilka minut.

Oczekiwane dane wyjściowe konsoli:

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)$

Tworzenie klastra AlloyDB

W tej sekcji utworzymy klaster AlloyDB w regionie us-central1.

Określ hasło użytkownika postgres. Możesz zdefiniować własne hasło lub użyć funkcji losowej, aby je wygenerować.

export PGPASSWORD=`openssl rand -hex 12`

Oczekiwane dane wyjściowe konsoli:

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

Zapisz hasło do PostgreSQL, aby użyć go w przyszłości.

echo $PGPASSWORD

To hasło będzie Ci potrzebne w przyszłości do połączenia z instancją jako użytkownik postgres. Proponuję zapisać go lub skopiować w inne miejsce, aby móc go później użyć.

Oczekiwane dane wyjściowe konsoli:

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

Tworzenie bezpłatnego klastra próbnego

Jeśli nie używasz jeszcze AlloyDB, możesz utworzyć bezpłatny klaster próbny:

Określ region i nazwę klastra AlloyDB. Użyjemy regionu us-central1 i nazwy klastra alloydb-aip-01:

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

Uruchom polecenie, aby utworzyć klaster:

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

Oczekiwane dane wyjściowe konsoli:

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.                                                                                                                                                                                                                                                           

Utwórz instancję główną AlloyDB dla klastra w tej samej sesji Cloud Shell. Jeśli połączenie zostanie przerwane, musisz ponownie zdefiniować zmienne środowiskowe regionu i nazwy klastra.

Uwaga: utworzenie instancji zajmuje zwykle 6–10 minut.

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

Oczekiwane dane wyjściowe konsoli:

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.                                                                                                                                                                                                                                                     

Tworzenie klastra AlloyDB Standard

Jeśli nie jest to Twój pierwszy klaster AlloyDB w projekcie, utwórz klaster standardowy.

Określ region i nazwę klastra AlloyDB. Użyjemy regionu us-central1 i nazwy klastra alloydb-aip-01:

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

Uruchom polecenie, aby utworzyć klaster:

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

Oczekiwane dane wyjściowe konsoli:

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.                                                                                                                                                                                                                                                           

Utwórz instancję główną AlloyDB dla klastra w tej samej sesji Cloud Shell. Jeśli połączenie zostanie przerwane, musisz ponownie zdefiniować zmienne środowiskowe regionu i nazwy klastra.

Uwaga: utworzenie instancji zajmuje zwykle 6–10 minut.

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

Oczekiwane dane wyjściowe konsoli:

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.                                                                                                                                                                                                                                                     

Przyznawanie AlloyDB niezbędnych uprawnień

Dodaj uprawnienia Vertex AI do agenta usługi AlloyDB.

Otwórz kolejną kartę Cloud Shell, klikając znak „+” u góry.

Na nowej karcie Cloud Shell wykonaj to polecenie:

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"

Oczekiwane dane wyjściowe konsoli:

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
 

Zamknij kartę, wpisując na niej polecenie „exit”:

exit

5. Przygotowywanie maszyny wirtualnej GCE

Jako platformy do pracy z bazą danych i wdrażania różnych części przykładowej aplikacji użyjemy maszyny wirtualnej Google Compute Engine (GCE). Korzystanie z maszyny wirtualnej zapewnia większą elastyczność w zakresie zainstalowanych komponentów i bezpośredni dostęp do prywatnego adresu IP AlloyDB na potrzeby przygotowywania danych.

Utwórz konto usługi

Ponieważ będziemy używać maszyny wirtualnej do wdrażania MCP Toolbox jako usługi oraz do wdrażania lub hostowania przykładowej aplikacji, pierwszym krokiem jest utworzenie konta usługi Google (GSA). Konto usługi Google będzie używane przez maszynę wirtualną GCE i musimy przyznać mu uprawnienia niezbędne do pracy z innymi usługami.

W Cloud Shell wykonaj to polecenie:

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

Wdrażanie maszyny wirtualnej GCE

Utwórz maszynę wirtualną GCE w tym samym regionie i sieci VPC co klaster AlloyDB.

W Cloud Shell wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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

Instalowanie klienta Postgres

Zainstaluj oprogramowanie klienta PostgreSQL na wdrożonej maszynie wirtualnej.

Połącz się z maszyną wirtualną:

Uwaga: pierwsze połączenie SSH z maszyną wirtualną może potrwać dłużej, ponieważ proces obejmuje utworzenie klucza RSA na potrzeby bezpiecznego połączenia i rozpowszechnienie publicznej części klucza w projekcie.

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

Oczekiwane dane wyjściowe konsoli:

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:~$ 

Zainstaluj oprogramowanie, uruchamiając w maszynie wirtualnej to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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

Łączenie z instancją AlloyDB

Połącz się z instancją podstawową z maszyny wirtualnej za pomocą psql.

Kontynuuj otwartą sesję SSH na maszynie wirtualnej. Jeśli połączenie zostało przerwane, połącz się ponownie za pomocą tego samego polecenia co powyżej.

Użyj zapisanego wcześniej hasła $PGASSWORD i nazwy klastra, aby połączyć się z AlloyDB z maszyny wirtualnej GCE:

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"

Oczekiwane dane wyjściowe konsoli:

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=>

Wyjdź z sesji psql, zachowując połączenie SSH:

exit

Oczekiwane dane wyjściowe konsoli:

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

6. Inicjowanie bazy danych

Użyjemy naszej maszyny wirtualnej klienta jako platformy do wypełnienia bazy danych danymi i hostowania aplikacji. Pierwszym krokiem jest utworzenie bazy danych i wypełnienie jej danymi.

Utwórz bazę danych

Utwórz bazę danych o nazwie „assistantdemo”.

W sesji maszyny wirtualnej GCE wykonaj to polecenie:

Uwaga: jeśli sesja SSH została zakończona, musisz zresetować zmienne środowiskowe, takie jak:

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"  

Oczekiwane dane wyjściowe konsoli:

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

Przygotuj środowisko Pythona

Aby kontynuować, użyjemy przygotowanych skryptów w Pythonie z repozytorium GitHub, ale zanim to zrobimy, musimy zainstalować wymagane oprogramowanie.

Na maszynie wirtualnej GCE wykonaj te czynności:

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

Oczekiwane dane wyjściowe konsoli:

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:~$

Sprawdź wersję Pythona.

Na maszynie wirtualnej GCE wykonaj te czynności:

python -V

Oczekiwane dane wyjściowe konsoli:

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

Instalowanie lokalnie Zestawu narzędzi MCP

MCP Toolbox for Databases (w dalszej części tekstu MCP Toolbox lub toolbox) to serwer MCP na licencji open source, który współpracuje z różnymi źródłami danych. Ułatwia tworzenie narzędzi, ponieważ zapewnia poziom abstrakcji dla różnych źródeł danych i dodaje funkcje takie jak uwierzytelnianie i pula połączeń. Wszystkie funkcje znajdziesz na oficjalnej stronie.

Użyjemy zestawu narzędzi MCP, aby zainicjować przykładowy zbiór danych, a później używać go jako serwera MCP do obsługiwania żądań źródeł danych z naszej aplikacji podczas procesu generowania rozszerzonego przez wyszukiwanie w zapisanych informacjach (RAG).

Zainstalujmy lokalnie zestaw narzędzi MCP, aby wypełnić bazę danych assistantdemo.

Na maszynie wirtualnej GCE wykonaj te czynności:

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

Oczekiwane dane wyjściowe konsoli:

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

Uruchomienie narzędzia Toolbox do inicjowania danych

Na maszynie wirtualnej GCE wykonaj te czynności:

Uwaga: jeśli sesja SSH została zakończona z powodu braku aktywności lub z innego powodu, musisz ustawić zmienne środowiskowe, takie jak:

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

Eksportuj zmienne środowiskowe na potrzeby wypełniania bazy danych:

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"

Uruchom narzędzia do inicjowania bazy danych. Rozpocznie on proces lokalnie, co pomoże Ci bezproblemowo połączyć się z docelową bazą danych w AlloyDB i wypełnić ją przykładowymi danymi.

./toolbox --prebuilt alloydb-postgres

Oczekiwane dane wyjściowe konsoli. W ostatnim wierszu danych wyjściowych powinien pojawić się komunikat „Server ready to serve!” (Serwer gotowy do obsługi):

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

Nie zamykaj tej karty Cloud Shell, dopóki nie zostaną wypełnione dane.

Wypełnianie bazy danych

Otwórz kolejną kartę Cloud Shell, klikając znak „+” u góry.

i połącz się z maszyną wirtualną instance-1:

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

Oczekiwane dane wyjściowe konsoli:

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:~$ 

Sklonuj repozytorium GitHub z kodem usługi pobierania i przykładowej aplikacji.

Na maszynie wirtualnej GCE wykonaj te czynności:

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

Oczekiwane dane wyjściowe konsoli:

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:~

Zwróć uwagę, czy nie ma błędów.

Przygotuj środowisko Pythona i zainstaluj wymagane pakiety:

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

Ustaw ścieżkę Pythona na folder główny repozytorium i uruchom skrypt, aby wypełnić bazę danych przykładowym zbiorem danych. Pierwsze polecenie dodaje ścieżkę do naszych modułów Pythona do środowiska, a drugie polecenie wypełnia bazę danych danymi.

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

Oczekiwane dane wyjściowe konsoli(zredagowane). Na końcu powinien pojawić się komunikat „database init done”:

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$ 

Możesz teraz zamknąć tę kartę.

W sesji maszyny wirtualnej wykonaj to polecenie:

exit

W sesji Cloud Shell naciśnij Ctrl+D lub wykonaj to polecenie :

exit

Na pierwszej karcie z uruchomionym narzędziem MCP Toolbox naciśnij Ctrl+C, aby zakończyć sesję narzędzia.

Baza danych została wypełniona przykładowymi danymi aplikacji.

Możesz to sprawdzić, łącząc się z bazą danych i sprawdzając liczbę wierszy w tabeli airports. Możesz użyć narzędzia psql, tak jak wcześniej, lub AlloyDB Studio . Aby to sprawdzić za pomocą psql:

W sesji SSH na maszynie wirtualnej instance-1 wykonaj to polecenie:

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"  

Oczekiwane dane wyjściowe konsoli:

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)

Baza danych jest gotowa i możemy przejść do wdrożenia MCP Toolbox.

7. Wdrażanie MCP Toolbox w Cloud Run

Teraz możemy wdrożyć MCP Toolbox w Cloud Run. Zestaw narzędzi MCP można wdrożyć na różne sposoby. Najprostszym sposobem jest uruchomienie go z wiersza poleceń, ale jeśli chcemy, aby działał jako skalowalna i niezawodna usługa, lepszym rozwiązaniem jest Cloud Run.

Przygotuj identyfikator klienta

Aby korzystać z funkcji rezerwacji w aplikacji, musimy przygotować identyfikator klienta OAuth 2.0 za pomocą konsoli Cloud. Bez niego nie możemy zalogować się w aplikacji za pomocą danych logowania Google, aby dokonać rezerwacji i zapisać ją w bazie danych.

W konsoli Cloud otwórz Interfejsy API i usługi i kliknij „Ekran zgody OAuth”. Oto link do strony. Otworzy się strona Przegląd OAuth, na której klikamy Rozpocznij.

Na następnej stronie podajemy nazwę aplikacji i adres e-mail dla użytkowników potrzebujących pomocy, a następnie klikamy Dalej.

Na następnym ekranie wybieramy Wewnętrzna dla naszej aplikacji i ponownie klikamy Dalej.

Następnie ponownie podajemy adres e-mail i klikamy Dalej.

Następnie akceptujemy zasady usług interfejsu API Google i klikamy przycisk Utwórz.

Przekieruje nas to na stronę, na której możemy utworzyć klienta OAuth.

Na ekranie wybierz „Aplikacja internetowa” z menu, wpisz „Cymbal Air” jako aplikację i kliknij przycisk Dodaj URI.

Identyfikatory URI reprezentują zaufane źródła aplikacji i zależą od tego, skąd próbujesz uzyskać do niej dostęp. Jako autoryzowany identyfikator URI podaliśmy „http://localhost:8081”, a jako identyfikator URI przekierowania „http://localhost:8081/login/google”. Te wartości będą działać, jeśli w przeglądarce wpiszesz „http://localhost:8081” jako URI połączenia. Na przykład podczas łączenia się z komputera przez tunel SSH. Pokażę Ci, jak to zrobić.

Po kliknięciu przycisku „Utwórz” pojawi się wyskakujące okienko z danymi logowania klienta. Dane logowania zostaną zapisane w systemie. Zawsze możesz skopiować identyfikator klienta, aby użyć go podczas uruchamiania aplikacji.

Później zobaczysz, gdzie podać ten identyfikator klienta.

Utwórz konto usługi

Potrzebujemy dedykowanego konta usługi dla naszej usługi Cloud Run ze wszystkimi wymaganymi uprawnieniami. Aby świadczyć nasze usługi, musimy mieć dostęp do AlloyDB i Cloud Secret Manager. Nazwa konta usługi, którego będziemy używać, to toolbox-identity.

Otwórz kolejną kartę Cloud Shell, klikając znak „+” u góry.

Na nowej karcie Cloud Shell wykonaj to polecenie:

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"

Zwróć uwagę, czy nie ma błędów. Polecenie ma utworzyć konto usługi dla usługi Cloud Run i przyznać uprawnienia do pracy z Secret Managerem, bazą danych i Vertex AI.

Zamknij kartę, naciskając Ctrl+D lub wykonując polecenie „exit” na karcie:

exit

Przygotowywanie konfiguracji Zestawu narzędzi MCP

Przygotuj plik konfiguracji dla zestawu narzędzi MCP. Wszystkie opcje konfiguracji znajdziesz w dokumentacji. My użyjemy przykładowego pliku tools.yaml i zastąpimy niektóre wartości, takie jak nazwa klastra i instancji, hasło AlloyDB i identyfikator projektu, naszymi rzeczywistymi wartościami.

Eksportowanie hasła AlloyDB:

export PGPASSWORD=<noted AlloyDB password>

Wyeksportuj identyfikator klienta przygotowany w poprzednim kroku:

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

Przygotuj plik konfiguracji.

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

Jeśli zajrzysz do sekcji pliku definiującej docelowe źródło danych, zobaczysz, że dodaliśmy też wiersz umożliwiający użycie prywatnego adresu IP do połączenia.

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

Utwórz klucz tajny, używając konfiguracji tools.yaml jako źródła.

W konsoli SSH maszyny wirtualnej wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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

Wdrażanie narzędzi MCP jako usługi Cloud Run

Wszystko jest teraz gotowe do wdrożenia MCP Toolbox jako usługi w Cloud Run. Do testowania lokalnego możesz użyć polecenia „./toolbox –tools-file=./tools.yaml”, ale jeśli chcesz, aby aplikacja działała w chmurze, wdrożenie w Cloud Run ma znacznie więcej sensu.

W sesji SSH maszyny wirtualnej wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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:~$

Weryfikacja usługi

Teraz możemy sprawdzić, czy usługa jest aktywna i czy mamy dostęp do punktu końcowego. Używamy narzędzia gcloud, aby uzyskać punkt końcowy usługi pobierania i token uwierzytelniania. Możesz też sprawdzić identyfikator URI usługi w konsoli Google Cloud.

Możesz skopiować wartość i zastąpić w poleceniu curl fragment "$(gcloud run services list –filter="(toolbox)" –format="value(URL)" .

Aby uzyskać adres URL dynamicznie z wiersza poleceń:

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

Oczekiwane dane wyjściowe konsoli:

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:~$

Jeśli zobaczymy komunikat „Hello World”, oznacza to, że nasza usługa działa i obsługuje żądania.

8. Wdrażanie przykładowej aplikacji

Teraz, gdy usługa pobierania działa, możemy wdrożyć przykładową aplikację. Aplikacja jest internetowym asystentem lotniskowym, który może podawać informacje o lotach i lotniskach, a nawet rezerwować loty na podstawie danych o lotach i lotniskach z naszej bazy danych.

Aplikację można wdrożyć lokalnie, na maszynie wirtualnej w chmurze lub w dowolnej innej usłudze, takiej jak Cloud Run czy Kubernetes. Najpierw pokażemy, jak wdrożyć go na maszynie wirtualnej.

Przygotuj środowisko

Nadal pracujemy na maszynie wirtualnej w ramach tej samej sesji SSH. Aby uruchomić aplikację, potrzebujemy kilku modułów Pythona. Dodaliśmy je już podczas inicjowania bazy danych. Przełączmy się na środowisko wirtualne Pythona i zmieńmy lokalizację na katalog aplikacji.

W sesji SSH maszyny wirtualnej wykonaj to polecenie:

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

Oczekiwane dane wyjściowe (z redakcją):

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

Uruchom aplikację Asystent

Zanim uruchomisz aplikację, musisz skonfigurować zmienne środowiskowe. Podstawowa funkcjonalność aplikacji, taka jak wyszukiwanie lotów i udogodnień na lotnisku, wymaga tylko parametru TOOLBOX_URL, który kieruje aplikację do usługi pobierania. Możemy go uzyskać za pomocą polecenia gcloud .

W sesji SSH maszyny wirtualnej wykonaj to polecenie:

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

Oczekiwane dane wyjściowe (z redakcją):

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

Aby korzystać z bardziej zaawansowanych funkcji aplikacji, takich jak rezerwowanie i zmienianie lotów, musimy zalogować się w niej za pomocą konta Google. W tym celu musimy podać zmienną środowiskową CLIENT_ID, używając identyfikatora klienta OAuth z rozdziału Przygotowywanie identyfikatora klienta:

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

Oczekiwane dane wyjściowe (z redakcją):

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

Teraz możemy uruchomić aplikację:

python run_app.py

Oczekiwane dane wyjściowe:

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)

Połącz się z aplikacją

Z aplikacją działającą na maszynie wirtualnej możesz połączyć się na kilka sposobów. Możesz na przykład otworzyć port 8081 na maszynie wirtualnej za pomocą reguł zapory sieciowej w sieci VPC lub utworzyć moduł równoważenia obciążenia z publicznym adresem IP. Użyjemy tunelu SSH do maszyny wirtualnej, który przetłumaczy lokalny port 8080 na port 8081 maszyny wirtualnej.

Nawiązywanie połączenia z urządzenia lokalnego

Jeśli chcemy połączyć się z maszyny lokalnej, musimy uruchomić tunel SSH. Możesz to zrobić za pomocą polecenia gcloud compute ssh:

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

Oczekiwane dane wyjściowe:

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:~$

Teraz możemy otworzyć przeglądarkę i użyć adresu http://localhost:8081, aby połączyć się z naszą aplikacją. Powinien pojawić się ekran aplikacji.

Nawiązywanie połączenia z Cloud Shell

Możemy też użyć Cloud Shell do połączenia. Otwórz kolejną kartę Cloud Shell, klikając znak „+” u góry.

Na nowej karcie uzyskaj źródło i identyfikator URI przekierowania dla klienta internetowego wykonującego polecenie gcloud:

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

Oto oczekiwane dane wyjściowe:

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

Użyj źródła i przekierowania identyfikatorów URI jako „Autoryzowane źródła JavaScript” i „Autoryzowane identyfikatory URI przekierowania” w przypadku danych logowania utworzonych w rozdziale „Przygotuj identyfikator klienta”, zastępując lub dodając pierwotnie podane wartości http://localhost:8080.

Na stronie Identyfikatory klienta OAuth 2.0 kliknij „Cymbal Air”.

Wpisz źródło i identyfikatory URI przekierowania dla Cloud Shell i kliknij przycisk Zapisz.

Na nowej karcie Cloud Shell uruchom tunel do maszyny wirtualnej, wykonując to polecenie gcloud:

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

Jeśli pojawi się błąd „Nie można przypisać żądanego adresu”, zignoruj go.

Oto oczekiwane dane wyjściowe:

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:~$

Otwiera port 8080 w Cloud Shell, który można wykorzystać w przypadku „Podglądu w przeglądarce”.

W prawym górnym rogu Cloud Shell kliknij przycisk „Podgląd w przeglądarce”, a następnie z menu wybierz „Podejrzyj na porcie 8080”.

W przeglądarce otworzy się nowa karta z interfejsem aplikacji. Powinna pojawić się strona „Asystent obsługi klienta Cymbal Air”.

Logowanie w aplikacji

Gdy wszystko będzie skonfigurowane i aplikacja będzie otwarta, możemy użyć przycisku „Zaloguj się” w prawym górnym rogu ekranu aplikacji, aby podać dane logowania. Jest to opcjonalne i wymagane tylko wtedy, gdy chcesz wypróbować funkcję rezerwacji w aplikacji.

Otworzy się wyskakujące okienko, w którym możemy wybrać dane logowania.

Po zalogowaniu aplikacja jest gotowa do użycia. Możesz zacząć publikować prośby w polu u dołu okna.

Prezentacja asystenta obsługi klienta Cymbal Air. Cymbal Air to fikcyjne linie lotnicze. Asystent to chatbot AI, który pomaga podróżnym zarządzać lotami i wyszukiwać informacje o węźle Cymbal Air na międzynarodowym lotnisku w San Francisco (SFO).

Bez logowania (bez CLIENT_ID) może pomóc w odpowiedzi na pytania użytkowników, takie jak:

Kiedy jest następny lot do Denver?

Czy w pobliżu bramy C28 znajdują się jakieś luksusowe sklepy?

Gdzie mogę kupić kawę w pobliżu bramki A6?

Gdzie mogę kupić prezent?

Znajdź lot z San Francisco do Denver z wylotem dzisiaj.

Po zalogowaniu się w aplikacji możesz wypróbować inne funkcje, takie jak rezerwacja lotów czy sprawdzenie, czy przypisane Ci miejsce jest przy oknie czy przy przejściu.

Aplikacja korzysta z najnowszych modeli podstawowych Google do generowania odpowiedzi i wzbogaca je o informacje o lotach i udogodnieniach z operacyjnej bazy danych AlloyDB. Więcej informacji o tej aplikacji demonstracyjnej znajdziesz na stronie projektu w GitHubie.

9. Czyszczenie środowiska

Gdy wszystkie zadania zostaną ukończone, możemy wyczyścić środowisko.

Usuwanie usługi Cloud Run

W Cloud Shell wykonaj to polecenie:

gcloud run services delete toolbox --region us-central1

Oczekiwane dane wyjściowe konsoli:

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

Usuwanie konta usługi dla usługi Cloud Run

W Cloud Shell wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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)$

Po zakończeniu modułu usuń instancje i klaster AlloyDB.

Usuwanie klastra AlloyDB i wszystkich instancji

Jeśli korzystasz z wersji próbnej AlloyDB. Nie usuwaj klastra próbnego, jeśli planujesz testować inne laboratoria i zasoby przy jego użyciu. Nie będzie można utworzyć kolejnego klastra próbnego w tym samym projekcie.

Klaster zostanie zniszczony z użyciem opcji force, która powoduje też usunięcie wszystkich instancji należących do klastra.

W Cloud Shell zdefiniuj projekt i zmienne środowiskowe, jeśli połączenie zostało przerwane i wszystkie poprzednie ustawienia zostały utracone:

gcloud config set project <your project id>

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

Usuń klaster:

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

Uwaga: wykonanie polecenia zajmuje 3–5 minut.

Oczekiwane dane wyjściowe konsoli:

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.   

Usuwanie kopii zapasowych AlloyDB

Usuń wszystkie kopie zapasowe AlloyDB dla klastra:

Uwaga: to polecenie usunie wszystkie kopie zapasowe danych klastra o nazwie określonej w zmiennej środowiskowej.

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

Oczekiwane dane wyjściowe konsoli:

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.                                                                                                                                                                                                                                                            

Teraz możemy zniszczyć maszynę wirtualną.

Usuwanie maszyny wirtualnej GCE

W Cloud Shell wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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

Usuń konto usługi dla maszyny wirtualnej GCE i usługi pobierania.

W Cloud Shell wykonaj to polecenie:

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

Oczekiwane dane wyjściowe konsoli:

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

Gratulujemy ukończenia ćwiczenia.

Omówione zagadnienia

• Jak wdrożyć klaster AlloyDB
• Jak połączyć się z AlloyDB
• Jak skonfigurować i wdrożyć usługę MCP Toolbox
• Jak wdrożyć przykładową aplikację za pomocą wdrożonej usługi

11. Ankieta

Dane wyjściowe:

Jak zamierzasz wykorzystać ten samouczek?

Tylko przeczytaj Przeczytaj i wykonaj ćwiczenia