Hoe je LeRobot (Hugging Face) Installeert: Een Praktische Gids

TL;DR

• Installeer LeRobot in 2 minuten met pip install lerobot en test met een voorafgetrainde beleidsregel op een gesimuleerde Franka-arm.
• Neem teleoperatiedata op van een echte robot (bijv. UR5) met behulp van de lerobot.record CLI-tool.
• Train een aangepaste beleidsregel op basis van demonstraties met slechts 3 regels code met lerobot.train.
• Evalueer in simulatie (Isaac Gym) of implementeer op hardware (SO-100) met minimale codewijzigingen.
• Deel datasets en modellen op de Hugging Face Hub met lerobot.push_to_hub.

1. Installatie en het LeRobot Dataset Formaat

LeRobot Installeren

Begin met de officiële installatie. Voor de meeste gebruikers is het Python-pakket de snelste optie:

pip install lerobot -U

Installatie controleren:

python -c "import lerobot; print(lerobot.__version__)"

Verwachte uitvoer:

0.5.0

GitHub Releases

Overzicht Dataset Formaat

LeRobot datasets volgen het RLDS (Robot Learning Dataset Standard)-formaat, maar met specifieke extensies van Hugging Face. Een minimale mapstructuur voor een dataset ziet er als volgt uit:

my_dataset/
├── scenes/               # Optioneel: 3D scene configuraties
│   └── table.yaml
├── trajectories/         # Opgenomen demonstraties
│   ├── demo_0.h5         # HDF5-formaat (verplicht)
│   ├── demo_1.h5
│   └── ...
└── metadata.json         # Dataset beschrijving (verplicht)

Belangrijke velden in metadata.json:

{
  "description": "UR5 pick-and-place dataset",
  "robot": "ur5e",
  "tasks": ["pick", "place"],
  "sensors": ["rgb_camera", "joint_states"],
  "version": "0.1.0"
}

Dataset Gids

Gebruikelijke fouten:

• Ontbrekende metadata.json: LeRobot geeft een ValueError: Dataset metadata niet gevonden.
• Onjuiste HDF5-structuur: Zorg ervoor dat elk .h5-bestand de groepen /observations en /actions bevat.

2. Voorafgetrainde Beleidsregels Laden

LeRobot biedt drie kant-en-klaar beleidsregeltypes: ACT (Action Chunk Transformer), Diffusion Policy en SmolVLA (Small Vision-Language-Action). Hier leer je ze laden en testen.

ACT Beleidsregel Laden

from lerobot import ACTPolicy

# Laad de voorafgetrainde ACT-model (Franka-arm, tafelmanipulatie)
policy = ACTPolicy.from_pretrained("lerobot/act3d-franka-table")

# Simuleer een stap (input: dict met observaties)
observation = {
    "image": torch.randn(3, 256, 256),  # RGB-afbeelding
    "joint_states": torch.randn(7),     # Arm gewrichtshoeken
    "ee_pose": torch.randn(7)            # Eind-effectorpunt
}
action = policy(observation)
print(action.shape)  # Verwachte uitvoer: torch.Size([7]) voor gewrichtskoppels

Modelkaarten

Diffusion Beleidsregel Laden

from lerobot import DiffusionPolicy

# Laad de diffusion beleidsregel voor grijpen
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_policy-grasp")

# Genereer een actie (stochastisch)
action = policy.sample(observation)
print(action)  # Uitvoer: {"action": tensor([...]), "log_probs": tensor([...])}

Modelkaarten

SmolVLA Laden

from lerobot import SmolVLA

# Laad de VLA-model voor taakgerichte taken met taal
vla = SmolVLA.from_pretrained("lerobot/smolvla-aloha")

# Vraag met tekst en afbeelding
query = {
    "image": torch.randn(3, 224, 224),
    "text": "pak het rode blok op",
    "joint_states": torch.randn(7)
}
action = vla(query)
print(action)  # Uitvoer: tensor([...]) voor gewrichtsacties

Hugging Face Blog

Valkuilen:

• ACT-beleidsregels vereisen observaties in genormaliseerd formaat (controleer de modelkaart voor schaalverdeling).
• Diffusion-beleidsregels zijn trager (~100 ms per stap) maar efficiënter in het genereren van monsters.
• SmolVLA heeft vooraf berekende tekstembedding nodig (gebruik lerobot.tokenizers als deze ontbreken).

3. Opnemen van Teleoperatiedatasets op een Echte Arm

Gebruik de lerobot.record CLI-tool om data van een echte robot op te nemen. Hier volgt een voorbeeld voor een UR5.

Voorwaarden

1. Installeer ROS 2 (Humble) en de UR-driver:

   sudo apt install ros-humble-ur-driver
   

   Copy
2. Zorg ervoor dat je robot op het netwerk is aangesloten en bereikbaar via ROS 2.

Dataset Opnemen

lerobot record \
  --robot ur5e \
  --sensors rgb_camera joint_states \
  --output_dir ./ur5_demos \
  --max_episodes 10

Hardware Documentatie

Verwachte uitvoer:

Dataset opnemen voor UR5e...
Episode 1/10: Wacht op teleoperatie-invoer...
[ROS 2-knooppunt gestart: /lerobot_recorder]
[Opname naar: ./ur5_demos/trajectories/episode_0.h5]
[Druk Ctrl+C om episode te beëindigen]

Teleoperatiemodi

Gebruikelijke fouten:

• ROS 2-verbinding mislukt: Controleer of ROS_DOMAIN_ID en ROS_MASTER_URI zijn ingesteld. Oplossing: Voer export ROS_DOMAIN_ID=0 uit voordat je de opname start.
• Sensor kalibratie: Als RGB-afbeeldingen vervormd zijn, recalibreer de camera met ros2 camera_calibration.

4. Een Beleidsregel Trainen op Basis van Demonstraties

Train een aangepaste beleidsregel met behulp van de lerobot.train-API. Hier volgt een voorbeeld van BC (Behavior Cloning).

Van Scratch Trainen

from lerobot import BehaviorCloningTrainer
from lerobot.datasets import load_dataset

# Laad je dataset
dataset = load_dataset("path/to/ur5_demos")

# Initialiseer trainer
trainer = BehaviorCloningTrainer(
    model="lerobot/act3d-base",  # Start met een voorafgetrainde basis
    dataset=dataset,
    batch_size=32,
    epochs=50,
    lr=1e-4
)

# Train!
trainer.train()
trainer.push_to_hub("my-ur5-policy")  # Sla op naar Hugging Face Hub

API Documentatie

Hyperparameter Afstemming

Belangrijke parameters om aan te passen:

Valkuilen:

• Overfitting: Als de trainingsloss << validatieloss, verminder de modelcapaciteit of voeg data-augmentatie toe.
• Actieschaal: Zorg ervoor dat de acties in je dataset overeenkomen met het commandobereik van de robot (bijv. [-1, 1] voor koppels).

5. Evaluatie in Simulatie en op Hardware

Evalueren in Isaac Gym

from lerobot.sim import IsaacGymEnv
from lerobot import ACTPolicy

# Laad beleidsregel en omgeving
policy = ACTPolicy.from_pretrained("my-ur5-policy")
env = IsaacGymEnv(robot="ur5e", task="pick_place")

# Voer evaluatie uit
success_rate = env.evaluate(policy, episodes=10)
print(f"Succespercentage: {success_rate * 100:.2f}%")

NVIDIA Developer

Verwachte uitvoer:

Episode 1/10: Success = True
Episode 2/10: Success = False
...

Implementeren op Hardware (UR5 Voorbeeld)

from lerobot.hardware import UR5Controller
from lerobot import ACTPolicy

# Initialiseer robot en beleidsregel
robot = UR5Controller()
policy = ACTPolicy.from_pretrained("my-ur5-policy")

# Voer gesloten-lusbesturing uit
while True:
    obs = robot.get_observations()
    action = policy(obs)
    robot.send_action(action)

Hardware Documentatie

Hardware Ondersteuningstabel:

Valkuilen:

• Latentie: Echte implementatie vereist <50ms looptime. Gebruik robot.set_control_rate(20) voor 20Hz-updates.
• Veiligheid: Schakel kracht-/koppelbeperkingen en noodstop altijd in bij hardwaremodus.

6. Datasets en Modellen naar de Hub Uploaden

Deel je werk met de community via de Hugging Face Hub.

Dataset Uploaden

lerobot push_to_hub \
  --path ./ur5_demos \
  --repo_id my-username/ur5-pick-place-demos \
  --private  # Optioneel: Zet op False voor publiek

Dataset Gids

Model Uploaden

from lerobot import ACTPolicy

# Laad je getrainde beleidsregel
policy = ACTPolicy.from_pretrained("lerobot/act3d-base")
policy.train()  # Aanname: je hebt het getraind

# Upload naar Hub
policy.push_to_hub("my-username/ur5-act-policy")

Model Hub

Hub Functies:

• Modelkaarten: Automatisch gegenereerd uit je code (pas README.md in de repo aan).
• Datasets: Versiebeheerd en doorzoekbaar (bijv., huggingface.co/datasets/my-username/ur5_demos).
• Spaces: Implementeer interactieve demonstraties (zie LeRobot Spaces).

Valkuilen:

• Grote bestanden: Datasets >10GB kunnen mislukken. Gebruik lerobot push_to_hub --chunk_size 1G.
• Licentie: Specificeer altijd een licentie (bijv., mit of apache-2.0) in metadata.json.

7. Hardware-specifieke Gidsen

SO-100 (Officieel Ondersteund)

LeRobot biedt native ondersteuning voor de SO-100 mobiele manipulator.

Installeer SO-100-drivers:

pip install lerobot[so100]

Hardware Documentatie

Voorbeeld: Teleoperatie SO-100:

lerobot record \
  --robot so100 \
  --sensors rgb_camera base_pose \
  --output_dir ./so100_navigation

Koch Robotics Armen

Voor Koch K1/K2-armen, gebruik de ROS 2-interface:

from lerobot.hardware import KochArm

robot = KochArm()
robot.move_to_joint_positions([0.5, -0.3, 0.0,