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

قاعدة البيانات كأداة: التوليد المعزّز بالاسترجاع المستند إلى الوكيل باستخدام "حزمة تطوير التطبيقات" و"مجموعة أدوات MCP" وCloud SQL

1. مقدمة

تكون الوكلاء المستندون إلى الذكاء الاصطناعي مفيدين بقدر البيانات التي يمكنهم الوصول إليها فقط. وتتوفّر معظم البيانات الواقعية في قواعد البيانات، وعادةً ما يعني ربط الوكلاء بقواعد البيانات كتابة إدارة الاتصال ومنطق طلب البحث وتضمين قنوات العرض داخل رمز الوكيل. ويكرّر كل وكيل يحتاج إلى الوصول إلى قاعدة البيانات هذه العملية، ويتطلّب كل تغيير في طلب البحث إعادة نشر الوكيل.

يوضّح هذا الدرس التطبيقي العملي طريقة مختلفة. يمكنك تحديد أدوات قاعدة البيانات في ملف YAML، مثل طلبات البحث بلغة الاستعلامات البنيوية (SQL) العادية، والبحث عن التشابه بين المتّجهات، وحتى إنشاء عمليات تضمين تلقائية، ويتولّى MCP Toolbox for Databases جميع عمليات قاعدة البيانات كخادم MCP. يظل رمز الوكيل بسيطًا: حمِّل الأدوات، ودَع Gemini يقرّر الأداة التي سيستخدمها.

ما ستنشئه

مساعد المطاعم في "اكتشاف أطباق جديدة": هو وكيل ADK يستند إلى Gemini ويساعد روّاد المطعم في تصفّح قائمة الطعام باستخدام الفلاتر العادية (الفئة ونوع المطبخ) واكتشاف الأطباق من خلال أوصاف باللغة الطبيعية، مثل "أريد طبقًا حارًا ونباتيًا". يقرأ الوكيل من قاعدة بيانات Cloud SQL PostgreSQL ويكتب فيها بالكامل من خلال MCP Toolbox for Databases، التي تتعامل مع جميع عمليات الوصول إلى قاعدة البيانات، بما في ذلك إنشاء عمليات تضمين تلقائية للبحث عن المتّجهات. وفي النهاية، يتم تشغيل كلّ من Toolbox والوكيل على Cloud Run.

ما ستتعلمه

كيف يوحّد بروتوكول MCP (بروتوكول سياق النموذج) إمكانية الوصول إلى الأدوات لوكلاء الذكاء الاصطناعي، وكيف تطبّق أداة MCP Toolbox for Databases ذلك على عمليات قواعد البيانات
إعداد MCP Toolbox for Databases كبرنامج وسيط بين وكيل ADK وCloud SQL PostgreSQL
تحديد أدوات قاعدة البيانات بشكل تعريفي في tools.yaml - بدون رمز قاعدة بيانات في الوكيل
إنشاء وكيل ADK يحمّل الأدوات من خادم Toolbox قيد التشغيل باستخدام ToolboxToolset
إنشاء تضمينات متجهة باستخدام الدالة المضمّنة embedding() في Cloud SQL وتفعيل البحث الدلالي باستخدام pgvector
استخدام ميزة valueFromParam لإدخال المتجهات تلقائيًا في عمليات الكتابة
نشر كلّ من خادم Toolbox ووكيل ADK على Cloud Run

المتطلبات الأساسية

حساب Google Cloud يتضمّن حساب فوترة تجريبيًا
معرفة أساسية بلغة Python وSQL
ستكون الخبرة السابقة في Cloud Database وADK مفيدة

2. إعداد البيئة

تجهّز هذه الخطوة بيئة Cloud Shell وتضبط مشروعك على Google Cloud وتستنسخ المستودع المرجعي.

فتح Cloud Shell

افتح Cloud Shell في المتصفّح. توفّر Cloud Shell بيئة تم ضبطها مسبقًا تتضمّن جميع الأدوات التي تحتاج إليها في هذا الدرس التطبيقي حول الترميز. انقر على تفويض عندما يُطلب منك ذلك

بعد ذلك، انقر على عرض -> وحدة طرفية لفتح الوحدة الطرفية.يجب أن تبدو واجهتك مشابهة لما يلي

ستكون هذه هي واجهتنا الرئيسية، مع وضع بيئة التطوير المتكاملة في الأعلى والوحدة الطرفية في الأسفل.

إعداد دليل العمل

أنشئ دليل العمل. يتم تخزين جميع الرموز التي تكتبها في هذا الدرس التطبيقي حول الترميز هنا:

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

بعد ذلك، لنجهّز عدة أدلة لإدارة أمور مثل نصوص البرامج الأولية والسجلات

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

إعداد مشروعك على Google Cloud

أنشئ ملف .env يحتوي على متغيّرات الموقع الجغرافي:

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

ملاحظة مهمة: يتم توفير الخطوة أدناه للمساعدة في إعداد مشروع Google Cloud المرتبط بحساب فوترة تجريبي (إلزامي) بسرعة. إذا كنت تفضّل استخدام مشروعك السابق، يمكنك تخطّي الخطوة التالية وتنفيذ الخطوة التالية بدلاً منها:

إضافة اسم مشروعك كمتغيّر GOOGLE_CLOUD_PROJECT في الملف .env
تفعيل مشروعك في نافذة الجهاز باستخدام gcloud config set project your-project-id

بعد ذلك، يمكنك الانتقال مباشرةً إلى قسم تفعيل واجهة برمجة التطبيقات.

إذا لم تكن متأكدًا من ذلك، يمكنك مواصلة قراءة القسم أدناه.

لتبسيط عملية إعداد المشاريع في الوحدة الطرفية، نزِّل نص برمجي لإعداد المشاريع في دليل العمل:

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

نفِّذ النص البرمجي. سيتحقّق من حساب الفوترة التجريبي، وينشئ مشروعًا جديدًا (أو يتحقّق من صحة مشروع حالي)، ويحفظ رقم تعريف مشروعك في ملف .env في الدليل الحالي، ويضبط المشروع النشط في gcloud.

bash setup_verify_trial_project.sh && source .env

سيؤدي النص البرمجي إلى ما يلي:

التأكّد من أنّ لديك حساب فوترة نشطًا لفترة تجريبية
التحقّق من وجود مشروع حالي في .env (إن وُجد)
إنشاء مشروع جديد أو إعادة استخدام المشروع الحالي
ربط حساب الفوترة التجريبي بمشروعك
احفظ رقم تعريف المشروع في .env
ضبط المشروع كمشروع gcloud نشط

تأكَّد من ضبط المشروع بشكل صحيح من خلال التحقّق من النص الأصفر بجانب دليل العمل في طلب Cloud Shell. من المفترض أن يعرض رقم تعريف مشروعك.

تفعيل واجهة برمجة التطبيقات المطلوبة

بعد ذلك، علينا تفعيل عدة واجهات برمجة تطبيقات للمنتج الذي سنتفاعل معه:

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): يستخدم الوكيل نماذج Gemini، وتستخدم "مجموعة الأدوات" واجهة برمجة التطبيقات الخاصة بالترميز للبحث المتّجه.
واجهة برمجة التطبيقات Cloud SQL Admin API (sqladmin.googleapis.com): يمكنك توفير مثيل PostgreSQL وإدارته.
Compute Engine API (compute.googleapis.com): مطلوب لإنشاء مثيلات Cloud SQL.
‫Cloud Run وCloud Build وArtifact Registry: يتم استخدامها في خطوة النشر لاحقًا في هذا الدرس التطبيقي حول الترميز

3- تجهيز النصوص البرمجية لإعداد قاعدة البيانات

تبدأ هذه الخطوة بإنشاء مثيل Cloud SQL وتشغيل نص التهيئة البرمجي المُبرمَج للإعداد ينتظر إلى أن يصبح المثيل جاهزًا، ثم ينشئ قاعدة البيانات ويملأها ببيانات الوظائف الشاغرة وينشئ عمليات التضمين، وكل ذلك في عملية واحدة.

أولاً، لنضِف كلمة مرور قاعدة البيانات إلى ملف .env ثم نعيد تحميله:

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

إنشاء نص برمجي Bash لإنشاء مثيل وقاعدة بيانات

بعد ذلك، أنشئ النص البرمجي scripts/setup_database.sh باستخدام الأمر التالي

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

بعد ذلك، انسخ الرمز التالي في ملف 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 ""

إنشاء نص برمجي بلغة Python لإنشاء بيانات أولية

بعد ذلك، أنشئ ملف python الخاص بنص التعبئة scripts/setup_restaurant_db.py باستخدام الأمر أدناه

cloudshell edit scripts/setup_restaurant_db.py

بعد ذلك، انسخ الرمز التالي في ملف 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()

لننتقل الآن إلى الخطوة التالية

4. إنشاء قاعدة البيانات وتهيئتها

