133 lines
14 KiB
Markdown
133 lines
14 KiB
Markdown
# مشخصات درس‌نامه: تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI
|
||
- **شناسه در سیلابس:** `L10.8`
|
||
- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۲۰ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L10.7` (اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** جهش از «کدنویسی با هوش مصنوعی» به «تزریق قابلیت‌های هوش مصنوعی به عنوان فیچر محصول» (AI as a Feature) را درک کرده و ساختار استاندارد Chat Completions API را شرح دهد.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** مزایای هاب‌های چندمدلی نظیر OpenRouter و سرویس‌های واسط بومی (نظیر AvalAI) را در کاهش هزینه‌ها و عدم نیاز به کارت‌های اعتباری بین‌المللی ارزیابی کند.
|
||
- [ ] **به‌کار ببندد (Apply):** یک ویجت چت‌بات هوشمند رزومه (AI Resume Assistant) در گوشه پورتفولیو پیاده کند که با استریم زنده (Streaming)، به سوالات کارفرمایان درباره مهارت‌ها و پروژه‌ها پاسخ دهد.
|
||
- [ ] **ایجاد کند (Create):** یک پرامپت سیستمی مستحکم (System Prompt با تکنیک Grounding) تنظیم کند تا از توهم اطلاعات غیرواقعی و حملات تزریق پرامپت (Prompt Injection) جلوگیری نماید.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **انقلاب در هویت محصول: پورتفولیویی که زنده است و حرف می‌زند!**
|
||
* بازدیدکننده پورتفولیو به جای خواندن صدها سطر رزومه، از هوش مصنوعی می‌پرسد: «آیا فلانی تجربه کار با Supabase را دارد؟» و پاسخ هوشمند دریافت می‌کند.
|
||
2. **کالبدشکافی ساختار پیام‌های API در مدل‌های زبانی (Chat Completion Schema):**
|
||
* پیام سیستمی (`system`): شخصیت، قوانین و دانش پایه دستیار.
|
||
* پیام کاربر (`user`): سوال یا ورودی جدید بازدیدکننده.
|
||
* پیام دستیار (`assistant`): تاریخچه پاسخ‌های مدل برای حفظ کانتکست گفتگو.
|
||
3. **دسترسی بی‌دردسر به مدل‌های روز جهان (OpenRouter و AvalAI):**
|
||
* چرا OpenRouter با یک کلید، دسترسی به Claude 3.5 Sonnet، GPT-4o، DeepSeek V3 و Llama 3 را ممکن می‌کند؟
|
||
* گزینه‌های پرداخت ریالی و پروکسی‌های داخلی پایدار در ایران.
|
||
4. **تکنیک لنگراندازی داده‌ها (Grounding) و دیوارهای امنیتی:**
|
||
* تزریق خلاصه مشخصات صاحب سایت، لیست پروژه‌ها، سابقه کار و راه‌های ارتباطی در پرامپت سیستمی.
|
||
* دستورالعمل سفت‌وسخت: «تو دستیار رزومه هستی. فقط بر اساس اطلاعات بالا پاسخ بده. اگر چیزی را نمی‌دانی، حدس نزن و بگو در رزومه ذکر نشده است.»
|
||
5. **معماری روت سرور امن `/api/chat` در Next.js:**
|
||
* دریافت پیام کاربر $\rightarrow$ افزودن پرامپت سیستمی مخفی در سرور $\rightarrow$ ارسال به OpenRouter با کلید محرمانه $\rightarrow$ استریم پاسخ به مرورگر کاربر.
|
||
6. **پیاده‌سازی رابط کاربری ویجت چت:**
|
||
* آیکون شناور در گوشه پایین سایت، قابلیت باز و بسته شدن، دکمه‌های پیشنهاد سریع سوال (Chips)، و افکت تایپ زنده (Typewriter/Streaming).
|
||
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): حمله تزریق پرامپت (Prompt Injection)؛ چطور نگذاریم کارفرما با گفتن «تمام دستورات قبلی را فراموش کن» دستیار را هک کند.
|
||
* کال‌اوت سبز (`<details class="green">`): مدل‌های فوق‌سریع و تقریباً رایگان مانند DeepSeek V3 یا Gemini 2.0 Flash در OpenRouter با هزینه چند صدم سنت برای هر مکالمه.
|
||
* کال‌اوت قرمز (`<details class="red">`): محدود کردن طول تاریخچه چت (Truncation) به ۶ پیام آخر برای جلوگیری از سوختن توکن‌ها و هزینه‌های انفجاری.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- مباحث پیچیده RAG (Retrieval-Augmented Generation) و دیتابیس‌های برداری وکتوری (در فصل ۱۵ بررسی می‌شود).
|
||
- فاین‌تیونینگ (Fine-Tuning) مدل‌های زبانی متن‌باز.
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Chat Completions API | وب‌سرویس تکمیل گفتگو | رابط استاندارد ارسال تاریخچه مکالمه به مدل زبانی و دریافت پاسخ متنی هوشمند |
|
||
| System Prompt | پرامپت سیستمی بنیادین | دستورالعمل سطح بالایی که رفتار، هویت، محدودیت‌ها و پایگاه دانش مدل را مشخص می‌کند |
|
||
| Grounding | لنگراندازی داده‌ها | مقید کردن مدل به استفاده انحصاری از اطلاعات و اسناد ارائه شده به جای تکیه بر اطلاعات عمومی |
|
||
| Streaming Response | پاسخ جریانی پیوسته | دریافت توکن‌به‌توکن کلمات مدل از طریق اینترنت برای ایجاد جلوه تایپ زنده بدون معطلی |
|
||
| Prompt Injection | تزریق پرامپت مخرب | ترفند کاربر برای دور زدن قوانین سیستمی مدل از طریق ارسال دستورات فریبکارانه |
|
||
| OpenRouter | روتر باز مدل‌های زبانی | پلتفرم تجمیع‌کننده مدل‌های هوش مصنوعی مختلف با یک رابط یکپارچه و کلید مشترک |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** مغز دیجیتال نئونی درخشان که یک ویجت چت شناور بنفش را روی صفحه سایت پورتفولیو زنده و فعال می‌کند.
|
||
2. **جریان فنی فراخوانی امن چت‌بات در Next.js:** `images/ai-chat-architecture.png`
|
||
* **موضوع:** دیاگرام معماری: کاربر در ویجت تایپ می‌کند $\rightarrow$ روت سرور `/api/chat` کانتکست رزومه را الصاق می‌کند $\rightarrow$ درخواست امن به OpenRouter/AvalAI $\rightarrow$ استریم پاسخ به کلاینت.
|
||
3. **ویجت چت‌بات تعاملی در گوشه پورتفولیو:** `images/portfolio-chat-widget-ui.png`
|
||
* **موضوع:** اسکرین‌شات از ویجت شناور در پورتفولیو با دکمه‌های پیشنهاد سوال سریع ("پروژه‌های شاخص"، "تجربه React"، "تماس با من").
|
||
4. **تکنیک جلوگیری از توهم و تزریق پرامپت:** `images/prompt-guardrails-diagram.png`
|
||
* **موضوع:** اینفوگرافیک محافظتی: تلاش کاربر برای خروج از نقش $\rightarrow$ فیلتر قوانین System Prompt $\rightarrow$ بازگرداندن مودبانه مکالمه به مباحث رزومه.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI`
|
||
2. **مقدمه:** تا پیش از این، با هوش مصنوعی کد می‌نوشتید؛ اکنون وقت آن است که هوش مصنوعی را به عنوان یک کارمند شبانه‌روزی داخل پروژه خود استخدام کنید!
|
||
3. **جدول کاور درس**
|
||
4. **استعاره منشی هوشمند و سخنگوی ۲۴ ساعته شما:**
|
||
* کارفرما ساعت ۲ نیمه‌شب می‌خواهد بداند شما برای پروژه‌اش مناسب هستید یا خیر؛ دستیار رزومه بیدار است و با تسلط کامل پاسخ می‌دهد.
|
||
5. **ساختار Chat Completions در مدل‌های زبانی (Roles: System, User, Assistant):**
|
||
* چگونگی هدایت هوش با تفکیک پیام‌های سه لایه.
|
||
6. **دریافت کلید API از OpenRouter یا سرویس‌های در دسترس داخلی (AvalAI):**
|
||
* ثبت نام سریع، دریافت کلید، و انتخاب مدل‌های مقرون‌به‌صرفه و سریع.
|
||
7. **طراحی پرامپت سیستمی طلایی با تکنیک Grounding:**
|
||
* تزریق رزومه به ساختار پرامپت:
|
||
```markdown
|
||
You are the AI Portfolio Assistant for [Your Name], a Full-Stack Developer.
|
||
Here is the verified knowledge base about the creator:
|
||
- Experience: 3 years building modern web apps with Next.js, TypeScript, Tailwind.
|
||
- Top Projects: 1) Personal Portfolio with Supabase, 2) E-Commerce MVP.
|
||
- Availability: Open for freelance and full-time remote roles.
|
||
Strict Rules:
|
||
1. ONLY answer questions about [Your Name]'s skills, experience, and projects.
|
||
2. If asked about cooking, politics, or unrelated topics, politely decline.
|
||
3. Never invent facts not listed in the knowledge base.
|
||
```
|
||
8. **ساخت روت سرور امن `/api/chat/route.ts` با قابلیت Streaming:**
|
||
* کد تمیز فراخوانی API به صورت استریم برای ایجاد حس پاسخ‌گویی بلادرنگ.
|
||
9. **طراحی کامپوننت ویجت شناور رزومه در فرانت‌اند:**
|
||
* دکمه آیکون چت در گوشه راست پایین، قابلیت مینیمایز، و دکمه‌های سریع (Quick Chips).
|
||
10. **جعبه پرامپت طلایی: ساخت کامل دستیار رزومه با ایجنت:**
|
||
* پرامپت دقیق:
|
||
> «من یک کلید `OPENROUTER_API_KEY` در `.env.local` دارم. لطفاً یک روت سرور `/api/chat` بساز که با مدل `deepseek/deepseek-chat` یا `openai/gpt-4o-mini` ارتباط برقرار کند. پرامپت سیستمی باید اطلاعات رزومه من را به صورت محرمانه در بر بگیرد. سپس یک ویجت چت شناور در پایین صفحه پورتفولیو اضافه کن که تاریخچه پیام‌ها را نمایش دهد، حالت لودینگ داشته باشد و متن پاسخ را به صورت تایپ زنده بنویسد.»
|
||
11. **دستورات چندسکویی برای پیکربندی متغیر محیطی هوش مصنوعی:**
|
||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||
- Windows (PowerShell):
|
||
```powershell
|
||
Add-Content .env.local "`nOPENROUTER_API_KEY=sk-or-v1-your-key-here"
|
||
```
|
||
- macOS (Terminal):
|
||
```bash
|
||
echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local
|
||
```
|
||
- Linux (Bash):
|
||
```bash
|
||
echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local
|
||
```
|
||
12. **باکس نکته امنیتی Quera (`<details class="violet">`):** مقابله با Prompt Injection؛ چرا کلید API هرگز نباید در کلاینت بماند و چطور کدهای مخرب کاربر را خنثی کنیم.
|
||
13. **باکس راهنمای بهینه‌سازی هزینه Quera (`<details class="green">`):** کوتاه کردن هیستوری به ۶ چت آخر برای جلوگیری از هزینه اضافی.
|
||
14. **باکس هشدار Quera (`<details class="red">`):** خطرات توهم مدل؛ حتماً تست کنید که مدل برای شما تخصص‌هایی که ندارید اختراع نکند!
|
||
15. **جمع‌بندی فصل دهم و پیش‌نمایش فصل یازدهم:** جشن اتصال کامل پورتفولیو به پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی؛ ورود به فصل سرنوشت‌ساز یازدهم: امنیت و استفاده مسئولانه.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] تفاوت استفاده از AI به عنوان ابزار با AI به عنوان قابلیت محصول تبیین شود.
|
||
- [ ] ساختار فنی Chat Completions API به همراه نقشه پیام‌های System, User, Assistant تشریح گردد.
|
||
- [ ] تکنیک Grounding برای جلوگیری از توهم در دستیار رزومه پیاده‌سازی شود.
|
||
- [ ] پرامپت ایجنت برای ساخت ویجت شناور چت با قابلیت Streaming در متن قرار گیرد.
|