تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

‫Google Cloud MCP لوكلاء الذكاء الاصطناعي في AlloyDB

1. مقدمة

يقدّم هذا الدرس التطبيقي حول الترميز دليلاً حول كيفية بدء استخدام خادم MCP من Google Cloud لـ AlloyDB وتفعيله كجزء من مجموعة الأدوات الخاصة بوكيل مستند إلى الذكاء الاصطناعي واستخدامه كجزء من التطبيق.

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

فهم أساسي لـ Google Cloud وGoogle Cloud Console
مهارات أساسية في واجهة سطر الأوامر وCloud Shell

ما ستتعلمه

كيفية إنشاء مجموعة AlloyDB واستيراد بيانات نموذجية
كيفية تفعيل واجهة AlloyDB Data access API
كيفية تفعيل ميزة "المعالجة المتوازية الضخمة" في Google Cloud لخدمة AlloyDB NL
كيفية إضافة Google Cloud MCP لـ AlloyDB إلى وكيل ADK
كيفية استخدام Google Cloud MCP مع AlloyDB في أحد التطبيقات
كيفية استخدام الوكلاء مع AlloyDB MCP للإحصاءات

المتطلبات

حساب Google Cloud ومشروع Google Cloud
متصفّح ويب، مثل Chrome، متوافق مع "وحدة تحكّم Google Cloud" وCloud Shell

2. الإعداد والمتطلبات

إعداد المشروع

سجِّل الدخول إلى Google Cloud Console. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

استخدام حساب شخصي بدلاً من حساب تابع للعمل أو لمؤسسة تعليمية

أنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. لإنشاء مشروع جديد في Google Cloud Console، انقر على الزر "اختيار مشروع" في العنوان، ما سيؤدي إلى فتح نافذة منبثقة.

في نافذة "اختيار مشروع"، انقر على الزر "مشروع جديد" الذي سيفتح مربع حوار للمشروع الجديد.

في مربّع الحوار، أدخِل اسم المشروع المفضّل لديك واختَر الموقع الجغرافي.

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

تفعيل الفوترة

إعداد حساب فوترة شخصي

إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.

لإعداد حساب فوترة شخصي، انتقِل إلى هنا لتفعيل الفوترة في Cloud Console.

ملاحظات:

يجب أن تكلّف إكمال هذا المختبر أقل من 3 دولارات أمريكية من موارد السحابة الإلكترونية.
يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب المزيد من الرسوم.
يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

تفعيل Cloud Shell

يمكنك بدلاً من ذلك الضغط على G ثم S. سيؤدي هذا التسلسل إلى تفعيل Cloud Shell إذا كنت تستخدم Google Cloud Console أو هذا الرابط.

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

لقطة شاشة لواجهة سطر الأوامر في Google Cloud Shell توضّح أنّه تم ربط البيئة

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

3- قبل البدء

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

لاستخدام AlloyDB وCompute Engine وخدمات الشبكات وVertex AI، عليك تفعيل واجهات برمجة التطبيقات الخاصة بها في مشروعك على Google Cloud.

داخل نافذة Cloud Shell، تأكَّد من إعداد رقم تعريف مشروعك:

gcloud config get-value project

من المفترض أن يعرض رقم تعريف مشروعك على Google.

اضبط متغيّر البيئة PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

فعِّل جميع الخدمات اللازمة:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com

الناتج المتوقّع

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. نشر AlloyDB

أنشئ مجموعة AlloyDB ومثيلًا أساسيًا. يمكنك إما نشرها باستخدام نص برمجي مُعدّ مسبقًا سينشر جميع الموارد اللازمة، أو يمكنك تنفيذ ذلك خطوة بخطوة بنفسك باتّباع المستندات.

نشر AlloyDB باستخدام نص برمجي آلي

يستخدم هذا الأسلوب نصًا برمجيًا مبرمَجًا لنشر مجموعة AlloyDB وتوفير المعلومات اللازمة لبدء العمل مع الموارد التي تم نشرها.

في نافذة Cloud Shell الطرفية، نفِّذ الأمر لاستنساخ نص النشر البرمجي من المستودع.

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

