# التثبيت يستخدم هذا الدليل `conda` (عبر miniforge) لإدارة البيئات (موصى به). إذا كنت تفضل مدير بيئات آخر (مثل `uv`، `venv`)، فتأكد من وجود Python >=3.12، ثم انتقل مباشرة إلى [إعداد البيئة](#step-2-environment-setup). ## الخطوة 1 (لـ`conda` فقط): ثبّت [`miniforge`](https://conda-forge.org/download/) ```bash wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" bash Miniforge3-$(uname)-$(uname -m).sh ``` ## الخطوة 2: إعداد البيئة أنشئ بيئة افتراضية باستخدام Python 3.12: ```bash conda create -y -n lerobot python=3.12 ``` = 2.10 فقط)"> ```bash uv python install 3.12 uv venv --python 3.12 ``` ثم فعّل بيئة Python الافتراضية، حيث يجب عليك القيام بذلك في كل مرة تفتح فيها نافذة طرفية (shell) لاستخدام lerobot: ```bash conda activate lerobot ``` > [!NOTE] > عند تثبيت LeRobot داخل WSL (نظام Linux الفرعي لنظام Windows)، تأكد من تثبيت `evdev` أيضًا: > > ```bash > conda install evdev -c conda-forge > ``` = 2.10 فقط)"> ```bash # Linux/macOS source .venv/bin/activate # Windows PowerShell .venv\Scripts\activate ``` > [!NOTE] > عند تثبيت LeRobot داخل WSL (نظام Linux الفرعي لنظام Windows)، تأكد من تثبيت `evdev` أيضًا: > > ```bash > sudo apt install libevdev-dev > uv pip install evdev > ``` ### متطلبات المنصة على Apple Silicon، يتطلب PyTorch **macOS 14 أو أحدث**، وتسريع MPS يتطلب **macOS 15 أو أحدث** (على macOS 14، يعود LeRobot إلى المعالج المركزي CPU). على Linux، تحتاج عجلات PyTorch الافتراضية إلى برنامج تشغيل NVIDIA من الإصدار **580.65 أو أحدث**؛ أما بالنسبة لبرامج التشغيل الأقدم، فراجع [PyTorch CUDA variant](#pytorch-cuda-variant-linux-only). ### قم بتثبيت `ffmpeg` (للتفكيك الفيديوي) LeRobot uses [TorchCodec](https://github.com/meta-pytorch/torchcodec) for video decoding by default, which requires `ffmpeg`. > [!NOTE] > **دعم المنصات:** **غير متوفر** TorchCodec على macOS Intel (x86_64) أو Linux armv7l. على هذه المنصات، يتراجع LeRobot تلقائيًا إلى `pyav` — لذا لا تحتاج إلى تثبيت `ffmpeg` ويمكنك الانتقال مباشرة إلى الخطوة 3. > > **Jetson (aarch64 + CUDA):** يتم فك ترميز الفيديو على وحدة المعالجة المركزية (CPU) افتراضيًا. يبني [`docker/Dockerfile.jetson`](https://github.com/huggingface/lerobot/blob/main/docker/Dockerfile.jetson) مكتبتَي `torch`/`torchcodec` من المصدر مع دعم CUDA لنظام JetPack 6.2 — وهو مُدار من قبل المجتمع، راجع [`ravediamond/lerobot-jetson`](https://github.com/ravediamond/lerobot-jetson) للحصول على الصورة الجاهزة للاستخدام، والمشكلة [#819](https://github.com/huggingface/lerobot/issues/819) للاطلاع على الخلفية. إذا كانت منصتك تدعم TorchCodec، فقم بتثبيت `ffmpeg` باستخدام إحدى الطرق أدناه: قم بتثبيت `ffmpeg` في بيئة conda الخاصة بك. يعمل هذا مع **جميع إصدارات PyTorch** وهو **مطلوب لـ PyTorch < 2.10**: ```bash conda install ffmpeg -c conda-forge ``` > [!TIP] > عادةً ما يؤدي هذا إلى تثبيت `ffmpeg 8.X` مع مُشفّر `libsvtav1`. إذا واجهت مشاكل (مثل غياب `libsvtav1` — تحقق باستخدام `ffmpeg -encoders` — أو عدم توافق في الإصدار مع `torchcodec`)، يمكنك تثبيت `ffmpeg 7.1.1` بشكل صريح باستخدام: > > ```bash > conda install ffmpeg=7.1.1 -c conda-forge > ``` = 2.10 فقط)"> بدءًا من **PyTorch >= 2.10** (TorchCodec ≥ 0.10)، يمكن لـ TorchCodec إنشاء ارتباط ديناميكي مع تثبيت `ffmpeg` على مستوى النظام. وهذا مفيد عند استخدام `uv` أو مُديري بيئات غير `conda`: ```bash # Ubuntu/Debian sudo apt install ffmpeg # macOS (Apple Silicon) brew install ffmpeg ``` > [!IMPORTANT] > نظام `ffmpeg` على مستوى النظام **مدعوم فقط مع PyTorch >= 2.10** (TorchCodec ≥ 0.10). بالنسبة لإصدارات PyTorch الأقدم، **يجب** عليك استخدام `conda install ffmpeg -c conda-forge` بدلاً من ذلك. ## الخطوة 3: تثبيت LeRobot 🤗 تثبيت `lerobot` الأساسي متعمد أن يكون **خفيفاً** — فهو يتضمن فقط تبعيات التعلم الآلي الأساسية (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). التبعيات الأثقل محجوبة خلف إضافات اختيارية حتى لا تثبّت إلا ما تحتاجه. ### من المصدر أولاً، انسخ المستودع وانتقل إلى المجلد: ```bash git clone https://github.com/huggingface/lerobot.git cd lerobot ``` ثم، ثبّت المكتبة في وضع قابل للتحرير. يكون هذا مفيدًا إذا كنت تخطط للمساهمة في الكود. ```bash pip install -e ".[core_scripts]" # For robot workflows (recording, replaying, calibrate) pip install -e ".[training]" # For training policies pip install -e ".[all]" # Everything (all policies, envs, hardware, dev tools) ``` ```bash uv pip install -e ".[core_scripts]" # For robot workflows (recording, replaying, calibrate) uv pip install -e ".[training]" # For training policies uv pip install -e ".[all]" # Everything (all policies, envs, hardware, dev tools) ``` ### التثبيت من PyPI **المكتبة الأساسية:** ثبّت الحزمة الأساسية باستخدام: ```bash pip install lerobot ``` ```bash uv pip install lerobot ``` _تقوم هذه الخطوة بتثبيت تبعيات التعلم الآلي الأساسية فقط. ستحتاج إلى إضافة إضافات لمعظم سير العمل._ **إضافات الميزات:** يوفّر LeRobot **إضافات مخصّصة لكل ميزة** تتوافق مع سير العمل الشائعة. إذا كنت تستخدم `uv`، فاستبدل `pip install` بـ`uv pip install` في الأوامر أدناه. | إضافات | ما يضيفه | حالة الاستخدام النموذجية | | ---------- | ------------------------------------------- | ----------------------------------- | | `dataset` | `datasets`, `av`, `torchcodec`, `jsonlines` | تحميل وإنشاء مجموعات البيانات | | `training` | `dataset` + `accelerate`, `trackio` | سياسات التدريب | | `hardware` | `pynput`, `pyserial`, `deepdiff` | الاتصال بالروبوتات الحقيقية | | `viz` | `rerun-sdk`, `foxglove-sdk` | التصور أثناء التسجيل/التقييم | تجمع **Composite Extras** إضافات الميزات الخاصة بأوامر سطر الأوامر الشائعة: | إضافات | يتضمن | حالة الاستخدام النموذجية | | -------------- | ------------------------------ | ------------------------------------------------------- | | `core_scripts` | `dataset` + `hardware` + `viz` | `lerobot-record`, `lerobot-replay`, `lerobot-calibrate` | | `evaluation` | `av` | `lerobot-eval` (أضف سياسة + إضافات البيئة حسب الحاجة) | | `dataset_viz` | `dataset` + `viz` | `lerobot-dataset-viz`, `lerobot-imgtransform-viz` | ```bash pip install 'lerobot[core_scripts]' # Record, replay, calibrate pip install 'lerobot[training]' # Train policies pip install 'lerobot[core_scripts,training]' # Record + train pip install 'lerobot[all]' # Everything ``` **إضافات السياسة والبيئة والأجهزة** لا تزال متاحة لبعض التبعيات المحددة: ```bash pip install 'lerobot[pi]' # Pi0/Pi0.5/Pi0-FAST policy deps pip install 'lerobot[smolvla]' # SmolVLA policy deps pip install 'lerobot[diffusion]' # Diffusion policy deps (diffusers) pip install 'lerobot[aloha,pusht]' # Simulation environments pip install 'lerobot[feetech]' # Feetech motor support ``` _يمكن دمج إضافات متعددة (على سبيل المثال، `.[core_scripts,pi,pusht]`). للاطلاع على القائمة الكاملة للإضافات المتاحة، راجع `pyproject.toml`._ ### نسخة PyTorch CUDA (لنظام Linux فقط) على نظام Linux، تأتي مكتبتا `torch` و`torchvision` من PyPI، حيث تكون الإصدارات الافتراضية (wheels) مبنية على CUDA 13 (الحد الأدنى للسائق **580.65**). أما عمليات التثبيت على macOS وWindows فتستخدم الإصدارات الافتراضية من PyPI ويمكنها تجاوز هذا القسم. لإصدار أقدم من السائق أو وحدة معالجة الرسوميات، ثبّت PyTorch أولاً من [فهرس PyTorch](https://pytorch.org/get-started/locally/) المطابق، ثم ثبّت LeRobot. إن إصدار TorchCodec الخاص بنظام لينكس على PyPI هو أيضاً بناء لـ CUDA 13، لذا احصل عليه من فهرس المعالجة المركزية (مع torch أقل من 2.11، اختر الإصدار المطابق من [جدول توافق TorchCodec](https://github.com/meta-pytorch/torchcodec#installing-torchcodec)): ```bash pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision pip install --index-url https://download.pytorch.org/whl/cpu torchcodec pip install -e ".[all]" # source # — or — pip install lerobot # from PyPI ``` > [!NOTE] > `cu126` هو الإصدار الذي يحتفظ به PyTorch للمحركات التي تدعم CUDA 12 فقط. لا يتوفر إصدار CUDA 12 لـ torch 2.15، لذا فإن هذا الفهرس يثبّت torch 2.14، والبقاء على CUDA 12 يعني البقاء على torch 2.14 أو إصدار أقدم. مع `uv pip`، يختار `--torch-backend` فهرس التثبيت في خطوة واحدة، على سبيل المثال `uv pip install --torch-backend cu126 lerobot`. أما `uv sync` فيثبّت دائمًا القفل المُلتزم به؛ لتغيير بناء CUDA هناك، أضِف الفهرس إلى `[tool.uv.index]` و`[tool.uv.sources]` في `pyproject.toml` ثم أعد تشغيل `uv lock`. ### استكشاف الأخطاء وإصلاحها إذا واجهت أخطاء في البناء، فقد تحتاج إلى تثبيت تبعيات نظام إضافية: `cmake` و`build-essential` و`ffmpeg libs`. لتثبيت هذه على نظام لينكس، نفّذ الأمر التالي: ```bash sudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev ``` بالنسبة لأنظمة أخرى، راجع: [تجميع PyAV](https://pyav.org/docs/develop/overview/installation.html#bring-your-own-ffmpeg) ## التبعيات الاختيارية توفر LeRobot إضافات اختيارية لوظائف محددة. يمكن دمج عدة إضافات معًا (مثل `.[aloha,feetech]`). للاطلاع على جميع الإضافات المتاحة، راجع `pyproject.toml`. إذا كنت تستخدم `uv`، فاستبدل `pip install` بـ `uv pip install` في الأوامر أدناه. ### المحاكاة ثبّت حزم البيئة: `aloha` ([gym-aloha](https://github.com/huggingface/gym-aloha))، `pusht` ([gym-pusht](https://github.com/huggingface/gym-pusht))، [`libero`](./libero) (لنظام Linux فقط) أو [`metaworld`](./metaworld). تتضمن هذه الحزم تلقائياً إضافة `dataset`. ```bash pip install -e ".[aloha]" # or "[pusht]" for example ``` ### التحكم في المحركات ثبّت الإضافة الخاصة بمحركاتك: `dynamixel` لـ Koch v1.1، و`feetech` لـ SO100/SO101/Moss. يتواصل كلاهما مع المحركات عبر [rustypot](https://github.com/pollen-robotics/rustypot). ```bash pip install -e ".[feetech]" # or "[dynamixel]" for example ``` ### تتبع التجارب يتضمن [Trackio](https://huggingface.co/docs/trackio) في الحزمة الإضافية `training`. لا تتطلب التشغيلات المحلية حسابًا أو تسجيل دخول: فهي تُخزَّن في قاعدة بيانات SQLite محلية تحت `~/.cache/huggingface/trackio`. افتح لوحة التحكم باستخدام: ```bash trackio show --project lerobot ``` لمزامنة التشغيلات مع مساحة Hugging Face (تُنشأ إذا لم تكن موجودة)، نفّذ `hf auth login` ومرّر `--trackio.space_id=/`. تتطلب المهام البعيدة (`--job.target`) التي تم تفعيل التتبع لها `space_id`، لأن قاعدة البيانات المحلية للوحدة تُفقد عند انتهاء المهمة. تكون خصوصية المساحة افتراضياً `None`: المساحات الجديدة عامة ما لم يكن الافتراضي للمنظمة خاصاً. مرّر `--trackio.private=true` لإنشاء مساحة خاصة. تُسجّل كل عملية الأمر الذي أطلقها ومخرجات وحدة التحكم الخاصة بها (الطباعة، والسجلات، وتتبع الأخطاء)، وتظهر كلاهما على صفحة العملية في لوحة التحكم. على مساحة، تكون هذه المخرجات مرئية بنفس درجة ظهور المساحة نفسها؛ مرّر `--trackio.capture_console=false` لإبقاء مخرجات وحدة التحكم خارج نطاق العملية. #### الانتقال من Weights & Biases | إعداد W&B | إعداد Trackio | | ------------------------------- | ------------------------------------------------------------------------------------------------ | | `--wandb.enable=true` | `--trackio.enable=true` | | `--wandb.project=` | `--trackio.project=` | | `--wandb.disable_artifact=true` | الافتراضي بالفعل؛ استخدم `--trackio.disable_artifact=false` للتفعيل | | `--wandb.entity=` | اختر `--trackio.space_id=/` للتسجيل المضيف | | `--wandb.run_id=` | استخدم `--trackio.run_name=` لتشغيل **Trackio** موجود مسبقًا | | `--wandb.mode=offline` | اترك `space_id` فارغًا للتسجيل المحلي؛ كما ألغِ تعيين `TRACKIO_SPACE_ID` و`TRACKIO_SERVER_URL` إذا كانا معيَّنين | | `--wandb.mode=disabled` | `--trackio.enable=false` | | `--wandb.console=off` | `--trackio.capture_console=false` | ## الخطوات التالية - **هل لديك روبوت؟** قم بتجميعه ومعايرته باتباع صفحته ضمن **Robots** في الشريط الجانبي (على سبيل المثال [SO-101](./so101))، ثم سجّل مجموعة بيانات ودرّب أول سياسة لك باستخدام [دليل تعلّم التقليد](./il_robots). - **لا تملك أي أجهزة بعد؟** درّب وتقييم سياسة في المحاكاة باستخدام [LIBERO](./libero)، أو جرّب [دفاتر Colab](./notebooks). - **هل ترغب في المساهمة؟** اقرأ [دليل المساهمة](./contributing). - احتفظ بـ [ورقة الشرح المختصرة](./cheat-sheet) في متناول يدك: فهي تدرج كل أوامر LeRobot في مكان واحد.