البرمجة الحدسية باستخدام AlloyDB: من البداية إلى الإنتاج مع Antigravity

1. مقدمة

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

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

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستنشئ دليل الذكاء الاصطناعي لفن الطهي وتنشره، وهو تطبيق حديث يستند إلى إطار Next.js ومدعوم من AlloyDB. سيتوافق التطبيق مع ما يلي:

  • استيعاب البيانات الديناميكي من الكتالوج: استيراد بيانات المطاعم وتنظيمها تلقائيًا من ملفات CSV الأولية
  • البحث المستند إلى الكلمات الرئيسية: طلب البحث من قاعدة البيانات بشكل ديناميكي باستخدام البحث عن النص الكامل
  • البحث الدلالي المستند إلى الذكاء الاصطناعي: العثور على مطاعم من خلال وصف "الأجواء" (مثلاً، "مكان مريح لتناول العشاء" أو "وجبة سريعة في وقت متأخر من الليل") باستخدام عمليات التضمين في "منصة الوكيل"

bc2d98c88c72648e.png

أهداف الدورة التعليمية

  • توفير مثيل Google Cloud AlloyDB مع إعدادات عنوان IP العلني وشبكة السحابة الافتراضية الخاصة (VPC)
  • ربط Antigravity IDE مباشرةً بـ AlloyDB باستخدام أداة Model Context Protocol ‏ (MCP) Toolbox
  • ربط واجهة Next.js أمامية بقاعدة بيانات مباشرة باستخدام متغيرات البيئة واتصالات طبقة المقابس الآمنة الآمنة
  • تفعيل عملية دمج "منصة الوكيل" داخل قاعدة البيانات لإنشاء تضمينات المتّجهات باستخدام نموذج text-embedding-004
  • إجراء بحث عن التشابه بين المتجهات باستخدام عامل تشغيل مسافة جيب التمام (<=>).
  • تحسين أداء قاعدة البيانات على مستوى الإنتاج باستخدام فهرسة HNSW وتقسيم الجداول، ما يتيح لك العمل كمسؤول قاعدة بيانات افتراضي

المتطلبات

لإكمال هذا الدرس التطبيقي، ستحتاج إلى:

  • يجب تثبيت Antigravity على جهازك.
  • يجب أن يكون Google Cloud CLI (gcloud) وGit مثبّتَين ومصدَّقًا عليهما على جهازك المحلي.
  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • متصفّح ويب (يُنصح باستخدام Chrome)

تم تصميم هذا الدرس التطبيقي حول الترميز للمطوّرين من جميع المستويات، بما في ذلك المبتدئين.

2. قبل البدء

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

إنشاء مشروع

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

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

تأكَّد من تثبيت الأدوات التالية على جهازك:

  • ‫Antigravity 2.0: ثبِّت تطبيق Antigravity
  • Git: نزِّل Git وثبِّته.
  • Google Cloud CLI: نزِّل وثبِّت gcloud

إعداد Antigravity 2.0

في المرة الأولى التي تشغّل فيها Antigravity 2.0، سيُطلب منك إدخال رقم تعريف مشروعك على Google Cloud من الخطوة السابقة.

أدخِل رقم تعريف مشروعك لإعداد مساحة العمل:

12bf4154b982f21e.png

إعداد Antigravity IDE وفتحه

سنثبّت Antigravity IDE ونفتحه على جهازنا المحلي لنتمكّن من تنفيذ أوامر الواجهة الطرفية.

  1. في واجهة Antigravity 2.0، ابحث عن خيار تثبيت Antigravity IDE وانقر عليه (في أعلى يسار الصفحة).

89eb42b2f840b96d.png

  1. بعد ظهور طلب التنزيل والتثبيت، اتّبِع معالج التثبيت باستخدام الإعدادات التلقائية.
  2. عند اكتمال التثبيت، شغِّل Antigravity IDE.

استنساخ المستودع والمصادقة باستخدام Google Cloud

ستنفّذ جميع تعليمات سطر الأوامر مباشرةً داخل بيئة التطوير المتكاملة.

  1. افتح Antigravity IDE على جهازك المحلي
  2. افتحوا نافذة أوامر Antigravity الطرفية وأنشئوا نسخة طبق الأصل من مستودع المشروع:
git clone https://github.com/mtoscano84/vibe-coding-postgres-mcp.git
  1. افتح مجلد المشروع:
  2. انتقِل إلى "ملف" > "فتح مجلد" (أو "فتح...").
  3. انتقِل إلى المجلد الذي تم استنساخه حديثًا vibe-coding-postgres-mcp واختَره.
  4. بعد فتح مجلد المشروع، شغِّل نافذة طرفية مدمجة جديدة في Antigravity IDE. اضبط متغيّر البيئة PROJECT_ID واضبط "واجهة سطر الأوامر gcloud" لاستخدامه (استبدِل [YOUR_PROJECT_ID] برقم تعريف مشروعك الفعلي على Google Cloud Platform):
export PROJECT_ID=[YOUR_PROJECT_ID]
gcloud config set project $PROJECT_ID
  1. سجِّل الدخول إلى Google Cloud CLI:
gcloud auth login
  1. تسجيل الدخول إلى بيانات الاعتماد التلقائية للتطبيق (ADC): (يؤدي ذلك إلى إنشاء ملف بيانات الاعتماد المحلّي الذي تتطلّبه موصّلات قاعدة بيانات الذكاء الاصطناعي وMCP لاحقًا في التمرين العملي)
gcloud auth application-default login
  1. أكِّد صحة حسابك النشط باتّباع الخطوات التالية:
gcloud auth list

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

نفِّذ الأمر التالي في وحدة Antigravity الطرفية لتفعيل خدمات Google Cloud اللازمة:

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

3- إنشاء مثيل AlloyDB

في هذا القسم، ستنفّذ نصًا برمجيًا آليًا في وحدة طرفية Antigravity لتوفير مجموعة AlloyDB ومثيلها في Google Cloud.

في نافذة Antigravity IDE النشطة والمدمجة (التي تقع حاليًا داخل دليل مشروع vibe-coding-postgres-mcp)، شغِّل نص AlloyDB البرمجي الخاص بتوفير الموارد:

source database/deploy_alloydb.sh --region us-central1 --public-ip

ملاحظة: تستغرق عملية توفير المتطلبات اللازمة 10 إلى 15 دقيقة تقريبًا.

سيعمل نص البرمجة الخاص بتوفير الموارد على ما يلي:

  • أنشِئ شبكة VPC باسم "تلقائية" (إذا لم تكن متوفّرة في مشروعك).
  • إعداد Private Services Access لخدمة AlloyDB
  • نشِر مجموعة AlloyDB ومثيلًا أساسيًا مع تفعيل كلّ من عنوان IP الخاص وعنوان IP العام.
  • امنح موظف دعم خدمة AlloyDB أذونات "منصة الوكيل" اللازمة.

يجب أن يكون الناتج مشابهًا لما يلي:

----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (STANDARD)
Instance: alloydb-aip-01-pr
Region:   us-central1
Private IP: XX.XX.XX.XX
Public IP:  XX.XX.XX.XX
Initial Password: XXXXXXXXXX (if new cluster)
----------------------------------------

يُرجى الحرص على نسخ هذه التفاصيل وحفظها:

  • عنوان IP الخاص في AlloyDB: يستخدمه تطبيق Cloud Run للاتصال بشكل آمن داخل شبكة VPC.
  • عنوان IP العام لـ AlloyDB: يستخدمه بيئة التطوير المتكاملة (IDE) المحلية Antigravity للاتصال مباشرةً.
  • كلمة مرور قاعدة البيانات: هي كلمة المرور التي يتم إنشاؤها تلقائيًا لمستخدم postgres.

4. نشر الواجهة الأمامية

في هذا القسم، ستنشر واجهة Next.js الأمامية الأساسية (الحالة 0) إلى Google Cloud Run باستخدام نافذة Antigravity IDE الطرفية المدمجة. يستخدم هذا الإصدار الأوّلي بيانات تجريبية ولا يرتبط بقاعدة البيانات بعد.

أولاً، شغِّل الأوامر التالية مباشرةً في وحدة Antigravity الطرفية لمنح أدوار "إدارة الهوية وإمكانية الوصول" اللازمة لحساب الخدمة التلقائي في Compute Engine:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")
# Grant Storage Object Viewer (to read source code)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/storage.objectViewer"
# Grant Log Writer (to write build logs)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/logging.logWriter"
# Grant Artifact Registry Writer (to push container images)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/artifactregistry.writer"

