إنشاء محرك فائض في الوقت الفعلي باستخدام Gemini 3 Flash وCloud SQL

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستنشئ تطبيق Neighbor Loop، وهو تطبيق مستدام لمشاركة فائض السلع يعامل الذكاء كعنصر أساسي في طبقة البيانات.

من خلال دمج Gemini 3.0 Flash مع ميزة تكامل تعلّم الآلة في Cloud SQL، ستنتقل من التخزين الأساسي إلى عالم "الذكاء في قاعدة البيانات". ستتعلّم كيفية إجراء تحليل متعدد الوسائط للسلع واستخلاص الدلالات مباشرةً من خلال SQL.

ما ستنشئه

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

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

• التوفير بنقرة واحدة: كيفية إعداد Cloud SQL ومثيل مصمَّم لمهام الذكاء الاصطناعي
• التضمينات داخل قاعدة البيانات: إنشاء متّجهات text-embedding-005 مباشرةً ضمن عبارات INSERT
• الاستدلال المتعدّد الوسائط: استخدام Gemini 3.0 Flash "لرؤية" العناصر وإنشاء نبذات تعريفية ذكية تلقائيًا بأسلوب مناسب للمواعدة
• استخلاص الدلالات: إجراء "عمليات التحقّق من الأجواء" المستندة إلى المنطق داخل طلبات بحث SQL باستخدام الدالة ai.if() لتصفية النتائج استنادًا إلى السياق وليس إلى العمليات الحسابية فقط

البنية

تتجاوز Neighbor Loop الاختناقات التقليدية في طبقة التطبيق. بدلاً من استخراج البيانات لمعالجتها، نستخدم ما يلي:

1. دمج Cloud SQL مع تعلُّم الآلة: لإنشاء المتجهات وتخزينها في الوقت الفعلي
2. Google Cloud Storage: لتخزين الصور
3. ‫Gemini 3.0 Flash: لإجراء عمليات استدلال في أقل من ثانية على بيانات الصور والنصوص مباشرةً من خلال SQL
4. ‫Cloud Run: لاستضافة خلفية Flask خفيفة الوزن تتضمّن ملفًا واحدًا

المتطلبات

• متصفّح، مثل Chrome أو Firefox
• مشروع Google Cloud تم تفعيل الفوترة فيه
• الإلمام بأساسيات SQL وPython

2. قبل البدء

إنشاء مشروع

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

لتجربة هذا الدرس التطبيقي حول الترميز، يمكنك استخدام رابط رصيد الفوترة التجريبي في Google Cloud Platform:

https://bit.ly/ez-cloudsql2

كيف يمكن تحصيل قيمة الرصيد باستخدام هذا الرابط؟ إحالة:

3. ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".

4. بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

5. نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

6. إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

7. فعِّل واجهات برمجة التطبيقات المطلوبة: اتّبِع الرابط وفعِّل واجهات برمجة التطبيقات.

يمكنك بدلاً من ذلك استخدام أمر gcloud لهذا الغرض. راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

المشاكل المحتملة وتحديد المشاكل وحلّها

متلازمة "المشروع الوهمي"	نفّذت الأمر gcloud config set project، ولكنّك في الواقع تنظر إلى مشروع مختلف في واجهة مستخدم Console. تحقَّق من رقم تعريف المشروع في القائمة المنسدلة أعلى يمين الصفحة.
حاجز الفوترة	لقد فعّلت المشروع، ولكن نسيت حساب الفوترة. لن يبدأ Cloud SQL إذا كانت الفوترة فارغة.
تأخّر في نشر واجهة برمجة التطبيقات	نقرت على "تفعيل واجهات برمجة التطبيقات"، ولكن سطر الأوامر لا يزال يعرض Service Not Enabled. انتظِر لمدة 60 ثانية. تحتاج السحابة الإلكترونية إلى بضع لحظات لتنشيط الخلايا العصبية.

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

في هذا التمرين العملي، سنستخدم Cloud SQL for PostgreSQL كقاعدة بيانات لبيانات الاختبار.

لننشئ مثيلاً من Cloud SQL سيتم تحميل مجموعة البيانات الاختبارية فيه.

1. انقر على الزر أو انسخ الرابط أدناه إلى المتصفّح الذي سجّلت فيه الدخول إلى حساب مستخدم Google Cloud Console.

التشغيل بنقرة واحدة

2. بعد إكمال هذه الخطوة، سيتم استنساخ المستودع إلى محرّر Cloud Shell المحلي، وستتمكّن من تنفيذ الأمر أدناه من مجلد المشروع (من المهم التأكّد من أنّك في دليل المشروع):

