Trang này được dịch bởi Cloud Translation API.

Ứng dụng RAG dựa trên tác nhân AlloyDB có MCP Toolbox

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách tạo một cụm AlloyDB, triển khai hộp công cụ MCP và định cấu hình hộp công cụ này để sử dụng AlloyDB làm nguồn dữ liệu. Sau đó, bạn sẽ tạo một ứng dụng RAG tương tác mẫu sử dụng hộp công cụ đã triển khai để căn cứ vào các yêu cầu của ứng dụng.

Bạn có thể xem thêm thông tin về MCP Toolbox trên trang tài liệu và ứng dụng Cymbal Air mẫu tại đây.

Phòng thí nghiệm này là một phần của bộ sưu tập phòng thí nghiệm dành riêng cho các tính năng AI của AlloyDB. Bạn có thể đọc thêm trên trang AI AlloyDB trong tài liệu và xem các phòng thí nghiệm khác.

Điều kiện tiên quyết

Có kiến thức cơ bản về Google Cloud Console
Kỹ năng cơ bản về giao diện dòng lệnh và Google Cloud Shell

Kiến thức bạn sẽ học được

Cách triển khai Cụm AlloyDB có tích hợp Vertex AI
Cách kết nối với AlloyDB
Cách định cấu hình và triển khai Dịch vụ MCP Tooolbox
Cách triển khai một ứng dụng mẫu bằng dịch vụ đã triển khai

Bạn cần có

Tài khoản Google Cloud và dự án trên Google Cloud
Một trình duyệt web như Chrome

2. Thiết lập và yêu cầu

Thiết lập môi trường theo tốc độ của riêng bạn

Đăng nhập vào Google Cloud Console rồi tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Nếu chưa có tài khoản Gmail hoặc Google Workspace, bạn phải tạo một tài khoản.

Tên dự án là tên hiển thị của những người tham gia dự án này. Đây là một chuỗi ký tự mà các API của Google không sử dụng. Bạn luôn có thể cập nhật thông tin này.
Mã dự án là giá trị duy nhất trên tất cả các dự án trên Google Cloud và không thể thay đổi (bạn không thể thay đổi mã này sau khi đã đặt). Cloud Console sẽ tự động tạo một chuỗi duy nhất; thường thì bạn không cần quan tâm đến chuỗi này. Trong hầu hết các lớp học lập trình, bạn sẽ cần tham chiếu đến Mã dự án (thường được xác định là PROJECT_ID). Nếu không thích mã nhận dạng được tạo, bạn có thể tạo một mã nhận dạng ngẫu nhiên khác. Hoặc bạn có thể thử tên người dùng của riêng mình để xem tên đó có được chấp nhận hay không. Bạn không thể thay đổi tên này sau bước này và tên này sẽ tồn tại trong suốt thời gian của dự án.
Để bạn nắm được thông tin, có một giá trị thứ ba là Số dự án mà một số API sử dụng. Tìm hiểu thêm về cả 3 giá trị này trong tài liệu.

Tiếp theo, bạn cần bật tính năng thanh toán trong Cloud Console để sử dụng các tài nguyên/API trên Cloud. Việc thực hiện lớp học lập trình này sẽ không tốn nhiều chi phí, nếu có. Để tắt các tài nguyên nhằm tránh bị tính phí ngoài phạm vi hướng dẫn này, bạn có thể xoá các tài nguyên đã tạo hoặc xoá dự án. Người dùng mới của Google Cloud đủ điều kiện tham gia chương trình Dùng thử miễn phí 300 USD.

Khởi động Cloud Shell

Mặc dù có thể vận hành Google Cloud từ xa trên máy tính xách tay, nhưng trong lớp học lập trình này, bạn sẽ sử dụng Google Cloud Shell, một môi trường dòng lệnh chạy trên Cloud.

Trên Bảng điều khiển Google Cloud, hãy nhấp vào biểu tượng Cloud Shell trên thanh công cụ ở trên cùng bên phải:

Kích hoạt Cloud Shell

