QueryData cho AlloyDB bằng Gemini Data Analytics

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 QueryData cho AlloyDB và dùng QueryData để tạo các câu lệnh SQL chính xác và có thể dự đoán từ dữ liệu đầu vào bằng ngôn ngữ tự nhiên trong các ứng dụng dựa trên tác nhân

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

Có kiến thức cơ bản về bảng điều khiển Google Cloud
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 QueryData cho AlloyDB
Cách tạo mẫu
Cách sử dụng tính năng tìm kiếm theo khía cạnh
Cách sử dụng QueryData với các tác nhân AI

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ợ bả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

Tạo một dự án trên Google Cloud

Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.

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

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:

Ả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ề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, 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

Bạn sẽ thấy tID dự án của mình trong kết quả đầu ra:

student@cloudshell:~ (test-project-001-402417)$ gcloud config get-value project
Your active configuration is: [cloudshell-23188]
test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$

Đặ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 \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.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 \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.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 (tập lệnh này sẽ triển khai tất cả các tài nguyên cần thiết) hoặc bạn có thể tự triển khai 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-querydata"

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 --public-ip

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) và triển khai cụm AlloyDB cũng như một phiên bản chính có IP công khai và riêng tư. IP công khai chỉ có sẵn cho các mạng được uỷ quyền hoặc bằng cách sử dụng proxy xác thực AlloyDB. Bạn có thể đọc thêm về địa chỉ IP công khai trong tài liệu. Là đầu ra, tập lệnh phải 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"

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

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",
 }'

Bật tính năng xác thực IAM

Chúng tôi sẽ sử dụng phương thức xác thực IAM cho các công cụ dựa trên tác nhân và bạn cần bật phương thức xác thực IAM trên phiên bản này, đồng thời thêm chính mình làm người dùng cơ sở dữ liệu. Trước khi bật tính năng xác thực IAM ở cấp phiên bản, vui lòng đợi cho đến khi bước trước đó bật API quyền truy cập dữ liệu hoàn tất. Trạng thái của phiên bản phải là màu xanh lục.

Chúng ta bắt đầu bằng cách bật IAM ở cấp phiên 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)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags password.enforce_complexity=on,alloydb.iam_authentication=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Thêm chính bạn làm người dùng AlloyDB:

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED

Đó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 và xác thực IAM. Sau đó, hãy nhấp vào nút "Xác thự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 phương thức xác thực IAM.

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, đồng thời làm việc với các tập hợp ngữ cảnh QueryData.

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ữ đã sao chép vào cơ sở dữ liệu AlloyDB. Bạn sẽ cần tạo một bộ chứa Cloud Storage cho việc đó và 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 nén 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-querydata"
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à kết nối với phiên bản AlloyDB bằng Bộ công cụ MCP cho cơ sở dữ liệu.

Cài đặt Bộ công cụ MCP cho cơ sở dữ liệu

Bộ công cụ MCP dành cho cơ sở dữ liệu là một dự án nguồn mở cung cấp dịch vụ hỗ trợ MCP cho nhiều công cụ cơ sở dữ liệu, bao gồm cả AlloyDB cho PostgreSQL. Bạn có thể đọc về MCP Toolbox trong tài liệu.

Bạn cần tải phiên bản phần mềm mới nhất xuống cho nền tảng của mình. Để biết phiên bản mới nhất, hãy xem trang phát hành. Ví dụ sau đây cho thấy cách tải MCP Toolbox phiên bản 31 xuống Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
export VERSION=0.31.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Bạn cần chuẩn bị một tệp cấu hình cho hộp công cụ. Chúng ta có một tệp tools.yaml.example mẫu trong thư mục hiện tại và sẽ chuẩn bị tệp tools.yaml bằng cách thay thế 2 phần giữ chỗ bằng mã dự án và khu vực.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    tools.yaml.example > tools.yaml

