‫QueryData لـ AlloyDB باستخدام "تحليل البيانات باستخدام Gemini"

1. مقدمة

يقدّم هذا الدرس التطبيقي حول الترميز دليلاً حول كيفية بدء استخدام QueryData في AlloyDB واستخدامه لإنشاء عبارات SQL دقيقة وقابلة للتوقّع من إدخال اللغة الطبيعية في التطبيقات المستندة إلى الوكلاء.

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

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

ما ستتعلمه

كيفية إنشاء مجموعة AlloyDB واستيراد بيانات نموذجية
كيفية تفعيل واجهة AlloyDB Data access API
كيفية تفعيل QueryData لخدمة AlloyDB
كيفية إنشاء نماذج
كيفية استخدام البحث المتعدّد الأوجه
كيفية استخدام QueryData مع "وكلاء الذكاء الاصطناعي"

المتطلبات

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

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

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

إنشاء مشروع على Google Cloud

في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء 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

من المفترض أن يظهر لك معرّف مشروعك في الناتج:

student@cloudshell:~ (test-project-001-402417)$ gcloud config get-value project
Your active configuration is: [cloudshell-23188]
test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$

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

PROJECT_ID=$(gcloud config get-value project)

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

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.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 \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.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-querydata"

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 --public-ip

سيستغرق تنفيذ النص البرمجي بعض الوقت، أي حوالي 5 إلى 7 دقائق، وسيتم نشر مجموعة AlloyDB ومثيل أساسي باستخدام عنوانَي IP عام وخاص. لا يتوفّر عنوان IP العام إلا للشبكات المصرّح بها أو باستخدام وكيل مصادقة AlloyDB. يمكنك الاطّلاع على مزيد من المعلومات حول عنوان IP العام في المستندات. يجب أن يقدّم النص البرمجي كناتج معلومات عن مجموعة 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"

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

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:
...
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",
 }'

تفعيل مصادقة إدارة الهوية وإمكانية الوصول

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

نبدأ بتفعيل إدارة الهوية وإمكانية الوصول على مستوى الجهاز الظاهري. في علامة تبويب الوحدة الطرفية نفسها، نفِّذ ما يلي:

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

أضِف نفسك كمستخدم AlloyDB:

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED

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

exit

الربط بـ AlloyDB Studio

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

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

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

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

اختَر قاعدة بيانات postgres ومصادقة IAM. بعد ذلك، انقر على الزر "المصادقة".

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

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

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

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

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

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

CREATE DATABASE quickstart_db

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

Statement executed successfully

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

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

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

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

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

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

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

ستستخدم حزمة تطوير البرامج (SDK) من Google (gcloud) لاستيراد البيانات من المستودع الذي تم استنساخه إلى قاعدة بيانات AlloyDB. عليك إنشاء حزمة Cloud Storage لذلك ومنح إذن الوصول إلى حساب خدمة 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-querydata"
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 والاتصال بمثيل AlloyDB باستخدام MCP Toolbox لقواعد البيانات.

تثبيت MCP Toolbox for Databases

‫MCP Toolbox for Databases هو مشروع مفتوح المصدر يوفّر إمكانية استخدام MCP لمحركات قواعد بيانات متعددة، بما في ذلك AlloyDB for PostgreSQL. يمكنك الاطّلاع على معلومات حول MCP Toolbox في المستندات.

عليك تنزيل أحدث إصدار من البرنامج المتوافق مع منصتك. للحصول على أحدث إصدار، يُرجى الاطّلاع على صفحة الإصدارات. يوضّح المثال التالي كيفية تنزيل الإصدار 31 من MCP Toolbox إلى Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
export VERSION=0.31.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

عليك إعداد ملف إعداد لمجموعة الأدوات. لدينا ملف tools.yaml.example عيّنة في الدليل الحالي وسنعدّ ملف tools.yaml عن طريق استبدال عنصرَين نائبَين برقم تعريف المشروع والمنطقة.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    tools.yaml.example > tools.yaml

بدء استخدام MCP Toolbox لقواعد البيانات

يمكنك الآن بدء استخدام مجموعة أدوات MCP باستخدام ملف الإعدادات الذي تم إعداده.