Quá trình này chỉ mất vài phút để cung cấp và kết nối với môi trường. Khi quá trình này kết thúc, bạn sẽ thấy như sau:

Ảnh chụp màn hình cửa sổ dòng lệnh Google Cloud Shell cho thấy môi trường đã kết nối

Máy ảo này được trang bị tất cả các công cụ phát triển mà bạn cần. Nó cung cấp một thư mục chính có dung lượng 5 GB và chạy trên Google Cloud, giúp tăng cường đáng kể hiệu suất mạng và hoạt động xác thực. Bạn có thể thực hiện mọi thao tác trong lớp học lập trình này trong trình duyệt. Bạn không cần cài đặt bất cứ thứ gì.

3. Trước khi bắt đầu

Bật API

Kết quả:

Trong Cloud Shell, hãy đảm bảo bạn đã thiết lập mã dự án:

Thông thường, mã dự án sẽ xuất hiện trong dấu ngoặc đơn trong dấu nhắc lệnh trong trình bao trên đám mây như trong hình:

gcloud config set project [YOUR-PROJECT-ID]

Sau đó, hãy đặt biến môi trường PROJECT_ID thành mã dự án Google Cloud của bạn:

PROJECT_ID=$(gcloud config get-value project)

Bật tất cả các dịch vụ cần thiết:

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

Kết quả đầu ra dự kiến

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. Triển khai Cụm AlloyDB

Tạo cụm và phiên bản chính AlloyDB. Quy trình sau đây mô tả cách tạo một cụm và phiên bản AlloyDB bằng Google Cloud SDK. Nếu muốn sử dụng phương pháp dựa trên bảng điều khiển, bạn có thể tham khảo tài liệu tại đây.

Trước khi tạo một cụm AlloyDB, chúng ta cần có một dải IP riêng tư có sẵn trong VPC để phiên bản AlloyDB trong tương lai sử dụng. Nếu chưa có, chúng ta cần tạo, chỉ định để các dịch vụ nội bộ của Google sử dụng. Sau đó, chúng ta sẽ có thể tạo cụm và phiên bản.

Tạo dải IP riêng tư

Chúng ta cần định cấu hình chế độ cài đặt Private Service Access trong VPC cho AlloyDB. Giả định ở đây là chúng ta có mạng VPC "mặc định" trong dự án và mạng này sẽ được dùng cho mọi hành động.

Tạo dải IP riêng tư:

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

Tạo kết nối riêng tư bằng dải IP được phân bổ:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Tạo cụm AlloyDB

Trong phần này, chúng ta sẽ tạo một cụm AlloyDB ở khu vực us-central1.

Xác định mật khẩu cho người dùng postgres. Bạn có thể tự xác định mật khẩu hoặc sử dụng một hàm ngẫu nhiên để tạo mật khẩu

export PGPASSWORD=`openssl rand -hex 12`

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Ghi lại mật khẩu PostgreSQL để sử dụng sau này.

echo $PGPASSWORD

Sau này, bạn sẽ cần mật khẩu đó để kết nối với phiên bản dưới dạng người dùng postgres. Bạn nên ghi lại hoặc sao chép mã này vào đâu đó để có thể sử dụng sau.

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Tạo Cụm dùng thử miễn phí

Nếu chưa sử dụng AlloyDB, bạn có thể tạo một cụm dùng thử miễn phí:

Xác định khu vực và tên cụm AlloyDB. Chúng ta sẽ sử dụng khu vực us-central1 và alloydb-aip-01 làm tên cụm:

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

Chạy lệnh để tạo cụm:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

Tạo một phiên bản chính AlloyDB cho cụm của chúng ta trong cùng một phiên cloud shell. Nếu bị ngắt kết nối, bạn sẽ cần xác định lại các biến môi trường tên vùng và tên cụm.

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

Tạo Cụm AlloyDB chuẩn

Nếu đây không phải là cụm AlloyDB đầu tiên của bạn trong dự án, hãy tiếp tục tạo một cụm tiêu chuẩn.

Xác định khu vực và tên cụm AlloyDB. Chúng ta sẽ sử dụng khu vực us-central1 và alloydb-aip-01 làm tên cụm:

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

