مستودع تمارين وواجبات AIE2026

يُستخدم هذا المستودع لتمارين وواجبات AI Engineering Pilot Course ‏(AIE2026). ستعمل طوال المقرر على تطوير وكيل يدعم تعلم هندسة الذكاء الاصطناعي تدريجيًا.

البيئة المتوقعة

صُممت التمارين لتُنجَز بالكامل في المتصفح. لا تحتاج إلى تثبيت شيء على حاسوبك.

ما تحتاجه	الغرض	ملاحظات
حساب GitHub شخصي	إنشاء نسخة متفرعة من هذا المستودع وتسليم العمل عبر فرع عمل وPull Request	قد تقيّد الحسابات التي تديرها شركة أو مؤسسة تعليمية استخدام Codespaces وCopilot
GitHub Codespaces	بيئة التطوير لـ Lecture 01 وLecture 03 وLecture 05 وغيرها. يجهّز إعداد .devcontainer/ تلقائيًا حاوية تضم Python 3.12 وuv وNode.js	تتيح الحسابات الشخصية حصة مجانية قدرها 120 ساعة نواة شهريًا (نحو 60 ساعة بنواتين). أوقف Codespace عند الانتهاء
GitHub Copilot (تكفي الخطة المجانية Free)	إكمال الشيفرة والمحادثة. يُستخدم أيضًا كعميل MCP في الواجب المتقدم لـ Lecture 05	للخطة المجانية حدود شهرية لعمليات الإكمال والمحادثة
Gemini API (الحصة المجانية في Google AI Studio)	استدعاء النموذج اللغوي الكبير. أنشئ مفتاحًا باستخدام حساب Google شخصي ومرّره عبر سر Codespaces المسمى GEMINI_API_KEY	للحصة المجانية حدود لكل دقيقة ولكل يوم (راجع «الافتراضات والقيود» أدناه)
Google Colab (وحدة T4 GPU، الحصة المجانية)	يُستخدم فقط لتدريب LoRA في Lecture 02	مدة استخدام GPU محدودة. افصل بيئة التشغيل واحذفها عند الانتهاء

إذا أردت التشغيل محليًا على حاسوبك، فثبّت Python 3.12 وuv، ونفّذ uv sync --frozen، واضبط متغير البيئة GEMINI_API_KEY.

البدء (Lecture 01)

1. أنشئ نسخة Fork من هذا المستودع في حسابك
2. أنشئ مفتاح Gemini API في Google AI Studio
3. سجّل GEMINI_API_KEY ضمن GitHub Settings → Codespaces → Secrets، واختر نسختك المتفرعة ضمن المستودعات المسموح لها باستخدام السرّ
4. في نسختك المتفرعة، اختر Code → Codespaces → Create codespace on main
5. تحقق من عمل البيئة في الطرفية

uv run pytest -q
uv run python -m app.ask "ما هو LoRA؟"

راجع lectures/01/problem.md لمعرفة الخطوات بالتفصيل.

البنية

.devcontainer/   تعريف بيئة Codespaces ‏(Python 3.12 وuv وNode.js؛ ينفّذ uv sync --frozen عند البدء)
.github/workflows/test.yml  يشغّل الاختبارات لكل Pull Request (فعّل سير العمل في تبويب Actions داخل نسختك المتفرعة)
app/
  config.py      يقرأ اسم النموذج ومفتاح API
  ask.py         Lecture 01: يطرح سؤالًا على النموذج اللغوي الكبير
  tools.py       Lecture 03: أدوات الوكيل (مثل البحث في المسرد)
  agent.py       Lecture 03: وكيل لدعم التعلم باستخدام Pydantic AI (Lecture 05: عبر MCP مع --mcp)
  mcp_server.py  Lecture 05: خادم MCP يتيح المسرد
  mcp_servers.json Lecture 05: إعداد خوادم MCP المستخدمة (بصيغة mcpServers)
data/
  glossary.json  مسرد المقرر
  lectures/      النقاط الرئيسة لكل محاضرة
lectures/NN/
  problem.md     تمارين وواجبات المحاضرة
  answer.md      ملف تملؤه وتسلّمه
notebooks/       Lecture 02: دفتر LoRA لـ Google Colab (lora_format_tuning.ipynb)
scripts/         برامج مساعدة
tests/           اختبارات (لا تتطلب مفتاح API)
pyproject.toml / uv.lock  التبعيات وإصداراتها المثبّتة

كيفية التسليم

1. أنشئ فرع عمل لكل محاضرة (مثل git switch -c lec01)
2. أنجز التمارين والواجب واملأ lectures/NN/answer.md
3. ادفع التغييرات ثم أنشئ Pull Request من فرع العمل إلى main داخل نسختك المتفرعة

للواجب ثلاثة مستويات: «أساسي» و«تطبيقي» و«متقدم». يكفي إكمال مستوى واحد منها.

الافتراضات والقيود

• إصدارات التبعيات مثبّتة (في uv.lock: ‏Python 3.12 وpydantic-ai-slim 2.57.0 وgoogle-genai 2.31.0). لن نرفع إصداراتها أثناء المقرر. ثبّتها كما هي باستخدام uv sync --frozen.
• النموذج الافتراضي هو gemini-3.5-flash-lite. غيّره بمتغير البيئة AIE_MODEL (راجع «تغيير النموذج» أدناه). يمكنك أيضًا استخدام نماذج أخرى أو API باشتراكك الخاص
• للحصة المجانية من Gemini API حدود على معدل الطلبات. يستدعي الوكلاء (من Lecture 03 فصاعدًا) النموذج اللغوي الكبير عدة مرات للسؤال الواحد، فيصلون إلى الحد أسرع من Lecture 01. إذا ظهرت رسالة بلغت حد معدل الطلبات فانتظر نحو دقيقة. وإذا تكررت النموذج مشغول (503) فجرّب AIE_MODEL=gemini-3.1-flash-lite
• مرّر مفتاح API من خلال متغير البيئة GEMINI_API_KEY فقط. لا تلصقه في الشيفرة أو الالتزامات (commits) أو المحادثة. إذا تسرّب، فاحذفه من AI Studio وأنشئ مفتاحًا جديدًا
• يستطيع Codespaces الاتصال بالإنترنت، لكن لا يمكن للاتصالات الخارجية الدخول إلى Codespace (المنافذ المُحوَّلة خاصة افتراضيًا). شغّل خادم MCP الخاص بـ Lecture 05 داخل Codespaces
• تعمل الاختبارات (uv run pytest -q) دون مفتاح API (إذ تستخدم TestModel الذي لا يستدعي نموذجًا لغويًا كبيرًا)

قواعد ينبغي اتباعها

• لا تضع مفاتيح API في الشيفرة أو الالتزامات. مرّرها عبر أسرار Codespaces
• أوقف Codespaces عند الانتهاء. لن تتمكن من تشغيل Codespace بعد استنفاد الحصة المجانية
• يمكنك استخدام أدوات ذكاء اصطناعي مثل Copilot. اقرأ الشيفرة المقترحة وافهمها قبل قبولها

تغيير النموذج

النموذج الافتراضي هو gemini-3.5-flash-lite. يمكنك تغييره بمتغير البيئة AIE_MODEL.

AIE_MODEL=gemini-3.5-flash uv run python -m app.ask "ما هو LoRA؟"

للحصة المجانية حدود لعدد الطلبات في الدقيقة واليوم. راجع صفحة حدود معدل طلبات Gemini API لمعرفة هذه الحدود.