Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cung cấp năng lượng cho Hệ thống dựa trên tác nhân bằng HTAP trong AlloyDB

1. Tổng quan

Trong Phần 1, chúng ta đã 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 Danh mục tri thức và DataScan. Giờ đây, chúng ta đã có một kho dữ liệu mạnh mẽ. Trong Phần 2, chúng ta đã thiết lập AlloyDB làm xương sống giao dịch và liên kết các bảng BigQuery vào đó, tạo 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 ta đang tạo một ứng dụng Nhiều tác nhân – "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ử thách: Tách AI khỏi Tác nhân

Khi xây dựng một Tác nhân AI cần giao tiếp với cơ sở dữ liệu, mẫu phản đối phổ biến nhất là buộc dữ liệu và logic AI trực tiếp vào ứng dụng Python. Điều này khiến ứng dụng của bạn dễ bị hỏng, không an toàn và cực kỳ khó duy trì khi kiến trúc dữ liệu của bạn phát triển.

Để giải quyết vấn đề này, chúng ta sẽ sử dụng Bộ công cụ Giao thức ngữ cảnh mô hình (MCP). Bộ công cụ MCP hoạt động như lớp trừu tượng dữ liệu hợp nhất của chúng ta. Chúng ta khai báo các thao tác cơ sở dữ liệu một cách khai báo trong một tệp tools.yaml đơn giản. Chúng ta triển khai bộ công cụ này dưới dạng một điểm cuối an toàn, không máy chủ trên Google Cloud Run. Tác nhân AI của chúng ta 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, 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 kiến trúc truyền thống, nếu một Tác nhân AI 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 mối liên kết 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à quản lý trạng thái dễ bị hỏng.

Chúng ta đã biến AlloyDB thành một nguồn năng lượng HTAP bằng cách liên kết trực tiếp kho dữ liệu BigQuery vào PostgreSQL. Do kiến trúc HTAP này, Tác nhân AI của chúng ta hiện chỉ cần giao tiếp với một điểm cuối cơ sở dữ liệu. Tác nhân này 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 nặng đối với tập dữ liệu BigQuery froyo_data được liên kết trong cùng một lần, mà không cần sao chép một byte dữ liệu nào. Hãy xem cách chúng ta hiển thị 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ấp
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 sang AlloyDB
Thử nghiệm

Yêu cầu

Một trình duyệt, chẳng hạn như Chrome hoặc Firefox.
Một dự án trên Google Cloud đã bật tính năng thanh toán.
Hiểu biết cơ bản về SQL.

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 bạn đã bật tính năng thanh toán cho một dự án hay chưa.

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 Activate Cloud Shell (Kích hoạt Cloud Shell) ở đầu bảng điều khiển Cloud.

Hình ảnh nút Kích hoạt Cloud Shell

Sau khi kết nối với Cloud Shell, bạn hãy kiểm tra để đảm bảo rằng bạn đã 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 dự án của bạn chưa được thiết lập, hãy sử dụng lệnh sau để thiết lập:

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

Lưu ý và khắc phục sự cố

Hội chứng "Dự án ảo"	Bạn đã chạy `gcloud config set project`, nhưng thực ra bạn đang xem một dự án khác trong giao diện người dùng Bảng điều khiển. Hãy kiểm tra mã dự án trong trình đơn thả xuống ở trên cùng bên trái!
Rào cả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ễ Truyền tải API	Bạn đã nhấp vào "Bật API", nhưng dòng lệnh vẫn cho biết `Service Not Enabled` (Dịch vụ chưa được bật). Hãy đợi 60 giây. Cloud cần một chút thời gian để kích hoạt các nơ-ron.
Hạn mức	Nếu đang sử dụng tài khoản dùng thử hoàn toàn mới, bạn có thể gặp phải hạn mức theo khu vực cho các thực thể AlloyDB. Nếu `us-central1` không thành công, hãy thử `us-east1`.

3. Chuẩn bị dữ liệu

Đảm bảo rằng dữ liệu có cấu trúc mà chúng ta đã 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 bạn đ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 (xóa cụm và bước thực thể) vì chúng ta cần điều phối AlloyDB cho hệ thống tác nhân được minh hoạ ở đây.

Ngoài dữ liệu này mà chúng ta đã tạo trong phần 2, chúng ta cần tạo thêm một bảng trong thực thể AlloyDB. Chuyển đến 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 một 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
);

Câu lệnh 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 ta tạo một tệp tools.yaml xác định cách tác nhân của chúng ta tương tác với AlloyDB có cả dữ liệu giao dịch và 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"
Bên trong thư mục, hãy tạo một tệp tools.yaml và 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, thực thể 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 ta đã giới hạn khả năng của tác nhân ở 2 công cụ – kiểm tra chất gây dị ứng và đặt hàng.

5. Triển khai Bộ công cụ lên Cloud Run

Để cung cấp công cụ này cho ứng dụng của chúng ta, chúng ta sẽ triển khai bộ công cụ một cách an toàn bằng CLI gcloud. Thao tác này sẽ tạo điểm cuối lớp trừu tượng của chúng ta.

Chuyển sang Cloud Shell Terminal và chuyển đến thư mục đang hoạt động bằng cách chạy lệnh:

cd froyo-agent

Lưu tools.yaml trong một 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 Bộ công cụ MCP 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 ta đã định cấu hình trong lớp học lập trình Phần 2.

