مسار مهندس الذكاء الاصطناعي وبيئات التطوير باستخدام uv

المشكلة التي نقوم بحلها

ينضم مهندس ذكاء اصطناعي جديد إلى الفريق. مهمة اليوم الأول بسيطة: تشغيل المشروع على حاسوبه المحمول. يقول ملف التعليمات (README): "شغّل الأمر python main.py". يقوم بتشغيله، فتظهر له رسالة الخطأ: ModuleNotFoundError: No module named 'httpx'. ولكن على جهاز الزميل الذي كتب المشروع، يعمل الأمر نفسه بلا أي مشكلة.

عند البحث والتحقق، يتضح أنه على مدار عامين، كانت كل حزمة يحتاجها أي مشروع على جهاز الكاتب تتراكم في نفس نسخة بايثون العامة على النظام. لا يوجد أي مكان مكتوب فيه ما هي الحزم التي يعتمد عليها هذا المشروع بالتحديد — الشعار الوحيد كان "الكود يعمل على جهازي!". يقضي الزميل الجديد نصف يوم في البحث عن الحزم وتثبيتها حزمة تلو الأخرى، وفي النهاية يثبت إحداها بإصدار مختلف، فتختلف النتائج عما هو متوقع.

لدى الفرق البرمجية المحترفة حل قاطع لهذه المعضلة: يحصل كل مشروع على بيئة عمل معزولة خاصة به، وتُسجل محتويات هذه البيئة بدقة داخل ملف، بحيث يمكن لأي شخص بناء البيئة نفسها تماماً بأمر واحد فقط. هذا هو ما سنبنيه في هذا الفصل — باستخدام أداة uv — وهو الأساس الذي سنعتمده في بقية مسار هذا التدريب.

بنهاية هذا الفصل ستكون قادراً على

• تثبيت بايثون باستخدام مثبت البرامج العادي وعبر الأمر uv python install، وتوضيح الفارق بين الطريقتين
• شرح ماهية pip ولماذا نستخدم uv بديلاً عنه في هذه الدورة
• إنشاء بيئة مشروع معزولة وتشغيلها باستخدام uv init وuv add وuv run وuv venv
• إثبات سبب خطورة تشغيل المشاريع على بايثون النظام من خلال مثال عملي
• تحديد مفسر بايثون الخاص بالمشروع داخل محرر VS Code أو PyCharm

المتطلبات المسبقة: القدرة على التنقل بين المجلدات في الطرفية (cd) وتشغيل الأوامر. هذا هو الفصل الأول من الدورة، لذا لا تحتاج إلى أي متطلبات أخرى.

كيف يعمل هذا المسار التعليمي

هذه الدورة هي مسار مهني متكامل. كل فصل يمثل درساً عملياً، وينتهي بمهمة تطبيقية تشغلها على جهازك الخاص. تضع الفصول الأولى حجر الأساس للعمل الاحترافي — بيئات التطوير، وإدارة النسخ بـ Git، وهيكلة المشاريع، وإدارة الإعدادات. تليها كتابة أكواد بايثون نظيفة، والاختبارات الآلية، والواجهات البرمجية (APIs)، وقواعد البيانات، وتقنيات RAG، والأمان، والنشر السحابي.

هناك حقيقة يجدر توضيحها منذ البداية: في بيئات العمل الاحترافية، لا يُقبل كود مهندس الذكاء الاصطناعي لمجرد أنه "يعمل". قدرة شخص آخر على تشغيله على جهازه، وقابلية الكود للمراجعة والتدقيق، وقدرة الفريق على فهمه بعد ستة أشهر — كل هذه متطلبات جوهرية في صميم الوظيفة. لذلك، صُممت كل مهمة عملية في هذه الدورة وكأنها متجهة مباشرة إلى مستودع كود لفريق عمل حقيقي. والخطوة الأولى في هذه الممارسة الاحترافية تبدأ من بيئة العمل.

تثبيت بايثون: طريقان متاحان

الطريق الأول — المثبت التقليدي (Normal Installer). قم بتنزيل مثبت بايثون 3.12 من موقع python.org وتشغيله. على نظام ويندوز، ضع علامة صح على خيار Add python.exe to PATH في الشاشة الأولى مباشرة؛ فبدونه لن تتعرف الطرفية على أمر python. على نظام macOS، يكفي تشغيل حزمة .pkg من موقع python.org. وعلى نظام لينكس، غالباً ما يكون python3 مثبتاً بالفعل — وهناك تنبيه مهم بخصوصه في الفقرات القادمة.

للتحقق من التثبيت:

python --version
Python 3.12.0

على macOS ولينكس غالباً ما يكون الأمر python3 --version.

الطريق الثاني — باستخدام uv. أداة uv هي أداة شاملة وموحدة تتولى إدارة إصدارات بايثون، وبيئات المشاريع، وتثبيت الحزم. قم بتثبيت uv أولاً. على macOS ولينكس:

curl -LsSf https://astral.sh/uv/install.sh | sh

في نافذة PowerShell على ويندوز:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

ثم افتح نافذة طرفية جديدة:

uv --version
uv 0.9.1 (9887ef5bd 2025-10-09)

قد يختلف رقم الإصدار على جهازك. الآن، نثبت بايثون عبرها:

uv python install 3.12
Installed Python 3.12.11 in 27.42s
 + cpython-3.12.11-windows-x86_64-none (python3.12.exe)

سيختلف وقت التثبيت واسم المنصة حسب جهازك. لاحظ أن نسخة بايثون التي ثبتتها uv تستقر في مجلد خاص بها — فهي لا تلمس بايثون الأساسي للنظام، ولا تغير متغير PATH العام.

يمكن للطريقين التعايش معاً بسلام، وكلاهما يعمل في هذه الدورة. الفارق الجوهري: المثبت التقليدي يمنحك نسخة بايثون واحدة للنظام بأكمله؛ بينما يمنحك uv python install نسخ بايثون تختار منها المشاريع بحسب حاجتها. مشروع يحتاج 3.12، وآخر يحتاج 3.13 — دون أن يتعارض أحدهما مع الآخر.

ما هي أداة pip، ولماذا نستخدم uv؟

تستقر الحزم الخارجية لبايثون — مثل httpx وpydantic وfastapi — في مستودع عام يُدعى PyPI. الأداة التقليدية لجلبها وتثبيتها هي pip، التي تأتي مدمجة مع بايثون. تكاد كل الشروحات على الإنترنت تقول pip install ....

تعمل pip بشكل جيد، لكنها تؤدي وظيفة واحدة فقط: تثبيت الحزم. وهي تثبتها داخل مفسر بايثون الذي قمت بتشغيلها بواسطته مباشرة. في المشاريع الاحترافية، كان كل متطلب إضافي يستلزم أداة منفصلة:

• الحصول على إصدار بايثون المناسب — أداة منفصلة
• إنشاء البيئة المعزولة وتفعيلها — أمر python -m venv، ثم كتابة أمر التفعيل activate يدوياً
• تسجيل متطلبات المشروع واعتمادياته — يدوياً داخل ملف، وغالباً ما يُنسى ذلك
• تثبيت وتحديد الإصدار الدقيق لكل حزمة فرعية (ملف القفل lockfile) — أداة إضافية أخرى

تقوم uv بكل هذه المهام الأربع في أداة واحدة فائقة السرعة. والأهم من ذلك: عندما تضيف أي حزمة باستخدام uv add، يتم تدوينها داخل ملف إعدادات المشروع تلقائياً. مشكلة "لقد ثبتت الحزمة لكن نسيت كتابتها في الملف" — وهي السبب الجذري لمشكلة الزميل الجديد المذكورة في البداية — تصبح مستحيلة الحدوث.

لذا، كلما ورد ذكر الحزم أو البيئات في هذا المسار، سنعتمد على uv. وحينما ترى في أي مرجع آخر أمر pip install، فإن المقابل الاحترافي له مع uv هو uv add.

