LeRobot documentation

Simulación

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Simulación

Un simulador en LeRobot es un entorno de Gymnasium que sigue las convenciones de LeRobot (observaciones en diccionario con imágenes de cámara y estado del robot, acciones continuas, éxito en info["is_success"]; ver El entorno), escrito una vez y utilizado en todas las partes donde LeRobot ejecuta un robot:

  • para evaluar una política, como un batched env (--env.*): muchos entornos de una misma tarea, ejecutados juntos. lerobot-eval y la evaluación durante el entrenamiento lo utilizan.
  • como un sim robot (--robot.type=sim --robot.env.*): un entorno detrás de la interfaz Robot, intercambiable con hardware real. lerobot-rollout, lerobot-record, lerobot-teleoperate y lerobot-replay lo utilizan.

Se ejecuta localmente, en tu entorno de Python, o servido por lerobot-env-server, normalmente en su propia imagen de Docker, para que las dependencias del simulador nunca se crucen con las de la política. Establecer un endpoint selecciona la ejecución servida; ambas rutas proporcionan a la política las mismas observaciones (imágenes uint8 en HWC, estado float32 plano), los mismos finales de episodio y las mismas convenciones de control.

LocalmenteServido
Entorno por lotes: lerobot-eval--env.type=<sim>--env.type=<sim> --env.server.endpoint=tcp/...
Robot simulado: lerobot-rollout, -record, -teleoperate, -replay--robot.type=sim --robot.env.type=<sim>--robot.type=sim --robot.env.type=<sim> --robot.env.server.endpoint=tcp/...
Instalaciónel simulador, junto a LeRobot (su extra)lerobot[remote]; el simulador se encuentra en la imagen del servidor
ALeer
Evaluar, registrar o teleoperar en simulaciónesta página, y la propia página del simulador (LIBERO, Meta-World, …)
Usar o publicar un simulador desde el Hugging Face HubEnvHub
Añade un benchmark que LeRobot mantiene en su CIAñadir un benchmark

Evaluar un punto de control

Localmente, con el simulador instalado junto a LeRobot (ver LIBERO):

lerobot-eval \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --policy.device=cuda \
  --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --eval.n_episodes=1 --eval.batch_size=1 \
  --output_dir=outputs/eval_libero

Servido: inicia el servidor con el mismo entorno (consulta Servir un entorno) y añade su punto de acceso:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
lerobot-eval ... --env.server.endpoint=tcp/127.0.0.1:7448

Un entorno de EnvHub funciona de la misma manera, con --env.type=envhub --env.hub_path=<user/repo>, y se sirve con lerobot-env-server --envhub=<user/repo> --trust_remote_code=true --docker=true una vez que has leído su código.

Todas las opciones del servidor están bajo --env.server.* y ninguna se aplica a una ejecución local. El cliente solicita el despliegue con el nombre que indica --env.type, tal como lo nombran las configuraciones del servidor; para otro, pasa --env.server.deployment. Un endpoint o despliegue incorrecto falla dentro de --env.server.handshake_timeout_s (10 s) e indica qué sirve el endpoint. Contra un servidor protegido con TLS, pasa su archivo Zenoh JSON5 con --env.server.zenoh_config_path, como para la inferencia remota. El servidor debe ejecutar el entorno que describe el comando: el mismo tipo, tarea, convenciones de control y cuerpo simulado (robot_type), o la evaluación se niega a iniciar y lista las diferencias. Otras opciones que difieren (resolución, longitud del episodio) se registran como advertencias.

Los nombres de las observaciones provienen del entorno (observation.images.<camera>, observation.state). Cuando un punto de control se entrenó con otros nombres de cámara, mapee los nombres con --rename_map, como para cualquier robot, y preserve la identidad de cada cámara incluso cuando varias tengan la misma forma. Las cámaras de marcador de posición (empty_cameras) son una configuración de la política guardada con el punto de control; sobrescríbala con --policy.empty_cameras solo cuando sea necesario.

Antes del primer paso, cada entrada de punto de control debe existir en el entorno después del cambio de nombre, con dimensiones de estado y acción coincidentes y el mismo número de canales RGB. La altura y el ancho de la imagen pueden diferir: el preprocesamiento de la política se encarga del redimensionado. No se verifican las convenciones del controlador (acciones delta frente a absolutas, formato de rotación); utilice un punto de control entrenado con la convención del entorno.

Lotes y rendimiento de servicio

Cada step() avanza una vez cada entorno no finalizado del lote. Un entorno que termina conserva su observación terminal hasta el siguiente reinicio; avanzar los demás nunca lo reinicia. Con --eval.use_async_envs=true (el valor predeterminado), cada entorno se ejecuta en su propio proceso de trabajo, localmente o en el servidor, y el lote avanza en paralelo. Un servidor admite hasta max_envs entornos por lote (32 por defecto).

--env.server.encoding=jpeg (o --robot.env.server.encoding=jpeg, con --env.server.jpeg_quality, 90 por defecto) envía los fotogramas de la cámara servidos como JPEG: respuestas más pequeñas para un servidor remoto y lotes más grandes, a costa del tiempo de codificación y de fotogramas con pérdida. En localhost, los fotogramas en bruto son más rápidos.

La respuesta incluye los fotogramas de cada entorno del lote y debe caber en max_payload_bytes (32 MiB por defecto) en ambos extremos; de lo contrario, el servidor rechaza el lote al abrirlo. Para lotes grandes o cámaras de alta resolución, aumente este valor en el servidor (max_payload_bytes en la sección zenoh del YAML, junto a listen_endpoints) y en el cliente (--env.server.max_payload_bytes, o --robot.env.server.max_payload_bytes).

Ejecutar un robot simulado

El mismo entorno que un entorno por lotes y como un robot de simulación:

lerobot-eval    --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' ...
lerobot-rollout --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 ...

Por ejemplo:

lerobot-rollout \
  --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 \
  --task="pick up the black bowl between the plate and the ramekin and place it on the plate" \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --device=cuda --fps=20 --inference.type=sync \
  --display_data=true --display_mode=rerun \
  --return_to_initial_position=false --play_sounds=false
  • --robot.env.* acepta las mismas opciones que --env.* en la evaluación. --robot.task_id selecciona la única tarea que ejecuta el robot, mientras que la evaluación ejecuta todas las tareas del conjunto o las especificadas en --env.task_ids. Los entornos de EnvHub son --robot.env.type=envhub --robot.env.hub_path=<user/repo>, con --robot.env.trust_remote_code=true para ejecutarlos localmente.
  • --robot.env.server.endpoint=tcp/... controla el entorno en un servidor de entornos, de la misma manera que --env.server.endpoint lo hace para un entorno por lotes. El robot comprueba que el servidor ejecute ese entorno.
  • Cada send_action() avanza el entorno exactamente una vez. Las lecturas de observación, la inferencia de la política y la espera no avanzan la simulación; el bucle de control existente gestiona el ritmo en tiempo real.
  • --fps debe ser igual a la tasa de control del entorno, dividida por --interpolation_multiplier al interpolar, ya que cada comando avanza el entorno una vez. Al grabar, --dataset.fps debe ser igual a --fps. De lo contrario, el rollout se niega a comenzar.

Un robot simulado es un robot: sustituya --robot.type=sim --robot.env.* por --robot.* del seguidor real, y todo lo demás se mantiene. Un teleoperador lo controla de la misma manera que controla al seguidor real (--teleop.type=so101_leader para un gemelo SO-101 como lerobot/so101-tabletop-mujoco), cuando el entorno declara los nombres y las unidades de las acciones del seguidor; una incompatibilidad se informa en la primera acción.

Las funciones de la cámara del robot utilizan los mismos nombres observation.images.<camera> que la grabación con hardware real. Una cámara sin nombre es observation.images.image. La evaluación por lotes conserva las propias claves del entorno, como observation.image para una sola cámara; al desplegar un punto de control con ese nombre a través de un robot simulado, use --rename_map='{"observation.images.image": "observation.image"}'.

Cuando la política se retrasa, mantener un robot simulado no avanza la física. Las fallas del simulador se propagan al cierre del despliegue.

Registrar en simulación

lerobot-record almacena el cuerpo que el entorno declara como robot_type del conjunto de datos (panda para LIBERO, so_follower para un gemelo SO-101), o sim_robot cuando no declara ninguno.

Los episodios grabados siguen los del entorno. lerobot-record y la estrategia de despliegue episódico reinician el entorno simulado al inicio de cada episodio y lo terminan cuando el episodio del entorno termina (éxito, terminación o su límite de pasos) o cuando se agota su duración, lo que ocurra primero. Cada episodio grabado es, por lo tanto, un episodio simulado, desde su estado inicial. No es necesario hacer ningún reinicio manual, así que omita la fase de reinicio entre episodios con --dataset.reset_time_s=0, y con la estrategia de despliegue episódico también pase --strategy.reset_to_initial_position=false.

Cuando termina un episodio, el robot se detiene: ignora las acciones y mantiene su estado final, y latest conserva la recompensa final, la terminación y el éxito. La teleoperación y la estrategia de rollout base inician entonces un nuevo episodio (la estrategia también restablece la política) y el replay se detiene. Para grabar con una política, usa la estrategia de rollout episódica. Los robots reales no se ven afectados: sus episodios están cronometrados y su escena se restablece manualmente. Para las tasas de éxito, evalúa con lerobot-eval y un env por lotes.

Inferencia remota

Mantenga las mismas opciones --robot.* y reemplace las opciones de política local y de inferencia con:

--inference.type=remote \
--inference.endpoint=tcp/127.0.0.1:7447 \
--inference.deployment=libero \
--inference.semantics=libero-delta-v1

Inicie el servidor de política por separado usando remote inference setup. Su esquema debe coincidir con las observaciones del robot después de --rename_map. Omita --policy.path del comando de rollout porque el servidor de política carga el checkpoint. Para RTC local, use --inference.type=rtc con la configuración de RTC de la política.

Servir un entorno

Desde un checkout de la fuente de LeRobot (la imagen se construye a partir de él), ejecute desde la raíz del repositorio:

# An in-tree simulator
lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
# An EnvHub repository, once you have read its code
lerobot-env-server --envhub=<user/repo>@<commit> --trust_remote_code=true --docker=true

--docker=true utiliza docker/sim/compose.server.yaml, selecciona la imagen desde sim.type (o la construye desde el repositorio de EnvHub), monta el YAML efectivo y ejecuta el contenedor en la red del host, de modo que el servidor escucha en localhost:7448 a menos que --zenoh.listen_endpoints indique lo contrario. Cambia el YAML para seleccionar otro simulador. La tasa de control, la convención de acciones, los nombres de los componentes y el tipo de robot de cada simulador provienen de conventions() de su integración (el LEROBOT_SIM de un repositorio de EnvHub), por lo que un YAML solo nombra la tarea y las opciones del simulador.

En cuanto a lerobot-policy-server, cada campo YAML acepta una anulación anidada desde la línea de comandos, y el archivo permanece sin cambios. Un valor de diccionario como sim.kwargs se fusiona con el del YAML:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true \
  --sim.task=libero_goal \
  --sim.kwargs='{gym_kwargs: {observation_height: 256, observation_width: 256}}'

La configuración efectiva se guarda en $HF_LEROBOT_HOME/sim, por lo que un contenedor reiniciado la encuentra. Cambiar la configuración recrea el servidor y termina las sesiones activas. La imagen se construye si falta; añade --build=true para reconstruirla después de cambiar el simulador o el código fuente de LeRobot, o --stop=true para detener el servidor. El contenedor requiere acceso a GPU de Docker para el renderizado EGL.

Si un simulador que renderiza con Vulkan (Isaac Sim, o ManiSkill/SAPIEN como en RoboMME, cuya imagen incluye su propio archivo de Vulkan) falla en el contenedor con vkCreateInstance failed o ERROR_INCOMPATIBLE_DRIVER mientras funciona fuera de Docker, el contenedor tiene las bibliotecas del controlador de NVIDIA pero no los archivos de cargador que apuntan a ellas (/usr/share/vulkan/icd.d/nvidia_icd.json, /usr/share/glvnd/egl_vendor.d/10_nvidia.json). El modo predeterminado del NVIDIA Container Toolkit, utilizado por gpus: all, puede no montarlas; su modo CDI sí lo hace. Solicita la GPU a través de CDI (--device nvidia.com/gpu=all para docker run, devices: [nvidia.com/gpu=all] en lugar de gpus: all en docker/sim/compose.server.yaml), o añade los dos archivos a la imagen.

Sin --docker=true, el mismo comando ejecuta el servidor en el entorno actual: instala las dependencias nativas del simulador en un entorno aislado con Python 3.12 o más reciente, instala LeRobot con --no-deps e instala docker/sim/requirements.txt. El servidor es parte de LeRobot, por lo que necesita el mismo Python que LeRobot; un simulador que solo admite una versión anterior de Python no puede servirse.

Donde se ejecuta el servidor

Por defecto, el servidor solo acepta conexiones desde su propia máquina, ya que la conexión no está cifrada ni autenticada: cualquiera que acceda a él puede controlar el entorno. Para ejecutarlo en otra máquina, como una estación de trabajo o una instancia en la nube con GPU, mientras la política se ejecuta en la tuya, pasa la dirección de la interfaz de red a la que tu máquina accede con --zenoh.listen_endpoints='[tcp/<address>:7448]' y conéctate con --env.server.endpoint=tcp/<address>:7448 (--robot.env.server.endpoint para un robot simulado). Limita esto a una red de confianza o añade TLS y control de acceso con un zenoh.config_file en el YAML del servidor y --env.server.zenoh_config_path en el cliente, como en el caso de la inferencia remota. En un enlace más lento, los marcos JPEG requieren menos ancho de banda.

Las solicitudes al servidor nunca se reintentan. Después de un tiempo de espera ambiguo, el cliente falla; ciérralo y abre una nueva sesión.

Agregar un simulador

Para compartir un entorno propio, publícalo en el Hub como un entorno de EnvHub: un env.py en un repositorio del Hub es toda la integración y obtiene todo lo de esta página. Los benchmarks que LeRobot mantiene y prueba en su CI, con un checkpoint fijo y una etapa de Docker, se añaden a LeRobot mismo: consulte Añadir un benchmark.

Update on GitHub