افتح علامة تبويب جديدة في Google Cloud Shell من خلال النقر على الزر "+" في أعلى واجهة Google Cloud Shell.

في علامة التبويب الجديدة، انتقِل إلى الدليل الذي يحتوي على ملف ثنائي لأدوات صندوق الأدوات وملف الإعداد tools.yaml، ثم ابدأ خادم MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config tools.yaml

من المفترض أن تظهر لك في الناتج الرسالة "الخادم جاهز للعرض"، كما هو موضّح أدناه.

2026-03-30T10:28:03.614374-04:00 INFO "Initialized 1 sources: cymbal-logistics-sql-source"
2026-03-30T10:28:03.614517-04:00 INFO "Initialized 0 authServices: "
2026-03-30T10:28:03.614531-04:00 INFO "Initialized 0 embeddingModels: "
2026-03-30T10:28:03.614657-04:00 INFO "Initialized 2 tools: execute_sql_tool, list_cymbal_logistics_schemas_tool"
2026-03-30T10:28:03.614711-04:00 INFO "Initialized 1 toolsets: default"
2026-03-30T10:28:03.614723-04:00 INFO "Initialized 0 prompts: "
2026-03-30T10:28:03.614779-04:00 INFO "Initialized 1 promptsets: default"
2026-03-30T10:28:03.616214-04:00 INFO "Server ready to serve!"

التحقّق من رمز المصدر الخاص ببرنامج Agent

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

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/agent.py

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

MCP_SERVER_URL = "http://127.0.0.1:5000"
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}")

mcp_toolset = ToolboxToolset(
    server_url=MCP_SERVER_URL,
)

