Cài đặt và thiết lập Hộp công cụ cho các ứng dụng Gen AI và Agentic trên AlloyDB

1. Tổng quan

Hộp công cụ Gen AI cho cơ sở dữ liệu là một máy chủ nguồn mở của Google giúp bạn dễ dàng xây dựng các công cụ Gen AI để tương tác với cơ sở dữ liệu. Thư viện này giúp bạn phát triển các công cụ dễ dàng, nhanh chóng và an toàn hơn bằng cách xử lý các vấn đề phức tạp như gộp kết nối, xác thực, v.v. Công cụ này giúp bạn xây dựng các công cụ AI tạo sinh để cho phép nhân viên hỗ trợ truy cập vào dữ liệu trong cơ sở dữ liệu của bạn. Hộp công cụ cung cấp:

Đơn giản hoá quá trình phát triển: Tích hợp các công cụ vào tác nhân của bạn trong chưa đến 10 dòng mã, tái sử dụng các công cụ giữa nhiều tác nhân hoặc khung và triển khai các phiên bản công cụ mới dễ dàng hơn.

Hiệu suất tốt hơn: Các phương pháp hay nhất như nhóm kết nối, xác thực và nhiều phương pháp khác.

Tăng cường bảo mật: Tích hợp tính năng xác thực để truy cập vào dữ liệu của bạn một cách an toàn hơn.

Khả năng quan sát toàn diện: Các chỉ số và tính năng theo dõi ngay từ đầu với tính năng hỗ trợ tích hợp cho OpenTelemetry.

Hộp công cụ nằm giữa khung điều phối của ứng dụng và cơ sở dữ liệu, cung cấp một vùng điều khiển dùng để sửa đổi, phân phối hoặc gọi các công cụ. Công cụ này giúp đơn giản hoá việc quản lý các công cụ bằng cách cung cấp cho bạn một vị trí tập trung để lưu trữ và cập nhật các công cụ, cho phép bạn chia sẻ các công cụ giữa các tác nhân và ứng dụng, đồng thời cập nhật các công cụ đó mà không cần triển khai lại ứng dụng.

Sản phẩm bạn sẽ tạo ra

Trong lớp học lập trình này, bạn sẽ xây dựng một ứng dụng sử dụng công cụ để thực hiện truy vấn cơ sở dữ liệu (AlloyDB) đơn giản có thể được gọi từ tác nhân hoặc ứng dụng AI tạo sinh. Để làm việc này, bạn sẽ

1. Cài đặt Hộp công cụ
2. Thiết lập công cụ (được thiết kế để thực hiện một tác vụ trong AlloyDB) trên máy chủ Hộp công cụ
3. Triển khai Hộp công cụ trên Cloud Run
4. Kiểm thử công cụ bằng điểm cuối Cloud Run đã triển khai
5. Tạo Hàm chạy trên đám mây để gọi Hộp công cụ

Yêu cầu

• Một trình duyệt, chẳng hạn như Chrome hoặc Firefox
• Một dự án Google Cloud đã bật tính năng thanh toán (các bước trong phần tiếp theo).

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

Tạo một dự án

1. Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
2. Đả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 dự án hay không.
3. 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 Google Cloud.

4. Sau khi kết nối với Cloud Shell, hãy kiểm tra xem bạn đã được xác thực hay chưa và dự án đã được đặt đúng mã dự án hay chưa bằng lệnh sau:

gcloud auth list

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

6. Nếu dự án của bạn chưa được đặt, hãy sử dụng lệnh sau để đặt dự án:

gcloud config set project <YOUR_PROJECT_ID>

7. Bật các API bắt buộc bằng cách chạy lần lượt các lệnh sau trong Dòng lệnh Cloud Shell:

Ngoài ra, bạn cũng có thể chạy một lệnh duy nhất như bên dưới. Tuy nhiên, nếu là người dùng tài khoản dùng thử, bạn có thể gặp phải các vấn đề về hạn mức khi bật các tính năng này hàng loạt. Đó là lý do các lệnh được tách riêng ra từng dòng.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

Cách thay thế cho lệnh gcloud là thông qua bảng điều khiển bằng cách tìm kiếm từng sản phẩm hoặc sử dụng đường liên kết này.

