# 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](#step-2-environment-setup). ## Bước 1 (chỉ dành cho `conda`): Cài đặt [`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 ``` ## Bước 2: Thiết lập môi trường Tạo môi trường ảo với Python 3.12: ```bash conda create -y -n lerobot python=3.12 ``` = chỉ 2.10)> ```bash 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: ```bash conda activate lerobot ``` > [!NOTE] > Khi cài đặt LeRobot bên trong WSL (Windows Subsystem for Linux), hãy đảm bảo cũng cài đặt `evdev`: > > ```bash > conda install evdev -c conda-forge > ``` = chỉ 2.10)> ```bash # Linux/macOS source .venv/bin/activate # Windows PowerShell .venv\Scripts\activate ``` > [!NOTE] > Khi cài đặt LeRobot bên trong WSL (Windows Subsystem for Linux), hãy đảm bảo cũng cài đặt `evdev`: > > ```bash > sudo apt install libevdev-dev > uv pip install evdev > ``` ### 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](#pytorch-cuda-variant-linux-only). ### Cài đặt `ffmpeg` (để giải mã video) LeRobot sử dụng [TorchCodec](https://github.com/meta-pytorch/torchcodec) để giải mã video theo mặc định, điều này yêu cầu `ffmpeg`. > [!NOTE] > **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`](https://github.com/huggingface/lerobot/blob/main/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`](https://github.com/ravediamond/lerobot-jetson) để biết hình ảnh đã xây dựng sẵn và xem [#819](https://github.com/huggingface/lerobot/issues/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: Cài đặt `ffmpeg` trong môi trường conda của bạn. Cách này hoạt động với **mọi phiên bản PyTorch** và là **bắt buộc với PyTorch < 2.10**: ```bash conda install ffmpeg -c conda-forge ``` > [!TIP] > Điều này thường cài đặt `ffmpeg 8.X` với bộ mã hóa `libsvtav1`. Nếu bạn gặp sự cố (ví dụ: thiếu `libsvtav1` — kiểm tra bằng `ffmpeg -encoders` — hoặc không khớp phiên bản với `torchcodec`), bạn có thể cài đặt rõ ràng `ffmpeg 7.1.1` bằng cách sử dụng: > > ```bash > conda install ffmpeg=7.1.1 -c conda-forge > ``` = chỉ 2.10)> Bắt đầu từ **PyTorch >= 2.10** (TorchCodec ≥ 0.10), TorchCodec có thể liên kết động với cài đặt `ffmpeg` trên toàn hệ thống. Điều này hữu ích khi sử dụng `uv` hoặc các trình quản lý môi trường không phải `conda`: ```bash # Ubuntu/Debian sudo apt install ffmpeg # macOS (Apple Silicon) brew install ffmpeg ``` > [!IMPORTANT] > `ffmpeg` trên toàn hệ thống chỉ được **hỗ trợ với PyTorch >= 2.10** (TorchCodec ≥ 0.10). Đối với các phiên bản PyTorch cũ hơn, bạn **phải** sử dụng `conda install ffmpeg -c conda-forge` thay thế. ## 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: ```bash 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. ```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) ``` ### Cài đặt từ PyPI **Thư viện lõi:** Cài đặt gói cơ bản bằng cách: ```bash pip install lerobot ``` ```bash 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. | Bổ sung | Những gì nó bổ sung | Trường hợp sử dụng điển hình | | ---------- | ------------------------------------------- | ----------------------------------- | | `dataset` | `datasets`, `av`, `torchcodec`, `jsonlines` | Tải và tạo bộ dữ liệu | | `training` | `dataset` + `accelerate`, `trackio` | Chính sách huấn luyện | | `hardware` | `pynput`, `pyserial`, `deepdiff` | Kết nối với robot thực | | `viz` | `rerun-sdk`, `foxglove-sdk` | Trực quan hóa trong quá trình ghi/đánh giá | **Composite Extras** kết hợp các tính năng bổ sung cho các script CLI phổ biến: | Bổ sung | Bao gồm | Trường hợp sử dụng điển hình | | -------------- | ------------------------------ | ------------------------------------------------------- | | `core_scripts` | `dataset` + `hardware` + `viz` | `lerobot-record`, `lerobot-replay`, `lerobot-calibrate` | | `evaluation` | `av` | `lerobot-eval` (thêm policy + env extras khi cần) | | `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 ``` **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ể: ```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 ``` _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](https://pytorch.org/get-started/locally/) tương ứng trước, sau đó cài đặt LeRobot. TorchCodec cho Linux 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](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` 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: ```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 ``` Đối với các hệ thống khác, xem: [Biên dịch PyAV](https://pyav.org/docs/develop/overview/installation.html#bring-your-own-ffmpeg) ## 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](https://github.com/huggingface/gym-aloha)), `pusht` ([gym-pusht](https://github.com/huggingface/gym-pusht)), [`libero`](./libero) (chỉ dành cho Linux) hoặc [`metaworld`](./metaworld). Những gói này tự động bao gồm phần mở rộng `dataset`. ```bash 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](https://github.com/pollen-robotics/rustypot). ```bash pip install -e ".[feetech]" # or "[dynamixel]" for example ``` ### Theo dõi thí nghiệm [Trackio](https://huggingface.co/docs/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: ```bash 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=/`. 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ài đặt W&B | Cài đặt Trackio | | ------------------------------- | ------------------------------------------------------------------------------------------------ | | `--wandb.enable=true` | `--trackio.enable=true` | | `--wandb.project=` | `--trackio.project=` | | `--wandb.disable_artifact=true` | Đã là mặc định; sử dụng `--trackio.disable_artifact=false` để bật | | `--wandb.entity=` | Chọn `--trackio.space_id=/` để ghi log trên hệ thống được quản lý | | `--wandb.run_id=` | Sử dụng `--trackio.run_name=` cho một run **Trackio** hiện có | | `--wandb.mode=offline` | Bỏ qua `space_id` để ghi log cục bộ; đồng thời hủy đặt `TRACKIO_SPACE_ID` và `TRACKIO_SERVER_URL` nếu chúng đã được đặt | | `--wandb.mode=disabled` | `--trackio.enable=false` | | `--wandb.console=off` | `--trackio.capture_console=false` | ## 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](./so101)), 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](./il_robots). - **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](./libero), hoặc thử các [Colab notebooks](./notebooks). - **Bạn muốn đóng góp?** Hãy đọc [hướng dẫn đóng góp](./contributing). - Hãy giữ [bảng tra nhanh](./cheat-sheet) bên cạnh: nó liệt kê mọi lệnh LeRobot tại một nơi.