Πώς να Εγκαταστήσετε και να Χρησιμοποιήσετε τον LeRobot (Hugging Face): Ένας Πρακτικός Οδηγός

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

GitHub Releases

Υπερσυνοπτική Παρουσίαση της Μορφής Δεδομένων

Τα σύνολα δεδομένων του 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([...]) για δράσεις στις αρθρώσεις

Blog Hugging Face

Πιθανά Προβλήματα:

• Οι πολιτικές ACT απαιτούν παρατηρήσεις σε κανονικοποιημένη μορφή (ελέγξτε την κάρτα του μοντέλου για κλίμακα).
• Οι πολιτικές Diffusion είναι πιο αργές (~100ms ανά βήμα) αλλά πιο αποδοτικές σε δείγματα.
• Το SmolVLA χρειάζεται προεπεξεργασμένα εμβέδματα κειμένου (χρησιμοποιήστε lerobot.tokenizers αν λείπουν).

3. Καταγραφή Δεδομένων Τηλεχειρισμού σε Πραγματικό Βραχίονα

Χρησιμοποιήστε την εντολή lerobot.record για να συλλέξετε δεδομένα από έναν πραγματικό ρομποτικό βραχίονα. Παρακάτω ακολουθεί ένα παράδειγμα για τον UR5.

Προαπαιτούμενα

1. Εγκαταστήστε το ROS 2 (Humble) και τον οδηγό του UR:

   sudo apt install ros-humble-ur-driver
   

   Copy
2. Βεβαιωθείτε ότι ο ρομπότας είναι συνδεδεμένος στο δίκτυο και προσβάσιμος μέσω 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 για να τελειώσετε το επεισόδιο]

Μορφές Τηλεχειρισμού

Συχνά Σφάλματα:

• Αποτυχία σύνδεσης 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

Τεχνική Υποστήριξη API

Προσαρμογή Υπερπαραμέτρων

Κύριες παραμέτρους που μπορείτε να προσαρμόσετε:

Πιθανά Προβλήματα:

• Υπερεκπαίδευση: Αν η εκπαιδευτική ζημιά είναι πολύ μικρότερη από αυτή του ελέγχου, μειώστε την ικανότητα του μοντέλου ή προσθέστε αύξηση δεδομένων.
• Κλίμακα δράσεων: Βεβαιωθείτε ότι οι δράσεις στο σύνολο δεδομένων σας ταιριάζουν με την κλίμακα εντολών του ρομπότ (π.χ., [-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}%")

NVIDIA Developer

Προσδοκώμενο Αποτέλεσμα:

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)

Τεχνική Υποστήριξη Υλικού

Πίνακας Υποστήριξης Υλικού:

Πιθανά Προβλήματα:

• Υστέρηση: Η εκτέλεση σε πραγματικό υλικό απαιτεί <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 Μοντέλων

Χαρακτηριστικά 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,