Khởi động Bộ công cụ MCP cho cơ sở dữ liệu

Giờ đây, bạn có thể khởi động hộp công cụ MCP bằng tệp cấu hình đã chuẩn bị.

Mở một thẻ mới trong Google Cloud Shell bằng cách nhấn vào nút "+" ở đầu giao diện Google Cloud Shell.

Trong thẻ mới, hãy chuyển sang thư mục có tệp nhị phân của hộp công cụ và tệp cấu hình tools.yaml rồi khởi động máy chủ MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config tools.yaml

Bạn sẽ thấy trong đầu ra "Server ready to serve!" (Máy chủ đã sẵn sàng phân phát!) tương tự như sau.

2026-03-30T10:28:03.614374-04:00 INFO "Initialized 1 sources: cymbal-logistics-sql-source"
2026-03-30T10:28:03.614517-04:00 INFO "Initialized 0 authServices: "
2026-03-30T10:28:03.614531-04:00 INFO "Initialized 0 embeddingModels: "
2026-03-30T10:28:03.614657-04:00 INFO "Initialized 2 tools: execute_sql_tool, list_cymbal_logistics_schemas_tool"
2026-03-30T10:28:03.614711-04:00 INFO "Initialized 1 toolsets: default"
2026-03-30T10:28:03.614723-04:00 INFO "Initialized 0 prompts: "
2026-03-30T10:28:03.614779-04:00 INFO "Initialized 1 promptsets: default"
2026-03-30T10:28:03.616214-04:00 INFO "Server ready to serve!"

Kiểm tra mã nguồn của Agent

Trong thẻ đầu tiên của thư mục 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-querydata"
edit ~/$REPO_NAME/$SOURCE_DIR/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.

MCP_SERVER_URL = "http://127.0.0.1:5000"
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}")

mcp_toolset = ToolboxToolset(
    server_url=MCP_SERVER_URL,
)

Và trong mã tác nhân, bộ công cụ MCP được đưa vào dưới dạng tham số tools cho tác nhân. 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}
    """,
    tools=[mcp_toolset],
)

Sau khi kiểm tra mã, hãy chuyển về thiết bị đầu cuối bằng cách nhấn vào nút "Open terminal" (Mở thiết bị đầu cuối) ở trên cùng bên phải của cửa sổ trình chỉnh sửa.

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 cung cấp một cách thuận tiện để kiểm thử và khắc phục sự cố 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-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
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ử NL2SQL mà không có QueryData cho AlloyDB

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 bộ công cụ MCP cho cơ sở dữ liệu 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?

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 đồ bằng cách sử dụng list_cymbal_logistics_schemas_tool và execute_sql_tool, thực hiện nhiều câu lệnh SQL để lấy dữ liệu phù hợp.

Cuối cùng, nó sẽ tạo ra kết quả chính xác sau khi tạo truy vấn phù hợp và thực thi truy vấn đó trên cơ sở dữ liệu.

Chúng tôi đã hoàn thành 108 chuyến đi vào tháng 2 năm 2026. Hồ sơ của chúng tôi cho thấy không có chuyến đi nào được lên lịch hoặc hoàn thành vào tháng 2 năm 2025.

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

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.

Bạn cũng có thể dừng MCP Toolbox ở thẻ thứ hai bằng cách nhấn tổ hợp phím tắt ctrl+c tương tự rồi đóng thẻ thứ hai.

Trong bước tiếp theo, chúng ta sẽ tạo ngữ cảnh QueryData để cải thiện phản hồi và hiệu suất NL2SQL.

9. Tạo QueryData ContextSet

Ở bước trước, bạn có thể thấy mô hình AI đã thực hiện nhiều lệnh gọi đến giản đồ thông tin của cơ sở dữ liệu để tìm ra bảng và cột mà mô hình nên dùng để tạo truy vấn SQL. Để cải thiện hiệu suất, độ chính xác và giúp kết quả dễ dự đoán hơn, chúng tôi sẽ thêm ngữ cảnh QueryData xác định truy vấn cần thực thi để phản hồi một yêu cầu nhất định.

Tạo mẫu nhắm đến mục tiêu

QueryData ContextSet là một tệp JSON chứa các mẫu truy vấn và khía cạnh cung cấp dữ liệu và hướng dẫn cần thiết cho mô hình AI để sử dụng truy vấn SQL hoặc các phần truy vấn SQL chính xác nhằm đạt được các mục tiêu được yêu cầu dựa trên mẫu truy vấn và cấu trúc dữ liệu.

Bạn bắt đầu từ một mẫu được nhắm đến. Tạo tệp bằng trình chỉnh sửa Cloud Shell. Thực thi trong cửa sổ dòng lệnh Cloud Shell.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

Sau đó, hãy chèn mẫu cho truy vấn bằng ngôn ngữ tự nhiên mà chúng ta đã dùng trong chương trước – "How many trips we've done in February?" (Chúng ta đã thực hiện bao nhiêu chuyến đi trong tháng 2?)

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a given month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ]
}

Sau đó, hãy tải mẫu xuống máy tính từ Cloud Shell bằng nút tải xuống.

Tải các tập hợp bối cảnh QueryData

Để sử dụng các tập hợp ngữ cảnh QueryData, chúng ta cần tải chúng lên cơ sở dữ liệu.

Mở AlloyDB Studio. Ở cuối bảng điều khiển bên trái, bạn sẽ thấy biểu tượng QueryData Context và dấu ba chấm.

Nhấp vào biểu tượng ba dấu chấm đó rồi chọn Tạo bối cảnh. Một hộp thoại sẽ mở ra để bạn nhập

Tên: cymbal_context_set
Thông tin mô tả: Cymbal Logistic Query Data
Tải tệp ngữ cảnh lên: nhấp vào nút "Browse" rồi chọn tệp JSON có QueryData ContextSet

Khi bạn nhấn nút lưu, có thể mất một khoảng thời gian để khởi động bộ nhớ bối cảnh nếu đây là lần đầu tiên bạn thực hiện.

Bạn sẽ thấy nội dung đã tải xuống và nếu nhấp vào 3 nút dọc ở bên phải, bạn sẽ thấy các thao tác có thể thực hiện. Trong chương tiếp theo, chúng ta sẽ bắt đầu từ thao tác "Test context" (Bối cảnh kiểm thử).

10. Kiểm thử Bộ ngữ cảnh QueryData

Mẫu kiểm thử

Sử dụng thao tác "Test context" để kiểm thử ngữ cảnh của chúng tôi trong AlloyDB Studio. Khi bạn nhấp vào "Test context" (Bối cảnh kiểm thử), một cửa sổ trình chỉnh sửa AlloyDB Studio mới sẽ mở ra với tiêu đề "cymbal_context_set" và lời mời tạo SQL của Gemini có tiêu đề "Generate SQL using QueryData context: cymbal_context_set ". Nhấp vào mục tạo SQL rồi nhập

Hello, can you tell me how many trips we've done in February?

Và khi SQL được tạo, hãy nhấn nút "Insert".

Bạn sẽ thấy chính xác câu hỏi mà chúng ta đã đặt cho mẫu ngữ cảnh trước đó.

-- How many trips we've done in February?
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'

Hãy thử thay thế tháng bằng "January" (tháng 1) rồi kiểm tra câu lệnh SQL được tạo. Thao tác này sẽ sử dụng tháng làm tham số cho ý định được tham số hoá và tự động điều chỉnh câu lệnh SQL.

Chúng tôi đã thử một mẫu cho một truy vấn và mẫu này hoạt động khi chúng tôi biết loại yêu cầu mà người dùng mong đợi. Nhưng đôi khi, việc chỉ hướng dẫn một phần của truy vấn (chẳng hạn như điều kiện hoặc bộ lọc) sẽ hữu ích khi chúng ta muốn sử dụng một thứ tự hoặc mệnh đề cụ thể cho một ý định được xác định lại.

Ví dụ: nếu yêu cầu trả về dữ liệu cho "tháng trước", chúng ta muốn nhận báo cáo cho tháng dương lịch trước đó từ ngày 1 đến ngày cuối cùng của tháng đó, chứ không phải 30 ngày qua.

Chúng ta có thể thêm các khía cạnh như một đoạn mã SQL vào cấu hình ContextSet cùng với mẫu mà chúng ta đã thêm trước đó. Mở querydata_cymbal_contextset.json.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

Thêm các khía cạnh sau các mẫu hiện có của chúng tôi. Nội dung thu được trong tệp sẽ là nội dung sau

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a certain month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)",
      "intent": "last month",
      "manifest": "Records for the previous calendar month",
      "parameterized": {
        "parameterized_intent": "previous calendar month",
        "parameterized_sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)"
      }
    }
  ]
}

Lưu tệp rồi tải tệp đó lên máy tính.

Sau đó, hãy sử dụng thao tác theo bối cảnh của truy vấn "Chỉnh sửa bối cảnh" và tải tệp đã sửa đổi lên để thay thế tập hợp bối cảnh cũ bằng tập hợp bối cảnh mới.

Bây giờ, hãy thử sử dụng lại ngữ cảnh kiểm thử và tạo một câu lệnh SQL bằng ý định "tháng trước". Ví dụ: nếu bạn tạo một SQL cho cụm từ "show trucks trips for the last month"", thì SQL đó sẽ sử dụng điều kiện mà chúng ta cung cấp dưới dạng một thuộc tính trong tệp cymbal_context.json.

Bạn sẽ nhận được nội dung tương tự như sau:

-- show trucks trips for the last month
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)

Vậy làm cách nào để sử dụng tính năng này với Tác nhân AI? Trong chương tiếp theo, chúng ta sẽ cung cấp ngữ cảnh Dữ liệu truy vấn cho các Đặc vụ AI.

11. QueryData bằng tác nhân AI

Bạn sẽ sử dụng cùng một Data Agent nhưng giờ đây, bộ công cụ MCP sẽ được định cấu hình để sử dụng QueryData ContextSet.

Chuẩn bị và khởi động Bộ công cụ MCP cho cơ sở dữ liệu

Chúng ta cần một tệp cấu hình mới cho MCP Toolbox. Tệp này sẽ sử dụng Gemini Data Analytics API và AlloyDB làm nguồn cơ sở dữ liệu.

Chạy trong thiết bị đầu cuối:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    querydata.yaml.example > querydata.yaml

Chuyển sang trình chỉnh sửa và tìm tệp querydata.yaml. Tệp cấu hình querydata.yaml sẽ có dạng như sau, ngoại trừ mã dự án và khu vực sẽ phản ánh môi trường của bạn. Tuy nhiên, bạn vẫn cần cập nhật giá trị contextSetId và thay thế phần giữ chỗ "<add-context-set-id>" bằng giá trị từ bảng điều khiển.

kind: sources
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: test-project-001-402417
---
kind: tools
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
location: "us-central1"
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
context:
  datasourceReferences:
    alloydb:
      databaseReference:
        projectId: "test-project-001-402417"
        region: "us-central1"
        clusterId: "alloydb-aip-01"
        instanceId: "alloydb-aip-01-pr"
        databaseId: "quickstart_db"
      agentContextReference:
        contextSetId: "<add-context-set-id>"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

Để tìm ContextSet ID, hãy nhấp vào nút chỉnh sửa cho bộ bối cảnh như trong hình.

Bạn sẽ thấy mã nhận dạng tập hợp bối cảnh ở trên cùng trong thẻ mới ở bên phải.

Bạn nên đặt đường dẫn đầy đủ đó để thay thế phần giữ chỗ "<add-context-set-id>" trong tệp querydata.yaml.

Chuyển về cửa sổ thiết bị đầu cuối.

Mở một thẻ mới trong Google Cloud Shell bằng cách nhấn vào nút "+" ở đầu giao diện Google Cloud Shell.

Trong thẻ mới, hãy chuyển sang thư mục có tệp nhị phân hộp công cụ và tệp cấu hình tools.yaml rồi khởi động máy chủ MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config querydata.yaml

Chạy tác nhân ADK

Trong thẻ Cloud Shell đầu tiên, hãy khởi động tác nhân.

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Và khi quá trình này bắt đầu, hãy nhấp lại vào đường liên kết đến http://127.0.0.1:8000 .

Bạn sẽ thấy giao diện quen thuộc của tác nhân xem trước web ADK. Đăng chính xác cùng một truy vấn như lần trước.

Hello, can you tell me how many trips we've done in February?

Và xem quy trình làm việc của nhân viên hỗ trợ. Nếu mọi thứ được định cấu hình chính xác, bạn sẽ thấy nội dung tương tự như sau.

Yêu cầu mất nhiều lượt trong lần gần đây nhất đã được chuyển đổi thành một lệnh gọi đến công cụ MCP và được thực thi bằng các câu lệnh SQL có thể dự đoán.

Bạn có thể kiểm thử các khía cạnh đã định cấu hình bằng cách sử dụng yêu cầu như

how trucks trips for the last month

Trong đầu ra, nếu nhấp vào thao tác công cụ, bạn có thể thấy thao tác đó đang sử dụng cùng một công cụ và áp dụng các khía cạnh để nhận được kết quả.

Đế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 QueryData cho AlloyDB. Công nghệ được cung cấp giúp bạn dự đoán và tin tưởng vào khối lượng công việc theo hướng tác nhân và việc tạo SQL.

12. 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 đang thử nghiệm quy trình. 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 thực thể và cụm AlloyDB khi bạn hoàn thành 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 các biến dự án và 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.

13. 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 QueryData cho AlloyDB
Cách tạo mẫu
Cách sử dụng tính năng tìm kiếm theo khía cạnh
Cách sử dụng QueryData với các tác nhân AI

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

QueryData cho AlloyDB bằng Gemini Data Analytics

1. Giới thiệu

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

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

Bạn cần có

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

Thiết lập dự án

Tạo một dự án trên Google Cloud

Khởi động Cloud Shell

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

Bật API

4. Triển khai AlloyDB

Triển khai AlloyDB bằng tập lệnh tự động

5. Chuẩn bị cơ sở dữ liệu

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

Bật Data Access API

Bật tính năng xác thực IAM

Kết nối với AlloyDB Studio

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

Kết nối với quickstart_db

6. Dữ liệu mẫu

Tạo vùng lưu trữ

Tải dữ liệu

7. Làm việc với Data Agent

Cài đặt Bộ công cụ MCP cho cơ sở dữ liệu

Khởi động Bộ công cụ MCP cho cơ sở dữ liệu

Kiểm tra mã nguồn của Agent

Khởi động nhân viên hỗ trợ

8. Kiểm thử NL2SQL mà không có QueryData cho AlloyDB

9. Tạo QueryData ContextSet

Tạo mẫu nhắm đến mục tiêu

Tải các tập hợp bối cảnh QueryData

10. Kiểm thử Bộ ngữ cảnh QueryData

Mẫu kiểm thử

Tạo các khía cạnh QueryData

11. QueryData bằng tác nhân AI

Chuẩn bị và khởi động Bộ công cụ MCP cho cơ sở dữ liệu

Chạy tác nhân ADK

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

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

Xoá bản sao lưu AlloyDB

13. Xin chúc mừng

Nội dung đã đề cập

14. Khảo sát

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