أصبحت النصوص البرمجية جاهزة للتنفيذ، ولكننا سنحتاج إلى Python لتنفيذ النص البرمجي الذي أعددناه، لذا لنبدأ بإعداد Python أولاً.

إعداد مشروع Python

‫uv هي حزمة Python سريعة وأداة لإدارة المشاريع مكتوبة بلغة Rust ( مستندات uv). تستخدم هذه التجربة العملية هذه الحزمة لتحقيق السرعة والبساطة في الحفاظ على مشروع Python.

ابدأ مشروع Python وأضِف التبعيات المطلوبة:

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

يُرجى العِلم أنّنا نستخدم حزمة تطوير البرامج (SDK) الخاصة بلغة Python هنا لإنشاء اتصال آمن بنسخة قاعدة البيانات التي يتمّ إثبات صحتها باستخدام بيانات الاعتماد التلقائية للتطبيق.cloud-sql-python-connector

تنفيذ نص التهيئة البرمجي

يمكننا الآن تشغيل نص التهيئة البرمجي في الخلفية وفحص ناتج وحدة التحكّم الذي سيتمّ كتابته في ملف logs/atabase_setup.log باستخدام الأمر التالي. يمكنك الانتقال إلى القسم التالي أثناء انتظار انتهاء هذه العملية.

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

تنزيل ملف Toolbox الثنائي

سنستخدم أداة MCP Toolbox في هذا البرنامج التعليمي، وهي تتضمّن لحسن الحظ ملفًا ثنائيًا مُعدًا مسبقًا وجاهزًا للاستخدام في بيئة Linux. لننزّله الآن في الخلفية لأنّ العملية تستغرق بعض الوقت. شغِّل الأمر التالي لتنزيل الملف الثنائي وفحص سجل الإخراج على logs/toolbox_dl.log. يمكنك الانتقال إلى القسم التالي أثناء انتظار انتهاء العملية.

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 &

فهم نص التهيئة البرمجي `scripts/setup_database.sh`

لنحاول الآن فهم نص التهيئة البرمجي الذي سبق أن أعددناه. تتضمّن هذه العملية الخطوات التالية:

أول أمر ننفّذه هو الأمر gcloud sql instances create مع العلامة التالية

‫db-custom-1-3840 هي أصغر فئة من فئات Cloud SQL ذات النواة المخصّصة (وحدة معالجة مركزية افتراضية واحدة، وذاكرة وصول عشوائي سعتها 3.75 غيغابايت) في إصدار ENTERPRISE. يمكنك الاطّلاع على مزيد من التفاصيل هنا. يجب توفّر نواة مخصّصة لإتاحة دمج تعلُّم الآلة من Vertex AI، ولا تتوافق فئات النواة المشتركة (db-f1-micro وdb-g1-small) مع هذه الميزة.
--root-password يضبط كلمة المرور للمستخدم التلقائي postgres.
تتيح --enable-google-ml-integration إمكانية الدمج المضمّن في Cloud SQL مع Vertex AI، ما يتيح لك استدعاء نماذج التضمين مباشرةً من SQL باستخدام الدالة embedding().

التحقّق ممّا إذا كانت الآلة الافتراضية في الحالة RUNNABLE
امنح حساب خدمة مثيل Cloud SQL الإذن باستدعاء Vertex AI باستخدام الأمر gcloud projects add-iam-policy-binding. هذا مطلوب للدالة embedding() المضمّنة التي سنستخدمها عند إنشاء قاعدة البيانات
إنشاء قاعدة البيانات
تنفيذ النص البرمجي setup_restaurant_db.py الخاص بإنشاء البيانات الأولية

فهم النص البرمجي الأوّلي `scripts/setup_restaurant_db.py`

بالانتقال الآن إلى نص التعبئة، ينفّذ هذا النص الإجراءات التالية:

تهيئة عملية الربط بمثيل قاعدة البيانات
تثبِّت هذه الحزمة إضافتَين إلى PostgreSQL:

google_ml_integration: توفّر دالة embedding() SQL التي تستدعي نماذج التضمين في Vertex AI مباشرةً من SQL. هذا هو امتداد على مستوى قاعدة البيانات يتيح استخدام دوال تعلُّم الآلة داخل restaurant_db. يتيح الخيار على مستوى المثيل (--enable-google-ml-integration) الذي تحدّده أثناء إنشاء المثيل لجهاز Cloud SQL الظاهري الوصول إلى Vertex AI، ويوفّر الامتداد دوال SQL داخل قاعدة البيانات المحدّدة هذه.
vector (pgvector): يضيف نوع البيانات vector وعوامل تشغيل المسافة لتخزين عمليات التضمين والاستعلام عنها.