Chạy lệnh để tạo cụm:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

Cấp các quyền cần thiết cho AlloyDB

Thêm quyền Vertex AI vào đơn vị hỗ trợ dịch vụ AlloyDB.

Mở một thẻ Cloud Shell khác bằng cách sử dụng dấu "+" ở trên cùng.

Trong thẻ cloud shell mới, hãy thực thi:

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"

Kết quả đầu ra dự kiến trên bảng điều khiển:

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:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

Đóng thẻ bằng lệnh thực thi "exit" trong thẻ:

exit

5. Chuẩn bị máy ảo GCE

Chúng ta sẽ sử dụng một VM Google Compute Engine (GCE) làm nền tảng để làm việc với cơ sở dữ liệu và triển khai các phần khác nhau của ứng dụng mẫu. Việc sử dụng một VM giúp chúng tôi linh hoạt hơn trong việc cài đặt các thành phần và truy cập trực tiếp vào IP AlloyDB riêng tư cho các bước chuẩn bị dữ liệu.

Tạo tài khoản dịch vụ

Vì chúng ta sẽ sử dụng VM để triển khai MCP Toolbox dưới dạng một dịch vụ và triển khai hoặc lưu trữ ứng dụng mẫu, nên bước đầu tiên là tạo Tài khoản dịch vụ Google (GSA). Máy ảo GCE sẽ sử dụng GSA và chúng ta cần cấp cho GSA các đặc quyền cần thiết để hoạt động với các dịch vụ khác.

Trong Cloud Shell, hãy thực thi:

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

Triển khai máy ảo GCE

Tạo một VM GCE trong cùng khu vực và VPC với cụm AlloyDB.

Trong Cloud Shell, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Cài đặt ứng dụng Postgres

Cài đặt phần mềm máy khách PostgreSQL trên máy ảo đã triển khai

Kết nối với máy ảo:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Cài đặt lệnh chạy phần mềm bên trong máy ảo:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Kết nối với phiên bản AlloyDB

Kết nối với phiên bản chính từ máy ảo bằng psql.

Tiếp tục với phiên SSH đã mở đến VM của bạn. Nếu bạn bị ngắt kết nối, hãy kết nối lại bằng lệnh tương tự như trên.

Dùng $PGASSWORD và tên cụm đã ghi chú trước đó để kết nối với AlloyDB từ máy ảo 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"

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Thoát khỏi phiên psql trong khi vẫn duy trì kết nối SSH:

exit

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

6. Khởi chạy cơ sở dữ liệu

Chúng ta sẽ sử dụng VM của ứng dụng làm nền tảng để điền dữ liệu vào cơ sở dữ liệu và lưu trữ ứng dụng. Bước đầu tiên là tạo cơ sở dữ liệu và điền dữ liệu vào đó.

Tạo cơ sở dữ liệu

Tạo một cơ sở dữ liệu có tên "assistantdemo".

Trong phiên máy ảo GCE, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Chuẩn bị môi trường Python

Để tiếp tục, chúng ta sẽ sử dụng các tập lệnh Python đã chuẩn bị sẵn trong kho lưu trữ GitHub, nhưng trước khi làm điều đó, chúng ta cần cài đặt phần mềm bắt buộc.

Trong máy ảo GCE, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Xác minh phiên bản Python.

Trong máy ảo GCE, hãy thực thi:

python -V

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Cài đặt Hộp công cụ MCP cục bộ

MCP Toolbox for Databases (sau đây gọi là MCP toolbox hoặc toolbox) là một máy chủ MCP nguồn mở hoạt động với nhiều nguồn dữ liệu. Nó giúp bạn phát triển các công cụ nhanh hơn bằng cách cung cấp một mức độ trừu tượng cho các nguồn dữ liệu khác nhau và thêm các tính năng như xác thực và nhóm kết nối. Bạn có thể đọc về tất cả các tính năng trên trang chính thức.

Chúng ta sẽ dùng hộp công cụ MCP để khởi tạo tập dữ liệu mẫu và sau đó dùng làm máy chủ MCP để xử lý các yêu cầu về nguồn dữ liệu từ ứng dụng trong quy trình Tạo sinh tăng cường truy xuất (RAG).

Hãy cài đặt bộ công cụ MCP cục bộ để điền sẵn cơ sở dữ liệu assistantdemo.

Trong máy ảo GCE, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Chạy Hộp công cụ để khởi chạy dữ liệu

Trong máy ảo GCE, hãy thực thi:

Xuất các biến môi trường để điền sẵn cơ sở dữ liệu:

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"

Khởi động hộp công cụ để khởi tạo cơ sở dữ liệu. Thao tác này sẽ bắt đầu quy trình cục bộ, giúp bạn kết nối liền mạch với cơ sở dữ liệu đích trên AlloyDB để điền dữ liệu mẫu.

./toolbox --prebuilt alloydb-postgres

Kết quả đầu ra dự kiến trên bảng điều khiển. Bạn sẽ thấy dòng cuối cùng của đầu ra là "Server ready to serve!" (Máy chủ đã sẵn sàng hoạt động!):

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

Đừng thoát hoặc đóng thẻ Cloud Shell này cho đến khi quá trình điền dữ liệu hoàn tất.

Điền sẵn cơ sở dữ liệu

Mở một thẻ Cloud Shell khác bằng cách sử dụng dấu "+" ở trên cùng.

Và kết nối với máy ảo instance-1:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Sao chép kho lưu trữ GitHub có mã cho dịch vụ truy xuất và ứng dụng mẫu.

Trong máy ảo GCE, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Vui lòng chú ý nếu bạn gặp phải lỗi.

Chuẩn bị môi trường Python và cài đặt các gói yêu cầu:

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

Đặt đường dẫn Python đến thư mục gốc của kho lưu trữ và chạy tập lệnh để điền dữ liệu mẫu vào cơ sở dữ liệu. Lệnh đầu tiên là thêm một đường dẫn đến các mô-đun Python vào môi trường của chúng ta và lệnh thứ hai là điền dữ liệu vào cơ sở dữ liệu.

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

Kết quả đầu ra dự kiến trên bảng điều khiển(đã chỉnh sửa). Bạn sẽ thấy "database init done" (đã hoàn tất quá trình khởi tạo cơ sở dữ liệu) ở cuối:

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$

Bây giờ, bạn có thể đóng thẻ này.

Trong phiên VM, hãy thực thi:

exit

Trong phiên Cloud Shell, hãy nhấn tổ hợp phím ctrl+d hoặc thực thi :

exit

Trong thẻ đầu tiên có MCP Toolbox đang chạy, hãy nhấn tổ hợp phím ctrl+c để thoát khỏi phiên đang chạy của hộp công cụ.

Cơ sở dữ liệu đã được điền sẵn dữ liệu mẫu cho ứng dụng.

Bạn có thể xác minh bằng cách kết nối với cơ sở dữ liệu và kiểm tra số lượng hàng trong bảng sân bay. Bạn có thể sử dụng tiện ích psql như chúng ta đã sử dụng trước đây hoặc AlloyDB Studio . sau đây là cách kiểm tra bằng psql

Trong phiên SSH đến máy ảo instance-1, hãy thực thi:

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"

Kết quả đầu ra dự kiến trên bảng điều khiển:

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)

Cơ sở dữ liệu đã sẵn sàng và chúng ta có thể chuyển sang triển khai MCP Toolbox.

7. Triển khai Hộp công cụ MCP lên Cloud Run

Giờ đây, chúng ta có thể triển khai MCP Toolbox lên Cloud Run. Có nhiều cách để triển khai hộp công cụ MCP. Cách đơn giản nhất là chạy từ dòng lệnh, nhưng nếu muốn có một dịch vụ có thể mở rộng và đáng tin cậy, thì Cloud Run là một giải pháp tốt hơn.

Chuẩn bị mã ứng dụng

