Web-Dev-For-Beginners/translations/fa/9-chat-project

ساخت یک دستیار چت با هوش مصنوعی

به یاد دارید در فیلم استار ترک وقتی اعضای تیم به طور غیررسمی با کامپیوتر سفینه صحبت می‌کردند، سوالات پیچیده می‌پرسیدند و پاسخ‌های دقیق و هوشمندانه دریافت می‌کردند؟ چیزی که در دهه ۱۹۶۰ صرفاً علمی–تخیلی به نظر می‌رسید، اکنون چیزی است که می‌توانید با استفاده از فناوری‌های وبی که از قبل می‌شناسید بسازید.

در این درس، ما یک دستیار چت هوش مصنوعی با استفاده از HTML، CSS، جاوااسکریپت و مقداری ادغام سمت سرور ایجاد خواهیم کرد. شما کشف خواهید کرد که چگونه مهارت‌های همان‌طور که یاد گرفته‌اید می‌توانند به سرویس‌های قدرتمند هوش مصنوعی متصل شوند که می‌توانند زمینه را درک کنند و پاسخ‌های معناداری تولید کنند.

هوش مصنوعی را مانند دسترسی به یک کتابخانه بزرگ در نظر بگیرید که نه تنها می‌تواند اطلاعات را پیدا کند بلکه آن‌ها را به پاسخ‌های منسجم و متناسب با سوالات خاص شما ترکیب می‌کند. به جای جستجو در هزاران صفحه، پاسخ‌های مستقیم و متنی دریافت می‌کنید.

ادغام از طریق فناوری‌های وب آشنا به صورت همکاری انجام می‌شود. HTML رابط چت را ایجاد می‌کند، CSS طراحی بصری را کنترل می‌کند، جاوااسکریپت تعاملات کاربر را مدیریت می‌کند و یک API سمت سرور همه چیز را به سرویس‌های هوش مصنوعی متصل می‌کند. این شبیه به نحوه همکاری بخش‌های مختلف یک ارکستر برای خلق یک سمفونی است.

ما اساساً در حال ساخت پلی میان ارتباطات طبیعی انسانی و پردازش ماشینی هستیم. شما هم پیاده‌سازی فنی ادغام سرویس هوش مصنوعی و هم الگوهای طراحی را که تعاملات را ملموس و شهودی می‌کند یاد خواهید گرفت.

در پایان این درس، ادغام هوش مصنوعی کمتر مانند یک فرایند مرموز و بیشتر مانند یک API دیگر که می‌توانید با آن کار کنید، حس خواهد شد. شما الگوهای بنیادی که برنامه‌هایی مثل ChatGPT و Claude را راه‌اندازی می‌کنند، با همان اصول توسعه وب که یاد گرفته‌اید، درک خواهید کرد.

⚡ کاری که در ۵ دقیقه آینده می‌توانید انجام دهید

مسیر شروع سریع برای توسعه‌دهندگان پرمشغله

flowchart LR
    A[⚡ ۵ دقیقه] --> B[دریافت توکن گیت‌هاب]
    B --> C[آزمایش محیط بازی هوش مصنوعی]
    C --> D[کپی کد پایتون]
    D --> E[مشاهده پاسخ‌های هوش مصنوعی]

• دقیقه ۱: به GitHub Models Playground مراجعه کنید و یک توکن دسترسی شخصی بسازید
• دقیقه ۲: تعاملات هوش مصنوعی را مستقیماً در رابط محیط بازیابی امتحان کنید
• دقیقه ۳: روی تب "Code" کلیک کرده و قطعه کد پایتون را کپی کنید
• دقیقه ۴: کد را با توکن خود به صورت محلی اجرا کنید: GITHUB_TOKEN=your_token python test.py
• دقیقه ۵: پاسخ اول هوش مصنوعی را که از کد خودتان تولید می‌شود تماشا کنید

کد تست سریع:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key="your_token_here"
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello AI!"}],
    model="openai/gpt-4o-mini"
)

print(response.choices[0].message.content)

چرا این مهم است: در ۵ دقیقه، جادوی تعامل برنامه‌نویسی با هوش مصنوعی را تجربه خواهید کرد. این نمایانگر بلوک پایه‌ای است که هر برنامه هوش مصنوعی که استفاده می‌کنید را تغذیه می‌کند.

پروژه نهایی شما به این شکل خواهد بود:

🗺️ مسیر یادگیری شما در توسعه اپلیکیشن‌های هوش مصنوعی

journey
    title از توسعه وب تا یکپارچه‌سازی هوش مصنوعی
    section درک مبانی هوش مصنوعی
      مفاهیم هوش مصنوعی مولد را کشف کنید: 4: You
      پلتفرم مدل‌های GitHub را بررسی کنید: 6: You
      پارامترها و پرسش‌های هوش مصنوعی را تسلط یابید: 8: You
    section یکپارچه‌سازی بک‌اند
      سرور API پایتون بسازید: 5: You
      فراخوانی توابع هوش مصنوعی را پیاده‌سازی کنید: 7: You
      عملیات‌های ناهمزمان را مدیریت کنید: 8: You
    section توسعه فرانت‌اند
      رابط چت مدرن ایجاد کنید: 6: You
      تعاملات زمان واقعی را تسلط یابید: 8: You
      تجربه کاربری پاسخگو بسازید: 9: You
    section کاربرد حرفه‌ای
      سیستم کامل هوش مصنوعی را مستقر کنید: 7: You
      الگوهای عملکرد را بهینه کنید: 8: You
      اپلیکیشن آماده تولید ایجاد کنید: 9: You

مقصد مسیر شما: تا پایان این درس، یک برنامه کامل مبتنی بر هوش مصنوعی ساخته‌اید که از همان فناوری‌ها و الگوهایی استفاده می‌کند که دستیارهای هوش مصنوعی مدرنی مانند ChatGPT، Claude و Google Bard را تغذیه می‌کنند.

درک هوش مصنوعی: از رمز و راز تا تسلط

پیش از ورود به کد، بیایید بفهمیم با چه چیزی کار می‌کنیم. اگر پیش‌تر از API استفاده کرده‌اید، الگوی اصلی را می‌دانید: درخواست ارسال می‌شود، پاسخ دریافت می‌شود.

APIهای هوش مصنوعی ساختار مشابهی دارند، اما به جای بازیابی داده‌های ذخیره‌شده از یک پایگاه داده، آن‌ها پاسخ‌های جدید را بر اساس الگوهای آموخته‌شده از حجم عظیمی از متن تولید می‌کنند. آن را مانند تفاوت بین سیستم فهرست کتابخانه و یک کتابدار بااطلاعات در نظر بگیرید که می‌تواند اطلاعات را از منابع مختلف ترکیب کند.

واقعاً "هوش مصنوعی مولد" چیست؟

فرض کنید که سنگ روزتا به دانشمندان کمک کرد تا هیروگلیف‌های مصری را با پیدا کردن الگوهایی بین زبان‌های شناخته شده و ناشناخته درک کنند. مدل‌های هوش مصنوعی به همین صورت کار می‌کنند – آن‌ها الگوهایی را در حجم زیادی از متن پیدا می‌کنند تا بفهمند زبان چگونه کار می‌کند، سپس از آن الگوها برای تولید پاسخ‌های مناسب به سوالات جدید استفاده می‌کنند.

اجازه دهید این را با یک مقایسه ساده توضیح دهم:

• پایگاه داده سنتی: مثل درخواست گواهی تولد شما – هر بار دقیقاً همان سند را دریافت می‌کنید
• موتور جستجو: مانند درخواست از یک کتابدار برای یافتن کتاب‌های مربوط به گربه‌ها – آن‌ها آنچه در دسترس است را نشان می‌دهند
• هوش مصنوعی مولد: مثل پرسیدن از دوستی آگاه درباره گربه‌ها – او با کلمات خود چیزهای جالبی می‌گوید که متناسب با چیزی است که می‌خواهید بدانید

graph LR
    A[سؤال شما] --> B[مدل هوش مصنوعی]
    B --> C[شناسایی الگو]
    C --> D[تولید محتوا]
    D --> E[پاسخ با توجه به زمینه]
    
    F[داده‌های آموزش<br/>کتاب‌ها، مقالات، وب] --> B

مدل‌های هوش مصنوعی چگونه یاد می‌گیرند (نسخه ساده)

مدل‌های هوش مصنوعی از قرار گرفتن در معرض مجموعه داده عظیمی شامل متن کتاب‌ها، مقالات و مکالمات یاد می‌گیرند. در این فرآیند، آن‌ها الگوهایی را در موارد زیر شناسایی می‌کنند:

• چگونه افکار در ارتباطات نوشتاری ساختاربندی شده‌اند
• کدام کلمات معمولاً با هم ظاهر می‌شوند
• معمولاً مکالمات چگونه جریان دارند
• تفاوت‌های زمینه‌ای بین ارتباط رسمی و غیررسمی

این مشابه نحوه رمزگشایی زبان‌های باستانی توسط باستان‌شناسان است: آن‌ها هزاران نمونه را تحلیل می‌کنند تا دستور زبان، واژگان و زمینه فرهنگی را بفهمند و در نهایت قادر می‌شوند متن‌های جدید را با استفاده از آن الگوها تفسیر کنند.

چرا GitHub Models؟

ما از GitHub Models به دلیلی کاملاً عملی استفاده می‌کنیم – این سرویس به ما دسترسی به هوش مصنوعی در سطح سازمانی می‌دهد بدون اینکه نیاز باشد زیرساخت هوش مصنوعی خود را راه‌اندازی کنیم (که واقعاً الان نمی‌خواهید این کار را انجام دهید!). آن را مانند استفاده از API هواشناسی در نظر بگیرید به جای آنکه خودتان ایستگاه‌های هواشناسی در همه جا راه‌اندازی کنید و هوا را پیش‌بینی نمایید.

اساساً این "هوش مصنوعی به عنوان سرویس" است و بهترین بخشش؟ شروع کار رایگان است، پس می‌توانید بدون نگرانی از هزینه‌های زیاد آزمایش کنید.

graph LR
    A[رابط کاربری چت فرانت‌اند] --> B[رابط برنامه‌نویسی پشتیبان شما]
    B --> C[رابط برنامه‌نویسی مدل‌های گیت‌هاب]
    C --> D[پردازش مدل هوش مصنوعی]
    D --> C
    C --> B
    B --> A

ما از GitHub Models برای ادغام پشت‌صحنه استفاده خواهیم کرد که دسترسی به قابلیت‌های هوش مصنوعی حرفه‌ای را از طریق یک رابط کاربری مناسب برای توسعه‌دهندگان فراهم می‌کند. GitHub Models Playground به عنوان محیط آزمایش عمل می‌کند که می‌توانید مدل‌های مختلف هوش مصنوعی را امتحان کنید و قابلیت‌های آن‌ها را پیش از پیاده‌سازی در کد درک کنید.

🧠 اکوسیستم توسعه اپلیکیشن‌های هوش مصنوعی

mindmap
  root((توسعه هوش مصنوعی))
    Understanding AI
      Generative Models
        Pattern Recognition [شناسایی الگو]
        Content Generation [تولید محتوا]
        Context Understanding [درک زمینه]
        Response Synthesis [ترکیب پاسخ]
      AI Parameters
        Temperature Control [کنترل دما]
        Token Limits [محدودیت‌های توکن]
        Top-p Filtering [فیلتر کردن Top-p]
        System Prompts [فرمان‌های سیستم]
    Backend Architecture
      API Integration [یکپارچه‌سازی API]
        GitHub Models [مدل‌های گیت‌هاب]
        Authentication [احراز هویت]
        Request Handling [مدیریت درخواست]
        Error Management [مدیریت خطا]
      Python Infrastructure [زیرساخت پایتون]
        FastAPI Framework [چارچوب FastAPI]
        Async Operations [عملیات غیرهم‌زمان]
        Environment Security [امنیت محیط]
        CORS Configuration [پیکربندی CORS]
    Frontend Experience [تجربه فرانت‌اند]
      Chat Interface [رابط گفتگو]
        Real-time Updates [به‌روزرسانی بلادرنگ]
        Message History [تاریخچه پیام‌ها]
        User Feedback [بازخورد کاربران]
        Loading States [وضعیت‌های بارگذاری]
      Modern Web Tech [فناوری‌های نوین وب]
        ES6 Classes [کلاس‌های ES6]
        Async/Await [Async/Await]
        DOM Manipulation [دستکاری DOM]
        Event Handling [مدیریت رویداد]
    Professional Patterns [الگوهای حرفه‌ای]
      Security Best Practices [بهترین روش‌های امنیتی]
        Token Management [مدیریت توکن]
        Input Validation [اعتبارسنجی ورودی]
        XSS Prevention [جلوگیری از XSS]
        Error Boundaries [مرزهای خطا]
      Production Readiness [آمادگی برای تولید]
        Performance Optimization [بهینه‌سازی عملکرد]
        Responsive Design [طراحی واکنش‌گرا]
        Accessibility [دسترسی‌پذیری]
        Testing Strategies [استراتژی‌های تست]

اصل اصلی: توسعه اپلیکیشن‌های هوش مصنوعی ترکیبی از مهارت‌های سنتی توسعه وب با ادغام سرویس‌های هوش مصنوعی است که برنامه‌هایی هوشمند و پاسخگو برای کاربران ایجاد می‌کند.

دلایلی که محیط بازیابی بسیار مفید است:

• آزمایش مدل‌های مختلف هوش مصنوعی مثل GPT-4o-mini، Claude و دیگران (همه رایگان!)
• تست ایده‌ها و درخواست‌های خود قبل از نوشتن کد
• دریافت قطعه کد آماده در زبان برنامه‌نویسی مورد علاقه شما
• تنظیم پارامترهایی مثل سطح خلاقیت و طول پاسخ برای مشاهده تأثیرشان روی خروجی

وقتی بازی کردید، کافی است روی تب "Code" کلیک کنید و زبان برنامه‌نویسی خود را انتخاب کنید تا کد پیاده‌سازی مورد نیاز را دریافت نمایید.

راه‌اندازی ادغام پشت‌صحنه پایتون