شغِّل نص النشر البرمجي.

./deploy_alloydb.sh

سيستغرق تنفيذ النص البرمجي بعض الوقت، أي حوالي 5 إلى 7 دقائق عادةً. بعد ذلك، يجب أن يقدّم معلومات عن مجموعة AlloyDB التي تم نشرها. يُرجى العلم أنّ كلمة المرور ستكون مختلفة، لذا سجِّلها في مكان ما لاستخدامها في المستقبل.

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------

ويمكنك أيضًا الاطّلاع على المجموعة الجديدة والمثيل الأساسي في وحدة التحكّم على الويب.

5- إعداد قاعدة البيانات

عليك تفعيل عملية دمج Vertex AI لاستخدام دوال الذكاء الاصطناعي وعوامل التشغيل، وتفعيل Data access API وإنشاء قاعدة بيانات لمجموعة البيانات النموذجية.

منح الأذونات اللازمة إلى AlloyDB

أضِف أذونات Vertex AI إلى وكيل خدمة AlloyDB.

افتح علامة تبويب أخرى في Cloud Shell باستخدام علامة "+" في أعلى الصفحة.

في علامة تبويب Cloud Shell الجديدة، نفِّذ ما يلي:

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"

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/discoveryengine.viewer"

الناتج المتوقّع في وحدة التحكّم:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ 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"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
... < redacted > 
etag: BwYIEbe_Z3U=
version: 1

تفعيل Data Access API

عليك تفعيل Data Access API على مجموعة AlloyDB لتتمكّن من استخدام أدوات MCP، مثل execute_sql.

في علامة تبويب الوحدة الطرفية نفسها، نفِّذ ما يلي.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

تعديل علامات المثيل

لاستخدام وظائف الذكاء الاصطناعي المتقدّمة في AlloyDB، علينا تفعيل بعض علامات قاعدة البيانات. بعد تفعيل Data Access API، قد يستغرق ظهور المثيل ليكون جاهزًا للتغييرات التالية بضع دقائق. يُرجى الاطّلاع على حالة الجهاز الظاهري في وحدة التحكّم للتأكّد من ظهور علامة الاختيار الخضراء.

في علامة تبويب الوحدة الطرفية نفسها، نفِّذ ما يلي.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

الربط بـ AlloyDB Studio

في الفصول التالية، يمكن تنفيذ جميع أوامر SQL التي تتطلّب الاتصال بقاعدة البيانات في AlloyDB Studio.

انتقِل إلى صفحة المجموعات في AlloyDB for Postgres.

افتح واجهة وحدة تحكّم الويب لمجموعة AlloyDB من خلال النقر على الآلة الافتراضية الأساسية.

بعد ذلك، انقر على AlloyDB Studio في يمين الصفحة:

اختَر قاعدة بيانات postgres ومستخدم postgres وأدخِل كلمة المرور التي تم تدوينها عند إنشاء المجموعة. بعد ذلك، انقر على الزر "المصادقة".

إذا لم تنجح كلمة المرور أو نسيت تدوينها، يمكنك تغييرها. راجِع المستندات لمعرفة كيفية إجراء ذلك.

سيؤدي ذلك إلى فتح واجهة AlloyDB Studio. لتنفيذ الأوامر في قاعدة البيانات، انقر على علامة التبويب "استعلام بدون عنوان" على يسار الصفحة.

يفتح واجهة يمكنك من خلالها تنفيذ أوامر SQL

إنشاء قاعدة بيانات

إنشاء قاعدة بيانات باستخدام التشغيل السريع

في "محرّر AlloyDB Studio"، نفِّذ الأمر التالي.

إنشاء قاعدة بيانات:

CREATE DATABASE quickstart_db

الناتج المتوقّع:

Statement executed successfully

الاتصال بقاعدة بيانات quickstart_db

تحقَّق مما إذا تم إنشاء قاعدة البيانات من خلال الاتصال بها. أعِد الاتصال بالاستوديو باستخدام الزرّ لتبديل المستخدم أو قاعدة البيانات.