Để sử dụng chức năng đặt phòng của ứng dụng, chúng ta cần chuẩn bị mã ứng dụng OAuth 2.0 bằng Cloud Console. Nếu không có, chúng tôi không thể đăng nhập vào ứng dụng bằng thông tin đăng nhập Google để đặt chỗ và ghi lại thông tin đặt chỗ vào cơ sở dữ liệu.

Trong Cloud Console, hãy chuyển đến phần API và dịch vụ rồi nhấp vào "Màn hình xin phép bằng OAuth". Sau đây là đường liên kết đến trang này. Thao tác này sẽ mở trang Tổng quan về OAuth, nơi chúng ta nhấp vào Bắt đầu.

Trên trang tiếp theo, chúng tôi cung cấp tên ứng dụng, email hỗ trợ người dùng và nhấp vào Tiếp theo.

Trên màn hình tiếp theo, chúng ta chọn Internal (Nội bộ) cho ứng dụng của mình rồi nhấp vào Next (Tiếp theo) một lần nữa.

Sau đó, chúng tôi cung cấp email liên hệ và nhấp vào Tiếp theo

Sau đó, chúng ta đồng ý với các chính sách của dịch vụ API của Google và nhấn nút Tạo.

Thao tác này sẽ đưa chúng ta đến trang mà chúng ta có thể tạo một ứng dụng OAuth.

Trên màn hình, chúng ta chọn "Web Application" (Ứng dụng web) trong trình đơn thả xuống, đặt "Cymbal Air" làm ứng dụng rồi nhấn nút Add URI (Thêm URI).

URI đại diện cho các nguồn đáng tin cậy của ứng dụng và phụ thuộc vào vị trí mà bạn đang cố gắng truy cập vào ứng dụng. Chúng tôi đặt "http://localhost:8081" làm URI được uỷ quyền và "http://localhost:8081/login/google" làm URI chuyển hướng. Những giá trị đó sẽ hoạt động nếu bạn nhập "http://localhost:8081" vào trình duyệt làm URI để kết nối. Ví dụ: khi bạn kết nối qua một đường hầm SSH từ máy tính. Tôi sẽ chỉ cho bạn cách thực hiện việc này sau.

Sau khi nhấn nút "Tạo", bạn sẽ thấy một cửa sổ bật lên chứa thông tin đăng nhập của khách hàng. Thông tin đăng nhập sẽ được ghi lại trong hệ thống. Bạn luôn có thể sao chép mã ứng dụng khách để sử dụng khi khởi động ứng dụng.

Sau này, bạn sẽ thấy nơi cung cấp mã ứng dụng khách đó.

Tạo tài khoản dịch vụ

Chúng ta cần một tài khoản dịch vụ chuyên dụng cho dịch vụ Cloud Run với tất cả các đặc quyền bắt buộc. Để cung cấp dịch vụ, chúng tôi cần có quyền truy cập vào AlloyDB và Cloud Secret Manager. Đối với tên của tài khoản dịch vụ, chúng ta sẽ sử dụng toolbox-identity.

Mở một thẻ Cloud Shell khác bằng cách sử dụng dấu "+" ở trên cùng.

Trong thẻ cloud shell mới, hãy thực thi:

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"

Vui lòng chú ý nếu bạn gặp phải lỗi. Lệnh này được dùng để tạo tài khoản dịch vụ cho dịch vụ Cloud Run và cấp đặc quyền để làm việc với trình quản lý bí mật, cơ sở dữ liệu và Vertex AI.

Đóng thẻ bằng cách nhấn tổ hợp phím ctrl+d hoặc thực thi lệnh "exit" trong thẻ:

exit

Chuẩn bị cấu hình Hộp công cụ MCP

Chuẩn bị tệp cấu hình cho MCP Toolbox. Bạn có thể đọc về tất cả các lựa chọn cấu hình trong tài liệu, nhưng ở đây, chúng ta sẽ sử dụng tệp tools.yaml mẫu và thay thế một số giá trị như tên cụm và tên phiên bản, mật khẩu AlloyDB và mã dự án bằng các giá trị thực tế của chúng ta.

Xuất mật khẩu AlloyDB:

export PGPASSWORD=<noted AlloyDB password>

Xuất mã ứng dụng khách mà chúng ta đã chuẩn bị ở bước trước:

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

Chuẩn bị tệp cấu hình.

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

Nếu xem phần tệp xác định nguồn dữ liệu mục tiêu, bạn sẽ thấy rằng chúng tôi cũng đã thêm một dòng để sử dụng IP riêng tư cho kết nối.

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

Tạo một bí mật bằng cách sử dụng cấu hình tools.yaml làm nguồn.

Trong bảng điều khiển ssh của máy ảo, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Triển khai MCP Toolbox dưới dạng một Dịch vụ Cloud Run

Giờ đây, bạn đã chuẩn bị xong mọi thứ để triển khai MCP Toolbox dưới dạng một dịch vụ cho Cloud Run. Đối với kiểm thử cục bộ, bạn có thể chạy "./toolbox –tools-file=./tools.yaml" nhưng nếu muốn ứng dụng chạy trên đám mây, thì việc triển khai trong Cloud Run sẽ hợp lý hơn nhiều.

Trong phiên SSH của máy ảo, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Xác minh Dịch vụ

Giờ đây, chúng ta có thể kiểm tra xem dịch vụ có hoạt động hay không và chúng ta có thể truy cập vào điểm cuối hay không. Chúng ta sẽ dùng tiện ích gcloud để lấy điểm cuối dịch vụ truy xuất và mã thông báo xác thực. Ngoài ra, bạn có thể kiểm tra URI dịch vụ trong Cloud Console.

Bạn có thể sao chép giá trị này và thay thế phần "$(gcloud run services list –filter="(toolbox)" –format="value(URL)" trong lệnh curl .

Sau đây là cách lấy URL một cách linh hoạt từ dòng lệnh:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Nếu chúng ta thấy thông báo "Hello World", tức là dịch vụ của chúng ta đang hoạt động và xử lý các yêu cầu.

8. Triển khai ứng dụng mẫu

Giờ đây, khi dịch vụ truy xuất đã hoạt động, chúng ta có thể triển khai một ứng dụng mẫu. Ứng dụng này là một trợ lý sân bay trực tuyến có thể cung cấp cho bạn thông tin về các chuyến bay, sân bay và thậm chí đặt chuyến bay dựa trên dữ liệu chuyến bay và sân bay trong cơ sở dữ liệu của chúng tôi.

Bạn có thể triển khai ứng dụng này cục bộ, trên một máy ảo trên đám mây hoặc bất kỳ dịch vụ nào khác như Cloud Run hoặc Kubernetes. Ở đây, chúng ta sẽ cho thấy cách triển khai trước trên máy ảo.

Chuẩn bị môi trường

Chúng ta tiếp tục làm việc trên VM bằng cùng một phiên SSH. Để chạy ứng dụng, chúng ta cần một số mô-đun Python và chúng ta đã thêm các mô-đun này khi khởi động cơ sở dữ liệu trước đó. Hãy chuyển sang môi trường ảo Python và thay đổi vị trí thành thư mục ứng dụng.

Trong phiên SSH của máy ảo, hãy thực thi:

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

Kết quả đầu ra dự kiến (đã chỉnh sửa):

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

Chạy ứng dụng Trợ lý

Trước khi bắt đầu ứng dụng, chúng ta cần thiết lập một số biến môi trường. Chức năng cơ bản của ứng dụng, chẳng hạn như truy vấn các chuyến bay và tiện nghi tại sân bay, chỉ yêu cầu TOOLBOX_URL. URL này sẽ hướng ứng dụng đến dịch vụ truy xuất. Chúng ta có thể lấy khoá này bằng lệnh gcloud .

Trong phiên SSH của máy ảo, hãy thực thi:

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

Kết quả đầu ra dự kiến (đã chỉnh sửa):

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

Để sử dụng các chức năng nâng cao hơn của ứng dụng, chẳng hạn như đặt và thay đổi chuyến bay, chúng ta cần đăng nhập vào ứng dụng bằng tài khoản Google. Vì mục đích đó, chúng ta cần cung cấp biến môi trường CLIENT_ID bằng mã ứng dụng OAuth trong chương Chuẩn bị mã ứng dụng:

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