أنشئ الجدول، مع العلم أنّ العمود description_embedding هو vector(3072)، أي عمود pgvector يخزّن متجهات ذات 3072 بُعدًا.
تعبئة بيانات عناصر القائمة الأولية
إنشاء بيانات التضمين من الحقل description وملء description_embedding باستخدام عملية التكامل المضمّنة في Vertex من خلال الدالة embedding()

embedding('gemini-embedding-001', description): تستدعي نموذج التضمين Gemini في Vertex AI مباشرةً من SQL، مع تمرير نص description لكل مهمة. هذه هي إضافة google_ml_integration التي ثبَّتها في النص البرمجي الأوّلي.
‫::vector: تحويل مصفوفة الأعداد العشرية التي تم إرجاعها إلى نوع vector في pgvector حتى يمكن تخزينها والاستعلام عنها باستخدام عوامل تشغيل المسافة
يتم تشغيل UPDATE على جميع الصفوف الـ 15، ما يؤدي إلى إنشاء تضمين واحد بـ 3072 بُعدًا لكل وصف وظيفي.

سيؤدي ذلك إلى إعداد البيانات الأولية التي سيصل إليها الوكيل

5- ضبط إعدادات MCP Toolbox for Databases

تتضمّن هذه الخطوة تقديم MCP Toolbox for Databases، وإعدادها للاتصال بمثيل Cloud SQL، وتحديد أداتَي طلب بحث SQL عاديتَين.

ما هو بروتوكول MCP ولماذا يجب استخدام "مجموعة الأدوات"؟

بروتوكول سياق النموذج (MCP) هو بروتوكول مفتوح يوحّد طريقة عثور وكلاء الذكاء الاصطناعي على الأدوات الخارجية والتفاعل معها. يحدّد هذا النموذج نموذجًا للعميل والخادم: يستضيف الوكيل عميل MCP، وتوفّر خوادم MCP الأدوات. يمكن لأي عميل متوافق مع MCP استخدام أي خادم متوافق مع MCP، ولا يحتاج الوكيل إلى رمز دمج مخصّص لكل أداة.

MCP Toolbox for Databases هو خادم MCP مفتوح المصدر تم إنشاؤه خصيصًا للوصول إلى قواعد البيانات. بدون ذلك، ستكتب دوال Python التي تفتح اتصالات بقاعدة البيانات، وتدير مجموعات الاتصال، وتنشئ استعلامات ذات معلَمات لمنع إدخال تعليمات برمجية SQL ضارة، وتتعامل مع الأخطاء، وتضمّن كل هذا الرمز البرمجي داخل برنامجك. ويكرّر كل وكيل يحتاج إلى الوصول إلى قاعدة البيانات هذه العملية. يعني تغيير الاستعلام إعادة نشر الوكيل.

باستخدام Toolbox، يمكنك كتابة ملف YAML. ترتبط كل أداة بعبارة SQL ذات معلَمات. تتعامل "مجموعة الأدوات" مع تجميع الاتصالات، والاستعلامات التي تتضمّن مَعلمات، والمصادقة، وإمكانية المراقبة. يتم فصل الأدوات عن الوكيل، ويمكنك تعديل طلب بحث من خلال تعديل tools.yaml وإعادة تشغيل Toolbox بدون تعديل رمز الوكيل. تعمل الأدوات نفسها على جميع إطارات العمل المتوافقة مع MCP، مثل ADK أو LangGraph أو LlamaIndex.

كتابة إعدادات الأدوات

الآن، علينا إنشاء ملف باسم tools.yaml في "محرّر Cloud Shell" لإعداد ضبط الأدوات.

cloudshell edit tools.yaml

يستخدم الملف YAML متعدد المستندات، وكل كتلة مفصولة بـ --- هي مورد مستقل. يحتوي كل مصدر على kind يوضّح نوعه (sources لعمليات ربط قواعد البيانات، وtools للإجراءات التي يمكن أن ينفّذها الوكيل) وtype يحدّد الخلفية (cloud-sql-postgres للمصدر، وpostgres-sql للأدوات المستندة إلى SQL). تشير الأداة إلى مصدرها باستخدام name، وهي الطريقة التي تعرف بها Toolbox مجموعة الاتصال التي سيتم تنفيذها. تستخدم متغيرات البيئة بنية ${VAR_NAME} ويتم تحديدها عند بدء التشغيل.

لننسخ الآن البرامج النصية التالية أولاً إلى ملف 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}

---