sh run.sh

3. استخدِم الآن واجهة المستخدم (من خلال النقر على الرابط في الوحدة الطرفية أو على الرابط "معاينة على الويب" في الوحدة الطرفية).
4. أدخِل تفاصيل معرّف المشروع واسم المثيل للبدء.
5. يمكنك تناول القهوة بينما يتم عرض السجلات، ويمكنك الاطّلاع على كيفية تنفيذ ذلك وراء الكواليس هنا.

المشاكل المحتملة وتحديد المشاكل وحلّها

عدم تطابق المنطقة	إذا فعّلت واجهات برمجة التطبيقات في us-central1 وحاولت توفير المجموعة في asia-south1، قد تواجه مشاكل في الحصة أو تأخيرات في أذونات حساب الخدمة. يجب الالتزام بمنطقة واحدة طوال فترة التدريب العملي.
مهلة Cloud Shell	إذا استغرقت استراحة القهوة 30 دقيقة، قد يتم تشغيل وضع السكون في Cloud Shell وفصل عملية sh run.sh. يجب إبقاء علامة التبويب نشطة.

4. توفير المخطط

بعد تشغيل مثيل Cloud SQL، انتقِل إلى أداة تعديل SQL في Cloud SQL Studio لتفعيل إضافات الذكاء الاصطناعي وتوفير المخطط.

قد تحتاج إلى الانتظار إلى أن يكتمل إنشاء مثيلك. بعد ذلك، سجِّل الدخول إلى مثيل Cloud SQL باستخدام بيانات الاعتماد التي أنشأتها عند إنشاء المثيل. استخدِم البيانات التالية للمصادقة على PostgreSQL:

• اسم المستخدم : "postgres"
• قاعدة البيانات : "postgres"
• كلمة المرور : "cloudsql" (أو أي كلمة مرور تم ضبطها عند إنشاء الحساب)

بعد إكمال عملية المصادقة بنجاح في Cloud SQL Studio، يتم إدخال أوامر SQL في "المحرّر". يمكنك إضافة نوافذ "المحرّر" متعددة باستخدام علامة الجمع على يسار النافذة الأخيرة.

ستُدخل أوامر Cloud SQL في نوافذ المحرّر، باستخدام الخيارات "تنفيذ" و"تنسيق" و"محو" حسب الحاجة.

تفعيل الإضافات

لإنشاء هذا التطبيق، سنستخدم الإضافتين pgvector وgoogle_ml_integration. تتيح لك إضافة pgvector تخزين عمليات التضمين المتجهة والبحث عنها. توفّر إضافة google_ml_integration دوال يمكنك استخدامها للوصول إلى نقاط نهاية التوقّعات في Vertex AI من أجل الحصول على توقّعات في SQL. فعِّل هذه الإضافات من خلال تنفيذ تعريفات البيانات التالية:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

إنشاء جدول

يمكنك إنشاء جدول باستخدام عبارة DDL أدناه في Cloud SQL Studio:

-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
   item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   owner_id UUID,
   provider_name TEXT,
   provider_phone TEXT,
   title TEXT,
   bio TEXT,
   category TEXT,
   image_url TEXT,
   item_vector VECTOR(768),
   status TEXT DEFAULT 'available',
   created_at TIMESTAMP DEFAULT NOW()
);

-- Swipes Table (The Interaction)
CREATE TABLE swipes (
   swipe_id SERIAL PRIMARY KEY,
   swiper_id UUID,
   item_id UUID REFERENCES items(item_id),
   direction TEXT CHECK (direction IN ('left', 'right')),
   is_match BOOLEAN DEFAULT FALSE,
   created_at TIMESTAMP DEFAULT NOW()
);

سيسمح العمود item_vector بتخزين قيم المتّجه للنص.

منح الإذن

نفِّذ العبارة أدناه لمنح إذن التنفيذ على الدالة "embedding":

GRANT EXECUTE ON FUNCTION embedding TO postgres;

تفعيل عملية الدمج مع تعلُّم الآلة

للاستفادة من ميزات تعلُّم الآلة مباشرةً في قاعدة البيانات، عليك تفعيل علامة دمج تعلُّم الآلة.

يمكنك تنفيذ الأمر أدناه من "وحدة Cloud Shell الطرفية":

INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"

gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840

gcloud sql instances patch $INSTANCE_NAME \
    --database-flags=cloudsql.enable_google_ml_integration=on

gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration

منح دور "مستخدم Vertex AI" لحساب خدمة Cloud SQL

من وحدة تحكّم Cloud IAM في Google Cloud، امنح حساب خدمة Cloud SQL (الذي يبدو على النحو التالي: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) إذن الوصول إلى دور "مستخدم Vertex AI". سيحتوي PROJECT_NUMBER على رقم مشروعك.

بدلاً من ذلك، يمكنك تنفيذ الأمر أدناه من "وحدة Cloud Shell الطرفية":

INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)

SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$SA_EMAIL" \
    --role="roles/aiplatform.user"

تسجيل نموذج Gemini 3 Flash في Cloud SQL

نفِّذ عبارة SQL أدناه من "محرّر طلبات البحث في Cloud SQL"

CALL google_ml.create_model(
    model_id => 'gemini-3-flash-preview',
    model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
    model_qualified_name => 'gemini-3-flash-preview',
    model_provider => 'google',
    model_type => 'generic',
    model_auth_type => 'cloudsql_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.

المشاكل المحتملة وتحديد المشاكل وحلّها

حلقة "فقدان الذاكرة" بشأن كلمات المرور	إذا كنت قد استخدمت عملية الإعداد "بنقرة واحدة" ولم تتمكّن من تذكُّر كلمة المرور، انتقِل إلى صفحة "المعلومات الأساسية للمثيل" في وحدة التحكّم وانقر على "تعديل" لإعادة ضبط كلمة مرور postgres.
رسالة الخطأ "لم يتم العثور على الإضافة"	إذا تعذّر تنفيذ CREATE EXTENSION، يكون السبب غالبًا أنّ الجهاز الظاهري لا يزال في حالة "صيانة" أو "تحديث" منذ عملية التوفير الأولية. تحقَّق ممّا إذا كانت خطوة إنشاء الجهاز الافتراضي قد اكتملت وانتظِر بضع ثوانٍ إذا لزم الأمر.
فجوة نشر إدارة الهوية وإمكانية الوصول	لقد نفّذت أمر gcloud في "إدارة الهوية وإمكانية الوصول"، ولكن لا يزال أمر SQL CALL يتعذّر تنفيذه بسبب خطأ في الأذونات. قد يستغرق نشر تغييرات "إدارة الهوية وإمكانية الوصول" بعض الوقت من خلال البنية الأساسية لشبكة Google. خذوا نفسًا عميقًا.
عدم تطابق أبعاد المتّجه	تم ضبط الجدول items على VECTOR(768). إذا حاولت استخدام نموذج مختلف (مثل نموذج 1536-dim) لاحقًا، ستنفجر عمليات الإدراج. الالتزام بـ text-embedding-005
خطأ إملائي في رقم تعريف المشروع	في create_model، إذا تركت الأقواس « » أو أخطأت في كتابة رقم تعريف مشروعك، ستبدو عملية تسجيل النموذج ناجحة ولكنها ستفشل أثناء الاستعلام الفعلي الأول. يُرجى التحقّق من السلسلة.
تم إيقاف دمج Vertex AI	تشغيل –enable-google-ml-integration (منفصل عن علامة قاعدة البيانات)

5- تخزين الصور (Google Cloud Storage)

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

1. إنشاء حزمة: أنشئ حزمة جديدة في مشروعك على Google Cloud Platform (مثل neighborloop-images)، ويُفضّل أن تكون في المنطقة نفسها التي توجد فيها قاعدة البيانات والتطبيق.
2. ضبط إذن الوصول العام: * انتقِل إلى علامة التبويب الأذونات الخاصة بالحزمة.
3. أضِف عنصر allUsers الأساسي.
4. عيِّن دور عارض عنصر التخزين (ليتمكّن الجميع من رؤية الصور) ودور منشئ عنصر التخزين (لأغراض تحميل العرض التوضيحي).

الحل البديل (حساب الخدمة): إذا كنت تفضّل عدم استخدام الوصول العام، تأكَّد من منح حساب الخدمة لتطبيقك إذن الوصول الكامل إلى Cloud SQL وأدوار "مساحة التخزين" اللازمة لإدارة العناصر بشكل آمن.

إذا أردت تنفيذ الأمر ومنح إذن الوصول العام نفِّذ الأوامر التالية في "وحدة Cloud Shell الطرفية":

BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
    --member="allUsers" \
    --role="roles/storage.objectViewer"

المشاكل المحتملة وتحديد المشاكل وحلّها

The Region Drag	إذا كانت قاعدة البيانات في us-central1 وكان الحِزمة في europe-west1، فإنّك تبطئ الذكاء الاصطناعي حرفيًا. تتم عملية "التحقّق من الأجواء" بسرعة، ولكن قد يبدو استرداد الصورة لواجهة المستخدم بطيئًا. يجب أن تكون في المنطقة نفسها
تفرد اسم الحزمة	أسماء الحِزم هي مساحة اسم عامة. إذا حاولت تسمية الحزمة neighborloop-images، من المحتمل أنّ مستخدمًا آخر قد اختار هذا الاسم من قبل. إذا تعذّر إنشاء الفيديو، أضِف لاحقة عشوائية.
الخلط بين "صاحب القناة" و"المشاهد"	الخلط بين "المُنشئ" و"المشاهد": إذا أضفت "مشاهد" فقط، سيتعطّل تطبيقك عندما يحاول المستخدم إدراج عنصر جديد لأنّه ليس لديه إذن بالكتابة في الملف. تحتاج إلى كليهما لإعداد هذا العرض التوضيحي المحدّد.

6. لننشئ التطبيق

استنسِخ هذا المستودع في مشروعك وسنستعرضه معًا.

مستودع Github

1. لاستنساخ هذا، شغِّل الأوامر التالية واحدًا تلو الآخر من "وحدة Cloud Shell الطرفية" (في الدليل الجذر أو من أي مكان تريد إنشاء هذا المشروع منه):

git clone https://github.com/flazer99/neighbor-loop-cloud-sql

cd neighbor-loop-cloud-sql/

من المفترض أن يؤدي ذلك إلى إنشاء المشروع، ويمكنك التأكّد من ذلك في "محرِّر Cloud Shell".

2. كيفية الحصول على مفتاح Gemini API
3. انتقِل إلى Google AI Studio: انتقِل إلى aistudio.google.com.
4. تسجيل الدخول: استخدِم حساب Google نفسه الذي تستخدمه لمشروعك على السحابة الإلكترونية.
5. إنشاء مفتاح واجهة برمجة التطبيقات:
6. في الشريط الجانبي الأيمن، انقر على "الحصول على مفتاح API".
7. انقر على الزر "إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد".
8. نسخ المفتاح: بعد إنشاء المفتاح، انقر على رمز النسخ.
9. الآن، اضبط متغيّرات البيئة في ملف ‎ .env

GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>

استبدِل قيم العناصر النائبة <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.

إذا أردت اختبارها محليًا أو من أي مكان، انتقِل إلى مثيل Cloud SQL، وانقر على "تعديل" ثم على "تفعيل عنوان IP العام" أو "إمكانية الاتصال عبر عنوان IP العام" (وليس العنوان الصادر)، وأدخِل "0.0.0.0/0" في "الشبكات الخارجية المسموح بها" لأغراض التطوير، ولكن بعد الانتهاء، أزِل إمكانية الاتصال عبر عنوان IP العام وأوقِفها.

المشاكل المحتملة وتحديد المشاكل وحلّها

الخلط بين حسابات متعددة	إذا كنت مسجّلاً الدخول إلى حسابات متعدّدة على Google (حساب شخصي مقابل حساب عمل)، قد يتم ضبط AI Studio تلقائيًا على الحساب الخاطئ. تحقَّق من الأفاتار في أعلى يسار الصفحة للتأكّد من أنّه يتطابق مع حساب مشروعك على GCP.
تجاوز حصة "المستوى المجاني"	إذا كنت تستخدم الفئة المجانية، ستكون هناك حدود للمعدّل (طلبات في الدقيقة). إذا "مرّرت" بسرعة كبيرة في Neighbor Loop، قد يظهر لك الخطأ 429 Too Many Requests. تمهَّل!
أمان المفتاح المعرَّض للخطر	إذا git commit ملف .env الذي يحتوي على المفتاح عن طريق الخطأ أضِف دائمًا .env إلى .gitignore.

7. هيا نتحقّق من الرمز

"الملف التعريفي للمواعدة" الخاص بك

عندما يحمّل المستخدم صورة لمنتج، لا يجب أن يضطر إلى كتابة وصف طويل. أستخدم Gemini 3 Flash "لرؤية" المنتج وكتابة بطاقة بيانات له.

في الخلفية، يقدّم المستخدم عنوانًا وصورة فقط. يتولّى Gemini الباقي:

prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
   "bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
   "category": "One-word category",
   "tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
   model="gemini-3-flash-preview",
   contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
   config=types.GenerateContentConfig(response_mime_type="application/json")
)