Nếu thiếu bất kỳ API nào, bạn luôn có thể bật API đó trong quá trình triển khai.

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.

3. Thiết lập cơ sở dữ liệu

Trong lớp học lập trình này, chúng ta sẽ sử dụng AlloyDB làm cơ sở dữ liệu để lưu trữ dữ liệu bán lẻ. Mô-đun này sử dụng các cụm để lưu giữ tất cả tài nguyên, chẳng hạn như cơ sở dữ liệu và nhật ký. Mỗi cụm có một phiên bản chính cung cấp điểm truy cập vào dữ liệu. Bảng sẽ chứa dữ liệu thực tế.

Hãy tạo một cụm, thực thể và bảng AlloyDB nơi tập dữ liệu thương mại điện tử sẽ được tải.

Tạo cụm và thực thể

1. Chuyển đến trang AlloyDB trong Cloud Console.

Bạn có thể dễ dàng tìm thấy hầu hết các trang trong Cloud Console bằng cách tìm kiếm các trang đó thông qua thanh tìm kiếm của bảng điều khiển.

2. Chọn CREATE CLUSTER (TẠO CLUSTER) trên trang đó:

3. Bạn sẽ thấy một màn hình như màn hình bên dưới. Tạo cụm và thực thể bằng các giá trị sau (Đảm bảo các giá trị khớp với nhau trong trường hợp bạn đang nhân bản mã ứng dụng từ kho lưu trữ):

• mã cụm: "vector-cluster"
• password: "alloydb"
• Tương thích với PostgreSQL 15
• Vùng: "us-central1"
• Mạng: "default"

4. Khi chọn mạng mặc định, bạn sẽ thấy một màn hình như dưới đây. Chọn THIẾT LẬP KẾT NỐI.
   
5. Tại đó, hãy chọn "Sử dụng dải IP được phân bổ tự động" rồi chọn Tiếp tục. Sau khi xem lại thông tin, hãy chọn TẠO KẾT NỐI.
6. Sau khi thiết lập mạng, bạn có thể tiếp tục tạo cụm. Nhấp vào CREATE CLUSTER (TẠO CLUSTER) để hoàn tất việc thiết lập cụm như minh hoạ bên dưới:

Hãy nhớ thay đổi mã nhận dạng thực thể thành "

vector-instance"

.

Xin lưu ý rằng quá trình tạo cụm sẽ mất khoảng 10 phút. Sau khi tạo thành công, bạn sẽ thấy một màn hình hiển thị thông tin tổng quan về cụm bạn vừa tạo.

4. Nhập dữ liệu

Bây giờ, đã đến lúc thêm một bảng chứa dữ liệu về cửa hàng. Chuyển đến AlloyDB, chọn cụm chính rồi chọn AlloyDB Studio:

Bạn có thể phải đợi thực thể của mình hoàn tất quá trình tạo. Sau khi hoàn tất, hãy đăng nhập vào AlloyDB bằng thông tin xác thực mà bạn đã tạo trong quá trình tạo cụm. Sử dụng dữ liệu sau để xác thực với PostgreSQL:

• Tên người dùng : "postgres"
• Cơ sở dữ liệu : "postgres"
• Mật khẩu : "alloydb"

Sau khi xác thực thành công vào AlloyDB Studio, bạn có thể nhập các lệnh SQL trong Trình chỉnh sửa. Bạn có thể thêm nhiều cửa sổ Trình chỉnh sửa bằng biểu tượng dấu cộng ở bên phải cửa sổ cuối cùng.

Bạn có thể nhập các lệnh cho AlloyDB trong cửa sổ trình chỉnh sửa, sử dụng các tuỳ chọn Run (Chạy), Format (Định dạng) và Clear (Xoá) nếu cần.

Bật tiện ích

Để xây dựng ứng dụng này, chúng ta sẽ sử dụng các tiện ích pgvector và google_ml_integration. Tiện ích pgvector cho phép bạn lưu trữ và tìm kiếm các vectơ nhúng. Tiện ích google_ml_integration cung cấp các hàm mà bạn sử dụng để truy cập vào các điểm cuối dự đoán của Vertex AI nhằm nhận thông tin dự đoán trong SQL. Bật các tiện ích này bằng cách chạy các DDL sau:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Nếu bạn muốn kiểm tra các tiện ích đã được bật trên cơ sở dữ liệu, hãy chạy lệnh SQL sau:

select extname, extversion from pg_extension;

Tạo bảng

Tạo bảng bằng câu lệnh DDL bên dưới:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Khi thực thi thành công lệnh trên, bạn sẽ có thể xem bảng trong cơ sở dữ liệu.

Nhập dữ liệu

Đối với lớp học này, chúng ta có dữ liệu kiểm thử gồm khoảng 72 bản ghi trong tệp SQL này. Tệp này chứa các trường id, name, description, quantity, price, image_url. Các trường khác sẽ được điền vào sau trong lớp học lập trình.

Sao chép các dòng/đoạn mã chèn từ đó, sau đó dán các dòng đó vào thẻ trình chỉnh sửa trống rồi chọn RUN (CHẠY).

Để xem nội dung của bảng, hãy mở rộng mục Trình khám phá cho đến khi bạn thấy bảng có tên là apparels. Chọn biểu tượng ba dấu chấm (⋮) để xem tuỳ chọn Truy vấn bảng. Câu lệnh SELECT sẽ mở trong thẻ Trình chỉnh sửa mới.

Cấp quyền

Chạy câu lệnh dưới đây để cấp quyền thực thi trên hàm embedding cho người dùng postgres:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Cấp VAI TRÒ Người dùng Vertex AI cho tài khoản dịch vụ AlloyDB

Chuyển đến cửa sổ dòng lệnh Cloud Shell và nhập lệnh sau:

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"

5. Tạo nội dung nhúng cho ngữ cảnh

Máy tính xử lý số dễ dàng hơn nhiều so với xử lý văn bản. Hệ thống nhúng chuyển đổi văn bản thành một loạt số dấu phẩy động, được gọi là nhúng vectơ, đại diện cho văn bản, bất kể văn bản được viết như thế nào, sử dụng ngôn ngữ nào, v.v.

Ví dụ: một vị trí bên bờ biển có thể được gọi là "on the water" (trên mặt nước), "beachfront" (bờ biển), "walk from your room to the ocean" (đi bộ từ phòng đến biển), "sur la mer" (trên biển), "на берегу океана" (trên bờ biển), v.v. Những cụm từ này đều có vẻ khác nhau, nhưng ý nghĩa ngữ nghĩa của chúng hoặc trong thuật ngữ học máy, nội dung nhúng của chúng phải rất gần nhau.

Giờ đây, khi dữ liệu và ngữ cảnh đã sẵn sàng, chúng ta sẽ chạy SQL để thêm nội dung nhúng của nội dung mô tả sản phẩm vào bảng trong trường embedding. Bạn có thể sử dụng nhiều mô hình nhúng. Chúng ta sẽ sử dụng text-embedding-005 từ Vertex AI. Hãy nhớ sử dụng cùng một mô hình nhúng trong suốt dự án!

Lưu ý: Nếu đang sử dụng một Dự án Google Cloud cũ, bạn có thể cần tiếp tục sử dụng các phiên bản cũ của mô hình nhúng văn bản như textembedding-gecko.

Quay lại thẻ AlloyDB Studio và nhập DML sau:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Xem lại bảng toys để xem một số phần nhúng. Hãy nhớ chạy lại câu lệnh SELECT để xem các thay đổi.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Thao tác này sẽ trả về vectơ nhúng, trông giống như một mảng float, cho nội dung mô tả đồ chơi như dưới đây:

Lưu ý: Các dự án Google Cloud mới tạo trong gói miễn phí có thể gặp vấn đề về hạn mức liên quan đến số lượng yêu cầu nhúng được phép mỗi giây đối với các mô hình Nhúng. Bạn nên sử dụng truy vấn bộ lọc cho mã nhận dạng, sau đó chọn lọc 1-5 bản ghi, v.v. trong khi tạo nội dung nhúng.

6. Tìm kiếm vectơ

Giờ đây, bảng, dữ liệu và nội dung nhúng đã sẵn sàng, hãy thực hiện tìm kiếm vectơ theo thời gian thực cho văn bản tìm kiếm của người dùng.

Giả sử người dùng hỏi:

"I want a white plush teddy bear toy with a floral pattern."

Bạn có thể tìm thấy các kết quả trùng khớp bằng cách chạy truy vấn dưới đây:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Hãy cùng xem chi tiết truy vấn này:

Trong truy vấn này,

1. Văn bản tìm kiếm của người dùng là: "I want a white plush teddy bear toy with a floral pattern."
2. Chúng ta sẽ chuyển đổi dữ liệu này thành dữ liệu nhúng trong phương thức embedding() bằng cách sử dụng mô hình: text-embedding-005. Bước này sẽ trông quen thuộc sau bước cuối cùng, khi chúng ta áp dụng hàm nhúng cho tất cả các mục trong bảng.
3. "<=>" thể hiện việc sử dụng phương thức khoảng cách COSINE SIMILARITY (TƯƠNG ĐỒNG COSINE). Bạn có thể tìm thấy tất cả các chỉ số tương đồng có trong tài liệu về pgvector.
4. Chúng ta đang chuyển đổi kết quả của phương thức nhúng thành loại vectơ để tương thích với các vectơ được lưu trữ trong cơ sở dữ liệu.
5. LIMIT 5 cho biết chúng ta muốn trích xuất 5 từ gần nhất cho văn bản tìm kiếm.

Kết quả sẽ có dạng như sau:

Như bạn có thể quan sát trong kết quả, các cụm từ trùng khớp khá gần với văn bản tìm kiếm. Hãy thử thay đổi văn bản để xem kết quả thay đổi như thế nào.

7. Chuẩn bị AlloyDB cho hoạt động tương tác trong Hộp công cụ

Để chuẩn bị thiết lập Hộp công cụ, hãy bật khả năng kết nối IP công khai trong thực thể AlloyDB để công cụ mới có thể truy cập vào cơ sở dữ liệu.

1. Chuyển đến phiên bản AlloyDB, nhấp vào CHỈNH SỬA rồi chuyển đến trang Chỉnh sửa phiên bản chính.
2. Chuyển đến phần Kết nối IP công khai, đánh dấu vào hộp Bật IP công khai rồi nhập địa chỉ IP của máy Cloud Shell.
3. Để lấy địa chỉ IP của máy Cloud Shell, hãy chuyển đến Cloud Shell Terminal rồi nhập ifconfig. Từ kết quả, hãy xác định địa chỉ inet eth0 và thay thế 2 chữ số cuối cùng bằng 0.0 với kích thước mặt nạ "/16". Ví dụ: "XX.XX.0.0/16", trong đó XX là các số.
4. Dán địa chỉ IP này vào hộp văn bản "Mạng" của phần Mạng bên ngoài được uỷ quyền trên trang chỉnh sửa thực thể.

5. Nhấp vào UPDATE INSTANCE (CẬP NHẬT MẪU) khi hoàn tất.

Quá trình này sẽ mất vài phút để hoàn tất.

8. Cài đặt Hộp công cụ

1. Bạn có thể tạo một thư mục dự án để lưu trữ thông tin chi tiết về công cụ. Trong trường hợp này, vì chúng ta đang xử lý dữ liệu cửa hàng đồ chơi, hãy tạo một thư mục có tên "toystore" (cửa hàng đồ chơi) rồi chuyển đến thư mục đó. Chuyển đến Cloud Shell Terminal (Cổng shell trên Google Cloud) và đảm bảo dự án của bạn đã được chọn và hiển thị trong lời nhắc của cổng. Chạy lệnh dưới đây từ Dòng lệnh Cloud Shell:

mkdir toystore

cd toystore

2. Chạy lệnh bên dưới để tải xuống và cài đặt hộp công cụ trong thư mục mới:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. Chuyển sang Trình chỉnh sửa Cloud Shell. Mở rộng thư mục "toystore" (cửa hàng đồ chơi) mới tạo và tạo một tệp mới có tên tools.yaml. Sao chép nội dung bên dưới. Thay thế YOUR_PROJECT_ID và kiểm tra xem tất cả thông tin kết nối khác có chính xác hay không.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

Trong công cụ này, chúng ta chỉ tìm nội dung khớp gần nhất với văn bản tìm kiếm của người dùng (nội dung mô tả đồ chơi tuỳ chỉnh) và trả về giá của nội dung đó. Bạn cũng có thể sửa đổi hàm này để tìm giá trung bình của 5 món đồ chơi phù hợp nhất:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

