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

Cơ sở dữ liệu như một công cụ: RAG dựa trên tác nhân bằng ADK, MCP Toolbox và Cloud SQL

1. Giới thiệu

Độ hữu ích của các tác nhân AI phụ thuộc vào dữ liệu mà chúng có thể truy cập. Hầu hết dữ liệu trong thế giới thực đều nằm trong cơ sở dữ liệu và việc kết nối các tác nhân với cơ sở dữ liệu thường có nghĩa là bạn phải viết quy trình quản lý kết nối, logic truy vấn và quy trình nhúng bên trong mã tác nhân. Mọi tác nhân cần quyền truy cập vào cơ sở dữ liệu đều lặp lại công việc này và mọi thay đổi về truy vấn đều yêu cầu bạn phải triển khai lại tác nhân.

Lớp học lập trình này trình bày một phương pháp khác. Bạn khai báo các công cụ cơ sở dữ liệu trong một tệp YAML (truy vấn SQL chuẩn, tìm kiếm mức độ tương đồng của vectơ, thậm chí là tạo vectơ nhúng tự động) và Bộ công cụ MCP dành cho cơ sở dữ liệu sẽ xử lý tất cả các thao tác cơ sở dữ liệu dưới dạng một máy chủ MCP. Mã tác nhân của bạn vẫn ở mức tối thiểu: tải các công cụ, để Gemini quyết định gọi công cụ nào.

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

Một Lễ tân nhà hàng cho "Foodie Finds" – một tác nhân ADK dựa trên Gemini giúp thực khách duyệt xem thực đơn của nhà hàng bằng các bộ lọc tiêu chuẩn (danh mục, loại ẩm thực) và khám phá các món ăn thông qua nội dung mô tả bằng ngôn ngữ tự nhiên như "Tôi muốn ăn món gì đó cay và chay". Tác nhân này đọc và ghi vào cơ sở dữ liệu Cloud SQL PostgreSQL hoàn toàn thông qua Bộ công cụ MCP cho cơ sở dữ liệu, bộ công cụ này xử lý mọi quyền truy cập vào cơ sở dữ liệu – bao gồm cả việc tự động tạo vectơ nhúng để tìm kiếm vectơ. Đến cuối cùng, cả Bộ công cụ và tác nhân đều chạy trên Cloud Run.

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

Cách MCP (Giao thức ngữ cảnh mô hình) chuẩn hoá quyền truy cập vào công cụ cho các tác nhân AI và cách Bộ công cụ MCP cho cơ sở dữ liệu áp dụng điều này cho các hoạt động trên cơ sở dữ liệu
Thiết lập Bộ công cụ MCP cho cơ sở dữ liệu làm phần mềm trung gian giữa một tác nhân ADK và Cloud SQL PostgreSQL
Xác định các công cụ cơ sở dữ liệu một cách khai báo trong tools.yaml – không có mã cơ sở dữ liệu trong tác nhân của bạn
Tạo một tác nhân ADK tải các công cụ từ một máy chủ Bộ công cụ đang chạy bằng cách sử dụng ToolboxToolset
Tạo các vectơ nhúng bằng hàm embedding() tích hợp của Cloud SQL và bật tính năng tìm kiếm ngữ nghĩa bằng pgvector
Sử dụng tính năng valueFromParam để tự động nạp vectơ trong các thao tác ghi
Triển khai cả máy chủ Toolbox và tác nhân ADK lên Cloud Run

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

Tài khoản Google Cloud có tài khoản thanh toán dùng thử
Có kiến thức cơ bản về Python và SQL
Kinh nghiệm sử dụng Cơ sở dữ liệu đám mây và ADK sẽ rất hữu ích

2. Thiết lập môi trường

Bước này chuẩn bị môi trường Cloud Shell, định cấu hình dự án trên đám mây của bạn và sao chép kho lưu trữ tham chiếu.

Mở Cloud Shell

Mở Cloud Shell trong trình duyệt. Cloud Shell cung cấp một môi trường được định cấu hình sẵn với tất cả các công cụ bạn cần cho lớp học lập trình này. Nhấp vào Uỷ quyền khi được nhắc

Sau đó, nhấp vào "View" (Xem) -> "Terminal" (Thiết bị đầu cuối) để mở thiết bị đầu cuối.Giao diện của bạn sẽ trông tương tự như thế này

Đây sẽ là giao diện chính của chúng ta, IDE ở trên cùng, thiết bị đầu cuối ở dưới cùng

Thiết lập thư mục làm việc

Tạo thư mục làm việc. Tất cả mã bạn viết trong lớp học lập trình này đều nằm ở đây:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

Sau đó, hãy chuẩn bị một số thư mục để quản lý những thứ như tập lệnh gieo hạt và nhật ký

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs

Thiết lập dự án trên đám mây của bạn

Tạo tệp .env bằng các biến vị trí:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

Để đơn giản hoá việc thiết lập dự án trong thiết bị đầu cuối, hãy tải tập lệnh thiết lập dự án này xuống thư mục làm việc của bạn:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Chạy tập lệnh. Lệnh này xác minh tài khoản thanh toán dùng thử của bạn, tạo một dự án mới (hoặc xác thực một dự án hiện có), lưu mã dự án vào một tệp .env trong thư mục hiện tại và đặt dự án đang hoạt động trong gcloud.

bash setup_verify_trial_project.sh && source .env

Tập lệnh sẽ:

Xác minh rằng bạn có một tài khoản thanh toán dùng thử đang hoạt động
Kiểm tra xem có dự án nào trong .env hay không (nếu có)
Tạo dự án mới hoặc sử dụng lại dự án hiện có
Liên kết tài khoản thanh toán dùng thử với dự án của bạn
Lưu mã dự án vào .env
Đặt dự án làm dự án gcloud đang hoạt động

Xác minh rằng dự án được thiết lập đúng cách bằng cách kiểm tra văn bản màu vàng bên cạnh thư mục đang hoạt động trong dấu nhắc của thiết bị đầu cuối Cloud Shell. Văn bản này sẽ hiển thị mã dự án của bạn.

Kích hoạt API bắt buộc

Tiếp theo, chúng ta cần bật một số API cho sản phẩm mà chúng ta sẽ tương tác:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

Vertex AI API (aiplatform.googleapis.com) – tác nhân của bạn sử dụng các mô hình Gemini và Toolbox sử dụng API nhúng để tìm kiếm vectơ.
Cloud SQL Admin API (sqladmin.googleapis.com) – bạn cung cấp và quản lý một phiên bản PostgreSQL.
Compute Engine API (compute.googleapis.com) – bắt buộc để tạo phiên bản Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry – được dùng trong bước triển khai sau này trong lớp học lập trình này

3. Chuẩn bị tập lệnh để khởi chạy cơ sở dữ liệu

Bước này bắt đầu quá trình tạo phiên bản Cloud SQL và chạy một tập lệnh thiết lập tự động. Tập lệnh này sẽ đợi phiên bản sẵn sàng, sau đó tạo cơ sở dữ liệu, gieo dữ liệu vào cơ sở dữ liệu bằng danh sách việc làm và tạo các mục nhúng – tất cả trong một thao tác.

Trước tiên, hãy thêm mật khẩu cơ sở dữ liệu vào tệp .env rồi tải lại tệp đó:

echo "DB_PASSWORD=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_db" >> .env
source .env

Tạo tập lệnh Bash để tạo phiên bản và cơ sở dữ liệu

Sau đó, hãy tạo tập lệnh scripts/setup_database.sh bằng lệnh sau

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
cloudshell edit scripts/setup_database.sh

Sau đó, hãy sao chép mã sau vào tệp scripts/setup_database.sh

#!/bin/bash
set -e
source .env

echo "================================================"
echo "Database Setup"
echo "================================================"
echo ""

# Step 1: Create Cloud SQL instance
echo "[1/5] Creating Cloud SQL instance..."

# Check if instance already exists
if gcloud sql instances describe "$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Instance already exists"
else
    echo "      Creating instance (takes 5-10 minutes)..."
    gcloud sql instances create "$DB_INSTANCE" \
        --database-version=POSTGRES_17 \
        --tier=db-custom-1-3840 \
        --edition=ENTERPRISE \
        --region="$REGION" \
        --root-password="$DB_PASSWORD" \
        --enable-google-ml-integration \
        --database-flags cloudsql.enable_google_ml_integration=on \
        --quiet
