LeRobot documentation
EnvHub: Comparte un simulador en el Hub
EnvHub: Comparte un simulador en el Hub
Un entorno de EnvHub es un repositorio de Hugging Face Hub con un env.py que construye un entorno de Gymnasium siguiendo las convenciones de LeRobot (ver El entorno). Ese archivo es toda la integración: no se necesita enviar una pull request a LeRobot ni publicar un paquete. Una vez que está en el Hub, cualquiera puede:
- evaluar una política en él con
lerobot-eval, - controlarlo como un robot con
lerobot-rollout,lerobot-record,lerobot-teleoperateylerobot-replay, intercambiable con el robot real que simula, - ejecutarlo localmente, en su propio entorno de Python, o servido por
lerobot-env-serveren una imagen de Docker construida a partir del repositorio, para que las dependencias del simulador nunca se crucen con las de la política.
Esta página muestra cómo usar un entorno de EnvHub y luego todo lo necesario para escribir y publicar uno. Simulation cubre los comandos en detalle; Adding a benchmark es para los benchmarks que LeRobot mantiene en su CI.
Usar un entorno de EnvHub
Explora los entornos publicados en la colección de entornos de EnvHub o busca en el Hub la etiqueta envhub.
Los ejemplos utilizan lerobot/so101-tabletop-mujoco: un brazo SO-101, cuatro cubos y una caja sobre una mesa, simulados con MuJoCo. Su estado y acciones son los del so101_follower real con use_degrees=True.
Sirve
Desde un checkout de la fuente de LeRobot (la imagen se construye a partir de él), con Docker y acceso a GPU para sus contenedores:
lerobot-env-server --envhub=lerobot/so101-tabletop-mujoco@<commit> --trust_remote_code=true --docker=trueEsto construye una imagen con el repositorio y su requirements.txt en el primer uso, y arranca el servidor en localhost:7448. --trust_remote_code=true es tu consentimiento para ejecutar el código del repositorio, dentro del contenedor: lee primero env.py, requirements.txt y packages.txt, y fija el commit que leíste, para que ejecutes exactamente ese código y los resultados sean reproducibles. Sin ello, el servidor se niega a arrancar. El lado cliente necesita el extra remote (pip install 'lerobot[remote]').
El servidor también puede ejecutarse en otra máquina, como una estación de trabajo con GPU o una instancia en la nube, mientras que la política se ejecuta en la tuya: consulta Dónde se ejecuta el servidor.
Evaluar una política
lerobot-eval \
--policy.path=<your SO-101 checkpoint> \
--env.type=envhub --env.hub_path=lerobot/so101-tabletop-mujoco@<commit> \
--env.server.endpoint=tcp/127.0.0.1:7448 \
--rename_map='{"observation.images.front": "observation.images.camera1", "observation.images.wrist": "observation.images.camera2"}' \
--eval.n_episodes=10 --eval.batch_size=1Las observaciones llegan a la política como observation.images.<camera> y observation.state; --rename_map las mapea a los nombres con los que se entrenó el punto de control.
Conduce como un robot
El mismo entorno es un robot: --robot.type=sim, con las opciones del entorno bajo --robot.env.*. Teleopéralo con un brazo líder SO-101 real, como lo harías con el seguidor real:
lerobot-teleoperate \
--robot.type=sim --robot.env.type=envhub --robot.env.hub_path=lerobot/so101-tabletop-mujoco@<commit> \
--robot.env.server.endpoint=tcp/127.0.0.1:7448 \
--teleop.type=so101_leader --teleop.port=/dev/ttyACM0 --teleop.id=my_leader \
--fps=30 --display_data=truelerobot-record acepta las mismas opciones para grabar un conjunto de datos, y lerobot-rollout para ejecutar una política. El conjunto de datos registra el cuerpo que declara el entorno, en este caso so_follower, tal como lo haría el seguidor real. Consulte Ejecutar un robot simulado para conocer los episodios, las tasas y la grabación.
Ejecútalo localmente
Sin --env.server.endpoint (o --robot.env.server.endpoint), el entorno se ejecuta en tu proceso. Instala su requirements.txt junto a LeRobot y añade --env.trust_remote_code=true (--robot.env.trust_remote_code=true): tu proceso ejecuta el env.py del repositorio. Si se sirve, tu proceso nunca lo ejecuta, por lo que el cliente no necesita consentimiento: el --trust_remote_code=true del servidor lo cubre.
Desde una carpeta local
Una carpeta que contiene env.py funciona en cualquier lugar donde funcione un repositorio de Hub, ya sea para un entorno que estés escribiendo o para un clon que hayas leído: --env.hub_path=./my-env, --robot.env.hub_path=./my-env, --envhub=./my-env. Requiere el mismo consentimiento, ya que sigue siendo código. Para servirlo sin construir una imagen, elimina --docker=true: el servidor se ejecutará entonces en tu entorno Python actual, con el requirements.txt de la carpeta instalado allí.
lerobot-env-server --envhub=./my-env --trust_remote_code=true # in your Python environment
lerobot-env-server --envhub=./my-env --trust_remote_code=true --docker=true # in an image built from the folderCrear un entorno
El repositorio
| Archivo | Obligatorio | Contenido |
|---|---|---|
env.py | sí | make_env, el entorno y, opcionalmente, LEROBOT_SIM |
requirements.txt | no | Los paquetes de Python que necesita env.py, instalados en la imagen del servidor |
packages.txt | no | Paquetes de Ubuntu, uno por línea, instalados en la imagen del servidor |
README.md | sí | Lo que simula el entorno, sus observaciones, acciones, tarea, recompensas y fin de episodio, los comandos para ejecutarlo, sus licencias |
| cualquier otra cosa | no | Escenas, modelos de robots, texturas, configuraciones: env.py los encuentra junto a sí mismo, en todos los modos |
Créalo como un repositorio de modelos en el Hub.
Python y dependencias
LeRobot requiere Python 3.12 o una versión más reciente, y lo mismo aplica a tu entorno: localmente, env.py se ejecuta en el proceso de LeRobot, y la imagen del servidor ejecuta Python 3.12 de Ubuntu 24.04. Un simulador que solo admite una versión anterior de Python (por ejemplo, Isaac Sim 5 e Isaac Lab 2, en Python 3.11) no se ejecuta de ninguna de las dos formas; utiliza una versión que admita Python 3.12 (Isaac Sim 6 e Isaac Lab 3, como lo hace RoboLab).
La imagen del servidor solo contiene lo que el servidor necesita: ni torch ni el resto de LeRobot. Enumera todo lo que env.py importa en requirements.txt, incluido torch si tu simulador lo necesita, y fija las versiones.
make_env
env.py debe definir make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs), que devuelve {suite_name: {task_id: vector_env}}, donde cada vector env contiene n_envs entornos de esa tarea:
def make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs):
factory = partial(MyEnv, **kwargs)
vector_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv
return {"my_task": {0: vector_cls([factory] * n_envs)}}- Construya cada env de vectores a partir de las fábricas por entorno, como se indicó anteriormente, y devuélvalo sin envolver: LeRobot toma las fábricas y ejecuta los entornos por sí mismo (consulte Batches). Un envoltorio de vectores personalizado o una subclase se rechaza en lugar de descartarse silenciosamente. También se acepta un único
gym.Env, como un solo suite con ID de tarea 0. - Varias suites o IDs de tareas forman un benchmark multitarea:
lerobot-evalinforma una tasa de éxito por tarea, por suite y en general. Un robot de simulación ejecuta la suite indicada por--robot.env.task(la primera por defecto) y la tarea indicada por--robot.task_id. kwargsson las opciones propias del entorno. Los usuarios las pasan con--env.make_env_kwargs='{"episode_length": 900}'(--robot.env.make_env_kwargspara un robot simulado); un servidor las recibe con--sim.kwargs='{make_env_kwargs: {episode_length: 900}}'.env.pyse importa una vez por proceso, por lo que puede mantener un estado a nivel de proceso, como una aplicación de simulador que solo puede iniciarse una vez (laSimulationAppde Isaac Sim).
El entorno
Cada entorno es un gym.Env que sigue estas convenciones. Un entorno de Gymnasium estándar normalmente no las cumple: la observación de CartPole es un vector plano y su acción es discreta, por lo que LeRobot lo rechaza. Envuelve este tipo de entorno para que devuelva este diccionario de observación y una acción continua Box.
| Qué | Contrato |
|---|---|
| Observación | Un diccionario de arrays de NumPy: pixels (una imagen RGB HWC uint8, o un diccionario de ellas, una por cámara), agent_pos (el estado del robot) y opcionalmente environment_state. Otros arrays se pasan tal cual |
| Acción | Una Box continua de una dimensión |
task_description | La instrucción de idioma dada a la política (recurre a task) |
_max_episode_steps | El límite de pasos, tras el cual LeRobot trunca el episodio (500 si no está presente) |
devolución de step() | terminated cuando termina el episodio (éxito o fracaso), truncated cuando se interrumpe |
info["is_success"] | Si la tarea se ha completado, en cada step() |
info["metrics"] | Opcional: otros números para informar, {name: float}; lerobot-eval los conserva por episodio, tomados en el paso en que terminó |
LeRobot mapea la observación a observation.images.<camera> (observation.image para una única imagen sin nombre), observation.state y observation.environment_state. Convierta las salidas de su simulador a estas convenciones dentro del entorno: imágenes de cámara en posición vertical y estado en las unidades y el orden de sus acciones cuando comparten articulaciones.
Si su simulador asigna contextos de GPU o EGL, créelos en la primera reset() en lugar de en __init__, para que un entorno creado en un proceso de worker no herede manejadores obsoletos.
LEROBOT_SIM
Un diccionario a nivel de módulo en env.py que describe el entorno. Se aplica localmente y al servirlo, y cada clave es opcional:
| Clave | Significado | Predeterminado |
|---|---|---|
fps | Tasa de control: step() por segundo de tiempo simulado | 30 |
control_mode | Convención de acción: position, delta o eef_pose | "position" |
semantics | Nombre de las convenciones de observación y acción | "envhub-v1" |
state_names | Nombres de los componentes de observation.state, en orden | state_0, state_1, … |
action_names | Nombres de los componentes de la acción, en orden | command_0, command_1, … |
robot_type | Cuerpo simulado, registrado como robot_type de los conjuntos de datos | ninguno (registro de datasets sim_robot) |
Decláralo siempre que los valores predeterminados no coincidan con tu entorno. Una clave desconocida es un error, indicando la clave válida más cercana. Las opciones --sim.* de un servidor lo sobrescriben, por ejemplo, --sim.fps=15.
Para que un entorno sea un gemelo de un robot real que LeRobot admite, utiliza los nombres, las unidades y el robot_type de ese robot. Un teleoperador lo controla de la misma manera que controla al seguidor real, los conjuntos de datos grabados en simulación y en el hardware coinciden, y un punto de control entrenado en uno funciona en el otro. En el caso de un SO-101, son shoulder_pan.pos … gripper.pos, en grados con la pinza de 0 a 100, y robot_type: "so_follower". Cuando LeRobot no tiene una clase para tu robot, elige un robot_type corto en snake_case (panda, sawyer).
Un ejemplo completo
Un punto para moverse a un objetivo, sin dependencias más allá de Gymnasium y NumPy. Cumple con todo lo anterior; cópialo como punto de partida:
# env.py
from functools import partial
import gymnasium as gym
import numpy as np
from gymnasium import spaces
JOINTS = ["x.pos", "y.pos"]
# How LeRobot describes this environment, locally and when served. Every key is optional.
LEROBOT_SIM = {
"fps": 10,
"control_mode": "position",
"state_names": JOINTS,
"action_names": JOINTS,
}
class ReachEnv(gym.Env):
"""Move a point to a target on a plane. The action is the point's next position, in [-1, 1]."""
metadata = {"render_modes": ["rgb_array"], "render_fps": 10}
def __init__(self, image_size: int = 96, episode_length: int = 100):
super().__init__()
self.image_size = image_size
self._max_episode_steps = episode_length
self.task = "reach"
self.task_description = "Move the blue point onto the red target."
image = spaces.Box(0, 255, (image_size, image_size, 3), np.uint8)
self.observation_space = spaces.Dict(
{"pixels": spaces.Dict({"top": image}), "agent_pos": spaces.Box(-1, 1, (2,), np.float32)}
)
self.action_space = spaces.Box(-1, 1, (2,), np.float32)
def reset(self, seed=None, options=None):
super().reset(seed=seed)
self.point = self.np_random.uniform(-1, 1, 2).astype(np.float32)
self.target = self.np_random.uniform(-1, 1, 2).astype(np.float32)
return self._obs(), {"is_success": False}
def step(self, action):
self.point = np.clip(np.asarray(action, np.float32), -1, 1)
distance = float(np.linalg.norm(self.point - self.target))
success = distance < 0.1
info = {"is_success": success, "metrics": {"distance": distance}}
# Ends on success (terminated); LeRobot truncates the episode after _max_episode_steps.
return self._obs(), -distance, success, False, info
def _obs(self):
image = np.full((self.image_size, self.image_size, 3), 255, np.uint8)
for xy, color in ((self.target, (220, 40, 40)), (self.point, (40, 40, 220))):
col, row = ((xy + 1) / 2 * (self.image_size - 1)).astype(int)
image[max(row - 3, 0) : row + 4, max(col - 3, 0) : col + 4] = color
return {"pixels": {"top": image}, "agent_pos": self.point.copy()}
def make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs):
"""The EnvHub entry point. `kwargs` come from --env.make_env_kwargs."""
factory = partial(ReachEnv, **kwargs)
vector_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv
return {"reach": {0: vector_cls([factory] * n_envs)}}Para un simulador real, consulte lerobot/so101-tabletop-mujoco (MuJoCo) y lerobot/so101-tabletop-isaac (Isaac Sim, instalado a través de requirements.txt y packages.txt). Sirven la misma escena SO-101 con las mismas observaciones, acciones y LEROBOT_SIM, por lo que las mismas políticas y comandos se ejecutan contra ambos. Hay más en la colección de entornos de EnvHub.
Lotes
lerobot-eval --eval.batch_size=N ejecuta N entornos de una tarea a la vez, y make_env recibe n_envs=N; un robot de simulación ejecuta uno. Un lote se avanza de una de dos maneras.
LeRobot hace un paso de un lote de entornos individuales, que es el comportamiento predeterminado y lo que la mayoría de los simuladores necesitan (MuJoCo, PyBullet, …). Escribe un gym.Env que simule un solo entorno y devuelve n_envs fábricas de este desde make_env, como se muestra arriba. LeRobot construye los entornos a partir de las fábricas: con --eval.use_async_envs=true (el valor predeterminado), cada uno se ejecuta en su propio proceso de trabajo y el lote da los pasos en paralelo; con false, todos se ejecutan en un solo proceso, uno tras otro. LeRobot solo utiliza las fábricas, por lo que no importa en qué clase de vector make_env las agrupa.
Su simulador avanza el lote completo cuando mantiene todos los entornos en un solo mundo y los avanza a la vez, como hacen los simuladores de GPU como Isaac Lab. Defina también vector_env_fns en env.py, devolviendo una fábrica por tarea, cada una construyendo un entorno vectorial de n_envs entornos; LeRobot luego lo usa en lugar de make_env:
from functools import partial
def vector_env_fns(task: str, n_envs: int, **make_env_kwargs):
# {suite_name: {task_id: factory}}, each factory building one vector env of n_envs envs
return {"suite_1": {0: partial(MyBatchedEnv, n_envs, "Task1"), 1: partial(MyBatchedEnv, n_envs, "Task2")}}Cada vector env debe tener num_envs == n_envs y no debe autoresetear (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED). Devuelve observaciones por lotes en el formato anterior, toma una semilla por entorno en reset(seed=[...]) e informa info["is_success"] por entorno. --env.make_env_kwargs se le pasan. Dado que ya ejecuta el lote completo, evalúe con --eval.use_async_envs=false: un proceso de worker solo copiaría cada lote entre procesos, y un servidor construiría el simulador una segunda vez, en el worker.
vector_env_fns también es adecuado para un benchmark con muchas tareas: make_env construye los entornos de cada tarea cuando se llama, mientras que solo se invocan las fábricas de las tareas que se ejecutan.
Prueba antes de publicar
Cada paso toma la carpeta local que contiene env.py en lugar de un repositorio de Hub.
Construye los entornos como lo hace LeRobot y comprueba las claves, formas y tareas de la observación:
import numpy as np from lerobot.envs import HubEnvConfig, make_env # LeRobot's make_env, which calls the make_env of your env.py envs = make_env(HubEnvConfig(hub_path="./my-env", trust_remote_code=True), n_envs=2) suite = next(iter(envs)) env = envs[suite][0] obs, info = env.reset(seed=0) print({key: (value.shape, value.dtype) for key, value in obs.items()}) print(env.call("task_description")) obs, reward, terminated, truncated, info = env.step(np.zeros(env.action_space.shape, np.float32)) print(reward, terminated, truncated, info["is_success"]) env.close()Compruébalo como un robot: los nombres de los estados y las acciones, y las vistas de la cámara:
from lerobot.envs.configs import HubEnvConfig from lerobot.robots.sim_robot import SimRobot, SimRobotConfig robot = SimRobot(SimRobotConfig(env=HubEnvConfig(hub_path="./my-env", trust_remote_code=True))) print(robot.robot_type, list(robot.action_features)) robot.connect() observation = robot.get_observation() robot.send_action({name: observation[name] for name in robot.action_features}) robot.disconnect()Con un teleoperador cuyas acciones coincidan con las tuyas,
lerobot-teleoperate --robot.type=sim --robot.env.type=envhub --robot.env.hub_path=./my-env --robot.env.trust_remote_code=true ... --display_data=truemuestra las cámaras en Rerun mientras lo conduces.Sirva desde la carpeta, lo que construye la imagen a partir de su
requirements.txtypackages.txt, y luego ejecute las mismas comprobaciones contra ella con--env.server.endpoint=tcp/127.0.0.1:7448:lerobot-env-server --envhub=./my-env --trust_remote_code=true --docker=true--build=truereconstruye solo lo que cambió: los paquetes de apt cuando cambiapackages.txt, los requisitos cuando cambiarequirements.txty, en caso contrario, solo los archivos del repositorio.
Publicar
Sube la carpeta a un repositorio de modelos en el Hub y luego:
- Toma nota del commit y úsalo en los comandos de tu README: los usuarios ejecutarán exactamente lo que tú probaste.
- Indica en el README las licencias de todo lo que incluye el repositorio (modelos de robots, escenas, texturas) y un resultado de referencia si lo tienes: un checkpoint, su revisión, el comando
lerobot-evaly la tasa de éxito que obtiene. - Añade
tags: [lerobot, envhub]a los metadatos del README para que el entorno pueda encontrarse en el Hub. - Para que se incluya en la colección de entornos de EnvHub, abre un issue en GitHub de LeRobot con un enlace al repositorio.
Las actualizaciones son nuevos commits: los usuarios que fijaron un commit anterior siguen ejecutando el código que revisaron.
Referencia
Rutas de Hub
--env.hub_path (y --envhub para el servidor) aceptan:
| Patrón | Cargas | Ejemplo |
|---|---|---|
user/repo | env.py de la rama principal | lerobot/so101-tabletop-mujoco |
user/repo@revision | env.py en un commit, rama o etiqueta | lerobot/so101-tabletop-mujoco@4684f500b94d07194f2c860314c4e27cb9349e8c |
user/repo:path | Otro archivo | my-org/my-envs:envs/task_a.py |
user/repo@rev:path | Otro archivo en una revisión | my-org/my-envs@v1.0:envs/task_a.py |
./folder | env.py en una carpeta local | ./my-env |
Versiones
Las versiones de un entorno son sus commits en Hub. Una revisión después de @ (un commit, una rama o una etiqueta) selecciona una, en tu proceso y en el servidor:
- En su proceso, el repositorio en esa revisión se descarga y se almacena en caché. Sin una revisión, cada ejecución sigue el último commit de
main. - En el servidor,
--envhub=user/repo@<revision>construye la imagen a partir de los archivos de esa revisión, y cada revisión obtiene su propia imagen. Sin una revisión, la imagen contiene el commit que era el más reciente en el momento de su construcción, hasta que--build=truela reconstruye a partir del más reciente. - Etiqueta las versiones para que los usuarios puedan fijar un nombre en lugar de un hash, y mantén
mainpara el desarrollo. Fija un commit para papers y comparaciones: a diferencia de una etiqueta o una rama, no puede moverse.
Opciones
| Opción | Significado |
|---|---|
--env.type=envhub | Un entorno de EnvHub (--robot.env.type=envhub para un robot de simulación) |
--env.hub_path | El repositorio, consulte rutas de Hub |
--env.trust_remote_code | Consentir con la ejecución del código del repositorio en su proceso; no es necesario cuando se sirve |
lerobot-env-server --trust_remote_code=true | Consentir con la ejecución del código del repositorio en el servidor, necesario para servirlo, desde --envhub o un YAML |
--env.make_env_kwargs | Argumentos de palabra clave para make_env; al servirlos, establécelos en el servidor en su lugar |
--env.server.endpoint | Ejecute el entorno en un servidor de entorno; consulte Simulation para las otras opciones de servidor |
lerobot-env-server --envhub=<path> | Sirve un repositorio; con --docker=true, en una imagen construida a partir de él |
lerobot-env-server --sim.kwargs=... | Las opciones make_env del servidor, p. ej. '{make_env_kwargs: {episode_length: 900}}' |
lerobot-env-server --sim.<key>=... | Sobrescribe un valor de LEROBOT_SIM, p. ej. --sim.fps=15 |
Seguridad
Ejecutar un entorno de EnvHub ejecuta su código, con tus permisos. LeRobot nunca lo ejecuta sin tu consentimiento explícito: trust_remote_code en tu proceso, --trust_remote_code=true en el servidor. Antes de concederlo:
- Lee
env.py,requirements.txtypackages.txt. - Fija el commit que leíste.
- Prefer serving it: en su contenedor, el código ve su imagen y la configuración del servidor, no tus archivos. El contenedor comparte la red de tu equipo anfitrión.
Solución de problemas
| Error | Corregir |
|---|---|
Refusing to run the EnvHub environment | Agregue --env.trust_remote_code=true (--robot.env.trust_remote_code=true) después de leer el código, o sirva el entorno |
failed to import because the dependency '<name>' is not installed | Instale los requirements.txt del repositorio junto a LeRobot, o sirva el entorno |
requires an unwrapped SyncVectorEnv or AsyncVectorEnv | Devuelve el vector env construido a partir de fábricas, sin envoltorios |
LEROBOT_SIM has unknown keys | Utilice las claves enumeradas en LEROBOT_SIM; el error indica la más cercana |
The env server at ... runs another environment than this command describes | El servidor ejecuta un entorno diferente al que describe --env.*; pasa las mismas opciones o reinicia el servidor con las tuyas |
A sim robot needs an observation.state feature with component names | Devuelve agent_pos en la observación |
images must be HWC uint8 with three channels | Convierte las imágenes de la cámara a alto x ancho x 3, uint8 |