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

‫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 في أحد التطبيقات
كيفية استخدام الوكلاء مع AlloyDBMCP لإجراء التحليلات

المتطلبات

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

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

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

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

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

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

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

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

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. لا تستخدم Google APIs اسم المشروع، ويمكن تغييره في أي وقت.
رقم تعريف المشروع فريد في جميع مشاريع 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

تفعيل MCP

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

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

PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
    --project=$PROJECT_ID

أغلِق علامة التبويب من خلال تنفيذ الأمر "exit" في علامة التبويب:

exit

الاتصال بـ AlloyDB Studio

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

انتقِل إلى صفحة المجموعات في 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 في مجلد المستودع المستنسخ. يفترض الأمر التالي أنّك استخدمت الدليل الرئيسي كنقطة بداية عند استنساخ المستودع في الخطوة السابقة أثناء إنشاء مجموعة 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

يمكنك الاطّلاع في الوكيل على قسم لخادم MCP في Google Cloud من أجل 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-flash-preview"
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-flash-preview 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". توفّر واجهة الويب الخاصة بـ ADK طريقة ملائمة لاختبار سير عمل الوكلاء وتحديد المشاكل وحلّها.

لنبدأ بتثبيت جميع الحِزم المطلوبة لـ 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-flash-preview 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 من AlloyDB AI في عبارات 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;

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

بهذا نكون قد أنهينا الدرس التطبيقي. آمل أن تكون قد تمكّنت من الاطّلاع على جميع الأمثلة والتعرّف على كيفية استخدام خدمة MCP من Google Cloud مع 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 Data access API
كيفية تفعيل ميزة "المعالجة المتوازية الضخمة" في Google Cloud لخدمة AlloyDB NL
كيفية إضافة Google Cloud MCP لـ AlloyDB إلى وكيل ADK
كيفية استخدام Google Cloud MCP مع AlloyDB في أحد التطبيقات
كيفية استخدام الوكلاء مع AlloyDBMCP لإجراء التحليلات

13. الاستطلاع

إخراج:

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

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

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