generative-ai-for-beginners / ar

# AGENTS.md

## نظرة عامة على المشروع

يحتوي هذا الريبو على منهج شامل مكون من 21 درسًا يشمل تعليم أساسيات الذكاء الاصطناعي التوليدي وتطوير التطبيقات. الدورة مُصممة للمبتدئين وتغطي كل شيء من المفاهيم الأساسية إلى بناء تطبيقات جاهزة للإنتاج.

**التقنيات الرئيسية:**
- بايثون 3.9+ مع المكتبات: `openai`، `python-dotenv`، `tiktoken`، `azure-ai-inference`، `pandas`، `numpy`، `matplotlib`
- تايبسكريبت/جافا سكريبت مع Node.js والمكتبات: `openai` (Azure OpenAI عبر نقطة النهاية v1 وResponses API)، `@azure-rest/ai-inference` (نماذج Microsoft Foundry)
- خدمة Azure OpenAI، OpenAI API، ونماذج Microsoft Foundry (نماذج GitHub ستتوقف نهاية يوليو 2026)
- دفاتر Jupyter للتعلم التفاعلي
- حاويات التطوير لبيئة تطوير موحدة

**هيكل المستودع:**
- 21 مجلد دروس مرقمة (00-21) تحتوي على README، أمثلة كود، وواجبات
- تطبيقات متعددة: بايثون، تايبسكريبت، وأحيانًا أمثلة .NET
- مجلد الترجمات مع أكثر من 40 لغة
- إعداد مركزي عبر ملف `.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/TypeScript

```bash
# تثبيت التبعيات على مستوى الجذر (لأدوات التوثيق)
npm install

# لأمثلة TypeScript للدرس الفردي، انتقل إلى الدرس المحدد:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### إعداد حاوية التطوير (موصى به)

يحتوي المستودع على إعداد `.devcontainer` لـ GitHub Codespaces أو VS Code Dev Containers:

1. افتح المستودع في GitHub Codespaces أو VS Code مع امتداد Dev Containers
2. حاوية التطوير ستقوم تلقائيًا بـ:
   - تثبيت تبعيات بايثون من `requirements.txt`
   - تشغيل سكريبت ما بعد الإنشاء (`.devcontainer/post-create.sh`)
   - إعداد نواة Jupyter

## سير عمل التطوير

### متغيرات البيئة

تستخدم جميع الدروس التي تحتاج وصول API متغيرات البيئة المعرفة في `.env`:

- `OPENAI_API_KEY` - لمفتاح API الخاص بـ OpenAI
- `AZURE_OPENAI_API_KEY` - لمفتاح Azure OpenAI في Microsoft Foundry (خدمة Azure OpenAI أصبحت جزءًا من Microsoft Foundry: https://ai.azure.com)
- `AZURE_OPENAI_ENDPOINT` - عنوان نقطة نهاية 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`** - نموذج **استدلال** حالي وغير مهجور. اعتبارًا من 2026، النماذج القديمة "mini" التي تدعم التحكم في درجة الحرارة (`gpt-4o-mini`، `gpt-4.1-mini`) *تتم إزالتها*، لذلك المنهج يوحد العائلة GPT-5.
- **نماذج الاستدلال ترفض متغيرات `temperature` و`top_p`**، وتستخدم `max_output_tokens` (Responses API) / `max_completion_tokens` (إكمالات الدردشة) بدلاً من `max_tokens`. لا تضف `temperature`/`top_p`/`max_tokens` إلى أمثلة تستدعي `gpt-5-mini`.
- **لتوضيح `temperature`**، تستخدم الأمثلة نموذج **Llama** (`Llama-3.3-70B-Instruct`) عبر نقطة نهاية نماذج Microsoft Foundry (`AZURE_INFERENCE_CHAT_MODEL`). وجه نماذج الاستدلال باستخدام هندسة التهيئة + ضوابط الاستدلال بدلاً من أزرار العينة.
- **التدريب الدقيق (الدرس 18)** يحتفظ بـ `gpt-4.1-mini`: GPT-5 يدعم فقط التدريب المعزز (RFT)، وليس التدريب الخاضع للإشراف (SFT) الموضح هناك.
- الدروس 20 (Mistral) و21 (Meta) تحتفظ بـ `temperature`/`max_tokens` لأنها موجهة لنماذج Mistral/Llama التي تدعمها.

### تشغيل أمثلة بايثون

```bash
# انتقل إلى دليل الدرس
cd 06-text-generation-apps/python

# شغل سكربت بايثون
python aoai-app.py
```

### تشغيل أمثلة تايبسكريبت

```bash
# التنقل إلى مجلد تطبيق TypeScript
cd 06-text-generation-apps/typescript/recipe-app

# بناء شفرة TypeScript
npm run build

# تشغيل التطبيق
npm start
```

### تشغيل دفاتر Jupyter

```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` لكل تطبيق
- استخدم حزمة `openai` لـ Azure OpenAI (وجّه العميل إلى نقطة نهاية `/openai/v1/` واستدعي `client.responses.create`); استخدم `@azure-rest/ai-inference` لنماذج Microsoft Foundry
- استخدم `nodemon` للتطوير مع إعادة تحميل تلقائية
- بناء قبل التشغيل: `npm run build` ثم `npm start`

### الاتفاقيات العامة

- اجعل أمثلة الكود بسيطة وتعليمية
- أدخل تعليقات تشرح المفاهيم الأساسية
- يجب أن يكون كود كل درس مستقل وقابل للتشغيل
- استخدم تسمية متسقة: بادئة `aoai-` لـ Azure OpenAI، `oai-` لـ OpenAI API، `githubmodels-` لنماذج Microsoft Foundry (البادئة قديمة من حقبة GitHub Models)

## إرشادات التوثيق

### أسلوب Markdown

- يجب أن تكون كل الروابط محاطة بالتنسيق `[text](../../url)` بدون فراغات إضافية
- يجب أن تبدأ الروابط النسبية بـ `./` أو `../`
- كل الروابط لمجالات Microsoft يجب أن تتضمن معرف التتبع: `?WT.mc_id=academic-105485-koreyst`
- لا تستخدم مواقع محددة للبلدان في الروابط (تجنب `/en-us/`)
- تُخزن الصور في مجلد `./images` مع أسماء وصفية
- استخدم أحرف إنجليزية وأرقام وواصلات في أسماء الملفات

### دعم الترجمة

- يدعم المستودع أكثر من 40 لغة عبر GitHub Actions مؤتمتة
- تخزن الترجمات في مجلد `translations/`
- لا ترسل ترجمات جزئية
- الترجمات الآلية غير مقبولة
- تُخزن الصور المترجمة في مجلد `translated_images/`

## الاختبار والتحقق

### الفحوصات قبل الإرسال

يستخدم هذا المستودع GitHub Actions للتحقق. قبل إرسال طلبات السحب:

1. **تحقق من روابط Markdown**:
   ```bash
   # يتحقق سير العمل validate-markdown.yml من:
   # - مسارات نسبية معطوبة
   # - عدم وجود معرفات تتبع على المسارات
   # - عدم وجود معرفات تتبع على روابط URL
   # - روابط URL التي تحتوي على إعدادات اللغة حسب البلد
   # - روابط URL الخارجية المعطوبة
   ```

2. **اختبار يدوي**:
   - اختبر أمثلة بايثون: فعّل البيئة الافتراضية وشغّل السكريبتات
   - اختبر أمثلة تايبسكريبت: `npm install`، `npm run build`، `npm start`
   - تحقق من إعداد متغيرات البيئة بشكل صحيح
   - تحقق من أن مفاتيح API تعمل مع أمثلة الكود

3. **أمثلة الكود**:
   - تأكد من أن كل الكود يعمل بدون أخطاء
   - اختبار مع كل من Azure OpenAI وOpenAI API حيثما ينطبق
   - تحقق من أن الأمثلة تعمل مع نماذج Microsoft Foundry حيثما تدعم

### لا اختبارات مؤتمتة

هذا مستودع تعليمي يركز على الدروس والأمثلة. لا توجد اختبارات وحدة أو تكامل يجب تشغيلها. التحقق الأساسي هو:
- اختبار يدوي لأمثلة الكود
- GitHub Actions للتحقق من Markdown
- مراجعة المجتمع للمحتوى التعليمي

## إرشادات طلب السحب

### قبل الإرسال

1. اختبر تغييرات الكود في كل من بايثون وتايبسكريبت حيثما ينطبق
2. شغّل التحقق من Markdown (مفعل تلقائيًا على طلب السحب)
3. تأكد من وجود معرفات التتبع في كل روابط Microsoft
4. تحقق من صلاحية الروابط النسبية
5. تحقق من أن الصور مذكورة بشكل صحيح

### تنسيق عنوان طلب السحب

- استخدم عناوين وصفية: `[Lesson 06] Fix Python example typo` أو `Update README for lesson 08`
- أضف أرقام القضايا عند الحاجة: `Fixes #123`

### وصف طلب السحب

- اشرح ماذا ولماذا تم التغيير
- أضف روابط للمشاكل ذات الصلة
- لتغييرات الكود، حدد أي الأمثلة تم اختبارها
- لطلبات الترجمة، أدرج كل الملفات للترجمة الكاملة

### متطلبات المساهمة

- وقع على اتفاقية المساهمين في Microsoft (تلقائيًا في أول طلب سحب)
- افصل المستودع إلى حسابك قبل إجراء التغييرات
- طلب واحد لكل تغيير منطقي (لا تدمج إصلاحات غير متعلقة)
- اجعل طلبات السحب مركزة وصغيرة قدر الإمكان

## سير العمل الشائعة

### إضافة مثال كود جديد

1. انتقل إلى مجلد الدرس المناسب
2. أنشئ المثال في المجلد الفرعي `python/` أو `typescript/`
3. اتبع اتفاقية التسمية: `{مزود}-{اسم-المثال}.{py|ts|js}`
4. اختبر باستخدام بيانات اعتماد API الفعلية
5. وثّق أي متغيرات بيئة جديدة في README الدرس

### تحديث التوثيق

1. عدّل README.md في مجلد الدرس
2. اتبع إرشادات Markdown (معرفات التتبع، الروابط النسبية)
3. تحديث الترجمات يتم عبر GitHub Actions (لا تعدل يدويًا)
4. تحقق من صلاحية كل الروابط

### العمل مع حاويات التطوير

1. يحتوي المستودع على `.devcontainer/devcontainer.json`
2. سكريبت ما بعد الإنشاء يثبت تبعيات بايثون تلقائيًا
3. ملحقات بايثون وJupyter مُعدة مسبقًا
4. البيئة مبنية على `mcr.microsoft.com/devcontainers/universal:2.11.2`

## النشر والنشر

هذا مستودع تعليمي - لا يوجد عملية نشر. يتم استهلاك المنهج بواسطة:

1. **مستودع GitHub**: وصول مباشر للكود والتوثيق
2. **GitHub Codespaces**: بيئة تطوير فورية مع إعداد مسبق
3. **Microsoft Learn**: قد يُنشر المحتوى على منصة التعلم الرسمية
4. **docsify**: موقع توثيق مبني من Markdown (انظر `docsifytopdf.js` و`package.json`)

### بناء موقع التوثيق

```bash
# إنشاء ملف PDF من الوثائق (إذا لزم الأمر)
npm run convert
```

## استكشاف الأخطاء وإصلاحها

### المشاكل الشائعة

**أخطاء استيراد بايثون**:
- تأكد من تفعيل البيئة الافتراضية
- شغّل `pip install -r requirements.txt`
- تحقق من أن نسخة بايثون 3.9+

**أخطاء بناء تايبسكريبت**:
- شغّل `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)
- [Discord الخاص بـ 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
- المحتوى متعدد اللغات مع سير عمل الترجمة الآلية
- مجتمع نشط على Discord للأسئلة والدعم

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**تنويه**:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->