Was Sie bauen und was Sie dafür brauchen
LeRobot ist die Open-Source-Robotikbibliothek von Hugging Face. Mit einheitlichen Befehlen bewegen Sie einen Roboter, nehmen Demonstrationen auf, trainieren eine Policy und führen sie aus. Der SO-101 ist der Flaggschiff-Arm der Bibliothek: Sie bewegen einen Leader-Arm von Hand, ein Follower-Arm ahmt die Bewegung nach, und die aufgezeichneten Bewegungen und Kamerabilder bringen einem neuronalen Netz bei, die Aufgabe selbstständig zu wiederholen.
Die Arbeit besteht aus sieben Stufen: Teile beschaffen und Software installieren, jedem Motor eine ID geben, beide Arme montieren, kalibrieren, mit Kameras per Teleoperation steuern, einen Datensatz aufnehmen und schließlich eine Policy trainieren und ausführen. Der letzte Bauabschnitt ergänzt die mobile Basis LeKiwi, danach folgt eine Checkliste zur Fehlersuche.
Seitlich wischen, um die ganze Abbildung zu sehen.
Sie benötigen zwei Arme (die Teile stehen im nächsten Abschnitt), für jeden Arm eine USB-Bus-Servo-Steuerplatine und ein Netzteil, einen Computer mit Python 3.12 oder neuer, zwei USB-Kameras (die Befehle in dieser Anleitung verwenden zwei), ein kostenloses Hugging Face-Konto für Datensätze und Checkpoints sowie eine GPU für das Training. Für die hier verwendete ACT-Policy genügt eine GPU der Laptop-Klasse; eine gemietete GPU funktioniert ebenfalls.
Wir haben diese Anleitung aus der offiziellen Dokumentation und aus Berichten der Community zusammengestellt und nicht jeden Schritt an jeder Hardwarerevision durch eigene Tests geprüft. Ältere Tutorials, die control_robot.py aufrufen, gelten nicht für 0.7.0, das die lerobot-*-Befehle verwendet.
Teile, 3D-Druck und Stromversorgung
Das SO-101-Projekt veröffentlicht die Stückliste und die Druckdateien; die Hugging Face-Seite zum SO-101 verlinkt beide. Ein vollständiges Paar aus Leader- und Follower-Arm braucht 12 Feetech STS3215-Servos, zwei Steuerplatinen, zwei Netzteile, zwei USB-C-Kabel und Tischklemmen. Für die Montage werden M2×6- und M3×6-Schrauben verwendet; die Stückliste des Projekts führt sie nicht auf, prüfen Sie daher, was Ihren Servos oder Ihrem Bausatz beiliegt. Gedruckte Teile und komplette Bausätze werden ebenfalls verkauft.
Der Follower-Arm verwendet sechs Servos mit einer Getriebeübersetzung von 1/345. Der Leader-Arm verwendet drei verschiedene Übersetzungen, damit er sein eigenes Gewicht halten kann und sich trotzdem mit wenig Kraft bewegen lässt.
Stimmen Sie das Netzteil auf die Servos ab. Der 7,4-V-STS3215 hat ein Blockiermoment von 16,5 kg·cm bei 6 V (an einem 5-V-Netzteil etwas weniger) und wird normalerweise an einem 5-V-Netzteil betrieben. Der Follower-Arm kann für mehr Leistung 12-V-Servos (30 kg·cm) verwenden, braucht dann aber ein 12-V-Netzteil mit mindestens 5 A; der Leader-Arm verwendet immer 7,4-V-Servos. Schließen Sie das 12-V-Netzteil niemals an eine Platine an, an der 7,4-V-Servos hängen; beschriften Sie jedes Netzteil mit seiner Spannung und dem Arm, zu dem es gehört.
Seitlich wischen, um die ganze Abbildung zu sehen.
Drucken Sie in PLA+ mit einer 0,4-mm-Düse bei 0,2 mm Schichthöhe (oder mit einer 0,6-mm-Düse bei 0,4 mm Schichthöhe) und 15 % Infill. Die Teile jedes Arms liegen als einzelne Datei vor, die so ausgerichtet ist, dass nur wenig Stützmaterial nötig ist; halten Sie horizontale Schraubenlöcher frei von Stützen. Drucken Sie zuerst die Testteile Gauge Zero und Gauge Tight und prüfen Sie sie an einem Servo; passt Gauge Zero nicht so, wie es im Video des Projekts gezeigt wird, passen Sie Ihre Druckereinstellungen an und drucken Sie das Teil erneut, bevor Sie die Arme drucken.
Halten Sie Kreuzschlitz-Schraubendreher (Phillips) Nr. 0 und Nr. 1 bereit und klemmen Sie jede Basis am Tisch fest, bevor Sie testen. Die Teile, die wir für diesen Aufbau liefern, sind unten verlinkt.
Seitlich scrollen, um alle Spalten zu vergleichen.
| Gelenk | Motor-ID | Getriebeübersetzung Leader | Getriebeübersetzung Follower |
|---|---|---|---|
| Schulterdrehung (Shoulder Pan) | 1 | 1/191 | 1/345 |
| Schulterhub (Shoulder Lift) | 2 | 1/345 | 1/345 |
| Ellbogenbeugung (Elbow Flex) | 3 | 1/191 | 1/345 |
| Handgelenkbeugung (Wrist Flex) | 4 | 1/147 | 1/345 |
| Handgelenkrotation (Wrist Roll) | 5 | 1/147 | 1/345 |
| Greifer (Gripper) | 6 | 1/147 | 1/345 |
LeRobot und Motorunterstützung installieren
LeRobot 0.7.0 benötigt Python 3.12 oder neuer. Erstellen Sie mit conda (aus miniforge) oder uv eine isolierte Umgebung und aktivieren Sie sie in jedem neuen Terminal. Für Videos wird auf den meisten Plattformen ffmpeg benötigt (auf Intel-Macs und unter 32-Bit-ARM-Linux weicht LeRobot auf PyAV aus, dort können Sie ffmpeg überspringen); das conda-Paket funktioniert mit jeder PyTorch-Version.
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forgeInstallieren Sie LeRobot von PyPI mit den Extras, die Sie brauchen. core_scripts ergänzt, was Aufnahme, Wiedergabe und Kalibrierung verwenden, feetech ergänzt die Unterstützung für die STS3215-Servos, und training ergänzt die Trainingswerkzeuge.
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'Hinweise zur Plattform: Auf Apple Silicon braucht PyTorch macOS 14 oder neuer, für die GPU-Beschleunigung (MPS) macOS 15 oder neuer. Um unter Linux eine NVIDIA-GPU zu nutzen, benötigen die Standard-Builds von PyTorch einen Treiber 580.65 oder neuer; bei einem älteren Treiber installieren Sie zuerst einen passenden CUDA-Build von PyTorch und beziehen torchcodec aus dem CPU-Index (siehe die Installationsseite von Hugging Face). Unter WSL installieren Sie außerdem evdev (conda install evdev -c conda-forge, oder mit uv sudo apt install libevdev-dev und danach uv pip install evdev). Ab PyTorch 2.10 können Sie statt der conda-Variante das ffmpeg des Systems verwenden.
Ports finden und Motor-IDs setzen
Neue STS3215-Servos werden in der Regel mit ID 1 geliefert, und der Controller und jeder Servo müssen dieselbe Baudrate verwenden. LeRobot schreibt beides einmalig in den Speicher jedes Servos. Erledigen Sie das daher vor der Montage und schließen Sie jeweils nur einen Servo an. Das gilt wahrscheinlich auch für Servos, die Sie aus einem anderen Roboter wiederverwenden.
Seitlich wischen, um die ganze Abbildung zu sehen.
Verbinden Sie eine Steuerplatine per USB mit dem Computer, versorgen Sie sie mit Strom und starten Sie den Port-Finder. Ziehen Sie auf Aufforderung nur das USB-Kabel dieser Platine ab und drücken Sie Enter; das Skript gibt den Port aus, etwa /dev/ttyACM0 unter Linux, /dev/tty.usbmodem… unter macOS oder COM3 unter Windows. Stecken Sie das Kabel wieder ein und wiederholen Sie das Ganze für die zweite Platine. Unter Linux müssen Sie den Zugriff eventuell mit sudo chmod 666 für jeden Port erlauben (zum Beispiel /dev/ttyACM0 und /dev/ttyACM1).
lerobot-find-portFühren Sie das Einrichtungsskript zuerst für den Follower-Arm aus, dann für den Leader-Arm, jeweils mit dem eigenen Port. Das Skript nennt immer nur einen Motor auf einmal; lesen Sie daher die folgenden Schritte, bevor Sie es starten.
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0Der Leader-Arm verwendet statt der Roboter-Optionen die Teleoperator-Optionen. Nehmen Sie bei jeder Aufforderung den Motor mit der Getriebeübersetzung, die in der Tabelle im Abschnitt zu den Teilen für das jeweilige Gelenk angegeben ist (beim Leader-Arm 1/191 für Schulterdrehung und Ellbogenbeugung, 1/345 für Schulterhub und 1/147 für Handgelenkbeugung, Handgelenkrotation und Greifer), und markieren Sie jeden Motor mit seiner ID, sobald das Skript meldet, dass sie gesetzt ist.
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- Das Skript nennt jeweils einen Motor, beginnend mit dem Greifer (ID 6) und endend mit der Schulterdrehung (ID 1). Schließen Sie nur diesen Motor an die Steuerplatine an; er darf nicht mit einem anderen Motor verkettet sein.
- Drücken Sie Enter. Meldet das Skript, dass die ID gesetzt ist, ziehen Sie das Kabel dieses Motors von der Platine ab, schließen Sie den nächsten genannten Motor an und drücken Sie erneut Enter.
- Prüfen Sie vor jedem Enter das Strom-, das USB- und das 3-Pin-Kabel. Meldet das Skript einen Fehler, prüfen Sie zuerst diese Kabel; bei einer Waveshare-Platine müssen außerdem beide Jumper auf Kanal B (USB) stehen.
- Wenn das Skript fertig ist, verbinden Sie die Motoren der Reihe nach zu einer Kette und schließen Sie den Motor der Schulterdrehung (ID 1) an die Steuerplatine an.
Seitlich wischen, um die ganze Abbildung zu sehen.
Motor-IDs einzeln setzen, danach die Servos der Reihe nach verketten
Leader- und Follower-Arm montieren
Beide Arme haben die meisten gedruckten Teile gemeinsam und werden in derselben Reihenfolge gebaut (das Teil für die Handgelenkrotation unterscheidet sich, und der Leader-Arm hat Griff und Abzug, wo der Follower-Arm eine bewegliche Backe hat): Basis und Schulter, Oberarm, Unterarm, Handgelenk, dann der Greifer am Follower-Arm beziehungsweise Griff und Abzug am Leader-Arm. Hugging Face veröffentlicht auf seiner SO-101-Seite für jedes Gelenk ein kurzes Video; schauen Sie es parallel zu diesen Hinweisen an. Entfernen Sie zuerst das gesamte Stützmaterial von den gedruckten Teilen und stecken Sie in jeden Servo ein 3-Pin-Kabel, bevor Sie ihn einbauen.
- Gelenk 1, Schulterdrehung: Setzen Sie beide Servohörner auf den Motor und sichern Sie das obere mit einer M3×6-Schraube (das untere Horn braucht keine). Setzen Sie den Motor mit vier M2×6-Schrauben in die Basis, schieben Sie den ersten Motorhalter mit zwei M2×6 auf, befestigen Sie die Schulter mit vier M3×6 oben und vier unten und fügen Sie den Schultermotorhalter hinzu.
- Gelenk 2, Schulterhub: Setzen Sie beide Servohörner auf und sichern Sie das obere mit einer M3×6-Schraube (das untere braucht keine), schieben Sie den Motor von oben ein, befestigen Sie ihn mit vier M2×6 und bringen Sie dann den Oberarm mit je vier M3×6 auf jeder Seite an.
- Gelenk 3, Ellbogen: Setzen Sie beide Servohörner auf und sichern Sie das obere mit einer M3×6-Schraube (das untere braucht keine), setzen Sie Motor 3 mit vier M2×6 ein und verbinden Sie den Unterarm damit, mit je vier M3×6 auf jeder Seite.
- Gelenk 4, Handgelenkbeugung: Setzen Sie beide Servohörner auf und sichern Sie das obere mit einer M3×6-Schraube (das untere braucht keine), schieben Sie Motorhalter 4 darüber, schieben Sie Motor 4 hinein und befestigen Sie ihn mit vier M2×6.
- Gelenk 5, Handgelenkrotation: Setzen Sie Motor 5 mit zwei M2×6 vorn in den Handgelenkhalter, setzen Sie ein einzelnes Servohorn mit einer M3×6-Schraube auf und sichern Sie das Handgelenk mit M3×6-Schrauben an Motor 4, wie im offiziellen Video zu Gelenk 5 gezeigt (die schriftliche Anleitung nennt vier auf beiden Seiten).
- Greifer des Follower-Arms: Befestigen Sie den Greifer mit vier M3×6 am Servohorn des Handgelenkmotors, setzen Sie den Greifermotor mit je zwei M2×6 auf jeder Seite ein, setzen Sie beide Servohörner auf und sichern Sie das obere mit einer M3×6-Schraube (das untere braucht keine), und sichern Sie die Greiferklaue mit M3×6-Schrauben, wie im offiziellen Greifer-Video gezeigt (die schriftliche Anleitung nennt vier auf beiden Seiten).
- Griff des Leader-Arms: Montieren Sie den Leader-Halter mit vier M3×6 am Handgelenk, befestigen Sie den Griff mit einer M2×6 daran, setzen Sie Motor 6, den Abzugsmotor (die offizielle Anleitung nennt ihn Greifermotor), mit je zwei M2×6 auf jeder Seite ein und ein Servohorn mit einer M3×6-Schraube auf, und bringen Sie dann den Abzug mit vier M3×6 an.
- Drehen Sie vor dem Einschalten jedes Gelenk langsam von Hand durch seinen gesamten Bereich und erzwingen Sie es nie über einen Anschlag hinaus; es sollte sich ohne Schleifen bewegen. Markieren Sie jeden Motor mit seiner ID, bevor Sie ihn einbauen, und klemmen Sie beide Basen am Tisch fest.
Beide Arme kalibrieren
Die Kalibrierung hält den Bereich jedes Gelenks fest, damit Leader- und Follower-Arm in derselben physischen Stellung dieselben Werte melden. Außerdem kann dadurch eine Policy, die auf einem Roboter trainiert wurde, auf einem anderen laufen. Führen Sie sie einmal für jeden Arm durch, und erneut nach einer Hardwareänderung oder wenn LeRobot eine fehlende Kalibrierung meldet. Aufnahmen und Policies, die vor einer Neukalibrierung entstanden sind, haben die alte Kalibrierung verwendet.
Kalibrieren Sie zuerst den Follower-Arm. Das Skript fordert Sie auf, jedes Gelenk in die Mitte seines Bereichs zu bewegen und Enter zu drücken, und danach jedes Gelenk durch seinen gesamten Bewegungsbereich zu führen und erneut Enter zu drücken, sobald jedes Gelenk ihn durchlaufen hat. Geben Sie jedem Arm eine eindeutige id; dieser Name kennzeichnet seine Kalibrierdatei. Die Befehle in dieser Anleitung verwenden als Beispiele /dev/ttyACM0 für den Follower-Arm und /dev/ttyACM1 für den Leader-Arm: Ersetzen Sie sie durch die gefundenen Ports und vertauschen Sie die beiden Arme nicht.
Seitlich wischen, um die ganze Abbildung zu sehen.
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_armKalibrieren Sie dann den Leader-Arm mit denselben Bewegungen.
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_armVerwenden Sie in jedem späteren Befehl dieselbe id; so findet LeRobot die Kalibrierdatei, die standardmäßig unter ~/.cache/huggingface/lerobot/calibration gespeichert ist. Sichern Sie sie und halten Sie sie aus temporären Ordnern heraus: Ein Nachbauer aus der Community verlor die Kalibrierdateien bei einem Aus- und Wiedereinschalten und führte die Kalibrierung erneut durch, ohne jedes Gelenk in die Mitte seines Bereichs zu bringen, wodurch einige Gelenke falsche Homing-Offsets erhielten.
Den Follower-Arm mit dem Leader-Arm per Teleoperation steuern
Die Teleoperation verbindet die beiden Arme: Der Follower-Arm ahmt den Leader-Arm nach. Fehlt eine Kalibrierung, startet der Befehl zuerst das Kalibrierverfahren. Beginnen Sie mit kleinen, langsamen Bewegungen, halten Sie Abstand zu den Gelenken des Follower-Arms und lassen Sie das Netzteil in Reichweite.
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_armFügen Sie als Nächstes Kameras hinzu. Listen Sie sie mit dem Kamera-Finder auf, der die Kennung jeder Kamera ausgibt und von jeder ein Testbild in outputs/captured_images speichert; öffnen Sie die Bilder, um zu sehen, welcher Index welche Kamera ist. Die Indizes können sich nach einem Neustart oder beim erneuten Anschließen einer Kamera ändern.
lerobot-find-cameras opencvSteuern Sie erneut per Teleoperation, diesmal mit angeschlossenen Kameras und einer Live-Ansicht in Rerun. Die Kameranamen, die Sie hier wählen, etwa top und wrist, werden später zu den Schlüsseln des Datensatzes. Verwenden Sie deshalb ab jetzt dieselben Namen und Einstellungen.
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=trueKameras so platzieren, dass die Policy lernen kann
Eine Policy sieht nur die Kamerabilder und die Gelenkpositionen, daher zählt ein guter Kameraaufbau mehr als eine hohe Auflösung. 640×480 bei 30 fps genügt für die meisten Aufgaben und hält Aufnahme und Training schnell.
Seitlich wischen, um die ganze Abbildung zu sehen.
- Leuchten Sie die Szene gleichmäßig mit diffusem Licht aus. Vermeiden Sie direktes Sonnenlicht, starke Reflexionen und wandernde Schatten: Unterschiedliche Beleuchtung bei Aufnahme und Ausführung kann dazu führen, dass eine Policy versagt.
- Befestigen Sie die Kameras starr und bewegen Sie sie zwischen Aufnahme und Ausführung nie. Die erste Policy eines Nachbauers aus der Community pickte nur auf den Tisch, und eine von mehreren Ursachen war, dass sich die Kameras zwischen Aufnahme und Test leicht verschoben hatten.
- Wählen Sie den Bildausschnitt passend zur Aufgabe: Das Objekt, der Greifer und das Ziel sollten in mindestens einer Kamera sichtbar sein. Ein guter Test ist, ob Sie die Aufgabe selbst allein anhand der Kamerabilder erledigen könnten. Derselbe Nachbauer demonstrierte, während er nur auf den Kamerastream schaute; wenn Sie das versuchen, lassen Sie das Netzteil in Reichweite.
- Derselbe Nachbauer ersetzte eine Seitenkamera, deren Blick auf die Greiferspitzen beim Greifen schlecht war, durch eine Überkopfkamera neben der Frontkamera, was die Verdeckung verringerte; eine Handgelenkkamera erscheint in diesem Beitrag nur als nächster Schritt. Wenn Sie über den Tag verteilt aufnehmen, fixieren Sie Belichtung und Weißabgleich in den eigenen Einstellungen Ihrer Webcam; auch die RealSense-Kamerakonfiguration von LeRobot akzeptiert
exposure,gainundwhite_balance. - Bei zwei baugleichen Webcams unter Ubuntu können die USB-Adressen vertauscht werden, und eine Aufnahme kann mit einem Kamerafehler abbrechen. Derselbe Nachbauer behob das mit udev-Regeln, die jede Kamera anhand ihres physischen USB-Ports identifizieren; lassen Sie daher jede Kamera im selben Port, andernfalls starten Sie nach jedem Neustart den Kamera-Finder erneut.
Einen Datensatz aufnehmen
Datensätze verwenden das LeRobotDataset-Format und werden auf den Hugging Face Hub hochgeladen. Legen Sie ein kostenloses Konto an, erstellen Sie in Ihren Hugging Face-Einstellungen ein Token mit Schreibzugriff, melden Sie sich dann an und speichern Sie Ihren Benutzernamen in einer Variablen. Setzen Sie zuerst HUGGINGFACE_TOKEN auf Ihr Token oder führen Sie hf auth login einzeln aus und fügen Sie das Token auf Nachfrage ein.
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USERNehmen Sie zuerst fünf Episoden auf, um den Aufbau zu testen. Verwenden Sie dieselbe Roboter-ID, dieselben Ports und dieselben Kameraeinstellungen wie bei der Teleoperation und beschreiben Sie die Aufgabe in einfachen Worten.
lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.streaming_encoding=trueLeRobot hängt Datum und Uhrzeit an den Datensatznamen an, sodass ${HF_USER}/record-test als ${HF_USER}/record-test_YYYYMMDD_HHMMSS gespeichert wird. Verwenden Sie diesen vollständigen Namen in späteren Befehlen; Sie finden ihn mit ls ~/.cache/huggingface/lerobot/${HF_USER}, oder Sie fügen --dataset.no_stamp=true hinzu, um den übergebenen Namen beizubehalten. Der Datensatz wird in ~/.cache/huggingface/lerobot abgelegt und am Ende der Aufnahme auf den Hub hochgeladen. Ein Datensatz, der von einem persönlichen Konto hochgeladen wird, kann öffentlich sein; prüfen Sie daher seine Sichtbarkeit auf dem Hub und fügen Sie --dataset.private=true hinzu, wenn er privat sein soll; mit --dataset.push_to_hub=False bleibt er lokal. Um eine unterbrochene Sitzung fortzusetzen, führen Sie den Befehl erneut aus, mit --resume=true, dem vollständigen --dataset.repo_id samt Zeitstempel, --dataset.root auf den lokalen Ordner des Datensatzes gesetzt und --dataset.num_episodes auf die Zahl der zusätzlichen Episoden, nicht auf die Gesamtzahl.
Episodendauer und Rücksetzzeit betragen standardmäßig 60 Sekunden (--dataset.episode_time_s und --dataset.reset_time_s), und die Standardanzahl der Episoden ist 50. Während der Aufnahme steuert die Tastatur den Ablauf, wie die folgende Tabelle zeigt.
Wählen Sie für einen ersten brauchbaren Datensatz eine einfache Aufgabe, etwa einen Gegenstand aus mehreren Positionen zu greifen und in einen Behälter zu legen. Nehmen Sie mindestens 50 Episoden auf, etwa 10 pro Position, halten Sie Kameras und Greifweise konsistent und bringen Sie Abwechslung nur langsam hinein. Nehmen Sie fehlgeschlagene Episoden neu auf. Fünfzig Episoden an festen Positionen sind ein Anfang; rechnen Sie mit einer Policy, die vor allem in der Nähe der aufgenommenen Positionen funktioniert. LeRobot gibt nach jeder behaltenen Episode eine Zeile zur Aufnahmefrequenz aus und am Ende der Aufnahme eine Zusammenfassung. Liegt die Rate deutlich unter dem Ziel von 30 Hz, gibt der Datensatz trotzdem 30 Hz an, sodass die Bewegung schneller wirkt, als sie war. Finden Sie heraus, was die Schleife bremst (im Beispiel der Dokumentation waren es die Kameraabfragen), und nehmen Sie die betroffenen Episoden neu auf, statt mit ihnen zu trainieren.
Prüfen Sie die Daten vor dem Training. Öffnen Sie den Datensatz im Datensatz-Visualizer von LeRobot auf Hugging Face und geben Sie eine Episode auf dem Roboter erneut wieder, um zu testen, dass sich die Bewegung wiederholen lässt. Die Wiedergabe bewegt den Arm ohne Ihr Zutun: Räumen Sie den Arbeitsbereich frei, starten Sie den Arm in der Nähe der ersten Stellung der Episode und lassen Sie das Netzteil in Reichweite.
lerobot-replay \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--dataset.episode=0Seitlich scrollen, um alle Spalten zu vergleichen.
| Taste | Aktion |
|---|---|
| Pfeil nach rechts oder n | Die Episode oder die Rücksetzphase vorzeitig beenden und weitergehen |
| Pfeil nach links oder r | Die aktuelle Episode verwerfen und neu aufnehmen |
| Esc oder q | Die Sitzung beenden: Die laufende Episode wird gespeichert, dann werden die Videos kodiert und der Datensatz hochgeladen (um diese Episode zu verwerfen, zuerst Pfeil nach links oder r drücken) |
Eine ACT-Policy trainieren
ACT (Action Chunking Transformer) ist die Policy aus dem LeRobot-Tutorial: Sie passt sich an die im Datensatz gespeicherten Motoren und Kameras an. Der Hardwareleitfaden beziffert die leichten Policies (ACT, VQ-BeT, TD-MPC) bei Batchgröße 8 auf etwa 2 bis 6 GB GPU-Speicher, als Richtwert. Trainieren Sie auf einer NVIDIA-GPU (cuda); auf Apple Silicon ändern Sie den Befehl auf --policy.device=mps, was macOS 15 oder neuer erfordert (unter macOS 14 weicht LeRobot auf die CPU aus, die sich für das Training nicht eignet).
Starten Sie das Training mit dem vollständigen Datensatznamen.
lerobot-train \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--trackio.enable=true \
--policy.repo_id=${HF_USER}/my_policy \
--steps=20000Ohne --steps läuft das Training über 100.000 Schritte, meist mehr, als ein kleiner Datensatz braucht: Imitationslernen konvergiert typischerweise innerhalb von 5 bis 10 Durchläufen über die Daten. Ein Datensatz mit 50 Episoden von je 30 Sekunden bei 30 fps enthält etwa 45.000 Bilder, bei Batchgröße 8 sind das etwa 5.600 Schritte pro Durchlauf; 5 bis 10 Durchläufe entsprechen also grob 28.000 bis 56.000 Schritten. Der obige Befehl verwendet --steps=20000, etwa dreieinhalb Durchläufe, als kurzen ersten Lauf; erhöhen Sie den Wert, wenn die Policy untertrainiert ist, und setzen Sie bei einer deutlich niedrigeren Schrittzahl auch --policy.scheduler_decay_steps nahe an --steps. Der Hardwareleitfaden schätzt für fünf Durchläufe von ACT bei Batchgröße 8 grob 30 bis 60 Minuten auf einer RTX 3090 oder 4090 und 1 bis 2 Stunden auf einer L4 oder A10G sowie 6 bis 14 Stunden bei Batchgröße 4 auf einem M1, M2 oder M3 Max; er bezeichnet diese Werte als Richtwerte und sagt, dass reale Läufe um etwa 50 % abweichen können.
Ohne geeignete GPU trainieren Sie in Google Colab mit dem ACT-Notebook, oder Sie führen hf auth login aus und hängen an denselben Befehl einen Hugging Face Jobs-Flavor wie --job.target=a10g-small an. Da dieser Befehl Trackio aktiviert, braucht ein Job außerdem --trackio.space_id=<user>/<space> (fügen Sie --trackio.private=true hinzu, damit der Space privat bleibt), oder Sie entfernen --trackio.enable=true. Jobs werden sekundengenau abgerechnet und sind auf 48 Stunden begrenzt, sofern Sie nicht --job.timeout setzen, laden einen nur lokal vorhandenen Datensatz für Sie in ein privates Repository hoch und laden am Ende das trainierte Modell hoch; hf jobs hardware listet die Flavors auf.
Checkpoints werden in outputs/train/act_so101_test/checkpoints abgelegt. Setzen Sie einen unterbrochenen Lauf vom letzten Checkpoint aus fort. Da der Trainingsbefehl --policy.repo_id=${HF_USER}/my_policy setzt, wird das fertige Modell am Ende in dieses Repository hochgeladen (--policy.push_to_hub=false schaltet das aus, --policy.private=true macht es privat); wenn Sie einen Checkpoint selbst hochladen, verwenden Sie denselben Repository-Namen, damit --policy.path=${HF_USER}/my_policy ihn findet.
lerobot-train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true
hf upload ${HF_USER}/my_policy \
outputs/train/act_so101_test/checkpoints/last/pretrained_modelDas Trainingsskript von LeRobot bewertet keine Policies auf echten Robotern. Halten Sie deshalb einige Episoden vom Training zurück, dazu Startpositionen, die Sie nicht aufgenommen haben, und testen Sie die Policy damit. Ein Nachbauer aus der Community trainierte mit 50 Episoden (je 10 in fünf Bereichen von Startpositionen) und erreichte 60 % Erfolg bei neuen Episoden aus diesen Bereichen, aber nur 10 % bei Episoden aus einem Bereich, der aus dem Training ausgelassen worden war. Nach der Erhöhung auf 25 Episoden pro Bereich kam derselbe Nachbauer auf 90 % und 75 %. Das sind kleine Stichproben, bewertet mit den eigenen Skripten des Nachbauers.
Die Policy auf dem Follower-Arm ausführen
Setzen Sie eine trainierte Policy mit lerobot-rollout ein. Verwenden Sie dieselbe Roboter-ID, dieselben Kameranamen, Kameraeinstellungen und denselben Aufgabentext wie bei der Aufnahme und starten Sie den Port-Finder erneut, falls Sie seitdem neu gestartet oder etwas neu angeschlossen haben. --duration wird in Sekunden angegeben; ohne diese Option läuft die Policy, bis Sie sie stoppen.
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/my_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--task="Grab the black cube" \
--duration=60Die Strategie legt fest, was während des Laufs geschieht, wie die folgende Tabelle zeigt. Eine Strategie, die einen Datensatz aufnimmt, braucht einen Repository-Namen, der nach Ihrem Benutzernamen mit rollout_ beginnt, zum Beispiel --dataset.repo_id=${HF_USER}/rollout_so101_test; ein Zeitstempel wird angehängt. Aufnehmende Strategien wie sentry verwenden --dataset.single_task statt --task; die Optionen jeder Strategie finden Sie in der LeRobot-Dokumentation.
Bei LeRobot v0.5.x und früher gibt es kein lerobot-rollout; verwenden Sie lerobot-record, wie in der Dokumentation zu v0.5.1 beschrieben. Die Trainingsoptionen in dieser Anleitung gelten für die aktuelle Version.
Führen Sie die Policy beim ersten Mal mit kurzer Dauer (zum Beispiel 15 Sekunden), freiem Arbeitsbereich und einem Plan aus, wie Sie den Arm anhalten; wenn Sie den Strom trennen, verlieren die Motoren ihr Haltemoment, sodass ein Arm, der auf nichts aufliegt, herunterfallen kann. Wenn der Arm auf den Tisch pickt oder über das Ziel hinausschießt, prüfen Sie den Aufbau, bevor Sie dem Modell die Schuld geben: dieselbe Kalibrier-ID, Kameras an derselben Stelle mit denselben Namen und derselben Auflösung, dieselbe Beleuchtung und Objekte in Positionen, die der Datensatz abdeckt.
Seitlich scrollen, um alle Spalten zu vergleichen.
| Strategie | Was sie tut |
|---|---|
| base | Läuft autonom ohne Aufnahme, für schnelle Tests |
| sentry | Nimmt fortlaufend auf und lädt automatisch hoch |
| highlight | Hält einen Ringpuffer vor und speichert ihn, wenn Sie eine Taste drücken |
| dagger | Datenerfassung mit Mensch in der Schleife (Human-in-the-Loop) |
| episodic | Nimmt Episode für Episode auf, mit Rücksetzphasen dazwischen |
Den Aufbau mit LeKiwi erweitern
LeKiwi ist eine dreirädrige mobile Basis, die einen SO-101 Follower-Arm trägt. Ein Raspberry Pi oder ein anderer 5-V-Computer mit genügend USB-Anschlüssen für die Kameras und die Motorsteuerplatine (die LeKiwi-Seite nennt zwei oder mehr) steuert den Roboter, und Sie fahren ihn von einem Laptop aus mit einem Leader-Arm und der Tastatur. In der kabelgebundenen Version läuft alles auf dem Laptop, und die Schritte für den Pi können übersprungen werden. Stückliste, Druckdateien und Montageanleitung der Basis stammen aus dem LeKiwi-Projekt, das auf der Hugging Face-Seite zu LeKiwi verlinkt ist.
Seitlich wischen, um die ganze Abbildung zu sehen.
Das Fahren der Basis per Tastatur braucht ein globales Tastatur-Backend. Es funktioniert daher unter X11, auf einem Windows-Desktop oder unter macOS, wenn Ihrem Terminal die Eingabeüberwachung (Input Monitoring) erlaubt wurde, nicht aber unter Wayland oder auf Rechnern ohne Bildschirm (headless).
- Bauen Sie mit den obigen Abschnitten zwei SO-101-Arme: einen für die Montage auf der Basis und einen als Leader-Arm. Montieren Sie dann die Basis.
- Installieren Sie Raspberry Pi OS, aktivieren Sie SSH und prüfen Sie, ob Sie sich mit
ssh <user>@<pi-ip>anmelden können. Installieren Sie LeRobot auf dem Pi und auf Ihrem Laptop wie im Abschnitt zur Installation und fügen Sie dann das LeKiwi-Extra hinzu, das den Servotreiber und ZeroMQ mitbringt.LeKiwi-Extra installieren pip install 'lerobot[lekiwi]' - Richten Sie alle Motoren mit einem Befehl ein. Er vergibt den Armmotoren die IDs 6 bis 1 und den Rädern 9, 8 und 7; die Rad-IDs müssen zu den Einbaupositionen passen, die in der LeKiwi-Dokumentation gezeigt werden. LeKiwi verwendet eine einzige Steuerplatine.
Motor-IDs von LeKiwi setzen lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - Kalibrieren Sie den Follower-Arm auf dem Pi und den Leader-Arm auf dem Laptop. Die LeKiwi-Seite zeigt für den Leader-Arm
--teleop.type=so100_leader; prüfen Sie, welche Leader-Klasseexamples/lekiwi/teleoperate.pyerzeugt, und kalibrieren Sie mit demselben Typ und derselben--teleop.id. Die Radmotoren brauchen keine Kalibrierung.LeKiwi-Arm kalibrieren lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - Aktivieren Sie auf dem Pi die LeRobot-Umgebung und starten Sie den Host. Er stoppt nach 30 Sekunden, sofern Sie
--host.connection_time_snicht erhöhen (zum Beispiel auf 600); das brauchen Sie für längere Sitzungen wie die Aufnahme.LeKiwi-Host auf dem Pi starten python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - Bearbeiten Sie auf dem Laptop
examples/lekiwi/teleoperate.pyim Quellcode-Repository von LeRobot: Setzen Sieremote_ipauf die Adresse des Pi sowieportund die ID des Leader-Arms auf Ihre eigenen Werte und führen Sie das Skript dann aus. Setzen Sie inrecord.pyzusätzlichHF_REPO_IDundTASK_DESCRIPTION; inreplay.pysetzen Sieremote_ip,port, die Datensatz-ID und den Episodenindex. Um eine trainierte Policy auszuführen, verwendet die LeKiwi-Seiteexamples/lekiwi/evaluate.py(setzen Sieremote_ip,portund das Modell); der Befehllerobot-rolloutim vorigen Abschnitt ist für einen eigenständigen SO-101 geschrieben. Die Geschwindigkeit hat drei Modi, die Sie mit R und F wechseln: schnell 0,3 m/s und 90°/s, mittel 0,2 m/s und 60°/s, langsam 0,1 m/s und 30°/s.
Seitlich scrollen, um alle Spalten zu vergleichen.
| Taste | Aktion |
|---|---|
| W | Vorwärts fahren |
| A | Nach links fahren |
| S | Rückwärts fahren |
| D | Nach rechts fahren |
| Z | Nach links drehen |
| X | Nach rechts drehen |
| R | Geschwindigkeit erhöhen |
| F | Geschwindigkeit verringern |
Checkliste zur Fehlersuche
Viele Probleme haben ihre Ursache bei Strom, Kabeln, Ports oder einem Aufbau, der sich zwischen Aufnahme und Ausführung geändert hat. Arbeiten Sie diese Tabelle durch, bevor Sie Code ändern.
Bei Fragen zu LeRobot selbst verlinkt die Hugging Face-Dokumentation die Discord-Community. Bei Teilen aus unserem Shop nutzen Sie die WhatsApp-Schaltfläche oder das Support-Formular.
Seitlich scrollen, um alle Spalten zu vergleichen.
| Symptom | Was zu prüfen ist |
|---|---|
| Ein serieller Port wird nicht gefunden oder der Zugriff wird verweigert | Starten Sie den Port-Finder erneut, mit eingeschalteter Platine und eingestecktem USB-Kabel. Erlauben Sie unter Linux den Zugriff mit sudo chmod 666 auf den Port. Ports können sich nach einem Neustart oder erneuten Anschließen ändern; führen Sie daher den Port-Finder erneut aus. |
| Das ID-Skript findet den Motor nicht | Prüfen Sie Netzteil, USB-Kabel und 3-Pin-Kabel. Es darf nur der Motor angeschlossen sein, dessen ID gesetzt wird. Bei einer Waveshare-Platine müssen beide Jumper auf Kanal B (USB) stehen. |
| Wiederverwendete Servos werden nicht gefunden oder reagieren nicht | Ihre IDs und Baudrate passen wahrscheinlich nicht zum neuen Roboter, wie die SO-101-Anleitung anmerkt. Führen Sie die Motoreinrichtung erneut aus, einen Servo nach dem anderen. |
| Die Kalibrierung schlägt fehl, oder der Arm bewegt sich nach dem Kalibrieren falsch | Kalibrieren Sie erneut: Bringen Sie zuerst jedes Gelenk in die Mitte seines Bereichs und drücken Sie Enter, bewegen Sie dann jedes Gelenk durch seinen gesamten Bereich. Ein Nachbauer aus der Community, der nicht jedes Gelenk zentriert hatte, endete mit falschen Homing-Offsets. Verwenden Sie danach dieselbe Roboter-ID. |
| Eine Kamera verliert die Verbindung oder ihr Index ändert sich | Starten Sie den Kamera-Finder nach jedem Neustart oder erneuten Anschließen neu. Zwei baugleiche Webcams können unter Linux ihre USB-Adressen vertauschen; ein Nachbauer aus der Community behob das mit udev-Regeln, die sich am physischen USB-Port orientieren. |
| Die Aufnahmetasten reagieren nicht | Starten Sie den Befehl aus einem interaktiven Terminal und lassen Sie es im Fokus; die Buchstabentasten n, r und q funktionieren ebenso wie die Pfeiltasten und Esc. Nur das Fahren eines Roboters per Tastatur, wie bei LeKiwi, braucht X11, einen Windows-Desktop oder die macOS-Berechtigung. |
| Das Training findet den Datensatz nicht | Verwenden Sie den vollständigen Datensatznamen samt Datums- und Uhrzeit-Suffix. |
| Die erreichte Aufnahmefrequenz liegt weit unter 30 Hz | Lesen Sie die Zeilen zur Aufnahmefrequenz, die die Aufnahme ausgibt. Wenn das Auslesen der Kameras dominiert, verringern Sie die Auflösung oder verwenden Sie weniger Kameras und nehmen Sie dann erneut auf: Eine Policy erwartet zur Laufzeit denselben Kameraaufbau, und Episoden, die deutlich unter 30 Hz aufgenommen wurden, werden gespeichert, als wären sie mit 30 Hz gelaufen. |
| Die Policy pickt auf den Tisch oder schießt über das Ziel hinaus | Vergleichen Sie Kalibrier-ID, Kamerapositionen, -namen und Beleuchtung mit der Aufnahmesitzung und prüfen Sie, ob Objekte dort starten, wo der Datensatz Beispiele hat. |
| LeKiwi verbindet sich nicht, oder der Host stoppt nach 30 Sekunden | Ermitteln Sie die Adresse des Pi mit hostname -I, senden Sie vom Laptop aus einen Ping dorthin und testen Sie ssh <user>@<pi-ip>; aktivieren Sie SSH bei Bedarf in sudo raspi-config. Der Host stoppt nach 30 Sekunden, sofern Sie nicht --host.connection_time_s setzen. |