LeRobot documentation

Simulação

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

Simulação

Um simulador no LeRobot é um ambiente Gymnasium que segue as convenções do LeRobot (observações em dicionário com imagens de câmera e estado do robô, ações contínuas, sucesso em info["is_success"]; veja O ambiente), escrito uma vez e usado em todos os lugares onde o LeRobot executa um robô:

  • para avaliar uma política, como um batched env (--env.*): muitos ambientes de uma única tarefa, executados em conjunto. lerobot-eval e a avaliação durante o treinamento usam isso.
  • como um robô simulado (--robot.type=sim --robot.env.*): um ambiente por trás da interface Robot, substituível por hardware real. lerobot-rollout, lerobot-record, lerobot-teleoperate e lerobot-replay o utilizam.

Executa localmente, no seu ambiente Python, ou servido por lerobot-env-server, geralmente em sua própria imagem Docker, para que as dependências do simulador nunca se encontrem com as da política. Definir um endpoint seleciona a execução servida; ambos os caminhos fornecem à política as mesmas observações (imagens uint8 HWC, estado float32 plano), os mesmos fins de episódio e as mesmas convenções de controle.

LocalmenteServido
Ambiente em lote: lerobot-eval--env.type=<sim>--env.type=<sim> --env.server.endpoint=tcp/...
Simulador de robô: lerobot-rollout, -record, -teleoperate, -replay--robot.type=sim --robot.env.type=<sim>--robot.type=sim --robot.env.type=<sim> --robot.env.server.endpoint=tcp/...
Instalaro simulador, ao lado do LeRobot (o extra dele)lerobot[remote]; o simulador fica na imagem do servidor
ParaLer
Avaliar, registrar ou teleoperar em simulaçãoesta página, e a própria página do simulador (LIBERO, Meta-World, …)
Use ou publique um simulador do Hugging Face HubEnvHub
Adicione um benchmark que o LeRobot mantém em seu CIAdicionando um benchmark

Avaliar um checkpoint

Localmente, com o simulador instalado ao lado do LeRobot (veja 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: inicie o servidor com o mesmo ambiente (veja Servir um ambiente) e adicione seu endpoint:

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

Um ambiente EnvHub funciona da mesma maneira, com --env.type=envhub --env.hub_path=<user/repo>, servido com lerobot-env-server --envhub=<user/repo> --trust_remote_code=true --docker=true depois que você tiver lido seu código.

Todas as opções do servidor estão sob --env.server.*, e nenhuma se aplica a uma execução local. O cliente solicita o deployment nomeado conforme --env.type, como as configurações do servidor o nomeiam; passe --env.server.deployment para outro. Um endpoint ou deployment incorreto falha dentro de --env.server.handshake_timeout_s (10 s) e indica o que o endpoint serve. Contra um servidor protegido com TLS, passe seu arquivo Zenoh JSON5 com --env.server.zenoh_config_path, como para inferência remota. O servidor deve executar o ambiente descrito pelo comando: o mesmo type, task, convenções de controle e corpo simulado (robot_type), ou a avaliação se recusa a iniciar e lista as diferenças. Outras opções que diferem (resolução, comprimento do episódio) são registradas como avisos.

Os nomes das observações vêm do ambiente (observation.images.<camera>, observation.state). Quando um checkpoint foi treinado com outros nomes de câmeras, mapeie-os com --rename_map, como para qualquer robô, e preserve a identidade de cada câmera, mesmo quando várias têm o mesmo formato. Câmeras de preenchimento (empty_cameras) são uma configuração de política salva com o checkpoint; substitua-a com --policy.empty_cameras apenas quando necessário.

Antes do primeiro passo, cada checkpoint de entrada deve existir no ambiente após a renomeação, com dimensões de estado e ação compatíveis e o mesmo número de canais RGB. A altura e a largura da imagem podem diferir: o pré-processamento da política é responsável pelo redimensionamento. As convenções do controlador (ações delta versus absolutas, formato de rotação) não são verificadas; utilize um checkpoint treinado com a convenção do ambiente.

Lotes e throughput servido

Cada step() avança uma vez todos os ambientes não finalizados no lote. Um ambiente que termina mantém sua observação terminal até o próximo reset; avançar os outros nunca o reinicia. Com --eval.use_async_envs=true (o padrão), cada ambiente é executado em seu próprio processo de worker, localmente ou no servidor, e o lote avança em paralelo. Um servidor aceita até max_envs ambientes por lote (32 por padrão).

--env.server.encoding=jpeg (ou --robot.env.server.encoding=jpeg, com --env.server.jpeg_quality, 90 por padrão) envia os quadros da câmera servidos como JPEG: respostas menores para um servidor remoto e lotes maiores, ao custo de tempo de codificação e quadros com perda. No localhost, os quadros brutos são mais rápidos.

A resposta contém os frames de todos os ambientes no lote e deve caber em max_payload_bytes (32 MiB por padrão) em ambas as extremidades, ou o servidor recusará o lote ao abri-lo. Para lotes grandes ou câmeras de alta resolução, aumente esse valor no servidor (max_payload_bytes na seção zenoh do YAML, ao lado de listen_endpoints) e no cliente (--env.server.max_payload_bytes, ou --robot.env.server.max_payload_bytes).

Executar um robô de simulação

O mesmo ambiente como um ambiente em lote e como um robô de simulação:

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 exemplo:

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.* aceita as mesmas opções de --env.* na avaliação. --robot.task_id seleciona a única tarefa que o robô executa, enquanto a avaliação executa todas as tarefas da suíte ou aquelas em --env.task_ids. Os ambientes do EnvHub são --robot.env.type=envhub --robot.env.hub_path=<user/repo>, com --robot.env.trust_remote_code=true para executá-los localmente.
  • --robot.env.server.endpoint=tcp/... executa o ambiente em um servidor de ambiente, assim como --env.server.endpoint faz para um ambiente em lote. O robô verifica se o servidor executa esse ambiente.
  • Cada send_action() avança o ambiente exatamente uma vez. Leitura de observações, inferência da política e espera não avançam a simulação; o loop de controle existente é responsável pelo ritmo em tempo real.
  • --fps deve ser igual à taxa de controle do ambiente, dividida por --interpolation_multiplier ao interpolar, pois cada comando avança o ambiente uma vez. Ao gravar, --dataset.fps deve ser igual a --fps. Caso contrário, o rollout se recusa a iniciar.

Um robô de simulação é um robô: substitua --robot.type=sim --robot.env.* pelos parâmetros --robot.* do seguidor real, e o restante permanece inalterado. Um teleoperador o controla da mesma forma que controla o seguidor real (--teleop.type=so101_leader para um gêmeo SO-101, como lerobot/so101-tabletop-mujoco), quando o ambiente declara os nomes e as unidades das ações do seguidor; uma incompatibilidade é reportada na primeira ação.

Os recursos da câmera do robô usam os mesmos nomes observation.images.<camera> que a gravação em hardware real. Uma única câmera sem nome é observation.images.image. A avaliação em lote mantém as próprias chaves do ambiente, como observation.image para uma única câmera; ao implantar um checkpoint com esse nome por meio de um robô de simulação, use --rename_map='{"observation.images.image": "observation.image"}'.

Quando a política está atrasada, manter um robô de simulação não avança a física. Falhas no simulador propagam-se para o encerramento do rollout.

Registrar na simulação

lerobot-record armazena o corpo que o ambiente declara como robot_type do conjunto de dados (panda para LIBERO, so_follower para um gêmeo SO-101) ou sim_robot quando não declara nenhum.

Os episódios gravados seguem o do ambiente. lerobot-record e a estratégia de rollout episódico reiniciam o ambiente simulado no início de cada episódio e o encerram quando o episódio do ambiente termina (sucesso, término ou seu limite de passos) ou quando sua duração se esgota, o que ocorrer primeiro. Cada episódio gravado é, portanto, um episódio simulado, a partir de seu estado inicial. Nada precisa ser reiniciado manualmente, então pule a fase de reset entre episódios com --dataset.reset_time_s=0 e, com a estratégia de rollout episódico, também passe --strategy.reset_to_initial_position=false.

Quando um episódio termina, o robô para: ele ignora as ações e mantém seu estado final, e latest mantém a recompensa final, a terminação e o sucesso. A teleoperação e a estratégia de rollout base então iniciam um novo episódio (a estratégia também reinicia a política), e o replay para. Para gravar com uma política, use a estratégia de rollout episódica. Robôs reais não são afetados: seus episódios são cronometrados e sua cena é reiniciada manualmente. Para taxas de sucesso, avalie com lerobot-eval e um env em lote.

Inferência remota

Mantenha as mesmas opções --robot.* e substitua as opções de política local e inferência por:

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

Inicie o servidor de política separadamente usando remote inference setup. Seu schema deve corresponder às observações do robô após --rename_map. Omita --policy.path do comando de rollout, pois o servidor de política carrega o checkpoint. Para RTC local, use --inference.type=rtc com as configurações de RTC da política.

Servir um ambiente

A partir de um checkout da fonte do LeRobot (a imagem é construída a partir dele), execute a partir da raiz do repositório:

# 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 usa docker/sim/compose.server.yaml, seleciona a imagem a partir de sim.type (ou constrói uma a partir do repositório EnvHub), monta o YAML efetivo e executa o container na rede do host, de modo que o servidor escuta em localhost:7448, a menos que --zenoh.listen_endpoints indique o contrário. Troque o YAML para selecionar outro simulador. A taxa de controle, a convenção de ação, os nomes dos componentes e o tipo de robô de cada simulador vêm do conventions() da sua integração (o LEROBOT_SIM de um repositório EnvHub), de modo que o YAML apenas nomeia a tarefa e as opções do simulador.

No que diz respeito ao lerobot-policy-server, cada campo YAML aceita uma substituição aninhada na linha de comando, e o arquivo permanece inalterado. Um valor de dicionário como sim.kwargs é mesclado ao do 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}}'

A configuração efetiva é mantida em $HF_LEROBOT_HOME/sim, de modo que um container reiniciado a encontre. Alterar a configuração recria o servidor e encerra as sessões ativas. A imagem é construída quando ausente; adicione --build=true para reconstruí-la após alterar o simulador ou o código-fonte do LeRobot, ou --stop=true para desligar o servidor. O container requer acesso à GPU do Docker para renderização EGL.

Se um simulador que renderiza com Vulkan (Isaac Sim, ou ManiSkill/SAPIEN como em RoboMME, cuja imagem inclui seu próprio arquivo Vulkan) falhar no contêiner com vkCreateInstance failed ou ERROR_INCOMPATIBLE_DRIVER enquanto funciona fora do Docker, o contêiner possui as bibliotecas do driver da NVIDIA, mas não os arquivos de loader que apontam para elas (/usr/share/vulkan/icd.d/nvidia_icd.json, /usr/share/glvnd/egl_vendor.d/10_nvidia.json). O modo padrão do NVIDIA Container Toolkit, usado por gpus: all, pode não montá-los; seu modo CDI sim. Solicite a GPU através do CDI (--device nvidia.com/gpu=all para docker run, devices: [nvidia.com/gpu=all] no lugar de gpus: all em docker/sim/compose.server.yaml), ou adicione os dois arquivos à imagem.

Sem --docker=true, o mesmo comando executa o servidor no ambiente atual: instale as dependências nativas do simulador em um ambiente isolado com Python 3.12 ou mais novo, instale o LeRobot com --no-deps e instale docker/sim/requirements.txt. O servidor faz parte do LeRobot, portanto precisa do mesmo Python que o LeRobot; um simulador que só suporta um Python mais antigo não pode ser servido.

Onde o servidor é executado

Por padrão, o servidor aceita conexões apenas da própria máquina, pois a conexão não é criptografada nem autenticada: qualquer pessoa que acesse pode controlar o ambiente. Para executá-lo em outra máquina, como uma estação de trabalho ou uma instância em nuvem com GPU, enquanto a política roda na sua, passe o endereço da interface de rede que a sua alcança com --zenoh.listen_endpoints='[tcp/<address>:7448]' e conecte-se com --env.server.endpoint=tcp/<address>:7448 (--robot.env.server.endpoint para um robô simulado). Mantenha isso em uma rede confiável ou adicione TLS e controle de acesso com um zenoh.config_file no YAML do servidor e --env.server.zenoh_config_path no cliente, como para inferência remota. Em um link mais lento, quadros JPEG exigem menos largura de banda.

As solicitações do servidor nunca são repetidas. Após um tempo limite ambíguo, o cliente falha; feche-o e abra uma nova sessão.

Adicionar um simulador

Para compartilhar um ambiente próprio, publique-o no Hub como um ambiente EnvHub: um env.py em um repositório do Hub é toda a integração necessária, e ele obtém tudo nesta página. Os benchmarks que o LeRobot mantém e testa em seu CI, com um checkpoint fixado e um estágio Docker, são adicionados ao próprio LeRobot: veja Adicionando um benchmark.

Update on GitHub