Thông tin về lớp học lập trình này
1. Tổng quan
Hộp công cụ MCP dành 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ụ dựa trên AI tạo sinh để 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. Nền tảng này giúp bạn xây dựng những 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ụ cho nhân viên hỗ trợ trong chưa đầy 10 dòng mã, sử dụng lại các công cụ giữa nhiều nhân viên hỗ trợ 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ư gộp nhóm kết nối, xác thực, v.v.
Bảo mật nâng cao: Tính năng xác thực tích hợp giúp bạn truy cập vào dữ liệu một cách an toàn hơn.
Khả năng quan sát toàn diện: Chỉ số và theo dõi ngay lập tức bằng tính năng hỗ trợ tích hợp sẵn 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 phòng thí nghiệm này, bạn sẽ xây dựng một ứng dụng sử dụng một công cụ để thực hiện truy vấn cơ sở dữ liệu đơn giản (alloyDB) có thể được gọi từ tác nhân của bạn hoặc ứng dụng AI tạo sinh. Để làm được điều này, bạn sẽ
- Cài đặt Hộp công cụ MCP cho cơ sở dữ liệu
- 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ụ
- Triển khai Hộp công cụ MCP cho cơ sở dữ liệu trên Cloud Run
- Kiểm thử công cụ này bằng điểm cuối Cloud Run đã triển khai
- Tạo Hàm chạy trên đám mây để gọi Hộp công cụ
Yêu cầu
2. Trước khi bắt đầu
Tạo một dự án
- 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.
- Đả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.
- 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.
- Sau khi kết nối với Cloud Shell, hãy kiểm tra xem bạn đã được xác thực chưa và dự án có được đặt thành đúng mã dự án hay không bằng lệnh sau đây:
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 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>
- Bật các API cần thiết bằng cách chạy từng lệnh sau trong Cloud Shell Terminal:
Ngoài ra còn có một lệnh để chạy bên dưới, nhưng 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 cố gắng bật các lệnh này hàng loạt. Đó là lý do tại sao các lệnh được tách ra một lệnh trên mỗi 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
Lựa chọn 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 phòng thí nghiệm này, chúng tôi sẽ sử dụng AlloyDB làm cơ sở dữ liệu để lưu trữ dữ liệu bán lẻ. Tệp 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 thực thể chính cung cấp điểm truy cập vào dữ liệu. Các bảng sẽ lưu trữ dữ liệu thực tế.
Hãy tạo một cụm, thực thể và bảng AlloyDB mà tập dữ liệu thương mại điện tử sẽ được tải.
Tạo một cụm và thực thể
- Di chuyển trên trang AlloyDB trong Cloud Console.
Một cách dễ dàng để tìm thấy hầu hết các trang trong Cloud Console là tìm các trang đó bằng thanh tìm kiếm của bảng điều khiển.
- Chọn TẠO CỤM TỪ trang đó:
- Bạn sẽ thấy một màn hình như màn hình dưới đây. Tạo một cụm và phiên bản có các giá trị sau (Đảm bảo các giá trị này khớp nhau trong trường hợp bạn đang sao chép mã xử lý ứng dụng từ kho lưu trữ):
- id cụm: "
vector-cluster" - mật khẩu: "
alloydb" - Tương thích với PostgreSQL 15
- Vùng: "
us-central1" - Kết nối mạng: "
default"
- Khi chọn mạng mặc định, bạn sẽ thấy một màn hình như màn hình bên dưới. Chọn THIẾT LẬP KẾT NỐI.
- Tiếp theo, 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 xét thông tin, hãy chọn TẠO KẾT NỐI.
- Sau khi thiết lập xong mạng, bạn có thể tiếp tục tạo cụm của mình. Nhấp vào TẠO CỤM để hoàn tất việc thiết lập cụm như minh hoạ dưới đây:
Hãy nhớ thay đổi mã thực thể thành "
vector-instance"
.
Lưu ý rằng quá trình tạo Cụm sẽ mất khoảng 10 phút. Sau khi thành công, bạn sẽ thấy 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 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:
Có thể bạn phải đợi cho đến khi thực thể của mình được tạo xong. Sau khi hoàn tất, hãy đăng nhập vào AlloyDB bằng thông tin đăng nhập 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 trong AlloyDB Studio, bạn có thể nhập các lệnh SQL vào 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 cách sử dụ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, bằng cách sử dụng tùy chọn Chạy, Định dạng và Xóa nếu cần.
Bật tiện ích
Để tạo ứng dụng này, chúng ta sẽ sử dụng các tiện ích pgvector và google_ml_integration. Phần mở rộng pgvector cho phép bạn lưu trữ và tìm kiếm các mục nhúng vectơ. Phần mở rộng google_ml_integration cung cấp các hàm mà bạn 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 của mình, 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ách sử dụ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 phòng thí nghiệm này, chúng tôi có dữ liệu kiểm thử của 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 sau trong phòng thí nghiệm.
Sao chép các dòng/chèn câu lệnh từ đó, sau đó dán các dòng đó vào một thẻ trống trong trình chỉnh sửa rồi chọn CHẠY.
Để xem mục lục, hãy mở rộng phần Explorer cho đến khi bạn có thể thấy bảng có tên là trang phục. Chọn dấu ba chấm (⋮) để xem tuỳ chọn Truy vấn bảng. Câu lệnh SELECT sẽ mở trong thẻ Người chỉnh sửa mới.
Cấp quyền
Chạy câu lệnh bên dưới để cấp quyền thực thi đối với hàm embedding cho người dùng postgres:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Cấp Vai trò của người dùng Vertex AI cho tài khoản dịch vụ AlloyDB
Đi đế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 các mục nhúng cho ngữ cảnh
Máy tính xử lý số dễ 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 chuỗi số dấu phẩy động, được gọi là vectơ nhúng. Các số này sẽ đại diện cho văn bản, bất kể văn bản đó được diễn đạt như thế nào hay sử dụng ngôn ngữ gì, v.v.
Ví dụ: một vị trí bên bờ biển có thể được gọi là "trên mặt nước", "bãi biển", "đi bộ từ phòng đến đại dương", "sur la mer", "На берегу океана", v.v. Tất cả các cụm từ này trông khác nhau, nhưng ý nghĩa ngữ nghĩa hoặc trong thuật ngữ học máy phải rất gần nhau.
Giờ đây, dữ liệu và ngữ cảnh đã sẵn sàng, chúng ta sẽ chạy SQL để thêm các mục 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 khác nhau. Chúng tôi đang dùng text-embedding-005 của 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ũ hơn 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ố mục 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 dấu phẩy động, cho nội dung mô tả đồ chơi như dưới đây:
Lưu ý: Các dự án Google Cloud mới tạo ở cấp miễn phí có thể gặp vấn đề về hạn mức liên quan đến số 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 này rồi chọn từ 1 đến 5 bản ghi, v.v. trong khi tạo mục nhúng.
6. Thực hiện tìm kiếm vectơ
Giờ thì bảng, dữ liệu và các mục 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ả phù hợp cho cụm từ này bằng cách chạy truy vấn bên dưới:
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,
- 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." - Chúng ta đang chuyển đổi đối tượng này thành các mục nhúng trong phương thức
embedding()bằng mô hình:text-embedding-005. Bước này trông quen thuộc sau bước cuối cùng, nơi chúng ta đã áp dụng hàm nhúng cho tất cả các mục trong bảng. - "
<=>" thể hiện việc sử dụng phương thức khoảng cách cosINE gầnITY. Bạn có thể tìm thấy tất cả các số đo tương tự có trong tài liệu về pgvector. - Chúng ta đang chuyển đổi kết quả của phương pháp nhúng thành kiểu vectơ để làm cho kết quả này tương thích với các vectơ được lưu trữ trong cơ sở dữ liệu.
- LIMIT 5 thể hiện rằng chúng ta muốn trích xuất 5 láng giềng 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ả, kết quả 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 tương tác Hộp công cụ
Để chuẩn bị thiết lập Hộp công cụ, hãy bật tính năng kết nối IP công khai trong phiên bản AlloyDB để công cụ mới có thể truy cập vào cơ sở dữ liệu.
- Chuyển đến phiên bản AlloyDB của bạn, nhấp vào CHỈNH SỬA và chuyển đến trang Chỉnh sửa phiên bản chính.
- 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 và nhập địa chỉ IP của máy Cloud Shell.
- Để lấy IP cho máy Cloud Shell của bạn, hãy chuyển đến Cloud Shell Terminal và nhập ifconfig. Từ kết quả, xác định địa chỉ inet eth0 và thay thế 2 chữ số cuối bằng 0.0 với kích thước mặt nạ '/16'. Ví dụ: nó sẽ trông giống như "XX.XX.0.0/16" trong đó XX là số.
- Dán IP này vào hộp văn bản "Mạng" bên ngoài được ủy quyền của trang chỉnh sửa bản sao.
- Nhấp vào CẬP NHẬT TÌNH TRẠNG sau khi hoàn tất.
Quá trình này sẽ mất vài phút để hoàn tất.
8. Hộp công cụ MCP để cài đặt cơ sở dữ liệu
- 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ụ này. 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" và điều hướng vào đó. Chuyển đến Cloud Shell Terminal và đảm bảo dự án của bạn được chọn và xuất hiện trong lời nhắc của thiết bị đầu cuối. Chạy lệnh bên dưới từ Cloud Shell Terminal:
mkdir toystore
cd toystore
- 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 của bạn:
# 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
- Chuyển sang Trình chỉnh sửa Cloud Shell. Mở rộng thư mục mới tạo "toystore" rồi 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ả cá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 tôi chỉ tìm kết quả phù hợp 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 món đồ đó. Bạn cũng có thể sửa đổi giá trị này để tìm giá trung bình của 5 món đồ chơi hàng đầu phù hợp nhất:
select Medium(price) from ( SELECT price FROM đồ chơi ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) làm giá;
Vậy là bạn đã có định nghĩa về công cụ này!
Để 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.
- Chuyển sang Cloud Shell Terminal và 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"
- Bây giờ, nếu mở máy chủ ở chế độ xem trước trên web trên đám mây, bạn sẽ có thể thấy máy chủ Toolbox được thiết lập và chạy bằng công cụ mới có tên
get-toy-price.
9. Triển khai Cloud Run của Hộp công cụ MCP cho cơ sở dữ liệu
Hãy triển khai công cụ này trên Cloud Run để có thể sử dụng công cụ này trong thực tế.
- Làm theo từng hướng dẫn trong trang này cho đến khi bạn gặp lệnh
gcloud run deploy toolboxở điểm thứ 3 trong phần "Deploy to Cloud Run". Bạn cần giải pháp đầu tiên chứ không phải cách thứ hai dành cho trường hợp bạn đang sử dụng phương thức mạng VPC. - Sau khi triển khai thành công, bạn sẽ nhận được một điểm cuối đã triển khai Cloud Run của máy chủ Hộp công cụ. Hãy kiểm thử bằng lệnh CURL.
Lưu ý:
Hãy làm theo hướng dẫn trong trang một cách cẩn thận và đừng bỏ lỡ.
Bạn đã sẵn sàng sử dụng công cụ mới triển khai trong ứng dụng tác nhân của mình!!!
10. Kết nối ứng dụng với Hộp công cụ MCP dành cho cơ sở dữ liệu
Trong phần này, chúng ta sẽ xây dựng một ứng dụng nhỏ nhằm 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.
- Chuyển đến Google Colab rồi mở một sổ tay mới.
- Chạy lệnh sau trong sổ tay của bạn
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- Bạn sẽ có 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.
- Nếu muốn sử dụng công cụ này và liên kết công cụ này với một tác nhân trong ứng dụng tích hợp LangGraph, bạn có thể thực hiện việc đó dễ dàng bằng bộ công cụ
langgraph. - Hãy tham khảo đoạn mã về việc này.
11. Hãy lên Cloud!!!
Hãy gói đoạn mã Python này vào Cloud Run Functions để mã này hoạt động không máy chủ!
- Sao chép nguồn từ thư mục kho lưu trữ mã để tải mã này vào Cloud Functions.
- Chuyển đến bảng điều khiển Cloud Run Functions (Chức năng chạy Cloud) rồi nhấp vào CREATE FUNCTION (Tạo chức năng).
- Giữ nguyên trạng thái không được xác thực cho ứ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.
- Sao chép các tệp
main.pyvàrequirements.txttừ 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. - Thay thế url máy chủ trong main.py bằng URL máy chủ của bạn.
- 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 toystore.
- Điểm cuối của bạn sẽ có dạng như sau:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- 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ẻ THỬ NGHIỆM rồi nhập những thông tin sau đây làm yêu cầu đầu vào:
{
"search": "White plush toy"
}
- Nhấp vào KIỂM TRA chức năng hoặc chạy trong Cloud Shell Terminal bất kể bạn chọn sử dụng gì. Bạn sẽ thấy kết quả ở bên phải dưới tiêu đề "Output" (Đầu ra):
12. Xin chúc mừng
Xin chúc mừng! Bạn đã tạo thành công một công cụ thực sự mạnh mẽ và theo mô-đun, có thể tương tác trên nhiều cơ sở dữ liệu, nền tảng và khung điều phối AI tạo sinh để hỗ trợ tạo ứng dụng tác nhân.