من جذر دليل vibe-coding-postgres-mcp في وحدة Antigravity الطرفية، نفِّذ الأمر التالي لتجميع تطبيق Next.js ونشره في شبكة السحابة الخاصة الافتراضية (VPC):

gcloud run deploy berlin-gastronomy-guide \
  --source frontend/ \
  --network=default \
  --subnet=default \
  --allow-unauthenticated \
  --region=us-central1

بعد اكتمال عملية النشر، سيتم عرض عنوان URL الخاص بالخدمة.

Building using Dockerfile and deploying container to Cloud Run service [berlin-gastronomy-guide] in project [vibe-coding-postgres-mcp] region [us-central1]
Building and deploying...
  Validating configuration...done
  Uploading sources...done
  Building Container... Logs are available at [ https://console.cloud.google.com/cloud-build/builds;region=us-central1/46a6e834-d5e9-4dfd-885e-d39e2790f72d?project=734791203988 ]....done
  Setting IAM Policy...done
  Creating Revision...done
  Routing traffic...done
Done.
Service [berlin-gastronomy-guide] revision [berlin-gastronomy-guide-00002-n6k] has been deployed and is serving 100 percent of traffic.
Service URL: https://berlin-gastronomy-guide-[YOUR_PROJECT_NUMBER].us-central1.run.app

انسخ عنوان URL وافتحه في المتصفّح.

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

16d3649d19796847.png

5- ربط Antigravity بخدمة Google Cloud

للسماح لوكيل الذكاء الاصطناعي في بيئة التطوير المتكاملة (Antigravity) التي تعمل محليًا بالتفاعل مع قاعدة البيانات، سنستخدم خادم MCP الرسمي من Google Cloud AlloyDB.

بما أنّنا فعّلنا عنوان IP العام على مثيل AlloyDB أثناء عملية التوفير، يمكن لبيئة التطوير المتكاملة المحلية الاتصال به مباشرةً عبر الإنترنت. يتم تأمين الاتصال باستخدام طبقة المقابس الآمنة ومصادقة كلمة المرور، ويستخدم خادم MCP بيانات اعتماد Google Cloud المحلية للسماح بالاتصال.

ضبط خادم MCP في Antigravity

  1. في Antigravity IDE، انقر على قائمة النقاط الثلاث (...) في أعلى يسار نافذة المحادثة.
  2. اختَر "خوادم MCP"، ثمّ انقر على "خوادم MCP المُدارة" (أو "عرض الإعدادات الأولية" / "تعديل ملف الإعدادات").
  3. أضِف كتلة JSON التالية داخل عنصر mcpServers. تأكَّد من استبدال [YOUR_PROJECT_ID] و[YOUR_ALLOYDB_PASSWORD] برقم تعريف مشروعك وكلمة مرور قاعدة البيانات التي حفظتها من خطوة توفير AlloyDB:
"alloydb-postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@toolbox-sdk/server@latest",
    "--prebuilt",
    "alloydb-postgres",
    "--stdio"
  ],
  "env": {
    "ALLOYDB_POSTGRES_PROJECT": "[YOUR_PROJECT_ID]",
    "ALLOYDB_POSTGRES_REGION": "us-central1",
    "ALLOYDB_POSTGRES_CLUSTER": "alloydb-aip-01",
    "ALLOYDB_POSTGRES_INSTANCE": "alloydb-aip-01-pr",
    "ALLOYDB_POSTGRES_DATABASE": "postgres",
    "ALLOYDB_POSTGRES_USER": "postgres",
    "ALLOYDB_POSTGRES_PASSWORD": "[YOUR_ALLOYDB_PASSWORD]"
  }
}
  1. حفظ ملف الإعداد
  2. ستبدأ بيئة التطوير المتكاملة (IDE) خادم MCP تلقائيًا. من المفترض أن تظهر لك نقطة خضراء بجانب alloydb-postgres في لوحة MCP، ما يشير إلى أنّه تم الربط بنجاح.

فتح المستودع في Antigravity 2.0

