En bref
- Installez LeRobot en 2 minutes avec
pip install lerobotet 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"
}
Erreurs courantes :
- Fichier
metadata.jsonmanquant : LeRobot affichera une erreurValueError: Metadata du jeu de données introuvable. - Structure HDF5 incorrecte : Assurez-vous que chaque fichier
.h5contient les groupes/observationset/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
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([...])}
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
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.tokenizerssi 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
- Installez ROS 2 (Humble) et le pilote UR :
sudo apt install ros-humble-ur-driver - 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
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
| Mode | Option de commande | Description |
|---|---|---|
| Clavier | --teleop_mode keyboard | Utilisez les touches directionnelles pour contrôler le robot. |
| Manette | --teleop_mode joystick | Nécessite le package python-joystick. |
| Gamepad | --teleop_mode gamepad | Compatible avec les contrôleurs XInput. |
| Guide des capteurs |
Erreurs courantes :
- Échec de connexion ROS 2 : Vérifiez les variables
ROS_DOMAIN_IDetROS_MASTER_URI. Correction : Exécutezexport ROS_DOMAIN_ID=0avant 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
Ajustement des hyperparamètres
Paramètres clés à ajuster :
| Paramètre | Valeur par défaut | Plage recommandée | Description |
|---|---|---|---|
batch_size | 32 | 16–128 | Des tailles de batch plus grandes = entraînement plus rapide. |
lr | 1e-4 | 1e-5 à 1e-3 | Trop élevé = instabilité ; trop bas = lent. |
epochs | 50 | 20–200 | Arrêt précoce si la perte de validation stagne. |
kl_weight | 0.1 | 0.01–0.5 | Uniquement pour l'apprentissage par renforcement affinement. |
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}%")
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)
Tableau de compatibilité matériel :
| Robot | Support LeRobot | Notes |
|---|---|---|
| UR5/UR10 | ✅ | Pilote ROS 2 requis. |
| Franka Emika | ✅ | Fonctionne avec le package franka_ros2. |
| SO-100 | ✅ | Support officiel (voir ci-dessous). |
| Stretch RE1 | ✅ | Nécessite le pilote stretch_ros2. |
| Aloha | ✅ | Expérimental (disponible à partir de 2026-05). |
| Documentation 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
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")
Fonctionnalités du Hub :
- Fiches modèles : Générées automatiquement à partir de votre code (modifiez le fichier
README.mddans 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,
mitouapache-2.0) dansmetadata.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]
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,