وفي رمز الوكيل، يتم تضمين مجموعة أدوات 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}
    """,
    tools=[mcp_toolset],
)

بعد فحص الرمز البرمجي، ارجع إلى نافذة الوحدة الطرفية من خلال النقر على الزر "فتح الوحدة الطرفية" (Open terminal) في أعلى يسار نافذة المحرّر.

بدء الوكيل

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

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

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
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 من القائمة المنسدلة على اليمين.

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

8. اختبار NL2SQL بدون QueryData لـ AlloyDB

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

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

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

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

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

وفي النهاية، ستقدّم النتيجة الصحيحة بعد إنشاء طلب البحث المناسب وتنفيذه في قاعدة البيانات.

أكملنا 108 رحلات في فبراير 2026. تشير سجلّاتنا إلى أنّه لم يتم تحديد أي رحلات أو إكمالها في شباط (فبراير) 2025.

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

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

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

يمكنك أيضًا إيقاف "أدوات MCP" في علامة التبويب الثانية من خلال الضغط على اختصار المفاتيح نفسه ctrl+c وإغلاق علامة التبويب الثانية.

في الخطوة التالية، سننشئ سياق QueryData لتحسين استجابة NL2SQL وأدائها.

9- إنشاء QueryData ContextSet

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

إنشاء نماذج موجَّهة

‫QueryData ContextSet هو ملف JSON يتضمّن نماذج استعلامات وجوانب توفّر البيانات والتوجيهات اللازمة لنموذج الذكاء الاصطناعي من أجل استخدام استعلام SQL أو أجزاء من استعلام SQL الصحيحَين لتحقيق الأهداف المطلوبة استنادًا إلى أنماط الاستعلامات وبنية البيانات.

تبدأ من نموذج مستهدَف. أنشئ ملفًا باستخدام محرِّر Cloud Shell. في وحدة Cloud Shell الطرفية، نفِّذ ما يلي:

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

أدخِل نموذج طلب البحث باللغة الطبيعية الذي استخدمناه في الفصل السابق: "كم عدد الرحلات التي أجريناها في شباط (فبراير)؟".

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a given month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ]
}

بعد ذلك، نزِّل النموذج إلى جهاز الكمبيوتر من Cloud Shell باستخدام زر التنزيل.

تحميل مجموعات سياق QueryData

لاستخدام مجموعات سياق QueryData، علينا تحميلها إلى قاعدة البيانات.

افتح AlloyDB Studio. في اللوحة اليمنى في أسفل الشاشة، سترى QueryData Context وثلاث نقاط.

انقر على هذه النقاط الثلاث واختَر "إنشاء سياق". سيتم فتح مربّع حوار حيث يمكنك وضع

الاسم: cymbal_context_set
الوصف: Cymbal Logistic Query Data
تحميل ملف السياق: انقر على الزر "Browse" واختَر ملف JSON الذي يحتوي على QueryData ContextSet

عند النقر على زر الحفظ، قد يستغرق الأمر بعض الوقت لتهيئة مساحة تخزين السياق إذا كنت تجري هذه العملية للمرة الأولى.

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

10. Test QueryData Context Set

نموذج الاختبار

استخدِم الإجراء "Test context" لاختبار السياق في AlloyDB Studio. عند النقر على "اختبار السياق" (Test context)، سيتم فتح نافذة محرِّر AlloyDB Studio جديدة بعنوان "cymbal_context_set" ودعوة إنشاء طلبات البحث باستخدام لغة SQL بعنوان "Generate SQL using QueryData context: cymbal_context_set ". انقر على إنشاء طلبات البحث باستخدام لغة SQL واكتب

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

وعندما يتم إنشاء SQL، انقر على الزر "Insert".

سيظهر لك الاستعلام نفسه تمامًا الذي أرسلناه إلى نموذج السياق في وقت سابق.

-- How many trips we've done in February?
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'

حاوِل استبدال الشهر بـ "يناير" وتحقَّق من عبارة SQL التي تم إنشاؤها. سيتم استخدام الشهر كمَعلمة للنية المحدّدة المَعلمات وتعديل عبارة SQL تلقائيًا.

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

على سبيل المثال، إذا طلبنا عرض بيانات "الشهر الماضي"، نريد الحصول على التقرير الخاص بالشهر التقويمي الأخير من اليوم الأول إلى اليوم الأخير من ذلك الشهر، وليس عن آخر 30 يومًا.

يمكننا إضافة هذه التصنيفات كجزء من رمز SQL إلى إعدادات ContextSet مع النموذج الذي أضفناه سابقًا. افتح الملف querydata_cymbal_contextset.json.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

وأضِف الأوجه بعد النماذج الحالية. يجب أن يكون المحتوى الناتج في الملف على النحو التالي

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a certain month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)",
      "intent": "last month",
      "manifest": "Records for the previous calendar month",
      "parameterized": {
        "parameterized_intent": "previous calendar month",
        "parameterized_sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)"
      }
    }
  ]
}

احفظ الملف وحمِّله إلى جهاز الكمبيوتر.

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

الآن، حاوِل استخدام سياق الاختبار مرة أخرى وإنشاء عبارة SQL باستخدام الغرض "الشهر الماضي". على سبيل المثال، إذا أنشأت طلب بحث SQL للعبارة "show trucks trips for the last month""، سيتم استخدام الشرط الذي قدّمناه كعامل تصفية في ملف cymbal_context.json.

من المفترض أن تحصل على نتيجة مشابهة لما يلي:

-- show trucks trips for the last month
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)

الآن، كيف يمكنك استخدامها مع "الوكلاء المستندين إلى الذكاء الاصطناعي"؟ في الفصل التالي، سنوفّر سياق "بيانات الاستعلام" لوكلاء الذكاء الاصطناعي.

11. ‫QueryData باستخدام وكلاء الذكاء الاصطناعي

ستستخدم Data Agent نفسها، ولكن سيتم الآن ضبط MCP Toolbox لاستخدام QueryData ContextSet.

إعداد MCP Toolbox for Databases وبدء استخدامه

نحتاج إلى ملف إعداد جديد لـ MCP Toolbox سيستخدم Gemini Data Analytics API وAlloyDB كمصدر قاعدة البيانات.

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

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    querydata.yaml.example > querydata.yaml

بدِّل إلى المحرّر وابحث عن الملف querydata.yaml. سيبدو ملف الإعداد querydata.yaml على النحو التالي باستثناء رقم تعريف المشروع والمنطقة اللذين سيعكسان بيئتك. ومع ذلك، لا يزال عليك تعديل قيمة contextSetId واستبدال العنصر النائب "<add-context-set-id>" بالقيمة من وحدة التحكّم.

kind: sources
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: test-project-001-402417
---
kind: tools
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
location: "us-central1"
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
context:
  datasourceReferences:
    alloydb:
      databaseReference:
        projectId: "test-project-001-402417"
        region: "us-central1"
        clusterId: "alloydb-aip-01"
        instanceId: "alloydb-aip-01-pr"
        databaseId: "quickstart_db"
      agentContextReference:
        contextSetId: "<add-context-set-id>"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

للعثور على رقم تعريف مجموعة السياقات، انقر على زر التعديل لمجموعة السياقات كما هو موضّح في الصورة.

سيظهر معرّف مجموعة السياق في أعلى علامة التبويب الجديدة على اليسار.

يجب وضع هذا المسار الكامل بدلاً من العنصر النائب "<add-context-set-id>" في الملف querydata.yaml.

العودة إلى النافذة الطرفية

افتح علامة تبويب جديدة في Google Cloud Shell من خلال النقر على الزر "+" في أعلى واجهة Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config querydata.yaml

تشغيل وكيل ADK

في علامة التبويب الأولى في Cloud Shell، ابدأ تشغيل الوكيل.

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

وعند بدء تشغيله، انقر مرة أخرى على الرابط http://127.0.0.1:8000 .

ستظهر لك واجهة وكيل معاينة الويب المألوفة في "حزمة تطوير التطبيقات". انشر الاستعلام نفسه تمامًا كما فعلت في المرة السابقة.

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

ويمكنك الاطّلاع على سير عمل الوكيل. في حال ضبط كل شيء بشكل صحيح، من المفترض أن يظهر لك ما يلي.

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

يمكنك اختبار التصنيفات المحدّدة باستخدام طلب مثل

how trucks trips for the last month

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

بهذا نكون قد أنهينا الدرس التطبيقي. آمل أن تكون قد تمكّنت من الاطّلاع على جميع الأمثلة وتعلّمت كيفية استخدام QueryData في AlloyDB. تساعد التكنولوجيا المقدَّمة في جعل عبء العمل المستند إلى الوكلاء وإنشاء SQL قابلاً للتوقّع وموثوقًا به.

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

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

13. تهانينا

تهانينا على إكمال هذا الدرس العملي.

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

كيفية إنشاء مجموعة AlloyDB واستيراد نموذج بيانات
كيفية تفعيل واجهة برمجة التطبيقات AlloyDB Data access API
كيفية تفعيل QueryData لخدمة AlloyDB
كيفية إنشاء نماذج
كيفية استخدام البحث المتعدّد الأوجه
كيفية استخدام QueryData مع "وكلاء الذكاء الاصطناعي"

14. الاستطلاع

إخراج:

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

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

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

‫QueryData لـ AlloyDB باستخدام "تحليل البيانات باستخدام Gemini"

1. مقدمة

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

ما ستتعلمه

المتطلبات

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

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

إنشاء مشروع على Google Cloud

بدء Cloud Shell

3- قبل البدء

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

4. تفعيل AlloyDB

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

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

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

تفعيل Data Access API

تفعيل مصادقة إدارة الهوية وإمكانية الوصول

الربط بـ AlloyDB Studio

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

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

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

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

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

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

تثبيت MCP Toolbox for Databases

بدء استخدام MCP Toolbox لقواعد البيانات

التحقّق من رمز المصدر الخاص ببرنامج Agent

بدء الوكيل

8. اختبار NL2SQL بدون QueryData لـ AlloyDB

9- إنشاء QueryData ContextSet

إنشاء نماذج موجَّهة

تحميل مجموعات سياق QueryData

10. Test QueryData Context Set

نموذج الاختبار

إنشاء أوجه QueryData

11. ‫QueryData باستخدام وكلاء الذكاء الاصطناعي

إعداد MCP Toolbox for Databases وبدء استخدامه

تشغيل وكيل ADK

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

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

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

13. تهانينا

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

14. الاستطلاع

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