Kết quả đầu ra dự kiến (đã chỉnh sửa):

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

Giờ đây, chúng ta có thể chạy ứng dụng:

python run_app.py

Kết quả đầu ra dự kiến:

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)

Kết nối với ứng dụng

Bạn có thể kết nối với ứng dụng đang chạy trên máy ảo theo một số cách. Ví dụ: bạn có thể mở cổng 8081 trên VM bằng cách sử dụng các quy tắc tường lửa trong VPC hoặc tạo một bộ cân bằng tải có IP công khai. Ở đây, chúng ta sẽ sử dụng một đường hầm SSH đến VM để dịch cổng cục bộ 8080 sang cổng 8081 của VM.

Kết nối từ máy cục bộ

Khi muốn kết nối từ một máy cục bộ, chúng ta cần chạy một đường hầm SSH. Bạn có thể thực hiện việc này bằng cách sử dụng gcloud compute ssh:

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

Kết quả đầu ra dự kiến:

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

Bây giờ, chúng ta có thể mở trình duyệt và sử dụng http://localhost:8081 để kết nối với ứng dụng của mình. Chúng ta sẽ thấy màn hình ứng dụng.

Kết nối từ Cloud Shell

Ngoài ra, chúng ta có thể sử dụng Google Cloud Shell để kết nối. Mở một thẻ Cloud Shell khác bằng cách sử dụng dấu "+" ở trên cùng.

Trong thẻ mới, hãy lấy URI gốc và URI chuyển hướng cho ứng dụng web của bạn đang thực thi lệnh gcloud:

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

Sau đây là kết quả đầu ra dự kiến:

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

Và sử dụng nguồn gốc cũng như lệnh chuyển hướng của URI làm "Nguồn gốc JavaScript được uỷ quyền" và "URI chuyển hướng được uỷ quyền" cho thông tin đăng nhập mà chúng ta đã tạo trong chương "Chuẩn bị mã ứng dụng khách" bằng cách thay thế hoặc thêm vào các giá trị http://localhost:8080 được cung cấp ban đầu.

Nhấp vào "Cymbal Air" trên trang mã ứng dụng khách OAuth 2.0.

Đặt URI gốc và URI chuyển hướng cho Cloud Shell rồi nhấn vào nút Lưu.

Trong thẻ Cloud Shell mới, hãy bắt đầu đường hầm đến VM của bạn bằng cách thực thi lệnh gcloud:

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

Nếu thông báo lỗi "Không thể chỉ định địa chỉ được yêu cầu" xuất hiện, vui lòng bỏ qua thông báo này.

Sau đây là kết quả đầu ra dự kiến:

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

Thao tác này sẽ mở cổng 8080 trên Cloud Shell. Bạn có thể dùng cổng này cho tính năng "Xem trước trên web".

Nhấp vào nút "Xem trước trên web" ở phía trên cùng bên phải của Cloud Shell rồi chọn "Xem trước trên cổng 8080" trong trình đơn thả xuống

Thao tác này sẽ mở một thẻ mới trong trình duyệt web của bạn với giao diện ứng dụng. Bạn sẽ thấy trang "Trợ lý dịch vụ khách hàng của Cymbal Air".

Đăng nhập vào Ứng dụng

Khi mọi thứ đã được thiết lập và ứng dụng của bạn đang mở, chúng ta có thể sử dụng nút "Đăng nhập" ở trên cùng bên phải màn hình ứng dụng để cung cấp thông tin đăng nhập. Đây là bước không bắt buộc và bạn chỉ cần thực hiện nếu muốn dùng thử chức năng đặt phòng của ứng dụng.

Một cửa sổ bật lên sẽ xuất hiện để chúng ta có thể chọn thông tin đăng nhập.

Sau khi đăng nhập, ứng dụng sẽ sẵn sàng và bạn có thể bắt đầu đăng các yêu cầu của mình vào trường ở cuối cửa sổ.

