vibe-coding-college-specs/chapters/15-product-evolution/05-lesson-advanced-ai-features-integration/spec.md

مشخصات درس‌نامه: تزریق قابلیت‌های پیشرفته هوش مصنوعی؛ جستجوی معنایی (Vector Search) و تولید هوشمند محتوا

• شناسه در سیلابس: L15.6
• فصل: فصل ۱۵: تکامل محصول با AI (Ch 15)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۲۰ دقیقه
• پیش‌نیازهای مستقیم: L15.5 (بهبود ساختار کد و ری‌فکتورینگ امن)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): تفاوت میان «جستجوی کلیدواژه‌ای سنتی» (Keyword Search) و «جستجوی معنایی برداری» (Semantic Vector Search) را شرح دهد و بداند چرا کاربری که کلمه «بانک اطلاعاتی» را سرچ می‌کند باید پروژه‌های برچسب‌خورده با «PostgreSQL» را ببیند.
• تحلیل/ارزیابی کند (Evaluate): نحوه کارکرد اکستنشن pgvector در پایگاه داده PostgreSQL و پایگاه داده Supabase را برای محاسبه شباهت کسینوسی (Cosine Similarity) میان بردارها ارزیابی کند.
• به‌کار ببندد (Apply): یک ویژگی هوشمند در پنل ادمین پیاده کند که با دریافت لینک گیت‌هاب پروژه، توضیحات جذاب فارسی، خلاصه فنی و تگ‌های سئو را به صورت خودکار با خروجی ساختاریافته JSON تولید نماید.
• ایجاد کند (Create): قابلیت جستجوی هوشمند در میان پروژه‌ها و مهارت‌های پورتفولیو را با مدل‌های تولید بردار (Text Embeddings) راه‌اندازی و به رابط کاربری متصل کند.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. فراتر از چت‌بات‌های ساده: هوش مصنوعی نامرئی در بافت محصول:
   • هوش مصنوعی فقط چت‌باکس گوشه صفحه نیست؛ می‌تواند موتور جستجو، دستیار تولید محتوا و پالایشگر داده‌های محصول باشد.
2. کالبدشکافی جستجوی معنایی و بردارها (Vector Embeddings):
   • چرا جستجوی متنی معمولی شکست می‌خورد؟ (عدم تطابق کلمات هم‌معنی).
   • بردار چیست؟ تبدیل معنای هر پروژه به یک رشته عدد در فضا (مثلاً ۱۵۳۶ بُعد) که پروژه‌های مشابه در نزدیکی هم قرار می‌گیرند.
3. فعال‌سازی اکستنشن قدرتمند pgvector در Supabase:
   • فعال‌سازی با دستور تک‌خطی: create extension if not exists vector;.
   • افزودن ستون embedding vector(1536) به جدول پروژه‌ها.
   • نوشتن تابع جستجوی شباهت کسینوسی در SQL با عملگر <=>.
4. تولید خودکار شناسنامه پروژه در پنل مدیریت با AI:
   • فیچر: ادمین آدرس گیت‌هاب یا چند خط یادداشت خام تایپ می‌کند \rightarrow دکمه «تکمیل هوشمند با AI» را می‌زند \rightarrow مدل با قابلیت Structured Outputs / JSON Schema یک پکیج کامل شامل: تیتر جذاب، ۳ پاراگراف توضیحات فارسی روان، دسته‌بندی و لیست تگ‌ها را استخراج و فیلدهای فرم را خودکار پر می‌کند!
5. خروجی ساختارمند با JSON Schema (پرهیز از پرحرفی مدل):
   • الزام مدل زبانی به برگرداندن یک شیء JSON بدون احوالپرسی یا توضیحات اضافه.
6. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): مفهوم شباهت کسینوسی (Cosine Similarity)؛ چگونگی سنجش زاویه میان دو بردار معنایی در فضای چندبُعدی.
   • کال‌اوت سبز (<details class="green">): هزینه ناچیز مدل‌های Embedding (مانند text-embedding-3-small) که ساخت بردار برای هزاران پروژه کمتر از چند هزار تومان هزینه دارد.
   • کال‌اوت قرمز (<details class="red">): تولید بردارها را در هنگام جستجوی کاربر فقط برای عبارت ورودی انجام دهید؛ بردار پروژه‌ها باید از قبل یک‌بار تولید و در دیتابیس ذخیره شده باشد.

آنچه نباید وارد آن شویم (Out-of-Scope):

