generative-ai-for-beginners / fa

# AGENTS.md

## مرور پروژه

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

**فناوری‌های کلیدی:**
- پایتون ۳.۹+ با کتابخانه‌های: `openai`، `python-dotenv`، `tiktoken`، `azure-ai-inference`، `pandas`، `numpy`، `matplotlib`
- تایپ‌اسکریپت/جاوااسکریپت با Node.js و کتابخانه‌های: `openai` (Azure OpenAI از طریق نقطه پایانی v1 + API پاسخ‌ها), `@azure-rest/ai-inference` (مدل‌های Microsoft Foundry)
- سرویس Azure OpenAI، API اپن‌ای‌آی، و مدل‌های Microsoft Foundry (مدل‌های GitHub تا پایان ژوئیه ۲۰۲۶ بازنشسته می‌شوند)
- نوت‌بوک‌های ژوپیتر برای یادگیری تعاملی
- Dev Containers برای محیط توسعه ثابت

**ساختار مخزن:**
- ۲۱ پوشه شماره‌گذاری شده درس (۰۰-۲۱) شامل فایل README، مثال‌های کد، و تکالیف
- پیاده‌سازی‌های متعدد: پایتون، تایپ‌اسکریپت، و بعضاً مثال‌های دات‌نت
- پوشه ترجمه‌ها با نسخه‌های ۴۰+ زبان
- پیکربندی متمرکز از طریق فایل `.env` (استفاده از `.env.copy` به عنوان الگو)

## دستورات راه‌اندازی

### راه‌اندازی اولیه مخزن

```bash
# کلون کردن مخزن
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# کپی قالب محیط
cp .env.copy .env
# ویرایش .env با کلیدهای API و نقاط انتهایی خودتان
```

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

```bash
# ایجاد محیط مجازی
python3 -m venv venv

# فعال‌سازی محیط مجازی
# در مک‌اواس/لینوکس:
source venv/bin/activate
# در ویندوز:
venv\Scripts\activate

# نصب وابستگی‌ها
pip install -r requirements.txt
```

### راه‌اندازی Node.js/تایپ‌اسکریپت

```bash
# نصب وابستگی‌های سطح ریشه (برای ابزار مستندسازی)
npm install

# برای مثال‌های TypeScript هر درس به درس خاص مراجعه کنید:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### راه‌اندازی Dev Container (توصیه‌شده)

مخزن شامل پیکربندی `.devcontainer` برای GitHub Codespaces یا VS Code Dev Containers است:

۱. مخزن را در GitHub Codespaces یا VS Code با افزونه Dev Containers باز کنید
۲. Dev Container به صورت خودکار:
   - وابستگی‌های پایتون را از `requirements.txt` نصب می‌کند
   - اسکریپت پس از ایجاد را اجرا می‌کند (`.devcontainer/post-create.sh`)
   - هسته ژوپیتر را راه‌اندازی می‌کند

## روند توسعه

### متغیرهای محیطی

همه درس‌هایی که به دسترسی API نیاز دارند از متغیرهای محیطی تعریف‌شده در `.env` استفاده می‌کنند:

- `OPENAI_API_KEY` - برای API اپن‌ای‌آی
- `AZURE_OPENAI_API_KEY` - برای Azure OpenAI در Microsoft Foundry (سرویس Azure OpenAI هم‌اکنون بخشی از Microsoft Foundry است: https://ai.azure.com)
- `AZURE_OPENAI_ENDPOINT` - URL نقطه پایانی Azure OpenAI (نقطه پایانی منبع Foundry)
- `AZURE_OPENAI_DEPLOYMENT` - نام استقرار مدل چت تکمیل (پیش‌فرض دوره: `gpt-5-mini`)
- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - نام استقرار مدل جاسازی‌ها (پیش‌فرض دوره: `text-embedding-3-small`)
- `AZURE_OPENAI_API_VERSION` - نسخه API (پیش‌فرض: `2024-10-21`)
- `HUGGING_FACE_API_KEY` - برای مدل‌های Hugging Face
- `AZURE_INFERENCE_ENDPOINT` - نقطه پایانی مدل‌های Microsoft Foundry (فهرست مدل چند تامین‌کننده)
- `AZURE_INFERENCE_CREDENTIAL` - کلید API مدل‌های Microsoft Foundry (جایگزین `GITHUB_TOKEN` در حال بازنشستگی)
- `AZURE_INFERENCE_CHAT_MODEL` - یک مدل فاقد استدلال (مثلاً `Llama-3.3-70B-Instruct`) استفاده‌شده در مثال‌های `temperature`، چون مدل‌های استدلالی کنترل نمونه‌برداری را پشتیبانی نمی‌کنند

### قراردادهای مدل (مهم)

- **مدل چت پیش‌فرض `gpt-5-mini` است** - یک مدل استدلالی فعلی و غیر منسوخ. از سال ۲۰۲۶ مدل‌های قدیمی‌تر "مینی" با قابلیت دما (`gpt-4o-mini`، `gpt-4.1-mini`) در حال *منسوخ شدن* هستند، بنابراین دوره بر خانواده GPT-۵ استاندارد شده است.
- **مدل‌های استدلالی پارامترهای `temperature` و `top_p` را رد می‌کنند** و به جای `max_tokens` از `max_output_tokens` (API پاسخ‌ها) / `max_completion_tokens` (تکمیل چت) استفاده می‌کنند. لطفاً این پارامترها را در نمونه‌هایی که `gpt-5-mini` را فراخوانی می‌کنند اضافه نکنید.
- **برای نشان دادن `temperature`، نمونه‌ها از مدل **Llama** (`Llama-3.3-70B-Instruct`) از طریق نقطه پایانی مدل‌های Microsoft Foundry (`AZURE_INFERENCE_CHAT_MODEL`) استفاده می‌کنند. کنترل مدل‌های استدلالی با مهندسی پرامپت و کنترل‌های استدلالی به جای دستگیره‌های نمونه‌برداری انجام شود.
- **تنظیم دقیق (درس ۱۸)** مدل را روی `gpt-4.1-mini` نگه می‌دارد: GPT-۵ فقط تنظیم دقیق تقویتی (RFT) را پشتیبانی می‌کند، نه تنظیم دقیق نظارتی (SFT) که در آنجا نشان داده شده است.
- در درس‌های ۲۰ (میسترال) و ۲۱ (متا) پارامترهای `temperature`/`max_tokens` حفظ شده‌اند زیرا هدف مدل‌های میسترال/لاما هستند که آن‌ها را پشتیبانی می‌کنند.

### اجرای مثال‌های پایتون

```bash
# به دایرکتوری درس بروید
cd 06-text-generation-apps/python

# یک اسکریپت پایتون را اجرا کنید
python aoai-app.py
```

### اجرای مثال‌های تایپ‌اسکریپت

```bash
# به دایرکتوری برنامه تایپ‌اسکریپت بروید
cd 06-text-generation-apps/typescript/recipe-app

# کد تایپ‌اسکریپت را بسازید
npm run build

# برنامه را اجرا کنید
npm start
```

### اجرای نوت‌بوک‌های ژوپیتر

```bash
# شروع Jupyter در ریشه مخزن
jupyter notebook

# یا استفاده از VS Code با افزونه Jupyter
```

### کار با انواع مختلف درس‌ها

- **درس‌های "یادگیری"**: تمرکز بر مستندات README.md و مفاهیم
- **درس‌های "ساخت"**: شامل مثال‌های کد عملی به زبان‌های پایتون و تایپ‌اسکریپت
- هر درس دارای README.md است با نظریه‌ها، مرور کدها و لینک به محتوای ویدیویی

## راهنمای سبک کد

### پایتون

- از `python-dotenv` برای مدیریت متغیرهای محیطی استفاده کنید
- کتابخانه `openai` را برای تعامل با API وارد کنید
- از `pylint` برای بررسی کد استفاده کنید (برخی مثال‌ها برای سادگی شامل `# pylint: disable=all` هستند)
- دستور نامگذاری PEP 8 را رعایت کنید
- اطلاعات اعتبارسنجی API را در فایل `.env` ذخیره کنید، هرگز در کد

### تایپ‌اسکریپت

- از بسته `dotenv` برای متغیرهای محیطی استفاده کنید
- پیکربندی تایپ‌اسکریپت در فایل `tsconfig.json` برای هر برنامه
- برای Azure OpenAI از بسته `openai` استفاده کنید (مشتری را به نقطه پایانی `/openai/v1/` اشاره دهید و تابع `client.responses.create` را صدا بزنید)؛ برای مدل‌های Microsoft Foundry از `@azure-rest/ai-inference` استفاده کنید
- برای توسعه از `nodemon` با بارگذاری مجدد خودکار استفاده کنید
- قبل از اجرا بسازید: `npm run build` سپس `npm start`

### قراردادهای عمومی

- مثال‌های کد باید ساده و آموزشی باشند
- شامل توضیحاتی در مورد مفاهیم کلیدی باشند
- کد هر درس باید به صورت مستقل باشد و قابل اجرا باشد
- نامگذاری یکنواخت: پیشوند `aoai-` برای Azure OpenAI، `oai-` برای API اپن‌ای‌آی، `githubmodels-` برای مدل‌های Microsoft Foundry (پیشوند قدیمی از دوران مدل‌های GitHub حفظ شده است)

## راهنمای مستندسازی

### سبک مارک‌داون

- همه آدرس‌های URL باید به فرمت `[text](../../url)` بدون فاصله اضافی باشند
- لینک‌های نسبی باید با `./` یا `../` شروع شوند
- همه لینک‌ها به دامنه‌های مایکروسافت باید شناسه رهگیری را شامل شوند: `?WT.mc_id=academic-105485-koreyst`
- استفاده از محلی‌سازی‌های خاص کشور در URLها ممنوع است (از `/en-us/` اجتناب کنید)
- تصاویر در پوشه `./images` با نام‌های توصیفی ذخیره شوند
- از کاراکترهای انگلیسی، اعداد و خط تیره در نام فایل‌ها استفاده شود

### پشتیبانی ترجمه

- مخزن از بیش از ۴۰ زبان از طریق GitHub Actions خودکار پشتیبانی می‌کند
- ترجمه‌ها در پوشه `translations/` ذخیره می‌شوند
- ترجمه‌های ناقص ارسال نکنید
- ترجمه‌های ماشینی پذیرفته نمی‌شوند
- تصاویر ترجمه‌شده در پوشه `translated_images/` قرار دارند

## آزمون و اعتبارسنجی

### چک‌های پیش از ارسال

این مخزن از GitHub Actions برای اعتبارسنجی استفاده می‌کند. قبل از ارسال PRها:

۱. **بررسی لینک‌های مارک‌داون**:
   ```bash
   # روند کاری validate-markdown.yml بررسی می‌کند:
   # - مسیرهای نسبی شکسته شده
   # - شناسه‌های پیگیری مفقود در مسیرها
   # - شناسه‌های پیگیری مفقود در URLها
   # - URLها با نشانی محلی کشور
   # - URLهای خارجی شکسته شده
   ```

۲. **آزمون دستی**:
   - مثال‌های پایتون را تست کنید: venv را فعال و اسکریپت‌ها را اجرا کنید
   - مثال‌های تایپ‌اسکریپت را تست کنید: `npm install`، `npm run build`، `npm start`
   - مطمئن شوید متغیرهای محیطی به درستی پیکربندی شده‌اند
   - بررسی کنید کلیدهای API با مثال‌های کد کار می‌کنند

۳. **مثال‌های کد**:
   - اطمینان حاصل کنید همه کدها بدون خطا اجرا می‌شوند
   - هنگام امکان با Azure OpenAI و OpenAI API تست کنید
   - مطمئن شوید مثال‌ها با مدل‌های Microsoft Foundry در صورت پشتیبانی کار می‌کنند

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

این یک مخزن آموزشی متمرکز بر آموزش‌ها و مثال‌ها است. هیچ تست واحد یا تست یکپارچه‌ای وجود ندارد. اعتبارسنجی عمدتاً شامل:
- آزمون دستی مثال‌های کد
- GitHub Actions برای اعتبارسنجی مارک‌داون
- بازبینی جامعه برای محتوای آموزشی

## راهنمای درخواست کشش (Pull Request)

### قبل از ارسال

۱. در صورت امکان تغییرات کد را در پایتون و تایپ‌اسکریپت تست کنید
۲. اعتبارسنجی مارک‌داون را اجرا کنید (به صورت خودکار در PR فعال می‌شود)
۳. اطمینان حاصل کنید شناسه‌های رهگیری در همه URLهای مایکروسافت وجود دارند
۴. بررسی کنید لینک‌های نسبی معتبر هستند
۵. اطمینان حاصل کنید تصاویر به درستی ارجاع داده شده‌اند

### قالب عنوان PR

- از عناوین توصیفی استفاده کنید: `[Lesson 06] اصلاح اشتباه مثال پایتون` یا `به‌روزرسانی README برای درس ۰۸`
- در صورت امکان شماره‌های مسأله را ارجاع دهید: `Fixes #123`

### شرح PR

- توضیح دهید چه چیزی تغییر کرده و چرا
- لینک به مسایل مرتبط
- برای تغییرات کد، مشخص کنید کدام مثال‌ها تست شده‌اند
- برای PRهای ترجمه، شامل همه فایل‌ها برای ترجمه کامل باشید

### شرایط مشارکت

- امضای CLA مایکروسافت (به طور خودکار در اولین PR)
- مخزن را به حساب خود فورک کنید قبل از ایجاد تغییرات
- یک PR برای هر تغییر منطقی (تعمیرات نامرتبط را ترکیب نکنید)
- PRها را متمرکز و کوچک نگه دارید در صورت امکان

## روندهای رایج

### اضافه کردن مثال کد جدید

۱. به دایرکتوری درس مربوطه بروید
۲. مثال را در زیرپوشه `python/` یا `typescript/` ایجاد کنید
۳. قرارداد نامگذاری را دنبال کنید: `{provider}-{example-name}.{py|ts|js}`
۴. با اعتبارسنجی واقعی API تست کنید
۵. متغیرهای محیطی جدید را در README درس مستند کنید

### به‌روزرسانی مستندات

۱. README.md در دایرکتوری درس را ویرایش کنید
۲. راهنمای مارک‌داون را رعایت کنید (شناسه‌های رهگیری، لینک‌های نسبی)
۳. به‌روزرسانی ترجمه‌ها توسط GitHub Actions انجام می‌شود (به‌صورت دستی ویرایش نکنید)
۴. بررسی صحت همه لینک‌ها

### کار با Dev Containers

۱. مخزن شامل فایل `.devcontainer/devcontainer.json` است
۲. اسکریپت پس از ایجاد به طور خودکار وابستگی‌های پایتون را نصب می‌کند
۳. افزونه‌های پایتون و ژوپیتر به صورت پیش‌فرض پیکربندی شده‌اند
۴. محیط بر پایه `mcr.microsoft.com/devcontainers/universal:2.11.2` است

## استقرار و انتشار

این یک مخزن آموزشی است - فرایند استقرار ندارد. دوره از طریق موارد زیر مصرف می‌شود:

۱. **مخزن گیت‌هاب**: دسترسی مستقیم به کد و مستندات
۲. **GitHub Codespaces**: محیط توسعه فوری با راه‌اندازی پیش‌پیکربندی شده
۳. **Microsoft Learn**: محتوا ممکن است به پلتفرم رسمی آموزش منتشر شود
۴. **docsify**: سایت مستندات ساخته‌شده از مارک‌داون (نگاه کنید به `docsifytopdf.js` و `package.json`)

### ساخت سایت مستندات

```bash
# تولید PDF از مستندات (در صورت نیاز)
npm run convert
```

## رفع اشکال

### مشکلات رایج

**خطاهای وارد کردن پایتون**:
- مطمئن شوید محیط مجازی فعال شده است
- دستور `pip install -r requirements.txt` را اجرا کنید
- نسخه پایتون باید ۳.۹+ باشد

**خطاهای ساخت تایپ‌اسکریپت**:
- در دایرکتوری برنامه خاص دستور `npm install` را اجرا کنید
- نسخه Node.js را بررسی کنید که سازگار باشد
- پوشه `node_modules` را پاک و مجدداً نصب کنید در صورت نیاز

**خطاهای احراز هویت API**:
- اطمینان حاصل کنید که فایل `.env` وجود دارد و مقادیر صحیح دارد
- کلیدهای API معتبر و منقضی نشده باشند
- آدرس‌های نقطه پایانی متناسب با منطقه شما باشد

**متغیرهای محیطی ناقص**:
- فایل `.env.copy` را به `.env` کپی کنید
- همه مقادیر مورد نیاز درس فعلی را پر کنید
- پس از به‌روزرسانی `.env` برنامه خود را ری‌استارت کنید

## منابع اضافی

- [راهنمای راه‌اندازی دوره](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)
- [راهنمای مشارکت](./CONTRIBUTING.md)
- [کد رفتار](./CODE_OF_CONDUCT.md)
- [سیاست امنیت](./SECURITY.md)
- [دیسکورد Azure AI](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)
- [مجموعه‌ای از نمونه‌های کد پیشرفته](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)

## یادداشت‌های خاص پروژه

- این یک **مخزن آموزشی** متمرکز بر یادگیری است، نه کد تولیدی
- مثال‌ها عمداً ساده و متمرکز بر آموزش مفاهیم هستند
- کیفیت کد با وضوح آموزشی متعادل شده است
- هر درس به صورت مستقل است و می‌تواند به تنهایی تکمیل شود
- مخزن از چندین ارائه‌دهنده API پشتیبانی می‌کند: Azure OpenAI، OpenAI، مدل‌های Microsoft Foundry، و ارائه‌دهندگان آفلاین مانند Foundry Local و Ollama
- محتوا چندزبانه است با روندهای ترجمه خودکار
- جامعه فعالی در دیسکورد برای سوالات و پشتیبانی وجود دارد

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**سلب مسئولیت**:
این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->