التضمينات في قاعدة البيانات في الوقت الفعلي

من أبرز ميزات Cloud SQL إمكانية إنشاء تضمينات بدون مغادرة سياق SQL. بدلاً من استدعاء نموذج تضمين في Python وإرسال المتّجه مرة أخرى إلى قاعدة البيانات، يمكنني إجراء كل ذلك في عبارة INSERT واحدة باستخدام الدالة embedding():

INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
   :owner, :name, :phone, :title, :bio, :cat, :url, 'available',
   embedding('text-embedding-005', :title || ' ' || :bio)::vector
)

ويضمن ذلك أن يكون كل عنصر "قابلاً للبحث" حسب معناه في اللحظة التي يتم فيها نشره. يُرجى العِلم أنّ هذا الجزء يغطّي ميزة "إدراج المنتج" في تطبيق Neighbor Loop.

ميزة "البحث عن المتّجهات" المتقدّمة و"الفلترة الذكية" باستخدام Gemini 3.0

البحث عن الكلمات الرئيسية العادية محدود. إذا بحثت عن "شيء لإصلاح الكرسي"، قد لا تعرض قاعدة البيانات التقليدية أي نتائج إذا لم تكن الكلمة "كرسي" واردة في العنوان. يحلّ Neighbor Loop هذه المشكلة من خلال ميزة البحث المتقدّم عن المتجهات في Cloud SQL AI.

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

