Cài đặt

Hướng dẫn này sử dụng conda (thông qua miniforge) để quản lý môi trường (được khuyến nghị). Nếu bạn thích một trình quản lý môi trường khác (ví dụ: uv, venv), hãy đảm bảo bạn có Python >=3.12, sau đó bỏ qua đến Thiết lập môi trường.

Bước 1 (chỉ conda): Cài đặt miniforge

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Bước 2: Thiết lập môi trường

Tạo môi trường ảo với Python 3.12:

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

Sau đó, kích hoạt môi trường ảo của bạn. Bạn phải thực hiện điều này mỗi khi mở một shell để sử dụng lerobot:

conda activate lerobot

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

Yêu cầu về nền tảng

Trên Apple Silicon, PyTorch yêu cầu macOS 14 trở lên, và tăng tốc MPS yêu cầu macOS 15 trở lên (trên macOS 14, LeRobot sẽ chuyển sang dùng CPU). Trên Linux, các bánh xe PyTorch mặc định cần trình điều khiển NVIDIA phiên bản 580.65 trở lên; với các trình điều khiển cũ hơn, hãy xem biến thể CUDA của PyTorch.

Cài đặt ffmpeg (để giải mã video)

LeRobot sử dụng TorchCodec để giải mã video theo mặc định, điều này yêu cầu ffmpeg.

Hỗ trợ nền tảng: TorchCodec không khả dụng trên macOS Intel (x86_64) hoặc Linux armv7l. Trên các nền tảng này, LeRobot tự động chuyển sang pyav — vì vậy bạn không cần cài đặt ffmpeg và có thể bỏ qua đến Bước 3.

Jetson (aarch64 + CUDA): việc giải mã video chạy trên CPU theo mặc định. docker/Dockerfile.jetson biên dịch torch/torchcodec từ mã nguồn với hỗ trợ CUDA cho JetPack 6.2 — do cộng đồng bảo trì, xem ravediamond/lerobot-jetson để biết hình ảnh đã xây dựng sẵn và xem #819 để biết thêm bối cảnh.

Nếu nền tảng của bạn hỗ trợ TorchCodec, hãy cài đặt ffmpeg bằng một trong các phương pháp dưới đây:

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

Bước 3: Cài đặt LeRobot 🤗

Việc cài đặt lerobot cơ bản được thiết kế nhẹ một cách có chủ đích — nó chỉ bao gồm các phụ thuộc ML cốt lõi (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). Các phụ thuộc nặng hơn được đặt sau các tùy chọn bổ sung (optional extras) để bạn chỉ cài đặt những gì mình cần.

Từ mã nguồn

Đầu tiên, clone kho mã và điều hướng vào thư mục:

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

Sau đó, cài đặt thư viện ở chế độ có thể chỉnh sửa. Điều này hữu ích nếu bạn có kế hoạch đóng góp cho mã nguồn.

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)

Cài đặt từ PyPI

Thư viện lõi: Cài đặt gói cơ bản bằng cách:

pip install lerobot

uv pip install lerobot

Điều này chỉ cài đặt các phụ thuộc ML cốt lõi. Bạn sẽ cần thêm các gói bổ sung cho hầu hết các quy trình làm việc.

Tùy chọn bổ sung theo tính năng: LeRobot cung cấp các tùy chọn bổ sung theo phạm vi tính năng tương ứng với các quy trình làm việc phổ biến. Nếu bạn đang sử dụng uv, hãy thay pip install bằng uv pip install trong các lệnh bên dưới.

Composite Extras kết hợp các tính năng bổ sung cho các script CLI phổ biến:

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

Các phần bổ sung về chính sách, môi trường và phần cứng vẫn có sẵn cho các phụ thuộc cụ thể:

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

Có thể kết hợp nhiều extras (ví dụ: .[core_scripts,pi,pusht]). Để xem danh sách đầy đủ các extras có sẵn, hãy tham khảo pyproject.toml.

Biến thể PyTorch CUDA (chỉ dành cho Linux)

Trên Linux, torch và torchvision được lấy từ PyPI, trong đó các wheel mặc định là bản build CUDA 13 (yêu cầu tối thiểu driver 580.65). Cài đặt trên macOS và Windows sử dụng các wheel mặc định từ PyPI và có thể bỏ qua phần này.