fi
echo "      ✓ Instance ready"
echo ""

# Step 2: Verify instance is ready
echo "[2/5] Verifying instance state..."

STATE=$(gcloud sql instances describe "$DB_INSTANCE" --format='value(state)')

if [ "$STATE" != "RUNNABLE" ]; then
    echo "ERROR: Instance not ready (state: $STATE)"
    exit 1
fi
echo "      ✓ Instance is RUNNABLE"
echo ""

# Step 3: Grant IAM permissions
echo "[3/5] Granting Vertex AI permissions..."

SERVICE_ACCOUNT=$(gcloud sql instances describe "$DB_INSTANCE" \
    --format='value(serviceAccountEmailAddress)')

if [ -z "$SERVICE_ACCOUNT" ]; then
    echo "ERROR: Could not retrieve service account"
    exit 1
fi

gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
    --member="serviceAccount:$SERVICE_ACCOUNT" \
    --role="roles/aiplatform.user" \
    --quiet

echo "      ✓ Permissions granted"
echo ""

# Step 4: Create database
echo "[4/5] Creating database..."

# Check if database already exists
if gcloud sql databases describe "$DB_NAME" \
    --instance="$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Database already exists"
else
    gcloud sql databases create "$DB_NAME" \
        --instance="$DB_INSTANCE" \
        --quiet
fi

echo "      ✓ Database '$DB_NAME' ready"
echo ""

# Step 5: Seed database and generate embeddings
echo "[5/5] Seeding database and generating embeddings..."

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETUP_SCRIPT="${SCRIPT_DIR}/setup_restaurant_db.py"

if [ ! -f "$SETUP_SCRIPT" ]; then
    echo "ERROR: Setup script not found: $SETUP_SCRIPT"
    exit 1
fi

uv run "$SETUP_SCRIPT"

echo ""
echo "================================================"
echo "Setup complete!"
echo "================================================"
echo ""

Tạo tập lệnh Python để gieo dữ liệu

Sau đó, hãy tạo tệp python tập lệnh gieo hạt scripts/setup_restaurant_db.py bằng lệnh bên dưới

cloudshell edit scripts/setup_restaurant_db.py

Sau đó, sao chép mã sau vào tệp scripts/setup_restaurant_db.py

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.cloud.sql.connector import Connector
import pg8000
import time

# Load environment variables from .env file
env_path = Path(__file__).parent.parent / '.env'
load_dotenv(env_path)
EMBEDDING_MODEL='gemini-embedding-001'

# Verify required environment variables
required_vars = ['GOOGLE_CLOUD_PROJECT', 'REGION', 'DB_PASSWORD']
missing_vars = [var for var in required_vars if not os.environ.get(var)]