SELECT item_id, title, bio, category, image_url,
      1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items 
WHERE status = 'available' 
 AND item_vector IS NOT NULL 
ORDER BY score DESC 
LIMIT 5

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

حلقة "التمرير سريعًا للمطابقة"

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

التمرير سريعًا إلى اليمين: تجاهل

التمرير سريعًا لليمين: لديك تطابق!

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

8. لننشره على Cloud Run

1. يمكنك نشرها على Cloud Run من خلال تنفيذ الأمر التالي من "وحدة Cloud Shell الطرفية" حيث يتم استنساخ المشروع والتأكّد من أنّك داخل المجلد الجذر للمشروع.

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

gcloud run deploy neighbor-loop-cloud-sql \
   --source . \
   --region=us-central1 \
   --allow-unauthenticated \
   --network=easy-cloudsql-vpc \
   --subnet=easy-cloudsql-subnet \
   --vpc-egress=private-ranges-only \
   --set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>

استبدِل قيم العناصر النائبة <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>

بعد انتهاء الأمر، سيتم عرض عنوان URL للخدمة. انسخها.

الآن، استخدِم عنوان URL الخاص بالخدمة (نقطة نهاية Cloud Run التي نسختها سابقًا) واختبِر التطبيق. حمِّل صورة لأداة الطاقة القديمة، ودَع Gemini يتولّى الباقي.

المشاكل المحتملة وتحديد المشاكل وحلّها

حلقة "تعذّر المراجعة"

إذا انتهى النشر ولكنّ عنوان URL يعرض 500 Internal Server Error، راجِع السجلات. يحدث ذلك عادةً بسبب متغيّر بيئة غير متوفّر (مثل خطأ إملائي في DATABASE_URL) أو لأنّ حساب خدمة Cloud Run لا يملك أذونات القراءة من حزمة GCS.

9- تحديد المشاكل وحلّها على مستوى عالٍ

10. عرض توضيحي

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

ولأغراض العرض التوضيحي لبضعة أيام، يمكنك تجربة ما يلي:

تطبيق العرض التوضيحي

11. تَنظيم

بعد الانتهاء من هذا الدرس العملي، لا تنسَ حذف مثيل Cloud SQL.

انتقِل إلى https://console.cloud.google.com/sql/instances. اختَر الجهاز الظاهري الذي تريد حذفه من خلال النقر على علامة الحذف العمودية بجانبه، ثم انقر على "حذف".

12. تهانينا

لقد أنشأت تطبيق Neighbor Loop بنجاح للمجتمعات المستدامة باستخدام Google Cloud. من خلال نقل عملية التضمين ومنطق الذكاء الاصطناعي في Gemini 3 Flash إلى Cloud SQL، يصبح التطبيق سريعًا للغاية (حسب إعدادات النشر) ويصبح الرمز البرمجي واضحًا بشكل ملحوظ. نحن لا نخزّن البيانات فقط، بل نخزّن النية.

إنّ الجمع بين سرعة Gemini 3 Flash ومعالجة المتجهات المحسّنة في Cloud SQL يمثّل حقًا آفاقًا جديدة للمنصات المستندة إلى المجتمع.