• آموزش شبکه‌های عصبی Transformer و معماری داخلی آنها.
• پیاده‌سازی خوشه‌بندی‌های بدون نظارت K-Means در لایه دیتابیس.

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Semantic Search	جستجوی معنایی	جستجوی مبتنی بر درک مقصود و معنای عمیق مفاهیم به جای تطابق کلمه به کلمه متن
Vector Embedding	تعبیه برداری	تبدیل متون به بردارهای عددی چندبعدی به گونه‌ای که کلمات هم‌معنی در فضا به هم نزدیک باشند
pgvector	اکستنشن پی‌جی‌وکتور	افزونه رسمی پایگاه داده PostgreSQL برای ذخیره، ایندکس و جستجوی فوق‌سریع بردارها
Cosine Similarity	شباهت کسینوسی	معیار ریاضی سنجش زاویه میان دو بردار که میزان همبستگی مفهومی آن‌ها را معین می‌کند
Structured JSON Output	خروجی ساختاریافته جیسون	وادار کردن مدل هوش مصنوعی به رعایت یک قالب و اسکیمای سخت‌گیرانه داده‌ها برای مصرف در برنامه

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: فضای سه‌بعدی نئونی پر از نقاط نوری معلق (بردارها) که با خطوط نورانی به کلمات «پایگاه داده»، «Supabase» و «SQL» متصل شده‌اند.
2. تفاوت جستجوی کلیدواژه‌ای با جستجوی برداری معنایی: images/keyword-vs-semantic-search.png
   • موضوع: اینفوگرافیک مقایسه‌ای: جستجوی «فروشگاه آنلاین» در جستجوی سنتی نتایج «E-Commerce» را نمی‌یابد؛ در جستجوی معنایی این دو دقیقاً در کنار هم قرار دارند.
3. معماری جستجوی معنایی در Supabase با pgvector: images/supabase-pgvector-flow.png
   • موضوع: فلوچارت: کاربر در اینپوت سرچ تایپ می‌کند \rightarrow تولید بردار کوئری با مدل \rightarrow کوئری SQL در سوپابیس با عملگر کسینوس \rightarrow برگرداندن پروژه‌ها به ترتیب شباهت.
4. دکمه جادویی تولید محتوای پروژه در پنل مدیریت: images/ai-project-generator-ui.png
   • موضوع: اسکرین‌شات از فرم ثبت پروژه در پنل ادمین با دکمه «تولید هوشمند با AI» و انیمیشن پر شدن خودکار فیلدهای توضیحات و تگ‌ها.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # تزریق قابلیت‌های پیشرفته هوش مصنوعی؛ جستجوی معنایی (Vector Search) و تولید هوشمند محتوا
2. مقدمه: هوش مصنوعی تا کنون کد می‌نوشت؛ حال وقت آن است که قابلیت‌های جادویی هوش مصنوعی را به عنوان قلب تپنده پورتفولیو به نمایش بگذاریم!
3. جدول کاور درس
4. استعاره جستجوی کتاب در کتابخانه بر اساس موضوع به جای عنوان جلد:
   • وقتی از کتابدار کتابی درباره «آشپزی ایتالیایی» می‌خواهید، او کتاب «طرز تهیه پاستا» را می‌آورد حتی اگر کلمه ایتالیا روی جلد نباشد.
5. مبانی بردارها و ریاضیات معنایی (Vector Embeddings):
   • چگونه هوش مصنوعی متون را به مختصات فضایی تبدیل می‌کند.
6. راه‌اندازی pgvector در Supabase و ذخیره بردار پروژه‌ها:
   • نوشتن مایگریشن فعال‌سازی اکستنشن و افزودن ستون embedding.
7. پیاده‌سازی ماژول جستجوی معنایی پورتفولیو در Next.js:
   • ساخت اینپوت جستجوی هوشمند در هدر سایت با افکت لودینگ برداری.
8. ساخت ویژگی تولید خودکار مشخصات پروژه با Structured Outputs:
   • پرامپت فرمت JSON Schema برای استخراج سئو و متن فارسی از روی یادداشت‌های خام یا ریپوی گیت‌هاب.
9. جعبه پرامپت طلایی: ساخت اندپوینت جستجوی معنایی با ایجنت:
   • پرامپت دقیق:

     «من اکستنشن vector را در Supabase فعال کرده‌ام. لطفاً ۱) یک تابع RPC در دیتابیس برای جستجوی شباهت کسینوسی پروژه‌ها بنویس، ۲) یک Route Handler برای تولید بردار متن سرچ با استفاده از مدل text-embedding-3-small اوپن‌ای‌آی یا OpenRouter ایجاد کن، و ۳) کامپوننت جستجو در فرانت‌اند را به گونه‌ای متصل کن که نتایج مرتبط را به صورت آنی نمایش دهد.»

10. باکس نکته Quera (<details class="violet">): استفاده از کش در جستجوی معنایی؛ برای عبارات جستجوی متداول، بردارها را کش کنید تا هزینه به حداقل برسد.
11. باکس هشدار Quera (<details class="red">): هرگز بردارها را به صورت پویا در سمت کلاینت تولید نکنید؛ کلید API هوش مصنوعی باید در محیط امن سرور اکشن بماند.
12. باکس رضایت‌بخش Quera (<details class="green">): تست سرچ کلماتی که در سایت نیستند (مثل «توسعه سمت کاربر») و دیدن لود شدن فوری پروژه‌های React و Next.js!
13. جمع‌بندی درس‌نامه: تسلط بر هوش مصنوعی پیشرفته داخلی؛ ورود به دنیای ساخت فرآیندهای خودمختار چندمرحله‌ای (Agentic Workflows) در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• تفاوت جستجوی متنی سنتی و جستجوی معنایی برداری با مثال‌های شفاف تبیین شود.
• نحوه فعال‌سازی و کاربرد اکستنشن pgvector در Supabase آموزش داده شود.
• تولید خروجی ساختاریافته JSON Schema برای تولید خودکار دیتای پروژه‌ها تشریح گردد.
• پرامپت‌های ساخت اندپوینت جستجوی برداری در متن درس لحاظ شوند.