۱. مرور کلی
در این آزمایشگاه کد، شما Neighbor Loop را خواهید ساخت، یک اپلیکیشن اشتراکگذاری مازاد پایدار که با هوش به عنوان یک شهروند درجه یک از لایه داده رفتار میکند.
با ادغام Gemini 3.0 Flash و ادغام یادگیری ماشینی Cloud SQL، شما از فضای ذخیرهسازی پایه به حوزه هوش درون پایگاه داده قدم خواهید گذاشت. شما یاد خواهید گرفت که چگونه تجزیه و تحلیل آیتمهای چندوجهی و کشف معنایی را مستقیماً در SQL انجام دهید.
آنچه خواهید ساخت
یک برنامه وب با عملکرد بالا و قابلیت «کشیدن برای تطبیق» برای اشتراکگذاری مازاد جامعه.
آنچه یاد خواهید گرفت
- تأمین با یک کلیک: نحوه راهاندازی یک Cloud SQL و نمونه طراحیشده برای بارهای کاری هوش مصنوعی.
- جاسازیهای درون پایگاه داده: تولید بردارهای text-embedding-005 مستقیماً درون دستورات INSERT.
- استدلال چندوجهی: استفاده از Gemini 3.0 Flash برای «دیدن» موارد و تولید خودکار بیوگرافیهای طنزآمیز به سبک قرار ملاقات.
- کشف معنایی: انجام «بررسیهای ارتعاشی» مبتنی بر منطق درون کوئریهای SQL با استفاده از تابع ai.if() برای فیلتر کردن نتایج بر اساس زمینه، نه فقط ریاضی.
معماری
حلقه همسایه (Neighbor Loop) گلوگاههای سنتی لایه برنامه را دور میزند. به جای بیرون کشیدن دادهها برای پردازش آنها، از موارد زیر استفاده میکنیم:
- ادغام SQL ابری + ML: برای تولید و ذخیره بردارها به صورت بلادرنگ.
- فضای ابری گوگل: برای ذخیره تصاویر
- Gemini 3.0 Flash: برای انجام استدلال زیر ثانیهای روی دادههای تصویر و متن مستقیماً از طریق SQL.
- Cloud Run: برای میزبانی یک بکاند سبک و تکفایلی Flask.
الزامات
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا میشود، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی میکنید که آیا از قبل احراز هویت شدهاید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
- فعال کردن API های مورد نیاز: روی لینک کلیک کنید و API ها را فعال کنید.
به عنوان یک روش جایگزین، میتوانید از دستور gcloud برای این کار استفاده کنید. برای مشاهده دستورات و نحوه استفاده از gcloud به مستندات آن مراجعه کنید.
اشکالات و عیبیابی
سندرم «پروژه ارواح» | شما |
سنگر بیلینگ | شما پروژه را فعال کردهاید، اما حساب صورتحساب را فراموش کردهاید. اگر صورتحساب خالی باشد، Cloud SQL شروع نمیشود. |
تأخیر انتشار API | شما روی «فعال کردن APIها» کلیک کردهاید، اما خط فرمان هنوز میگوید |
۳. راهاندازی پایگاه داده
در این آزمایش، ما از Cloud SQL برای PostgreSQL به عنوان پایگاه داده برای دادههای آزمایشی استفاده خواهیم کرد.
بیایید یک نمونه Cloud SQL ایجاد کنیم که مجموعه دادههای آزمایشی در آن بارگذاری شود.
- روی دکمه کلیک کنید یا لینک زیر را در مرورگر خود که کاربر Google Cloud Console در آن وارد شده است، کپی کنید.
- پس از اتمام این مرحله، مخزن در ویرایشگر پوسته ابری محلی شما کلون میشود و میتوانید دستور زیر را از پوشه پروژه اجرا کنید (مهم است که مطمئن شوید در دایرکتوری پروژه هستید):
sh run.sh
- حالا از رابط کاربری استفاده کنید (با کلیک روی لینک در ترمینال یا کلیک روی لینک «پیشنمایش در وب» در ترمینال).
- برای شروع، اطلاعات خود را برای شناسه پروژه و نام نمونه وارد کنید.
- در حالی که کندهها در حال حرکت هستند، یک قهوه بنوشید و میتوانید در اینجا در مورد چگونگی انجام این کار در پشت صحنه بخوانید.
اشکالات و عیبیابی
عدم تطابق منطقه | اگر APIهای خود را در |
مهلت زمانی پوسته ابری | اگر زمان استراحت قهوه شما 30 دقیقه طول بکشد، ممکن است Cloud Shell به حالت خواب برود و فرآیند |
۴. تأمین طرحواره
پس از اجرای نمونه Cloud SQL خود، به ویرایشگر SQL Cloud SQL Studio بروید تا افزونههای هوش مصنوعی را فعال کرده و طرحواره را آماده کنید.
ممکن است لازم باشد منتظر بمانید تا نمونه شما به طور کامل ایجاد شود. پس از اتمام این کار، با استفاده از اعتبارنامههایی که هنگام ایجاد آن ایجاد کردهاید، وارد نمونه Cloud SQL شوید. از دادههای زیر برای تأیید اعتبار در PostgreSQL استفاده کنید:
- نام کاربری: "
postgres" - پایگاه داده: "
postgres" - رمز عبور: "
cloudsql" (یا هر چیزی که در زمان ایجاد تعیین کردهاید)
پس از اینکه با موفقیت در Cloud SQL Studio احراز هویت شدید، دستورات SQL در ویرایشگر وارد میشوند. میتوانید با استفاده از علامت + در سمت راست آخرین پنجره، چندین پنجره ویرایشگر اضافه کنید.
شما دستورات مربوط به Cloud SQL را در پنجرههای ویرایشگر وارد خواهید کرد و در صورت لزوم از گزینههای Run، Format و Clear استفاده خواهید کرد.
فعال کردن افزونهها
برای ساخت این برنامه، از افزونههای pgvector و google_ml_integration استفاده خواهیم کرد. افزونه pgvector به شما امکان ذخیره و جستجوی جاسازیهای برداری را میدهد. افزونه google_ml_integration توابعی را ارائه میدهد که برای دسترسی به نقاط پایانی پیشبینی هوش مصنوعی Vertex برای دریافت پیشبینیها در SQL استفاده میکنید. این افزونهها را با اجرای DDL های زیر فعال کنید :
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;
فعال کردن ادغام ML
برای استفاده مستقیم از ویژگیهای یادگیری ماشین در پایگاه داده خود، باید پرچم ادغام ML را فعال کنید.
میتوانید دستور زیر را از ترمینال 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
از کنسول Google Cloud IAM ، به حساب سرویس Cloud SQL (که به این شکل است: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) دسترسی به نقش "Vertex AI User" را بدهید. 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.
اشکالات و عیبیابی
حلقهی «فراموشی رمز عبور» | اگر از تنظیمات «یک کلیک» استفاده کردهاید و رمز عبور خود را به خاطر نمیآورید، به صفحه اطلاعات اولیه Instance در کنسول بروید و برای تنظیم مجدد رمز عبور |
خطای "افزونه یافت نشد" | اگر |
شکاف انتشار IAM | شما دستور |
عدم تطابق ابعاد برداری | جدول |
شناسه پروژه، غلط املایی | در فراخوانی |
ادغام هوش مصنوعی Vertex غیرفعال است | دستور |
۵. فضای ذخیرهسازی تصویر (فضای ذخیرهسازی ابری گوگل)
برای ذخیره عکسهای اقلام اضافیمان، از یک سطل GCS استفاده میکنیم. برای این اپلیکیشن آزمایشی، میخواهیم تصاویر به صورت عمومی در دسترس باشند تا فوراً در کارتهای ما نمایش داده شوند.
- ایجاد یک سطل: یک سطل جدید در پروژه GCP خود (مثلاً neighborloop-images) ایجاد کنید ، ترجیحاً در همان ناحیهای که پایگاه داده و برنامه شما قرار دارد.
- پیکربندی دسترسی عمومی: * به برگه مجوزهای سطل بروید.
- تابع اصلی allUsers را اضافه کنید.
- نقش «مشاهدهگر اشیاء ذخیرهسازی» (تا همه بتوانند عکسها را ببینند) و نقش « خالق اشیاء ذخیرهسازی» (برای آپلود نسخه آزمایشی) را تعیین کنید.
جایگزین (حساب کاربری سرویس): اگر ترجیح میدهید از دسترسی عمومی استفاده نکنید، مطمئن شوید که به حساب کاربری سرویس برنامه شما دسترسی کامل به 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"
اشکالات و عیبیابی
کشش منطقه | اگر پایگاه داده شما در |
منحصر به فرد بودن نام سطل | نامهای سطل یک فضای نام سراسری هستند. اگر سعی کنید سطل خود را |
خلط مبحث «خالق» در مقابل «بیننده» | اشتباه در انتخاب «خالق» در مقابل «مشاهدهگر»: اگر فقط «مشاهدهگر» را اضافه کنید، وقتی کاربر سعی میکند یک مورد جدید را فهرست کند، برنامه شما از کار میافتد زیرا مجوز نوشتن فایل را ندارد. برای این تنظیمات نمایشی خاص، به هر دو نیاز دارید. |
۶. بیایید برنامه را ایجاد کنیم
این مخزن را در پروژه خود کلون کنید و بیایید آن را بررسی کنیم.
- برای کلون کردن این، از ترمینال Cloud Shell خود (در دایرکتوری ریشه یا از هر جایی که میخواهید این پروژه را ایجاد کنید)، دستورات زیر را یکی یکی اجرا کنید:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
این باید پروژه را ایجاد کند و شما میتوانید آن را در ویرایشگر Cloud Shell تأیید کنید.
- چگونه کلید API جمینی خود را دریافت کنید
- از استودیوی هوش مصنوعی گوگل دیدن کنید: به aistudio.google.com بروید.
- ورود: از همان حساب گوگلی که برای پروژه گوگل کلود خود استفاده میکنید، استفاده کنید.
- ایجاد کلید API:
- در نوار کناری سمت چپ، روی «دریافت کلید API» کلیک کنید.
- روی دکمهی «ایجاد کلید API در پروژهی جدید» کلیک کنید.
- کپی کردن کلید: پس از تولید کلید، روی نماد کپی کلیک کنید.
- حالا متغیرهای محیطی را در فایل .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>>.
اشکالات و عیبیابی
سردرگمی در مورد حسابهای کاربری متعدد | اگر به چندین حساب گوگل (شخصی در مقابل کاری) وارد شدهاید، ممکن است AI Studio به طور پیشفرض روی حساب اشتباهی تنظیم شود. آواتار گوشه بالا سمت راست را بررسی کنید تا مطمئن شوید که با حساب پروژه GCP شما مطابقت دارد. |
سهمیه «ردیف رایگان» به اوج خود رسید | اگر از سطح رایگان استفاده میکنید، محدودیتهای سرعت وجود دارد (RPM - درخواست در دقیقه). اگر در حلقه همسایه خیلی سریع "swipe" کنید، ممکن است با خطای |
امنیت کلید افشا شده | اگر به طور تصادفی فایل |
۷. بیایید کد را بررسی کنیم
«پروفایل دوستیابی» برای سایت شما
وقتی کاربری عکسی از یک کالا آپلود میکند، نباید مجبور باشد توضیح طولانی بنویسد. من از 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 است. به جای فراخوانی یک مدل جاسازی در پایتون و ارسال بردار به پایگاه داده، من همه این کارها را در یک دستور 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 SQLs، میتوانیم جستجوهای شباهت بسیار سریعی انجام دهیم. اما «جادو»ی واقعی زمانی اتفاق میافتد که نزدیکی برداری را با منطق مبتنی بر LLM ترکیب کنیم.
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 یک "بررسی ارتعاش" را در داخل موتور پایگاه داده انجام میدهد. این امر باعث کاهش تأخیر، کاهش هزینههای خروجی و تضمین این میشود که نتایج نه تنها از نظر ریاضی مشابه هستند، بلکه از نظر زمینهای نیز مرتبط هستند.
حلقه «کشیدن برای تطبیق»
رابط کاربری یک دسته کارت کلاسیک است.
کشیدن انگشت به چپ: حذف کردن.
به راست بکشید: این یک تطابق است!
وقتی به سمت راست میکشید، بکاند تعامل را در جدول سوایپهای ما ثبت میکند و کالا را به عنوان منطبق علامتگذاری میکند. فرانتاند فوراً یک پنجرهی مودال را باز میکند که اطلاعات تماس ارائهدهنده را نشان میدهد تا بتوانید زمان تحویل گرفتن کالا را هماهنگ کنید.
۸. بیایید آن را در Cloud Run مستقر کنیم
- با اجرای دستور زیر از ترمینال Cloud Shell که پروژه در آن کلون شده است، آن را روی Cloud Run مستقر کنید و مطمئن شوید که در پوشه ریشه پروژه هستید .
این را در ترمینال 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 سرویس نمایش داده میشود. آن را کپی کنید.
حالا از آدرس اینترنتی سرویس (نقطه پایانی Cloud Run که قبلاً کپی کردهاید) استفاده کنید و برنامه را آزمایش کنید. عکسی از آن ابزار برقی قدیمی آپلود کنید و بگذارید Gemini بقیه کارها را انجام دهد!
اشکالات و عیبیابی
حلقهی «بازنگری ناموفق» | اگر نصب تمام شد اما URL |
۹. عیبیابی سطح بالا
۱۰. نسخه آزمایشی
شما باید بتوانید از نقطه پایانی خود برای آزمایشها استفاده کنید.
اما برای اهداف آزمایشی برای چند روز، میتوانید با این کار کنید:
۱۱. تمیز کردن
پس از انجام این آزمایش، فراموش نکنید که نمونه Cloud SQL را حذف کنید.
۱۲. تبریک
شما با موفقیت برنامه Neighbor Loop را برای جوامع پایدار با Google Cloud ساختید. با انتقال جاسازی و منطق هوش مصنوعی Gemini 3 Flash به Cloud SQL ، برنامه فوقالعاده سریع است (منوط به تنظیمات استقرار) و کد به طرز چشمگیری تمیز است. ما فقط دادهها را ذخیره نمیکنیم - ما قصد (intent) را ذخیره میکنیم.
ترکیب سرعت Gemini 3 Flash و پردازش برداری بهینه شده Cloud SQL واقعاً مرز بعدی برای پلتفرمهای مبتنی بر جامعه است.