لماذا لا نثبت حزم المشاريع على بايثون النظام مباشرة؟

"بايثون النظام" (System Python) هو مفسر بايثون المثبت مباشرة على الحاسوب — وهو الذي يعمل عند كتابة python في الطرفية دون تفعيل أي بيئة مخصصة. تثبيت حزم المشاريع بداخله يسبب ثلاث مشاكل رئيسية:

1. الجميع يتشاركون نفس الغرفة. مشروع يحتاج إلى pydantic الإصدار 1، ومشروع آخر يحتاج الإصدار 2. لا يستوعب بايثون النظام إلا إصداراً واحداً، وتحديث أحد المشروعين سيعطل الآخر حتماً.
2. الاعتماديات تصبح غير مرئية. قد تكون الحزمة مثبتة مسبقاً لمشروع قديم، فيعمل المشروع الجديد بنجاح — رغم أنه لا يوجد في ملفات المشروع أي ذكر لحاجته لتلك الحزمة! لن يظهر أي خطأ على جهازك؛ بل سيقع الخطأ على جهاز زميلك، أو على خادم الإنتاج.
3. نظام التشغيل يعتمد عليه. في macOS ولينكس، تعتمد بعض أدوات النظام الأساسية على مفسر بايثون هذا. التلاعب بحزمه قد يعطل وظائف في نظام التشغيل — ولهذا تمنع توزيعات لينكس الحديثة التثبيت المباشر في بايثون النظام.

المشكلة الثانية هي الأكثر خطورة لأنها تحدث بصمت. على الجهاز الذي كُتب عليه هذا الفصل، يحتوي بايثون النظام على بقايا حزم قديمة مثل httpx وpydantic وrich. وبالتالي، فإن أي سكريبت "يعمل" هناك — وهذا تحديداً هو السبب في استحالة معرفة ما يحتاجه السكريبت فعلياً من مجرد تشغيله هناك.

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

مشروعنا الأول باستخدام uv

افتح الطرفية في مجلد عملك:

uv init hello-ai --python 3.12
Initialized project `hello-ai` at `D:\ai-lab\hello-ai`

(سيكون المسار في النهاية هو مسار مجلدك الخاص؛ تم اختصار المسارات في هذه الأمثلة). يُنشئ أمر uv init مجلداً جديداً، ويضع بداخله:

hello-ai/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

الملف الأهم بين هذه الملفات هو pyproject.toml — وهو بمثابة بطاقة هوية المشروع:

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

السطر dependencies = [] يعني أن المشروع لا يحتاج حالياً إلى أي حزم خارجية. يحتوي ملف .python-version على 3.12 فقط: لتحديد إصدار بايثون المعتمد لهذا المشروع. وقد قام أمر uv init بإنشاء مستودع Git وملف .gitignore تلقائياً — وسنتعرف على دورهما في الفصل التالي.

والآن، لنشغّل المشروع:

cd hello-ai
uv run main.py
Using CPython 3.12.11
Creating virtual environment at: .venv
Hello from hello-ai!

في المرة الأولى، أنشأ أمر uv run مجلد .venv من تلقاء نفسه — وتلك هي البيئة المعزولة للمشروع — ثم شغّل main.py باستخدام مفسر بايثون الخاص بتلك البيئة. لم تضطر إلى تفعيل أي شيء يدوياً.

uv add: إضافة حزمة وتوثيقها تلقائياً

يحتاج كل مشروع لمهندس الذكاء الاصطناعي تقريباً إلى استدعاء واجهات برمجية (APIs)، لذا ستكون أول حزمة نضيفها هي عميل HTTP الشهير httpx، بالإضافة إلى python-dotenv لقراءة ملفات الإعدادات .env:

uv add httpx python-dotenv
Resolved 9 packages in 119ms
Installed 8 packages in 92ms
 + anyio==4.15.1
 + certifi==2026.7.22
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.20
 + python-dotenv==1.2.3
 + typing-extensions==4.16.0