اختَر قاعدة البيانات الجديدة quickstart_db من القائمة المنسدلة واستخدِم اسم المستخدم وكلمة المرور نفسها كما كان من قبل.

سيتم فتح اتصال جديد يمكنك من خلاله العمل مع عناصر من قاعدة بيانات quickstart_db. يمكنك هناك فحص المخطط والبيانات المستوردة.

6. عيّنات البيانات

الآن، عليك إنشاء عناصر في قاعدة البيانات وتحميل البيانات. ستستخدم مجموعة بيانات وهمية لشركة Cymbal Shipping. يتضمّن هذا الملف بيانات وهمية حول السلع والشاحنات والطلبات ورحلات الشاحنات بالإضافة إلى السائقين الوهميين.

إنشاء حزمة تخزين

ستستخدِم حزمة تطوير البرامج (SDK) من Google‏ (gcloud) لاستيراد البيانات من المستودع الذي تم استنساخه إلى قاعدة بيانات AlloyDB، وعليك إنشاء حزمة تخزين لهذا الغرض ومنح إذن الوصول إلى حساب خدمة AlloyDB. يمكنك أيضًا محاولة إجراء ذلك باستخدام وحدة تحكّم الويب كما هو موضّح في المستندات.

في وحدة Google Cloud Shell الطرفية، نفِّذ ما يلي:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

تحميل البيانات

الخطوة التالية هي تحميل البيانات. يقع ملف SQL dump في مجلد المستودع المستنسخ. يفترض الأمر التالي أنّك استخدمت الدليل الرئيسي كنقطة بداية عند استنساخ المستودع في الخطوة السابقة أثناء إنشاء مجموعة AlloyDB.

انسخ ملف SQL المضغوط إلى حزمة التخزين الجديدة:

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

بعد ذلك، حمِّل البيانات إلى قاعدة بيانات quickstart_db:

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

سيحمّل الأمر مجموعة البيانات النموذجية إلى قاعدة بيانات quickstart_db. يمكنك التحقّق من الجداول والسجلات باستخدام AlloyDB Studio.

7. العمل باستخدام "وكيل البيانات"

لنبدأ بعيّنة من وكيل الذكاء الاصطناعي تم إنشاؤها باستخدام Google ADK للغة Python، وسنوضّح كيفية ضبطها للعمل مع خادم Google Cloud MCP على AlloyDB.

التحقّق من رمز المصدر الخاص بـ "الوكيل"

في المستودع المستنسخ، راجِع رمز الوكيل باستخدام محرّر Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py

يمكنك الاطّلاع في الوكيل على قسم لخادم Google Cloud MCP الخاص بـ AlloyDB. نوفّر نقطة نهاية باسم MCP_SERVER_URL، ومصادقة، ورقم تعريف المشروع، ونضيفها إلى مجموعة أدوات MCP.

# Google Cloud MCP Server for AlloyDB

MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
    "Authorization": f"Bearer {creds.token}",
    "X-Goog-User-Project": project_id
}
    
connection_params = StreamableHTTPConnectionParams(
    url=MCP_SERVER_URL,
    headers=headers,
    timeout=300.0,
    sse_read_timeout=600.0
)

mcp_toolset = McpToolset(connection_params=connection_params)

وفي رمز الوكيل، يتم تضمين مجموعة أدوات MCP كمَعلمة tools للوكيل. تتوفّر أيضًا أسماء المجموعات والخوادم والمنطقة وقاعدة البيانات كمتغيّرات لطلب العامل.

