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

1. مقدمة

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

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

ما ستنشئه

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

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

e74cb0eb7e17d6da.png

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

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

المتطلبات

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

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

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

2. قبل البدء

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

إنشاء مشروع

  1. في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
  2. تأكَّد من تفعيل الفوترة لمشروعك على 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. اضبط متغيّر البيئة 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. أكِّد صحة حسابك النشط باتّباع الخطوات التالية:
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 النشطة المدمجة (التي تقع حاليًا داخل دليل مشروع 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. يستخدم هذا الإصدار الأوّلي بيانات تجريبية ولا يرتبط بقاعدة البيانات بعد.

أولاً، شغِّل الأوامر التالية مباشرةً في وحدة 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، ما يشير إلى أنّه تم الربط بنجاح.

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

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

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

المهمة

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

في Antigravity، افتح لوحة Agent Chat (عادةً على يسار المحرّر).

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

Read the headers of database/seed_data_berlin.csv to determine column data types and create the restaurants table using the MCP tool execute_sql. Then, read the CSV rows locally and insert all 100 records into remote AlloyDB using a single batched multi-row INSERT INTO ... VALUES (...), (...), ...; statement via execute_sql. Do not print the CSV contents, row payloads, or SQL statements to the chat transcript.

التحقّق

سيفعل الوكيل ما يلي:

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

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. When testing or verifying queries, always use LIMIT 3 and suppress quiet npm/build logs.

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

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

التحقّق

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

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

شغِّل أمر النشر، مع تمرير عنوان 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. Execute embedding generation quietly without printing embedding vectors or SQL progress logs to chat.

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

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

التحقّق

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

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

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 my Principal Database Architect! Our semantic search is feeling great, but let's level up our backend to effortlessly scale to 100K+ rows and handle high concurrent traffic. Inspect our restaurants schema quietly, and work your magic by immediately applying your top 2 production optimizations—an HNSW vector index and list partitioning by neighborhood—right now in this turn. No need to wait for approval! Keep the SQL logs clean and hit me with a crisp 3-bullet summary of how we just supercharged our database.

التحقّق

سيحلّل الوكيل مخطط قاعدة البيانات بشكل مستقل ويطبّق تحسينَين مهمَّين على الإنتاج:

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

سيختتم هذا القسم بملخّص موجز من 3 نقاط يشرح المزايا المعمارية لهذه الترقيات في مرحلة الإنتاج.

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

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

المهمة

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

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

التحقّق

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

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 يدويًا أو فتح برامج خارجية لقواعد البيانات.

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