15 KiB

Raw Blame History

AGENTS.md

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

هذا هو تعلم الآلة للمبتدئين، منهج شامل لمدة 12 أسبوعًا يتضمن 26 درسًا يغطي مفاهيم تعلم الآلة الكلاسيكية باستخدام Python (بشكل أساسي مع Scikit-learn) وR. تم تصميم المستودع كمورد تعليمي ذاتي مع مشاريع عملية، اختبارات، وتمارين. يستكشف كل درس مفاهيم تعلم الآلة من خلال بيانات واقعية من ثقافات ومناطق مختلفة حول العالم.

المكونات الرئيسية:

المحتوى التعليمي: 26 درسًا تغطي مقدمة في تعلم الآلة، الانحدار، التصنيف، التجميع، معالجة اللغة الطبيعية، السلاسل الزمنية، والتعلم المعزز
تطبيق الاختبارات: تطبيق اختبارات يعتمد على Vue.js مع تقييمات قبل وبعد الدرس
دعم متعدد اللغات: ترجمات تلقائية لأكثر من 40 لغة عبر GitHub Actions
دعم لغتين: الدروس متوفرة باللغتين Python (دفاتر Jupyter) وR (ملفات R Markdown)
تعلم قائم على المشاريع: كل موضوع يتضمن مشاريع عملية وتمارين

هيكل المستودع

ML-For-Beginners/
├── 1-Introduction/         # ML basics, history, fairness, techniques
├── 2-Regression/          # Regression models with Python/R
├── 3-Web-App/            # Flask web app for ML model deployment
├── 4-Classification/      # Classification algorithms
├── 5-Clustering/         # Clustering techniques
├── 6-NLP/               # Natural Language Processing
├── 7-TimeSeries/        # Time series forecasting
├── 8-Reinforcement/     # Reinforcement learning
├── 9-Real-World/        # Real-world ML applications
├── quiz-app/           # Vue.js quiz application
├── translations/       # Auto-generated translations
└── sketchnotes/       # Visual learning aids

عادةً ما يحتوي مجلد الدرس على:

README.md - محتوى الدرس الرئيسي
notebook.ipynb - دفتر Jupyter بلغة Python
solution/ - كود الحل (إصدارات Python وR)
assignment.md - تمارين عملية
images/ - موارد بصرية

أوامر الإعداد

لدروس Python

تستخدم معظم الدروس دفاتر Jupyter. قم بتثبيت التبعيات المطلوبة:

# Install Python 3.8+ if not already installed
python --version

# Install Jupyter
pip install jupyter

# Install common ML libraries
pip install scikit-learn pandas numpy matplotlib seaborn

# For specific lessons, check lesson-specific requirements
# Example: Web App lesson
pip install flask

لدروس R

دروس R موجودة في مجلدات solution/R/ كملفات .rmd أو .ipynb:

# Install R and required packages
# In R console:
install.packages(c("tidyverse", "tidymodels", "caret"))

لتطبيق الاختبارات

تطبيق الاختبارات هو تطبيق Vue.js موجود في دليل quiz-app/:

cd quiz-app
npm install

لموقع التوثيق

لتشغيل التوثيق محليًا:

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

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

العمل مع دفاتر الدروس

انتقل إلى دليل الدرس (مثل 2-Regression/1-Tools/)
افتح دفتر Jupyter:
```
jupyter notebook notebook.ipynb
```
اعمل على محتوى الدرس والتمارين
تحقق من الحلول في مجلد solution/ إذا لزم الأمر

تطوير Python

تستخدم الدروس مكتبات Python القياسية لتحليل البيانات
دفاتر Jupyter للتعلم التفاعلي
كود الحل متوفر في مجلد solution/ لكل درس

تطوير R

دروس R تأتي بصيغة .rmd (R Markdown)
الحلول موجودة في مجلدات فرعية solution/R/
استخدم RStudio أو Jupyter مع نواة R لتشغيل دفاتر R

تطوير تطبيق الاختبارات

cd quiz-app

# Start development server
npm run serve
# Access at http://localhost:8080

# Build for production
npm run build

# Lint and fix files
npm run lint

تعليمات الاختبار

اختبار تطبيق الاختبارات

cd quiz-app

# Lint code
npm run lint

# Build to verify no errors
npm run build

ملاحظة: هذا المستودع مخصص بشكل أساسي للتعليم. لا توجد اختبارات تلقائية لمحتوى الدروس. يتم التحقق من الصحة من خلال:

إكمال تمارين الدروس
تشغيل خلايا الدفاتر بنجاح
مقارنة النتائج مع الحلول المتوقعة

إرشادات أسلوب الكود

كود Python

اتبع إرشادات أسلوب PEP 8
استخدم أسماء متغيرات واضحة وموصوفة
أضف تعليقات للعمليات المعقدة
يجب أن تحتوي دفاتر Jupyter على خلايا Markdown تشرح المفاهيم

JavaScript/Vue.js (تطبيق الاختبارات)

يتبع دليل أسلوب Vue.js
تكوين ESLint في quiz-app/package.json
قم بتشغيل npm run lint للتحقق من المشكلات وإصلاحها تلقائيًا

التوثيق

يجب أن تكون ملفات Markdown واضحة ومنظمة بشكل جيد
تضمين أمثلة الكود في كتل الكود المحددة
استخدام الروابط النسبية للإشارات الداخلية
اتباع الاتفاقيات التنسيقية الحالية

البناء والنشر

نشر تطبيق الاختبارات

يمكن نشر تطبيق الاختبارات على Azure Static Web Apps:

المتطلبات الأساسية:
- حساب Azure
- مستودع GitHub (تم نسخه بالفعل)
النشر على Azure:
- إنشاء مورد Azure Static Web App
- الاتصال بمستودع GitHub
- تحديد موقع التطبيق: /quiz-app
- تحديد موقع الإخراج: dist
- يقوم Azure تلقائيًا بإنشاء سير عمل GitHub Actions
سير عمل GitHub Actions:
- يتم إنشاء ملف سير العمل في .github/workflows/azure-static-web-apps-*.yml
- يتم البناء والنشر تلقائيًا عند الدفع إلى الفرع الرئيسي

وثيقة PDF

إنشاء PDF من التوثيق:

npm install
npm run convert

سير عمل الترجمة

هام: يتم تنفيذ الترجمات تلقائيًا عبر GitHub Actions باستخدام Co-op Translator.

يتم إنشاء الترجمات تلقائيًا عند دفع التغييرات إلى الفرع main
لا تقم بترجمة المحتوى يدويًا - النظام يتولى ذلك
يتم تعريف سير العمل في .github/workflows/co-op-translator.yml
يستخدم خدمات Azure AI/OpenAI للترجمة
يدعم أكثر من 40 لغة

إرشادات المساهمة

للمساهمين في المحتوى

قم بنسخ المستودع وأنشئ فرعًا جديدًا
قم بإجراء تغييرات على محتوى الدرس إذا كنت تضيف أو تحدث الدروس
لا تقم بتعديل الملفات المترجمة - يتم إنشاؤها تلقائيًا
اختبر الكود الخاص بك - تأكد من تشغيل جميع خلايا الدفاتر بنجاح
تحقق من الروابط والصور للتأكد من عملها بشكل صحيح
قدم طلب سحب مع وصف واضح

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

تنسيق العنوان: [القسم] وصف مختصر للتغييرات
- مثال: [Regression] تصحيح خطأ في الدرس 5
- مثال: [Quiz-App] تحديث التبعيات
قبل التقديم:
- تأكد من تنفيذ جميع خلايا الدفاتر دون أخطاء
- قم بتشغيل npm run lint إذا كنت تعدل تطبيق الاختبارات
- تحقق من تنسيق Markdown
- اختبر أي أمثلة كود جديدة
يجب أن يتضمن طلب السحب:
- وصف التغييرات
- سبب التغييرات
- لقطات شاشة إذا كانت هناك تغييرات في واجهة المستخدم
مدونة السلوك: اتبع مدونة قواعد السلوك مفتوحة المصدر من Microsoft
CLA: ستحتاج إلى توقيع اتفاقية ترخيص المساهم

هيكل الدرس

يتبع كل درس نمطًا ثابتًا:

اختبار ما قبل المحاضرة - اختبار المعرفة الأساسية
محتوى الدرس - تعليمات وشروحات مكتوبة
عروض الكود - أمثلة عملية في الدفاتر
فحوصات المعرفة - التحقق من الفهم خلال الدرس
التحدي - تطبيق المفاهيم بشكل مستقل
التمرين - ممارسة موسعة
اختبار ما بعد المحاضرة - تقييم نتائج التعلم

مرجع الأوامر الشائعة

# Python/Jupyter
jupyter notebook                    # Start Jupyter server
jupyter notebook notebook.ipynb     # Open specific notebook
pip install -r requirements.txt     # Install dependencies (where available)

# Quiz App
cd quiz-app
npm install                        # Install dependencies
npm run serve                      # Development server
npm run build                      # Production build
npm run lint                       # Lint and fix

# Documentation
docsify serve                      # Serve documentation locally
npm run convert                    # Generate PDF

# Git workflow
git checkout -b feature/my-change  # Create feature branch
git add .                         # Stage changes
git commit -m "Description"       # Commit changes
git push origin feature/my-change # Push to remote

موارد إضافية

مجموعة Microsoft Learn: وحدات تعلم الآلة للمبتدئين
تطبيق الاختبارات: اختبارات عبر الإنترنت
لوحة المناقشة: مناقشات GitHub
مقاطع الفيديو التوضيحية: قائمة تشغيل YouTube

التقنيات الرئيسية

Python: اللغة الأساسية لدروس تعلم الآلة (Scikit-learn، Pandas، NumPy، Matplotlib)
R: تنفيذ بديل باستخدام tidyverse، tidymodels، caret
Jupyter: دفاتر تفاعلية لدروس Python
R Markdown: مستندات لدروس R
Vue.js 3: إطار عمل تطبيق الاختبارات
Flask: إطار عمل تطبيقات الويب لنشر نماذج تعلم الآلة
Docsify: مولد موقع التوثيق
GitHub Actions: CI/CD وترجمات تلقائية

اعتبارات الأمان

لا توجد أسرار في الكود: لا تقم أبدًا بتضمين مفاتيح API أو بيانات اعتماد
التبعيات: حافظ على تحديث حزم npm وpip
مدخلات المستخدم: أمثلة تطبيقات الويب باستخدام Flask تتضمن تحققًا أساسيًا من المدخلات
البيانات الحساسة: مجموعات البيانات المستخدمة عامة وغير حساسة

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

دفاتر Jupyter

مشاكل النواة: أعد تشغيل النواة إذا توقفت الخلايا: Kernel → Restart
أخطاء الاستيراد: تأكد من تثبيت جميع الحزم المطلوبة باستخدام pip
مشاكل المسار: قم بتشغيل الدفاتر من الدليل الذي يحتوي عليها

تطبيق الاختبارات

فشل تثبيت npm: قم بمسح ذاكرة التخزين المؤقت لـ npm: npm cache clean --force
تعارض المنافذ: قم بتغيير المنفذ باستخدام: npm run serve -- --port 8081
أخطاء البناء: احذف node_modules وأعد التثبيت: rm -rf node_modules && npm install

دروس R

الحزمة غير موجودة: قم بالتثبيت باستخدام: install.packages("package-name")
عرض RMarkdown: تأكد من تثبيت حزمة rmarkdown
مشاكل النواة: قد تحتاج إلى تثبيت IRkernel لـ Jupyter

ملاحظات خاصة بالمشروع

هذا في الأساس منهج تعليمي وليس كود إنتاج
التركيز على فهم مفاهيم تعلم الآلة من خلال الممارسة العملية
أمثلة الكود تركز على الوضوح بدلاً من التحسين
معظم الدروس مستقلة ويمكن إكمالها بشكل منفصل
الحلول متوفرة ولكن يجب على المتعلمين محاولة حل التمارين أولاً
يستخدم المستودع Docsify لتوثيق الويب بدون خطوة البناء
Sketchnotes توفر ملخصات بصرية للمفاهيم
الدعم متعدد اللغات يجعل المحتوى متاحًا عالميًا

إخلاء المسؤولية:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي Co-op Translator. بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق. للحصول على معلومات حاسمة، يُوصى بالترجمة البشرية الاحترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.

15 KiB Raw Blame History