Memuat Lingkungan dari Hub

Fitur EnvHub memungkinkan Anda memuat lingkungan simulasi langsung dari Hugging Face Hub dengan satu baris kode. Hal ini membuka model kolaborasi baru yang kuat: alih-alih lingkungan terkunci di dalam pustaka monolitik, siapa pun dapat menerbitkan lingkungan kustom dan membagikannya dengan komunitas.

Apa itu EnvHub?

EnvHub memungkinkan Anda membuat lingkungan simulasi robotika kustom dengan model robot dan skenario Anda sendiri, serta membuatnya mudah digunakan oleh siapa pun melalui kerangka kerja LeRobot.

Paket EnvHub disimpan di Hugging Face Hub, dan dapat ditarik serta digunakan secara mulus dalam proyek robotika AI Anda melalui LeRobot dengan satu baris kode.

Berkat EnvHub, Anda dapat:

1. Buat dan terbitkan lingkungan ke Hugging Face Hub sebagai repositori Git, dan distribusikan simulasi fisika yang kompleks tanpa repotnya pengemasan
2. Memuat lingkungan secara dinamis, tanpa menginstalnya sebagai paket
3. Versi dan lacak perubahan lingkungan menggunakan semantik Git
4. Temukan tugas simulasi baru yang dibagikan oleh komunitas

Desain ini memungkinkan Anda beralih dari menemukan lingkungan menarik di Hub hingga menjalankan eksperimen dalam hitungan detik, atau membuat robot dan lingkungan kustom Anda sendiri tanpa perlu khawatir tentang konflik dependensi atau prosedur instalasi yang rumit.

Saat Anda membuat paket EnvHub, Anda dapat membangun apa pun yang Anda inginkan di dalamnya dan menggunakan alat simulasi apa pun yang Anda sukai: ini adalah ruang Anda sendiri untuk bereksperimen. Satu-satunya persyaratan adalah paket tersebut berisi file env.py yang mendefinisikan lingkungan dan memungkinkan LeRobot untuk memuat serta menggunakan paket EnvHub Anda.

File env.py ini perlu mengekspos API kecil agar LeRobot dapat memuat dan menjalankannya. Secara khusus, Anda harus menyediakan fungsi make_env(n_envs: int = 1, use_async_envs: bool = False), yang merupakan titik masuk utama untuk LeRobot. LeRobot memanggilnya tanpa config, baik secara lokal maupun saat disajikan. Fungsi ini harus mengembalikan salah satu dari:

• Sebuah gym.vector.VectorEnv (paling umum)
• Satu gym.Env (akan dibungkus secara otomatis)
• Dict yang memetakan {suite_name: {task_id: VectorEnv}} (untuk benchmark multi-tugas)

Secara default, vektor env yang dikembalikan harus berupa SyncVectorEnv atau AsyncVectorEnv yang tidak dibungkus: LeRobot mengambil env_fns dan membangun setiap lingkungan sendiri. Pembungkus vektor kustom dan subkelas ditolak, bukan dihapus secara diam-diam.

Untuk wrapper vektor milik provider atau batch native GPU, gunakan --env.use_native_batch=true. Ini menjaga lingkungan vektor repositori tetap utuh untuk evaluasi batch lokal, termasuk persyaratan preprosesnya. Opsi ini tidak dapat digabungkan dengan endpoint atau SimRobot. API string (make_env("user/repo")) juga menjaga lingkungan provider tetap utuh.

env.py juga dapat mendefinisikan kamus opsional LEROBOT_SIM yang menjelaskan lingkungan (fps, control_mode, nama komponen; lihat EnvHub dan server simulator). Kamus ini berlaku secara lokal dan saat disajikan.

Mulai Cepat

Memuat lingkungan dari Hub sesederhana:

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.

Struktur Repository

Untuk membuat lingkungan Anda dapat dimuat dari Hub, repositori Anda harus memuat setidaknya:

File yang Diperlukan

env.py (atau file Python kustom)

