LeRobot documentation
EnvHub: Compartilhe um simulador no Hub
EnvHub: Compartilhe um simulador no Hub
Um ambiente do EnvHub é um repositório do Hugging Face Hub com um env.py que constrói um ambiente Gymnasium seguindo as convenções do LeRobot (veja O ambiente). Esse arquivo é toda a integração: sem pull request para o LeRobot, sem pacote para publicar. Uma vez que ele está no Hub, qualquer pessoa pode:
- avaliar uma política nele com
lerobot-eval, - controlá-lo como um robô com
lerobot-rollout,lerobot-record,lerobot-teleoperateelerobot-replay, substituível pelo robô real que ele simula, - executá-lo localmente, em seu próprio ambiente Python, ou servido por
lerobot-env-serverem uma imagem Docker construída a partir do repositório, para que as dependências do simulador nunca se encontrem com as da política.
Esta página mostra como usar um ambiente do EnvHub e, em seguida, tudo o que é necessário para escrever e publicar um. Simulação aborda os comandos em detalhes; Adicionando um benchmark é para os benchmarks que o LeRobot mantém em seu CI.
Use um ambiente do EnvHub
Navegue pelos ambientes publicados na coleção de ambientes do EnvHub ou pesquise no Hub pela tag envhub.
Os exemplos usam lerobot/so101-tabletop-mujoco: um braço SO-101, quatro cubos e uma caixa sobre uma mesa, simulados com MuJoCo. Seu estado e ações são os do so101_follower real com use_degrees=True.
Sirva-o
A partir de um checkout de fonte do LeRobot (a imagem é construída a partir dele), com acesso a Docker e GPU para seus contêineres:
lerobot-env-server --envhub=lerobot/so101-tabletop-mujoco@<commit> --trust_remote_code=true --docker=trueIsso constrói uma imagem com o repositório e seu requirements.txt no primeiro uso e inicia o servidor em localhost:7448. --trust_remote_code=true é o seu consentimento para executar o código do repositório, no container: leia env.py, requirements.txt e packages.txt primeiro e fixe o commit que você leu, para que você execute exatamente esse código e os resultados permaneçam reproduzíveis. Sem isso, o servidor se recusa a iniciar. O lado do cliente precisa do extra remote (pip install 'lerobot[remote]').
O servidor também pode ser executado em outra máquina, como uma estação de trabalho com GPU ou uma instância em nuvem, enquanto a política é executada na sua: veja Onde o servidor é executado.
Avaliar uma 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=1As observações chegam à política como observation.images.<camera> e observation.state; --rename_map as mapeia para os nomes com os quais o checkpoint foi treinado.
Dirija-o como um robô
O mesmo ambiente é um robô: --robot.type=sim, com as opções de ambiente em --robot.env.*. Teleopere-o com um braço líder SO-101 real, da mesma forma que faria com o 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 aceita as mesmas opções para gravar um conjunto de dados, e lerobot-rollout para executar uma política. O conjunto de dados grava o corpo que o ambiente declara, aqui so_follower, como um seguidor real faria. Consulte Executar um robô simulado para episódios, taxas e gravação.
Execute local
Sem --env.server.endpoint (ou --robot.env.server.endpoint), o ambiente é executado no seu processo. Instale o requirements.txt ao lado do LeRobot e adicione --env.trust_remote_code=true (--robot.env.trust_remote_code=true): o seu processo executa o env.py do repositório. Quando servido, o seu processo nunca o executa, portanto o cliente não precisa de consentimento: o --trust_remote_code=true do servidor cobre isso.
De uma pasta local
Uma pasta que contém env.py funciona em qualquer lugar em que um repositório do Hub funciona, seja para um ambiente que você está escrevendo ou para um clone que você leu: --env.hub_path=./my-env, --robot.env.hub_path=./my-env, --envhub=./my-env. É necessário o mesmo consentimento, pois, no fim das contas, é código. Para servi-lo sem construir uma imagem, remova --docker=true: o servidor então roda no seu ambiente Python atual, com o requirements.txt da pasta instalado nele.
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 folderCriar um ambiente
O repositório
| Arquivo | Obrigatório | Conteúdo |
|---|---|---|
env.py | sim | make_env, o ambiente e, opcionalmente, LEROBOT_SIM |
requirements.txt | não | Pacotes Python necessários para env.py, instalados na imagem do servidor |
packages.txt | não | Pacotes do Ubuntu, um por linha, instalados na imagem do servidor |
README.md | sim | O que o ambiente simula, suas observações, ações, tarefa, recompensas e término de episódio, os comandos para executá-lo, suas licenças |
| qualquer outra coisa | não | Cenas, modelos de robôs, texturas, configurações: env.py os encontra ao seu lado, em todos os modos |
Crie-o como um repositório de modelo no Hub.
Python e dependências
LeRobot requer Python 3.12 ou mais novo, e o seu ambiente também: localmente, env.py é executado no processo do LeRobot, e a imagem do servidor executa o Python 3.12 do Ubuntu 24.04. Um simulador que só suporta uma versão anterior do Python (por exemplo, Isaac Sim 5 e Isaac Lab 2, no Python 3.11) não funciona de nenhuma das formas; use uma versão que suporte Python 3.12 (Isaac Sim 6 e Isaac Lab 3, como o RoboLab faz).
A imagem do servidor contém apenas o que o servidor precisa: nem o torch nem o restante do LeRobot. Liste tudo o que env.py importa em requirements.txt, incluindo o torch, se o seu simulador precisar dele, e fixe as versões.
make_env
env.py deve definir make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs), que retorna {suite_name: {task_id: vector_env}}, cada vector env contendo n_envs ambientes daquela tarefa:
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)}}- Construa cada env vetorial a partir de fábricas por ambiente, conforme acima, e retorne-o sem embrulhar: o LeRobot assume as fábricas e executa os ambientes por conta própria (veja Batches). Um wrapper vetorial personalizado ou uma subclasse é rejeitado em vez de ser descartado silenciosamente. Um único
gym.Envtambém é aceito, como um único conjunto com ID de tarefa 0. - Vários conjuntos ou IDs de tarefa compõem um benchmark multitarefa:
lerobot-evalrelata uma taxa de sucesso por tarefa, por conjunto e no geral. Um robô de simulação executa o conjunto nomeado por--robot.env.task(o primeiro por padrão) e a tarefa indicada por--robot.task_id. kwargssão as opções próprias do ambiente. Os usuários as passam com--env.make_env_kwargs='{"episode_length": 900}'(--robot.env.make_env_kwargspara um robô simulado); um servidor as recebe com--sim.kwargs='{make_env_kwargs: {episode_length: 900}}'.env.pyé importado uma vez por processo, portanto, pode manter estado em nível de processo, como um aplicativo de simulador que só pode ser iniciado uma vez (oSimulationAppdo Isaac Sim).
O ambiente
Cada ambiente é um gym.Env que segue estas convenções. Um ambiente Gymnasium padrão geralmente não as segue: a observação do CartPole é um vetor plano e sua ação é discreta, portanto o LeRobot o rejeita. Envolver um ambiente assim para retornar este dicionário de observação e uma ação contínua Box.
| O quê | Contrato |
|---|---|
| Observação | Um dicionário de arrays NumPy: pixels (uma imagem RGB HWC uint8, ou um dicionário delas, uma por câmera), agent_pos (o estado do robô) e, opcionalmente, environment_state. Outros arrays são passados |
| Ação | Uma Box contínua unidimensional |
task_description | A instrução de idioma fornecida à política (usa task como alternativa) |
_max_episode_steps | O limite de passos, após o qual o LeRobot truncará o episódio (500, se ausente) |
retorno de step() | terminated quando o episódio termina (sucesso ou falha), truncated quando é interrompido |
info["is_success"] | Se a tarefa é concluída, a cada step() |
info["metrics"] | Opcional: outros números para relatar, {name: float}; lerobot-eval os mantém por episódio, obtidos no passo em que ele terminou |
LeRobot mapeia a observação para observation.images.<camera> (observation.image para uma única imagem sem nome), observation.state e observation.environment_state. Converta as saídas do seu simulador para essas convenções dentro do ambiente: imagens da câmera na posição vertical, estado nas unidades e na ordem das suas ações onde elas compartilham juntas.
Se o seu simulador alocar contextos de GPU ou EGL, crie-os no primeiro reset() em vez de em __init__, para que um ambiente construído em um processo de worker não herde handles obsoletos.
LEROBOT_SIM
Um dicionário em nível de módulo em env.py que descreve o ambiente. Ele se aplica localmente e quando servido, e todas as chaves são opcionais:
| Chave | Significado | Padrão |
|---|---|---|
fps | Taxa de controle: step()s por segundo de tempo simulado | 30 |
control_mode | Convenção de ação: position, delta ou eef_pose | "position" |
semantics | Nome das convenções de observação e ação | "envhub-v1" |
state_names | Nomes dos componentes de observation.state, em ordem | state_0, state_1, … |
action_names | Nomes dos componentes de ação, em ordem | command_0, command_1, … |
robot_type | Corpo simulado, registrado como robot_type dos conjuntos de dados | nenhum (registro de datasets sim_robot) |
Declare-o sempre que os padrões não corresponderem ao seu ambiente. Uma chave desconhecida é um erro, indicando a mais próxima válida. As opções --sim.* de um servidor o substituem, por exemplo, --sim.fps=15.
Para tornar um ambiente um gêmeo de um robô real suportado pelo LeRobot, use os nomes, unidades e robot_type desse robô. Um teleoperador então o dirige da mesma forma que dirige o robô seguidor real, os conjuntos de dados gravados na simulação e no hardware coincidem, e um checkpoint treinado em um funciona no outro. Para um SO-101, isso é shoulder_pan.pos … gripper.pos, em graus, com o garra de 0 a 100, e robot_type: "so_follower". Quando o LeRobot não tem uma classe para o seu robô, escolha um robot_type curto em snake_case (panda, sawyer).
Um exemplo completo
Um ponto para se mover até um alvo, sem dependências além de Gymnasium e NumPy. Ele atende a tudo o que foi mencionado acima; copie-o como ponto 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 um simulador real, consulte lerobot/so101-tabletop-mujoco (MuJoCo) e lerobot/so101-tabletop-isaac (Isaac Sim, instalado por meio de requirements.txt e packages.txt). Eles servem a mesma cena SO-101 com as mesmas observações, ações e LEROBOT_SIM, de modo que as mesmas políticas e comandos funcionam em ambos. Há mais na coleção de ambientes do EnvHub.
Lotes
lerobot-eval --eval.batch_size=N executa N ambientes de uma tarefa ao mesmo tempo, e make_env recebe n_envs=N; um robô de simulação executa um. Um lote é processado de uma das duas maneiras.
LeRobot executa um passo em um lote de ambientes únicos, o padrão e o que a maioria dos simuladores precisa (MuJoCo, PyBullet, …). Escreva um gym.Env que simule um único ambiente e retorne n_envs fábricas dele de make_env, como acima. O LeRobot constrói os ambientes a partir das fábricas: com --eval.use_async_envs=true (o padrão), cada um roda em seu próprio processo de worker e o lote executa os passos em paralelo; com false, todos rodam em um único processo, um após o outro. O LeRobot usa apenas as fábricas, então não faz diferença em qual classe vetorial make_env as constrói.
Seu simulador executa o passo para o lote inteiro, quando ele mantém todos os ambientes em um único mundo e os avança de uma vez, como os simuladores de GPU, como o Isaac Lab. Defina também vector_env_fns em env.py, retornando uma fábrica por tarefa, cada uma construindo um ambiente vetorial de n_envs ambientes; o LeRobot então o usa no 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 env vetorial deve ter num_envs == n_envs e não deve fazer autoreset (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED). Ele retorna observações em lote no formato acima, recebe uma seed por ambiente em reset(seed=[...]) e relata info["is_success"] por ambiente. --env.make_env_kwargs são passados para ele. Como ele já executa o passo para o lote inteiro, avalie com --eval.use_async_envs=false: um processo de worker apenas copiaria cada lote entre processos, e um servidor construiria o simulador uma segunda vez, no worker.
vector_env_fns também é adequado para um benchmark com muitas tarefas: make_env constrói os ambientes de todas as tarefas quando é chamado, enquanto apenas as fábricas das tarefas que são executadas são chamadas.
Teste antes de publicar
Cada etapa usa a pasta local que contém env.py no lugar de um repositório do Hub.
Construa os ambientes como o LeRobot faz e verifique as chaves de observação, formas e tarefa:
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()Verifique como um robô: os nomes de estado e ação, e as visões da câmera:
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()Com um teleoperador cujas ações correspondem às suas,
lerobot-teleoperate --robot.type=sim --robot.env.type=envhub --robot.env.hub_path=./my-env --robot.env.trust_remote_code=true ... --display_data=trueexibe as câmeras no Rerun enquanto você o controla.Sirva-o a partir da pasta, o que constrói a imagem a partir do seu
requirements.txtepackages.txt, e em seguida execute as mesmas verificações contra ele com--env.server.endpoint=tcp/127.0.0.1:7448:lerobot-env-server --envhub=./my-env --trust_remote_code=true --docker=true--build=truereconstrói apenas o que mudou: os pacotes apt quandopackages.txtmuda, os requisitos quandorequirements.txtmuda e, caso contrário, apenas os arquivos do repositório.
Publicar
Envie a pasta para um repositório de modelos no Hub, em seguida:
- Observe o commit e use-o nos comandos do seu README: os usuários executam exatamente o que você testou.
- Especifique no README as licenças de tudo que o repositório inclui (modelos de robôs, cenas, texturas) e um resultado de referência, se houver: um checkpoint, sua revisão, o comando
lerobot-evale a taxa de sucesso obtida. - Adicione
tags: [lerobot, envhub]aos metadados do README para que o ambiente possa ser encontrado no Hub. - Para que ele seja listado na coleção de ambientes do EnvHub, abra uma issue no GitHub do LeRobot com um link para o repositório.
Atualizações são novos commits: usuários fixados em um commit anterior continuam executando o código que revisaram.
Referência
Caminhos do Hub
--env.hub_path (e --envhub para o servidor) aceitam:
| Padrão | Carregamentos | Exemplo |
|---|---|---|
user/repo | env.py da branch principal | lerobot/so101-tabletop-mujoco |
user/repo@revision | env.py em um commit, branch ou tag | lerobot/so101-tabletop-mujoco@4684f500b94d07194f2c860314c4e27cb9349e8c |
user/repo:path | Outro arquivo | my-org/my-envs:envs/task_a.py |
user/repo@rev:path | Outro arquivo em uma revisão | my-org/my-envs@v1.0:envs/task_a.py |
./folder | env.py em uma pasta local | ./my-env |
Versões
As versões de um ambiente são seus commits no Hub. Uma revisão após @ (um commit, um branch ou uma tag) seleciona uma delas, no seu processo e no servidor:
- No seu processo, o repositório naquela revisão é baixado e armazenado em cache. Sem uma revisão, cada execução segue o commit mais recente de
main. - No servidor,
--envhub=user/repo@<revision>constrói a imagem a partir dos arquivos daquela revisão, e cada revisão recebe sua própria imagem. Sem uma revisão, a imagem contém o commit que era o mais recente no momento da construção, até que--build=truea reconstrua a partir do mais recente. - Marque as liberações para que os usuários possam fixar um nome em vez de um hash, e mantenha
mainpara desenvolvimento. Fixe um commit para artigos e comparações: diferentemente de uma tag ou de um branch, ele não pode se mover.
Opções
| Opção | Significado |
|---|---|
--env.type=envhub | Um ambiente do EnvHub (--robot.env.type=envhub para um robô de simulação) |
--env.hub_path | O repositório, veja caminhos do Hub |
--env.trust_remote_code | Consentir a execução do código do repositório no seu processo; não é necessário quando servido |
lerobot-env-server --trust_remote_code=true | Consentir com a execução do código do repositório no servidor, necessário para servi-lo, a partir de --envhub ou de um YAML |
--env.make_env_kwargs | Argumentos de palavra-chave para make_env; quando servido, defina-os no servidor |
--env.server.endpoint | Execute o ambiente em um servidor de ambiente; consulte Simulation para as outras opções de servidor |
lerobot-env-server --envhub=<path> | Serve um repositório; com --docker=true, em uma imagem construída a partir dele |
lerobot-env-server --sim.kwargs=... | As opções make_env do servidor, por exemplo, '{make_env_kwargs: {episode_length: 900}}' |
lerobot-env-server --sim.<key>=... | Substitua um valor de LEROBOT_SIM, por exemplo, --sim.fps=15 |
Segurança
Executar um ambiente do EnvHub executa seu código, com suas permissões. O LeRobot nunca o executa sem seu consentimento explícito: trust_remote_code em seu processo, --trust_remote_code=true no servidor. Antes de concedê-lo:
- Leia
env.py,requirements.txtepackages.txt. - Fixe o commit que você leu.
- Prefira servi-lo: em seu contêiner, o código vê sua imagem e a configuração do servidor, não seus arquivos. O contêiner compartilha a rede do seu host.
Solução de problemas
| Erro | Corrigir |
|---|---|
Refusing to run the EnvHub environment | Adicione --env.trust_remote_code=true (--robot.env.trust_remote_code=true) após ler o código, ou sirva o ambiente |
failed to import because the dependency '<name>' is not installed | Instale o requirements.txt do repositório ao lado do LeRobot, ou sirva o ambiente |
requires an unwrapped SyncVectorEnv or AsyncVectorEnv | Retorna o env vetorial construído a partir de fábricas, sem wrappers |
LEROBOT_SIM has unknown keys | Use as chaves listadas em LEROBOT_SIM; o erro indica a mais próxima |
The env server at ... runs another environment than this command describes | O servidor executa um ambiente diferente do que --env.* descreve; passe as mesmas opções ou reinicie o servidor com as suas |
A sim robot needs an observation.state feature with component names | Retorne agent_pos na observação |
images must be HWC uint8 with three channels | Converta as imagens da câmera para altura x largura x 3, uint8 |