Đối với trình điều khiển hoặc GPU cũ hơn, hãy cài đặt PyTorch từ chỉ mục PyTorch tương ứng trước, sau đó cài đặt LeRobot. Bản Linux TorchCodec trên PyPI cũng là bản build CUDA 13, vì vậy hãy lấy nó từ chỉ mục CPU (với torch dưới 2.11, hãy chọn bản phát hành tương ứng từ bảng tương thích 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 là bản build mà PyTorch dành cho các driver chỉ hỗ trợ CUDA 12. torch 2.15 không có bản build CUDA 12, nên index này cài đặt torch 2.14, và việc ở lại CUDA 12 đồng nghĩa với việc ở lại torch 2.14 hoặc các phiên bản cũ hơn.

Với uv pip, --torch-backend chọn index trong một bước, ví dụ uv pip install --torch-backend cu126 lerobot. uv sync luôn cài đặt lock đã cam kết: để thay đổi bản build CUDA ở đó, hãy thêm index vào [tool.uv.index] và [tool.uv.sources] trong pyproject.toml và chạy lại uv lock.

Xử lý sự cố

Nếu bạn gặp lỗi khi build, bạn có thể cần cài đặt các phụ thuộc hệ thống bổ sung: cmake, build-essential và ffmpeg libs. Để cài đặt những thứ này trên Linux, hãy chạy:

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

Đối với các hệ thống khác, xem: Biên dịch PyAV

Các phụ thuộc tùy chọn

LeRobot cung cấp các tùy chọn bổ sung cho các chức năng cụ thể. Có thể kết hợp nhiều tùy chọn bổ sung (ví dụ: .[aloha,feetech]). Để biết tất cả các tùy chọn bổ sung khả dụng, hãy tham khảo pyproject.toml. Nếu bạn đang sử dụng uv, hãy thay thế pip install bằng uv pip install trong các lệnh bên dưới.

Mô phỏng

Cài đặt các gói môi trường: aloha (gym-aloha), pusht (gym-pusht), libero (chỉ dành cho Linux) hoặc metaworld. Các gói này tự động bao gồm phần mở rộng dataset.

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

Điều khiển động cơ

Cài đặt phần mở rộng cho động cơ của bạn: dynamixel cho Koch v1.1, feetech cho SO100/SO101/Moss. Cả hai đều giao tiếp với động cơ thông qua rustypot.

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

Theo dõi thí nghiệm

Trackio được bao gồm trong phần bổ sung training. Các lần chạy cục bộ không cần tài khoản hay đăng nhập: chúng được lưu trong cơ sở dữ liệu SQLite cục bộ tại ~/.cache/huggingface/trackio. Mở bảng điều khiển bằng lệnh:

trackio show --project lerobot

Để đồng bộ các lần chạy với một Hugging Face Space (tạo nếu chưa có), hãy chạy hf auth login và truyền --trackio.space_id=<user>/<space>. Các tác vụ từ xa (--job.target) có bật tính năng theo dõi yêu cầu space_id, vì cơ sở dữ liệu cục bộ của pod sẽ bị mất khi tác vụ kết thúc.

Quyền riêng tư của Space mặc định là None: các Space mới sẽ là công khai trừ khi mặc định của tổ chức là riêng tư. Truyền --trackio.private=true để tạo một Space riêng tư.

Mỗi lần chạy sẽ ghi lại lệnh khởi chạy nó và đầu ra của console (prints, logs, tracebacks), cả hai đều được hiển thị trên trang của lần chạy đó trong dashboard. Trên một Space, chúng có mức độ hiển thị tương đương với chính Space; hãy truyền --trackio.capture_console=false để giữ đầu ra console ra khỏi lần chạy.

Chuyển đổi từ Weights & Biases

Các bước tiếp theo

• Bạn có robot không? Hãy lắp ráp và hiệu chuẩn nó bằng cách làm theo trang của nó trong mục Robots ở thanh bên (ví dụ SO-101), sau đó ghi lại một bộ dữ liệu và huấn luyện chính sách đầu tiên của bạn với tutorial học bắt chước.
• Chưa có phần cứng? Hãy huấn luyện và đánh giá chính sách trong mô phỏng bằng LIBERO, hoặc thử các Colab notebooks.
• Bạn muốn đóng góp? Hãy đọc hướng dẫn đóng góp.
• Hãy giữ bảng tra nhanh bên cạnh: nó liệt kê mọi lệnh LeRobot tại một nơi.