1. Giới thiệu
Lớp học lập trình này cung cấp hướng dẫn về cách bắt đầu sử dụng máy chủ MCP của Google Cloud cho AlloyDB và bật máy chủ này trong bộ công cụ cho một tác nhân AI, đồng thời sử dụng máy chủ này trong ứng dụng.
Đ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à Cloud Shell
Kiến thức bạn sẽ học được
- Cách tạo một cụm AlloyDB và nhập dữ liệu mẫu
- Cách bật AlloyDB Data Access API
- Cách bật MCP của Google Cloud cho AlloyDB NL
- Cách thêm MCP Google Cloud cho AlloyDB vào tác nhân ADK
- Cách sử dụng MCP của Google Cloud cho AlloyDB trong một ứng dụng
- Cách sử dụng các tác nhân với AlloyDBMCP để phân tích
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 hỗ trợ bảng điều khiển Cloud và Cloud Shell
2. Thiết lập và yêu cầu
Thiết lập dự án
- Đăng nhập vào Google Cloud Console. 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.
Sử dụng tài khoản cá nhân thay vì tài khoản trường học hoặc tài khoản do nơi làm việc cấp.
- Tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Để tạo một dự án mới trong bảng điều khiển Cloud của Google, trong tiêu đề, hãy nhấp vào nút Chọn dự án. Thao tác này sẽ mở một cửa sổ bật lên.
Trong cửa sổ Chọn một dự án, hãy nhấn vào nút Dự án mới. Thao tác này sẽ mở một hộp thoại cho dự án mới.
Trong hộp thoại, hãy nhập tên Dự án mà bạn muốn và chọn vị trí.
- Tên dự án là tên hiển thị của những người tham gia dự án này. Tên dự án không được các API của Google sử dụng và bạn có thể thay đổi tên này bất cứ lúc nào.
- Mã dự án là mã 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). Bảng điều khiển Cloud của Google tự động tạo một mã nhận dạng duy nhất, nhưng bạn có thể tuỳ chỉnh mã này. 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 cung cấp mã nhận dạng của riêng bạn để kiểm tra xem mã đó có còn trống hay không. 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 của mình. Mã này thường được xác định bằng phần giữ chỗ PROJECT_ID.
- Để 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.
Bật tính năng thanh toán
Thiết lập tài khoản thanh toán cá nhân
Nếu thiết lập thông tin thanh toán bằng tín dụng Google Cloud, bạn có thể bỏ qua bước này.
Để thiết lập tài khoản thanh toán cá nhân, hãy truy cập vào đây để bật tính năng thanh toán trong Cloud Console.
Một số lưu ý:
- Việc hoàn thành bài tập thực hành này sẽ tốn ít hơn 3 USD cho các tài nguyên trên đám mây.
- Bạn có thể làm theo các bước ở cuối bài thực hành này để xoá tài nguyên nhằm tránh bị tính thêm phí.
- Người dùng mới đủ điều kiện dùng thử miễn phí trị giá 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:
Hoặc bạn có thể nhấn phím G rồi nhấn phím S. Trình tự này sẽ kích hoạt Cloud Shell nếu bạn đang ở trong Google Cloud Console hoặc sử dụng đường liên kết này.
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:
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ền tảng này 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
Để sử dụng AlloyDB, Compute Engine, Networking services (Dịch vụ mạng) và Vertex AI, bạn cần bật các API tương ứng trong dự án trên đám mây của Google.
Trong thiết bị đầu cuối Cloud Shell, hãy đảm bảo rằng bạn đã thiết lập mã dự án:
gcloud config get-value project
Thao tác này sẽ trả về mã dự án của bạn trên Google.
Đặt biến môi trường PROJECT_ID:
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 \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Kết quả đầu ra dự kiến
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
4. Triển khai AlloyDB
Tạo cụm và phiên bản chính AlloyDB. Bạn có thể triển khai bằng cách sử dụng một tập lệnh đã chuẩn bị sẵn để triển khai tất cả các tài nguyên cần thiết hoặc bạn có thể tự thực hiện từng bước theo tài liệu.
Triển khai AlloyDB bằng tập lệnh tự động
Phương pháp này sử dụng một tập lệnh tự động để triển khai cụm AlloyDB và cung cấp thông tin cần thiết để bắt đầu làm việc với các tài nguyên đã triển khai.
Trong thiết bị đầu cuối Cloud Shell, hãy thực thi lệnh để sao chép tập lệnh triển khai từ kho lưu trữ.
REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"
git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR
Chạy tập lệnh triển khai.
./deploy_alloydb.sh
Tập lệnh sẽ mất một chút thời gian để chạy – thường là khoảng 5 đến 7 phút. Sau đó, dưới dạng đầu ra, nó sẽ cung cấp thông tin về cụm AlloyDB mà bạn đã triển khai. Xin lưu ý rằng mật khẩu của bạn sẽ khác – hãy ghi lại mật khẩu ở đâu đó để sử dụng sau này.
... <redacted> ... Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster) Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715 Creating instance...done. ---------------------------------------- Deployment Process Completed Cluster: alloydb-aip-01 (TRIAL) Instance: alloydb-aip-01-pr Region: us-central1 Initial Password: JBBoDTgixzYwYpkF (if new cluster) ----------------------------------------
Bạn cũng có thể xem cụm mới và phiên bản chính trong bảng điều khiển trên web
5. Chuẩn bị cơ sở dữ liệu
Bạn cần bật tính năng tích hợp Vertex AI để sử dụng các chức năng và toán tử AI, bật API quyền truy cập dữ liệu và tạo cơ sở dữ liệu cho tập dữ liệu mẫu.
Cấp các quyền cần thiết cho AlloyDB
Thêm quyền Vertex AI vào tác nhân 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"
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/discoveryengine.viewer"
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: ... < redacted > etag: BwYIEbe_Z3U= version: 1
Bật Data Access API
Bạn phải bật Data Access API trên cụm AlloyDB để có thể sử dụng các công cụ MCP như execute_sql.
Thực thi trong cùng một thẻ của thiết bị đầu cuối.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
Cập nhật cờ phiên bản
Để sử dụng các hàm AI nâng cao trong AlloyDB, chúng ta cần bật một số cờ cơ sở dữ liệu. Sau khi bật Data Access API, có thể mất vài phút để thực thể sẵn sàng cho các thay đổi tiếp theo. Vui lòng xem trạng thái của phiên bản trong bảng điều khiển để đảm bảo phiên bản có dấu kiểm màu xanh lục.
Thực thi trong cùng một thẻ của thiết bị đầu cuối.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
--database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
--region=$REGION \
--cluster=$ADBCLUSTER \
--project=$PROJECT_ID \
--update-mode=FORCE_APPLY
Bật MCP
Bước tiếp theo là bật máy chủ MCP của Google Cloud cho AlloyDB trong dự án của bạn. Theo mặc định, MCP không được bật và đây là một trong nhiều lớp bảo vệ, bao gồm cả xác thực và uỷ quyền IAM, API truy cập dữ liệu và các vai trò trong cụm của bạn.
Thực thi trong cùng một thẻ của thiết bị đầu cuối.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
--project=$PROJECT_ID
Đóng thẻ bằng lệnh thực thi "exit" trong thẻ:
exit
Kết nối với AlloyDB Studio
Trong các chương sau, bạn có thể thực thi tất cả các lệnh SQL yêu cầu kết nối với cơ sở dữ liệu trong AlloyDB Studio. T
Chuyển đến trang Cụm trong AlloyDB cho Postgres.
Mở giao diện bảng điều khiển web cho cụm AlloyDB bằng cách nhấp vào phiên bản chính.
Sau đó, nhấp vào AlloyDB Studio ở bên trái:
Chọn cơ sở dữ liệu postgres, người dùng postgres và cung cấp mật khẩu đã ghi lại khi chúng ta tạo cụm. Sau đó, hãy nhấp vào nút "Xác thực".
Nếu mật khẩu không hoạt động hoặc bạn quên ghi lại mật khẩu, bạn có thể thay đổi mật khẩu. Hãy xem tài liệu về cách thực hiện việc đó.
Thao tác này sẽ mở giao diện AlloyDB Studio. Để chạy các lệnh trong cơ sở dữ liệu, bạn nhấp vào thẻ "Untitled Query" (Truy vấn chưa có tiêu đề) ở bên phải.
Thao tác này sẽ mở ra giao diện nơi bạn có thể chạy các lệnh SQL
Tạo cơ sở dữ liệu
Tạo cơ sở dữ liệu bắt đầu nhanh.
Trong Trình chỉnh sửa AlloyDB Studio, hãy thực thi lệnh sau.
Tạo cơ sở dữ liệu:
CREATE DATABASE quickstart_db
Kết quả đầu ra dự kiến:
Statement executed successfully
Kết nối với quickstart_db
Kiểm tra xem cơ sở dữ liệu của bạn có được tạo bằng cách kết nối với cơ sở dữ liệu đó hay không. Kết nối lại với studio bằng nút chuyển đổi người dùng/cơ sở dữ liệu.
Chọn cơ sở dữ liệu quickstart_db mới trong danh sách thả xuống và sử dụng cùng một người dùng và mật khẩu như trước.
Thao tác này sẽ mở một kết nối mới để bạn có thể làm việc với các đối tượng trong cơ sở dữ liệu quickstart_db. Tại đây, bạn có thể kiểm tra giản đồ và dữ liệu đã nhập.
6. Dữ liệu mẫu
Bây giờ, bạn cần tạo các đối tượng trong cơ sở dữ liệu và tải dữ liệu. Bạn sẽ sử dụng một tập dữ liệu giả định của công ty Cymbal Shipping. Ứng dụng này có dữ liệu giả định về hàng hoá, xe tải, yêu cầu và chuyến đi của xe tải cùng với các tài xế giả định.
Tạo vùng lưu trữ
Bạn sẽ sử dụng Google SDK (gcloud) để nhập dữ liệu từ kho lưu trữ được nhân bản vào cơ sở dữ liệu AlloyDB và cần tạo một bộ chứa lưu trữ cho dữ liệu đó, đồng thời cấp quyền truy cập cho tài khoản dịch vụ AlloyDB. Ngoài ra, bạn luôn có thể thử thực hiện việc này bằng bảng điều khiển web như mô tả trong tài liệu.
Trong cửa sổ dòng lệnh Google Cloud Shell, hãy thực thi:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer
Tải dữ liệu
Bước tiếp theo là tải dữ liệu. Tệp kết xuất SQL của chúng tôi nằm trong thư mục kho lưu trữ được sao chép. Lệnh sau đây giả định rằng bạn đã sử dụng thư mục chính làm điểm xuất phát khi nhân bản kho lưu trữ ở bước trước trong khi tạo cụm AlloyDB.
Sao chép tệp kết xuất SQL đã nén vào bộ chứa lưu trữ mới:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz gs://$PROJECT_ID-import
Sau đó, tải dữ liệu lên cơ sở dữ liệu quickstart_db:
PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql
Lệnh này sẽ tải tập dữ liệu mẫu vào cơ sở dữ liệu quickstart_db. Bạn có thể xác minh các bảng và bản ghi bằng AlloyDB Studio.
7. Làm việc với Data Agent
Hãy bắt đầu từ một tác nhân AI mẫu được tạo bằng Google ADK cho Python và cho biết cách định cấu hình tác nhân đó để hoạt động với máy chủ MCP của Google Cloud cho AlloyDB.
Kiểm tra mã nguồn của Agent
Trong kho lưu trữ được sao chép, hãy xem xét mã tác nhân bằng trình chỉnh sửa Google Cloud Shell.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py
Bạn có thể thấy trong tác nhân, chúng ta có một phần dành cho máy chủ MCP của Google Cloud cho AlloyDB. Chúng tôi cung cấp một điểm cuối dưới dạng MCP_SERVER_URL, xác thực, mã dự án và thêm mã dự án đó vào bộ công cụ MCP.
# Google Cloud MCP Server for AlloyDB
MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
creds.refresh(GoogleAuthRequest())
print(f"Authenticated as project: {project_id}")
# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
"Authorization": f"Bearer {creds.token}",
"X-Goog-User-Project": project_id
}
connection_params = StreamableHTTPConnectionParams(
url=MCP_SERVER_URL,
headers=headers,
timeout=300.0,
sse_read_timeout=600.0
)
mcp_toolset = McpToolset(connection_params=connection_params)
Và trong mã nhân viên hỗ trợ, bộ công cụ MCP được đưa vào dưới dạng tham số tools cho nhân viên hỗ trợ. Ngoài ra, còn có tên cụm và tên phiên bản, khu vực và cơ sở dữ liệu dưới dạng các biến cho lời nhắc của tác nhân.
MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"
# Agent configuration
root_agent = Agent(
model=MODEL_ID,
name='root_agent',
description='A helpful assistant for analyst requests.',
instruction=f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
""",
tools=[mcp_toolset],
)
Dịch vụ MCP của Google Cloud cho AlloyDB có một bộ công cụ được xác định trước. Nếu muốn liệt kê tất cả các công cụ có sẵn, bạn có thể sử dụng lệnh curl từ thiết bị đầu cuối của bảng điều khiển Cloud Shell bằng lệnh sau. Bạn luôn có thể xem thông tin tham khảo mới nhất về máy chủ MCP của Google Cloud cho alloydb trong tài liệu.
curl -s -X POST http://alloydb.googleapis.com/mcp \
-H "Content-Type: application/json" \
-d @- <<EOF | jq -r '.result.tools[].name'
{
"id": "my_id_01",
"jsonrpc": "2.0",
"method": "tools/list"
}
EOF
Khởi động nhân viên hỗ trợ
Giờ đây, bạn có thể khởi động tác nhân ở chế độ tương tác bằng giao diện web Google ADK. Giao diện web ADK là một cách thuận tiện để kiểm thử và khắc phục sự cố cho quy trình làm việc của các tác nhân.
Trước tiên, hãy cài đặt tất cả các gói cần thiết cho Python bằng trình quản lý gói uv.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync
Khi đã cài đặt tất cả các gói, bạn cần thêm tệp .env vào thư mục tác nhân để hướng dẫn tác nhân sử dụng Vertex AI cho mọi hoạt động giao tiếp với các mô hình AI.
echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env
Sau đó, bạn có thể khởi động tác nhân
uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Bạn sẽ thấy kết quả như sau với điểm cuối như http://127.0.0.1:8000 .
Bạn có thể nhấp vào URL đó trong Cloud Shell và URL này sẽ mở một cửa sổ xem trước trong một thẻ trình duyệt riêng, nơi bạn chọn data_agent trong danh sách thả xuống ở bên trái.
Trong giao diện web ADK, bạn có thể đăng câu hỏi ở dưới cùng bên phải và xem toàn bộ quy trình thực thi, bao gồm cả dấu vết cho từng bước ở bên phải.
8. Kiểm thử MCP AlloyDB bằng Agent
Agent cho phép bạn đặt câu hỏi ở dạng biểu mẫu tuỳ ý bằng ngôn ngữ tự nhiên và Agent sẽ sử dụng máy chủ MCP của Google Cloud cho AlloyDB làm công cụ để trả lời các câu hỏi. Các câu hỏi được đăng ở dưới cùng bên phải và câu trả lời cùng với tất cả lệnh gọi đến các công cụ sẽ xuất hiện ở trên cùng.
Bạn đang làm việc với dữ liệu vận hành của một công ty vận chuyển có thông tin về các yêu cầu vận chuyển, xe tải, tài xế và chuyến đi của tài xế. Câu hỏi đầu tiên là về số lượng chuyến đi được thực hiện vào tháng 2 năm 2026.
Trong trường nhập dữ liệu ở dưới cùng bên phải, hãy nhập nội dung sau rồi nhấn phím Enter.
Hello, can you tell me how many trips we've done in February this year?
Tác nhân sẽ thực hiện nhiều lệnh gọi công cụ để xác định các bảng phù hợp trong giản đồ và cấu trúc bảng trước khi thực thi câu lệnh SQL chính xác để lấy dữ liệu phù hợp.
Cuối cùng, nó sẽ tạo ra kết quả sau khi tạo truy vấn phù hợp và thực thi truy vấn đó trên cơ sở dữ liệu.
Theo hồ sơ trong cơ sở dữ liệu của chúng tôi, có 108 chuyến đi đã hoàn thành vào tháng 2 năm 2026.
Bạn có thể xem từng lệnh gọi công cụ thực hiện những việc gì bằng cách nhấp vào quá trình thực thi công cụ. Ví dụ: đây là truy vấn được thực thi để nhận kết quả.
Bây giờ, hãy đưa ra yêu cầu phức tạp hơn bằng cách yêu cầu so sánh kết quả với tháng trước.
How is it in comparison in numbers and mileage with the January?
Nó trả về kết quả bằng cách thực hiện các truy vấn khác nhau để phân tích kết quả và cung cấp sự khác biệt về số lượng chuyến đi và quãng đường.
In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage: January 2026: 114 trips with a total mileage of 185,597 km. February 2026: 108 trips with a total mileage of 177,893 km. This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.
Hãy thử các yêu cầu đơn giản khác bằng giao diện web ADK và xem cách ADK thực thi các truy vấn khác nhau để đạt được kết quả.
Dừng tác nhân bằng cách nhấn ctrl+c trong dòng lệnh. Bạn có thể đóng thẻ trình duyệt bằng giao diện web ADK.
Giờ đây, bạn có thể dùng thử một ứng dụng mẫu và xem cách ứng dụng này có thể được dùng làm công cụ cho nhà phân tích dữ liệu.
9. Ứng dụng mẫu
Trong cùng một kho lưu trữ được sao chép, chúng ta có một ứng dụng mẫu cho công ty Cymbol Logistic. Ứng dụng này đang sử dụng khung Python Mesop của Google .
Bạn có thể phân tích mã xử lý ứng dụng bằng cách mở tệp app.py trong trình chỉnh sửa cloud shell.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py
Trong mã, chúng ta dùng một hàm để truyền một câu lệnh mới có các biến đến tác nhân dữ liệu. Lý do là để có thể định cấu hình nó trong giao diện nếu chúng ta quyết định gọi một cơ sở dữ liệu hoặc phiên bản khác. Sau đây là định nghĩa hàm và câu lệnh.
def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
local_runner = FrontendRunner()
instruction = f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
"""
...
Sau khi kiểm tra mã, hãy nhấn nút "terminal" (thiết bị đầu cuối) để bắt đầu và kiểm thử ứng dụng của chúng ta. Ứng dụng sẽ bắt đầu trên cổng 8080. Nếu bạn muốn thay đổi cổng, hãy điều chỉnh lệnh thay đổi giá trị cổng.
Thực thi trong Cloud Shell.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080
Sau đó, hãy sử dụng tính năng xem trước trên web trong Google Cloud Shell bằng cách nhấp vào http://localhost:8080
Thao tác này sẽ mở một thẻ mới trong trình duyệt có giao diện ứng dụng.
Nhấp vào hộp đánh dấu "Enable Debug Output" (Bật đầu ra gỡ lỗi) ở trên cùng bên phải rồi nhập một câu hỏi như sau.
What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.
Sau đó, nhấn nút Submit Request.
Trợ lý này sẽ hoạt động ngầm và tạo ra thông tin đầu ra cũng như thông tin gỡ lỗi với tất cả các truy vấn do bộ công cụ MCP của chúng tôi thực hiện. Kiểm tra các truy vấn để xem quy trình.
Bạn có thể kiểm thử các tác nhân và khả năng của ứng dụng bằng cách thử nhiều câu hỏi phân tích.
Cho đến nay, bạn có thể thực hiện một số hoạt động phân tích và khám phá cơ bản bằng cách sử dụng tác nhân với MCP. Trong chương tiếp theo, bạn sẽ thử sử dụng các tính năng nâng cao hơn của AlloyDB.
10. Các hàm AI của AlloyDB
Các hàm AI của AlloyDB cho phép lọc và xếp hạng thông minh đối với văn bản và dữ liệu đa phương thức (đặc biệt là hình ảnh) cũng như mang sức mạnh của Gemini vào các truy vấn của bạn. Cụ thể, các hàm AI của AlloyDB (AI.IF và AI.RANK) có thể xuất hiện trong các câu lệnh SQL cùng với các toán tử SQL thông thường (bộ lọc, phép kết hợp, phép tổng hợp, v.v.).
Trước khi sử dụng các chức năng AI, chúng ta sẽ xem xét một lượt tìm kiếm và các lượt tổng hợp bằng phương pháp "cổ điển". Hãy thử câu lệnh sau.
Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.
Công cụ này có thể tìm thấy cột "điểm xếp hạng" trong bảng có ý kiến phản hồi của khách hàng và sử dụng cột này để xác định những người lái xe có điểm xếp hạng cao nhất. Sau đó, ứng dụng này dùng thông tin đó để lấy thêm thông tin về người lái xe.
SELECT
d.first_name || ' ' || d.last_name as driver_name,
SUM(sr.distance_km) as total_distance,
d.experience_years,
COUNT(cf.feedback_id) as positive_feedback_count
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
WHERE tt.arrival_time >= '2025-12-01'
AND tt.arrival_time < '2026-05-01'
AND cf.rating >= 4
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY positive_feedback_count DESC, total_distance DESC
LIMIT 5;
Tuy nhiên, về mặt kỹ thuật, điểm xếp hạng có thể bao gồm hoặc không bao gồm tất cả các thông số mà chúng ta muốn đánh giá. Để làm việc đó, chúng ta có thể sử dụng Các hàm AI của AlloyDB.
Toán tử AI.RANK
Hàm ai.rank() tính điểm cho mức độ phù hợp của một tài liệu với một cụm từ tìm kiếm nhất định. Bạn có thể dùng tham số này để xếp hạng hoặc xếp hạng lại kết quả của truy vấn. Bạn có thể đọc thêm về các toán tử trong tài liệu.
Sửa đổi yêu cầu và yêu cầu rõ ràng sử dụng AI.RANK trong quá trình phân tích để đánh giá người lái xe dựa trên hiệu suất và tính chuyên nghiệp của họ.
Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function? Give me top drivers names, distance, years of experience and rank for each driver.
Lệnh này có thể mất nhiều thời gian hơn một chút vì tác nhân cần tìm ra cách sử dụng hàm AI.RANK, lấy dữ liệu và áp dụng AI.RANK để sắp xếp thông tin cho phù hợp. Cuối cùng, bạn sẽ nhận được danh sách các trình điều khiển được xếp hạng theo mô hình và danh sách các truy vấn đã thực thi.
Câu hỏi đó có thể mất một chút thời gian để thực hiện, tuỳ thuộc vào đường dẫn mà mô hình chọn. Bạn có thể xem chính xác truy vấn được thực thi để lấy thông tin về các trình điều khiển trong cửa sổ gỡ lỗi.
WITH fastest_drivers AS (
SELECT
d.driver_id,
d.first_name || ' ' || d.last_name as driver_name,
d.experience_years,
SUM(sr.distance_km) as total_distance,
AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
LEFT
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
WHERE tt.arrival_time >= '2026-04-04'
AND tt.arrival_time IS NOT NULL
AND tt.departure_time IS NOT NULL
AND tt.arrival_time > tt.departure_time
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY avg_speed DESC
LIMIT 5
)
SELECT
f.driver_name,
f.total_distance,
f.experience_years,
f.avg_speed,
f.feedbacks,
(SELECT r.score
FROM ai.rank(
'semantic-ranker-fast-004',
'excellent customer service, professional, friendly, fast,
and reliable delivery reviews',
ARRAY[f.feedbacks],
1
) r
LIMIT 1) as feedback_score
FROM fastest_drivers f
ORDER BY feedback_score DESC;
Bạn có thể tiếp tục kiểm thử ứng dụng và kiểm tra các truy vấn để xem cách mà tác nhân đưa ra kết quả cuối cùng.
Đến đây là hết phần thực hành. Tôi hy vọng bạn đã xem qua tất cả các ví dụ và tìm hiểu cách sử dụng dịch vụ MCP của Google Cloud cho AlloyDB. Để MCP hoạt động cho doanh nghiệp, bạn nên kết hợp MCP với các tính năng NL2SQL của AlloyDB như mô tả trong tài liệu về AlloyDB. Bạn có thể dùng thử bằng lớp học lập trình về cách tạo câu lệnh SQL cho AlloyDB.
11. Dọn dẹp môi trường
Để tránh các khoản phí không mong muốn, bạn nên dọn dẹp các tài nguyên tạm thời. Cách đáng tin cậy nhất là xoá dự án mà bạn đã dùng để kiểm thử quy trình công việc. Tuy nhiên, bạn có thể tự giới hạn bằng cách xoá từng tài nguyên, chẳng hạn như AlloyDB.
Huỷ các phiên bản và cụm AlloyDB khi bạn hoàn tất lớp học.
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.
12. 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 tạo một cụm AlloyDB và nhập dữ liệu mẫu
- Cách bật API truy cập dữ liệu AlloyDB
- Cách bật MCP của Google Cloud cho AlloyDB NL
- Cách thêm MCP Google Cloud cho AlloyDB vào tác nhân ADK
- Cách sử dụng MCP của Google Cloud cho AlloyDB trong một ứng dụng
- Cách sử dụng các tác nhân với AlloyDBMCP để phân tích
13. Khảo sát
Kết quả: