Carregando Ambientes do Hub

O recurso EnvHub permite carregar ambientes de simulação diretamente do Hugging Face Hub com uma única linha de código. Isso libera um novo e poderoso modelo de colaboração: em vez de os ambientes ficarem trancados dentro de bibliotecas monolíticas, qualquer pessoa pode publicar ambientes personalizados e compartilhá-los com a comunidade.

O que é o EnvHub?

O EnvHub permite criar ambientes de simulação de robótica personalizados com seus próprios modelos de robôs e cenários, e torná-los facilmente utilizáveis por qualquer pessoa por meio do framework LeRobot.

Os pacotes do EnvHub são armazenados no Hugging Face Hub e podem ser obtidos e usados de forma transparente em seus projetos de robótica de IA por meio do LeRobot com uma única linha de código.

Graças ao EnvHub, você pode:

1. Crie e publique ambientes no Hugging Face Hub como repositórios Git e distribua simulações físicas complexas sem a burocracia de empacotamento
2. Carregar ambientes dinamicamente, sem instalá-los como pacotes
3. Versionar e rastrear alterações de ambiente usando semântica do Git
4. Descubra novas tarefas de simulação compartilhadas pela comunidade

Esse design significa que você pode ir da descoberta de um ambiente interessante no Hub para a execução de experimentos em segundos, ou criar seu próprio robô e ambiente personalizados sem se preocupar com conflitos de dependências ou procedimentos de instalação complexos.

Ao criar um pacote do EnvHub, você pode construir o que quiser dentro dele e usar qualquer ferramenta de simulação que preferir: este é o seu próprio espaço para experimentar. O único requisito é que o pacote contenha um arquivo env.py que defina o ambiente e permita que o LeRobot carregue e utilize seu pacote do EnvHub.

Este arquivo env.py precisa expor uma pequena API para que o LeRobot possa carregá-lo e executá-lo. Em particular, você deve fornecer uma função make_env(n_envs: int = 1, use_async_envs: bool = False), que é o ponto de entrada principal para o LeRobot. O LeRobot a chama sem uma configuração, localmente e quando servido. Ela deve retornar um dos seguintes:

• A gym.vector.VectorEnv (mais comum)
• Um único gym.Env (será automaticamente envolvido)
• Um dicionário mapeando {suite_name: {task_id: VectorEnv}} (para benchmarks de múltiplas tarefas)

Por padrão, um vector env retornado deve ser um SyncVectorEnv ou AsyncVectorEnv sem wrappers: o LeRobot pega seus env_fns e constrói cada ambiente por conta própria. Wrappers de vetor personalizados e subclasses são rejeitados em vez de serem removidos silenciosamente.

Para wrappers de vetores pertencentes ao provedor ou lotes nativos de GPU, use --env.use_native_batch=true. Isso mantém o ambiente de vetores do repositório intacto para avaliação em lote local, incluindo seus requisitos de pré-processamento. Não pode ser combinado com um endpoint ou SimRobot. A API de string (make_env("user/repo")) também mantém o ambiente do provedor intacto.

env.py também pode definir um dicionário opcional LEROBOT_SIM descrevendo o ambiente (fps, control_mode, nomes dos componentes; veja EnvHub e o servidor do simulador). Ele se aplica localmente e quando servido.

Início rápido

Carregar um ambiente do Hub é tão simples quanto:

from lerobot.envs import make_env

# Load a hub environment (requires explicit consent to run remote code)
env = make_env("lerobot/cartpole-env", trust_remote_code=True)

**Security Notice**: Loading environments from the Hub executes Python code from third-party repositories. Only use `trust_remote_code=True` with repositories you trust. We strongly recommend pinning to a specific commit hash for reproducibility and security.

Estrutura do Repositório

Para que seu ambiente seja carregável do Hub, seu repositório deve conter, no mínimo:

Arquivos obrigatórios

env.py (ou arquivo Python personalizado)

• Deve expor uma função make_env(n_envs: int, use_async_envs: bool)
• Os argumentos de palavra-chave extras de make_env são as próprias opções do ambiente: --env.make_env_kwargs='{"episode_length": 900}' os passa (--robot.env.make_env_kwargs para um robô simulado), e um servidor os recebe com --sim.kwargs='{make_env_kwargs: {episode_length: 900}}'
• Esta função deve retornar um dos seguintes:
  • A gym.vector.VectorEnv (mais comum)
  • Um único gym.Env (será automaticamente envolvido)
  • Um dicionário mapeando {suite_name: {task_id: VectorEnv}} (para benchmarks de múltiplas tarefas)

Arquivos Opcionais

requirements.txt

• Liste quaisquer dependências adicionais que seu ambiente precisa
• Os usuários precisarão instalar esses manualmente antes de carregar seu ambiente

LEROBOT_SIM em env.py

• Um dicionário em nível de módulo que descreve o ambiente quando ele é servido pelo simulator server, de modo que ele começa com um único comando
• Cada chave é opcional; repositórios sem LEROBOT_SIM continuam funcionando com os padrões
• robot_type é o tipo que o robô real registra (so_follower, omx_follower) quando o lerobot possui uma classe para o corpo, de modo que os conjuntos de dados simulados e reais correspondam

README.md

• Documente seu ambiente: qual tarefa ele implementa, espaços de observação/ação, recompensas, etc.
• Inclua exemplos de uso e quaisquer instruções especiais de configuração

.gitignore

• Exclua arquivos desnecessários do seu repositório

Estrutura de exemplo do repositório

my-environment-repo/
├── env.py                 # Main environment definition (required)
├── requirements.txt       # Dependencies (optional)
├── README.md             # Documentation (recommended)
├── assets/               # Images, videos, etc. (optional)
│   └── demo.gif
└── configs/              # Config files if needed (optional)
    └── task_config.yaml

Criando seu repositório de ambiente

Etapa 1: Defina seu ambiente

Crie um arquivo env.py com uma função make_env:

# env.py
import gymnasium as gym

# Optional: describes the environment to the simulator server (see "Optional Files").
LEROBOT_SIM = {"fps": 50, "control_mode": "position"}

def make_env(n_envs: int = 1, use_async_envs: bool = False):
    """
    Create vectorized environments for your custom task.

    Args:
        n_envs: Number of parallel environments
        use_async_envs: Whether to use AsyncVectorEnv or SyncVectorEnv

    Returns:
        gym.vector.VectorEnv or dict mapping suite names to vectorized envs
    """
    def _make_single_env():
        # Create your custom environment
        return gym.make("CartPole-v1")

    # Choose vector environment type
    env_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv

    # Create vectorized environment
    vec_env = env_cls([_make_single_env for _ in range(n_envs)])

    return vec_env

Etapa 2: Teste localmente

Antes de fazer o upload, teste seu ambiente localmente:

import numpy as np

from lerobot.envs.configs import HubEnvConfig

# Build the envs from the local folder that holds env.py, as lerobot-eval and the env server do
envs = HubEnvConfig(hub_path="./my-env", trust_remote_code=True).create_envs(n_envs=2)

# Verify it works
suite_name = next(iter(envs))
env = envs[suite_name][0]
obs, info = env.reset(seed=0)
print({key: value.shape for key, value in obs.items()})  # LeRobot keys, e.g. observation.state
env.step(np.zeros(env.action_space.shape, np.float32))
env.close()

Etapa 3: Enviar para o Hub

Envie seu repositório para o Hugging Face:

# Install huggingface_hub if needed
pip install huggingface_hub

# Login to Hugging Face
hf auth login

# Create a new repository
hf repos create my-org/my-custom-env

# Initialize git and push
git init
git add .
git commit -m "Initial environment implementation"
git remote add origin https://huggingface.co/my-org/my-custom-env
git push -u origin main

Alternativamente, use a API Python huggingface_hub:

from huggingface_hub import HfApi

api = HfApi()

# Create repository
api.create_repo("my-custom-env", repo_type="space")

# Upload files
api.upload_folder(
    folder_path="./my-env-folder",
    repo_id="username/my-custom-env",
    repo_type="space",
)

Carregando Ambientes do Hub

Uso Básico

from lerobot.envs import make_env

# Load from the hub
envs_dict = make_env(
    "username/my-custom-env",
    n_envs=4,
    trust_remote_code=True
)

# Access the environment
suite_name = next(iter(envs_dict))
env = envs_dict[suite_name][0]

# Use it like any gym environment
obs, info = env.reset()
action = env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)

Avançado: Fixação em Versões Específicas

Para reprodutibilidade e segurança, fixe em uma revisão Git específica:

# Pin to a specific branch
env = make_env("username/my-env@main", trust_remote_code=True)

# Pin to a specific commit (recommended for papers/experiments)
env = make_env("username/my-env@abc123def456", trust_remote_code=True)

# Pin to a tag
env = make_env("username/my-env@v1.0.0", trust_remote_code=True)

Caminhos de Arquivo Personalizados

Se a definição do seu ambiente não estiver em env.py:

# Load from a custom file
env = make_env("username/my-env:custom_env.py", trust_remote_code=True)

# Combine with version pinning
env = make_env("username/my-env@v1.0:envs/task_a.py", trust_remote_code=True)

Ambientes Assíncronos

Para um melhor desempenho com múltiplos ambientes:

envs_dict = make_env(
    "username/my-env",
    n_envs=8,
    use_async_envs=True,  # Use AsyncVectorEnv for parallel execution
    trust_remote_code=True
)

Referência de Formato de URL

O formato de URL do hub suporta vários padrões:

EnvHub e o servidor do simulador

Por padrão, os ambientes do EnvHub são executados dentro do processo de avaliação: make_env baixa o env.py do repositório e suas dependências são instaladas junto ao LeRobot. Para manter as dependências de um ambiente separadas das da sua política, sirva-o com o simulator server em vez disso. Um único comando constrói uma imagem com o repositório e seu requirements.txt e inicia o servidor:

lerobot-env-server --envhub=username/my-env@<commit> --docker=true

Além do requirements.txt (instalado com as regras do pip, portanto as linhas --extra-index-url funcionam), a imagem instala os pacotes apt listados em um arquivo opcional packages.txt, um por linha, como nos Hugging Face Spaces. A imagem é Ubuntu puro: o driver de GPU vem do host, e as bibliotecas CUDA vêm das rodas Python que as necessitam (torch, Isaac Sim).

Passar --envhub é o consentimento explícito para executar o código do repositório, como trust_remote_code=True. Fixe um commit. Em seguida, avalie em relação a ele como qualquer outro ambiente, adicionando seu endpoint:

lerobot-eval --policy.path=<checkpoint> \
  --env.type=envhub --env.hub_path=username/my-env@<commit> --env.server.endpoint=tcp/127.0.0.1:7448 \
  --rename_map='{"observation.images.front": "observation.images.camera1"}' \
  --eval.n_episodes=10

Sem --env.server.endpoint, o mesmo comando executa o ambiente localmente (com --trust_remote_code=true); um robô de simulação aceita as mesmas opções sob --robot.env.*.

O servidor lê a taxa de controle, a convenção de ação e os nomes dos componentes do LEROBOT_SIM do repositório e usa os valores padrão para tudo que não for declarado. Substitua um valor na linha de comando, que tem precedência sobre o repositório, por exemplo, --sim.fps=15.

Para ser servido, um ambiente deve seguir estas convenções:

• make_env retorna ambientes vetoriais construídos a partir de fábricas por ambiente (SyncVectorEnv/AsyncVectorEnv, como nos exemplos acima) ou um único gym.Env. O servidor constrói seus próprios ambientes a partir dessas fábricas e os fecha quando uma sessão termina.
• env.py é executado uma vez por processo do servidor, 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).
• As observações são os dicionários que o LeRobot lê localmente: pixels (uma única imagem HWC uint8 ou um dicionário de câmeras), agent_pos e environment_state, como arrays NumPy.
• As ações são uma Box contínua unidimensional.
• Os episódios terminam por meio de terminated/truncated ou _max_episode_steps (padrão 500), e info["is_success"] relata o sucesso. O texto da tarefa vem do atributo task_description (ou task) do ambiente.
• LEROBOT_SIM é opcional, mas declare-o sempre que os padrões (30 fps, controle de posição) não corresponderem ao seu ambiente.

Para exemplos, consulte a coleção de ambientes do EnvHub: lerobot/so101-tabletop-mujoco (MuJoCo) e lerobot/so101-tabletop-isaac (Isaac Sim, instalado por meio de requirements.txt e packages.txt) servem a mesma cena SO-101 com as mesmas observações, ações e LEROBOT_SIM.

O repositório é baixado na sua máquina com o seu login do Hugging Face (HF_TOKEN ou hf auth login), então repositórios privados também funcionam, e a construção da imagem nunca vê um token. --envhub também aceita um diretório local contendo env.py, para servir um ambiente antes de enviá-lo: lerobot-env-server --envhub=./my-env --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. Teste um novo ambiente localmente primeiro (veja Etapa 2: Teste Localmente).

Ambientes de Tarefas Múltiplas

Para benchmarks com múltiplas tarefas (como LIBERO), retorne um dicionário aninhado:

def make_env(n_envs: int = 1, use_async_envs: bool = False):
    env_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv

    # Return dict: {suite_name: {task_id: VectorEnv}}
    return {
        "suite_1": {
            0: env_cls([lambda: gym.make("Task1-v0") for _ in range(n_envs)]),
            1: env_cls([lambda: gym.make("Task2-v0") for _ in range(n_envs)]),
        },
        "suite_2": {
            0: env_cls([lambda: gym.make("Task3-v0") for _ in range(n_envs)]),
        }
    }

make_env constrói todas as tarefas quando é chamado. Para um simulador de GPU que processa um lote inteiro em um único mundo (por exemplo, Isaac Lab), ou para um benchmark com muitas tarefas, defina vector_env_fns em env.py em vez disso, como as próprias integrações do LeRobot fazem. Ele retorna fábricas, e apenas as fábricas das tarefas que são executadas são chamadas:

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, não deve fazer autoreset (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED), retorna observações em lote no formato acima, recebe uma seed por env em reset(seed=[...]) e relata info["is_success"] por env. --env.make_env_kwargs são passados para ele, e tanto o lerobot-eval quanto o servidor do simulador o usam no lugar de make_env. Como um env vetorial já executa o passo de todo o lote, avalie com --eval.use_async_envs=false: um processo de worker apenas copiaria cada lote de observações entre processos, e um servidor construiria o simulador uma segunda vez, no worker.

Considerações de Segurança

**Important**: The `trust_remote_code=True` flag is required to execute environment code from the Hub. This is by design for security.

Ao carregar ambientes do Hub:

1. Revise o código primeiro: visite o repositório e inspecione env.py antes de carregar
2. Fixar em commits: Use hashes de commit específicos para reprodutibilidade
3. Verifique as dependências: revise requirements.txt em busca de pacotes suspeitos
4. Use fontes confiáveis: Prefira organizações oficiais ou pesquisadores de renome
5. Sandbox quando necessário: Execute código não confiável em ambientes isolados (contêineres, VMs)

Exemplo de uso seguro:

# ❌ BAD: Loading without inspection
env = make_env("random-user/untrusted-env", trust_remote_code=True)

# ✅ GOOD: Review code, then pin to specific commit
# 1. Visit https://huggingface.co/trusted-org/verified-env
# 2. Review the env.py file
# 3. Copy the commit hash
env = make_env("trusted-org/verified-env@a1b2c3d4", trust_remote_code=True)

Exemplo: CartPole do Hub

Aqui está um exemplo completo usando o ambiente de referência CartPole:

from lerobot.envs import make_env
import numpy as np

# Load the environment
envs_dict = make_env("lerobot/cartpole-env", n_envs=4, trust_remote_code=True)

# Get the vectorized environment
suite_name = next(iter(envs_dict))
env = envs_dict[suite_name][0]

# Run a simple episode
obs, info = env.reset()
done = np.zeros(env.num_envs, dtype=bool)
total_reward = np.zeros(env.num_envs)

while not done.all():
    # Random policy
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    total_reward += reward
    done = terminated | truncated

print(f"Average reward: {total_reward.mean():.2f}")
env.close()

Vantagens do EnvHub

Para Autores de Ambientes

• Distribuição fácil: Não requer empacotamento no PyPI
• Controle de versão: Use Git para versionamento de ambiente
• Iteração rápida: Publique atualizações instantaneamente
• Documentação: O README do Hub é renderizado de forma bela
• Comunidade: Entre em contato diretamente com os usuários do LeRobot

Para Pesquisadores

• Experimentos rápidos: Carregue qualquer ambiente em uma linha
• Reprodutibilidade: Fixar em commits específicos
• Descoberta: Navegue pelos ambientes no Hub
• Sem conflitos: Não é necessário instalar pacotes conflitantes

Para a Comunidade

• Ecossistema em crescimento: Tarefas de simulação mais diversas
• Padronização: API comum make_env
• Colaboração: Faça um fork e melhore ambientes existentes
• Acessibilidade: Reduzir a barreira para compartilhar pesquisas

Solução de problemas

“Recusando-se a executar código remoto”

Você deve passar explicitamente trust_remote_code=True:

env = make_env("user/repo", trust_remote_code=True)

“Módulo X não encontrado”

O ambiente do hub tem dependências que você precisa instalar:

# Check the repo's requirements.txt and install dependencies
pip install gymnasium numpy

“make_env não encontrado no módulo”

Seu env.py deve expor uma função make_env:

def make_env(n_envs: int, use_async_envs: bool):
    # Your implementation
    pass

Environment retorna o tipo incorreto

A função make_env deve retornar:

• Uma gym.vector.VectorEnv, ou
• Um único gym.Env, ou
• Um dicionário {suite_name: {task_id: VectorEnv}}

Boas Práticas

1. Documente seu ambiente: Inclua descrições dos espaços de observação/ação, a estrutura de recompensa e as condições de término no seu README
2. Adicione requirements.txt: Liste todas as dependências com as versões
3. Declare LEROBOT_SIM: Permita que o ambiente seja servido pelo servidor do simulador com um único comando
4. Teste minuciosamente: Verifique se o seu ambiente funciona localmente antes de enviar
5. Use versionamento semântico: Marque as liberações com números de versão
6. Adicionar exemplos: Inclua exemplos de uso no seu README
7. Mantenha simples: minimize as dependências sempre que possível
8. Conceda licença ao seu trabalho: Adicione um arquivo LICENSE para esclarecer os termos de uso

Direções Futuras

O ecossistema EnvHub permite possibilidades empolgantes:

• Física acelerada por GPU: Compartilhe ambientes Isaac Gym ou Brax
• Renderização fotorrealista: Distribua ambientes com gráficos avançados
• Cenários multiagente: Tarefas de interação complexas
• Simuladores do mundo real: Gêmeos digitais de configurações físicas
• Geração procedural: Variações infinitas de tarefas
• Randomização de domínio: Pipelines de DR pré-configurados

À medida que mais pesquisadores e desenvolvedores contribuem, a diversidade e a qualidade dos ambientes disponíveis crescerão, beneficiando toda a comunidade de aprendizado em robótica.

Veja também

• Documentação do Hugging Face Hub
• Documentação do Gymnasium
• Exemplo de Ambiente do Hub