لقد طلبت تثبيت حزمتين وحصلت على ثماني حزم — الحزم الست الأخرى هي الاعتماديات الفرعية لحزمة httpx، والتي قامت uv باكتشافها وتنزيلها تلقائياً. قد تختلف أرقام الإصدارات قليلاً عند تطبيقك للتمرين.

الآن ألقِ نظرة على ملف pyproject.toml:

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.28.1",
    "python-dotenv>=1.2.3",
]

قام أمر واحد بثلاثة أشياء دفعة واحدة: تم تثبيت الحزم داخل بيئة .venv، وتوثيق حاجة المشروع إليها في pyproject.toml، وإنشاء ملف جديد باسم uv.lock يحدد الإصدارات الدقيقة للحزم الثماني جميعها. سنفصل الحديث عن ملفات القفل (lockfiles) لاحقاً في الدورة؛ ويكفيك الآن أن تعلم أن أي زميل ينسخ مستودع المشروع ويشغل أمر uv sync سيحصل بدقة متناهية على نفس هذه الإصدارات الثمانية.

ولحذف أي حزمة، نستخدم أمر uv remove:

uv remove python-dotenv
Resolved 8 packages in 21ms
Uninstalled 1 package in 11ms
 - python-dotenv==1.2.3

يعمل هذا الأمر في الاتجاهين أيضاً: يحذف الحزمة من بيئة .venv ويزيلها من ملف pyproject.toml.

uv venv والتفعيل اليدوي

يتكفل أمر uv run بإنشاء البيئة واستخدامها تلقائياً، وهو ما يكفينا تماماً في معظم مراحل هذه الدورة. لكن في بعض الأحيان قد تحتاج فقط إلى إنشاء بيئة افتراضية فارغة — على سبيل المثال في مشروع قديم لا يحتوي على ملف pyproject.toml. حينها يمكنك كتابة:

uv venv --python 3.12
Using CPython 3.12.11
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

السطر الأخير في المخرجات مخصص لنافذة PowerShell في ويندوز. وهنا يكمن الاختلاف بين أنظمة التشغيل:

# Windows (PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

بمجرد التفعيل، سيبدأ سطر الأوامر بظهور (hello-ai) أو (.venv)، وسيؤدي أمر python العادي إلى تشغيل مفسر بايثون التابع لتلك البيئة المعزولة. للخروج منها، اكتب deactivate. وتذكر أنه مع uv run لست بحاجة لأي من هذه الخطوات — وهذه ميزته الكبرى، كما أن كتابة uv run في ملف إرشادات الفريق هو الخيار الأكثر أماناً لضمان عدم نسيان التفعيل.

توجيه المحرر إلى بايثون الخاص بالمشروع

يعمل البرنامج بنجاح من الطرفية، ومع ذلك يظهر في المحرر خط أحمر تحذيري تحت السطر import httpx — هذا يعني غالباً أن المحرر يستعين بمفسر بايثون مختلف عن مفسر المشروع.

في VS Code: ثبّت إضافة Python الرسمية من مايكروسوفت. ثم افتح مجلد المشروع، واضغط Ctrl + Shift + P (أو Cmd + Shift + P على macOS) ← اختر Python: Select Interpreter ← ثم حدد مفسر بايثون الموجود داخل مجلد .venv. إذا لم يظهر في القائمة، اختر Enter interpreter path وحدد المسار يدوياً: .venv\Scripts\python.exe في ويندوز، أو .venv/bin/python في macOS ولينكس.

في PyCharm: اذهب إلى Settings ← Project ← Python Interpreter ← Add Interpreter ← Add Local Interpreter ← اختر بيئة موجودة مسبقاً (Existing) وحدد المسار نفسه. في الإصدارات الأحدث، يوفر بيشارم خيار بيئة uv بشكل مباشر.

للتأكد تماماً من المفسر الذي يستخدمه المحرر، يمكنك تشغيل الكود التالي في الطرفية المدمجة داخل المحرر:

import sys

print(sys.executable)

يجب أن ينتهي المسار داخل مجلد .venv الخاص بمشروعك — على سبيل المثال ...\hello-ai\.venv\Scripts\python.exe. تعتمد بداية المسار على موقع مجلدك، لذا لم نعرض المسار الكامل هنا.

مثال عملي كامل

داخل مشروع hello-ai، أنشئ ملفاً باسم env_check.py. هذا سكريبت مصغر "لفحص البيئة" — عندما ينضم شخص جديد للفريق، فإن تشغيل مثل هذا السكريبت أولاً يؤكد أن كل شيء تم ضبطه كما ينبغي:

import sys
from importlib.metadata import version
from pathlib import Path


def main() -> None:
    in_venv = sys.prefix != sys.base_prefix
    print(f"Python      : {sys.version_info.major}.{sys.version_info.minor}")
    print(f"In a venv   : {in_venv}")
    print(f"Env folder  : {Path(sys.prefix).name}")

    import httpx  # installed with `uv add httpx`

    print(f"httpx       : {version('httpx')}")
    print(f"Client ready: {httpx.Client is not None}")
    print("Hello, AI engineer.")


if __name__ == "__main__":
    main()

شغّل الملف من داخل مجلد المشروع:

uv run env_check.py

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

الآن، دعنا نشغل الملف نفسه في بيئة فارغة. تم نسخ الملف إلى مجلد آخر، وإنشاء بيئة هناك عبر uv venv --python 3.12، ثم تشغيل الملف مباشرة بواسطة مفسر بايثون الخاص بتلك البيئة (.venv\Scripts\python env_check.py في ويندوز، أو .venv/bin/python env_check.py في macOS ولينكس):

Python      : 3.12
In a venv   : True
Env folder  : .venv
Traceback (most recent call last):
  File "env_check.py", line 20, in <module>
    main()
  File "env_check.py", line 12, in main
    import httpx  # installed with `uv add httpx`
    ^^^^^^^^^^^^
ModuleNotFoundError: No module named 'httpx'

(على جهازك سيعرض تتبع الخطأ المسار الكامل للملف؛ تم الاكتفاء باسم الملف هنا).

هناك تفاصيل وتصميمات مقصودة في هذا السكريبت تستحق الانتباه:

sys.prefix != sys.base_prefix — بايثون نفسه يعلم ما إذا كان يعمل داخل بيئة افتراضية أم لا. يمثل sys.base_prefix مسار بايثون الأساسي الذي أُنشئت منه البيئة، بينما يمثل sys.prefix مسار المفسر الفعلي الذي يعمل حالياً. إذا اختلف المساران، فأنت حتماً داخل بيئة افتراضية.

اسم المجلد، وليس المسار الكامل — يطبع Path(sys.prefix).name الجزء الأخير فقط من المسار، وهو .venv. المسار الكامل يختلف من جهاز لآخر؛ بينما الاسم يظل ثابتاً لدى الجميع. كلما كانت مخرجات سكريبت الفحص مستقلة عن خصوصية الجهاز، كان من الأسهل مقارنتها في محادثات الفريق الفنية.

import httpx في منتصف الدالة — من المعتاد وضع الاستدعاءات في أعلى الملف دائماً، وهذا هو الأصل. لكننا تعمدنا وضعه هنا في المنتصف، حتى تتم طباعة الأسطر الثلاثة الأولى قبل وقوع الخطأ عند تشغيله في بيئة فارغة. تخبرنا رسالة الخطأ بالقصة كاملة: إصدار بايثون 3.12 سليم، والبيئة مفعلة، لكن البيئة تفتقر إلى حزمة httpx. والحل هو uv add httpx — أو تشغيل uv sync إذا كان ملف pyproject.toml يتضمنها بالفعل.

version('httpx') — مكتبة importlib.metadata هي الطريقة القياسية المعتمدة لقراءة إصدار أي حزمة. فليس كل الحزم توفر متغير __version__، ولكن كل حزمة مثبتة تمتلك بيانات وصفية (metadata).

عند حدوث مشاكل شائعة

The term 'uv' is not recognized as the name of a cmdlet, function, script file, or operable program (أو uv: command not found في macOS/لينكس) أداة uv مثبتة، لكن نافذة الطرفية التي تكتب فيها كانت مفتوحة قبل عملية التثبيت، ولذا لم تتعرف على مسار PATH الجديد. أغلق الطرفية وأعد فتحها (وفي VS Code، أعد تشغيل المحرر بالكامل).

error: No pyproject.toml found in current directory or any parent directory لقد نفذت أمر uv add خارج مجلد المشروع. يكتب أمر uv add في ملف المشروع، وبدون وجود مشروع لا يجد مكاناً للكتابة فيه. انتقل إلى مجلد المشروع باستخدام cd، أو أنشئ المشروع أولاً باستخدام uv init.

ModuleNotFoundError: No module named 'httpx' مفسر بايثون الذي يشغل السكريبت لا يحتوي على الحزمة. هناك سببان شائعان: إما أن الحزمة لم تُضف إطلاقاً باستخدام uv add، أو أن السكريبت تم تشغيله بأمر python العادي بدلاً من uv run، مما جعل بايثون النظام هو الذي يعمل بدلاً من بيئة المشروع. شغّله عبر uv run env_check.py.

error: Failed to spawn: hello.py متبوعة بـ Caused by: program not found لقد مررت إلى أمر uv run اسم ملف غير موجود في المجلد الحالي — غالباً بسبب خطأ إملائي في كتابة الاسم، أو لوجودك في مجلد خاطئ. عندما لم تجد uv الملف، بحثت عن برنامج تنفيذي يحمل هذا الاسم، ولهذا بدت رسالة الخطأ غير مألوفة.

× No solution found when resolving dependencies متبوعة بـ Because htpx was not found in the package registry ... خطأ مطبعي في اسم الحزمة (htpx بدلاً من httpx). النقطة الإيجابية هي أن فشل أمر uv add لا يغير أي شيء على الإطلاق — يظل ملفا pyproject.toml وuv.lock سليمين كما كانا. صحح الاسم وأعد المحاولة.

.venv\Scripts\activate : File ... cannot be loaded because running scripts is disabled on this system سياسة أمان في PowerShell. نفّذ الأمر Set-ExecutionPolicy -Scope CurrentUser RemoteSigned مرة واحدة وافتح طرفية جديدة — أو تجاوز خطوة التفعيل اليدوي وشغّل كل شيء باستخدام uv run.

دورك الآن

بعد أن جهزت uv وبايثون 3.12 على جهازك، أنشئ مشروعاً جديداً:

1. أنشئ المشروع بالأمر uv init my-first-agent --python 3.12، ثم أضف حزمة واحدة عبر uv add httpx
2. اكتب كود ملف env_check.py الموضح أعلاه داخل المشروع تماماً كما هو، ثم شغّله باستخدام uv run env_check.py
3. افتح ملف pyproject.toml وتحقق من إدراج httpx تحت بند dependencies، وتأكد من ظهور ملف uv.lock في المشروع
4. افتح المشروع في VS Code أو PyCharm، واختر بيئة .venv التابعة للمشروع كمفسر لبايثون، بحيث يختفي أي خط أحمر تحذيري تحت السطر import httpx

المخرجات المتوقعة (قد يكون إصدار httpx أحدث عند قيامك بالتجربة):

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

بعد ذلك، تعمّد تعطيل المشروع لرؤية النتيجة: نفّذ الأمر uv remove httpx ثم أعد تشغيل uv run env_check.py. دوّن ما تم طباعته قبل التوقف، ورسالة الخطأ التي ظهرت، وما الذي تغير في ملف pyproject.toml. ثم أصلح الأمر مجدداً عبر uv add httpx. تستغرق دورة "الإفساد والإصلاح" هذه دقيقتين فقط، لكنها في أسبوعك الأول في أي وظيفة ستكون أكثر مهارة توفر عليك ساعات من العناء.