التثبيت

يستخدم هذا الدليل conda (عبر miniforge) لإدارة البيئات (موصى به). إذا كنت تفضل مدير بيئات آخر (مثل uv، venv)، فتأكد من وجود Python >=3.12، ثم انتقل مباشرة إلى إعداد البيئة.

الخطوة 1 (لـ conda فقط): تثبيت miniforge

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:

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

ثم فعّل بيئة Python الافتراضية، حيث يجب عليك القيام بذلك في كل مرة تفتح فيها نافذة طرفية (shell) لاستخدام lerobot:

conda activate lerobot

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\activate

متطلبات المنصة

على Apple Silicon، يتطلب PyTorch macOS 14 أو أحدث، وتسريع MPS يتطلب macOS 15 أو أحدث (على macOS 14، يعود LeRobot إلى المعالج المركزي CPU). على Linux، تحتاج عجلات PyTorch الافتراضية إلى برنامج تشغيل NVIDIA من الإصدار 580.65 أو أحدث؛ أما بالنسبة لبرامج التشغيل الأقدم، فراجع PyTorch CUDA variant.

قم بتثبيت ffmpeg (للتفكيك الفيديوي)

LeRobot uses TorchCodec for video decoding by default, which requires ffmpeg.

دعم المنصات: غير متوفر TorchCodec على macOS Intel (x86_64) أو Linux armv7l. على هذه المنصات، يتراجع LeRobot تلقائيًا إلى pyav — لذا لا تحتاج إلى تثبيت ffmpeg ويمكنك الانتقال مباشرة إلى الخطوة 3.

Jetson (aarch64 + CUDA): يتم فك ترميز الفيديو على وحدة المعالجة المركزية (CPU) افتراضيًا. يبني docker/Dockerfile.jetson مكتبتَي torch/torchcodec من المصدر مع دعم CUDA لنظام JetPack 6.2 — وهو مُدار من قبل المجتمع، راجع ravediamond/lerobot-jetson للحصول على الصورة الجاهزة للاستخدام، والمشكلة #819 للاطلاع على الخلفية.

إذا كانت منصتك تدعم TorchCodec، فقم بتثبيت ffmpeg باستخدام إحدى الطرق أدناه:

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

الخطوة 3: تثبيت LeRobot 🤗

تثبيت lerobot الأساسي متعمد أن يكون خفيفاً — فهو يتضمن فقط تبعيات التعلم الآلي الأساسية (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). التبعيات الأثقل محجوبة خلف إضافات اختيارية حتى لا تثبّت إلا ما تحتاجه.

من المصدر

أولاً، انسخ المستودع وانتقل إلى المجلد:

git clone https://github.com/huggingface/lerobot.git
cd lerobot

ثم، ثبّت المكتبة في وضع قابل للتحرير. يكون هذا مفيدًا إذا كنت تخطط للمساهمة في الكود.

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)

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

المكتبة الأساسية: ثبّت الحزمة الأساسية باستخدام:

pip install lerobot

uv pip install lerobot

تقوم هذه الخطوة بتثبيت تبعيات التعلم الآلي الأساسية فقط. ستحتاج إلى إضافة إضافات لمعظم سير العمل.

إضافات الميزات: يوفّر LeRobot إضافات مخصّصة لكل ميزة تتوافق مع سير العمل الشائعة. إذا كنت تستخدم uv، فاستبدل pip install بـuv pip install في الأوامر أدناه.

تجمع Composite Extras إضافات الميزات الخاصة بأوامر سطر الأوامر الشائعة:

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

إضافات السياسة والبيئة والأجهزة لا تزال متاحة لبعض التبعيات المحددة:

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 المطابق، ثم ثبّت LeRobot. إن إصدار TorchCodec الخاص بنظام لينكس على PyPI هو أيضاً بناء لـ CUDA 13، لذا احصل عليه من فهرس المعالجة المركزية (مع torch أقل من 2.11، اختر الإصدار المطابق من جدول توافق TorchCodec):

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

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. لتثبيت هذه التبعيات على نظام Linux، نفّذ الأمر التالي:

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

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

توفر LeRobot إضافات اختيارية لوظائف محددة. يمكن دمج عدة إضافات معًا (مثل .[aloha,feetech]). للاطلاع على جميع الإضافات المتاحة، راجع pyproject.toml. إذا كنت تستخدم uv، فاستبدل pip install بـ uv pip install في الأوامر أدناه.

المحاكاة

ثبّت حزم البيئة: aloha (gym-aloha)، pusht (gym-pusht)، libero (لنظام Linux فقط) أو metaworld. تتضمن هذه الحزم تلقائياً إضافة dataset.

pip install -e ".[aloha]" # or "[pusht]" for example

التحكم في المحركات

ثبّت الإضافة الخاصة بمحركاتك: dynamixel لـ Koch v1.1، وfeetech لـ SO100/SO101/Moss. يتواصل كلاهما مع المحركات عبر rustypot.

pip install -e ".[feetech]" # or "[dynamixel]" for example

تتبع التجارب

يتضمن Trackio في الحزمة الإضافية training. لا تتطلب التشغيلات المحلية حسابًا أو تسجيل دخول: فهي تُخزَّن في قاعدة بيانات SQLite محلية تحت ~/.cache/huggingface/trackio. افتح لوحة التحكم باستخدام:

trackio show --project lerobot

لمزامنة التشغيلات مع مساحة Hugging Face (تُنشأ إذا لم تكن موجودة)، نفّذ hf auth login ومرّر --trackio.space_id=<user>/<space>. تتطلب المهام البعيدة (--job.target) التي تم تفعيل التتبع لها space_id، لأن قاعدة البيانات المحلية للوحدة تُفقد عند انتهاء المهمة.

تكون خصوصية المساحة افتراضياً None: فالمساحات الجديدة تكون عامة ما لم يكن الافتراضي في المنظمة خاصاً. مرّر --trackio.private=true لإنشاء مساحة خاصة.

تُسجّل كل عملية الأمر الذي أطلقها ومخرجات وحدة التحكم الخاصة بها (الطباعة، والسجلات، وتتبع الأخطاء)، وتظهر كلاهما على صفحة العملية في لوحة التحكم. على مساحة (Space) تكون هذه المخرجات مرئية بنفس درجة ظهور المساحة نفسها؛ مرّر --trackio.capture_console=false لإبقاء مخرجات وحدة التحكم خارج نطاق العملية.

الانتقال من Weights & Biases

الخطوات التالية

• هل لديك روبوت؟ قم بتجميعه ومعايرته باتباع صفحته ضمن Robots في الشريط الجانبي (على سبيل المثال SO-101)، ثم سجّل مجموعة بيانات ودرّب أول سياسة لك باستخدام دليل تعلّم التقليد.
• لا تملك أي أجهزة بعد؟ درّب وتقييم سياسة في المحاكاة باستخدام LIBERO، أو جرّب دفاتر Colab.
• هل ترغب في المساهمة؟ اقرأ دليل المساهمة.
• احتفظ بـ ورقة الشرح المختصرة في متناول يدك: فهي تدرج كل أوامر LeRobot في مكان واحد.