Bạn đã hoàn tất việc xác định công cụ!

Để biết thêm thông tin chi tiết về cách định cấu hình tools.yaml, hãy tham khảo tài liệu này.

4. Chuyển sang Cloud Shell Terminal (Dòng lệnh Cloud Shell) rồi nhập lệnh sau để khởi động máy chủ hộp công cụ bằng cấu hình công cụ của bạn:

./toolbox --tools_file "tools.yaml"

5. Bây giờ, nếu mở máy chủ ở chế độ xem trước trên web trên đám mây, bạn sẽ thấy máy chủ Toolbox đang hoạt động với công cụ mới có tên get-toy-price.

9. Triển khai Hộp công cụ trên Cloud Run

Hãy triển khai ứng dụng này trên Cloud Run để bạn có thể sử dụng công cụ này trong thực tế.

1. Làm theo hướng dẫn trong trang này từng bước cho đến khi bạn đến lệnh gcloud run deploy toolbox ở điểm thứ 3 trong phần "Triển khai lên Cloud Run". Bạn cần tuỳ chọn đầu tiên chứ không phải tuỳ chọn thứ hai dành cho khi bạn đang sử dụng phương thức mạng VPC.
2. Sau khi triển khai thành công, bạn sẽ nhận được một điểm cuối được triển khai trên Cloud Run của máy chủ Toolbox. Kiểm thử bằng lệnh CURL.

Bạn đã sẵn sàng sử dụng công cụ mới triển khai trong ứng dụng đại lý của mình!!!

10. Kết nối Ứng dụng của bạn với Hộp công cụ

Trong phần này, chúng ta sẽ xây dựng một ứng dụng nhỏ để kiểm thử công cụ của bạn nhằm tương tác với nhu cầu của ứng dụng và truy xuất phản hồi.

1. Chuyển đến Google Colab rồi mở một sổ tay mới.
2. Chạy mã sau trong sổ tay

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. Bạn sẽ thấy kết quả như sau:

Đây là công cụ được gọi rõ ràng trong một ứng dụng Python sử dụng bộ công cụ toolbox-langchain.

4. Nếu muốn sử dụng công cụ này và liên kết công cụ đó với một tác nhân trong ứng dụng tích hợp LangGraph, bạn có thể dễ dàng thực hiện việc đó bằng bộ công cụ langgraph.
5. Hãy tham khảo các đoạn mã để biết thông tin này.

11. Chuyển sang đám mây!!!

Hãy gói đoạn mã Python này trong một Hàm Cloud Run để tạo một hàm không cần máy chủ!

1. Sao chép nguồn từ thư mục kho lưu trữ mã để chuyển nguồn này đến Cloud Functions.
2. Chuyển đến bảng điều khiển Cloud Run Functions (Hàm Cloud Run) rồi nhấp vào CREATE FUNCTION (TẠO HÀM).
3. Không xác thực ứng dụng minh hoạ và chọn môi trường thời gian chạy Python 3.11 trong trang tiếp theo.
4. Sao chép các tệp main.py và requirements.txt từ kho lưu trữ nguồn được chia sẻ ở bước 1 rồi dán vào các tệp tương ứng.
5. Triển khai hàm này và bạn sẽ có một điểm cuối REST để truy cập vào công cụ dự đoán giá trong ứng dụng web cửa hàng đồ chơi.
6. Điểm cuối của bạn sẽ có dạng như sau:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. Bạn có thể kiểm thử trực tiếp trên bảng điều khiển Cloud Functions bằng cách chuyển đến thẻ TESTING (KIỂM THỬ) rồi nhập nội dung sau làm dữ liệu đầu vào cho yêu cầu:

{

               "`search`"`:` "`White plush toy`"

}

3. Nhấp vào TEST THE FUNCTION (KIỂM TRA HÀM) hoặc chạy trong Cloud Shell Terminal (Màn hình điều khiển Cloud Shell) bất kỳ mà bạn chọn sử dụng. Bạn sẽ thấy kết quả ở bên phải trong tiêu đề "Kết quả":

12. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo thành công một công cụ mạnh mẽ và thực sự mô-đun có thể tương tác trên các cơ sở dữ liệu, nền tảng và khung điều phối AI tạo sinh để giúp tạo ứng dụng tác nhân.