MODEL_ID = "gemini-3.5-flash"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3.5-flash with the functions from the schema.
    """,
    tools=[mcp_toolset],
)

تتضمّن خدمة Google Cloud MCP لـ AlloyDB مجموعة محدّدة مسبقًا من الأدوات. إذا أردت إدراج جميع الأدوات المتاحة، يمكنك استخدام الأمر curl من نافذة Cloud Shell الطرفية باستخدام الأمر التالي. ويمكنك دائمًا الاطّلاع على أحدث مرجع لخادم Google Cloud MCP الخاص بـ AlloyDB في المستندات.

curl -s -X POST http://alloydb.googleapis.com/mcp \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.result.tools[].name'
{
  "id": "my_id_01",
  "jsonrpc": "2.0",
  "method": "tools/list"
}
EOF

بدء استخدام "الوكيل"

يمكنك الآن بدء تشغيل البرنامج في وضع التفاعل باستخدام واجهة الويب الخاصة بـ "حزمة تطوير التطبيقات من Google". توفّر واجهة الويب الخاصة بـ "مجموعة أدوات المطوّرين" طريقة ملائمة لاختبار سير عمل الوكلاء وتحديد المشاكل وحلّها.

لنبدأ بتثبيت جميع الحِزم المطلوبة لـ Python باستخدام أداة إدارة الحِزم uv.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync

بعد تثبيت جميع الحِزم، عليك إضافة ملف .env إلى دليل الوكيل لتوجيهه إلى استخدام Vertex AI في جميع عمليات التواصل مع نماذج الذكاء الاصطناعي.

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

بعد ذلك، يمكنك بدء تشغيل الوكيل

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

من المفترض أن يظهر لك ناتج مشابه لما يلي مع نقطة نهاية مثل http://127.0.0.1:8000 .

يمكنك النقر على عنوان URL هذا في Cloud Shell وسيتم فتح نافذة معاينة في علامة تبويب متصفّح منفصلة حيث يمكنك اختيار data_agent من القائمة المنسدلة على اليمين.

في واجهة الويب الخاصة بـ ADK، يمكنك نشر أسئلتك في أسفل يسار الصفحة والاطّلاع على مسار التنفيذ الكامل، بما في ذلك عمليات التتبُّع لكل خطوة على الجانب الأيسر.

8. اختبار AlloyDB MCP باستخدام Agent

يتيح لك "الوكيل" طرح الأسئلة في شكل حر باستخدام اللغة الطبيعية، وسيستخدم "الوكيل" خادم Google Cloud MCP لـ AlloyDB كأداة للإجابة عن الأسئلة. يتم نشر الأسئلة في أسفل يسار الصفحة، وستظهر الإجابة مع جميع طلبات الأدوات في أعلى الصفحة.

أنت تعمل على بيانات تشغيلية لشركة شحن تتضمّن معلومات حول طلبات الشحن والشاحنات والسائقين والرحلات التي أجراها السائقون. السؤال الأول هو عن عدد الرحلات التي تم تنفيذها في فبراير 2026.

في حقل الإدخال في أسفل يسار الشاشة، اكتب ما يلي واضغط على Enter.

Hello, can you tell me how many trips we've done in February this year?

سيعمل الوكيل على تنفيذ طلبات متعددة للأدوات لتحديد الجداول المناسبة في المخطط وبنية الجدول قبل تنفيذ عبارة SQL الصحيحة للحصول على البيانات المناسبة.

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

استنادًا إلى السجلات في قاعدة البيانات، تم إكمال 108 رحلات في فبراير 2026.

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

الآن، اجعل الطلب أكثر تعقيدًا من خلال طلب مقارنة النتائج بالشهر السابق.

How is it in comparison in numbers and mileage with the January?

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

In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage:

January 2026: 114 trips with a total mileage of 185,597 km.
February 2026: 108 trips with a total mileage of 177,893 km.
This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.

جرِّب طلبات بسيطة أخرى باستخدام واجهة الويب الخاصة بـ ADK واطّلِع على كيفية تنفيذ طلبات بحث مختلفة لتحقيق النتائج.

أوقِف الوكيل بالضغط على ctrl+c في نافذة Terminal. يمكنك إغلاق علامة تبويب المتصفّح التي تتضمّن واجهة الويب الخاصة بـ ADK.

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

9. تطبيق نموذجي

في المستودع الذي تم استنساخه نفسه، لدينا تطبيق نموذجي لشركة Cymbol Logistic. يستخدم التطبيق إطار عمل Python Mesop من Google .

يمكنك تحليل رمز التطبيق من خلال فتح ملف app.py في محرِّر Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py

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

def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
    local_runner = FrontendRunner()
    
    instruction = f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3.5-flash with the functions from the schema.
    """
    ...

بعد فحص الرمز، اضغط على الزر "وحدة طرفية" لبدء تطبيقنا واختباره. سيبدأ التطبيق على المنفذ 8080. إذا أردت تغيير المنفذ، عدِّل الأمر عن طريق تغيير قيمة المنفذ.

نفِّذ ما يلي في Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080

بعد ذلك، استخدِم معاينة الويب في Google Cloud Shell من خلال النقر على http://localhost:8080.

سيتم فتح علامة تبويب جديدة في المتصفّح تتضمّن واجهة التطبيق.

انقر على مربّع الاختيار "تفعيل ناتج تصحيح الأخطاء" (Enable Debug Output) في أعلى يسار الصفحة واكتب سؤالاً على النحو التالي.

What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.

بعد ذلك، اضغط على الزر Submit Request.

سيعمل البرنامج في الخلفية وينتج المخرجات ومعلومات تصحيح الأخطاء مع جميع طلبات البحث التي تنفّذها مجموعة أدوات MCP. راجِع طلبات البحث للاطّلاع على سير العمل.

يمكنك اختبار الوكلاء وإمكانات التطبيق من خلال تجربة أسئلة تحليلية مختلفة.

حتى الآن، كان بإمكانك إجراء بعض التحليلات الأساسية والاستكشاف باستخدام الوكيل مع MCP. في الفصل التالي، ستجرّب استخدام ميزات أكثر تقدّمًا في AlloyDB.

10. دوال AlloyDB AI

تتيح دوال AlloyDB AI إجراء فلترة وترتيب ذكيَّين للنصوص والبيانات المتعددة الوسائط (خاصةً الصور)، وتوفّر إمكانات Gemini لطلبات البحث. على وجه الخصوص، يمكن أن تظهر الدالتان AI.IF وAI.RANK في عبارات SQL إلى جانب عوامل تشغيل SQL التقليدية (الفلاتر وعمليات الربط والتجميع وما إلى ذلك).

قبل استخدام وظائف الذكاء الاصطناعي، نفحص عملية البحث وعمليات التجميع باستخدام الطرق "الكلاسيكية". جرِّب الطلب التالي.

Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.

يمكنه العثور على عمود "التقييم" في الجدول الذي يتضمّن ملاحظات العملاء واستخدامه لتحديد السائقين الحاصلين على أفضل تقييم. ثم استخدمت المعلومات للحصول على مزيد من المعلومات حول السائقين.

SELECT 
    d.first_name || ' ' || d.last_name as driver_name,
    SUM(sr.distance_km) as total_distance,
    d.experience_years,
    COUNT(cf.feedback_id) as positive_feedback_count

FROM drivers d

JOIN truck_trips tt ON d.driver_id = tt.driver_id

JOIN customer_feedback cf ON tt.trip_id = cf.trip_id

JOIN shipping_requests sr ON tt.request_id = sr.request_id

WHERE tt.arrival_time >= '2025-12-01' 
AND tt.arrival_time < '2026-05-01'
  
AND cf.rating >= 4

GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years

ORDER BY positive_feedback_count DESC, total_distance DESC

LIMIT 5;

ولكن من الناحية الفنية، قد يتضمّن التقييم جميع المَعلمات التي نريد تقييمها أو لا يتضمّنها. يمكننا استخدام "وظائف AlloyDB AI" لهذا الغرض.

عوامل تشغيل AI.RANK

تُسجّل الدالة ai.rank() مدى جودة إجابة المستند عن طلب بحث معيّن. ويمكن استخدامها لترتيب نتائج طلب البحث أو إعادة ترتيبها. يمكنك الاطّلاع على مزيد من المعلومات حول عوامل التشغيل في المستندات.

عدِّل الطلب واطلب صراحةً استخدام AI.RANK أثناء التحليل لتقييم السائقين استنادًا إلى أدائهم واحترافيتهم.

Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function?  Give me top drivers  names, distance, years of experience and rank for each driver.

