Introducción a reBot Arm B601-DM basado en LeRobot y reBot 102 Leader

Brazo robótico de 6 GDL · Soporte multi-motor · Solucionador de cinemática · Planificación de trayectoria · Totalmente de código abierto
reBot Arm B601-DM es un proyecto de brazo robótico de código abierto lanzado por Seeed, dedicado a reducir el umbral para aprender inteligencia encarnada. Abrimos por completo todos los diseños estructurales y el código, haciendo que la tecnología robótica sea accesible para todos.
LeRobot se compromete a proporcionar modelos, conjuntos de datos y herramientas para robótica en el mundo real en PyTorch. Su objetivo es reducir la barrera de entrada a la robótica, permitiendo que todos contribuyan y se beneficien compartiendo conjuntos de datos y modelos preentrenados. LeRobot integra metodologías de vanguardia validadas para aplicaciones en el mundo real, centrándose en el aprendizaje por imitación y el aprendizaje por refuerzo. Ha proporcionado un conjunto de modelos preentrenados, conjuntos de datos con demostraciones recopiladas por humanos y entornos de simulación, lo que permite a los usuarios comenzar sin necesidad de ensamblar robots.
Este wiki proporciona tutoriales de depuración para reBot-DevArm e implementa la recopilación de datos y el entrenamiento dentro del framework LeRobot.
Los tutoriales de Seeed Studio se actualizan estrictamente de acuerdo con la documentación oficial. Si encuentras problemas de software o de entorno que no se puedan resolver, primero consulta las FAQ al final del artículo, o contacta con atención al cliente para unirte al grupo de discusión de SeeedStudio LeRobot. También puedes hacer preguntas aquí: LeRobot GitHub o en el canal de Discord.
Entorno inicial del sistema
- Ubuntu x86
- Jetson Orin
- Ubuntu 22.04/Ubuntu 24.04
- GPU NVIDIA con CUDA 12+ (opcional, para entrenamiento e inferencia acelerados por GPU)
- Python 3.10
- Torch 2.6 (las compilaciones para CPU pueden ejecutar flujos de trabajo básicos; se requieren compilaciones con CUDA para la aceleración por GPU)
- Jetson JetPack 6.0 y 6.1, 6.2 no es compatible
- Python 3.10
- Torch 2.3+
Instalar LeRobot
LeRobot se puede instalar y ejecutar en máquinas solo con CPU para flujos de trabajo básicos. Si necesitas entrenamiento o inferencia acelerados por GPU, confirma que tu ordenador tiene una GPU NVIDIA y luego instala las versiones de PyTorch y Torchvision que coincidan con tu versión de CUDA.
1. Instalar Miniforge
cd ~
wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
~/miniforge3/bin/conda init bash
source ~/.bashrc
2. Clonar el repositorio de LeRobot
mkdir ~/rebot_lerobot
cd ~/rebot_lerobot
git clone https://github.com/Seeed-Projects/lerobot.git
3. Crear un entorno Conda e instalar LeRobot
Para las funciones detalladas de los paquetes de funciones, consulta:
El repositorio lerobot ya tiene un pyproject.toml. Crea un entorno conda e instala todas las dependencias.
cd ~/rebot_lerobot
# Create conda environment (Python 3.12)
conda create -y -n lerobot python=3.12
# Activate environment
conda activate lerobot
# Install lerobot main project (editable mode)
pip install -e ./lerobot
# Add dependency packages
pip install lerobot-teleoperator-rebot-arm-102
pip install lerobot-robot-seeed-b601
pip install motorbridge
4. Instalar dependencias de vídeo
ffmpeg es una dependencia de decodificación de vídeo, instálala mediante conda:
conda install ffmpeg -c conda-forge
Notas de versión:
-
De forma predeterminada, se instalará ffmpeg 7.X (compatible con el codificador libsvtav1)
-
Si encuentras problemas de compatibilidad de versión, puedes especificar ffmpeg 7.1.1:
conda install ffmpeg=7.1.1 -c conda-forge -
Puedes comprobar si el codificador libsvtav1 es compatible mediante
ffmpeg -encoders | grep svtav1
- Ubuntu x86
- Jetson Orin
Ubuntu x86 no requiere ninguna otra configuración de dependencias de vídeo. Continúa con el paso 5.
En un dispositivo Jetson JetPack 6.0+, asegúrate de haber instalado PyTorch y Torchvision con soporte para GPU siguiendo el paso 5 de este tutorial antes de ejecutar los siguientes comandos.
conda install -y -c conda-forge "opencv>=4.10.0.84" # Install OpenCV and other dependencies via conda, for Jetson JetPack 6.0+ only
conda remove opencv # Uninstall OpenCV
pip3 install opencv-python==4.10.0.84 # Install specific OpenCV version using pip3
conda uninstall numpy
pip3 install numpy==1.26.0 # This version must be compatible with torchvision
5. Comprobar PyTorch y Torchvision
Instalar el entorno LeRobot con pip puede reemplazar los PyTorch y Torchvision originales por compilaciones para CPU, así que comprueba el resultado en Python.
python3
import torch
print(torch.cuda.is_available())
exit()
Si la salida es False, el entorno actual está usando la versión de PyTorch para CPU. Esto es lo esperado en ordenadores sin GPU NVIDIA, y puedes continuar con flujos de trabajo básicos basados en CPU, aunque el entrenamiento será mucho más lento. Si tu ordenador tiene una GPU NVIDIA y necesitas aceleración por GPU, instala las versiones de PyTorch y Torchvision que coincidan con tu versión de CUDA desde la guía oficial de PyTorch. En ese caso, la comprobación final debería devolver True.
Si estás usando un dispositivo Jetson, instala PyTorch y Torchvision con soporte para GPU según este tutorial.
Las GPU NVIDIA RTX serie 50 requieren la versión preliminar de PyTorch con CUDA 12.8 o posterior:
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
Calibrar el brazo robótico
A continuación, debes conectar la fuente de alimentación y el cable de datos a tu robot reBot B601-DM para la calibración, a fin de garantizar que los brazos líder y seguidor tengan los mismos valores de posición cuando estén en la misma posición física. Esta calibración es esencial porque permite que una red neuronal entrenada en un robot reBot B601-DM funcione en otro. Si necesitas recalibrar el brazo robótico, elimina por completo los archivos en ~/.cache/huggingface/lerobot/calibration/robots o ~/.cache/huggingface/lerobot/calibration/teleoperators y vuelve a calibrar el brazo robótico. De lo contrario, aparecerá un mensaje de error. La información de calibración del brazo robótico se almacenará en los archivos JSON de este directorio.
Primero, debes otorgar permisos de interfaz ejecutando los siguientes comandos:
sudo chmod 666 /dev/ttyUSB* # Leader arm
sudo chmod 666 /dev/ttyACM* # Follower arm (serial bridge)
- Brazo seguidor
- Brazo líder
El B601-DM solo necesita calibrarse una vez después del montaje. Aquí está el comando de calibración. Consulta la figura para ver la posición cero (pinza completamente cerrada).
sudo chmod 666 /dev/ttyACM* # follower arm (serial bridge)
lerobot-calibrate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao

Los pasos de calibración son cruciales y afectarán directamente si el brazo robótico funciona con normalidad. Sigue el proceso estrictamente.
Notas de calibración del reBot 102 leader:
- Cuando comienza la calibración, la posición actual de cada servo en el reBot Arm 102 se restablecerá a cero
joint_ranges(límites de las articulaciones) se toman del archivo de configuraciónconfig_rebot_arm_102_leader.py, no de los datos de calibración- Si una articulación siempre parece atascada cerca de un límite, primero revisa la configuración de
joint_ranges - Las direcciones de las articulaciones se definen en el archivo de configuración. Si las direcciones no coinciden, modifica la configuración en lugar de recalibrar
- El reBot 102 leader utiliza un módulo USB-a-UART, normalmente asignado a
/dev/ttyUSB* - Usa
ls /dev/ttyUSB*para comprobar el número de puerto real
Si es la primera conexión, es posible que obtengas un error indicando que no se puede encontrar /dev/ttyACM0. Esto se debe a que brltty está ocupando el puerto serie. Ejecuta los siguientes pasos:
sudo dmesg | grep ttyUSB #Check the last line shows "disconnected"
sudo apt remove brltty #Remove brltty

Siguiendo las indicaciones, mueve el brazo líder a la posición cero mostrada arriba,
sudo chmod 666 /dev/ttyUSB0
lerobot-calibrate \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader
Mantenlo quieto y luego presiona Enter hasta que la calibración se complete.
Durante la teleoperación, si el brazo robótico maestro-esclavo sufre una desconexión de energía, mal contacto de alimentación o desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero inicial. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
Teleoperar
Durante la teleoperación, si el brazo robótico maestro-esclavo sufre una desconexión de energía, mal contacto de alimentación o desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero inicial. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
Primero otorga permisos a los puertos serie:
sudo chmod 666 /dev/ttyUSB* # Leader arm
sudo chmod 666 /dev/ttyACM* # Follower arm (serial bridge)
Ejecuta la teleoperación:
lerobot-teleoperate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader
Añadir cámaras
Durante la teleoperación, si el brazo robótico maestro-esclavo sufre una desconexión de energía, mal contacto de alimentación o desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero inicial. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
- RealSense D435i / D405
- Orbbec Gemini2
- Cámara genérica
Las cámaras de profundidad RealSense pueden proporcionar percepción RGB-D para LeRobot y son adecuadas para tareas como reconocimiento de objetos, reconstrucción de nubes de puntos y manipulación sobre mesa. Los modelos recomendados aquí son RealSense D405 y RealSense D435i.
RealSense D405

La RealSense D405 es una cámara estéreo de profundidad de corto alcance diseñada para tareas de alta precisión a corta distancia, como la manipulación robótica sobre mesa, con un rango de trabajo típico de 7 cm a 50 cm.
RealSense D435i

La RealSense D435i combina sensado de profundidad, imagen RGB y una IMU, lo que la hace adecuada para aplicaciones de rango medio a corto como reconstrucción 3D, SLAM y percepción del entorno robótico.
Cambiar a la rama de cámara
Paso 1
El soporte actual para cámaras está disponible en la rama DepthCameraSupport:
git checkout DepthCameraSupport
git pull origin DepthCameraSupport
Confirma la rama actual:
git branch --show-current
Salida esperada:
DepthCameraSupport
Instalar LeRobot en modo editable
Paso 2
Si solo utilizas RealSense:
pip install -e ".[realsense]"
Conceder permisos
Paso 3
sudo chmod a+rw /dev/bus/usb/*/*
Detectar cámaras
Paso 4
lerobot-find-cameras realsense
Este paso mostrará:
- Modelo de la cámara
- Número de serie
- Información USB
- Configuración de flujo predeterminada
Ejemplo de RealSense
Paso 5
Prueba con dos RealSense:
lerobot-teleoperate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras='{
d435i_color: {
type: realsense_d435i_color,
serial_number_or_name: "419522072950",
width: 640,
height: 480,
fps: 30,
color_mode: rgb,
color_stream_format: rgb8,
rotation: 0,
warmup_s: 1
},
d435i_depth: {
type: realsense_d435i_depth,
serial_number_or_name: "419522072950",
width: 640,
height: 480,
fps: 30,
max_depth_m: 2.0,
depth_alpha: 0.2,
rotation: 0,
warmup_s: 5
},
d405_color: {
type: realsense_d405_color,
serial_number_or_name: "409122273421",
width: 640,
height: 480,
fps: 30,
color_mode: rgb,
color_stream_format: rgb8,
rotation: 0,
warmup_s: 1
},
d405_depth: {
type: realsense_d405_depth,
serial_number_or_name: "409122273421",
width: 640,
height: 480,
fps: 30,
depth_alpha: 0.03,
rotation: 0,
warmup_s: 5
}
}' \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true
Notas sobre parámetros
Paso 6
depth_alphacontrola el factor de escala de la imagen de profundidad y se puede ajustar según el resultado de la visualización y el rango de distancia objetivo.- Si conectas tres o más cámaras de profundidad, se recomienda reducir
fpsa15para mejorar la estabilidad general. - Se recomienda mantener la resolución en
640x480para un mejor equilibrio entre estabilidad y rendimiento en tiempo real.

proporcionando flujos sincronizados de RGB y profundidad con una alineación precisa de profundidad a color. Combinado con la detección de profundidad estéreo y un IMU integrado de 6 ejes, es muy adecuado para tareas robóticas como detección de objetos, percepción 3D, mapeo y navegación. Su diseño compacto y la compatibilidad completa con el SDK de Orbbec lo hacen adecuado tanto para la investigación como para el despliegue en el mundo real.

Gemini 336 es un nuevo miembro de la serie Gemini 330. Hereda el sólido rendimiento de profundidad de Gemini 335 y mejora aún más la calidad de la imagen de profundidad en áreas interiores reflectantes, regiones oscuras en escenas de alto rango dinámico y entornos exteriores brillantes. Para aplicaciones de robótica, puede proporcionar datos de profundidad más estables y de alta calidad para tareas como percepción, localización y manipulación.
Cambiar a la rama de Camera
Paso 1
La compatibilidad actual con cámaras está disponible en la rama DepthCameraSupport:
git checkout DepthCameraSupport
git pull origin DepthCameraSupport
Confirma la rama actual:
git branch --show-current
Salida esperada:
DepthCameraSupport
Instalar LeRobot en modo editable
Paso 2
Si solo utilizas Orbbec:
pip install -e ".[orbbec]"
Conceder permisos
Paso 3
sudo chmod a+rw /dev/bus/usb/*/*
Detectar cámaras
Paso 4
lerobot-find-cameras orbbec
Este paso mostrará:
- Modelo de cámara
- Número de serie
- Información USB
- Configuración de flujo predeterminada
Ejemplo de Orbbec
Paso 5
Prueba con una sola Orbbec:
lerobot-teleoperate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras="{
orbbec_color: {
type: orbbec_color,
serial_number_or_name: "CP9JA530003A",
width: 640,
height: 480,
fps: 30,
color_mode: rgb,
rotation: 0,
warmup_s: 1
},
orbbec_depth: {
type: orbbec_depth,
serial_number_or_name: "CP9JA530003A",
width: 640,
height: 400,
fps: 30,
depth_alpha: 0.2,
rotation: 0,
warmup_s: 5
}
}" \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true
Notas sobre parámetros
Paso 6
depth_alphacontrola el factor de escala de la imagen de profundidad. Un buen punto de partida es0.2, luego puedes ajustarlo finamente según el resultado mostrado.- Si conectas tres o más cámaras de profundidad, se recomienda reducir
fpsa15para una mejor estabilidad. - Se recomienda mantener la resolución en
640x480para una visualización y transferencia de datos más estables.
Problemas comunes
Paso 7
Si ves el siguiente error:
No Orbbec camera found for 'XXXX'
normalmente significa que el número de serie en la configuración no coincide con el dispositivo conectado actualmente. Ejecuta:
lerobot-find-cameras orbbec
Luego confirma el serial real y actualiza serial_number_or_name en tu comando.
💡 Autor y contribución
- Autor: Zhang Jiaquan, Wang Wenzhao - South China Normal University
Para instanciar una cámara, necesitas un identificador de cámara. Este identificador puede cambiar si reinicias tu ordenador o vuelves a conectar tu cámara, un comportamiento que depende principalmente de tu sistema operativo.
Para encontrar los índices de las cámaras conectadas a tu sistema, ejecuta el siguiente script:
lerobot-find-cameras opencv # or realsense for Intel Realsense cameras
La terminal imprimirá información relevante de la cámara.
--- 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
--------------------
(more cameras ...)
Puedes encontrar las imágenes tomadas por cada cámara en el directorio ~/lerobot/outputs/captured_images.
Al usar cámaras Intel RealSense en macOS, podrías obtener este error: "Error finding RealSense cameras: failed to set power state". Esto se puede resolver ejecutando el mismo comando con permisos de sudo. Ten en cuenta que el uso de cámaras RealSense en macOS es inestable.
Después de eso, podrás mostrar las cámaras en tu ordenador mientras realizas la teleoperación ejecutando el siguiente código. Esto es útil para preparar tu configuración antes de grabar tu primer conjunto de datos.
Durante la teleoperación, si el brazo robótico maestro-esclavo experimenta una desconexión de energía, un mal contacto de energía o un desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero de origen. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
lerobot-teleoperate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true
Las imágenes en el formato fourcc: "MJPG" están comprimidas. Puedes probar resoluciones más altas y también puedes intentar el formato YUYV. Sin embargo, este último reducirá la resolución de la imagen y los FPS, lo que provocará retrasos en el funcionamiento del brazo robótico. Actualmente, bajo el formato MJPG, puede soportar 3 cámaras a una resolución de 1920*1080 manteniendo 30FPS. Sin embargo, sigue sin recomendarse conectar 2 cámaras a un ordenador a través del mismo HUB USB.
Si tienes más cámaras, puedes cambiar el parámetro --robot.cameras para añadirlas. Debes prestar atención al formato de index_or_path, que está determinado por el último dígito del ID de la cámara que se muestra al ejecutar python -m lerobot.find_cameras opencv.
Por ejemplo, si quieres añadir una cámara:
Durante la teleoperación, si el brazo robótico maestro-esclavo experimenta una desconexión de energía, un mal contacto de energía o un desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero de origen. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
lerobot-teleoperate \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true
Recopilación de conjuntos de datos
Durante la teleoperación, si el brazo robótico maestro-esclavo experimenta una desconexión de energía, un mal contacto de energía o un desprendimiento de la línea de señal, primero debes detener el código del programa y devolver el brazo robótico a su posición cero de origen. Solo entonces vuelve a conectar la fuente de alimentación y reinicia el programa. Esto evita que el desorden de datos provoque que el brazo robótico se descontrole y cause posibles riesgos de seguridad.
- Guardar localmente
- Upload to Hugging Face Hub
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true \
--dataset.repo_id=seeed_rebot_b601_dm/test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.push_to_hub=false \
--dataset.episode_time_s=30 \
--dataset.reset_time_s=30
Entre ellos, repo_id se puede modificar de forma personalizada, y push_to_hub=false. Finalmente, el conjunto de datos se guardará en el directorio ~/.cache/huggingface/lerobot de la carpeta de inicio, donde se creará la carpeta seeed_rebot_b601_dm/test mencionada anteriormente.
- Si quieres usar las funciones de Hugging Face Hub para subir tu conjunto de datos y no lo has hecho antes, asegúrate de haber iniciado sesión usando un token con permisos de escritura, que se puede generar desde los ajustes de Hugging Face:
huggingface-cli login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
Guarda el nombre de tu repositorio de Hugging Face en una variable para ejecutar estos comandos:
HF_USER=$(huggingface-cli whoami | head -n 1)
echo $HF_USER
Graba 5 episodios y sube tu conjunto de datos al Hub:
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=follower1 \
--robot.can_adapter=damiao \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.push_to_hub=true \
--dataset.episode_time_s=30 \
--dataset.reset_time_s=30
Verás que aparecen muchas líneas como esta:
INFO 2024-08-10 15:02:58 ol_robot.py:219 dt:33.34 (30.0hz) dtRlead: 5.06 (197.5hz) dtWfoll: 0.25 (3963.7hz) dtRfoll: 6.22 (160.7hz) dtRlaptop: 32.57 (30.7hz) dtRphone: 33.84 (29.5hz)
Función de grabación
La función record proporciona un conjunto de herramientas para capturar y gestionar datos durante el funcionamiento del robot.
1. Almacenamiento de datos
- Los datos se almacenan usando el formato
LeRobotDatasety se guardan en disco durante la grabación. - De forma predeterminada, el conjunto de datos se envía a tu página de Hugging Face después de la grabación.
- Para desactivar la subida, usa:
--dataset.push_to_hub=False.
2. Puntos de control y reanudación
- Los puntos de control se crean automáticamente durante la grabación.
- Para reanudar después de una interrupción, vuelve a ejecutar el mismo comando con:
--resume=true
⚠️ Nota importante: Al reanudar, establece --dataset.num_episodes en el número de episodios adicionales que se van a grabar (no en el número total de episodios objetivo del conjunto de datos).
- Para empezar a grabar desde cero, elimina manualmente el directorio del conjunto de datos.
3. Parámetros de grabación
Configura el flujo de grabación de datos usando argumentos de línea de comandos:
| Parámetro | Descripción | Predeterminado |
|---|---|---|
| --dataset.episode_time_s | Duración por episodio de datos (segundos) | 60 |
| --dataset.reset_time_s | Tiempo de reinicio del entorno después de cada episodio (segundos) | 60 |
| --dataset.num_episodes | Número total de episodios a grabar | 50 |
4. Controles de teclado durante la grabación
Controla el flujo de grabación de datos usando atajos de teclado:
| Tecla | Acción |
|---|---|
| → (Flecha derecha) | Detener anticipadamente el episodio actual/reiniciar; pasar al siguiente. |
| ← (Flecha izquierda) | Cancelar el episodio actual; volver a grabarlo. |
| ESC | Detener la sesión inmediatamente, codificar los vídeos y subir el conjunto de datos. |
Si las pulsaciones de tu teclado no responden, puede que necesites hacer un downgrade de tu versión de pynput, por ejemplo instalando la versión 1.6.8.
pip install pynput==1.6.8
Consejos para recopilar datos
- Sugerencia de tarea: Agarrar objetos en diferentes ubicaciones y colocarlos en un contenedor.
- Escala: Grabar ≥50 episodios (10 episodios por ubicación).
- Consistencia:
- Mantén las cámaras fijas.
- Mantén un comportamiento de agarre idéntico.
- Asegúrate de que los objetos manipulados sean visibles en las imágenes de las cámaras.
- Progresión:
- Comienza con agarres fiables antes de añadir variaciones (nuevas ubicaciones, técnicas de agarre, ajustes de cámara).
- Evita aumentar la complejidad demasiado rápido para prevenir fallos.
💡 Regla general: Deberías ser capaz de realizar la tarea tú mismo solo mirando las imágenes de la cámara en la pantalla.
Si quieres profundizar en este tema importante, puedes consultar la entrada de blog que escribimos sobre qué hace que un conjunto de datos sea bueno.
Solución de problemas
Problema específico de Linux: Si las teclas Flecha derecha/Flecha izquierda/ESC no responden durante la grabación:
- Verifica que la variable de entorno
$DISPLAYesté configurada (consulta las limitaciones de pynput).
Visualizar el conjunto de datos
echo ${HF_USER}/rebot_test
Si subiste los datos, también puedes visualizarlos localmente con el siguiente comando:
lerobot-dataset-viz \
--repo-id ${HF_USER}/rebot_test \
--episode-index 0 \
--display-compressed-images=false
Si usaste --dataset.push_to_hub=false y no subiste los datos, también puedes visualizarlos localmente con:
lerobot-dataset-viz \
--repo-id seeed_rebot_b601_dm/test \
--episode-index 0 \
--display-compressed-images=false
Aquí, seeed_rebot_b601_dm/test es el nombre personalizado de repo_id definido durante la recopilación de datos.
Reproducir un episodio
Inestable, se puede omitir o probar.
Ahora, intenta reproducir el primer conjunto de datos en tu robot:
lerobot-replay \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.id=follower1 \
--dataset.repo_id=seeed_rebot_b601_dm/test \
--dataset.episode=0
En este punto, el robot debería realizar las mismas acciones que cuando lo teleoperaste durante la grabación.
Entrenamiento y evaluación
- ACT
- SmolVLA
- Pi0
- Pi0.5
- GR00T N1.5
- PEFT (Opcional)
- Multi-GPU (Opcional)
- Async Inference (Optional)
Consulta el tutorial oficial ACT
Entrenamiento
Para entrenar una política que controle tu robot, usa el script python -m lerobot.scripts.train. Algunos parámetros son obligatorios. Aquí tienes un comando de ejemplo:
lerobot-train \
--dataset.repo_id=${HF_USER}/rebot_test \
--policy.type=act \
--output_dir=outputs/train/act_rebot_test \
--job_name=act_rebot_test \
--policy.device=cuda \
--wandb.enable=false \
--steps=300000
Si quieres entrenar en un conjunto de datos local, asegúrate de que el repo_id coincida con el nombre usado durante la recopilación de datos y añade --policy.push_to_hub=false.
lerobot-train \
--dataset.repo_id=seeed_rebot_b601_dm/test \
--policy.type=act \
--output_dir=outputs/train/act_rebot_test \
--job_name=act_rebot_test \
--policy.device=cuda \
--wandb.enable=false \
--policy.push_to_hub=false \
--steps=300000
Si estás usando una GPU RTX serie 50, necesitas añadir --dataset.video_backend=pyav para evitar APIs faltantes en la versión preliminar de torchvision. El comando de entrenamiento se convierte en:
lerobot-train \
--dataset.repo_id=seeed_rebot_b601_dm/test \
--dataset.video_backend=pyav \
--policy.type=act \
--output_dir=outputs/train/act_rebot_test \
--policy.device=cuda \
--wandb.enable=false \
--policy.push_to_hub=false \
--steps=300000
Explicación del comando
- Especificación del conjunto de datos: Proporcionamos el conjunto de datos mediante el parámetro
--dataset.repo_id=${HF_USER}/rebot_test. - Pasos de entrenamiento: Modificamos el número de pasos de entrenamiento usando
--steps=300000. El algoritmo usa por defecto 800000 pasos; ajústalo según la dificultad de tu tarea. Puedes establecerlo más alto si no estás seguro, ya que se generan puntos de control durante el entrenamiento y la evaluación puede reanudarse desde cualquier punto de control. - Tipo de política: Proporcionamos la política con
policy.type=act. Del mismo modo, puedes cambiar entre políticas como [act,diffusion,pi0,pi0fast,sac,smolvla]. Esto cargará la configuración desdeconfiguration_act.py. Es importante destacar que esta política se adaptará automáticamente a los estados de los motores de tu robot, a las acciones de los motores y al número de cámaras, ya que esta información ya está almacenada en tu conjunto de datos. - Selección de dispositivo: Proporcionamos
policy.device=cudaporque estamos entrenando en una GPU Nvidia, pero puedes usarpolicy.device=mpspara entrenar en Apple Silicon. - Herramienta de visualización: Proporcionamos
wandb.enable=truepara visualizar las gráficas de entrenamiento usando Weights and Biases. Esto es opcional, pero si lo usas, asegúrate de haber iniciado sesión ejecutandowandb login.
Evaluación
Puedes usar la función record de lerobot/record.py pero con un punto de control de la política como entrada. Por ejemplo, ejecuta este comando para grabar 10 episodios de evaluación:
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"} }' \
--robot.id=follower1 \
--display_data=false \
--dataset.repo_id=seeed/eval_test123 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=outputs/train/act_rebot_test/checkpoints/last/pretrained_model
- El parámetro
--policy.pathindica la ruta al archivo de pesos de los resultados de entrenamiento de tu política (por ejemplo,outputs/train/act_rebot_test/checkpoints/last/pretrained_model). Si subes el archivo de pesos de los resultados del entrenamiento del modelo al Hub, también puedes usar el repositorio del modelo (por ejemplo,${HF_USER}/act_rebot_test). - El nombre del conjunto de datos
dataset.repo_idcomienza coneval_. Esta operación grabará por separado vídeos y datos durante la evaluación, que se guardarán en la carpeta que comienza coneval_, comoseeed/eval_test123. - Si encuentras
File exists: 'home/xxxx/.cache/huggingface/lerobot/xxxxx/seeed/eval_xxxx'durante la fase de evaluación, elimina primero la carpeta que comienza coneval_y luego ejecuta el programa de nuevo. - Cuando te encuentres con
mean is infinity. You should either initialize with stats as an argument or use a pretrained model, ten en cuenta que palabras clave comofrontysideen el parámetro--robot.camerasdeben ser estrictamente coherentes con las utilizadas al recopilar el conjunto de datos.
Consulta el tutorial oficial SmolVLA.
SmolVLA es un modelo base de robot ligero proporcionado por Hugging Face. Está diseñado para que puedas tomar tu propio conjunto de datos LeRobot grabado y ajustarlo de forma rápida para obtener resultados en robots reales.
En pocas palabras, sus entradas/salidas son:
- Entrada: metraje de múltiples cámaras + estado actual del robot (sensores/articulaciones, etc.) + una instrucción de tarea en lenguaje natural
- Salida: un fragmento de acción continua para mover el brazo robótico y ejecutar la tarea
pip install -e ".[smolvla]"
Recopilación de conjuntos de datos (recomendado)
SmolVLA es un "modelo base". Para que funcione bien en tu mesa, con tus cámaras, pinza y objetos, normalmente necesitas ajustarlo con tus propios datos.
- Empieza con ~50 episodios (muy pocos pueden conducir a un aprendizaje/generalización deficientes).
- Si tu tarea tiene "variables" (por ejemplo, diferentes posiciones del cubo en la mesa), asegúrate de que cada variación tenga suficientes demostraciones:
- Ejemplo: 5 posiciones × 10 episodios cada una = 50 episodios
- Experiencia: grabar solo 25 episodios suele ser insuficiente. Tanto la calidad como la cantidad de datos importan.
Entrenamiento
Utiliza smolvla_base (el modelo preentrenado de 450M) como punto de partida y ajústalo con tu conjunto de datos. El ejemplo oficial entrena durante 20k pasos; en una sola A100 esto lleva unas 4 horas (solo como referencia; el tiempo real varía según el hardware).
Si no tienes una GPU disponible, considera entrenar mediante un cuaderno de Colab (consulta el tutorial oficial).
lerobot-train \
--policy.path=lerobot/smolvla_base \
--dataset.repo_id=${HF_USER}/mydataset \
--batch_size=64 \
--steps=20000 \
--output_dir=outputs/train/my_smolvla \
--job_name=my_smolvla_training \
--policy.device=cuda \
--wandb.enable=true
Consejos:
- Si te quedas sin memoria, reduce primero
--batch_size. Una vez que funcione, ve aumentándolo gradualmente. - Para ver los parámetros disponibles:
lerobot-train --help
Evaluación
La fase de evaluación carga tu modelo ajustado, permite que el robot ejecute la tarea y registra el proceso de evaluación como un nuevo conjunto de datos (para revisar vídeos y analizar resultados).
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.id=follower1 \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"} }' \
--dataset.single_task="Grasp a lego block and put it in the bin." \
--dataset.repo_id=${HF_USER}/eval_DATASET_NAME_test \
--dataset.episode_time_s=50 \
--dataset.num_episodes=10 \
--policy.path=${HF_USER}/FINETUNE_MODEL_NAME
Cómo rellenar los parámetros:
--robot.port: Cámbialo al puerto serie reconocido en tu máquina (normalmente/dev/ttyACM0o/dev/ttyUSB0).--robot.id: El ID de tu robot (debe coincidir con el que usaste durante la calibración/recopilación).--robot.cameras: Cámbialo alindex_or_pathde tu cámara real y asegúrate de que las claves de cámara (por ejemplo,front,side) coincidan exactamente con las que usaste al grabar el conjunto de datos.--dataset.single_task: Debe coincidir con la descripción de la tarea utilizada al grabar el conjunto de datos.--dataset.repo_id: El nombre del conjunto de datos de salida de evaluación; si has iniciado sesión en Hugging Face, se creará/cargará en tu cuenta.--policy.path:- Si el modelo es local: rellena la ruta de los pesos dentro del directorio de salida de entrenamiento (por ejemplo,
outputs/train/my_smolvla/checkpoints/last/pretrained_model) - Si el modelo está en Hub: rellena
${HF_USER}/FINETUNE_MODEL_NAME
- Si el modelo es local: rellena la ruta de los pesos dentro del directorio de salida de entrenamiento (por ejemplo,
Opcional: si quieres "teleoperar manualmente para ajustar" entre episodios de evaluación, puedes añadir teleop (rellena según tu dispositivo y configuración):
--teleop.type=rebot_arm_102_leader \
--teleop.port=/dev/ttyUSB0 \
--teleop.id=rebot_arm_102_leader
Consulta el tutorial oficial Pi0.
π₀ (Pi0) es un modelo de Visión-Lenguaje-Acción propuesto por Physical Intelligence para un control robótico más "general". Puedes entenderlo así: puede ver imágenes de la cámara y entender una instrucción en lenguaje natural, y luego generar acciones para controlar el brazo robótico.
Usarlo en LeRobot es sencillo: solo tienes que establecer el tipo de política en --policy.type=pi0 durante el entrenamiento (no es necesario repetir los conceptos generales de entrenamiento/evaluación cubiertos en la sección ACT).
pip install -e ".[pi]"
Si estás usando una versión antigua de LeRobot (por ejemplo, 0.4.0), puede que necesites instalar la dependencia pi desde el código fuente de GitHub (la documentación oficial corregirá esto en un parche posterior):
pip install "lerobot[pi]@git+https://github.com/huggingface/lerobot.git"
Entrenamiento
lerobot-train \
--policy.type=pi0 \
--dataset.repo_id=${HF_USER}/my_dataset \
--job_name=pi0_training \
--output_dir=outputs/pi0_training \
--policy.pretrained_path=lerobot/pi0_base \
--policy.repo_id=${HF_USER}/my_pi0_policy \
--policy.compile_model=true \
--policy.gradient_checkpointing=true \
--policy.dtype=bfloat16 \
--policy.freeze_vision_encoder=false \
--policy.train_expert_only=false \
--steps=3000 \
--policy.device=cuda \
--batch_size=32 \
--wandb.enable=false
Parámetros comunes (solo específicos de Pi0 / los más ajustados con frecuencia):
--policy.pretrained_path=lerobot/pi0_base: Modelo base. Oficialmente también se proporcionalerobot/pi0_libero(versión orientada al conjunto de datos Libero), puedes probar a cambiar según tu tarea.--policy.compile_model=true: Activa la optimización por compilación, el entrenamiento puede ser más rápido (la primera compilación es más lenta).--policy.gradient_checkpointing=true: Ahorra significativamente VRAM, adecuado cuando la VRAM es limitada.--policy.dtype=bfloat16: Precisión mixta, más amigable para la velocidad/VRAM (recomendado cuando el hardware lo soporta).--policy.train_expert_only=true(truco para ahorrar VRAM): Congela la parte del modelo grande (VLM), solo entrena el "experto de acción" y las capas de proyección; ahorra más VRAM pero la capacidad entrenable es más limitada, adecuado para empezar o para experimentos rápidos con pocos datos.
Evaluación
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"} }' \
--robot.id=follower1 \
--display_data=false \
--dataset.repo_id=${HF_USER}/eval_my_pi0_test \
--dataset.single_task="Put lego brick into the transparent box" \
--dataset.episode_time_s=50 \
--dataset.num_episodes=10 \
--policy.path=outputs/pi0_training/checkpoints/last/pretrained_model
Consulta el tutorial oficial Pi0.5.
π₀.₅ (Pi0.5) también es un modelo de Visión-Lenguaje-Acción propuesto por Physical Intelligence, que puede entenderse como una "versión mejorada" de π₀, con énfasis en una mayor capacidad de generalización en mundo abierto.
Para usarlo en LeRobot: simplemente establece el tipo de política en --policy.type=pi05.
pip install -e ".[pi]"
Si estás usando una versión antigua de LeRobot (por ejemplo, 0.4.0), puede que necesites instalar la dependencia pi desde el código fuente de GitHub (la documentación oficial corregirá esto en un parche posterior):
pip install "lerobot[pi]@git+https://github.com/huggingface/lerobot.git"
Entrenamiento
lerobot-train \
--dataset.repo_id=${HF_USER}/my_dataset \
--policy.type=pi05 \
--output_dir=outputs/pi05_training \
--job_name=pi05_training \
--policy.repo_id=${HF_USER}/my_pi05_policy \
--policy.pretrained_path=lerobot/pi05_base \
--policy.compile_model=true \
--policy.gradient_checkpointing=true \
--policy.dtype=bfloat16 \
--policy.freeze_vision_encoder=false \
--policy.train_expert_only=false \
--steps=3000 \
--policy.device=cuda \
--batch_size=32 \
--wandb.enable=false
Parámetros comunes (relacionados con Pi0.5):
--policy.pretrained_path=lerobot/pi05_base: Modelo base. Oficialmente también se proporcionalerobot/pi05_libero.--policy.train_expert_only=true(truco para ahorrar VRAM): Congela la parte del modelo grande (VLM), solo entrena el "experto de acción" y las capas de proyección.--policy.normalization_mapping=...: Si las estadísticas de normalización de tu conjunto de datos no coinciden o faltan, puedes usar este mapeo para forzar un método de normalización.
Evaluación
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"} }' \
--robot.id=follower1 \
--display_data=false \
--dataset.repo_id=${HF_USER}/eval_my_pi05_test \
--dataset.single_task="Put lego brick into the transparent box" \
--dataset.episode_time_s=50 \
--dataset.num_episodes=10 \
--policy.path=outputs/pi05_training/checkpoints/last/pretrained_model
Consulta el tutorial oficial GR00T N1.5.
GR00T N1.5 es un modelo base abierto proporcionado por NVIDIA. La clave para usarlo en LeRobot es establecer el tipo de política en --policy.type=groot. Nota: GR00T N1.5 actualmente tiene mayores requisitos de entorno (depende de FlashAttention y requiere una GPU CUDA). Se recomienda hacer funcionar primero ACT / Pi0 antes de probar GR00T.
Instalación (Importante)
Según la documentación oficial, GR00T N1.5 requiere flash-attn para funcionar y solo puede utilizarse en dispositivos compatibles con CUDA.
Pasos recomendados (ejecutar en orden):
- Configura primero el entorno base (Python, CUDA, drivers, etc.) siguiendo la guía de instalación. No instales
leroboten este paso. - Instala PyTorch (rango de versiones según los requisitos oficiales):
pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0"
Si estás usando la serie RTX 50, necesitas: Python=3.10, CUDA=12.8, Torch=2.7.1
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128
- Instala la dependencia flash-attn y flash-attn en sí:
pip install ninja "packaging>=24.2,<26.0"
pip install "flash-attn>=2.5.9,<3.0.0" --no-build-isolation
python -c "import flash_attn; print(f'Flash Attention {flash_attn.__version__} imported successfully')"
Si estás usando la serie RTX 50, necesitas: flash_attn=2.8.0
pip install flash_attn==2.8.0.post2 torch==2.7.1 --no-build-isolation
- Instala la dependencia groot de LeRobot:
pip install "lerobot[groot]"
Si la instalación de flash-attn falla, normalmente está relacionada con (1) incompatibilidad entre las versiones de PyTorch/CUDA, (2) dependencias de compilación faltantes o (3) un entorno demasiado nuevo/demasiado antiguo. En este caso, consulta primero la documentación oficial de GR00T y la guía de instalación de PyTorch.
Entrenamiento (Fine-tuning)
El repositorio oficial proporciona un ejemplo de entrenamiento multi-GPU (accelerate launch --multi_gpu ...). Si solo tienes una GPU, también puedes intentar ejecutarlo primero en modo de proceso único (el soporte / detalles de parámetros están sujetos a la documentación oficial).
Multi-GPU (las variables deben ser reemplazadas):
accelerate launch \
--multi_gpu \
--num_processes=$NUM_GPUS \
$(which lerobot-train) \
--output_dir=$OUTPUT_DIR \
--save_checkpoint=true \
--batch_size=$BATCH_SIZE \
--steps=$NUM_STEPS \
--save_freq=$SAVE_FREQ \
--log_freq=$LOG_FREQ \
--policy.push_to_hub=true \
--policy.type=groot \
--policy.repo_id=$REPO_ID \
--policy.tune_diffusion_model=false \
--dataset.repo_id=$DATASET_ID \
--wandb.enable=true \
--wandb.disable_artifact=true \
--job_name=$JOB_NAME
Explicación de parámetros (los más comúnmente modificados):
--dataset.repo_id: Tu conjunto de datos de entrenamiento (username/dataset_nameen Hub o caché local correspondiente arepo_id).--output_dir: Directorio de salida del entrenamiento (aquí se guardarán los pesos/checkpoints).--steps,--batch_size: Pasos de entrenamiento y tamaño de batch. Los modelos grandes son sensibles a la VRAM; si no se ejecuta, reduce primerobatch_size.--policy.repo_id: Si quieres subir el modelo a Hub, rellena el nombre del repositorio de modelo que quieres crear.
Evaluación (Ejecución en el Robot)
Después del entrenamiento, puedes usar lerobot-record para evaluación/registro igual que con otras políticas. Para usuarios de brazo único reBot B601-DM, consulta el siguiente comando:
lerobot-record \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30} }' \
--robot.id=follower1 \
--display_data=true \
--dataset.repo_id=${HF_USER}/eval_groot_rebot \
--dataset.num_episodes=10 \
--dataset.single_task="Grab the black cube and put it in the box" \
--policy.path=${HF_USER}/groot-rebot \
--dataset.episode_time_s=30 \
--dataset.reset_time_s=10
Licencia: Este modelo sigue la licencia Apache 2.0 (coherente con el repositorio original de GR00T).
PEFT (Parameter-Efficient Fine-Tuning) es un conjunto de métodos y herramientas de "adaptación eficiente en parámetros" para adaptar grandes modelos preentrenados a nuevas tareas sin actualizar todos los parámetros del modelo. Para las políticas preentrenadas de LeRobot (por ejemplo, SmolVLA, π₀, etc.), normalmente puedes entrenar solo un pequeño número de parámetros "adaptadores" (por ejemplo, LoRA) para lograr resultados cercanos al fine-tuning completo, reduciendo al mismo tiempo el uso de VRAM y el coste de entrenamiento.
Instalación
Instala la dependencia opcional peft de LeRobot para usar parámetros relacionados con PEFT:
pip install -e ".[peft]"
pip install "lerobot[peft]"
Para más métodos de adaptación y explicaciones de conceptos, consulta la documentación oficial: 🤗 PEFT Documentation
Ejemplo: Fine-tuning de SmolVLA con LoRA (subtarea libero_spatial de Libero)
El siguiente ejemplo muestra cómo realizar fine-tuning con LoRA de lerobot/smolvla_base en el conjunto de datos HuggingFaceVLA/libero. Los nombres de los parámetros se basan en la versión actual de LeRobot; consulta también lerobot-train --help.
lerobot-train \
--policy.path=lerobot/smolvla_base \
--policy.repo_id=${HF_USER}/my_libero_smolvla_peft \
--dataset.repo_id=HuggingFaceVLA/libero \
--env.type=libero \
--env.task=libero_spatial \
--output_dir=outputs/train/my_libero_smolvla_peft \
--job_name=my_libero_smolvla_peft \
--policy.device=cuda \
--steps=10000 \
--batch_size=32 \
--optimizer.lr=1e-3 \
--peft.method_type=LORA \
--peft.r=64
Parámetros clave de PEFT
--peft.method_type: Selecciona el método PEFT. LoRA (Low-Rank Adapter) es uno de los métodos más utilizados.--peft.r: Rango de LoRA. En general, un rango más alto implica mayor capacidad expresiva, pero también más parámetros y mayor uso de VRAM.
Especificar capas para inyectar LoRA (Opcional)
Por defecto, PEFT suele inyectar LoRA en las capas de proyección más críticas del modelo (por ejemplo, q_proj, v_proj de la atención, etc.), y puede cubrir adicionalmente capas de proyección relacionadas con estado/acción. Si necesitas apuntar a capas diferentes, usa --peft.target_modules para especificar las capas objetivo.
Los patrones comunes incluyen:
- Por lista de sufijos de nombre de módulo (ejemplo):
--peft.target_modules="['q_proj', 'v_proj']"
- Usando una expresión regular (ejemplo, ajusta según los nombres reales de los módulos):
--peft.target_modules='(model\\.vlm_with_expert\\.lm_expert\\..*\\.(down|gate|up)_proj|.*\\.(state_proj|action_in_proj|action_out_proj|action_time_mlp_in|action_time_mlp_out))'
Especificar ciertas capas para entrenamiento completo (Opcional)
Si quieres que ciertos módulos se "entrenen completamente" (en lugar de solo inyectar LoRA), usa --peft.full_training_modules para especificarlos. Por ejemplo, para entrenar completamente solo state_proj:
--peft.full_training_modules="['state_proj']"
Recomendaciones de tasa de aprendizaje (valores de experiencia)
La tasa de aprendizaje de LoRA normalmente puede ser un orden de magnitud mayor que la del fine-tuning completo (experiencia común: ~10x). Por ejemplo, el fine-tuning completo suele usar 1e-4, mientras que LoRA puede empezar desde 1e-3; si tienes activada la disminución de la tasa de aprendizaje (scheduler), la tasa de aprendizaje final también suele establecerse alrededor de 1e-4 como referencia.
1. Pasos de entrenamiento
Método Uno: Entrenamiento Multi-GPU mediante argumentos de línea de comandos
Primero, instala el sistema de aceleración de entrenamiento en tu entorno de lerobot:
pip install accelerate
Luego ejecuta el siguiente comando para iniciar el entrenamiento multi-GPU:
accelerate launch \
--multi_gpu \
--num_processes=2 \
$(which lerobot-train) \
--dataset.repo_id=${HF_USER}/my_dataset \
--policy.type=act \
--policy.repo_id=${HF_USER}/my_trained_policy \
--output_dir=outputs/train/act_multi_gpu \
--job_name=act_multi_gpu \
--wandb.enable=true
Explicación de parámetros clave de accelerate:
--multi_gpu: Habilita el entrenamiento multi-GPU--num_processes=2: Número de GPUs a usar (normalmente igual al número de GPUs)--mixed_precision=fp16: Usa precisión mixta fp16 (o bf16 si tu hardware lo soporta)
Ten en cuenta que bf16 requiere soporte de hardware y no está disponible en todas las GPUs.
| Tipo de precisión | Soporte de hardware |
|---|---|
| fp16 | Soportado por casi todas las GPUs NVIDIA |
| bf16 | Solo soportado en GPUs más nuevas (arquitectura Ampere y posteriores) |
Si tu GPU no soporta bf16, elige fp16 en tu configuración de accelerate, o especifica explícitamente fp16 en la línea de comandos.
Método Dos: Usar un archivo de configuración de Accelerate (Opcional)
Si realizas entrenamiento multi-GPU con frecuencia, puedes guardar la configuración de entrenamiento anterior para evitar introducir repetidamente los parámetros en la línea de comandos.
Consejo: Si no entiendes esta sección, o solo quieres empezar rápidamente, puedes omitir esta sección y usar el Método Uno (argumentos de línea de comandos).
El propósito de accelerate config es:
Guardar tu entorno de hardware (número de GPUs, precisión mixta, etc.) como un archivo de configuración,
para que no necesites rellenar repetidamente estos parámetros al ejecutar accelerate launch en el futuro.
No cambia ninguna lógica de entrenamiento de LeRobot; solo reduce la introducción repetitiva de parámetros.
Si solo usas ocasionalmente multi-GPU, o es tu primer intento, está perfectamente bien no usarlo.
Ejecuta:
accelerate config
En el proceso de configuración interactiva, para el escenario común de una sola máquina con múltiples GPUs, puedes seleccionar lo siguiente:
- Entorno de cómputo: Esta máquina
- Número de máquinas: 1
- Número de procesos: Número de GPUs a usar (normalmente igual al número de GPUs)
- IDs de GPU a usar: Pulsa Enter directamente (significa usar todas las GPUs)
- Precisión mixta:
- Preferir fp16
- Si confirmas que la GPU soporta bf16, también puedes elegir bf16
Después de la configuración, puedes entrenar con:
accelerate launch $(which lerobot-train) \
--dataset.repo_id=${HF_USER}/my_dataset \
--policy.type=act \
--policy.repo_id=${HF_USER}/my_trained_policy \
--output_dir=outputs/train/act_multi_gpu \
--job_name=act_multi_gpu \
--wandb.enable=true
Impacto del entrenamiento Multi-GPU en los parámetros de entrenamiento y estrategias de ajuste
LeRobot no ajusta automáticamente la tasa de aprendizaje ni los pasos de entrenamiento en función del número de GPUs, para evitar cambiar el comportamiento de entrenamiento sin que el usuario lo sepa. Esto difiere de otros frameworks de entrenamiento distribuido de uso común.
Si quieres ajustar los hiperparámetros para entrenamiento multi‑GPU, debes hacerlo manualmente siguiendo estos pasos.
Impacto en los steps y estrategia de ajuste
Dado que el uso de varias GPU incrementa el batch size efectivo (batch_size × num_gpus):
(Para entenderlo de forma intuitiva: si el entrenamiento es como caminar, una GPU da un paso de un metro, dos GPU dan un paso de dos metros. Para alcanzar la misma distancia (datos totales aprendidos por el modelo), el entrenamiento con dos GPU debería reducir a la mitad los steps. De forma similar, n GPU = 1/n.)
Por lo tanto, al entrenar con varias GPU, deberías reducir apropiadamente el número de steps de entrenamiento.
Entrenamiento con una sola GPU:
- batch_size = 8
- steps = 100000
Entrenamiento con dos GPU (el batch size efectivo pasa a 16):
- batch_size, si sigue configurado en 8
- los steps se pueden reducir a 50000
accelerate launch --num_processes=2 $(which lerobot-train) \
--batch_size=8 \
--steps=50000 \
--dataset.repo_id=lerobot/pusht \
--policy=act
Impacto en la tasa de aprendizaje y estrategia de ajuste
Cuando se usan varias GPU, cada actualización de step utiliza más muestras.
Si quieres mantener la "velocidad de aprendizaje" del modelo similar a la de una sola GPU, normalmente necesitas aumentar la tasa de aprendizaje proporcionalmente al número de GPU.
- Nueva tasa de aprendizaje = tasa de aprendizaje de una sola GPU × número de GPU
Por ejemplo:
Si la tasa de aprendizaje con una sola GPU (optimizer.lr) es 1e-4, al usar 2 GPU, puedes cambiarla a 2e-4:
accelerate launch --num_processes=2 $(which lerobot-train) \
--optimizer.lr=2e-4 \
--dataset.repo_id=lerobot/pusht \
--policy=act
Nota:
Estas no son reglas obligatorias, sino buenas prácticas habituales.
Si no estás seguro de cómo ajustar, también puedes:
- Mantener la tasa de aprendizaje sin cambios
- Mantener los steps de entrenamiento sin cambios
Mientras el proceso de entrenamiento sea estable, los resultados seguirán siendo utilizables.
Para configuraciones más avanzadas y resolución de problemas, consulta la documentación de Accelerate. Si quieres aprender más sobre entrenamiento con un gran número de GPU, revisa esta excelente guía: Ultrascale Playbook.
Sin inferencia asíncrona, el flujo de control de LeRobot puede entenderse como inferencia secuencial/sincrónica convencional: la policy predice un action chunk, luego lo ejecuta y después espera la siguiente predicción. Para modelos más grandes, esto puede causar pausas notables mientras el robot espera nuevos action chunks. El objetivo de la inferencia asíncrona es permitir que el robot ejecute el action chunk actual mientras pre‑calcula el siguiente, reduciendo el tiempo inactivo y mejorando la capacidad de respuesta. La inferencia asíncrona se aplica a las policies compatibles con LeRobot que generan action chunks, como ACT, OpenVLA, Pi0, SmolVLA. Dado que la inferencia y el control real están desacoplados, la inferencia asíncrona también permite usar máquinas más potentes para la inferencia del robot de forma remota.
Puedes leer más sobre inferencia asíncrona en esta entrada de blog de Hugging Face.
Presentemos algunos conceptos básicos:
- Client: Se conecta al brazo robótico y a las cámaras, recopila observaciones (imágenes, pose del robot, etc.), las envía al server; también recibe action chunks del server y los ejecuta en orden.
- Server: El dispositivo que proporciona capacidad de cómputo. Recibe datos de la cámara y del robot, infiere (calcula) action chunks y los envía de vuelta al client. Puede ser el mismo dispositivo conectado al robot y a las cámaras, otro ordenador en la misma LAN o un servidor en la nube.
- Action chunk: Una serie de comandos de acción del brazo robótico, producidos por la policy mediante inferencia en el server.
- Synchronous inference: Predecir un chunk, ejecutar un chunk; el robot tendrá huecos de inactividad mientras espera a que se infiera el siguiente chunk. Cuando el modelo es más grande y el cómputo es insuficiente, la brecha de inferencia es significativa: el brazo se mueve, luego se detiene (inferencias), y luego vuelve a moverse.
- Asynchronous inference: A diferencia de la inferencia sincrónica, mientras el robot ejecuta el chunk actual, el server ya está calculando el siguiente chunk; las partes superpuestas se agregan para un control más receptivo.
Tres escenarios de despliegue de inferencia asíncrona
1. Despliegue en una sola máquina
Robot, cámaras, client y server están todos en el mismo dispositivo. Este es el caso más sencillo: el server escucha en 127.0.0.1 y el client también se conecta a 127.0.0.1:port. Los ejemplos de comandos en la documentación oficial siguen este escenario.
2. Despliegue en LAN
El robot y las cámaras se conectan a un dispositivo ligero, y el policy server se ejecuta en otro dispositivo de alto cómputo en la misma LAN. En este caso, el server debe escuchar en una dirección accesible para otras máquinas, y el client debe conectarse a la IP de la LAN del server, no a 127.0.0.1.
3. Despliegue entre redes / en la nube
El policy server se ejecuta en un host en la nube accesible públicamente, y el client se conecta a través de una red pública. Este enfoque puede aprovechar GPU más potentes en hosts en la nube. Con buenas condiciones de red, el tiempo de ida y vuelta (latencia de red) puede ser relativamente pequeño en comparación con el tiempo de inferencia, pero esto depende de tu entorno de red real.
Nota de seguridad: El pipeline de inferencia asíncrona de LeRobot tiene riesgos de gRPC sin autenticación + deserialización con pickle. Si el server aloja información o servicios importantes, no se recomienda exponer el servicio directamente a internet pública al desplegar en una red pública. Un enfoque más seguro es usar VPN, túneles SSH o, como mínimo, restringir las IP de origen del security group a la IP pública de tu client.
Inicio del despliegue de inferencia asíncrona
Paso 1: Configuración del entorno
Primero, instala con pip las dependencias adicionales necesarias para la inferencia asíncrona. Tanto el client como el server necesitan tener lerobot instalado con la dependencia extra:
pip install -e ".[async]"
Paso 2: Configuración y comprobación de red
1. Problemas de proxy
Si tu terminal tiene variables de entorno de proxy configuradas y se producen problemas de conexión, puedes desactivarlas temporalmente:
unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY
Nota: El comando anterior solo afecta a la sesión de terminal actual. Si abres una nueva ventana de terminal, necesitas ejecutarlo de nuevo.
2. Permitir puertos en el firewall / security groups
- Despliegue en una sola máquina: Normalmente se puede omitir.
- Despliegue en LAN: Debes permitir el puerto de escucha en el lado del server. Ejemplo de permitir un puerto de escucha en LAN (ejecutar en el server):
sudo ufw allow 8080/tcp
- Despliegue en la nube: Debes permitir el puerto en el security group del servidor en la nube e idealmente restringir las IP de origen.
Si se ejecuta en un servidor en la nube: Permite el puerto 8080 en el security group en la página de gestión del servidor, o usa otro puerto ya permitido. Los métodos varían según el proveedor de la nube.
3. Confirmar la dirección IP
El despliegue en una sola máquina puede omitir este paso (la IP siempre es 127.0.0.1).
4. Prueba de conexión
- Despliegue en una sola máquina: Omite este paso.
- Despliegue en LAN / nube: Se recomienda probar si el client puede acceder al puerto del server:
nc -vz <LAN_IP_address> 8080
nc -vz <server_public_IP> 8080
Paso 3: Iniciar el servicio
Escenario A: Despliegue en una sola máquina
Inicia el servicio local en una terminal:
python -m lerobot.async_inference.policy_server \
--model_path=outputs/train/act_rebot_test/checkpoints/last/pretrained_model \
--server_address=127.0.0.1:8080
Después de que se inicie correctamente, debes mantener esta terminal abierta y crear una nueva terminal para ejecutar otros comandos.
Escenario B: Despliegue en LAN
Ejecutar en el server:
python -m lerobot.async_inference.policy_server \
--model_path=outputs/train/act_rebot_test/checkpoints/last/pretrained_model \
--server_address=0.0.0.0:8080
Cuando el client se conecte, --server_address debe usar la dirección IP de la LAN del server: <LAN_IP_address>:8080.
Escenario C: Despliegue en servidor en la nube
Ejecutar en el server:
python -m lerobot.async_inference.policy_server \
--model_path=outputs/train/act_rebot_test/checkpoints/last/pretrained_model \
--server_address=0.0.0.0:8080
Cuando el client se conecte, --server_address debe usar la dirección IP pública del server: <server_public_IP>:8080.
Paso 4: Elegir parámetros de inferencia
Ejecutar en el client:
python -m lerobot.async_inference.robot_client \
--robot.type=seeed_b601_dm_follower \
--robot.port=/dev/ttyACM0 \
--robot.can_adapter=damiao \
--robot.cameras='{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"} }' \
--robot.id=follower1 \
--server_address=127.0.0.1:8080 \
--actions_per_chunk=50 \
--chunk_size_threshold=0.5 \
--fixed_update_fps=30 \
--visualize_action_queue=false
Explicación de parámetros clave:
--server_address: Dirección del server. Usa127.0.0.1:portpara una sola máquina y la IP del server para LAN/nube.--actions_per_chunk: Tamaño de cada action chunk (número de acciones). Valores mayores implican menor frecuencia de inferencia pero resultados por inferencia más estables; valores menores implican un movimiento más suave pero más carga de inferencia en el server.--chunk_size_threshold: Umbral de mezcla entre action chunks antiguos y nuevos. Cuando el chunk antiguo se ha ejecutado hasta esta proporción, comienza la mezcla con el nuevo chunk.--fixed_update_fps: Frecuencia de envío de comandos de control, correspondiente a la suavidad del movimiento del brazo robótico.--visualize_action_queue: Indica si se visualiza el tamaño de la cola de acciones en tiempo de ejecución. Cuando está activado, puedes ver de forma más intuitiva si la cola llega frecuentemente al fondo, lo que te ayuda a ajustar actions_per_chunk y chunk_size_threshold.
Paso 5: Ajustar parámetros según el comportamiento del robot
En la inferencia asíncrona, hay dos parámetros adicionales que no están presentes en la inferencia sincrónica y que necesitan ajuste:
--actions_per_chunk: Tamaño de cada action chunk. Si el movimiento del robot es entrecortado/brusco, aumenta este valor; si la respuesta del robot tiene un retraso notable, disminuye este valor.--chunk_size_threshold: Umbral de mezcla entre action chunks antiguos y nuevos. Normalmente se empieza probando con0.5.
La inferencia asíncrona necesita equilibrarse: la velocidad de generación de fragmentos de acciones del servidor debe ser mayor o igual que la velocidad de consumo del cliente. De lo contrario, la cola de acciones se vaciará y el robot comenzará a tartamudear (esto se puede ver en la curva de visualización de la cola tocando fondo).
Para reanudar el entrenamiento desde un checkpoint, aquí tienes un comando de ejemplo para reanudar desde el checkpoint last de la política act_rebot_test:
lerobot-train \
--config_path=outputs/train/act_rebot_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true
Preguntas frecuentes (FAQ)
-
Si estás siguiendo este tutorial de documentación, por favor haz git clone del repositorio de GitHub recomendado
https://github.com/Seeed-Projects/lerobot.git. El repositorio recomendado en esta documentación es una versión estable verificada; el repositorio oficial de LeRobot se actualiza continuamente a la última versión, lo que puede causar problemas imprevistos como diferentes versiones de conjuntos de datos, diferentes comandos, etc. -
Si te encuentras con:
Could not connect on port "/dev/ttyUSB0" or "/dev/ttyACM0"Y puedes ver que el dispositivo existe al ejecutar
ls /dev/ttyUSB*ols /dev/ttyACM*, significa que olvidaste otorgar permisos al puerto serie. Introducesudo chmod 666 /dev/ttyUSB* /dev/ttyACM*en la terminal para solucionarlo. -
Si te encuentras con:
No valid stream found in input file. Is -1 of the desired media type?Por favor instala ffmpeg 7.1.1 usando
conda install ffmpeg=7.1.1 -c conda-forge. -
Entrenar ACT con 50 conjuntos de datos lleva aproximadamente 6 horas en un portátil con una RTX 3060 (8GB), y alrededor de 2-3 horas en ordenadores con GPUs RTX 4090 o A100.
-
Durante la recopilación de datos, asegúrate de que la posición de la cámara, el ángulo y la iluminación ambiental sean estables. Reduce la cantidad de fondo inestable y de peatones capturados por la cámara, ya que cambios excesivos en el entorno de despliegue pueden hacer que el brazo robótico no pueda agarrar correctamente.
-
Para el comando de recopilación de datos, asegúrate de que el parámetro
num-episodesesté configurado para recopilar suficientes datos. No pauses manualmente a mitad de camino, ya que la media y la varianza de los datos se calculan solo después de que la recopilación de datos se haya completado, lo cual es necesario para el entrenamiento. -
Si el programa indica que no puede leer datos de imagen desde la cámara USB, asegúrate de que la cámara USB no esté conectada a través de un hub. La cámara USB debe estar conectada directamente al dispositivo para garantizar una alta velocidad de transmisión de imágenes.
Si encuentras problemas de software o de dependencias del entorno que no puedas resolver, además de revisar la sección de Preguntas frecuentes (FAQ) al final de este tutorial, informa del problema de inmediato en la plataforma LeRobot o en el canal de Discord de LeRobot.
Referencias
Wiki en inglés de Seeed Studio: Cómo usar el brazo robótico SO100Arm en Lerobot
Proyecto TheRobotStudio: SO-ARM10x
Proyecto Huggingface: LeRobot
Dnsty: Jetson Containers
Soporte técnico y debate sobre el producto
¡Gracias por elegir nuestros productos! Estamos aquí para ofrecerte diferentes tipos de soporte y garantizar que tu experiencia con nuestros productos sea lo más fluida posible. Ofrecemos varios canales de comunicación para adaptarnos a diferentes preferencias y necesidades.