LeRobot (Hugging Face) einrichten: Ein praktischer Leitfaden

Zusammenfassung

• Installieren Sie LeRobot in 2 Minuten mit pip install lerobot und testen Sie eine vorab trainierte Strategie an einem simulierten Franka-Arm.
• Nehmen Sie Teleoperationsdaten von einem echten Roboter (z. B. UR5) mit dem lerobot.record-CLI-Tool auf.
• Trainieren Sie eine individuelle Strategie aus Demonstrationen mit nur 3 Codezeilen mithilfe von lerobot.train.
• Bewerten Sie in der Simulation (Isaac Gym) oder setzen Sie auf Hardware (SO-100) mit minimalen Codeanpassungen ein.
• Teilen Sie Datensätze/Modelle auf dem Hugging Face Hub mit lerobot.push_to_hub.

1. Installation und LeRobot-Datensatzformat

LeRobot installieren

Beginnen Sie mit der offiziellen Installation. Für die meisten Nutzer ist das Python-Paket die schnellste Option:

pip install lerobot -U

Installation überprüfen:

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

Erwartetes Ergebnis:

0.5.0

GitHub-Releases

Überblick zum Datensatzformat

LeRobot-Datensätze folgen dem RLDS (Robot Learning Dataset Standard), jedoch mit spezifischen Erweiterungen von Hugging Face. Eine minimale Verzeichnisstruktur sieht wie folgt aus:

my_dataset/
├── scenes/               # Optional: 3D-Szenenkonfigurationen
│   └── table.yaml
├── trajectories/         # Aufgezeichnete Demonstrationen
│   ├── demo_0.h5         # HDF5-Format (erforderlich)
│   ├── demo_1.h5
│   └── ...
└── metadata.json         # Datensatzbeschreibung (erforderlich)

Wichtige Felder in metadata.json:

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

Datensatz-Anleitung

Häufige Fehler:

• Fehlende metadata.json: LeRobot wirft eine ValueError: Dataset metadata not found aus.
• Falsche HDF5-Struktur: Stellen Sie sicher, dass jede .h5-Datei die Gruppen /observations und /actions enthält.

2. Laden vorab trainierter Strategien

LeRobot bietet drei einsatzbereite Strategietypen: ACT (Action Chunk Transformer), Diffusion Policy und SmolVLA (Small Vision-Language-Action). Hier erfahren Sie, wie Sie diese laden und testen.

ACT-Strategie laden

from lerobot import ACTPolicy

# Laden Sie das vorab trainierte ACT-Modell (Franka-Arm, Tischmanipulation)
policy = ACTPolicy.from_pretrained("lerobot/act3d-franka-table")

# Simulieren Sie einen Schritt (Eingabe: Dictionary der Beobachtungen)
observation = {
    "image": torch.randn(3, 256, 256),  # RGB-Bild
    "joint_states": torch.randn(7),     # Gelenkwinkel des Arms
    "ee_pose": torch.randn(7)            # Position des Endeffektors
}
action = policy(observation)
print(action.shape)  # Erwartetes Ergebnis: torch.Size([7]) für Gelenkmomente

Modell-Dokumentation

Diffusion-Strategie laden

from lerobot import DiffusionPolicy

# Laden Sie die Diffusion-Strategie für Greifaufgaben
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_policy-grasp")

# Generieren Sie eine Aktion (stochastisch)
action = policy.sample(observation)
print(action)  # Ausgabe: {"action": tensor([...]), "log_probs": tensor([...])}

Modell-Dokumentation

SmolVLA laden

from lerobot import SmolVLA

# Laden Sie das VLA-Modell für sprachgesteuerte Aufgaben
vla = SmolVLA.from_pretrained("lerobot/smolvla-aloha")

# Abfrage mit Text und Bild
query = {
    "image": torch.randn(3, 224, 224),
    "text": "Hebe den roten Block auf",
    "joint_states": torch.randn(7)
}
action = vla(query)
print(action)  # Ausgabe: tensor([...]) für Gelenkaktionen

Hugging Face Blog

Wichtige Hinweise:

• ACT-Strategien erfordern Beobachtungen im normalisierten Format (Skalierung prüfen Sie in der Modell-Dokumentation).
• Diffusion-Strategien sind langsamer (~100 ms pro Schritt), aber effizienter in der Stichprobenentnahme.
• SmolVLA benötigt vorberechnete Texteinbettungen (falls fehlend, verwenden Sie lerobot.tokenizers).

3. Aufnahme von Teleoperationsdaten an einem echten Arm

Verwenden Sie das lerobot.record-CLI-Tool, um Daten von einem echten Roboter zu sammeln. Hier ein Beispiel für einen UR5.

Voraussetzungen

1. Installieren Sie ROS 2 (Humble) und den UR-Treiber:

   sudo apt install ros-humble-ur-driver
   

   Copy
2. Stellen Sie sicher, dass Ihr Roboter im Netzwerk erreichbar ist und über ROS 2 angesprochen werden kann.

Datensatz aufnehmen

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

Hardware-Dokumentation

Erwartete Ausgabe:

Aufnahme eines Datensatzes für UR5e...
Episode 1/10: Warte auf Teleoperations-Eingabe...
[ROS 2-Knoten gestartet: /lerobot_recorder]
[Aufnahme in: ./ur5_demos/trajectories/episode_0.h5]
[Drücken Sie Strg+C, um Episode zu beenden]

Teleoperationsmodi

Häufige Fehler:

• ROS 2-Verbindung fehlgeschlagen: Überprüfen Sie ROS_DOMAIN_ID und ROS_MASTER_URI. Lösung: Führen Sie export ROS_DOMAIN_ID=0 vor der Aufnahme aus.
• Sensor-Kalibrierung: Falls RGB-Bilder verzerrt sind, kalibrieren Sie die Kamera mit ros2 camera_calibration.

4. Training einer Strategie aus Demonstrationen

Trainieren Sie eine individuelle Strategie mit der lerobot.train-API. Hier ein Beispiel für BC (Behavior Cloning).

Training von Grund auf

from lerobot import BehaviorCloningTrainer
from lerobot.datasets import load_dataset

# Laden Sie Ihren Datensatz
dataset = load_dataset("path/to/ur5_demos")

# Initialisieren Sie den Trainer
trainer = BehaviorCloningTrainer(
    model="lerobot/act3d-base",  # Starten Sie mit einem vorab trainierten Modell
    dataset=dataset,
    batch_size=32,
    epochs=50,
    lr=1e-4
)

# Trainieren!
trainer.train()
trainer.push_to_hub("my-ur5-policy")  # Speichern auf Hugging Face Hub

API-Dokumentation

Anpassung der Hyperparameter

Wichtige Parameter zur Anpassung:

Wichtige Hinweise:

• Überanpassung: Falls Trainingsverlust deutlich niedriger als Validierungsverlust ist, reduzieren Sie die Modellkapazität oder fügen Sie Datenaugmentierung hinzu.
• Aktionsskalierung: Stellen Sie sicher, dass die Aktionen in Ihrem Datensatz dem Befehlsbereich des Roboters entsprechen (z. B. [-1, 1] für Momente).

5. Bewertung in der Simulation und auf Hardware

Bewertung in Isaac Gym

from lerobot.sim import IsaacGymEnv
from lerobot import ACTPolicy

# Laden Sie Strategie und Umgebung
policy = ACTPolicy.from_pretrained("my-ur5-policy")
env = IsaacGymEnv(robot="ur5e", task="pick_place")

# Führen Sie die Bewertung durch
success_rate = env.evaluate(policy, episodes=10)
print(f"Erfolgsquote: {success_rate * 100:.2f}%")

NVIDIA Entwickler

Erwartete Ausgabe:

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

Einsatz auf Hardware (UR5-Beispiel)

from lerobot.hardware import UR5Controller
from lerobot import ACTPolicy

# Initialisieren Sie Roboter und Strategie
robot = UR5Controller()
policy = ACTPolicy.from_pretrained("my-ur5-policy")

# Geschlossener Regelkreis
while True:
    obs = robot.get_observations()
    action = policy(obs)
    robot.send_action(action)

Hardware-Dokumentation

Hardware-Unterstützungstabelle:

Wichtige Hinweise:

• Latenz: Bei der Hardware-Einsatzzeit muss die Schleifenzeit <50 ms liegen. Verwenden Sie robot.set_control_rate(20) für 20 Hz-Updates.
• Sicherheit: Aktivieren Sie Kraft-/Momentbegrenzungen und Notstopp im Hardware-Modus immer.

6. Hochladen von Datensätzen und Modellen auf den Hub

Teilen Sie Ihre Arbeit mit der Community über den Hugging Face Hub.

Datensatz hochladen

lerobot push_to_hub \
  --path ./ur5_demos \
  --repo_id my-username/ur5-pick-place-demos \
  --private  # Optional: Auf False setzen für öffentliche Freigabe

Datensatz-Anleitung

Modell hochladen

from lerobot import ACTPolicy

# Laden Sie Ihre trainierte Strategie
policy = ACTPolicy.from_pretrained("lerobot/act3d-base")
policy.train()  # Angenommen, Sie haben es trainiert

# Hochladen auf den Hub
policy.push_to_hub("my-username/ur5-act-policy")

Modell-Hub

Hub-Funktionen:

• Modellkarten: Werden automatisch aus Ihrem Code generiert (bearbeiten Sie README.md im Repository).
• Datensätze: Versioniert und durchsuchbar (z. B. huggingface.co/datasets/my-username/ur5_demos).
• Spaces: Interaktive Demos bereitstellen (siehe LeRobot Spaces).

Wichtige Hinweise:

• Große Dateien: Datensätze >10 GB können fehlschlagen. Verwenden Sie lerobot push_to_hub --chunk_size 1G.
• Lizenz: Geben Sie immer eine Lizenz an (z. B. mit oder apache-2.0) in metadata.json an.

7. Hardware-spezifische Anleitungen

SO-100 (Offizielle Unterstützung)

LeRobot bietet native Unterstützung für den SO-100-Mobilmanipulator.

SO-100-Treiber installieren:

pip install lerobot[so100]

Hardware-Dokumentation

Beispiel: SO-100 teleoperieren

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

Arme von Koch Robotics

Für Koch K1/K2-Arme verwenden Sie die ROS 2-Schnittstelle:

from lerobot.hardware import KochArm

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