Graba tu primer conjunto de datos LeRobot con un SO-100

Un SO-100 seguidor, un brazo líder del mismo diseño y dos cámaras USB pueden ajustar una política en una tarde. El mismo banco puede producir fácilmente sesenta episodios que se ven saludables en un explorador de archivos y desperdiciar una ejecución de GPU de seis horas. La diferencia rara vez es el modelo; es lo que sucedió entre los servos y el archivo parquet.

Aquí está la ruta manual, luego la más corta. Cada comando es de lerobot 0.6.1, lanzado el 3 de agosto de 2026 y actual en PyPI. Se movió a puntos de entrada de consola, por lo que los tutoriales que ejecutan python lerobot/scripts/control_robot.py describen un archivo que ya no existe.

Lo que captura una sesión de grabación

Un conjunto de datos LeRobot no es una carpeta de videos, sino una tabla indexada por tiempo con video adjunto: cada ciclo de control escribe una fila que contiene la acción comandada, el estado alcanzado por el seguidor, un fotograma por cámara, una marca de tiempo e índices. La política solo ve esas columnas. El esquema de lerobot/svla_so100_pickplace, leído de su meta/info.json.

Las articulaciones son main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll y main_gripper: los seis grados de libertad. Acción y estado comparten una forma porque teleoperación líder-seguidor registra un objetivo y la posición alcanzada un paso después. Esa brecha es información: dónde el brazo luchó contra la gravedad o un objeto atascado. Esas cadenas son las de ese conjunto de datos. Una sesión grabada con 0.6.1 hoy escribe shoulder_pan.pos hasta gripper.pos, IDs 1 a 6 en el bus: las mismas seis articulaciones, diferentes claves, lo cual importa en el momento en que una configuración se refiere a una característica por su nombre.

Lo que necesitas en el banco de trabajo

Si el brazo aún no está construido, eso es una tarea para otra noche: empieza en Introducción al SO-100 y la guía completa de configuración del SO-100. Si aún no has comprado nada, lee primero la comparación SO-100 vs SO-101 primero: el SO-101 es la revisión más reciente con cableado mejorado y sin el paso de extracción de engranajes, y el flujo de trabajo de grabación es idéntico.

Instalar lerobot 0.6.1

conda create -y -n lerobot python=3.12
conda activate lerobot

# TorchCodec is the default video decoder and needs ffmpeg
conda install ffmpeg -c conda-forge

# core_scripts = dataset + hardware + viz extras (record, replay, calibrate)
# feetech     = SDK for the STS3215 bus servos in the SO-100
pip install 'lerobot[core_scripts,feetech]'

lerobot-info

Los extras son lo que más confunde a la gente. pip install lerobot instala solo las dependencias principales de ML, nada que se comunique con un robot. Los brazos Koch necesitan dynamixel en lugar de feetech. Si tu shell nunca ha oído hablar de lerobot-record, esta es la razón.

Puertos, IDs de motor y calibración

Tres pasos únicos se interponen entre las piezas y un bucle de teleoperación funcional. permite que una política entrenada en su brazo funcione en el de otra persona, mapeando los conteos brutos del codificador a una convención de articulación compartida.

1. 1
   Encontrar el puerto USB de cada brazo

   Ejecútelo con ambos brazos conectados, desconecte el que está identificando cuando se le solicite y anote qué puerto desaparece. En Linux, es posible que necesite sudo chmod 666 /dev/ttyACM0.

   bash

   lerobot-find-port
   # Finding all available ports for the MotorsBus.
   # Ports before disconnecting: ['/dev/ttyACM0', '/dev/ttyACM1']
   # Remove the USB cable from your MotorsBus and press Enter when done.
   # The port of this MotorsBus is '/dev/ttyACM1'
   # Reconnect the USB cable.

2. 2
   Escribir IDs de motor y velocidades de transmisión

   Los IDs se escriben un motor a la vez, y la documentación es estricta sobre cómo: conecte exactamente un motor a la placa controladora, aún no encadenado a ningún otro. El script recorre la cadena hacia atrás, solicitando primero la pinza y asignándole el ID 6, luego el giro de muñeca (wrist_roll) como 5, hasta el giro de hombro (shoulder_pan) como 1. Hágalo antes del ensamblaje.

   bash

   lerobot-setup-motors \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0
   
   lerobot-setup-motors \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1

3. 3
   Calibrar ambos brazos

   Mueva cada articulación al centro de su rango, presione Enter y luego recorra cada una a través de su rango completo. El id se convierte en el nombre de archivo del perfil.

   bash

   lerobot-calibrate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower
   
   lerobot-calibrate \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader

4. 4
   Teleoperar antes de grabar cualquier cosa

   La prueba de aceptación para todo lo anterior. Si la teleoperación es irregular, está espejada o una articulación no sigue, la grabación lo conserva en 50 episodios.

   bash

   lerobot-teleoperate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader \
       --display_data=true

Las cámaras deciden lo que ve la política

lerobot-find-cameras opencv   # or: lerobot-find-cameras realsense

# --- Detected Cameras ---
# Camera #0:
#   Name: OpenCV Camera @ 0
#   Type: OpenCV
#   Id: 0
#   Backend api: AVFOUNDATION
#   Default stream profile:
#     Format: 16.0
#     Width: 1920
#     Height: 1080
#     Fps: 15.0

Dos vistas, y su ubicación importa: una cámara de escena fija que cubre el espacio de trabajo y una cámara de muñeca cerca del efector final mostrando lo que el efector final está a punto de tocar. La lista de verificación de conjuntos de datos de la comunidad LeRobot solicita preferiblemente dos vistas a 480x640 / 720p o mejor, un fondo estático, iluminación neutra y estable, y que el brazo líder y las extremidades humanas estén fuera del encuadre. La guía de grabación añade la regla general: deberías poder realizar la tarea tú mismo/a con solo mirar las imágenes de la cámara.

El comando record y cada flag

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_so100_follower \
    --robot.cameras="{ top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so100_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_so100_leader \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/so100_pick_cube \
    --dataset.single_task="Pick the red cube and drop it in the box" \
    --dataset.num_episodes=50 \
    --dataset.fps=30 \
    --dataset.episode_time_s=25 \
    --dataset.reset_time_s=10 \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2

Los valores predeterminados a continuación provienen de src/lerobot/configs/dataset.py en la rama principal, no de un tutorial. Varios no son lo que la gente asume.

Control por teclado durante una sesión

• Flecha derecha o n: finaliza el episodio o reinicia la fase antes de tiempo. Es la tecla que más usará, porque un agarre limpio rara vez necesita 25 segundos.
• Flecha izquierda o r: descarta el episodio y lo rehace. Una mala toma no cuesta nada ahora y mucho después.
• Escape o q: detiene la sesión, finaliza la codificación, sube.
• Estos funcionan en X11, Wayland y SSH sin interfaz gráfica: sin un backend de teclado global, lerobot-record lee las mismas teclas desde la terminal de control. Las letras sobreviven a los enlaces SSH lentos, donde las secuencias de flechas se dividen.
• La teleoperación por teclado es diferente y sí necesita un backend global: X11, Windows o macOS con Accesibilidad.

¿Cuántos episodios, y cómo es uno bueno?

La guía de grabación sugiere al menos 50 episodios para una primera tarea, aproximadamente 10 por ubicación de objeto. Las páginas de políticas enumeran un mínimo por modelo, por debajo del cual una ejecución no vale el tiempo de GPU.

La mejor pregunta es cuántos de qué. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) recopilaron más de 40.000 demostraciones y realizaron más de 15.000 ejecuciones en el mundo real. La generalización siguió una relación aproximadamente de ley de potencia con el número de entornos y objetos, y superado un umbral por entorno u objeto, las demostraciones adicionales tuvieron un efecto mínimo. En un banco: mover el objeto, cambiar la iluminación, intercambiar el cubo, en lugar de repetir una toma.

Un buen episodio es aburrido: pose inicial repetible, una cosa hecha, terminado una vez que el objeto está en el contenedor, cadena de tarea de 25 a 50 caracteres como recomienda la lista de verificación. Recoge el cubo rojo y déjalo en la caja es una cadena de tarea; task1 es el antipatrón que la lista de verificación nombra explícitamente. Las anotaciones vagas encabezan su lista de problemas, y son las más importantes para , donde la cadena es una entrada del modelo, no un nombre de archivo.

Defectos que arruinan silenciosamente un conjunto de datos

Ninguno lanza una excepción. Todos sobreviven al entrenamiento, apareciendo como una curva de pérdida que parece correcta y un robot que no hace nada. Verifique mientras la escena está configurada.

Una advertencia: la tabla de la guía de codificación de streaming lista el valor predeterminado como True, mientras que la dataclass en main lee streaming_encoding: bool = False. La documentación y el código no concuerdan, así que configúrelo explícitamente; lerobot registra una sugerencia recomendándolo cada vez que se inicia con la bandera desactivada.

Verifique el conjunto de datos antes de alquilar una GPU

La prueba de aceptación de la documentación: compare la duración del video con la duración del episodio reportada por la CLI, y confirme que el número de filas es igual a los fps por la duración. Por episodio, no en el total.

from lerobot.datasets import LeRobotDataset

ds = LeRobotDataset("your-user/so100_pick_cube_20260823_141530")
print("fps:", ds.fps, "frames:", ds.num_frames)

# In v3.0 the per-episode records live in meta/episodes/ as chunked parquet:
# lengths, tasks and offsets into the shared parquet and mp4 shards.
# They load through the datasets stack, so this is a datasets.Dataset --
# use .column_names and integer indexing, not pandas .columns / .head().
eps = ds.meta.episodes
print(eps.column_names)
print(eps[0])

# Global feature statistics, including per-joint min and max.
# A joint whose min equals its max never moved. A joint sitting at a
# hard limit for most of the run is the one that will stall the policy.
print(ds.meta.stats["observation.state"])

Luego, obsérvalo. lerobot-dataset-viz reproduce un episodio fotograma a fotograma con trazas de articulaciones junto a las vistas de la cámara, en Rerun o Foxglove. Cámaras intercambiadas y fotogramas congelados aparecen en diez segundos. La gente se salta este paso.

# Replay one episode with camera views and joint traces
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0

# Foxglove instead, for a seekable, scrubbable timeline
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0 \
    --display-mode foxglove

# Drop the episodes that did not survive review
lerobot-edit-dataset \
    --repo_id your-user/so100_pick_cube_20260823_141530 \
    --new_repo_id your-user/so100_pick_cube_clean \
    --operation.type delete_episodes \
    --operation.episode_indices "[3, 17, 41]"

v2.1 o v3.0: decide antes de grabar

v2.1 escribía un parquet y un MP4 por episodio. v3.0 concatena muchos episodios en fragmentos compartidos y reconstruye los límites a partir de los metadatos, por lo que info.json contiene plantillas de ruta como data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet en lugar de un número de episodio. La justificación principal es tener menos archivos y más grandes: inicialización más rápida y menos presión sobre el sistema de archivos a escala.

# Upgrade an older v2.1 dataset to v3.0
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube

# By default it pushes the converted dataset back to the hub and tags it v3.0.
# To convert a local copy and keep it off the hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube \
    --root=/path/to/dataset/directory \
    --push-to-hub=false

Dos rutas al mismo conjunto de datos

Del conjunto de datos a la política

Cincuenta episodios limpios alimentan cada ejecutado aquí. se entrena desde cero solo en su tarea, con aproximadamente 80 millones de parámetros a unos 20 ms por paso de acción, siendo el único de los cinco que se siente cómodo con movimientos rápidos. tiene aproximadamente 450 millones de parámetros en una tarjeta de 24 GB. es un modelo fundacional de aproximadamente 3 mil millones de parámetros donde el toca unos 40 millones de parámetros, necesita una A100 o H100, y requiere ese conjunto de datos v2.1.

A continuación, la guía para su combinación: , o ; para una primera ejecución, es más corta. Cuando la política funciona en el banco de pruebas pero colapsa en el momento en que mueve la mesa, eso es un problema de datos: y profundizan en la diversidad.