TL;DR
- Εγκαταστήστε τον LeRobot σε 2 λεπτά με την εντολή
pip install lerobotκαι δοκιμάστε τον με μια προεγκατεστημένη πολιτική σε ένα προσομοιωμένο βραχίονα Franka. - Καταγράψτε δεδομένα τηλεχειρισμού από έναν πραγματικό ρομποτικό βραχίονα (π.χ., UR5) χρησιμοποιώντας την εντολή
lerobot.record. - Εκπαιδεύστε μια προσαρμοσμένη πολιτική από παραδείγματα με 3 γραμμές κώδικα χρησιμοποιώντας την εντολή
lerobot.train. - Αξιολογήστε σε προσομοίωση (Isaac Gym) ή εκτελέστε σε υλικό (SO-100) με ελάχιστες αλλαγές στον κώδικα.
- Μοιραστείτε σύνολα δεδομένων και μοντέλα στο Hugging Face Hub με την εντολή
lerobot.push_to_hub.
1. Εγκατάσταση και Μορφή Δεδομένων του LeRobot
Εγκατάσταση του LeRobot
Αρχίστε με την επίσημη εγκατάσταση. Για τους περισσότερους χρήστες, το πακέτο Python είναι η ταχύτερη επιλογή:
pip install lerobot -U
Επαλήθευση εγκατάστασης:
python -c "import lerobot; print(lerobot.__version__)"
Προσδοκώμενο αποτέλεσμα:
0.5.0
Υπερσυνοπτική Παρουσίαση της Μορφής Δεδομένων
Τα σύνολα δεδομένων του LeRobot ακολουθούν το πρότυπο RLDS (Robot Learning Dataset Standard), αλλά με επεκτάσεις ειδικές για το Hugging Face. Μια ελάχιστη δομή καταλόγου δεδομένων έχει ως εξής:
my_dataset/
├── scenes/ # Προαιρετικά: 3D διαμορφώσεις σκηνών
│ └── table.yaml
├── trajectories/ # Καταγραφές παραδειγμάτων
│ ├── demo_0.h5 # Μορφή HDF5 (απαιτείται)
│ ├── demo_1.h5
│ └── ...
└── metadata.json # Περιγραφή του συνόλου δεδομένων (απαιτείται)
Κύρια πεδία στο metadata.json:
{
"description": "Σύνολο δεδομένων UR5 για λήψη και τοποθέτηση αντικειμένων",
"robot": "ur5e",
"tasks": ["pick", "place"],
"sensors": ["rgb_camera", "joint_states"],
"version": "0.1.0"
}
Συχνές Σφάλματα:
- Λείπει το
metadata.json: Ο LeRobot θα εκδώσει το σφάλμαValueError: Δεν βρέθηκε περιγραφή συνόλου δεδομένων. - Λανθασμένη δομή HDF5: Βεβαιωθείτε ότι κάθε αρχείο
.h5περιέχει τις ομάδες/observationsκαι/actions.
2. Φόρτωση Προεγκατεστημένων Πολιτικών
Ο LeRobot παρέχει 3 έτοιμες πολιτικές: ACT (Action Chunk Transformer), Diffusion Policy και SmolVLA (Small Vision-Language-Action). Εδώ θα δούμε πώς να τις φορτώσετε και να τις δοκιμάσετε.
Φόρτωση Πολιτικής ACT
from lerobot import ACTPolicy
# Φόρτωση προεγκατεστημένου μοντέλου ACT (βραχίονας Franka, χειρισμός αντικειμένων σε τραπέζι)
policy = ACTPolicy.from_pretrained("lerobot/act3d-franka-table")
# Προσομοίωση βήματος (είσοδος: λεξικό παρατηρήσεων)
observation = {
"image": torch.randn(3, 256, 256), # Εικόνα RGB
"joint_states": torch.randn(7), # Γωνίες αρθρώσεων του βραχίονα
"ee_pose": torch.randn(7) # Θέση του τελικού σημείου
}
action = policy(observation)
print(action.shape) # Προσδοκώμενο: torch.Size([7]) για ροπές στις αρθρώσεις
Φόρτωση Πολιτικής Diffusion
from lerobot import DiffusionPolicy
# Φόρτωση πολιτικής Diffusion για πιάσιμο αντικειμένων
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_policy-grasp")
# Δείγμα δράσης (τυχαία)
action = policy.sample(observation)
print(action) # Αποτέλεσμα: {"action": tensor([...]), "log_probs": tensor([...])}
Φόρτωση SmolVLA
from lerobot import SmolVLA
# Φόρτωση μοντέλου VLA για εργασίες με κείμενο
vla = SmolVLA.from_pretrained("lerobot/smolvla-aloha")
# Ερώτηση με εικόνα και κείμενο
query = {
"image": torch.randn(3, 224, 224),
"text": "πάρτε το κόκκινο κουτί",
"joint_states": torch.randn(7)
}
action = vla(query)
print(action) # Αποτέλεσμα: tensor([...]) για δράσεις στις αρθρώσεις
Πιθανά Προβλήματα:
- Οι πολιτικές ACT απαιτούν παρατηρήσεις σε κανονικοποιημένη μορφή (ελέγξτε την κάρτα του μοντέλου για κλίμακα).
- Οι πολιτικές Diffusion είναι πιο αργές (~100ms ανά βήμα) αλλά πιο αποδοτικές σε δείγματα.
- Το SmolVLA χρειάζεται προεπεξεργασμένα εμβέδματα κειμένου (χρησιμοποιήστε
lerobot.tokenizersαν λείπουν).
3. Καταγραφή Δεδομένων Τηλεχειρισμού σε Πραγματικό Βραχίονα
Χρησιμοποιήστε την εντολή lerobot.record για να συλλέξετε δεδομένα από έναν πραγματικό ρομποτικό βραχίονα. Παρακάτω ακολουθεί ένα παράδειγμα για τον UR5.
Προαπαιτούμενα
- Εγκαταστήστε το ROS 2 (Humble) και τον οδηγό του UR:
sudo apt install ros-humble-ur-driver - Βεβαιωθείτε ότι ο ρομπότας είναι συνδεδεμένος στο δίκτυο και προσβάσιμος μέσω ROS 2.
Καταγραφή Συνόλου Δεδομένων
lerobot record \
--robot ur5e \
--sensors rgb_camera joint_states \
--output_dir ./ur5_demos \
--max_episodes 10
Προσδοκώμενο Αποτέλεσμα:
Καταγραφή συνόλου δεδομένων για UR5e...
Εpisode 1/10: Αναμονή για εισαγωγή τηλεχειρισμού...
[ROS 2 κόμβος ξεκίνησε: /lerobot_recorder]
[Καταγραφή σε: ./ur5_demos/trajectories/episode_0.h5]
[Πατήστε Ctrl+C για να τελειώσετε το επεισόδιο]
Μορφές Τηλεχειρισμού
| Μορφή | Σημαία Εντολής | Περιγραφή |
|---|---|---|
| Πληκτρολόγιο | --teleop_mode keyboard | Χρήση βελών για τον έλεγχο του ρομπότ. |
| Joystick | --teleop_mode joystick | Απαιτεί πακέτο python-joystick. |
| Gamepad | --teleop_mode gamepad | Λειτουργεί με συμβατές με XInput ελεγκτές. |
| Οδηγός Αισθητήρων |
Συχνά Σφάλματα:
- Αποτυχία σύνδεσης ROS 2: Ελέγξτε τις μεταβλητές
ROS_DOMAIN_IDκαιROS_MASTER_URI. Λύση: Εκτελέστεexport ROS_DOMAIN_ID=0πριν από την καταγραφή. - Επαναληψιμότητα αισθητήρων: Αν οι εικόνες RGB είναι παραμορφωμένες, επανεκτιμήστε την κάμερα με
ros2 camera_calibration.
4. Εκπαίδευση Πολιτικής από Παραδείγματα
Εκπαιδεύστε μια προσαρμοσμένη πολιτική χρησιμοποιώντας την API lerobot.train. Παρακάτω ακολουθεί ένα παράδειγμα BC (Behavior Cloning).
Εκπαίδευση από την Αρχή
from lerobot import BehaviorCloningTrainer
from lerobot.datasets import load_dataset
# Φόρτωση συνόλου δεδομένων
dataset = load_dataset("path/to/ur5_demos")
# Αρχικοποίηση εκπαιδευτή
trainer = BehaviorCloningTrainer(
model="lerobot/act3d-base", # Αρχή από προεγκατεστημένο μοντέλο
dataset=dataset,
batch_size=32,
epochs=50,
lr=1e-4
)
# Εκπαίδευση!
trainer.train()
trainer.push_to_hub("my-ur5-policy") # Αποθήκευση στο Hugging Face Hub
Προσαρμογή Υπερπαραμέτρων
Κύριες παραμέτρους που μπορείτε να προσαρμόσετε:
| Παράμετρος | Προεπιλογή | Προτεινόμενη Περιοχή | Περιγραφή |
|---|---|---|---|
batch_size | 32 | 16–128 | Μεγαλύτερα batch = ταχύτερη εκπαίδευση. |
lr | 1e-4 | 1e-5 έως 1e-3 | Πολύ υψηλό = αστάθεια, πολύ χαμηλό = αργή εκπαίδευση. |
epochs | 50 | 20–200 | Πρόωρη διακοπή αν η ζημιά στο έλεγχο σταθεροποιηθεί. |
kl_weight | 0.1 | 0.01–0.5 | Μόνο για RL προσαρμογή. |
Πιθανά Προβλήματα:
- Υπερεκπαίδευση: Αν η εκπαιδευτική ζημιά είναι πολύ μικρότερη από αυτή του ελέγχου, μειώστε την ικανότητα του μοντέλου ή προσθέστε αύξηση δεδομένων.
- Κλίμακα δράσεων: Βεβαιωθείτε ότι οι δράσεις στο σύνολο δεδομένων σας ταιριάζουν με την κλίμακα εντολών του ρομπότ (π.χ.,
[-1, 1]για ροπές).
5. Αξιολόγηση σε Προσομοίωση και σε Πραγματικό Υλικό
Αξιολόγηση σε Isaac Gym
from lerobot.sim import IsaacGymEnv
from lerobot import ACTPolicy
# Φόρτωση πολιτικής και περιβάλλοντος
policy = ACTPolicy.from_pretrained("my-ur5-policy")
env = IsaacGymEnv(robot="ur5e", task="pick_place")
# Εκτέλεση αξιολόγησης
success_rate = env.evaluate(policy, episodes=10)
print(f"Ποσοστό επιτυχίας: {success_rate * 100:.2f}%")
Προσδοκώμενο Αποτέλεσμα:
Episode 1/10: Επιτυχία = True
Episode 2/10: Επιτυχία = False
...
Εκτέλεση σε Πραγματικό Υλικό (Παράδειγμα UR5)
from lerobot.hardware import UR5Controller
from lerobot import ACTPolicy
# Αρχικοποίηση ρομπότ και πολιτικής
robot = UR5Controller()
policy = ACTPolicy.from_pretrained("my-ur5-policy")
# Εκτέλεση κλειστού βρόχου ελέγχου
while True:
obs = robot.get_observations()
action = policy(obs)
robot.send_action(action)
Πίνακας Υποστήριξης Υλικού:
| Ρομπότας | Υποστήριξη LeRobot | Σημειώσεις |
|---|---|---|
| UR5/UR10 | ✅ | Απαιτείται οδηγός ROS 2. |
| Franka Emika | ✅ | Λειτουργεί με πακέτο franka_ros2. |
| SO-100 | ✅ | Επίσημη υποστήριξη (βλέπε παρακάτω). |
| Stretch RE1 | ✅ | Απαιτείται οδηγός stretch_ros2. |
| Aloha | ✅ | Πειραματικό (2026-05). |
| Τεχνική Υποστήριξη Υλικού |
Πιθανά Προβλήματα:
- Υστέρηση: Η εκτέλεση σε πραγματικό υλικό απαιτεί <50ms χρόνο βρόχου. Χρησιμοποιήστε
robot.set_control_rate(20)για ενημερώσεις 20Hz. - Ασφάλεια: Πάντα να ενεργοποιείτε όρια ροπών/δυνάμεων και ακραίες διακοπές σε λειτουργία υλικού.
6. Αποστολή Συνόλων Δεδομένων και Μοντέλων στο Hub
Μοιραστείτε την εργασία σας με την κοινότητα χρησιμοποιώντας το Hugging Face Hub.
Αποστολή Συνόλου Δεδομένων
lerobot push_to_hub \
--path ./ur5_demos \
--repo_id my-username/ur5-pick-place-demos \
--private # Προαιρετικά: Ρυθμίστε σε False για δημόσια πρόσβαση
Αποστολή Μοντέλου
from lerobot import ACTPolicy
# Φόρτωση εκπαιδευμένης πολιτικής
policy = ACTPolicy.from_pretrained("lerobot/act3d-base")
policy.train() # Υποθέτουμε ότι έχει εκπαιδευτεί
# Αποστολή στο Hub
policy.push_to_hub("my-username/ur5-act-policy")
Χαρακτηριστικά Hub:
- Κάρτες Μοντέλων: Αυτογεννούνται από τον κώδικα σας (επιδιόρθωση του
README.mdστο αποθετήριο). - Σύνολα Δεδομένων: Έχουν έκδοση και είναι αναζητήσιμα (π.χ.,
huggingface.co/datasets/my-username/ur5_demos). - Spaces: Εκτελέστε αλληλεπιδραστικές δημοσιεύσεις (βλέπε LeRobot Spaces).
Πιθανά Προβλήματα:
- Μεγάλα αρχεία: Σύνολα δεδομένων >10GB μπορεί να αποτύχουν. Χρησιμοποιήστε
lerobot push_to_hub --chunk_size 1G. - Αδεια: Πάντα να ορίζετε αδεια (π.χ.,
mitήapache-2.0) στοmetadata.json.
7. Οδηγοί Ειδικοί για Υλικό
SO-100 (Επίσημη Υποστήριξη)
Ο LeRobot περιλαμβάνει ενσωματωμένη υποστήριξη για τον SO-100 κινητό ρομποτικό βραχίονα.
Εγκατάσταση οδηγών SO-100:
pip install lerobot[so100]
Παράδειγμα: Τηλεχειρισμός SO-100:
lerobot record \
--robot so100 \
--sensors rgb_camera base_pose \
--output_dir ./so100_navigation
Βραχίονες Koch Robotics
Για τους βραχίονες Koch K1/K2, χρησιμοποιήστε την διεπαφή ROS 2:
from lerobot.hardware import KochArm
robot = KochArm()
robot.move_to_joint_positions([0.5, -0.3, 0.0,