if missing_vars:
    print(f"ERROR: Missing required environment variables: {', '.join(missing_vars)}", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Expected .env file location: {env_path}", file=sys.stderr)
    if not env_path.exists():
        print(f"✗ File not found at that location", file=sys.stderr)
    else:
        print(f"✓ File exists but is missing the variables above", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Make sure your .env file contains:", file=sys.stderr)
    for var in missing_vars:
        print(f"  {var}=<value>", file=sys.stderr)
    sys.exit(1)

# Menu items data
MENU_ITEMS = [
    ("Truffle Mushroom Risotto", "Italian", "Main Course",
     "Arborio rice, truffle oil, porcini mushrooms, parmesan, white wine",
     "$28", "Vegetarian, Gluten-Free", True,
     "A creamy, luxurious risotto made with arborio rice slow-cooked in white wine and mushroom broth, finished with shaved black truffle and aged parmesan. The porcini mushrooms add a deep, earthy flavor that pairs beautifully with the delicate truffle oil drizzled on top."),
    ("Spicy Tuna Tartare", "Japanese", "Appetizer",
     "Ahi tuna, sriracha, sesame oil, avocado, crispy wonton",
     "$22", "Gluten-Free, Dairy-Free", True,
     "Fresh ahi tuna diced and tossed with sriracha aioli, toasted sesame oil, and lime juice, served atop creamy avocado slices with crispy wonton chips. A perfect balance of heat, richness, and crunch inspired by modern Japanese fusion cuisine."),
    ("Lamb Kofta Kebab", "Middle Eastern", "Main Course",
     "Ground lamb, cumin, coriander, yogurt sauce, flatbread",
     "$24", "Halal", True,
     "Hand-formed spiced lamb kebabs grilled over charcoal, seasoned with cumin, coriander, and sumac. Served with warm flatbread, tangy yogurt-cucumber sauce, and a fresh herb salad. A classic Middle Eastern street food elevated with premium ingredients."),
    ("Pad Thai", "Thai", "Main Course",
     "Rice noodles, shrimp, tamarind, peanuts, bean sprouts, lime",
     "$19", "Gluten-Free, Dairy-Free", True,
     "Stir-fried rice noodles with tiger shrimp, scrambled egg, and a sweet-sour tamarind sauce, topped with crushed peanuts, fresh bean sprouts, and a squeeze of lime. This classic Thai street food dish balances sweet, sour, salty, and umami in every bite."),
    ("Margherita Pizza", "Italian", "Main Course",
     "San Marzano tomatoes, fresh mozzarella, basil, olive oil",
     "$18", "Vegetarian", True,
     "A Neapolitan-style pizza with a thin, charred crust topped with crushed San Marzano tomatoes, creamy buffalo mozzarella, fresh basil leaves, and a drizzle of extra virgin olive oil. Simple, classic, and made with imported Italian ingredients."),
    ("Miso Glazed Black Cod", "Japanese", "Main Course",
     "Black cod, white miso, mirin, sake, pickled ginger",
     "$36", "Gluten-Free, Dairy-Free", True,
     "Buttery black cod marinated for 72 hours in a sweet white miso glaze with mirin and sake, then broiled until caramelized. Served with pickled ginger and steamed bok choy. A signature dish inspired by Nobu's iconic preparation."),
    ("Caesar Salad", "American", "Appetizer",
     "Romaine lettuce, parmesan, croutons, anchovy dressing",
     "$14", "Contains Gluten", True,
     "Crisp romaine hearts tossed with a house-made anchovy-garlic dressing, shaved parmesan, and golden sourdough croutons. A timeless salad that serves as the perfect light starter or side dish with grilled proteins."),
    ("Chicken Tikka Masala", "Indian", "Main Course",
     "Chicken thigh, tomato cream sauce, garam masala, basmati rice",
     "$21", "Gluten-Free", True,
     "Tender chunks of tandoori-marinated chicken simmered in a rich, creamy tomato sauce spiced with garam masala, cumin, and fenugreek. Served over fragrant basmati rice with warm garlic naan on the side."),
    ("Chocolate Lava Cake", "French", "Dessert",
     "Dark chocolate, butter, eggs, vanilla, powdered sugar",
     "$15", "Vegetarian", True,
     "A warm, individual-sized chocolate cake with a molten dark chocolate center that flows when you break through the delicate outer shell. Made with 70% Belgian dark chocolate and served with a scoop of vanilla bean ice cream."),
    ("Pho Bo", "Vietnamese", "Main Course",
     "Rice noodles, beef brisket, star anise, cinnamon, bean sprouts, Thai basil",
     "$17", "Gluten-Free, Dairy-Free", True,
     "A deeply aromatic beef broth simmered for 12 hours with star anise, cinnamon, and charred ginger, ladled over rice noodles and thinly sliced beef brisket. Served with fresh Thai basil, bean sprouts, jalapeño, and lime for the table to customize."),
    ("Lobster Bisque", "French", "Appetizer",
     "Lobster, heavy cream, cognac, tarragon, cayenne",
     "$19", "Gluten-Free", True,
     "A velvety smooth soup made from roasted lobster shells, finished with heavy cream, a splash of cognac, and fresh tarragon. Each bowl is garnished with tender lobster meat and a pinch of cayenne for subtle warmth."),
    ("Falafel Plate", "Middle Eastern", "Main Course",
     "Chickpeas, herbs, tahini, pickled vegetables, hummus",
     "$16", "Vegan, Gluten-Free", True,
     "Crispy-on-the-outside, fluffy-on-the-inside chickpea fritters seasoned with fresh parsley, cilantro, and cumin. Served with creamy tahini sauce, house-made hummus, pickled turnips, and warm pita bread."),
    ("Crème Brûlée", "French", "Dessert",
     "Heavy cream, vanilla bean, egg yolks, caramelized sugar",
     "$13", "Vegetarian, Gluten-Free", True,
     "A classic French custard made with Madagascar vanilla bean and farm-fresh egg yolks, topped with a perfectly torched layer of caramelized sugar that cracks with a satisfying snap. Rich, creamy, and elegantly simple."),
    ("Korean BBQ Short Ribs", "Korean", "Main Course",
     "Beef short ribs, soy sauce, sesame, garlic, pear marinade",
     "$32", "Dairy-Free", False,
     "Premium beef short ribs marinated overnight in a sweet and savory blend of soy sauce, Asian pear, garlic, and toasted sesame. Grilled tableside over charcoal and served with lettuce wraps, pickled daikon, and gochujang dipping sauce."),
    ("Tiramisu", "Italian", "Dessert",
     "Mascarpone, espresso, ladyfingers, cocoa, Marsala wine",
     "$14", "Vegetarian, Contains Gluten", True,
     "Layers of espresso-soaked ladyfingers and whipped mascarpone cream flavored with Marsala wine, dusted with premium Dutch cocoa powder. Made fresh daily and chilled for 24 hours to develop rich, complex flavors."),
]


def get_connection():
    """Create a connection to Cloud SQL using the connector."""
    project = os.environ['GOOGLE_CLOUD_PROJECT']
    region = os.environ['REGION']
    password = os.environ['DB_PASSWORD']
    instance = os.environ['DB_INSTANCE']
    database = os.environ['DB_NAME']

    connector = Connector()
    conn = connector.connect(
        f"{project}:{region}:{instance}",
        "pg8000",
        user="postgres",
        password=password,
        db=database
    )
    return conn, connector


def create_schema(cursor):
    """Create extensions and menu_items table."""
    cursor.execute("CREATE EXTENSION IF NOT EXISTS google_ml_integration")
    cursor.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS menu_items (
            id SERIAL PRIMARY KEY,
            name VARCHAR NOT NULL,
            cuisine_type VARCHAR NOT NULL,
            category VARCHAR NOT NULL,
            ingredients VARCHAR NOT NULL,
            price VARCHAR NOT NULL,
            dietary_tags VARCHAR NOT NULL,
            available BOOLEAN NOT NULL DEFAULT TRUE,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_menu_items(cursor, conn):
    """Insert menu items."""
    cursor.execute("SELECT COUNT(*) FROM menu_items")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} menu items already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO menu_items (name, cuisine_type, category, ingredients, price, dietary_tags, available, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, MENU_ITEMS)
    conn.commit()
    return len(MENU_ITEMS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM menu_items WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All menu items already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE menu_items
        SET description_embedding = embedding('{EMBEDDING_MODEL}', description)::vector
        WHERE description_embedding IS NULL
    """)
    rows_updated = cursor.rowcount
    conn.commit()
    return rows_updated


def main():
    conn, connector = get_connection()
    cursor = conn.cursor()

    try:
        create_schema(cursor)
        conn.commit()

        seeded = seed_menu_items(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} menu items")

        # Waiting for vertex role propagation
        time.sleep(60)
        embedded = generate_embeddings(cursor, conn)
        if embedded > 0:
            print(f"      ✓ Generated {embedded} embeddings")

    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        cursor.close()
        conn.close()
        connector.close()


if __name__ == "__main__":
    main()

Bây giờ, hãy chuyển sang bước tiếp theo

4. Tạo và khởi chạy cơ sở dữ liệu

Giờ đây, các tập lệnh của chúng ta đã sẵn sàng để thực thi. Chúng ta sẽ cần Python để thực thi tập lệnh đã chuẩn bị, vì vậy, trước tiên, hãy chuẩn bị tập lệnh đó

Thiết lập dự án Python

uv là một trình quản lý dự án và gói Python nhanh được viết bằng Rust ( tài liệu uv ). Lớp học lập trình này sử dụng uv để duy trì dự án Python một cách nhanh chóng và đơn giản

Khởi động một dự án Python và thêm các phần phụ thuộc bắt buộc:

uv init
uv add cloud-sql-python-connector --extra pg8000
uv add python-dotenv

Xin lưu ý rằng ở đây, chúng ta đang sử dụng cloud-sql-python-connector Python SDK để khởi chạy một kết nối an toàn với phiên bản cơ sở dữ liệu được xác thực bằng Thông tin đăng nhập mặc định của ứng dụng.

Thực thi tập lệnh thiết lập

Giờ đây, chúng ta có thể chạy tập lệnh thiết lập ở chế độ nền và kiểm tra đầu ra của bảng điều khiển sẽ được ghi vào tệp logs/atabase_setup.log bằng lệnh sau. Bạn có thể tiếp tục chuyển sang phần tiếp theo trong khi chờ quá trình này hoàn tất

mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs
bash scripts/setup_database.sh > logs/database_setup.log 2>&1 &

Tải tệp nhị phân của Hộp công cụ xuống

Chúng ta sẽ sử dụng MCP Toolbox trong hướng dẫn này. May mắn là công cụ này đi kèm với một tệp nhị phân được tạo sẵn và sẵn sàng sử dụng trong môi trường Linux. Giờ đây, hãy tải tệp nhị phân này xuống ở chế độ nền vì quá trình này mất khá nhiều thời gian. Chạy lệnh sau để tải tệp nhị phân xuống và kiểm tra nhật ký đầu ra trên logs/toolbox_dl.log. Bạn có thể tiếp tục chuyển sang phần tiếp theo trong khi chờ quá trình này hoàn tất

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.1.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

Tìm hiểu về tập lệnh thiết lập `scripts/setup_database.sh`

Bây giờ, hãy thử tìm hiểu tập lệnh thiết lập mà chúng ta đã định cấu hình trước đó. Quy trình này thực hiện những việc sau

Lệnh đầu tiên mà chúng ta thực thi ở đó là lệnh gcloud sql instances create có cờ sau

db-custom-1-3840 là cấp Cloud SQL nhỏ nhất có lõi chuyên dụng (1 vCPU, RAM 3,75 GB) trong phiên bản ENTERPRISE. Bạn có thể đọc thêm thông tin chi tiết tại đây. Bạn cần có một lõi chuyên dụng để tích hợp Vertex AI ML – các cấp lõi dùng chung (db-f1-micro, db-g1-small) không hỗ trợ tính năng này.
--root-password đặt mật khẩu cho người dùng postgres mặc định.
--enable-google-ml-integration cho phép tích hợp sẵn Cloud SQL với Vertex AI, giúp bạn gọi các mô hình nhúng trực tiếp từ SQL bằng hàm embedding().

Xác minh xem phiên bản đã ở trạng thái RUNNABLE hay chưa
Cấp cho tài khoản dịch vụ của phiên bản Cloud SQL quyền gọi Vertex AI bằng lệnh gcloud projects add-iam-policy-binding. Đây là yêu cầu bắt buộc đối với hàm embedding() tích hợp mà chúng ta sẽ dùng khi gieo dữ liệu vào cơ sở dữ liệu
Tạo cơ sở dữ liệu
Thực thi tập lệnh gieo hạt setup_restaurant_db.py

Tìm hiểu về tập lệnh ban đầu `scripts/setup_restaurant_db.py`

Bây giờ, hãy chuyển sang tập lệnh gieo hạt. Tập lệnh này sẽ thực hiện những việc sau:

Khởi tạo kết nối đến phiên bản cơ sở dữ liệu
Cài đặt 2 tiện ích PostgreSQL:

google_ml_integration – cung cấp hàm SQL embedding(), gọi các mô hình nhúng Vertex AI trực tiếp từ SQL. Đây là một tiện ích ở cấp cơ sở dữ liệu giúp các hàm ML có sẵn trong restaurant_db. Cờ cấp phiên bản (--enable-google-ml-integration) mà bạn đặt trong quá trình tạo phiên bản cho phép VM Cloud SQL truy cập vào Vertex AI – tiện ích này cung cấp các hàm SQL trong cơ sở dữ liệu cụ thể này.
vector (pgvector) – thêm kiểu dữ liệu vector và các toán tử khoảng cách để lưu trữ và truy vấn các mục nhúng.

Tạo bảng, lưu ý rằng cột description_embedding là vector(3072) — một cột pgvector lưu trữ các vectơ 3072 chiều.
Gieo dữ liệu ban đầu cho các mục trong trình đơn
Tạo dữ liệu nhúng từ trường description và điền vào description_embedding bằng cách sử dụng tính năng tích hợp đỉnh được tích hợp sẵn thông qua hàm embedding()

embedding('gemini-embedding-001', description) – gọi mô hình nhúng Gemini của Vertex AI trực tiếp từ SQL, truyền văn bản description của từng công việc. Đây là tiện ích google_ml_integration mà bạn đã cài đặt trong tập lệnh ban đầu.
::vector – truyền mảng số thực được trả về sang kiểu vector của pgvector để có thể lưu trữ và truy vấn bằng các toán tử khoảng cách.
UPDATE chạy trên cả 15 hàng, tạo ra một vectơ nhúng 3072 chiều cho mỗi nội dung mô tả công việc.

Thao tác này sẽ chuẩn bị dữ liệu ban đầu mà tác nhân của chúng tôi sẽ truy cập

5. Định cấu hình Bộ công cụ MCP cho cơ sở dữ liệu

Bước này giới thiệu Bộ công cụ MCP dành cho cơ sở dữ liệu, định cấu hình bộ công cụ này để kết nối với phiên bản Cloud SQL của bạn và xác định 2 công cụ truy vấn SQL tiêu chuẩn.

MCP là gì và tại sao nên sử dụng Toolbox?

MCP (Giao thức ngữ cảnh mô hình) là một giao thức mở giúp chuẩn hoá cách các tác nhân AI khám phá và tương tác với các công cụ bên ngoài. Nó xác định một mô hình ứng dụng-máy chủ: tác nhân lưu trữ một ứng dụng MCP và các công cụ được máy chủ MCP hiển thị. Mọi ứng dụng tương thích với MCP đều có thể sử dụng mọi máy chủ tương thích với MCP – tác nhân không cần mã tích hợp tuỳ chỉnh cho từng công cụ.

Bộ công cụ MCP dành cho cơ sở dữ liệu là một máy chủ MCP nguồn mở được xây dựng dành riêng cho quyền truy cập vào cơ sở dữ liệu. Nếu không có bộ công cụ này, bạn sẽ viết các hàm Python mở kết nối cơ sở dữ liệu, quản lý nhóm kết nối, tạo truy vấn được tham số hoá để ngăn chặn kỹ thuật chèn SQL, xử lý lỗi và nhúng tất cả mã đó vào tác nhân của bạn. Mọi tác nhân cần có quyền truy cập vào cơ sở dữ liệu đều lặp lại công việc này. Việc thay đổi một truy vấn có nghĩa là triển khai lại tác nhân.

Với Toolbox, bạn sẽ viết một tệp YAML. Mỗi công cụ sẽ liên kết đến một câu lệnh SQL có tham số. Toolbox xử lý việc gộp kết nối, truy vấn có tham số, xác thực và khả năng quan sát. Các công cụ được tách biệt khỏi tác nhân – cập nhật truy vấn bằng cách chỉnh sửa tools.yaml và khởi động lại Toolbox mà không cần chỉnh sửa mã tác nhân. Các công cụ này hoạt động trên ADK, LangGraph, LlamaIndex hoặc bất kỳ khung tương thích nào với MCP.

Viết cấu hình công cụ

Bây giờ, chúng ta cần tạo một tệp có tên là tools.yaml trong Cloud Shell Editor để thiết lập cấu hình công cụ

cloudshell edit tools.yaml

Tệp này sử dụng YAML nhiều tài liệu – mỗi khối được phân tách bằng --- là một tài nguyên độc lập. Mỗi tài nguyên đều có một kind khai báo tài nguyên đó là gì (sources cho các mối kết nối cơ sở dữ liệu, tools cho các thao tác có thể gọi của tác nhân) và một type chỉ định phần phụ trợ (cloud-sql-postgres cho nguồn, postgres-sql cho các công cụ dựa trên SQL). Một công cụ tham chiếu nguồn của nó bằng name. Đây là cách Toolbox biết nên thực thi nhóm kết nối nào. Các biến môi trường sử dụng cú pháp ${VAR_NAME} và được phân giải khi khởi động.

Bây giờ, trước tiên hãy sao chép các tập lệnh sau vào tệp tools.yaml

# tools.yaml

# --- Data Source ---
kind: source
name: restaurant-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---