• Harus mengekspos fungsi make_env(n_envs: int, use_async_envs: bool)
• Argumen kata kunci tambahan dari make_env adalah opsi lingkungan itu sendiri: --env.make_env_kwargs='{"episode_length": 900}' meneruskannya (--robot.env.make_env_kwargs untuk robot simulasi), dan server menerimanya dengan --sim.kwargs='{make_env_kwargs: {episode_length: 900}}'
• Fungsi ini harus mengembalikan salah satu dari:
  • Sebuah gym.vector.VectorEnv (paling umum)
  • Satu gym.Env (akan dibungkus secara otomatis)
  • Dict yang memetakan {suite_name: {task_id: VectorEnv}} (untuk benchmark multi-tugas)

File Opsional

requirements.txt

• Daftarkan semua dependensi tambahan yang dibutuhkan lingkungan Anda
• Pengguna perlu menginstal ini secara manual sebelum memuat lingkungan Anda

LEROBOT_SIM di env.py

• Kamus tingkat modul yang menggambarkan lingkungan saat disajikan oleh simulator server, sehingga dimulai dengan satu perintah
• Setiap kunci bersifat opsional; repositori tanpa LEROBOT_SIM tetap berfungsi dengan nilai bawaan
• robot_type adalah tipe yang dicatat oleh robot fisik (so_follower, omx_follower) ketika lerobot memiliki kelas untuk bodinya, sehingga dataset simulasi dan dataset fisik cocok

README.md

• Dokumentasikan lingkungan Anda: tugas apa yang diimplementasikan, ruang observasi/aksi, reward, dan sebagainya.
• Sertakan contoh penggunaan dan instruksi pengaturan khusus

.gitignore

• Hilangkan file yang tidak perlu dari repositori Anda

Struktur Repositori Contoh

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

Membuat Repositori Lingkungan Anda

Langkah 1: Definisikan Lingkungan Anda

Buat file env.py dengan fungsi 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

Langkah 2: Uji Secara Lokal

Sebelum mengunggah, uji lingkungan Anda secara lokal:

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

Langkah 3: Unggah ke Hub

Unggah repositori Anda ke 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

Sebagai alternatif, gunakan 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",
)

Memuat Lingkungan dari Hub

Penggunaan Dasar

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)

Lanjutan: Mengunci ke Versi Tertentu

Untuk reproduktibilitas dan keamanan, kunci ke revisi Git tertentu:

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

Jalur File Kustom

Jika definisi lingkungan Anda tidak ada di 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)

Lingkungan Asinkron

Untuk kinerja yang lebih baik dengan beberapa lingkungan:

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

Referensi Format URL

Format URL hub mendukung beberapa pola:

EnvHub dan server simulator

Secara default, lingkungan EnvHub berjalan di dalam proses evaluasi: make_env mengunduh env.py dari repositori, dan dependensinya diinstal berdampingan dengan LeRobot. Untuk memisahkan dependensi lingkungan dari dependensi kebijakan Anda, layanilah lingkungan tersebut dengan simulator server sebagai gantinya. Satu perintah membangun image dengan repositori dan requirements.txt miliknya, lalu memulai server:

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

Selain requirements.txt (diinstal dengan aturan pip, sehingga baris --extra-index-url berfungsi), image menginstal paket apt yang tercantum dalam packages.txt opsional, satu per baris, seperti di Hugging Face Spaces. Image ini adalah Ubuntu polos: driver GPU berasal dari host, dan pustaka CUDA berasal dari wheel Python yang membutuhkannya (torch, Isaac Sim).

Menyampaikan --envhub merupakan persetujuan eksplisit untuk menjalankan kode repositori, seperti trust_remote_code=True. Kunci sebuah commit. Kemudian evaluasi terhadapnya seperti lingkungan lainnya, dengan menambahkan endpoint-nya:

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

Tanpa --env.server.endpoint, perintah yang sama menjalankan lingkungan secara lokal (dengan --trust_remote_code=true); robot simulasi mengambil opsi yang sama di bawah --robot.env.*.

Server membaca laju kontrol, konvensi aksi, dan nama komponen dari LEROBOT_SIM di repositori, dan menggunakan nilai bawaan untuk apa pun yang tidak dideklarasikan. Timpa nilai di baris perintah, yang memiliki prioritas lebih tinggi daripada repositori, misalnya --sim.fps=15.

Untuk dapat disajikan, lingkungan harus mengikuti konvensi berikut:

• make_env mengembalikan lingkungan vektor yang dibangun dari pabrik per-lingkungan (SyncVectorEnv/AsyncVectorEnv, seperti pada contoh di atas) atau satu gym.Env. Server membangun lingkungannya sendiri dari pabrik-pabrik tersebut dan menutupnya ketika sesi berakhir.
• env.py dieksekusi sekali per proses server, sehingga dapat mempertahankan status di seluruh proses, seperti aplikasi simulator yang hanya dapat dimulai sekali (SimulationApp dari Isaac Sim).
• Observasi adalah kamus yang dibaca secara lokal oleh LeRobot: pixels (satu gambar HWC uint8 atau kamus kamera), agent_pos dan environment_state, sebagai array NumPy.
• Actions adalah Box kontinu satu dimensi.
• Episode berakhir melalui terminated/truncated atau _max_episode_steps (default 500), dan info["is_success"] melaporkan keberhasilan. Teks tugas berasal dari atribut task_description (atau task) lingkungan.
• LEROBOT_SIM bersifat opsional, tetapi nyatakannya setiap kali nilai bawaan (30 fps, kontrol posisi) tidak sesuai dengan lingkungan Anda.

Untuk contoh, lihat koleksi lingkungan EnvHub: lerobot/so101-tabletop-mujoco (MuJoCo) dan lerobot/so101-tabletop-isaac (Isaac Sim, diinstal melalui requirements.txt dan packages.txt) menyajikan adegan SO-101 yang sama dengan observasi, aksi, dan LEROBOT_SIM yang sama.

Repositori diunduh ke mesin Anda dengan login Hugging Face Anda (HF_TOKEN atau hf auth login), sehingga repositori privat juga berfungsi, dan build image tidak pernah melihat token. --envhub juga menerima direktori lokal yang berisi env.py, untuk menyajikan lingkungan sebelum mendorongnya: lerobot-env-server --envhub=./my-env --docker=true. --build=true hanya membangun ulang apa yang berubah: paket apt ketika packages.txt berubah, requirements ketika requirements.txt berubah, dan selain itu hanya file dari repositori. Uji lingkungan baru secara lokal terlebih dahulu (lihat Langkah 2: Uji Secara Lokal).

Lingkungan Multi-Tugas

Untuk benchmark dengan beberapa tugas (seperti LIBERO), kembalikan kamus bersarang:

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 membangun setiap tugas saat dipanggil. Untuk simulator GPU yang memproses seluruh batch dalam satu dunia (misalnya Isaac Lab), atau benchmark dengan banyak tugas, definisikan vector_env_fns di env.py sebagai gantinya, seperti yang dilakukan oleh integrasi LeRobot sendiri. Fungsi ini mengembalikan factory, dan hanya factory dari tugas yang dijalankan yang akan dipanggil:

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")}}

Setiap vector env harus memiliki num_envs == n_envs, tidak boleh autoreset (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED), mengembalikan observasi yang di-batch dalam format di atas, menerima satu seed per env dalam reset(seed=[...]), dan melaporkan info["is_success"] per env. --env.make_env_kwargs diteruskan ke dalamnya, dan baik lerobot-eval maupun server simulator menggunakannya sebagai pengganti make_env. Karena satu vector env sudah melakukan step untuk seluruh batch, lakukan evaluasi dengan --eval.use_async_envs=false: proses worker hanya akan menyalin setiap batch observasi antar proses, dan server akan membangun simulator untuk kedua kalinya, di dalam worker.

Pertimbangan Keamanan

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

Saat memuat lingkungan dari Hub:

1. Periksa kode terlebih dahulu: Kunjungi repositori dan periksa env.py sebelum memuat
2. Kunci ke commit: Gunakan hash commit tertentu untuk reproduktibilitas
3. Periksa dependensi: Tinjau requirements.txt untuk paket yang mencurigakan
4. Gunakan sumber yang tepercaya: Utamakan organisasi resmi atau peneliti yang dikenal luas
5. Sandbox jika diperlukan: Jalankan kode yang tidak tepercaya di lingkungan terisolasi (kontainer, VM)

Contoh penggunaan yang aman:

# ❌ 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)

Contoh: CartPole dari Hub

Berikut adalah contoh lengkap menggunakan lingkungan referensi 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()

Manfaat EnvHub

Untuk Penulis Lingkungan

• Distribusi mudah: Tidak memerlukan pengemasan PyPI
• Kontrol versi: Gunakan Git untuk penerbitan versi lingkungan
• Iterasi cepat: Dorong pembaruan secara instan
• Dokumentasi: README Hub dirender dengan indah
• Community: Hubungi pengguna LeRobot secara langsung

Untuk Peneliti

• Eksperimen cepat: Muat lingkungan apa pun dalam satu baris
• Reproducibility: Kunci ke commit tertentu
• Penemuan: Jelajahi lingkungan di Hub
• Tidak ada konflik: Tidak perlu menginstal paket yang saling bertentangan

Untuk Komunitas

• Ekosistem yang berkembang: Tugas simulasi yang lebih beragam
• Standarisasi: API make_env yang umum
• Kolaborasi: Fork dan perbaiki lingkungan yang sudah ada
• Aksesibilitas: Mengurangi hambatan dalam berbagi penelitian

Pemecahan Masalah

“Menolak untuk mengeksekusi kode jarak jauh”

Anda harus secara eksplisit meneruskan trust_remote_code=True:

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

“Module X tidak ditemukan”

Lingkungan hub memiliki dependensi yang perlu Anda instal:

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

“make_env tidak ditemukan di modul”

env.py Anda harus mengekspos fungsi make_env:

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

Environment mengembalikan tipe yang salah

Fungsi make_env harus mengembalikan:

• Sebuah gym.vector.VectorEnv, atau
• Satu gym.Env, atau
• Dict {suite_name: {task_id: VectorEnv}}

Praktik Terbaik

1. Dokumentasikan lingkungan Anda: Sertakan deskripsi ruang observasi/aksi, struktur reward, dan kondisi terminasi di README Anda
2. Tambahkan requirements.txt: Daftarkan semua dependensi beserta versinya
3. Declarasikan LEROBOT_SIM: Biarkan lingkungan disajikan oleh server simulator dengan satu perintah
4. Uji secara menyeluruh: Pastikan lingkungan Anda berfungsi secara lokal sebelum mendorong (push)
5. Gunakan semantic versioning: Beri tag rilis dengan nomor versi
6. Tambahkan contoh: Sertakan contoh penggunaan di README Anda
7. Jaga agar tetap sederhana: Minimalkan dependensi jika memungkinkan
8. Lisensikan pekerjaan Anda: Tambahkan file LICENSE untuk memperjelas ketentuan penggunaan

Arah Masa Depan

Ekosistem EnvHub memungkinkan berbagai kemungkinan menarik:

• Fisika dengan akselerasi GPU: Bagikan lingkungan Isaac Gym atau Brax
• Render fotorealistis: Distribusikan lingkungan dengan grafis canggih
• Skenario multi-agen: Tugas interaksi kompleks
• Simulator dunia nyata: Kembar digital dari setup fisik
• Generasi prosedural: Variasi tugas tak terbatas
• Randomisasi domain: Pipeline DR yang sudah dikonfigurasi

Seiring bertambahnya peneliti dan pengembang yang berkontribusi, keragaman dan kualitas lingkungan yang tersedia akan meningkat, sehingga menguntungkan seluruh komunitas pembelajaran robotika.

Lihat Juga

• Dokumentasi Hugging Face Hub
• Dokumentasi Gymnasium
• Contoh Lingkungan Hub