Bản minh hoạ này giới thiệu trợ lý dịch vụ khách hàng Cymbal Air. Cymbal Air là một hãng hàng không chở khách hư cấu. Trợ lý này là một chatbot AI giúp hành khách quản lý các chuyến bay và tra cứu thông tin về trung tâm hoạt động của Cymbal Air tại Sân bay quốc tế San Francisco (SFO).

Nếu không đăng nhập (không có CLIENT_ID), bạn có thể trả lời các câu hỏi của người dùng như:

Khi nào có chuyến bay tiếp theo đến Denver?

Có cửa hàng cao cấp nào ở gần cổng C28 không?

Tôi có thể mua cà phê ở đâu gần cổng A6?

Tôi có thể mua quà tặng ở đâu?

Vui lòng tìm chuyến bay từ SFO đến Denver khởi hành hôm nay

Khi đăng nhập vào ứng dụng, bạn có thể thử các chức năng khác như đặt vé máy bay hoặc kiểm tra xem ghế được chỉ định cho bạn là ghế cạnh cửa sổ hay ghế cạnh lối đi.

Ứng dụng này sử dụng các mô hình cơ sở mới nhất của Google để tạo câu trả lời và tăng cường câu trả lời bằng thông tin về các chuyến bay và tiện nghi từ cơ sở dữ liệu AlloyDB đang hoạt động. Bạn có thể đọc thêm về ứng dụng minh hoạ này trên trang Github của dự án.

9. Dọn dẹp môi trường

Giờ đây, khi hoàn thành tất cả các nhiệm vụ, chúng ta có thể dọn dẹp môi trường

Xoá dịch vụ Cloud Run

Trong Cloud Shell, hãy thực thi:

gcloud run services delete toolbox --region us-central1

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Xoá Tài khoản dịch vụ cho dịch vụ Cloud Run

Trong Cloud Shell, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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 [retrieval-identity@gleb-test-short-004.iam.gserviceaccount.com]
student@cloudshell:~ (gleb-test-short-004)$

Huỷ các phiên bản và cụm AlloyDB khi bạn hoàn tất bài thực hành.

Xoá cụm AlloyDB và tất cả các phiên bản

Nếu bạn đã dùng phiên bản dùng thử của AlloyDB. Đừng xoá cụm dùng thử nếu bạn có kế hoạch kiểm thử các phòng thí nghiệm và tài nguyên khác bằng cụm dùng thử. Bạn sẽ không thể tạo một cụm thử nghiệm khác trong cùng một dự án.

Cụm bị huỷ bằng lựa chọn force, thao tác này cũng sẽ xoá tất cả các phiên bản thuộc cụm.

Trong cloud shell, hãy xác định dự án và các biến môi trường nếu bạn bị ngắt kết nối và mất tất cả các chế độ cài đặt trước đó:

gcloud config set project <your project id>

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

Xoá cụm:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

Xoá bản sao lưu AlloyDB

Xoá tất cả bản sao lưu AlloyDB cho cụm:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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.

Bây giờ, chúng ta có thể huỷ VM

Xoá máy ảo GCE

Trong Cloud Shell, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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

Xoá Tài khoản dịch vụ cho VM GCE và dịch vụ Truy xuất

Trong Cloud Shell, hãy thực thi:

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

Kết quả đầu ra dự kiến trên bảng điều khiển:

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 [compute-aip@gleb-test-short-004.iam.gserviceaccount.com]
student@cloudshell:~ (gleb-test-short-004)$

10. Xin chúc mừng

Chúc mừng bạn đã hoàn thành lớp học lập trình này.

Nội dung đã đề cập

Cách triển khai Cụm AlloyDB
Cách kết nối với AlloyDB
Cách định cấu hình và triển khai Dịch vụ Hộp công cụ MCP
Cách triển khai một ứng dụng mẫu bằng dịch vụ đã triển khai

11. Khảo sát

Kết quả:

Bạn sẽ sử dụng hướng dẫn này như thế nào?

Chỉ đọc qua

Đọc và hoàn thành bài tập