Ghi lại URL Cloud Run kết quả (ví dụ: https://toolbox-froyo-xxx.run.app).

Chúng ta sẽ sử dụng điểm cuối Bộ công cụ MCP đã triển khai này trong bước định cấu hình tác nhân.

6. Phần phụ trợ tác nhân (app.py)

Với cơ sở dữ liệu được trừu tượng hoá, mã Python của chúng ta có thể tập trung hoàn toàn vào việc điều phối và suy luận.

Chúng ta đang 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 ta ghi nhớ ngữ cảnh của cuộc trò chuyện. ADK tích hợp tự nhiên với ToolboxSyncClient để kéo các công cụ của chúng ta một cách liền mạch từ Cloud Run.

Đây là app.py:

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 lần lượt tương tác với AlloyDB (cũng như dữ liệu được liên kết BigQuery) và phản hồi người dùng.

Để tải dự án này trong Trình chỉnh sửa Cloud Shell, bạn có thể sao chép kho lưu trữ cho tác nhân bằng cách chạy các lệnh sau trong Cloud Shell Terminal:

cd

git clone https://github.com/AbiramiSukumaran/froyo-data

Bạn sẽ thấy cấu trúc dự án sau:

Các bước để tiếp tục trải nghiệm dữ liệu mà không cần tài khoản thanh toán:

Các tệp này phải có trong cùng thư mục với app.py.

B. Tệp Python có tên app-nobill.py trong cùng đường dẫn

Trong thư mục gốc của dự án, có một tệp có tên là app-nobill.py
Tệp này được thiết kế để tạo trải nghiệm ứng dụng tương tự nhưng không cần kết nối rõ ràng với các nguồn dữ liệu này vì dữ liệu đã được cung cấp trong các tệp.
Tất cả các tệp khác như đã đề cập trong phòng thí nghiệm cũng phải còn nguyên vẹn cho phiên bản này (chỉ cần không thực thi tệp app.py)

7. Giao diện người dùng và Chạy ứng dụng

Để mang đến cho Trình quản lý cửa hàng trải nghiệm phù hợp, chúng ta đã tạo một giao diện người dùng glassmorphic bóng bẩy (templates/index.html) 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 kho lưu trữ 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ó các phần phụ thuộc trong tệp requirements.txt với 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=***

Cách lấy GOOGLE_API_KEY ?

Làm theo hướng dẫn trong blog này để thiết lập Khoá API của Google.

Cách lấy MCP_TOOLBOX_SERVER_URL?

Chúng ta đã thiết lập khoá này trong bước trước trong lớp học lập trình này và bạn đã sao chép điểm cuối Bộ công cụ MCP đã triển khai. Sử dụng đường liên kết đó cho biến môi trường MCP_TOOLBOX_SERVER_URL.

Chạy ứng dụng:

Trong Cloud Shell Terminal, hãy đảm bảo bạn đang ở trong thư mục dự án, chạy từng lệnh sau:

Chuyển đến thư mục gốc của dự án:

cd froyo-data

Cài đặt các phần phụ thuộc:

pip install -r requirements.txt

Đang thực thi tệp Python:

python app.py

Nhấp vào đường liên kết xuất hiện trong cửa sổ dòng lệnh 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 tác nhân:

Does Midnight Swirl have any allergens?

Bạn sẽ thấy phản hồi:

Video hậu trường:

Tác nhân ADK nhận được lời nhắc và quyết định sử dụng công cụ check_allergens.
Tác nhân này gọi Bộ công cụ MCP một cách an toàn trên Cloud Run.
Bộ công cụ thực thi truy vấn trong AlloyDB, truy vấn này sẽ liên kết ngay 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à Tác nhân 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 Swirl for Alice.

Tác nhân chuyển chuỗi "Midnight Swirl" (Vòng xoáy nửa đêm) sang Bộ công cụ. SQL cơ bản sẽ tự động phân giải chuỗi thành mã nhận dạng số nguyên thông qua BigQuery, chèn đơn đặt hàng trực tiếp vào AlloyDB và xác nhận giao dịch.

Kho lưu trữ mã

https://github.com/AbiramiSukumaran/froyo-data

9. Dọn dẹp

Sau khi hoàn tất phòng thí nghiệm này, đừng quên xoá cụm và thực thể AlloyDB.

Thao tác này sẽ dọn dẹp cụm cùng với(các) thực thể của cụm đó.

10. Chúc mừng bạn đã có Tác nhân!

Hãy nghĩ về những gì chúng ta vừa hoàn thành:

Hệ thống tác nhân được điều phối tốt của chúng ta chỉ tương tác với Bộ công cụ MCP cho cơ sở dữ liệu. Hệ thống này ở chế độ nền xử lý lệnh gọi công cụ và dữ liệu cho logic AI của ứng dụng, giúp luồng hoạt động đơn giản:

Ứng dụng giao dịch của chúng ta (chạy trên AlloyDB) có thể xử lý các phiên người dùng đồng thời và nhanh chóng.
Khi cần dữ liệu phân tích nặng hoặc ngữ cảnh trước đây (như thông tin chi tiết về nhà cung cấp hoặc mối liên kết thành phần phức tạp), ứng dụng này sẽ truy vấn froyo_dataschema BigQuery.
Không có ETL. Không có đường dẫn dữ liệu bị hỏng. Không có cơ sở dữ liệu không đồng bộ. Chúng ta lưu trữ một lần (trong BQ) và tính toán ở nơi cần.

Giờ đây, khi tác nhân và nền tảng dữ liệu của chúng ta – cả phân tích và giao dịch – đã hoàn tất, hãy chuyển sang phần tiếp theo.

Tiếp theo là gì?

Tác nhân của chúng ta hoạt động hoàn hảo... trên đường dẫn thành công. Trong Phần 4, chúng ta sẽ xây dựng một quy trình Đánh giá tác nhân để kiểm thử nghiêm ngặt tính hợp lệ, cơ sở 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é!