Comment configurer LeRobot (Hugging Face) : Un guide pratique

En bref

• Installez LeRobot en 2 minutes avec pip install lerobot et testez avec une politique préentraînée sur un bras Franka simulé.
• Enregistrez des données de téléopération depuis un robot réel (par exemple, un UR5) en utilisant l'outil CLI lerobot.record.
• Entraînez une politique personnalisée à partir de démonstrations en 3 lignes de code avec lerobot.train.
• Évaluez en simulation (Isaac Gym) ou déployez sur matériel (SO-100) avec des modifications de code minimales.
• Partagez vos jeux de données et modèles sur Hugging Face Hub avec lerobot.push_to_hub.

1. Installation et format des jeux de données LeRobot

Installer LeRobot

Commencez par l'installation officielle. Pour la plupart des utilisateurs, le package Python est l'option la plus rapide :

pip install lerobot -U

Vérification de l'installation :

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

Résultat attendu :

0.5.0

Liens vers les versions GitHub

Vue d'ensemble du format des jeux de données

Les jeux de données LeRobot suivent le standard RLDS (Robot Learning Dataset Standard), mais avec des extensions spécifiques à Hugging Face. Une structure minimale de répertoire ressemble à ceci :

my_dataset/
├── scenes/               # Optionnel : configurations 3D des scènes
│   └── table.yaml
├── trajectories/         # Démonstrations enregistrées
│   ├── demo_0.h5         # Format HDF5 (obligatoire)
│   ├── demo_1.h5
│   └── ...
└── metadata.json         # Description du jeu de données (obligatoire)

Champs clés dans metadata.json :

{
  "description": "Jeu de données de préhension et de dépôt pour **UR5**",
  "robot": "ur5e",
  "tasks": ["pick", "place"],
  "sensors": ["rgb_camera", "joint_states"],
  "version": "0.1.0"
}

Guide des jeux de données

Erreurs courantes :

• Fichier metadata.json manquant : LeRobot affichera une erreur ValueError: Metadata du jeu de données introuvable.
• Structure HDF5 incorrecte : Assurez-vous que chaque fichier .h5 contient les groupes /observations et /actions.

2. Chargement des politiques préentraînées

LeRobot propose 3 types de politiques prêtes à l'emploi : ACT (Action Chunk Transformer), Diffusion Policy et SmolVLA (Small Vision-Language-Action). Voici comment les charger et les tester.

Charger une politique ACT

from lerobot import ACTPolicy

# Charger un modèle ACT préentraîné (bras Franka, manipulation sur table)
policy = ACTPolicy.from_pretrained("lerobot/act3d-franka-table")

# Simuler une étape (entrée : dictionnaire d'observations)
observation = {
    "image": torch.randn(3, 256, 256),  # Image RGB
    "joint_states": torch.randn(7),     # Angles des articulations du bras
    "ee_pose": torch.randn(7)            # Position de l'effecteur final
}
action = policy(observation)
print(action.shape)  # Résultat attendu : torch.Size([7]) pour les couples articulaires

Fiches modèles

Charger une politique de diffusion

from lerobot import DiffusionPolicy

# Charger une politique de diffusion pour la préhension
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_policy-grasp")

# Échantillonner une action (stochastique)
action = policy.sample(observation)
print(action)  # Résultat : {"action": tensor([...]), "log_probs": tensor([...])}

Fiches modèles

Charger SmolVLA

from lerobot import SmolVLA

# Charger le modèle VLA pour des tâches conditionnées par le langage
vla = SmolVLA.from_pretrained("lerobot/smolvla-aloha")

# Requête avec texte et image
query = {
    "image": torch.randn(3, 224, 224),
    "text": "ramasser le bloc rouge",
    "joint_states": torch.randn(7)
}
action = vla(query)
print(action)  # Résultat : tensor([...]) pour les actions articulaires

Blog Hugging Face

Points d'attention :

• Les politiques ACT nécessitent des observations au format normalisé (vérifiez la fiche modèle pour les paramètres d'échelle).
• Les politiques de diffusion sont plus lentes (~100 ms par étape) mais plus efficaces en échantillonnage.
• SmolVLA nécessite des embeddings de texte précomputés (utilisez lerobot.tokenizers si nécessaire).

3. Enregistrement de jeux de données par téléopération sur un bras réel

Utilisez l'outil CLI lerobot.record pour collecter des données depuis un robot réel. Voici un exemple pour un UR5.

Prérequis

1. Installez ROS 2 (Humble) et le pilote UR :

   sudo apt install ros-humble-ur-driver
   

   Copy
2. Assurez-vous que votre robot est sur le réseau et accessible via ROS 2.

Enregistrer un jeu de données

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

Documentation matériel

Résultat attendu :

Enregistrement du jeu de données pour UR5e...
Épisode 1/10 : Attente des commandes de téléopération...
[Nœud ROS 2 démarré : /lerobot_recorder]
[Enregistrement vers : ./ur5_demos/trajectories/episode_0.h5]
[Appuyez sur Ctrl+C pour terminer l'épisode]

Modes de téléopération

Erreurs courantes :

• Échec de connexion ROS 2 : Vérifiez les variables ROS_DOMAIN_ID et ROS_MASTER_URI. Correction : Exécutez export ROS_DOMAIN_ID=0 avant l'enregistrement.
• Calibration des capteurs : Si les images RGB sont déformées, recalibrez la caméra avec ros2 camera_calibration.

4. Entraînement d'une politique à partir de démonstrations

Entraînez une politique personnalisée en utilisant l'API lerobot.train. Voici un exemple avec BC (Behavior Cloning).

Entraînement à partir de zéro

from lerobot import BehaviorCloningTrainer
from lerobot.datasets import load_dataset

# Charger votre jeu de données
dataset = load_dataset("path/to/ur5_demos")

# Initialiser l'entraîneur
trainer = BehaviorCloningTrainer(
    model="lerobot/act3d-base",  # Démarrer à partir d'un modèle préentraîné
    dataset=dataset,
    batch_size=32,
    epochs=50,
    lr=1e-4
)

# Lancer l'entraînement !
trainer.train()
trainer.push_to_hub("my-ur5-policy")  # Sauvegarder sur Hugging Face Hub

Documentation API

Ajustement des hyperparamètres

Paramètres clés à ajuster :

Points d'attention :

• Surcharge : Si la perte d'entraînement << perte de validation, réduisez la capacité du modèle ou ajoutez de l'augmentation de données.
• Échelle des actions : Assurez-vous que les actions dans votre jeu de données correspondent à la plage de commandes du robot (par exemple, [-1, 1] pour les couples).

5. Évaluation en simulation et sur matériel

Évaluer dans Isaac Gym

from lerobot.sim import IsaacGymEnv
from lerobot import ACTPolicy

# Charger la politique et l'environnement
policy = ACTPolicy.from_pretrained("my-ur5-policy")
env = IsaacGymEnv(robot="ur5e", task="pick_place")

# Lancer l'évaluation
success_rate = env.evaluate(policy, episodes=10)
print(f"Taux de succès : {success_rate * 100:.2f}%")

NVIDIA Developer

Résultat attendu :

Épisode 1/10 : Succès = True
Épisode 2/10 : Succès = False
...

Déploiement sur matériel (exemple UR5)

from lerobot.hardware import UR5Controller
from lerobot import ACTPolicy

# Initialiser le robot et la politique
robot = UR5Controller()
policy = ACTPolicy.from_pretrained("my-ur5-policy")

# Boucle de contrôle en temps réel
while True:
    obs = robot.get_observations()
    action = policy(obs)
    robot.send_action(action)

Documentation matériel

Tableau de compatibilité matériel :

Points d'attention :

• Latence : Le déploiement en temps réel nécessite un temps de boucle <50 ms. Utilisez robot.set_control_rate(20) pour des mises à jour à 20 Hz.
• Sécurité : Activez toujours les limites de force/couple et les arrêts d'urgence en mode matériel.

6. Publication de jeux de données et modèles sur le Hub

Partagez votre travail avec la communauté via Hugging Face Hub.

Publier un jeu de données

lerobot push_to_hub \
  --path ./ur5_demos \
  --repo_id my-username/ur5-pick-place-demos \
  --private  # Optionnel : Définissez sur False pour le rendre public

Guide des jeux de données

Publier un modèle

from lerobot import ACTPolicy

# Charger votre politique entraînée
policy = ACTPolicy.from_pretrained("lerobot/act3d-base")
policy.train()  # Supposons que vous l'ayez entraîné

# Publier sur le Hub
policy.push_to_hub("my-username/ur5-act-policy")

Hub des modèles

Fonctionnalités du Hub :

• Fiches modèles : Générées automatiquement à partir de votre code (modifiez le fichier README.md dans le dépôt).
• Jeux de données : Versionnés et recherchables (par exemple, huggingface.co/datasets/my-username/ur5_demos).
• Spaces : Déployez des démonstrations interactives (voir LeRobot Spaces).

Points d'attention :

• Fichiers volumineux : Les jeux de données >10 Go peuvent échouer. Utilisez lerobot push_to_hub --chunk_size 1G.
• Licence : Spécifiez toujours une licence (par exemple, mit ou apache-2.0) dans metadata.json.

7. Guides spécifiques au matériel

SO-100 (Support officiel)

LeRobot inclut un support natif pour le manipulateur mobile SO-100.

Installer les pilotes SO-100 :

pip install lerobot[so100]

Documentation matériel

Exemple : Téléopération du SO-100 :

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

Bras robotisés Koch

Pour les bras Koch K1/K2, utilisez l'interface ROS 2 :

from lerobot.hardware import KochArm

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