حالا بیایید ادغام هوش مصنوعی را با استفاده از پایتون پیاده کنیم. پایتون به دلیل نحو ساده و کتابخانه‌های قدرتمند برای برنامه‌های هوش مصنوعی عالی است. ما با کد موجود در محیط GitHub Models شروع می‌کنیم و سپس آن را به تابعی قابل استفاده مجدد و آماده برای تولید بازنویسی می‌کنیم.

درک پیاده‌سازی پایه

وقتی کد پایتون را از محیط بازیابی می‌گیرید، چیزی شبیه به این خواهید داشت. نگران حجم کد در ابتدا نباشید – بیایید قدم به قدم آن را مرور کنیم:

"""Run this model in Python

> pip install openai
"""
import os
from openai import OpenAI

# برای احراز هویت با مدل، باید یک توکن دسترسی شخصی (PAT) در تنظیمات گیت‌هاب خود ایجاد کنید.
# توکن PAT خود را با دنبال کردن راهنمایی‌های اینجا ایجاد کنید: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key=os.environ["GITHUB_TOKEN"],
)

response = client.chat.completions.create(
    messages=[
        {
            "role": "system",
            "content": "",
        },
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="openai/gpt-4o-mini",
    temperature=1,
    max_tokens=4096,
    top_p=1
)

print(response.choices[0].message.content)

چیزهایی که در این کد اتفاق می‌افتد:

• وارد کردن ابزارهای مورد نیاز: os برای خواندن متغیرهای محیطی و OpenAI برای ارتباط با هوش مصنوعی
• تنظیم کلاینت OpenAI برای اتصال به سرورهای هوش مصنوعی GitHub به جای OpenAI مستقیم
• احراز هویت با استفاده از توکن خاص GitHub (که بعداً توضیح داده می‌شود!)
• سازماندهی مکالمه با نقش‌های مختلف – شبیه تنظیم صحنه برای یک نمایش
• ارسال درخواست به هوش مصنوعی با برخی پارامترهای ظریف‌کننده
• استخراج متن پاسخ واقعی از تمام داده‌هایی که برگشت داده شده است

درک نقش پیام‌ها: چارچوب مکالمه هوش مصنوعی

مکالمات هوش مصنوعی از ساختار خاصی با نقش‌های مختلف استفاده می‌کنند که هرکدام هدف خاصی دارند:

messages=[
    {
        "role": "system",
        "content": "You are a helpful assistant who explains things simply."
    },
    {
        "role": "user", 
        "content": "What is machine learning?"
    }
]

شبیه هدایت یک نمایش است:

• نقش سیستم: مانند دستورالعمل‌های صحنه برای بازیگر – به هوش مصنوعی می‌گوید چگونه رفتار کند، چه شخصیتی داشته باشد و چگونه پاسخ دهد
• نقش کاربر: سوال یا پیام واقعی از فردی که از برنامه شما استفاده می‌کند
• نقش دستیار: پاسخ هوش مصنوعی (شما این را نمی‌فرستید اما در تاریخچه مکالمه ظاهر می‌شود)

مثال دنیای واقعی: فرض کنید به دوستی در یک مهمانی معرفی می‌کنید:

• پیام سیستم: "این دوست من سارا است، یک پزشک که در توضیح مفاهیم پزشکی به زبان ساده بسیار مهارت دارد"
• پیام کاربر: "می‌توانی توضیح بدهی واکسن‌ها چگونه کار می‌کنند؟"
• پاسخ دستیار: سارا به عنوان یک پزشک دوستانه پاسخ می‌دهد، نه یک وکیل یا آشپز

درک پارامترهای هوش مصنوعی: تنظیم دقیق رفتار پاسخ

پارامترهای عددی در فراخوانی API هوش مصنوعی کنترل می‌کنند مدل چگونه پاسخ تولید کند. این تنظیمات به شما اجازه می‌دهند رفتار مدل را برای موارد مختلف استفاده تنظیم کنید:

دما (۰.۰ تا ۲.۰): کنترل درجه خلاقیت

کاربرد آن: کنترل می‌کند پاسخ‌های هوش مصنوعی چقدر خلاقانه یا قابل پیش‌بینی باشد.

آن را مانند سطح بداهه‌نوازی یک نوازنده جاز تصور کنید:

• دمای ۰.۱: اجرای دقیق همان ملودی هر بار (بسیار قابل پیش‌بینی)
• دمای ۰.۷: افزودن برخی تغییرات معقول در حالی که قابل تشخیص باقی می‌ماند (خلاقیت متعادل)
• دمای ۱.۵: اجرای کامل جاز تجربی با پیچ و خم‌های غیرمنتظره (بسیار غیرقابل پیش‌بینی)

# پاسخ‌های بسیار قابل پیش‌بینی (خوب برای سوالات واقعی)
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "What is 2+2?"}],
    temperature=0.1  # تقریباً همیشه "4" خواهد گفت
)

# پاسخ‌های خلاقانه (خوب برای طوفان فکری)
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Write a creative story opening"}],
    temperature=1.2  # داستان‌های منحصربه‌فرد و غیرمنتظره تولید خواهد کرد
)

حداکثر توکن‌ها (۱ تا ۴۰۹۶+): کنترل طول پاسخ

کاربرد آن: محدودیتی برای طول پاسخ هوش مصنوعی تعیین می‌کند.

توکن‌ها تقریباً معادل کلمات هستند (حدود ۱ توکن = ۰.۷۵ کلمه در انگلیسی):

• max_tokens=50: کوتاه و مختصر (مثل یک پیام متنی)
• max_tokens=500: یک پاراگراف یا دو پاراگراف خوب
• max_tokens=2000: توضیح مفصل با مثال‌ها

# پاسخ‌های کوتاه و مختصر
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Explain JavaScript"}],
    max_tokens=100  # وادار کردن به توضیح کوتاه
)

# پاسخ‌های دقیق و جامع
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Explain JavaScript"}],
    max_tokens=1500  # اجازه دادن به توضیحات مفصل با نمونه‌ها
)

top_p (۰.۰ تا ۱.۰): پارامتر تمرکز

کاربرد آن: کنترل می‌کند چقدر مدل بر روی محتمل‌ترین پاسخ‌ها متمرکز باشد.

تصور کنید هوش مصنوعی دارای دایره‌المعارف عظیمی است، رتبه‌بندی شده بر اساس احتمال هر کلمه:

• top_p=0.1: فقط ۱۰٪ بالای کلمات پر احتمال را در نظر می‌گیرد (بسیار متمرکز)
• top_p=0.9: ۹۰٪ کلمات ممکن را در نظر می‌گیرد (خلاق‌تر)
• top_p=1.0: همه چیز را در نظر می‌گیرد (تنوع حداکثری)

مثلاً اگر بپرسید "آسمان معمولاً..."

• top_p کم: تقریباً قطعاً می‌گوید "آبی"
• top_p زیاد: ممکن است بگوید "آبی"، "ابری"، "وسیع"، "در حال تغییر"، "زیبا" و غیره

همه چیز را کنار هم بگذاریم: ترکیب پارامترها برای موارد مختلف استفاده

# برای پاسخ‌های مستند و دقیق (مانند یک بات مستندات)
factual_params = {
    "temperature": 0.2,
    "max_tokens": 300,
    "top_p": 0.3
}

# برای کمک در نوشتن خلاقانه
creative_params = {
    "temperature": 1.1,
    "max_tokens": 1000,
    "top_p": 0.9
}

# برای پاسخ‌های تعاملی و مفید (متعادل)
conversational_params = {
    "temperature": 0.7,
    "max_tokens": 500,
    "top_p": 0.8
}

quadrantChart
    title ماتریس بهینه‌سازی پارامترهای هوش مصنوعی
    x-axis خلاقیت کم --> خلاقیت زیاد
    y-axis پاسخ کوتاه --> پاسخ طولانی
    
    quadrant-1 محتوای خلاقانه
    quadrant-2 تحلیل دقیق
    quadrant-3 حقایق سریع
    quadrant-4 هوش مصنوعی گفتگو محور
    
    Documentation Bot: [0.2, 0.3]
    Customer Service: [0.4, 0.4]
    General Assistant: [0.7, 0.5]
    Creative Writer: [0.9, 0.9]
    Brainstorming Tool: [0.8, 0.8]

چرا این پارامترها اهمیت دارند؟ برنامه‌های مختلف به نوع پاسخ‌های مختلفی نیاز دارند. یک ربات خدمات مشتری باید ثابت و حقیقی (دمای پایین) باشد، در حالی که یک دستیار نوشتاری خلاق باید خیال‌پرداز و متنوع (دمای بالا) باشد. درک این پارامترها به شما کنترل روی شخصیت و سبک پاسخ هوش مصنوعی‌تان می‌دهد.

**Here's what's happening in this code:**
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
- **We authenticate** using a special GitHub token (more on that in a minute!)
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
- **We send** our request to the AI with some fine-tuning parameters
- **We extract** the actual response text from all the data that comes back

> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.

### Creating a Reusable AI Function

Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:

```python
import asyncio
from openai import AsyncOpenAI

# Use AsyncOpenAI for better performance
client = AsyncOpenAI(
    base_url="https://models.github.ai/inference",
    api_key=os.environ["GITHUB_TOKEN"],
)

async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
    """
    Sends a prompt to the AI model asynchronously and returns the response.
    
    Args:
        prompt: The user's question or message
        system_message: Instructions that define the AI's behavior and personality
    
    Returns:
        str: The AI's response to the prompt
    """
    try:
        response = await client.chat.completions.create(
            messages=[
                {
                    "role": "system",
                    "content": system_message,
                },
                {
                    "role": "user",
                    "content": prompt,
                }
            ],
            model="openai/gpt-4o-mini",
            temperature=1,
            max_tokens=4096,
            top_p=1
        )
        return response.choices[0].message.content
    except Exception as e:
        logger.error(f"AI API error: {str(e)}")
        return "I'm sorry, I'm having trouble processing your request right now."

# Backward compatibility function for synchronous calls
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
    """Synchronous wrapper for async AI calls."""
    return asyncio.run(call_llm_async(prompt, system_message))

درک این تابع بهبود یافته:

• دو پارامتر می‌پذیرد: درخواست کاربر و یک پیام سیستم اختیاری
• یک پیام سیستم پیش‌فرض برای رفتار کلی دستیار ارائه می‌دهد
• از راهنمای نوع در پایتون به‌درستی استفاده می‌کند برای مستندسازی بهتر کد
• شامل یک docstring دقیق که هدف تابع و پارامترها را توضیح می‌دهد
• فقط محتوای پاسخ را بازمی‌گرداند که استفاده از آن را در API وب آسان می‌کند
• پارامترهای مدل را ثابت نگه می‌دارد تا رفتار هوش مصنوعی یکنواخت باشد

جادوی پیام‌های سیستم: برنامه‌ریزی شخصیت هوش مصنوعی

اگر پارامترها کنترل می‌کنند هوش مصنوعی چگونه فکر کند، پیام‌های سیستم کنترل می‌کنند که هوش مصنوعی فکر کند که کیست. این یکی از جالب‌ترین بخش‌های کار با هوش مصنوعی است – شما اساساً به هوش مصنوعی یک شخصیت کامل، سطح تخصص و سبک ارتباطی می‌دهید.

پیام‌های سیستم را مانند انتخاب بازیگران مختلف برای نقش‌های مختلف در نظر بگیرید: به جای داشتن یک دستیار عمومی، می‌توانید متخصصان ویژه‌ای برای موقعیت‌های مختلف بسازید. به یک معلم صبور نیاز دارید؟ یک هم‌فکر خلاق؟ یک مشاور جدی تجاری؟ فقط پیام سیستم را تغییر دهید!

چرا پیام‌های سیستم این قدر قدرتمندند

قسمت جذاب این است: مدل‌های هوش مصنوعی روی مکالمات بین افراد زیادی که نقش‌ها و سطوح تخصص متفاوتی را بازی می‌کنند آموزش دیده‌اند. وقتی به هوش مصنوعی نقشی خاص می‌دهید، مانند روشن کردن کلیدی است که تمام آن الگوهای آموخته شده را فعال می‌کند.

این شبیه به بازیگری به سبک متد است: به یک بازیگر بگویید "تو استاد خردمند پیر هستی" و ببینید چگونه به طور خودکار حالت، واژگان و حرکات خود را تنظیم می‌کند. هوش مصنوعی هم کاری بسیار مشابه با الگوهای زبان انجام می‌دهد.

ساخت پیام سیستم مؤثر: هنر و علم

اجزای یک پیام سیستم عالی:

1. نقش/هویت: هوش مصنوعی کیست؟
2. تخصص: چه چیز می‌داند؟
3. سبک ارتباطی: چگونه صحبت می‌کند؟
4. دستورالعمل‌های خاص: باید روی چه چیزی تمرکز کند؟

# ❌ راهنمای سیستم نامشخص
"You are helpful."

# ✅ راهنمای سیستم دقیق و موثر
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."

مثال‌های پیام سیستم با زمینه

ببینیم پیام‌های سیستم مختلف چگونه شخصیت‌های کاملاً متفاوتی برای هوش مصنوعی می‌سازند:

# مثال ۱: معلم صبور
teacher_prompt = """
You are an experienced programming instructor who has taught thousands of students. 
You break down complex concepts into simple steps, use analogies from everyday life, 
and always check if the student understands before moving on. You're encouraging 
and never make students feel bad for not knowing something.
"""

# مثال ۲: همکار خلاق
creative_prompt = """
You are a creative writing partner who loves brainstorming wild ideas. You're 
enthusiastic, imaginative, and always build on the user's ideas rather than 
replacing them. You ask thought-provoking questions to spark creativity and 
offer unexpected perspectives that make stories more interesting.
"""

# مثال ۳: مشاور استراتژیک کسب‌وکار
business_prompt = """
You are a strategic business consultant with an MBA and 20 years of experience 
helping startups scale. You think in frameworks, provide structured advice, 
and always consider both short-term tactics and long-term strategy. You ask 
probing questions to understand the full business context before giving advice.
"""

مشاهده پیام‌های سیستم در عمل

بیایید همان سوال را با پیام‌های سیستم مختلف امتحان کنیم تا تفاوت‌های چشمگیر را ببینیم:

سوال: "چگونه باید احراز هویت کاربر را در اپلیکیشن وب خود مدیریت کنم؟"

# با درخواست معلم:
teacher_response = call_llm(
    "How do I handle user authentication in my web app?",
    teacher_prompt
)
# پاسخ معمول: «سؤال عالی! بیایید احراز هویت را به گام‌های ساده تقسیم کنیم.
# به آن مثل نگهبان باشگاه شبانه فکر کن که کارت‌های شناسایی را بررسی می‌کند...»

# با درخواست کسب‌وکار:
business_response = call_llm(
    "How do I handle user authentication in my web app?", 
    business_prompt
)
# پاسخ معمول: «از دیدگاه استراتژیک، احراز هویت برای اعتماد کاربران و رعایت مقررات حیاتی است.
# اجازه دهید چارچوبی را با در نظر گرفتن امنیت،
# تجربه کاربری و مقیاس‌پذیری ارائه دهم...»

تکنیک‌های پیشرفته پیام سیستم

۱. تنظیم زمینه: به هوش مصنوعی اطلاعات زمینه‌ای بدهید

system_prompt = """
You are helping a junior developer who just started their first job at a startup. 
They know basic HTML/CSS/JavaScript but are new to backend development and databases. 
Be encouraging and explain things step-by-step without being condescending.
"""

۲. قالب‌بندی خروجی: به هوش مصنوعی بگویید پاسخ‌ها را چگونه ساختاربندی کند

system_prompt = """
You are a technical mentor. Always structure your responses as:
1. Quick Answer (1-2 sentences)
2. Detailed Explanation 
3. Code Example
4. Common Pitfalls to Avoid
5. Next Steps for Learning
"""

۳. تعیین محدودیت‌ها: مشخص کنید هوش مصنوعی چه کارهایی نباید انجام دهد

system_prompt = """
You are a coding tutor focused on teaching best practices. Never write complete 
solutions for the user - instead, guide them with hints and questions so they 
learn by doing. Always explain the 'why' behind coding decisions.
"""

چرا این موضوع برای دستیار چت شما مهم است

درک پرامپت‌های سیستمی به شما قدرت فوق‌العاده‌ای می‌دهد تا دستیارهای هوش مصنوعی تخصصی بسازید:

• ربات خدمات مشتری: مفید، صبور، آگاه به سیاست‌ها
• معلم آموزشی: تشویق‌کننده، گام به گام، بررسی فهم
• شریک خلاق: تخیلی، توسعه‌دهنده ایده‌ها، پرسیدن «اگر فلان بود چه می‌شد؟»
• کارشناس فنی: دقیق، جزئیات‌دار، آگاه به امنیت

نکته کلیدی: شما فقط یک API هوش مصنوعی را صدا نمی‌زنید – بلکه یک شخصیت هوش مصنوعی سفارشی ایجاد می‌کنید که کاربرد خاص شما را پشتیبانی می‌کند. این همان چیزی است که برنامه‌های مدرن هوش مصنوعی را کاربرپسند و شخصی‌سازی‌شده می‌سازد، نه کلی و عمومی.

🎯 بررسی آموزشی: برنامه‌نویسی شخصیت هوش مصنوعی

توقف و فکر کنید: شما همین الان یاد گرفتید شخصیت‌های هوش مصنوعی را با پرامپت‌های سیستمی برنامه‌نویسی کنید. این یک مهارت بنیادی در توسعه برنامه‌های مدرن هوش مصنوعی است.

ارزیابی سریع خود:

• می‌توانید تفاوت پرامپت‌های سیستمی و پیام‌های معمولی کاربر را توضیح دهید؟
• تفاوت پارامترهای temperature و top_p چیست؟
• چطور یک پرامپت سیستمی برای یک کاربرد خاص (مثل معلم کدنویسی) می‌سازید؟

ارتباط دنیای واقعی: تکنیک‌های پرامپت سیستمی که آموختید در هر برنامه بزرگ هوش مصنوعی به کار می‌رود – از کمک کدگشایی GitHub Copilot تا رابط مکالمه ChatGPT. شما همان الگوهایی را یاد می‌گیرید که تیم‌های محصول شرکت‌های بزرگ فناوری استفاده می‌کنند.

سؤال چالشی: چگونه شخصیت‌های مختلف هوش مصنوعی را برای انواع کاربران مختلف طراحی می‌کنید (مثلاً مبتدی در مقابل حرفه‌ای)؟ در نظر بگیرید چطور همان مدل هوش مصنوعی می‌تواند با مهندسی پرامپت، مخاطبان متفاوتی را پشتیبانی کند.

ساخت وب API با FastAPI: هاب ارتباطی هوش مصنوعی با عملکرد بالا

حالا بیایید بک‌اندی بسازیم که فرانت‌اند شما را به سرویس‌های هوش مصنوعی متصل کند. ما از FastAPI استفاده می‌کنیم، یک فریمورک مدرن پایتون که در ساخت API برای برنامه‌های هوش مصنوعی بسیار قوی است.

FastAPI مزایای زیادی برای این نوع پروژه دارد: پشتیبانی داخلی از برنامه‌نویسی ناهمزمان برای رسیدگی به درخواست‌های همزمان، تولید مستندات خودکار API و عملکرد عالی. سرور FastAPI شما به عنوان واسطه‌ای عمل می‌کند که درخواست‌ها را از فرانت‌اند دریافت می‌کند، با سرویس‌های هوش مصنوعی ارتباط برقرار می‌کند و پاسخ‌های قالب‌بندی‌شده را بازمی‌گرداند.

چرا FastAPI برای برنامه‌های هوش مصنوعی؟

ممکن است بپرسید: «چرا نمی‌توانم مستقیم از جاوااسکریپت فرانت‌اند AI را صدا بزنم؟» یا «چرا FastAPI به جای Flask یا Django؟» سؤال‌های عالی!

این دلایل باعث می‌شود FastAPI ایده‌آل باشد:

• پیش‌فرض ناهمزمان: می‌تواند درخواست‌های متعددی از هوش مصنوعی را همزمان مدیریت کند بدون اینکه گیر کند
• مستندات خودکار: به /docs بروید و صفحه مستندات زیبا و تعاملی رایگان داشته باشید
• اعتبارسنجی داخلی: خطاها را قبل از ایجاد مشکل تشخیص می‌دهد
• سرعت بسیار بالا: یکی از سریع‌ترین فریم‌ورک‌های پایتون
• پایتون مدرن: از آخرین ویژگی‌ها و قابلیت‌های پایتون استفاده می‌کند

و این هم دلیل نیاز به بک‌اند:

امنیت: کلید API هوش مصنوعی شما مثل رمز عبور است – اگر آن را در جاوااسکریپت فرانت‌اند قرار دهید، هرکسی که کد منبع سایت شما را ببیند می‌تواند آن را بدزدد و اعتبار هوش مصنوعی شما را مصرف کند. بک‌اند این اطلاعات حساس را امن نگه می‌دارد.

محدودیت نرخ و کنترل: بک‌اند به شما امکان می‌دهد کنترل کنید هر کاربر چند بار می‌تواند درخواست ارسال کند، احراز هویت کاربران را پیاده‌سازی کنید و لاگ‌هایی برای ردیابی مصرف بسازید.

پردازش داده: ممکن است بخواهید گفتگوها را ذخیره کنید، محتوای نامناسب را فیلتر کنید یا چند سرویس هوش مصنوعی را ترکیب کنید. این منطق در بک‌اند انجام می‌شود.

معماری شبیه مدل کلاینت-سرور است:

• فرانت‌اند: لایه رابط کاربری برای تعامل
• API بک‌اند: لایه پردازش و مسیریابی درخواست‌ها
• سرویس هوش مصنوعی: محاسبات بیرونی و تولید پاسخ
• متغیرهای محیطی: پیکربندی و ذخیره امن اطلاعات حساس

درک جریان درخواست-پاسخ

بیایید ببینیم وقتی کاربر پیامی ارسال می‌کند چه اتفاقی می‌افتد:

sequenceDiagram
    participant User as 👤 کاربر
    participant Frontend as 🌐 فرانت‌اند
    participant API as 🔧 سرور FastAPI
    participant AI as 🤖 سرویس هوش مصنوعی
    
    User->>Frontend: تایپ می‌کند "سلام هوش مصنوعی!"
    Frontend->>API: ارسال POST /hello {"message": "سلام هوش مصنوعی!"}
    Note over API: درخواست را اعتبارسنجی می‌کند<br/>پرامپت سیستم را اضافه می‌کند
    API->>AI: ارسال درخواست فرمت شده
    AI->>API: پاسخ هوش مصنوعی را بازمی‌گرداند
    Note over API: پاسخ را پردازش می‌کند<br/>گفتگو را لاگ می‌کند
    API->>Frontend: {"response": "سلام! چطور می‌توانم کمک کنم؟"}
    Frontend->>User: نمایش پیام هوش مصنوعی

درک هر مرحله:
۱. تعامل کاربر: فرد در رابط چت تایپ می‌کند
۲. پردازش فرانت‌اند: جاوااسکریپت ورودی را گرفته و به صورت JSON قالب‌بندی می‌کند
۳. اعتبارسنجی API: FastAPI به طور خودکار درخواست را با مدل‌های Pydantic اعتبارسنجی می‌کند
۴. ادغام هوش مصنوعی: بک‌اند متن زمینه (پرامپت سیستمی) را اضافه و سرویس هوش مصنوعی را فراخوانی می‌کند
۵. پردازش پاسخ: API پاسخ هوش مصنوعی را دریافت می‌کند و در صورت نیاز آن را تغییر می‌دهد
۶. نمایش فرانت‌اند: جاوااسکریپت پاسخ را در رابط چت نشان می‌دهد

درک معماری API

sequenceDiagram
    participant Frontend
    participant FastAPI
    participant AI Function
    participant GitHub Models
    
    Frontend->>FastAPI: POST /hello {"پیغام": "سلام هوش مصنوعی!"}
    FastAPI->>AI Function: call_llm(پیغام, دستور_سیستم)
    AI Function->>GitHub Models: درخواست API
    GitHub Models->>AI Function: پاسخ هوش مصنوعی
    AI Function->>FastAPI: متن پاسخ
    FastAPI->>Frontend: {"پاسخ": "سلام! چطور می‌توانم کمک کنم؟"}

flowchart TD
    A[ورودی کاربر] --> B[اعتبارسنجی فرانت‌اند]
    B --> C[درخواست HTTP POST]
    C --> D[روتر FastAPI]
    D --> E[اعتبارسنجی Pydantic]
    E --> F[فراخوانی تابع AI]
    F --> G[API مدل‌های GitHub]
    G --> H[پردازش پاسخ]
    H --> I[پاسخ JSON]
    I --> J[به‌روزرسانی فرانت‌اند]
    
    subgraph "لایه امنیتی"
        K[میان‌افزار CORS]
        L[متغیرهای محیطی]
        M[مدیریت خطا]
    end
    
    D --> K
    F --> L
    H --> M

ساخت برنامه FastAPI

بیایید API خود را مرحله به مرحله بسازیم. فایلی به نام api.py ایجاد کنید و کد FastAPI زیر را در آن قرار دهید:

# api.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from llm import call_llm
import logging

# پیکربندی لاگ‌برداری
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# ایجاد برنامه FastAPI
app = FastAPI(
    title="AI Chat API",
    description="A high-performance API for AI-powered chat applications",
    version="1.0.0"
)

# پیکربندی CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # پیکربندی مناسب برای محیط تولید
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# مدل‌های Pydantic برای اعتبارسنجی درخواست/پاسخ
class ChatMessage(BaseModel):
    message: str

class ChatResponse(BaseModel):
    response: str

@app.get("/")
async def root():
    """Root endpoint providing API information."""
    return {
        "message": "Welcome to the AI Chat API",
        "docs": "/docs",
        "health": "/health"
    }

@app.get("/health")
async def health_check():
    """Health check endpoint."""
    return {"status": "healthy", "service": "ai-chat-api"}

@app.post("/hello", response_model=ChatResponse)
async def chat_endpoint(chat_message: ChatMessage):
    """Main chat endpoint that processes messages and returns AI responses."""
    try:
        # استخراج و اعتبارسنجی پیام
        message = chat_message.message.strip()
        if not message:
            raise HTTPException(status_code=400, detail="Message cannot be empty")
        
        logger.info(f"Processing message: {message[:50]}...")
        
        # فراخوانی سرویس هوش مصنوعی (توجه: call_llm باید به صورت async نوشته شود برای عملکرد بهتر)
        ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
        
        logger.info("AI response generated successfully")
        return ChatResponse(response=ai_response)
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error processing chat message: {str(e)}")
        raise HTTPException(status_code=500, detail="Internal server error")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)

درک اجرای FastAPI:

• وارد کردن FastAPI برای امکانات فریمورک وب مدرن و Pydantic برای اعتبارسنجی داده‌ها
• ایجاد مستندات خودکار API (در /docs زمانی که سرور اجرا شود)
• فعال کردن middleware CORS برای اجازه درخواست‌های فرانت‌اند از مبداهای مختلف
• تعریف مدل‌های Pydantic برای اعتبارسنجی خودکار درخواست/پاسخ و مستندسازی
• استفاده از نقاط پایانی async برای عملکرد بهتر با درخواست‌های همزمان
• پیاده‌سازی کدهای وضعیت HTTP مناسب و مدیریت خطا با HTTPException
• شامل کردن لاگ‌گیری ساختاریافته برای نظارت و رفع اشکال
• ارائه نقطه انتهایی بررسی سلامت برای نظارت بر وضعیت سرویس

مزایای کلیدی FastAPI نسبت به فریمورک‌های سنتی:

• اعتبارسنجی خودکار: مدل‌های Pydantic صحت داده را قبل از پردازش تضمین می‌کنند
• مستندات تعاملی: به /docs بروید برای مستندات خودکار و قابل آزمایش API
• امنیت نوع: هینت‌های نوع پایتون خطاهای زمان اجرا را کاهش می‌دهند و کیفیت کد را بهبود می‌بخشند
• پشتیبانی async: تعداد زیادی درخواست هوش مصنوعی را بدون مسدود شدن همزمان مدیریت کنید
• عملکرد بالا: پردازش درخواست‌ها را به شکل چشمگیری برای برنامه‌های بلادرنگ سریع‌تر می‌کند

درک CORS: نگهبان امنیتی وب

CORS (Cross-Origin Resource Sharing) مثل نگهبان امنیتی ساختمان است که بررسی می‌کند آیا بازدیدکنندگان اجازه ورود دارند یا نه. بیایید بفهمیم چرا این مهم است و چگونه روی برنامه شما تأثیر می‌گذارد.

CORS چیست و چرا وجود دارد؟

مشکل: فرض کنید هر وب‌سایتی بتواند بدون اجازه شما از طرف شما به سایت بانک‌تان درخواست بفرستد. کابوس امنیتی خواهد بود! مرورگرها این موضوع را به طور پیش‌فرض با «سیاست مبدأ یکسان» جلوگیری می‌کنند.

سیاست مبدأ یکسان: مرورگرها فقط اجازه می‌دهند صفحات وب به دامنه، پورت و پروتکلی که از آن بارگذاری شده‌اند درخواست بفرستند.

تشبیه در دنیای واقعی: مثل امنیت آپارتمان است – فقط ساکنین (مبدأ یکسان) می‌توانند وارد شوند. اگر می‌خواهید دوستی (مبدأ متفاوت) بیاید، باید به نگهبانی بگویید که اشکالی ندارد.

CORS در محیط توسعه شما

در حین توسعه، فرانت‌اند و بک‌اند روی پورت‌های متفاوت اجرا می‌شوند:

• فرانت‌اند: http://localhost:3000 (یا file:// اگر HTML را مستقیم باز کنید)
• بک‌اند: http://localhost:5000

اینها «مبادی متفاوت» محسوب می‌شوند حتی اگر روی همان کامپیوتر باشند!

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(__name__)
CORS(app)   # این به مرورگرها می‌گوید: "ارسال درخواست از سوی مبداهای دیگر به این API مجاز است"

پیکربندی CORS در عمل:

• افزودن هدرهای HTTP خاص به پاسخ‌های API که به مرورگر می‌گوید «این درخواست از مبدأ متفاوت مجاز است»
• مدیریت درخواست‌های پیش‌پرواز (مرورگرها گاهی قبل از ارسال درخواست اصلی مجوز می‌گیرند)
• جلوگیری از خطای ترسناک «مسدود شده توسط سیاست CORS» در کنسول مرورگر شما

امنیت CORS: توسعه در مقابل تولید

# 🚨 توسعه: اجازه دادن به تمام مبدأها (راحت اما ناامن)
CORS(app)

# ✅ تولید: فقط اجازه دادن به دامنه فرانت‌اند خاص خودتان
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])

# 🔒 پیشرفته: مبدأهای مختلف برای محیط‌های مختلف
if app.debug:  # حالت توسعه
    CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else:  # حالت تولید
    CORS(app, origins=["https://yourdomain.com"])

چرا مهم است: در توسعه، CORS(app) مثل باز گذاشتن در جلوی خانه است – راحت اما ناامن. در تولید باید دقیقاً مشخص کنید کدام وب‌سایت‌ها می‌توانند با API شما ارتباط برقرار کنند.

سناریوها و راه‌حل‌های رایج CORS

سناریو	مشکل	راه‌حل
توسعه محلی	فرانت‌اند به بک‌اند نمی‌رسد	افزودن CORSMiddleware به FastAPI
GitHub Pages + Heroku	فرانت‌اند منتشرشده به API دسترسی ندارد	آدرس GitHub Pages خود را به مبادی CORS اضافه کنید
دامنه سفارشی	خطاهای CORS در تولید	مبادی CORS را برای دامنه خود به‌روز کنید
اپلیکیشن موبایل	اپلیکیشن به وب API نمی‌رسد	دامنه اپلیکیشن خود را اضافه کنید یا * را با دقت استفاده کنید

نکته حرفه‌ای: می‌توانید هدرهای CORS را در ابزارهای توسعه مرورگر، زیر تب «شبکه» بررسی کنید. به دنبال هدرهایی مانند Access-Control-Allow-Origin در پاسخ باشید.

مدیریت خطا و اعتبارسنجی

ببینید چطور API ما مدیریت خطا را به خوبی انجام می‌دهد:

# بررسی کنید که پیامی دریافت کرده‌ایم
if not message:
    return jsonify({"error": "Message field is required"}), 400

اصول کلیدی اعتبارسنجی:

• بررسی فیلدهای مورد نیاز قبل از پردازش درخواست‌ها
• برگرداندن پیام‌های خطای معنی‌دار در قالب JSON
• استفاده از کدهای وضعیت HTTP مناسب (۴۰۰ برای درخواست‌های نادرست)
• ارائه بازخورد شفاف برای کمک به توسعه‌دهندگان فرانت‌اند در رفع اشکال

راه‌اندازی و اجرای بک‌اند شما

حالا که ادغام هوش مصنوعی و سرور FastAPI آماده است، بیایید همه چیز را اجرا کنیم. فرآیند راه‌اندازی شامل نصب وابستگی‌های پایتون، پیکربندی متغیرهای محیطی و شروع سرور توسعه می‌شود.

راه‌اندازی محیط پایتون

بیایید محیط توسعه پایتون شما را آماده کنیم. محیط‌های مجازی مثل پروژه منهتن هستند که هر پروژه فضای جدا و ابزارهای مخصوص خود را دارد، جلوگیری از تداخل وابستگی‌ها بین پروژه‌ها.

# به دایرکتوری بک‌اند خود بروید
cd backend

# یک محیط مجازی بسازید (مانند ایجاد یک اتاق تمیز برای پروژه‌تان)
python -m venv venv

# آن را فعال کنید (لینوکسی/مک)
source ./venv/bin/activate

# در ویندوز، استفاده کنید:
# venv\Scripts\activate

# چیزهای مفید را نصب کنید
pip install openai fastapi uvicorn python-dotenv

کارهایی که انجام دادیم:

• ایجاد حباب کوچکی از پایتون که بتوانیم بسته‌ها را بدون تأثیر روی بقیه نصب کنیم
• فعال کردن آن تا ترمینال بداند باید این محیط خاص را استفاده کند
• نصب ضروریات: OpenAI برای جادوی هوش مصنوعی، FastAPI برای API وب، Uvicorn برای اجرای آن و python-dotenv برای مدیریت امن اسرار

وابستگی‌های کلیدی:

• FastAPI: فریمورک وب مدرن و سریع با مستندات خودکار API
• Uvicorn: سرور ASGI بسیار سریع که برنامه‌های FastAPI را اجرا می‌کند
• OpenAI: کتابخانه رسمی برای مدل‌های GitHub و API OpenAI
• python-dotenv: بارگذاری امن متغیرهای محیطی از فایل‌های .env

پیکربندی محیط: حفظ اسرار امن

قبل از شروع API، باید درباره یکی از مهم‌ترین درس‌های توسعه وب صحبت کنیم: چگونه رمزهای خود را واقعاً محرمانه نگه داریم. متغیرهای محیطی مثل صندوق امانت امن هستند که فقط برنامه شما به آن دسترسی دارد.

متغیرهای محیطی چیست؟

به متغیرهای محیطی مثل یک گاوصندوق فکر کنید – ارزشمندهای خود را داخل آن می‌گذارید و فقط شما (و برنامه‌تان) کلید بیرون آوردن آن را دارید. به جای اینکه اطلاعات حساس را مستقیم در کد بنویسید (که هرکسی می‌بیند)، آن را در محیط ذخیره می‌کنید.

این تفاوت است:

• راه اشتباه: نوشتن رمز عبور روی برچسب و چسباندن به مانیتور
• راه درست: نگه داشتن رمز عبور در مدیریت‌کننده رمز عبور امن که فقط شما دسترسی دارید

چرا متغیرهای محیطی مهمند

# 🚨 هرگز این کار را نکنید - کلید API برای همه قابل مشاهده است
client = OpenAI(
    api_key="ghp_1234567890abcdef...",  # هر کسی می‌تواند این را سرقت کند!
    base_url="https://models.github.ai/inference"
)

# ✅ این کار را انجام دهید - کلید API به صورت امن ذخیره شده است
client = OpenAI(
    api_key=os.environ["GITHUB_TOKEN"],  # فقط برنامه‌ی شما می‌تواند به این دسترسی داشته باشد
    base_url="https://models.github.ai/inference"
)

وقتی رموز را در کد می‌نویسید چه می‌شود:
۱. افشای کنترل نسخه: هرکسی که به مخزن گیت شما دسترسی دارد کلید API شما را می‌بیند
۲. مخازن عمومی: اگر به گیت‌هاب پوش کنید، کلید شما برای کل اینترنت قابل دیدن است
۳. اشتراک‌گذاری تیمی: توسعه‌دهندگان دیگر پروژه به کلید شخصی شما دسترسی پیدا می‌کنند
۴. نقض امنیت: اگر کسی کلید API شما را بدزدد، می‌تواند اعتبار هوش مصنوعی شما را مصرف کند

راه‌اندازی فایل محیطی شما

یک فایل .env در دایرکتوری بک‌اند بسازید. این فایل اسرار شما را به صورت محلی ذخیره می‌کند:

# فایل .env - این هرگز نباید به گیت کامیت شود
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development

درک فایل .env:

• یک راز در هر خط به فرمت KEY=value
• بدون فضای خالی اطراف علامت مساوی
• معمولاً بدون نقل قول برای مقادیر
• کامنت‌ها با # شروع می‌شوند

ساخت توکن دسترسی شخصی GitHub

توکن GitHub شما مثل رمز عبور ویژه‌ای است که اجازه می‌دهد برنامه‌تان از سرویس‌های هوش مصنوعی GitHub استفاده کند:

مرحله به مرحله ساخت توکن:
۱. به تنظیمات GitHub → تنظیمات توسعه‌دهنده → توکن‌های دسترسی شخصی → توکن‌ها (کلاسیک) بروید
۲. روی «Generate new token (classic)» کلیک کنید
۳. تاریخ انقضا تنظیم کنید (۳۰ روز برای تست، زمان طولانی‌تر برای تولید)
۴. اسکوب‌ها را انتخاب کنید: «repo» و هر مجوز مورد نیاز دیگر را علامت بزنید
۵. توکن را تولید کنید و فوراً کپی کنید (دیگر دیده نمی‌شود!)
۶. آن را در فایل .env خود جای‌گذاری کنید

# نمونه‌ای از شکل توکن شما (این جعلی است!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R

بارگذاری متغیرهای محیطی در پایتون

import os
from dotenv import load_dotenv

# بارگذاری متغیرهای محیطی از فایل .env
load_dotenv()

# اکنون می‌توانید به‌صورت امن به آن‌ها دسترسی داشته باشید
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
    raise ValueError("GITHUB_TOKEN not found in environment variables!")

client = OpenAI(
    api_key=api_key,
    base_url="https://models.github.ai/inference"
)

این کد چه می‌کند:

• فایل .env شما را بارگذاری می‌کند و متغیرها را در دسترس پایتون قرار می‌دهد
• بررسی می‌کند که توکن مورد نیاز موجود است (مدیریت خطای خوب!)
• اگر توکن نبود خطای واضحی ایجاد می‌کند
• توکن را به صورت امن بدون افشا در کد استفاده می‌کند

امنیت گیت: فایل .gitignore

فایل .gitignore به گیت می‌گوید کدام فایل‌ها را هرگز پیگیری یا آپلود نکند:

# این خطوط را به .gitignore اضافه کنید.
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/

چرا این مهم است: وقتی .env را به .gitignore اضافه می‌کنید، گیت فایل محیطی شما را نادیده می‌گیرد و از بارگذاری ناخواسته اسرار به GitHub جلوگیری می‌کند.

محیط‌های مختلف، اسرار مختلف

برنامه‌های حرفه‌ای از کلیدهای API جداگانه برای محیط‌های مختلف استفاده می‌کنند:

# توسعه .env.
GITHUB_TOKEN=your_development_token
DEBUG=True

# تولید .env.
GITHUB_TOKEN=your_production_token
DEBUG=False

چرا این مهم است: نمی‌خواهید آزمایش‌های توسعه روی سهمیه هوش مصنوعی تولید شما تأثیر بگذارد، و سطوح امنیتی متفاوتی برای محیط‌های مختلف لازم دارید.

راه‌اندازی سرور توسعه: زنده کردن FastAPI شما

اکنون لحظه هیجان‌انگیز فرا می‌رسد – راه‌اندازی سرور توسعه FastAPI و دیدن عملی شدن ادغام هوش مصنوعی شما! FastAPI از Uvicorn استفاده می‌کند، یک سرور ASGI بسیار سریع که به‌صورت خاص برای برنامه‌های پایتون ناهمگام طراحی شده است.

درک فرآیند راه‌اندازی سرور FastAPI

# روش ۱: اجرای مستقیم پایتون (شامل بارگذاری مجدد خودکار)
python api.py

# روش ۲: استفاده مستقیم از Uvicorn (کنترل بیشتر)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload

هنگامی که این فرمان را اجرا می‌کنید، پشت صحنه چه اتفاقی می‌افتد:

1. پایتون برنامه FastAPI شما را بارگذاری می‌کند:

• وارد کردن تمام کتابخانه‌های مورد نیاز (FastAPI، Pydantic، OpenAI و غیره)
• بارگذاری متغیرهای محیطی از فایل .env شما
• ایجاد نمونه برنامه FastAPI با مستندات خودکار

2. Uvicorn سرور ASGI را تنظیم می‌کند:

• اتصال به پورت ۵۰۰۰ با قابلیت‌های پردازش درخواست‌های ناهمگام
• تنظیم مسیرهای درخواست با اعتبارسنجی خودکار
• فعال‌سازی بارگذاری مجدد داغ برای توسعه (راه‌اندازی مجدد در تغییر فایل‌ها)
• تولید مستندات تعاملی API

3. سرور شروع به گوش دادن می‌کند:

• ترمینال شما نمایش می‌دهد: INFO: Uvicorn running on http://0.0.0.0:5000
• سرور می‌تواند درخواست‌های همزمان چندگانه AI را مدیریت کند
• API شما آماده است با مستندات خودکار در http://localhost:5000/docs

آنچه هنگام کارکرد صحیح باید ببینید

$ python api.py
INFO:     Will watch for changes in these directories: ['/your/project/path']
INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

درک خروجی FastAPI:

• Will watch for changes: بارگذاری مجدد خودکار برای توسعه فعال است
• Uvicorn running: سرور ASGI با عملکرد بالا فعال است
• Started reloader process: ناظر فایل برای راه‌اندازی مجدد خودکار
• Application startup complete: برنامه FastAPI با موفقیت راه‌اندازی شد
• Interactive docs available: به /docs مراجعه کنید برای مستندات خودکار API

تست FastAPI: چند روش قدرتمند

FastAPI راه‌های متعددی برای تست API شما فراهم می‌کند، از جمله مستندات تعاملی خودکار:

روش ۱: مستندات تعاملی API (توصیه شده)

1. مرورگر خود را باز کرده و به http://localhost:5000/docs بروید
2. رابط Swagger UI با تمام نقاط پایان شما نمایش داده می‌شود
3. روی /hello کلیک کنید → "Try it out" → پیام آزمایشی وارد کنید → "Execute"
4. پاسخ را مستقیماً در مرورگر با قالب‌بندی مناسب مشاهده کنید

روش ۲: تست ساده با مرورگر

1. به http://localhost:5000 برای نقطه پایان ریشه بروید
2. به http://localhost:5000/health بروید تا سلامت سرور را بررسی کنید
3. این اطمینان می‌دهد سرور FastAPI شما به درستی اجرا شده است

روش ۲: تست خط فرمان (پیشرفته)

# آزمایش با curl (در صورت موجود بودن)
curl -X POST http://localhost:5000/hello \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello AI!"}'

# پاسخ مورد انتظار:
# {"response": "سلام! من دستیار هوش مصنوعی شما هستم. امروز چگونه می‌توانم به شما کمک کنم؟"}

روش ۳: اسکریپت تست پایتون

# test_api.py - فایل را برای تست API خود ایجاد کنید
import requests
import json

# نقطه پایان API را تست کنید
url = "http://localhost:5000/hello"
data = {"message": "Tell me a joke about programming"}

response = requests.post(url, json=data)
if response.status_code == 200:
    result = response.json()
    print("AI Response:", result['response'])
else:
    print("Error:", response.status_code, response.text)

رفع اشکال مشکلات رایج در راه‌اندازی

پیام خطا	معنی	راه حل
ModuleNotFoundError: No module named 'fastapi'	FastAPI نصب نشده است	در محیط مجازی خود pip install fastapi uvicorn را اجرا کنید
ModuleNotFoundError: No module named 'uvicorn'	سرور ASGI نصب نشده است	در محیط مجازی خود pip install uvicorn را اجرا کنید
KeyError: 'GITHUB_TOKEN'	متغیر محیطی یافت نشد	فایل .env و فراخوانی load_dotenv() را بررسی کنید
Address already in use	پورت ۵۰۰۰ مشغول است	روندهای دیگر استفاده‌کننده از پورت ۵۰۰۰ را متوقف کنید یا پورت را تغییر دهید
ValidationError	داده درخواست با مدل Pydantic مطابقت ندارد	فرمت درخواست خود را بررسی کنید که مطابق با اسکیمای مورد انتظار باشد
HTTPException 422	موجودیت پردازش‌ناشدنی	اعتبارسنجی درخواست شکست خورده، قالب صحیح را در /docs چک کنید
OpenAI API error	احراز هویت سرویس هوش مصنوعی شکست خورده است	مطمئن شوید توکن GitHub شما صحیح است و مجوزهای لازم را دارد

بهترین شیوه‌های توسعه

بارگذاری مجدد داغ: FastAPI با Uvicorn بارگذاری مجدد خودکار را هنگام ذخیره تغییرات در فایل‌های پایتون فراهم می‌کند. این یعنی می‌توانید کد را تغییر دهید و فوراً تست کنید بدون راه‌اندازی مجدد دستی.

# فعال‌سازی صریح بارگذاری مجدد سریع
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)  # debug=True بارگذاری مجدد سریع را فعال می‌کند

ثبت لاگ برای توسعه: برای درک اتفاقات، لاگ اضافه کنید:

import logging

# تنظیم لاگ‌گیری
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.route("/hello", methods=["POST"])
def hello():
    data = request.get_json()
    message = data.get("message", "")
    
    logger.info(f"Received message: {message}")
    
    if not message:
        logger.warning("Empty message received")
        return jsonify({"error": "Message field is required"}), 400
    
    try:
        response = call_llm(message, "You are a helpful and friendly assistant.")
        logger.info(f"AI response generated successfully")
        return jsonify({"response": response})
    except Exception as e:
        logger.error(f"AI API error: {str(e)}")
        return jsonify({"error": "AI service temporarily unavailable"}), 500

چرا لاگ مفید است: در طول توسعه، دقیقا می‌توانید ببینید چه درخواست‌هایی دریافت می‌شود، هوش مصنوعی چگونه پاسخ می‌دهد و خطاها کجا رخ می‌دهند. این باعث اشکال‌زدایی سریع‌تر می‌شود.

پیکربندی برای GitHub Codespaces: توسعه ابری آسان

GitHub Codespaces مثل داشتن یک کامپیوتر توسعه قدرتمند در ابر است که می‌توانید از هر مرورگری به آن دسترسی داشته باشید. اگر در Codespaces کار می‌کنید، چند گام اضافی وجود دارد تا backend شما برای frontend قابل دسترس شود.

درک شبکه‌بندی Codespaces

در محیط توسعه محلی، همه چیز روی همان کامپیوتر اجرا می‌شود:

• Backend: http://localhost:5000
• Frontend: http://localhost:3000 (یا file://)

در Codespaces، محیط توسعه شما روی سرورهای GitHub اجرا می‌شود، بنابراین "localhost" معنای متفاوتی دارد. GitHub خودکار URLهای عمومی برای سرویس‌های شما می‌سازد، اما باید آنها را درست پیکربندی کنید.

پیکربندی گام به گام Codespaces

1. سرور backend خود را راه‌اندازی کنید:

cd backend
python api.py

پیغام راه‌اندازی آشنا FastAPI/Uvicorn را مشاهده خواهید کرد، اما توجه داشته باشید که در محیط Codespace اجرا می‌شود.

۲. قابل مشاهده بودن پورت را تنظیم کنید:

• به برگه "Ports" در پنل پایین VS Code نگاه کنید
• پورت ۵۰۰۰ را در لیست پیدا کنید
• روی پورت ۵۰۰۰ راست‌کلیک کنید
• "Port Visibility" → "Public" را انتخاب کنید

چرا عمومی کنیم؟ به طور پیش‌فرض، پورت‌های Codespace خصوصی هستند (فقط شما قابل دسترسید). عمومی کردن پورت به frontend شما (که در مرورگر اجرا می‌شود) اجازه می‌دهد با backend ارتباط برقرار کند.

۳. URL عمومی خود را دریافت کنید: پس از عمومی کردن پورت، URLای شبیه به این خواهید دید:

https://your-codespace-name-5000.app.github.dev

۴. پیکربندی frontend خود را به‌روزرسانی کنید:

// در فایل app.js فرانت‌اند خود، BASE_URL را بروزرسانی کنید:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";

درک URLهای Codespace

URLهای Codespace الگوی مشخصی دارند:

https://[codespace-name]-[port].app.github.dev

تفسیر این موارد:

• codespace-name: شناسه منحصر‌به‌فرد Codespace شما (معمولاً شامل نام کاربری)
• port: شماره پورتی است که سرویس شما روی آن اجرا می‌شود (۵۰۰۰ برای برنامه FastAPI ما)
• app.github.dev: دامنه GitHub برای برنامه‌های Codespace

تست تنظیمات Codespace خود

۱. backend را مستقیماً تست کنید: URL عمومی خود را در یک تب جدید مرورگر باز کنید. باید ببینید:

Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.

۲. تست با ابزارهای توسعه‌دهنده مرورگر:

// کنسول مرورگر را باز کنید و API خود را آزمایش کنید
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({message: 'Hello from Codespaces!'})
})
.then(response => response.json())
.then(data => console.log(data));

تفاوت Codespaces و توسعه محلی

جنبه	توسعه محلی	GitHub Codespaces
زمان راه‌اندازی	طولانی‌تر (نصب پایتون، وابستگی‌ها)	فوری (محیط پیش‌پیکربندی شده)
دسترسی URL	http://localhost:5000	https://xyz-5000.app.github.dev
پیکربندی پورت	خودکار	دستی (عمومی کردن پورت‌ها)
پایداری فایل‌ها	دستگاه محلی	مخزن GitHub
همکاری	به اشتراک‌گذاری محیط دشوار است	به اشتراک‌گذاری لینک Codespace آسان است
وابستگی به اینترنت	فقط برای تماس‌های API هوش مصنوعی	برای همه چیز لازم است

نکات توسعه در Codespace

متغیرهای محیطی در Codespaces: فایل .env شما دقیقا مانند Codespaceهای محلی کار می‌کند، اما می‌توانید متغیرهای محیطی را مستقیماً در Codespace نیز تنظیم کنید:

# تنظیم متغیر محیطی برای نشست فعلی
export GITHUB_TOKEN="your_token_here"

# یا برای حفظ تغییرات به فایل .bashrc خود اضافه کنید
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc

مدیریت پورت:

• Codespaces به طور خودکار هنگام شروع گوش دادن برنامه روی پورت، آن را تشخیص می‌دهد
• می‌توانید چندین پورت را همزمان فوروارد کنید (مفید اگر بعدا دیتابیس اضافه کنید)
• پورت‌ها تا زمانی که Codespace شما اجرا می‌شود، قابل دسترس باقی می‌مانند

گردش کار توسعه:

1. تغییرات کد را در VS Code انجام دهید
2. FastAPI به طور خودکار بارگذاری مجدد می‌شود (به لطف حالت reload در Uvicorn)
3. بلافاصله از طریق URL عمومی تغییرات را تست کنید
4. پس از آماده شدن، کامیت و پوش کنید

💡 نکته حرفه‌ای: در طول توسعه، آدرس backend Codespace خود را نشانه‌گذاری کنید. از آنجا که نام Codespaceها ثابت است، URL تغییر نمی‌کند تا زمانی که از همان Codespace استفاده می‌کنید.

ساخت رابط چت فرانت‌اند: جایی که انسان‌ها با هوش مصنوعی ملاقات می‌کنند

اکنون رابط کاربری را می‌سازیم – قسمتی که تعیین می‌کند مردم چگونه با دستیار هوش مصنوعی شما تعامل کنند. مثل طراحی رابط اصلی آیفون، تمرکز ما بر این است که فناوری پیچیده به صورت شهودی و طبیعی برای استفاده احساس شود.

درک معماری مدرن فرانت‌اند

رابط چت ما یک "برنامه تک صفحه‌ای" یا SPA خواهد بود. به جای روش قدیمی که هر کلیک صفحه جدیدی را بارگذاری می‌کرد، اپ ما به صورت نرم و فوری به‌روزرسانی می‌شود:

وب‌سایت‌های قدیمی: شبیه خواندن یک کتاب فیزیکی – صفحه به صفحه ورق می‌زنید
اپ چت ما: شبیه استفاده از گوشی – همه چیز روان و بدون وقفه به‌روزرسانی می‌شود

graph TD
    A[کاربر پیام می‌فرستد] --> B[جاوااسکریپت ورودی را دریافت می‌کند]
    B --> C[اعتبارسنجی و قالب‌بندی داده‌ها]
    C --> D[ارسال به API بک‌اند]
    D --> E[نمایش حالت بارگذاری]
    E --> F[دریافت پاسخ هوش مصنوعی]
    F --> G[بروزرسانی رابط چت]
    G --> H[آماده برای پیام بعدی]

classDiagram
    class ChatApp {
        +messages: HTMLElement
        +form: HTMLElement
        +input: HTMLElement
        +sendButton: HTMLElement
        +BASE_URL: string
        +API_ENDPOINT: string
        
        +constructor()
        +initializeEventListeners()
        +handleSubmit(event)
        +callAPI(message)
        +appendMessage(text, role)
        +escapeHtml(text)
        +scrollToBottom()
        +setLoading(isLoading)
    }
    
    ChatApp --> DOM : دستکاری می‌کند
    ChatApp --> FastAPI : درخواست‌ها را ارسال می‌کند

سه ستون توسعه فرانت‌اند

هر برنامه فرانت‌اند – از وب‌سایت‌های ساده تا اپ‌های پیچیده‌ای مثل Discord یا Slack – بر پایه سه فناوری اصلی ساخته شده است. آنها را پایه و اساس هر چیزی که می‌بینید و با آن تعامل دارید تصور کنید:

HTML (ساختار): این بنیان شماست

• تعیین می‌کند چه عناصری وجود دارند (دکمه‌ها، نواحی متنی، کانتینرها)
• معنا به محتوا می‌دهد (این یک هدر است، این یک فرم است و غیره)
• ساختار اولیه را شکل می‌دهد که همه چیز روی آن ساخته می‌شود

CSS (ظاهر): این طراح داخلی شماست

• ظاهر همه چیز را زیبا می‌کند (رنگ‌ها، قلم‌ها، چیدمان)
• اندازه‌های صفحه نمایش مختلف را مدیریت می‌کند (گوشی، لپ‌تاپ، تبلت)
• انیمیشن‌های روان و بازخورد بصری ایجاد می‌کند

JavaScript (رفتار): این مغز شماست

• به اقدامات کاربر واکنش نشان می‌دهد (کلیک‌ها، تایپ، اسکرول)
• با backend شما ارتباط برقرار می‌کند و صفحه را به‌روزرسانی می‌کند
• همه چیز را تعاملی و پویا می‌سازد

شبیه طراحی معماری است:

• HTML: نقشه ساختاری (تعریف فضاها و روابط)
• CSS: طراحی زیبایی‌شناسی و محیطی (سبک بصری و تجربه کاربری)
• JavaScript: سیستم‌های مکانیکی (عملکرد و تعامل)

اهمیت معماری مدرن جاوااسکریپت

اپ چت ما از الگوهای مدرن جاوااسکریپت استفاده می‌کند که در اپلیکیشن‌های حرفه‌ای مشاهده می‌کنید. درک این مفاهیم به شما کمک می‌کند تا به عنوان توسعه‌دهنده رشد کنید:

معماری مبتنی بر کلاس: کد خود را در کلاس‌ها سازماندهی می‌کنیم، شبیه ایجاد نقشه‌های شیء
Async/Await: روش مدرن برای مدیریت عملیات زمان‌بر (مثل فراخوانی API)
برنامه‌نویسی رویدادمحور: اپ ما به جای اجرای مداوم، به اقدامات کاربر واکنش نشان می‌دهد (کلیک‌ها، فشردن دکمه‌ها)
دستکاری DOM: به‌روزرسانی پویا محتوای صفحه بر اساس تعاملات کاربر و پاسخ‌های API

ساختار پروژه

یک دایرکتوری فرانت‌اند با ساختار سازمان‌یافته زیر ایجاد کنید:

frontend/
├── index.html      # Main HTML structure
├── app.js          # JavaScript functionality
└── styles.css      # Visual styling

درک معماری:

• جدا کردن مسئولیت‌ها میان ساختار (HTML)، رفتار (JavaScript) و ظاهر (CSS)
• حفظ ساختار ساده‌ای از فایل که به آسانی قابل پیمایش و تغییر است
• رعایت بهترین شیوه‌های توسعه وب برای سازمان‌دهی و نگهداری

ساخت پایه HTML: ساختار معنایی برای دسترسی‌پذیری

از ساختار HTML شروع کنیم. توسعه مدرن وب بر «HTML معنایی» تأکید دارد – استفاده از عناصری که هدف خود را واضح بیان می‌کنند، نه فقط ظاهرشان. این باعث می‌شود برنامه شما برای صفحه‌خوان‌ها، موتورهای جستجو و ابزارهای دیگر قابل دسترسی باشد.

چرا HTML معنایی اهمیت دارد: تصور کنید بخواهید برنامه چت خود را تلفنی توصیف کنید. می‌گویید: «یک هدر با عنوان، یک بخش اصلی برای نمایش گفتگوها و یک فرم در پایین برای تایپ پیام.» HTML معنایی از عناصری استفاده می‌کند که با این توصیف طبیعی مطابقت دارد.

فایل index.html را با این نشانه‌گذاری ساختارمند و هدفمند ایجاد کنید:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Chat Assistant</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <div class="chat-container">
        <header class="chat-header">
            <h1>AI Chat Assistant</h1>
            <p>Ask me anything!</p>
        </header>
        
        <main class="chat-messages" id="messages" role="log" aria-live="polite">
            <!-- Messages will be dynamically added here -->
        </main>
        
        <form class="chat-form" id="chatForm">
            <div class="input-group">
                <input 
                    type="text" 
                    id="messageInput" 
                    placeholder="Type your message here..." 
                    required
                    aria-label="Chat message input"
                >
                <button type="submit" id="sendBtn" aria-label="Send message">
                    Send
                </button>
            </div>
        </form>
    </div>
    <script src="app.js"></script>
</body>
</html>

توضیح هر عنصر HTML و کاربرد آن:

ساختار سند

• <!DOCTYPE html>: به مرورگر می‌گوید این HTML5 مدرن است
• <html lang="en">: زبان صفحه برای صفحه‌خوان و ابزارهای ترجمه مشخص می‌شود
• <meta charset="UTF-8">: تضمین رمزگذاری صحیح کاراکترها برای متن بین‌المللی
• <meta name="viewport"...>: باعث واکنشگرایی موبایل می‌شود با کنترل بزرگنمایی و مقیاس

عناصر معنایی

• <header>: بخش بالایی با عنوان و توضیح را به وضوح مشخص می‌کند
• <main>: ناحیه اصلی محتوا (جایی که گفتگوها نمایش داده می‌شوند)
• <form>: برای ورودی کاربر به صورت معنایی صحیح است و ناوبری صفحه کلید را بهبود می‌بخشد

ویژگی‌های دسترسی

• role="log": به صفحه‌خوان می‌گوید این بخش حاوی یک گزارش زمانی از پیام‌ها است
• aria-live="polite": پیام‌های جدید را بدون قطع شدن به صفحه‌خوان اعلام می‌کند
• aria-label: برچسب‌های توصیفی برای کنترل‌های فرم فراهم می‌کند
• required: مرورگر از وارد کردن پیام توسط کاربر قبل از ارسال اطمینان می‌یابد

ادغام CSS و JavaScript

• ویژگی class: قلاب‌هایی برای استفاده در CSS فراهم می‌کند (مانند chat-container، input-group)
• ویژگی id: اجازه می‌دهد JavaScript عناصر مشخص را پیدا و دستکاری کند
• محل قرارگیری اسکریپت: فایل JavaScript در انتها بارگذاری می‌شود تا اول HTML لود شود

چرا این ساختار کار می‌کند:

• جریان منطقی: هدر → محتوای اصلی → فرم ورودی، مطابق با ترتیب طبیعی خواندن
• قابل دسترس برای صفحه کلید: کاربران می‌توانند از طریق همه عناصر تعاملی تب‌زنی کنند
• دوستدار صفحه‌خوان‌ها: نقاط راهنما و توضیحات واضح برای کاربران کم‌بینا
• واکنشگرا برای موبایل: تگ متا ویوپورت طراحی واکنشگرا را فعال می‌کند
• افزایش تدریجی: حتی اگر CSS یا JavaScript بارگذاری نشود، کار می‌کند

افزودن JavaScript تعاملی: منطق اپلیکیشن وب مدرن

حال بیایید جاوااسکریپتی بسازیم که رابط چت ما را زنده کند. از الگوهای مدرن جاوااسکریپت استفاده خواهیم کرد که در توسعه حرفه‌ای وب خواهید دید، شامل کلاس‌های ES6، async/await و برنامه‌نویسی بر مبنای رویداد.

درک معماری مدرن جاوااسکریپت

به جای نوشتن کد رویه‌ای (یک سری توابع که پشت سر هم اجرا می‌شوند)، یک معماری مبتنی بر کلاس ایجاد می‌کنیم. یک کلاس را مثل یک نقشه‌ی مهندسی تصور کنید که می‌توان از آن برای ساخت چندین شیء استفاده کرد؛ درست همانند نقشه ساختمانی که برای ساخت چند خانه کاربرد دارد.

چرا برای برنامه‌های وب از کلاس استفاده کنیم؟

• سازماندهی: تمام قابلیت‌های مرتبط در یکجا جمع شده‌اند
• قابلیت استفاده مجدد: می‌توانید چند نمونه چت را در یک صفحه بسازید
• قابل نگهداری بودن: عیب‌یابی و اصلاح ویژگی‌های خاص آسان‌تر است
• استاندارد حرفه‌ای: این الگو در فریمورک‌هایی مثل React، Vue و Angular استفاده می‌شود

فایل app.js را با این جاوااسکریپت مدرن و منظم بسازید:

// app.js - منطق برنامه چت مدرن

class ChatApp {
    constructor() {
        // دریافت مراجع به عناصر DOM که باید دستکاری شوند
        this.messages = document.getElementById("messages");
        this.form = document.getElementById("chatForm");
        this.input = document.getElementById("messageInput");
        this.sendButton = document.getElementById("sendBtn");
        
        // آدرس URL بک‌اند خود را اینجا تنظیم کنید
        this.BASE_URL = "http://localhost:5000"; // این مقدار را برای محیط خود به‌روزرسانی کنید
        this.API_ENDPOINT = `${this.BASE_URL}/hello`;
        
        // تنظیم شنونده‌های رویداد هنگام ایجاد برنامه چت
        this.initializeEventListeners();
    }
    
    initializeEventListeners() {
        // گوش دادن به ارسال فرم (وقتی کاربر روی ارسال کلیک می‌کند یا دکمه Enter را فشار می‌دهد)
        this.form.addEventListener("submit", (e) => this.handleSubmit(e));
        
        // همچنین گوش دادن به کلید Enter در فیلد ورودی (تجربه کاربری بهتر)
        this.input.addEventListener("keypress", (e) => {
            if (e.key === "Enter" && !e.shiftKey) {
                e.preventDefault();
                this.handleSubmit(e);
            }
        });
    }
    
    async handleSubmit(event) {
        event.preventDefault(); // جلوگیری از رفرش شدن صفحه هنگام ارسال فرم
        
        const messageText = this.input.value.trim();
        if (!messageText) return; // پیام‌های خالی ارسال نکنید
        
        // بازخورد به کاربر برای نشان دادن انجام فرآیند
        this.setLoading(true);
        
        // افزودن پیام کاربر به چت بلافاصله (رابط کاربری خوشبینانه)
        this.appendMessage(messageText, "user");
        
        // پاک کردن فیلد ورودی تا کاربر بتواند پیام بعدی را تایپ کند
        this.input.value = '';
        
        try {
            // فراخوانی API هوش مصنوعی و انتظار برای پاسخ
            const reply = await this.callAPI(messageText);
            
            // افزودن پاسخ هوش مصنوعی به چت
            this.appendMessage(reply, "assistant");
        } catch (error) {
            console.error('API Error:', error);
            this.appendMessage("Sorry, I'm having trouble connecting right now. Please try again.", "error");
        } finally {
            // فعال‌سازی دوباره رابط کاربری صرف‌نظر از موفقیت یا شکست
            this.setLoading(false);
        }
    }
    
    async callAPI(message) {
        const response = await fetch(this.API_ENDPOINT, {
            method: "POST",
            headers: { 
                "Content-Type": "application/json" 
            },
            body: JSON.stringify({ message })
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        const data = await response.json();
        return data.response;
    }
    
    appendMessage(text, role) {
        const messageElement = document.createElement("div");
        messageElement.className = `message ${role}`;
        messageElement.innerHTML = `
            <div class="message-content">
                <span class="message-text">${this.escapeHtml(text)}</span>
                <span class="message-time">${new Date().toLocaleTimeString()}</span>
            </div>
        `;
        
        this.messages.appendChild(messageElement);
        this.scrollToBottom();
    }
    
    escapeHtml(text) {
        const div = document.createElement('div');
        div.textContent = text;
        return div.innerHTML;
    }
    
    scrollToBottom() {
        this.messages.scrollTop = this.messages.scrollHeight;
    }
    
    setLoading(isLoading) {
        this.sendButton.disabled = isLoading;
        this.input.disabled = isLoading;
        this.sendButton.textContent = isLoading ? "Sending..." : "Send";
    }
}

// مقداردهی اولیه برنامه چت هنگام بارگذاری صفحه
document.addEventListener("DOMContentLoaded", () => {
    new ChatApp();
});

درک هر مفهوم جاوااسکریپت

ساختار کلاس ES6:

class ChatApp {
    constructor() {
        // این زمانی اجرا می‌شود که یک نمونه جدید از ChatApp ایجاد می‌کنید
        // این مانند تابع «تنظیمات» برای چت شماست
    }
    
    methodName() {
        // متدها توابعی هستند که متعلق به کلاس هستند
        // آن‌ها می‌توانند به ویژگی‌های کلاس با استفاده از «this» دسترسی داشته باشند
    }
}

الگوی Async/Await:

// روش قدیمی (جهنم callback):
fetch(url)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

// روش مدرن (async/await):
try {
    const response = await fetch(url);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

برنامه‌نویسی رویدادمحور:
به جای بررسی مداوم اینکه چیزی اتفاق افتاده یا نه، به رویدادها «گوش می‌دهیم»:

// وقتی فرم ارسال می‌شود، تابع handleSubmit را اجرا کن
this.form.addEventListener("submit", (e) => this.handleSubmit(e));

// وقتی کلید Enter فشرده شد، نیز تابع handleSubmit را اجرا کن
this.input.addEventListener("keypress", (e) => { /* ... */ });

دستکاری DOM:

// ایجاد عناصر جدید
const messageElement = document.createElement("div");

// تغییر ویژگی‌های آنها
messageElement.className = "message user";
messageElement.innerHTML = "Hello world!";

// اضافه کردن به صفحه
this.messages.appendChild(messageElement);

امنیت و بهترین شیوه‌ها

جلوگیری از XSS:

escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;  // این به طور خودکار HTML را ایمن می‌کند
    return div.innerHTML;
}

چرا این اهمیت دارد: اگر کاربر <script>alert('hack')</script> تایپ کند، این تابع تضمین می‌کند که به عنوان متن نمایش داده شود و اجرا نشود.

مدیریت خطا:

try {
    const reply = await this.callAPI(messageText);
    this.appendMessage(reply, "assistant");
} catch (error) {
    // نمایش خطای کاربرپسند به جای خراب شدن برنامه
    this.appendMessage("Sorry, I'm having trouble...", "error");
}

ملاحظات تجربه کاربری:

• رابط کاربری خوش‌بینانه: پیام کاربر بلافاصله افزوده می‌شود، منتظر پاسخ سرور نمی‌مانیم
• وضعیت بارگذاری: دکمه‌ها غیر فعال و هنگام انتظار «در حال ارسال...» نمایش داده شود
• اسکرول خودکار: جدیدترین پیام‌ها همیشه قابل مشاهده باشند
• اعتبارسنجی ورودی: پیام‌های خالی ارسال نشوند
• میانبرهای صفحه‌کلید: کلید Enter برای ارسال پیام (مانند برنامه‌های واقعی چت)

درک جریان برنامه

1. بارگذاری صفحه → رویداد DOMContentLoaded → ایجاد new ChatApp()
2. اجرای سازنده → دریافت ارجاعات DOM → تنظیم شنونده‌های رویداد
3. کاربر پیام می‌نویسد → Enter می‌زند یا دکمه ارسال را کلیک می‌کند → اجرای handleSubmit
4. در handleSubmit → اعتبارسنجی ورودی → نمایش وضعیت بارگذاری → فراخوانی API
5. پاسخ API → افزودن پیام هوش مصنوعی به چت → فعال‌سازی مجدد رابط
6. آماده برای پیام بعدی → کاربر می‌تواند ادامه دهد

این معماری قابل توسعه است – می‌توانید ویژگی‌هایی مثل ویرایش پیام، بارگذاری فایل یا چندین رشته گفتگو را بدون بازنویسی ساختار اصلی اضافه کنید.

🎯 بررسی آموزشی: معماری مدرن فرانت‌اند

درک معماری: یک برنامه تک‌صفحه‌ای کامل با الگوهای مدرن جاوااسکریپت پیاده‌سازی کرده‌اید. این نمایانگر توسعه حرفه‌ای فرانت‌اند است.

مفاهیم کلیدی یادگرفته شده:

• معماری کلاس ES6: ساختار کد سازمان‌یافته و قابل نگهداری
• الگوهای Async/Await: برنامه‌نویسی ناهمگام مدرن
• برنامه‌نویسی رویدادمحور: طراحی رابط کاربری پاسخگو
• بهترین شیوه‌های امنیتی: جلوگیری از XSS و اعتبارسنجی ورودی

پیوند به صنعت: الگوهایی که یاد گرفتید (معماری مبتنی بر کلاس، عملیات async، دستکاری DOM) اساس فریمورک‌های مدرن مانند React، Vue و Angular هستند. شما با همان تفکر معماری که در برنامه‌های تولیدی بکار می‌رود توسعه می‌دهید.

سؤال تأملی: چگونه این برنامه چت را برای مدیریت چندین گفتگو یا احراز هویت کاربر گسترش می‌دهید؟ تغییرات معماری لازم و چگونگی تکامل ساختار کلاس را در نظر بگیرید.

استایل‌دهی رابط چت

حالا یک رابط چت مدرن و جذاب با CSS بسازیم. استایل خوب باعث می‌شود برنامه شما حرفه‌ای به نظر برسد و تجربه کاربری را بهبود بخشد. از ویژگی‌های مدرن CSS مثل Flexbox، CSS Grid و خاصیت‌های سفارشی برای طراحی واکنش‌گرا و قابل دسترس استفاده خواهیم کرد.

فایل styles.css را با این سبک‌های جامع بسازید:

/* styles.css - Modern chat interface styling */

:root {
    --primary-color: #2563eb;
    --secondary-color: #f1f5f9;
    --user-color: #3b82f6;
    --assistant-color: #6b7280;
    --error-color: #ef4444;
    --text-primary: #1e293b;
    --text-secondary: #64748b;
    --border-radius: 12px;
    --shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    min-height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 20px;
}

.chat-container {
    width: 100%;
    max-width: 800px;
    height: 600px;
    background: white;
    border-radius: var(--border-radius);
    box-shadow: var(--shadow);
    display: flex;
    flex-direction: column;
    overflow: hidden;
}

.chat-header {
    background: var(--primary-color);
    color: white;
    padding: 20px;
    text-align: center;
}

.chat-header h1 {
    font-size: 1.5rem;
    margin-bottom: 5px;
}

.chat-header p {
    opacity: 0.9;
    font-size: 0.9rem;
}

.chat-messages {
    flex: 1;
    padding: 20px;
    overflow-y: auto;
    display: flex;
    flex-direction: column;
    gap: 15px;
    background: var(--secondary-color);
}

.message {
    display: flex;
    max-width: 80%;
    animation: slideIn 0.3s ease-out;
}

.message.user {
    align-self: flex-end;
}

.message.user .message-content {
    background: var(--user-color);
    color: white;
    border-radius: var(--border-radius) var(--border-radius) 4px var(--border-radius);
}

.message.assistant {
    align-self: flex-start;
}

.message.assistant .message-content {
    background: white;
    color: var(--text-primary);
    border-radius: var(--border-radius) var(--border-radius) var(--border-radius) 4px;
    border: 1px solid #e2e8f0;
}

.message.error .message-content {
    background: var(--error-color);
    color: white;
    border-radius: var(--border-radius);
}

.message-content {
    padding: 12px 16px;
    box-shadow: var(--shadow);
    position: relative;
}

.message-text {
    display: block;
    line-height: 1.5;
    word-wrap: break-word;
}

.message-time {
    display: block;
    font-size: 0.75rem;
    opacity: 0.7;
    margin-top: 5px;
}

.chat-form {
    padding: 20px;
    border-top: 1px solid #e2e8f0;
    background: white;
}

.input-group {
    display: flex;
    gap: 10px;
    align-items: center;
}

#messageInput {
    flex: 1;
    padding: 12px 16px;
    border: 2px solid #e2e8f0;
    border-radius: var(--border-radius);
    font-size: 1rem;
    outline: none;
    transition: border-color 0.2s ease;
}

#messageInput:focus {
    border-color: var(--primary-color);
}

#messageInput:disabled {
    background: #f8fafc;
    opacity: 0.6;
    cursor: not-allowed;
}

#sendBtn {
    padding: 12px 24px;
    background: var(--primary-color);
    color: white;
    border: none;
    border-radius: var(--border-radius);
    font-size: 1rem;
    font-weight: 600;
    cursor: pointer;
    transition: background-color 0.2s ease;
    min-width: 80px;
}

#sendBtn:hover:not(:disabled) {
    background: #1d4ed8;
}

#sendBtn:disabled {
    background: #94a3b8;
    cursor: not-allowed;
}

@keyframes slideIn {
    from {
        opacity: 0;
        transform: translateY(10px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

/* Responsive design for mobile devices */
@media (max-width: 768px) {
    body {
        padding: 10px;
    }
    
    .chat-container {
        height: calc(100vh - 20px);
        border-radius: 8px;
    }
    
    .message {
        max-width: 90%;
    }
    
    .input-group {
        flex-direction: column;
        gap: 10px;
    }
    
    #messageInput {
        width: 100%;
    }
    
    #sendBtn {
        width: 100%;
    }
}

/* Accessibility improvements */
@media (prefers-reduced-motion: reduce) {
    .message {
        animation: none;
    }
    
    * {
        transition: none !important;
    }
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
    .chat-container {
        background: #1e293b;
        color: #f1f5f9;
    }
    
    .chat-messages {
        background: #0f172a;
    }
    
    .message.assistant .message-content {
        background: #334155;
        color: #f1f5f9;
        border-color: #475569;
    }
    
    .chat-form {
        background: #1e293b;
        border-color: #475569;
    }
    
    #messageInput {
        background: #334155;
        color: #f1f5f9;
        border-color: #475569;
    }
}

درک معماری CSS:

• استفاده از خاصیت‌های سفارشی CSS (متغیرها) برای تم‌بندی یکپارچه و نگهداری آسان
• اجرای لایه‌بندی Flexbox برای طراحی واکنش‌گرا و موقعیت‌دهی مناسب
• شامل انیمیشن‌های نرم برای ظاهر شدن پیام‌ها بدون ایجاد حواس‌پرتی
• ارائه تمایز بصری بین پیام‌های کاربر، پاسخ هوش مصنوعی و وضعیت خطا
• پشتیبانی از طراحی واکنش‌گرا در دیوایس‌های دسکتاپ و موبایل
• ملاحظه کردن دسترسی با حالت کاهش حرکت و نسبت‌های کنتراست مناسب
• ارائه حالت تاریک بر اساس تنظیمات سیستمی کاربر

پیکربندی آدرس بک‌اند

آخرین مرحله، به‌روزرسانی مقدار BASE_URL در جاوااسکریپت برای تطبیق با سرور بک‌اند شما است:

// برای توسعه محلی
this.BASE_URL = "http://localhost:5000";

// برای GitHub Codespaces (با URL واقعی خود جایگزین کنید)
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";

نحوه تعیین آدرس بک‌اند:

• توسعه محلی: اگر هر دو فرانت‌اند و بک‌اند را محلی اجرا می‌کنید از http://localhost:5000 استفاده کنید
• کداسپیس‌ها: آدرس بک‌اند را در تب پورت‌ها بعد از عمومی کردن پورت 5000 پیدا کنید
• محیط تولید: هنگام استقرار به سرویس میزبانی، آدرس دامنه واقعی خود را وارد کنید

💡 نکته تست: می‌توانید بک‌اند خود را مستقیماً با بازدید آدرس ریشه در مرورگر امتحان کنید. باید پیام خوشامدگویی از سرور FastAPI خود را ببینید.

تست و استقرار

حالا که هر دو بخش فرانت‌اند و بک‌اند ساخته شده‌اند، بیایید مطمئن شویم همه با هم کار می‌کنند و گزینه‌های استقرار را برای به اشتراک گذاشتن دستیار چت خود بررسی کنیم.

روند تست محلی

این مراحل را دنبال کنید تا برنامه کامل خود را تست کنید:

graph TD
    A[راه‌اندازی سرور بک‌اند] --> B[پیکربندی متغیرهای محیطی]
    B --> C[آزمون نقاط انتهایی API]
    C --> D[باز کردن فرانت‌اند در مرورگر]
    D --> E[آزمون عملکرد چت]
    E --> F[رفع اشکال مشکلات]

فرآیند گام به گام تست:

1. سرور بک‌اند خود را اجرا کنید:

   cd backend
   source venv/bin/activate  # یا venv\Scripts\activate در ویندوز
   python api.py
   

2. تأیید کارکرد API:

   • http://localhost:5000 را در مرورگر باز کنید
   • باید پیام خوشامدگویی از سرور FastAPI خود را ببینید

3. فرانت‌اند را باز کنید:

   • به دایرکتوری فرانت‌اند بروید
   • index.html را در مرورگر باز کنید
   • یا برای تجربه بهتر توسعه از افزونه Live Server در VS Code استفاده کنید

4. عملکرد چت را تست کنید:

   • در فیلد ورودی پیام تایپ کنید
   • روی «ارسال» کلیک کنید یا Enter بزنید
   • پاسخ هوش مصنوعی را بررسی کنید
   • کنسول مرورگر را برای خطاهای جاوااسکریپت چک کنید

رفع اشکال مشکلات متداول

مشکل	علائم	راه‌حل
خطای CORS	فرانت‌اند به بک‌اند نمی‌رسد	اطمینان از پیکربندی صحیح CORSMiddleware در FastAPI
خطای کلید API	پاسخ 401 غیرمجاز	بررسی متغیر محیطی GITHUB_TOKEN
اتصال رد شده	خطاهای شبکه در فرانت‌اند	اطمینان از URL بک‌اند و اجرای سرور Flask
پاسخ هوش مصنوعی نمی‌آید	پاسخ خالی یا خطا	بررسی لاگ‌های بک‌اند برای مشکلات کوتا یا احراز هویت

مراحل رایج عیب‌یابی:

• بررسی کنسول Developer Tools مرورگر برای خطاهای جاوااسکریپت
• بررسی تب Network برای درخواست‌ها و پاسخ‌های موفق API
• مرور خروجی ترمینال بک‌اند برای خطاهای پایتون یا مشکلات API
• تأیید بارگذاری صحیح متغیرهای محیطی

📈 جدول زمان‌بندی تسلط بر توسعه برنامه‌های هوش مصنوعی شما

timeline
    title سفر کامل توسعه برنامه هوش مصنوعی
    
    section مبانی هوش مصنوعی
        درک هوش مصنوعی تولیدی
            : درک مفاهیم شناخت الگو
            : تسلط بر کنترل پارامترهای هوش مصنوعی
            : یادگیری تکنیک‌های مهندسی درخواست
        
        ادغام مدل‌های GitHub
            : پیمایش در بسترهای خدمات هوش مصنوعی
            : مدیریت ایمن احراز هویت
            : بهینه‌سازی پارامترهای مدل
    
    section توسعه بک‌اند
        معماری API پایتون
            : ساخت برنامه‌های FastAPI
            : پیاده‌سازی عملیات ناهمزمان
            : ایجاد نقاط پایانی ایمن
        
        ادغام خدمات هوش مصنوعی
            : اتصال به API‌های خارجی هوش مصنوعی
            : مدیریت محدودیت نرخ
            : پیاده‌سازی مرزهای خطا
    
    section تسلط بر فرانت‌اند
        الگوهای مدرن جاوااسکریپت
            : تسلط بر معماری کلاس ES6
            : پیاده‌سازی جریان‌های async/await
            : ساخت رابط‌های پاسخگو
        
        تجربه کاربری بلادرنگ
            : ایجاد رابط‌های گفتگوی پویا
            : مدیریت وضعیت بارگذاری
            : بهینه‌سازی تعاملات کاربر
    
    section آماده‌سازی تولید
        امنیت و عملکرد
            : پیاده‌سازی مدیریت ایمن نشانه‌ها
            : جلوگیری از آسیب‌پذیری‌های XSS
            : بهینه‌سازی عملکرد API
        
        استقرار حرفه‌ای
            : ساخت معماری‌های مقیاس‌پذیر
            : ایجاد کد قابل نگهداری
            : مستندسازی فرایندهای توسعه

🎓 نقطه عطف فارغ‌التحصیلی: شما با موفقیت یک برنامه کامل مبتنی بر هوش مصنوعی ساخته‌اید که از همان فناوری‌ها و الگوهای معماری مدرن استفاده می‌کند. این مهارت‌ها تقاطع توسعه وب سنتی و ادغام پیشرفته هوش مصنوعی را نشان می‌دهند.

🔄 قابلیت‌های سطح بعدی:

• آماده کاوش فریمورک‌های پیشرفته AI (LangChain، LangGraph)
• آماده ساخت برنامه‌های AI چندرسانه‌ای (متن، تصویر، صدا)
• مجهز به پیاده‌سازی پایگاه داده و سیستم بازیابی وکتور
• پایه گذاری شده برای یادگیری ماشین و تنظیم دقیق مدل‌های AI

چالش GitHub Copilot Agent 🚀

از حالت Agent برای تکمیل چالش زیر استفاده کنید:

شرح: دستیار چت را با افزودن تاریخچه گفتگو و ماندگاری پیام بهبود دهید. این چالش به شما کمک می‌کند مدیریت حالت در برنامه‌های چت و پیاده‌سازی ذخیره‌سازی داده را برای تجربه کاربری بهتر درک کنید.

دستور: برنامه چت را طوری اصلاح کنید که تاریخچه گفتگو بین جلسات ذخیره شود. قابلیت ذخیره پیام‌ها در local storage، نمایش تاریخچه گفتگو هنگام بارگذاری صفحه و افزودن دکمه «پاک کردن تاریخچه» را اضافه کنید. همچنین شاخص‌های در حال تایپ و زمان‌های پیام را برای واقعی‌تر شدن تجربه چت پیاده‌سازی کنید.

برای اطلاعات بیشتر درباره حالت agent اینجا ببینید.

تمرین: ساخت دستیار شخصی AI خودتان

حالا شما نسخه پیاده‌سازی دستیار AI شخصی خود را می‌سازید. به جای تکرار صرف کد آموزشی، فرصتی است برای اعمال مفاهیم در ساخت چیزی که بازتاب‌دهنده علاقه‌مندی‌ها و کاربردهای شماست.

الزامات پروژه

بیایید پروژه را با ساختاری تمیز و منظم راه‌اندازی کنیم:

my-ai-assistant/
├── backend/
│   ├── api.py          # Your FastAPI server
│   ├── llm.py          # AI integration functions
│   ├── .env            # Your secrets (keep this safe!)
│   └── requirements.txt # Python dependencies
├── frontend/
│   ├── index.html      # Your chat interface
│   ├── app.js          # The JavaScript magic
│   └── styles.css      # Make it look amazing
└── README.md           # Tell the world about your creation

وظایف اصلی پیاده‌سازی

توسعه بک‌اند:

• استفاده از کد FastAPI ما و شخصی‌سازی آن
• ساخت یک شخصیت AI منحصر به فرد – ممکن است دستیار آشپزی، همکار نویسندگی خلاق یا دوست مطالعه باشد؟
• افزودن مدیریت خطای قوی تا برنامه هنگام بروز مشکل از کار نیفتد
• نوشتن مستندات واضح برای هرکسی که می‌خواهد درباره API شما بداند

توسعه فرانت‌اند:

• ساخت یک رابط چت که شهودی و خوشایند باشد
• نوشتن جاوااسکریپت مدرن و تمیز که مایه افتخار دیگر توسعه‌دهندگان باشد
• طراحی استایل سفارشی که شخصیت AI شما را منعکس کند – سرگرم‌کننده و رنگارنگ؟ ساده و مینیمال؟ کاملاً به انتخاب شما!
• اطمینان از کارکرد مناسب روی تلفن‌ها و کامپیوترها

الزامات شخصی‌سازی:

• انتخاب نام و شخصیت منحصر به فرد برای دستیار AI – شاید چیزی که علایق یا مشکلاتی که می‌خواهید حل کنید را نشان دهد
• سفارشی‌سازی طراحی بصری مطابق حال و هوای دستیار
• نوشتن پیام خوشامدگویی که افراد را به شروع گفتگو تشویق کند
• آزمون دستیار با انواع سوالات مختلف برای ارزیابی پاسخ‌ها

ایده‌های ارتقاء (اختیاری)

می‌خواهید پروژه را به سطح بالاتری ببرید؟ این ایده‌های جالب را بررسی کنید:

ویژگی	توضیح	مهارت‌هایی که تمرین می‌کنید
تاریخچه پیام‌ها	حفظ گفتگوها حتی بعد از بارگذاری مجدد صفحه	کار با localStorage، مدیریت JSON
شاخص‌های تایپ کردن	نمایش «هوش مصنوعی در حال تایپ...» هنگام انتظار پاسخ	انیمیشن CSS، برنامه‌نویسی async
زمان‌سنج پیام‌ها	نمایش زمان ارسال هر پیام	قالب‌بندی تاریخ/زمان، طراحی UX
صادرات چت	اجازه به کاربران برای دانلود گفتگوها	مدیریت فایل، خروجی داده
تغییر تم	سویچ حالت روشن/تاریک	متغیرهای CSS، تنظیمات کاربر
ورودی صوتی	افزودن قابلیت تبدیل گفتار به متن	وب APIها، دسترسی‌پذیری

تست و مستندسازی

تضمین کیفیت:

• تست برنامه با ورودی‌های متنوع و موارد مرزی
• بررسی کارکرد طراحی واکنش‌گرا در اندازه‌های صفحه مختلف
• چک کردن دسترسی با ناوبری صفحه‌کلید و خواننده صفحه
• اعتبارسنجی HTML و CSS مطابق با استانداردها

الزامات مستندسازی:

• نوشتن README.md که پروژه و نحوه اجرا را توضیح می‌دهد
• شامل کردن تصاویر صفحه از رابط چت در حال اجرا
• مستندسازی هر ویژگی یا سفارشی‌سازی خاص اضافه شده
• ارائه دستورالعمل‌های واضح راه‌اندازی برای سایر توسعه‌دهندگان

راهنمای ارسال

تحویل پروژه:

1. پوشه کامل پروژه با تمام کدهای منبع
2. README.md با شرح پروژه و دستورالعمل‌های راه‌اندازی
3. تصاویر صفحه که دستیار چت را در حال اجرا نشان می‌دهد
4. بازتاب کوتاهی درباره آنچه آموخته‌اید و چالش‌های پیش‌رو

معیارهای ارزیابی:

• عملکرد: آیا دستیار چت طبق انتظار کار می‌کند؟
• کیفیت کد: آیا کد منظم، کامنت‌گذاری شده و قابل نگهداری است؟
• طراحی: آیا رابط کاربری جذاب و کاربرپسند است؟
• خلاقیت: پیاده‌سازی شما چقدر منحصر به فرد و شخصی‌سازی شده است؟
• مستندسازی: آیا دستورالعمل‌های راه‌اندازی کامل و واضح هستند؟

💡 نکته موفقیت: ابتدا با الزامات پایه شروع کنید، سپس پس از کارکرد کامل، ارتقاءها را اضافه کنید. روی خلق یک تجربه پایه و بدون نقص تمرکز کنید قبل از افزودن ویژگی‌های پیشرفته.

راه‌حل

راه‌حل

چالش‌های جایزه

آماده‌اید دستیار AI خود را به سطح بعدی ببرید؟ این چالش‌های پیشرفته را امتحان کنید تا درک شما از ادغام هوش مصنوعی و توسعه وب عمیق‌تر شود.

شخصی‌سازی شخصیت

جادوی واقعی وقتی اتفاق می‌افتد که به دستیار AI خود شخصیت منحصر به فرد بدهید. با پرامپت‌های سیستمی مختلف آزمایش کنید تا دستیارهای تخصصی بسازید:

نمونه دستیار حرفه‌ای:

call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")

نمونه دستیار خلاق نویسندگی:

call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")

نمونه مربی فنی:

call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")

بهبودهای فرانت‌اند

رابط چت خود را با این بهبودهای بصری و عملکردی متحول کنید:

ویژگی‌های پیشرفته CSS:

• اجرای انیمیشن‌ها و انتقال‌های نرم پیام‌ها
• افزودن طراحی سفارشی حباب‌های چت با اشکال CSS و گرادیان‌ها
• ساخت انیمیشن شاخص تایپ کردن زمانی که AI «در حال فکر است»
• طراحی واکنش‌های ایموجی یا سیستم امتیازدهی پیام‌ها

بهبودهای جاوااسکریپت:

• افزودن میانبرهای صفحه‌کلید (Ctrl+Enter برای ارسال، Escape برای پاک کردن ورودی)
• پیاده‌سازی جستجو و فیلتر پیام‌ها
• ساخت قابلیت صادرات گفتگو (دانلود به صورت متن یا JSON)
• افزودن ذخیره خودکار در localStorage برای جلوگیری از از دست رفتن پیام

ادغام پیشرفته AI

چندین شخصیت AI:

• ایجاد یک منوی کشویی برای تعویض بین شخصیت‌های مختلف AI
• ذخیره شخصیت مورد علاقه کاربر در localStorage
• پیاده‌سازی سوئیچینگ زمینه که جریان گفتگو را حفظ می‌کند

ویژگی‌های پاسخ هوشمند:

• افزودن آگاهی از زمینه گفتگو (AI پیام‌های قبلی را به یاد می‌آورد)
• پیاده‌سازی پیشنهادهای هوشمند بر اساس موضوع گفتگو
• ایجاد دکمه‌های پاسخ سریع برای سوالات متداول

🎯 هدف یادگیری: این چالش‌های اضافی به شما کمک می‌کنند الگوهای پیشرفته توسعه وب و تکنیک‌های یکپارچه‌سازی هوش مصنوعی که در برنامه‌های تولیدی استفاده می‌شوند را درک کنید.

خلاصه و مراحل بعدی

تبریک! شما با موفقیت یک دستیار چت مجهز به هوش مصنوعی را از ابتدا ساخته‌اید. این پروژه به شما تجربه عملی با تکنولوژی‌های مدرن توسعه وب و یکپارچه‌سازی هوش مصنوعی داده است – مهارت‌هایی که در چشم‌انداز فناوری امروزی روزبه‌روز ارزشمندتر می‌شوند.

دستاوردهای شما

در طول این درس، چندین فناوری و مفهوم کلیدی را فراگرفته‌اید:

توسعه بک‌اند:

• یکپارچه‌سازی با GitHub Models API برای عملکرد هوش مصنوعی
• ساخت یک API به سبک RESTful با استفاده از Flask و مدیریت صحیح خطا
• پیاده‌سازی احراز هویت ایمن با استفاده از متغیرهای محیطی
• پیکربندی CORS برای درخواست‌های بین مبداهای مختلف بین فرانت‌اند و بک‌اند

توسعه فرانت‌اند:

• ایجاد رابط کاربری پاسخگو چت با استفاده از HTML معنایی
• پیاده‌سازی جاوااسکریپت مدرن با async/await و معماری مبتنی بر کلاس
• طراحی رابط کاربری جذاب با CSS Grid، Flexbox و انیمیشن‌ها
• افزودن ویژگی‌های دسترسی‌پذیری و اصول طراحی پاسخگو

یکپارچه‌سازی فول‌استک:

• اتصال فرانت‌اند و بک‌اند از طریق فراخوانی‌های API HTTP
• مدیریت تعاملات کاربر به صورت بلادرنگ و جریان داده‌های ناهمزمان
• پیاده‌سازی مدیریت خطا و بازخورد به کاربر در کل برنامه
• آزمایش روند کامل برنامه از ورودی کاربر تا پاسخ هوش مصنوعی

نتایج کلیدی یادگیری

mindmap
  root((مهارت‌های اپ چت هوش مصنوعی))
    API Integration
      Authentication[احراز هویت]
      Error Handling[مدیریت خطا]
      Async Programming[برنامه‌نویسی ناهمگام]
    Web Development
      HTML5 Semantics[معنای HTML5]
      Modern CSS[CSS مدرن]
      ES6+ JavaScript[جاوااسکریپت ES6+]
    User Experience
      Responsive Design[طراحی واکنش‌گرا]
      Accessibility[دسترس‌پذیری]
      Real-time Interaction[تعامل بلادرنگ]
    AI Understanding
      Prompt Engineering[مهندسی پرامپت]
      Model Parameters[پارامترهای مدل]
      Conversation Flow[جریان گفتگو]

این پروژه شما را با اصول پایه ساخت برنامه‌های مجهز به هوش مصنوعی آشنا کرده که نمایانگر آینده توسعه وب است. اکنون می‌دانید چگونه قابلیت‌های هوش مصنوعی را در برنامه‌های وب سنتی ادغام کنید و تجارب کاربری جذاب، هوشمند و پاسخگو خلق نمایید.

کاربردهای حرفه‌ای

مهارت‌هایی که در این درس یاد گرفته‌اید مستقیماً در مشاغل مدرن توسعه نرم‌افزار کاربرد دارد:

• توسعه وب فول‌استک با استفاده از فریم‌ورک‌ها و APIهای مدرن
• یکپارچه‌سازی هوش مصنوعی در برنامه‌های وب و موبایل
• طراحی و توسعه API برای معماری‌های میکروسرویس
• توسعه رابط کاربری با تمرکز بر دسترسی‌پذیری و طراحی پاسخگو
• روش‌های DevOps شامل پیکربندی محیط و استقرار

ادامه مسیر توسعه هوش مصنوعی شما

مراحل بعدی یادگیری:

• کاوش مدل‌ها و APIهای پیشرفته‌تر هوش مصنوعی (GPT-4، Claude، Gemini)
• آموزش تکنیک‌های مهندسی پرامپت برای پاسخ‌های بهتر هوش مصنوعی
• مطالعه اصول طراحی گفتگو و تجربه کاربری چت‌بات
• بررسی ایمنی هوش مصنوعی، اخلاق، و توسعه مسئولانه هوش مصنوعی
• ساخت برنامه‌های پیچیده‌تر با حافظه گفتگو و آگاهی از زمینه

ایده‌های پروژه پیشرفته:

• اتاق‌های گفتگوی چندکاربره با مدیریت هوش مصنوعی
• چت‌بات‌های خدمات مشتری مجهز به هوش مصنوعی
• دستیاران آموزشی با یادگیری شخصی‌سازی شده
• همکاران خلاق نوشتاری با شخصیت‌های مختلف هوش مصنوعی
• دستیارهای مستندسازی فنی برای توسعه‌دهندگان

شروع به کار با GitHub Codespaces

می‌خواهید این پروژه را در یک محیط توسعه ابری امتحان کنید؟ GitHub Codespaces یک محیط توسعه کامل در مرورگر شما فراهم می‌کند که برای آزمایش برنامه‌های هوش مصنوعی بدون نیاز به تنظیمات محلی عالی است.

راه‌اندازی محیط توسعه شما

مرحله 1: ساخت از قالب

• مراجعه به مخزن Web Dev For Beginners
• کلیک روی "Use this template" در گوشه بالا سمت راست (اطمینان حاصل کنید که وارد حساب GitHub شده‌اید)

مرحله 2: راه‌اندازی Codespaces

• باز کردن مخزن تازه ساخته شده
• کلیک روی دکمه سبز "Code" و انتخاب "Codespaces"
• انتخاب "Create codespace on main" برای شروع محیط توسعه شما

مرحله 3: پیکربندی محیط
پس از بارگذاری Codespace، به موارد زیر دسترسی خواهید داشت:

• ابزارهای توسعه از پیش نصب شده مانند Python، Node.js و تمام ابزارهای لازم
• رابط VS Code با افزونه‌های توسعه وب
• دسترسی به ترمینال برای اجرای سرورهای بک‌اند و فرانت‌اند
• فوروارد کردن پورت‌ها برای آزمایش برنامه‌های شما

مواردی که Codespaces فراهم می‌کند:

• رفع مشکلات تنظیم و پیکربندی محیط محلی
• تضمین محیط توسعه یکنواخت در دستگاه‌های مختلف
• شامل ابزارها و افزونه‌های پیکربندی شده برای توسعه وب
• ارائه ادغام بی‌نقص با GitHub برای کنترل نسخه و همکاری

🚀 نکته حرفه‌ای: Codespaces برای یادگیری و نمونه‌سازی برنامه‌های هوش مصنوعی عالی است چون به طور خودکار تمام تنظیمات پیچیده محیط را مدیریت می‌کند و به شما امکان می‌دهد روی ساخت و یادگیری تمرکز کنید نه رفع مشکلات پیکربندی.

---

سلب مسئولیت: این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی اشتباهات یا نادرستی‌هایی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، استفاده از ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هر گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم.