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) ou make_env(n_envs: int = 1, use_async_envs: bool = False, cfg: EnvConfig | None = None), que é o ponto de entrada principal para o LeRobot. 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)

Você também pode passar um objeto EnvConfig para make_env para configurar o ambiente (por exemplo, o número de ambientes, tarefa, nome da câmera, estados iniciais, modo de controle, comprimento do episódio, etc.).

Por fim, seu ambiente deve implementar a interface padrão gym.vector.VectorEnv para funcionar com o LeRobot, incluindo métodos como reset e step.

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)
• 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

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

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:

from lerobot.envs.utils import _load_module_from_path, _call_make_env, _normalize_hub_result

# Load your module
module = _load_module_from_path("./env.py")

# Test the make_env function
result = _call_make_env(module, n_envs=2, use_async_envs=False, cfg=None)
normalized = _normalize_hub_result(result)

# Verify it works
suite_name = next(iter(normalized))
env = normalized[suite_name][0]
obs, info = env.reset()
print(f"Observation shape: {obs.shape if hasattr(obs, 'shape') else type(obs)}")
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 repo 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:

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)]),
        }
    }

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. Teste minuciosamente: Verifique se o seu ambiente funciona localmente antes de enviar
4. Use versionamento semântico: Marque as liberações com números de versão
5. Adicionar exemplos: Inclua exemplos de uso no seu README
6. Mantenha simples: minimize as dependências sempre que possível
7. 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