LeRobot documentation

EnvHub: Compartilhe um simulador no Hub

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

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-teleoperate e lerobot-replay, substituível pelo robô real que ele simula,
  • executá-lo localmente, em seu próprio ambiente Python, ou servido por lerobot-env-server em 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=true

Isso 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=1

As 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=true

lerobot-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 folder

Criar um ambiente

O repositório

ArquivoObrigatórioConteúdo
env.pysimmake_env, o ambiente e, opcionalmente, LEROBOT_SIM
requirements.txtnãoPacotes Python necessários para env.py, instalados na imagem do servidor
packages.txtnãoPacotes do Ubuntu, um por linha, instalados na imagem do servidor
README.mdsimO 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 coisanãoCenas, 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.Env também é aceito, como um único conjunto com ID de tarefa 0.
  • Vários conjuntos ou IDs de tarefa compõem um benchmark multitarefa: lerobot-eval relata 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.
  • kwargs sã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_kwargs para 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 (o SimulationApp do 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çãoUm 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çãoUma Box contínua unidimensional
task_descriptionA instrução de idioma fornecida à política (usa task como alternativa)
_max_episode_stepsO 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:

ChaveSignificadoPadrão
fpsTaxa de controle: step()s por segundo de tempo simulado30
control_modeConvenção de ação: position, delta ou eef_pose"position"
semanticsNome das convenções de observação e ação"envhub-v1"
state_namesNomes dos componentes de observation.state, em ordemstate_0, state_1, …
action_namesNomes dos componentes de ação, em ordemcommand_0, command_1, …
robot_typeCorpo simulado, registrado como robot_type dos conjuntos de dadosnenhum (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.

  1. 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()
  2. 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=true exibe as câmeras no Rerun enquanto você o controla.

  3. Sirva-o a partir da pasta, o que constrói a imagem a partir do seu requirements.txt e packages.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=true reconstrói apenas o que mudou: os pacotes apt quando packages.txt muda, os requisitos quando requirements.txt muda 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-eval e 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ãoCarregamentosExemplo
user/repoenv.py da branch principallerobot/so101-tabletop-mujoco
user/repo@revisionenv.py em um commit, branch ou taglerobot/so101-tabletop-mujoco@4684f500b94d07194f2c860314c4e27cb9349e8c
user/repo:pathOutro arquivomy-org/my-envs:envs/task_a.py
user/repo@rev:pathOutro arquivo em uma revisãomy-org/my-envs@v1.0:envs/task_a.py
./folderenv.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=true a 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 main para 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çãoSignificado
--env.type=envhubUm ambiente do EnvHub (--robot.env.type=envhub para um robô de simulação)
--env.hub_pathO repositório, veja caminhos do Hub
--env.trust_remote_codeConsentir a execução do código do repositório no seu processo; não é necessário quando servido
lerobot-env-server --trust_remote_code=trueConsentir 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_kwargsArgumentos de palavra-chave para make_env; quando servido, defina-os no servidor
--env.server.endpointExecute 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:

  1. Leia env.py, requirements.txt e packages.txt.
  2. Fixe o commit que você leu.
  3. 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

ErroCorrigir
Refusing to run the EnvHub environmentAdicione --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 installedInstale o requirements.txt do repositório ao lado do LeRobot, ou sirva o ambiente
requires an unwrapped SyncVectorEnv or AsyncVectorEnvRetorna o env vetorial construído a partir de fábricas, sem wrappers
LEROBOT_SIM has unknown keysUse as chaves listadas em LEROBOT_SIM; o erro indica a mais próxima
The env server at ... runs another environment than this command describesO 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 namesRetorne agent_pos na observação
images must be HWC uint8 with three channelsConverta as imagens da câmera para altura x largura x 3, uint8
Update on GitHub