قد يستغرق تنفيذ الأمر وقتًا أطول قليلاً لأنّ الوكيل يجب أن يحدّد كيفية استخدام دالة AI.RANK، والحصول على البيانات، وتطبيق AI.RANK لترتيب المعلومات وفقًا لذلك. في النهاية، يجب أن تحصل على قائمة ببرامج التشغيل مرتّبة حسب النموذج وقائمة بطلبات البحث التي تم تنفيذها.

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

WITH fastest_drivers AS (
    SELECT 
        d.driver_id,
        d.first_name || ' ' || d.last_name as driver_name,
        d.experience_years,
        SUM(sr.distance_km) as total_distance,
        AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
        COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
        ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
    
FROM drivers d
    
JOIN truck_trips tt ON d.driver_id = tt.driver_id
    
JOIN shipping_requests sr ON tt.request_id = sr.request_id
    LEFT 
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
    
WHERE tt.arrival_time >= '2026-04-04'
      
AND tt.arrival_time IS NOT NULL 
      
AND tt.departure_time IS NOT NULL
      
AND tt.arrival_time > tt.departure_time
    
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
    
ORDER BY avg_speed DESC
    
LIMIT 5
)
SELECT 
    f.driver_name,
    f.total_distance,
    f.experience_years,
    f.avg_speed,
    f.feedbacks,
    (SELECT r.score 
FROM ai.rank(
        'semantic-ranker-fast-004',
        'excellent customer service, professional, friendly, fast, 
and reliable delivery reviews',
        ARRAY[f.feedbacks],
        1
    ) r 
LIMIT 1) as feedback_score

FROM fastest_drivers f

ORDER BY feedback_score DESC;

يمكنك مواصلة اختبار التطبيق وفحص طلبات البحث لمعرفة كيف يتوصّل الوكيل إلى النتائج النهائية.

بهذا نكون قد أنهينا الدرس التطبيقي. آمل أن تكون قد تمكّنت من الاطّلاع على جميع الأمثلة وتعلّمت كيفية استخدام خدمة Google Cloud MCP مع AlloyDB. لجعل MCP مناسبًا للمؤسسات، من المنطقي دمج MCP مع ميزات NL2SQL في AlloyDB الموضّحة في مستندات AlloyDB. يمكنك تجربة هذه الميزة باستخدام الدرس التطبيقي حول إنشاء عبارات SQL لـ AlloyDB.

11. تنظيف البيئة

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

إتلاف مثيلات AlloyDB ومجموعة AlloyDB عند الانتهاء من الدرس التطبيقي

حذف مجموعة AlloyDB وجميع مثيلاتها

إذا سبق لك استخدام الإصدار التجريبي من AlloyDB لا تحذف المجموعة التجريبية إذا كنت تخطّط لاختبار مختبرات ومراجع أخرى باستخدام المجموعة التجريبية. لن تتمكّن من إنشاء مجموعة تجريبية أخرى في المشروع نفسه.

يتم إيقاف المجموعة باستخدام الخيار force الذي يؤدي أيضًا إلى حذف جميع المثيلات التابعة للمجموعة.

في Cloud Shell، حدِّد متغيرات المشروع والبيئة إذا تم قطع الاتصال وفقدت جميع الإعدادات السابقة:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

احذف المجموعة:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

الناتج المتوقّع في وحدة التحكّم:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

حذف نُسخ AlloyDB الاحتياطية

احذف جميع النُسخ الاحتياطية من AlloyDB للمجموعة:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

الناتج المتوقّع في وحدة التحكّم:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

12. تهانينا

تهانينا على إكمال درس البرمجة.

المواضيع التي تناولناها

كيفية إنشاء مجموعة AlloyDB واستيراد نموذج بيانات
كيفية تفعيل واجهة برمجة التطبيقات للوصول إلى بيانات AlloyDB
كيفية تفعيل ميزة "المعالجة المتوازية الضخمة" في Google Cloud لخدمة AlloyDB NL
كيفية إضافة Google Cloud MCP لـ AlloyDB إلى وكيل ADK
كيفية استخدام Google Cloud MCP مع AlloyDB في أحد التطبيقات
كيفية استخدام الوكلاء مع AlloyDB MCP للإحصاءات

استطلاع الرأي

إخراج:

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط

قراءة المحتوى وإكمال التمارين