في بقية هذا الدرس التطبيقي، سنكتب تطبيقنا وننشئه باستخدام Antigravity 2.0.

  1. ارجع إلى Antigravity 2.0 وافتح مجلد المشروع الذي استنسخته للتو.
  2. انقر على "محادثة جديدة" > "مشروع جديد" > "إضافة مجلد".
  3. انتقِل إلى المجلد الذي تم استنساخه حديثًا باسم vibe-coding-postgres-mcp واختَره.
  4. ستظهر لك الآن "واجهة الوكيل" داخل Antigravity 2.0 تشير مباشرةً إلى مساحة العمل المستنسخة، وهي جاهزة لكتابة الرموز البرمجية.

e806fdbce47d43f0.png

6. البرمجة الحدسية: نقل البيانات إلى قاعدة البيانات

بعد ربط Antigravity بمثيل AlloyDB من خلال خادم MCP، يمكنك البدء في تجربة الترميز الصوتي.

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

المهمة

ستستخدم ميزة "الدردشة مع الوكيل الذكي" في Antigravity. سيقرأ الوكيل الملف بشكل مستقل، ويحلّل أنواع البيانات، ويتصل بقاعدة البيانات، وينشئ الجدول، ويدرج السجلات.

بعد ذلك، انسخ الطلب التالي والصقه في المحادثة واضغط على Enter:

Read the headers of database/seed_data_berlin.csv. Connect to the database via the MCP tool, create a table named restaurants with the correct data types, and load all the records from the CSV file into it.

يراقب الوكيل أثناء تنفيذه للمهمة:

  • سيقرأ أولاً عناوين ملف CSV وبعض الصفوف النموذجية لتحديد المخطط المناسب.
  • سيتم استدعاء أداة AlloyDB MCP لإنشاء جدول المطاعم.
  • سيتم إدراج 100 سجل مطعم من ملف CSV في قاعدة البيانات على شكل دفعات.

التحقّق

بعد أن يخبرك الوكيل بأنّه انتهى، يمكنك التأكّد من أنّه تم تحميل البيانات:

في "محادثة مع الوكيل"، اطرح السؤال التالي على الوكيل:

Show me the first 5 records from the restaurants table.

سيبحث الوكيل في قاعدة البيانات ويعرض أول 5 مطاعم (مثل Pub Lia's Kitchen وCafe Clärchens)، ما يؤكّد أنّ عملية عرض البيانات في قاعدة البيانات تمت بنجاح.

7. البرمجة الحدسية: ربط الواجهة الأمامية بقاعدة البيانات

في هذا القسم، ستربط واجهة Next.js الأمامية بقاعدة بيانات AlloyDB النشطة. ستطلب من الوكيل استبدال البيانات التجريبية بطلب بحث مباشر في قاعدة البيانات وتنفيذ البحث عن الكلمات الرئيسية.

المهمة

ستطلب من الوكيل كتابة رمز الاتصال وتعديل الصفحة الرئيسية. بما أنّنا أضفنا قاعدة طبقة المقابس الآمنة (SSL) الخاصة بقاعدة البيانات في ‎.agents/AGENTS.md، سيضبط الوكيل تلقائيًا مجموعة الاتصالات لاستخدام طبقة المقابس الآمنة (SSL) للاتصالات السحابية بدون الحاجة إلى تحديدها في طلبك.

في محادثة Antigravity Agent، انسَخ الطلب التالي وألصِقه ثم اضغط على Enter (استبدِل [YOUR_PASSWORD] بكلمة مرور قاعدة البيانات الفعلية):

Connect our Next.js frontend to the restaurants table in the database using the pg library. Use a connection pool configured with environment variables: DB_HOST, DB_USER (postgres), DB_PASS (password is '[YOUR_PASSWORD]'), and DB_NAME (postgres). Replace the mock data in page.tsx with a live query, and implement keyword search on the name, category, and description

يراقب الوكيل أثناء تنفيذه للمهمة:

  • سيتم تثبيت حزمة pg وأنواع TypeScript الخاصة بها (@types/pg).
  • سيتم إنشاء ملف ربط بقاعدة البيانات (أو إجراء خادم Next.js) وإعداد مجموعة الربط.
  • سيقرأ قواعد AGENTS.md ويضيف تلقائيًا إعدادات SSL للمضيفين غير المحليين.
  • ستعيد كتابة ملف page.tsx لطلب البحث من قاعدة البيانات وفلترة النتائج استنادًا إلى طلب البحث.

التحقّق

لاختبار التغييرات، يجب إعادة نشر الواجهة الأمامية إلى Cloud Run. بما أنّنا نستخدم مسار "السحابة الإلكترونية فقط"، هذه هي طريقة إرسال الرمز الجديد.

افتح النافذة الطرفية المدمجة في Antigravity IDE (تأكَّد من أنّك في دليل الجذر).

شغِّل أمر النشر، مع تمرير عنوان IP الخاص وكلمة المرور في AlloyDB كمتغيرات بيئية (استبدِل العناصر النائبة بالقيم الفعلية):

gcloud run deploy berlin-gastronomy-guide \
  --source frontend/ \
  --network=default \
  --subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
  --allow-unauthenticated \
  --region=us-central1

بعد اكتمال عملية النشر، افتح عنوان URL للخدمة في المتصفّح.

جرِّب البحث عن "برغرميستر" أو "كباب". من المفترض أن تظهر لك المطاعم الحقيقية التي تم تحميلها من قاعدة البيانات.

لاحظ أنّ بطاقات المطاعم تعرض الآن صور GCS الفعلية (بما أنّ سجلّات قاعدة البيانات تحتوي على عناوين URL العلنية لخدمة GCS التي حمّلناها سابقًا).

8. البرمجة الوصفية: تفعيل البحث الدلالي

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

المهمة

ستطلب من الوكيل تفعيل البحث الدلالي في جدول المطاعم. سيستفيد الوكيل من المهارة المخصّصة add-vector-search-alloydb في المستودع للتعامل تلقائيًا مع إضافات قاعدة البيانات وتسجيل نموذج "منصة الوكيل" وإنشاء عمليات التضمين وتعديل طلبات البحث.

في محادثة Antigravity Agent، انسَخ الطلب التالي وألصِقه ثم اضغط على Enter:

Upgrade our database to support Semantic Vector Search on the restaurants table based on the description column. Then, update our frontend search query to use vector similarity search.

يراقب الوكيل أثناء تنفيذه للمهمة:

  • سيتصل هذا البرنامج بـ AlloyDB ويتيح استخدام الإضافتين vector (pgvector) وgoogle_ml_integration.
  • سيتم تسجيل نموذج التضمين في Agent Platform (text-embedding-004) داخل قاعدة البيانات.
  • سيؤدي ذلك إلى إضافة عمود تضمين جديد إلى جدول المطاعم.
  • سيتم تنفيذ طلب بحث داخل قاعدة البيانات لإنشاء تضمينات لجميع أوصاف المطاعم البالغ عددها 100.
  • سيعدّل هذا الإجراء رمز الواجهة الأمامية لإنشاء تضمين لطلب بحث المستخدم وإجراء بحث عن التشابه بين المتجهات باستخدام عامل تشغيل مسافة جيب التمام (<=>).

التحقّق

أعِد نشر الرمز المعدَّل على Cloud Run.

في نافذة المحطة الطرفية المدمجة Antigravity IDE، شغِّل أمر النشر (استبدِل العناصر النائبة بالقيم الفعلية):

gcloud run deploy berlin-gastronomy-guide \
  --source frontend/ \
  --network=default \
  --subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
  --allow-unauthenticated \
  --region=us-central1

بعد اكتمال عملية النشر، افتح عنوان URL للخدمة في المتصفّح.

اختبِر البحث الدلالي من خلال إدخال وصف بلغة طبيعية، مثل:

  • "a romantic dinner spot"
  • "وجبة سريعة بعد الذهاب إلى نادٍ ليلي"

لاحظ أنّها تعرض مطاعم ذات صلة كبيرة (مثل Cafe Clärchens أو Burgermeister) حتى إذا لم تتضمّن أسماؤها أو أوصافها الكلمتَين "رومانسي" أو "سهرات" بالضبط.

9. الفايب كودنغ: تحسين قاعدة البيانات

مع توسّع تطبيقك، يجب تحسين قاعدة البيانات للتعامل مع كميات كبيرة من البيانات (أكثر من 100 ألف صف) وعدد كبير من الزيارات المتزامنة من البحث. في هذه الخطوة الأخيرة، ستتعامل مع وكيلك كمسؤول قاعدة بيانات افتراضي (DBA) لتحليل مخطط قاعدة البيانات وتحسينه.

المهمة

ستطلب من الوكيل أن يتصرف كمهندس رئيسي لتصميم قواعد البيانات، وأن يحلّل المخطط الحالي ويقترح تحسينات. بعد مراجعة الاقتراحات والموافقة عليها، سيستخدم الوكيل مهارته المخصّصة optimize-database-alloydb لتطبيقها تلقائيًا.

Act as a Principal Database Architect. Our semantic search is working, but we need to optimize the database for production scale. Analyze our current schema. What are the top 2 database-schema optimizations you recommend we implement right now? Explain them to me and wait for my approval before modifying the database.

سيحلّل الوكيل قاعدة البيانات ويقدّم اقتراحَين:

  • فهرس HNSW: فهرس "أقرب جار تقريبي" (ANN) في عمود التضمين لإجراء طلبات البحث عن التشابه المتجهي بسرعة فائقة.
  • تقسيم الجدول: تقسيم جدول المطاعم (مثل تقسيم القائمة حسب الحي) لتحسين أداء طلب البحث وإمكانية الإدارة

راجِع التفسيرات. عندما تكون مستعدًا، أرسِل ردًا إلى الموظف في المحادثة:

Approved, please apply these optimizations.

يراقب الوكيل أثناء تنفيذه للمهمة:

  • سيؤدي ذلك إلى إنشاء فهرس HNSW في عمود التضمين.
  • سيتم تقسيم جدول المطاعم حسب الحي، ما يؤدي إلى إنشاء جداول أقسام فرعية لكل حي ونقل البيانات الحالية.

التحقّق

اطلب من الوكيل التأكّد من تطبيق التحسينات بنجاح. في محادثة مع موظّف الدعم، اطرح السؤال التالي:

Show me the list of partitions for the restaurants table and the indexes on it.

سيستعلم الوكيل عن فهرس قاعدة البيانات ويعرض بنية الأقسام الجديدة (مثل restaurants_mitte وrestaurants_kreuzberg) وفهرس HNSW، ما يؤكّد أنّ قاعدة البيانات أصبحت الآن محسّنة بالكامل للإنتاج.

10. التحدّي: إضافة مراجعات وتقييمات

حان دورك الآن لاختبار مهاراتك في Vibe Coding. في هذا التحدي، ستوسّع "دليل فن الطهي في برلين" ليشمل مراجعات العملاء والتقييمات بالنجوم.

المهمة

بدلاً من اتّباع طلب منسوخ ولصقه، اكتب طلبك الخاص في Antigravity Agent Chat لتنفيذ الميزات التالية:

  1. مخطّط قاعدة البيانات: أنشئ جدول reviews جديدًا مرتبطًا بجدول restaurants. يجب أن يخزّن تقييمًا (عددًا صحيحًا من 1 إلى 5) وتعليقًا نصيًا قصيرًا.
  2. إنشاء البيانات: أنشئ 3 أو 4 مراجعات واقعية من العملاء لكلّ من المطاعم الـ 100 في قاعدة البيانات.
  3. الدمج في الواجهة الأمامية: عدِّل الواجهة الأمامية في Next.js لاحتساب وعرض متوسط تقييم النجوم (مثلاً، ⭐⭐⭐⭐☆) على كل بطاقة مطعم.
  4. الفلترة: أضِف فلترًا منسدلاً في أعلى الصفحة لفلترة المطاعم حسب تقييمها (مثلاً، "عرض الكل" أو "4 نجوم أو أكثر" أو "3 نجوم أو أكثر").

التحقّق

بعد أن يكمل الوكيل المهمة، أعِد نشر تطبيقك على Cloud Run (استبدِل العناصر النائبة بقيمك الفعلية) من وحدة طرفية مدمجة في Antigravity IDE:

gcloud run deploy berlin-gastronomy-guide \
  --source frontend/ \
  --network=default \
  --subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
  --allow-unauthenticated \
  --region=us-central1

بعد اكتمال عملية النشر، أعِد تحميل المتصفّح وتأكَّد من ظهور تقييمك بالنجوم على البطاقات

1433b3c589f08f2a.png.

11. النتائج

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

التكامل مع قاعدة البيانات المستندة إلى الذكاء الاصطناعي الوكيل (بروتوكول سياق النموذج)

في السابق، كانت كتابة رمز قاعدة البيانات عملية يدوية تتطلّب التبديل بين بيئة التطوير المتكاملة والمستندات وعملاء قاعدة البيانات.

في هذا التمرين المعملي، استخدمت أداة Model Context Protocol (MCP) Toolbox لسدّ هذه الفجوة. من خلال إتاحة فحص مخطط قاعدة البيانات وتنفيذ SQL كأدوات مباشرةً لبرنامج الذكاء الاصطناعي، تمكّن البرنامج من:

  • فحص بيانات CSV الأولية وتصميم مخطط قاعدة البيانات
  • إنشاء وتنفيذ DDL لإنشاء جداول
  • ربط مجموعة الاتصالات في تطبيق Next.js

يوضّح ذلك كيف يتيح MCP تجربة تطوير قواعد البيانات بشكل حواري وعالي السرعة مع إبقاء المطوّر تحت السيطرة الكاملة داخل بيئة التطوير المتكاملة.

الذكاء الاصطناعي داخل قاعدة البيانات (منصّة الوكيل والبحث الدلالي)

يستفيد تطبيقك من عملية الدمج الأصلية لـ AlloyDB مع "منصّة الوكلاء" من Google Cloud لإنشاء تضمينات متجهة مباشرةً داخل قاعدة البيانات باستخدام SQL:

  • إنشاء التضمينات على الإنترنت: بدلاً من استخراج البيانات إلى خدمة Python خارجية، يستدعي AlloyDB نموذج text-embedding-004 داخل قاعدة البيانات من خلال دوال SQL.
  • البحث الدلالي المتّجه: باستخدام إضافة pgvector وعامل تشغيل مسافة جيب التمام (<=>)، يمكن للوكيل مطابقة "الجو العام" للغة الطبيعية التي يستخدمها المستخدم (مثل "عشاء رومانسي") مع أقرب تمثيل متّجه في قائمة المطاعم، ما يؤدي إلى عرض نتائج ذات صلة دلاليًا في أجزاء من الثانية.

تحسين قاعدة البيانات على مستوى الإنتاج (HNSW والتقسيم)

لضمان إمكانية توسيع نطاق التطبيق ليشمل أكثر من 100 ألف صف والتعامل مع عدد كبير من الزيارات، عملت كمسؤول قاعدة بيانات افتراضي لتطبيق تحسينَين متقدّمين على قاعدة البيانات:

  • فهرس HNSW (Hierarchical Navigable Small World): لقد أنشأت فهرس HNSW في عمود المتجهات. على عكس الفهارس المسطّحة، ينشئ HNSW رسمًا بيانيًا متعدد الطبقات يتيح إجراء عمليات بحث سريعة للغاية عن أقرب جيران تقريبيين (ANN) مع استرجاع عالٍ.
  • تقسيم الجدول حسب التصريح: قسّمت جدول المطاعم حسب الحي. يضمن ذلك أن تفحص الطلبات التي تستهدف منطقة معيّنة القسم ذي الصلة فقط بدلاً من الجدول بأكمله، ما يقلّل بشكل كبير من عمليات الإدخال والإخراج على القرص ووقت استجابة الطلبات.

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

12. تنظيف

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس التطبيقي، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد.
  2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على "حذف".
  3. في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على "إيقاف" لحذف المشروع.

13. تهانينا

لقد أنشأت ونشرت بنجاح تطبيقًا مستندًا إلى البيانات ويعمل بالذكاء الاصطناعي باستخدام Vibe Coding.

في هذا التمرين العملي، عليك:

  • تم توفير قاعدة بيانات AlloyDB مع إمكانية الوصول إلى عناوين IP الخاصة والعامة.
  • ربطت بيئة Antigravity IDE مباشرةً بقاعدة البيانات باستخدام أداة Model Context Protocol (MCP) Toolbox.
  • استخدام اللغة الطبيعية لاستيعاب فهرس CSV وربط واجهة Next.js الأمامية بقاعدة البيانات ونشرها على Cloud Run
  • تم تفعيل عملية دمج "منصّة الوكيل" داخل قاعدة البيانات لإنشاء تضمينات المتّجهات وإجراء البحث الدلالي.
  • عملت كمسؤول قاعدة بيانات افتراضي لتحسين قاعدة البيانات لتناسب حجم الإنتاج باستخدام فهرسة HNSW وتقسيم الجداول.

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

لمزيد من المعلومات، يُرجى الرجوع إلى مستندات المنتج: