1. Tổng quan
Trong Phần 1, chúng tôi đã chuyển đổi thành công các tệp PDF hỗn loạn, không có cấu trúc thành các bảng sạch, thông minh và có cấu trúc trong BigQuery bằng Knowledge Catalog và DataScan. Giờ đây, chúng ta đã có một kho dữ liệu mạnh mẽ. Trong Phần 2, chúng tôi đã thiết lập AlloyDB làm nền tảng giao dịch và liên kết các bảng BigQuery vào đó, tạo ra một lớp dữ liệu hợp nhất mà không cần sao chép một byte nào.
Hôm nay, chúng ta sẽ xây dựng bộ não. Chúng tôi đang tạo một ứng dụng Multi-Agent (Ứng dụng nhiều tác nhân) – "FroyoOS Store Manager" (Trình quản lý cửa hàng FroyoOS) – nằm trên lớp dữ liệu này để trả lời câu hỏi, kiểm tra chất gây dị ứng và xử lý đơn đặt hàng trực tiếp.
Thách thức: Tách AI khỏi Agent
Khi xây dựng một AI Agent cần trao đổi với cơ sở dữ liệu, mẫu chống phổ biến nhất là buộc dữ liệu và logic AI trực tiếp vào ứng dụng Python của bạn. Điều này khiến ứng dụng của bạn dễ bị lỗi, không an toàn và cực kỳ khó duy trì khi cấu trúc dữ liệu của bạn phát triển.
Để giải quyết vấn đề này, chúng tôi đang sử dụng Bộ công cụ Giao thức ngữ cảnh mô hình (MCP). Bộ công cụ MCP đóng vai trò là lớp trừu tượng dữ liệu hợp nhất của chúng tôi. Chúng ta xác định các thao tác trên cơ sở dữ liệu một cách khai báo trong tệp tools.yaml đơn giản. Chúng tôi triển khai hộp công cụ này dưới dạng một điểm cuối không máy chủ, an toàn trên Google Cloud Run. AI Agent của chúng tôi chỉ cần kết nối với điểm cuối này và nói "Thực thi công cụ "place_order"".
Sức mạnh của HTAP
Trước khi bắt đầu xây dựng tác nhân phần mềm, hãy nói về lý do tiêu đề của bài đăng này đặc biệt đề cập đến HTAP (Xử lý giao dịch/phân tích kết hợp).
Trong một cấu trúc truyền thống, nếu một AI Agent cần xử lý đơn đặt hàng trực tiếp của người dùng (tải công việc OLTP giao dịch) và tham chiếu chéo hàng nghìn ánh xạ thành phần phức tạp (tải công việc OLAP phân tích), thì ứng dụng Python của bạn sẽ phải xử lý các kết nối đến hai cơ sở dữ liệu hoàn toàn khác nhau. Điều này tạo ra độ trễ nghiêm trọng, chi phí bảo mật và khả năng quản lý trạng thái không ổn định.
Chúng tôi đã biến AlloyDB thành một HTAP mạnh mẽ bằng cách liên kết kho dữ liệu BigQuery trực tiếp vào PostgreSQL. Nhờ kiến trúc HTAP này, tác nhân AI của chúng tôi hiện chỉ cần giao tiếp với một điểm cuối cơ sở dữ liệu. Bạn có thể chèn các giao dịch trực tiếp vào bảng live_orders và chạy các lượt quét phân tích chuyên sâu đối với tập dữ liệu froyo_data BigQuery liên kết ngay lập tức mà không cần sao chép một byte dữ liệu nào. Hãy xem cách chúng ta cung cấp công cụ này cho AI.
Hãy bắt đầu xây dựng!
Kiến thức bạn sẽ học được
- Cách thiết lập Cụm, Thực thể và Mạng AlloyDB chỉ bằng một nút nhấn
- Cách thiết lập tiện ích để chuẩn bị cho việc liên kết
- Cách thiết lập liên kết từ BigQuery đến AlloyDB
- Kiểm thử
Yêu cầu
2. Trước khi bắt đầu
Tạo dự án
- 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 rằng 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.
- Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud.
- Sau khi kết nối với Cloud Shell, bạn có thể kiểm tra để đảm bảo rằng bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:
gcloud auth list
- Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.
gcloud config list project
- Nếu bạn muốn xác thực
gcloud auth login
- Nếu bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- Bật các API bắt buộc: Chạy lệnh này để bật tất cả các API bắt buộc:
gcloud services enable \
alloydb.googleapis.com \
bigquery.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com
Các lỗi thường gặp và cách khắc phục sự cố
Hội chứng "Dự án ma" | Bạn đã chạy |
Rào chắn thanh toán | Bạn đã bật dự án nhưng quên tài khoản thanh toán. AlloyDB là một công cụ hiệu suất cao; công cụ này sẽ không khởi động nếu "bình xăng" (thanh toán) trống. |
Độ trễ API Propagation | Bạn đã nhấp vào "Bật API", nhưng dòng lệnh vẫn hiển thị |
Quota Quags | Nếu đang sử dụng tài khoản dùng thử hoàn toàn mới, bạn có thể đạt đến hạn mức theo vùng cho các thực thể AlloyDB. Nếu |
3. Chuẩn bị dữ liệu
Đảm bảo rằng dữ liệu có cấu trúc mà chúng tôi trích xuất từ các tệp PDF không có cấu trúc có trong BigQuery và liên kết AlloyDB của dữ liệu BigQuery cũng được thiết lập và kiểm thử. Nếu bạn chưa hoàn tất các bước đó, thì đây là thời điểm thích hợp để thực hiện các bước đơn giản đó từ đây và đây cho phần 1 và phần 2 tương ứng.
Lưu ý:
Nếu đang thử lớp học lập trình này, bạn không nên thực hiện bước dọn dẹp của phần 2 (xoá bước cụm và phiên bản) vì chúng ta cần có hoạt động điều phối AlloyDB cho hệ thống dựa trên tác nhân được minh hoạ ở đây.
Ngoài dữ liệu này mà chúng ta đã tạo ở phần 2, chúng ta cần tạo thêm một bảng trong phiên bản AlloyDB. Truy cập vào AlloyDB Studio bằng đường liên kết:
https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio
Thay đổi tên cụm trong đường liên kết ở trên nếu bạn đang sử dụng một cụm khác.
Trong AlloyDB Studio, trong thẻ Trình chỉnh sửa truy vấn mới, hãy chạy câu lệnh sau:
CREATE TABLE live_orders (
order_id SERIAL PRIMARY KEY,
customer_name VARCHAR(100),
product_id VARCHAR(100),
quantity INT,
order_status VARCHAR(50) DEFAULT 'Pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
Thao tác này sẽ tạo bảng live_orders trong cơ sở dữ liệu của bạn.
4. Xác định lớp trừu tượng (tools.yaml)
Trước tiên, chúng ta chính thức đăng ký các thao tác cơ sở dữ liệu. Chúng tôi tạo một tệp tools.yaml để xác định cách tác nhân của chúng tôi tương tác với AlloyDB. AlloyDB có cả dữ liệu giao dịch và dữ liệu phân tích (dữ liệu phân tích từ liên kết BigQuery).
- Chuyển đến Cloud Shell Terminal. Chuyển sang chế độ Trình chỉnh sửa.
- Tạo một thư mục mới trong thư mục gốc: "froyo-agent"
- Trong thư mục này, hãy tạo một tệp tools.yaml rồi dán nội dung sau: (thay thế bằng các giá trị của riêng bạn cho dự án, cụm, phiên bản và mật khẩu)
# tools.yaml
sources:
alloydb-source:
kind: "alloydb-postgres"
project: "*******"
region: "us-central1"
cluster: "my-alloydb-cluster"
instance: "my-primary-inst"
database: "postgres"
user: "postgres"
password: "*******"
ipType: "private"
tools:
check_allergens:
kind: postgres-sql
source: alloydb-source
description: Queries the federated BigQuery tables to find allergens for a product.
statement: |
SELECT a.allergen_name
FROM consistsof c
INNER JOIN product p ON c.product_id = p.product_id
INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
WHERE UPPER(p.product_name) LIKE UPPER($1)
parameters:
- name: product_name
type: string
description: The name of the product to check. (e.g., '%Midnight%')
place_order:
kind: postgres-sql
source: alloydb-source
description: Inserts a new live transaction into the native AlloyDB orders table.
statement: |
INSERT INTO live_orders (customer_name, product_id, quantity)
VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
parameters:
- name: customer_name
type: string
description: The name of the customer placing the order.
- name: product_name
type: string
description: The name of the product being ordered.
- name: quantity
type: integer
description: The quantity of the product being ordered.
toolsets:
alloydb_tools:
- check_allergens
- place_order
Chúng tôi chỉ cung cấp 2 công cụ cho trợ lý ảo là kiểm tra chất gây dị ứng và đặt hàng.
5. Triển khai Hộp công cụ lên Cloud Run
Để cung cấp công cụ này cho ứng dụng của mình, chúng tôi triển khai hộp công cụ một cách an toàn bằng cách sử dụng gcloud CLI. Thao tác này sẽ tạo điểm cuối của lớp trừu tượng.
- Chuyển sang Cloud Shell Terminal rồi chuyển đến thư mục làm việc bằng cách chạy lệnh:
cd froyo-agent
- Lưu tools.yaml trong một khoá bí mật có tên là "tools-froyo":
gcloud secrets create tools-froyo --data-file=tools.yaml
- Triển khai vùng chứa MCP Toolbox lên Cloud Run
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox-froyo \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-froyo:latest" \
--args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--network easy-alloydb-vpc \
--subnet easy-alloydb-subnet \
--allow-unauthenticated \
--vpc-egress private-ranges-only
Bạn cần thay thế các giá trị "network" và "subnet" nếu đã sử dụng các giá trị khác với những giá trị mà chúng tôi đã định cấu hình trong phần 2 của lớp học lập trình.
- Ghi lại URL Cloud Run nhận được (ví dụ: https://toolbox-froyo-xxx.run.app).
6. Phần phụ trợ của tác nhân (app.py)
Khi cơ sở dữ liệu của chúng ta được trừu tượng hoá, mã Python có thể hoàn toàn tập trung vào việc điều phối và suy luận.
Chúng ta sẽ sử dụng Bộ công cụ phát triển tác nhân (ADK) cùng với Flask. ADK cung cấp bộ nhớ phiên cấp doanh nghiệp (InMemorySessionService), nghĩa là tác nhân của chúng tôi sẽ ghi nhớ ngữ cảnh của cuộc trò chuyện. Ứng dụng này tích hợp nguyên bản với ToolboxSyncClient để kéo các công cụ của chúng tôi một cách liền mạch từ Cloud Run.
Sau đây là app.py của bạn:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py
Ứng dụng Python Flask đơn giản kết nối tác nhân ADK với các công cụ mà chúng ta đã xác định trong Bộ công cụ. Bộ công cụ này sẽ tương tác với AlloyDB (cũng như dữ liệu liên kết BigQuery) và phản hồi người dùng.
7. Giao diện người dùng và cách chạy ứng dụng
Để mang đến trải nghiệm phù hợp cho các Nhà quản lý cửa hàng, chúng tôi đã tạo ra một giao diện người dùng (UI) theo phong cách kính mờ (templates/index.html) bóng bẩy, có thanh bên danh mục sản phẩm trực tiếp và giao diện trò chuyện tương tác.
Bạn có thể tìm thấy index.html trong tệp repo tại đây:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html
Trước khi chạy ứng dụng, hãy đảm bảo bạn đã cài đặt các phần phụ thuộc bằng cách tạo tệp requirements.txt có nội dung sau:
Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv
và tệp .env của bạn được điền sẵn:
GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***
Trong Cloud Shell Terminal, hãy đảm bảo rằng bạn đang ở trong thư mục dự án, rồi chạy lần lượt các lệnh sau:
Cài đặt các phần phụ thuộc:
pip install -r requirements.txt
Thực thi tệp python:
python app.py
Nhấp vào đường liên kết xuất hiện trong thiết bị đầu cuối hoặc mở http://localhost:8080!
8. Bài kiểm tra cuối cùng
Hãy nhấp vào một sản phẩm trong danh mục để hỏi trợ lý ảo:
Does Midnight Swirl have any allergens?
Bạn sẽ thấy phản hồi:
Hậu trường:
- ADK Agent nhận được câu lệnh và quyết định sử dụng công cụ check_allergens.
- Ứng dụng này gọi MCP Toolbox một cách an toàn trên Cloud Run.
- Hộp công cụ sẽ thực thi truy vấn trong AlloyDB, truy vấn này sẽ liên kết ngay lập tức với BigQuery để quét các mối quan hệ phức tạp mà chúng ta đã xây dựng trong Phần 1.
- Cơ sở dữ liệu trả về "Đậu nành", mà Agent tóm tắt gọn gàng trong giao diện người dùng.
Tiếp theo, chúng ta nói:
Order 2 Midnight Swirls for Alice.
Trợ lý truyền chuỗi "Midnight Swirl" đến Hộp công cụ. SQL cơ bản sẽ tự động phân giải chuỗi thành một mã nhận dạng số nguyên thông qua BigQuery, chèn đơn đặt hàng đang hoạt động vào AlloyDB và xác nhận giao dịch.
Kho lưu trữ mã
9. Dọn dẹp
Sau khi hoàn tất bài thực hành này, đừng quên xoá cụm và phiên bản AlloyDB.
Thao tác này sẽ dọn dẹp cụm cùng với(các) phiên bản của cụm.
10. Chúc mừng bạn đã có được một Agent!
Hãy nghĩ về những gì chúng ta vừa đạt được:
Hệ thống dựa trên tác nhân được điều phối tốt của chúng tôi chỉ tương tác với MCP Toolbox for Databases. Ở chế độ nền, thao tác này xử lý lệnh gọi công cụ và dữ liệu cho logic AI của ứng dụng, giúp quy trình diễn ra đơn giản:
- Ứng dụng giao dịch của chúng tôi (chạy trên AlloyDB) có thể xử lý các phiên hoạt động của người dùng diễn ra nhanh chóng và đồng thời.
- Khi cần dữ liệu phân tích chuyên sâu hoặc ngữ cảnh lịch sử (chẳng hạn như thông tin chi tiết về nhà cung cấp hoặc các mối liên kết phức tạp giữa các thành phần), tác nhân này sẽ truy vấn froyo_dataschema của BigQuery.
- Zero ETL. Không có quy trình xử lý dữ liệu nào bị gián đoạn. Không có cơ sở dữ liệu bị lệch. Chúng tôi lưu trữ một lần (trong BQ) và tính toán khi cần.
Giờ đây, khi đã hoàn tất nền tảng dữ liệu và tác nhân (cả phân tích và giao dịch), chúng ta hãy chuyển sang phần tiếp theo.
Các bước tiếp theo
Tác nhân của chúng tôi hoạt động hoàn hảo... trong trường hợp lý tưởng. Trong Phần 4, chúng ta sẽ xây dựng một pipeline Đánh giá tác nhân để kiểm tra nghiêm ngặt tính hợp lệ, tính bám sát nguồn và hiệu suất của hệ thống tác nhân. Hẹn gặp bạn ở lớp học này nhé!