Hub'dan Ortamları Yükleme

EnvHub özelliği, simülasyon ortamlarını Hugging Face Hub'dan tek satır kodla doğrudan yüklemenizi sağlar. Bu, iş birliği için güçlü yeni bir modelin kapısını aralar: ortamlar monolitik kütüphanelerin içinde kilitli kalmak yerine, herkes özel ortamlar yayınlayabilir ve bunları toplulukla paylaşabilir.

EnvHub nedir?

EnvHub, kendi robot modellerinizi ve senaryolarınızı kullanarak özel robotik simülasyon ortamları oluşturmanızı ve bunları LeRobot çerçevesi aracılığıyla herkesin kolayca kullanabilmesini sağlar.

EnvHub paketleri Hugging Face Hub üzerinde saklanır ve LeRobot aracılığıyla tek satır kodla AI robotik projelerinizde sorunsuz bir şekilde çekilip kullanılabilir.

EnvHub sayesinde şunları yapabilirsiniz:

1. Hugging Face Hub'a Git depoları olarak ortamlar oluşturun ve yayınlayın, karmaşık fizik simülasyonlarını paketleme zahmeti olmadan dağıtın
2. Ortamları paket olarak yüklemeye gerek kalmadan dinamik olarak yükleyin
3. Git sözdizimini kullanarak sürüm ve izleme ortamı değişikliklerini yönetin
4. Keşfet topluluk tarafından paylaşılan yeni simülasyon görevleri

Bu tasarım, Hub'da ilginç bir ortam keşfetmekten saniyeler içinde deneyler çalıştırmaya geçmenizi veya bağımlılık çakışmaları veya karmaşık kurulum işlemleriyle uğraşmadan kendi özel robotunuzu ve ortamınızı oluşturmanızı sağlar.

EnvHub paketi oluşturduğunuzda, içinde istediğiniz her şeyi oluşturabilir ve istediğiniz herhangi bir simülasyon aracını kullanabilirsiniz: bu, denemeler yapabileceğiniz kendi alanınızdır. Tek gereklilik, paketin ortamı tanımlayan ve LeRobot'un EnvHub paketinizi yükleyip kullanmasını sağlayan bir env.py dosyası içermesidir.

Bu env.py dosyasının, LeRobot'un dosyayı yükleyip çalıştırabilmesi için küçük bir API sunması gerekir. Özellikle, LeRobot'un ana giriş noktası olan make_env(n_envs: int = 1, use_async_envs: bool = False) fonksiyonunu sağlamalısınız. LeRobot bu fonksiyonu, hem yerel olarak hem de servis edildiğinde yapılandırma olmadan çağırır. Aşağıdakilerden birini döndürmelidir:

• En yaygın olanı: gym.vector.VectorEnv
• Tek bir gym.Env (otomatik olarak sarılacaktır)
• {suite_name: {task_id: VectorEnv}} (çoklu görev kıyaslamaları için) eşleyen bir sözlük

Varsayılan olarak, döndürülen vektör env, sarmalanmamış bir SyncVectorEnv veya AsyncVectorEnv olmalıdır: LeRobot, env_fns değerlerini alır ve her ortamı kendisi oluşturur. Özel vektör sarmalayıcılar ve alt sınıflar sessizce kaldırılmak yerine reddedilir.

Sağlayıcıya ait vektör sarmalayıcıları veya GPU yerel toplamlar için --env.use_native_batch=true kullanın. Bu, ön işleme gereksinimleri dahil olmak üzere yerel toplu değerlendirme için depodaki vektör ortamını olduğu gibi korur. Bir uç nokta veya SimRobot ile birleştirilemez. Dize API’si (make_env("user/repo")) de sağlayıcının ortamını olduğu gibi korur.

env.py ayrıca ortamı tanımlayan (fps, control_mode, bileşen adları; bkz. EnvHub ve simülatör sunucusu) isteğe bağlı bir LEROBOT_SIM sözlüğü de tanımlayabilir. Bu sözlük hem yerel olarak hem de sunulurken geçerlidir.

Hızlı Başlangıç

Hub'dan bir ortam yüklemek şu kadar basit:

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.

Depo Yapısı

Ortamınızın Hub'dan yüklenebilir olması için, deponuzda en azından şunlar bulunmalıdır:

Gerekli Dosyalar

env.py (veya özel Python dosyası)

• make_env(n_envs: int, use_async_envs: bool) fonksiyonunu dışa açmalıdır
• make_env işlevinin ek anahtar kelime argümanları, ortamın kendi seçenekleridir: --env.make_env_kwargs='{"episode_length": 900}' bunları iletir (simülasyon robotu için --robot.env.make_env_kwargs), bir sunucu ise bunları --sim.kwargs='{make_env_kwargs: {episode_length: 900}}' ile alır.
• Bu fonksiyon aşağıdakilerden birini döndürmelidir:
  • En yaygın olanı: gym.vector.VectorEnv
  • Tek bir gym.Env (otomatik olarak sarılacaktır)
  • {suite_name: {task_id: VectorEnv}} (çoklu görev kıyaslamaları için) eşleyen bir sözlük

İsteğe Bağlı Dosyalar

requirements.txt

• Ortamınızın ihtiyaç duyduğu ek bağımlılıkları listeleyin
• Kullanıcılar, ortamınızı yüklemesinden önce bunları manuel olarak kurmalıdır

LEROBOT_SIM in env.py

• simulator server tarafından sunulduğunda ortamı tanımlayan ve tek bir komutla başlanmasını sağlayan modül düzeyinde bir sözlük
• Her anahtar isteğe bağlıdır; LEROBOT_SIM içermeyen depolar varsayılanlarla çalışmaya devam eder
• robot_type, lerobot'un gövde için bir sınıfına sahip olduğu durumlarda gerçek robotun kaydettiği türdür (so_follower, omx_follower); böylece simüle ve gerçek veri kümeleri eşleşir

README.md

• Ortamınızı belgeleyin: hangi görevi uyguladığı, gözlem/aksiyon uzayları, ödüller vb.
• Kullanım örneklerini ve özel kurulum talimatlarını dahil edin

.gitignore

• Deponuzdan gereksiz dosyaları hariç tutun

Örnek Depo Yapısı

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

Ortam Deponuzu Oluşturma

Adım 1: Ortamınızı Tanımlayın

Bir env.py dosyası oluşturun ve içinde bir make_env fonksiyonu tanımlayın:

# 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

Adım 2: Yerel olarak test edin

Yüklemeden önce ortamınızı yerel olarak test edin:

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

Adım 3: Hub'a Yükle

Deponuzu Hugging Face'e yükleyin:

# 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

Alternatif olarak, huggingface_hub Python API'sini kullanın:

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

Hub'dan Ortamları Yükleme

Temel Kullanım

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)

Gelişmiş: Belirli Sürümlere Sabitleme

Tekrarlanabilirlik ve güvenlik için belirli bir Git revizyonuna sabitleyin:

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

Özel Dosya Yolları

Ortam tanımınız env.py dosyasında değilse:

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

Asenkron Ortamlar

Birden fazla ortamda daha iyi performans için:

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

URL Biçimi Referansı

Hub URL biçimi birkaç deseni destekler:

EnvHub ve simülatör sunucusu

Varsayılan olarak, EnvHub ortamları değerlendirme sürecinin içinde çalışır: make_env, depodaki env.py dosyasını indirir ve bağımlılıkları LeRobot’un yanına kurulur. Bir ortamın bağımlılıklarını politikanızın bağımlılıklarından ayrı tutmak için, ortamı bunun yerine simülatör sunucusu ile sunun. Tek bir komut, depoyu ve requirements.txt dosyasını içeren bir görüntü oluşturur ve sunucuyu başlatır:

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

requirements.txt dışında (pip kurallarıyla kurulur, bu yüzden --extra-index-url satırları çalışır), görüntü, Hugging Face Spaces’te olduğu gibi, isteğe bağlı packages.txt içinde satır satır listelenen apt paketlerini de kurar. Görüntü düz Ubuntu’dur: GPU sürücüsü ana makineden gelir, CUDA kütüphaneleri ise onlara ihtiyaç duyan Python tekerleklerinden (torch, Isaac Sim) gelir.

--envhub parametresinin geçirilmesi, trust_remote_code=True gibi, depodaki kodun çalıştırılmasına açık bir onaydır. Bir commit sabitleyin. Ardından, diğer herhangi bir ortamda olduğu gibi, endpoint'ini ekleyerek bu commit'e karşı değerlendirme yapın:

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

--env.server.endpoint olmadan, aynı komut ortamı yerel olarak çalıştırır (--trust_remote_code=true ile); bir sim robotu aynı seçenekleri --robot.env.* altında alır.

Sunucu, kontrol hızını, eylem sözleşmesini ve bileşen adlarını depodaki LEROBOT_SIM dosyasından okur ve beyan etmediği her şey için varsayılanları kullanır. Değeri komut satırında geçersiz kılın; bu, depodaki değerden üstün gelir, örneğin --sim.fps=15.

Sunulacak bir ortamın bu kurallara uyması gerekir:

• make_env, ortam başına fabrikalardan (SyncVectorEnv/AsyncVectorEnv, yukarıdaki örneklerdeki gibi) oluşturulan vektörel ortamları veya tek bir gym.Env döndürür. Sunucu, bu fabrikalardan kendi ortamlarını oluşturur ve bir oturum sonlandığında bunları kapatır.
• env.py her sunucu süreci için bir kez çalıştırılır, bu nedenle süreç genelinde durum tutabilir; örneğin yalnızca bir kez başlatılabilen bir simülatör uygulaması (Isaac Sim’in SimulationApp bileşeni).
• Gözlemler, LeRobot'ün yerel olarak okuduğu sözlüklerdir: pixels (tek bir HWC uint8 görüntü veya kameraların sözlüğü), agent_pos ve environment_state, NumPy dizileri olarak.
• Actions, bir boyutlu sürekli bir Box'tur.
• Episodlar terminated/truncated veya _max_episode_steps (varsayılan 500) ile sona erer ve info["is_success"] başarıyı raporlar. Görev metni, ortamın task_description (veya task) özniteliğinden gelir.
• LEROBOT_SIM isteğe bağlıdır, ancak varsayılanlar (30 fps, konum kontrolü) ortamınızla eşleşmiyorsa her zaman bildirin.

Örnekler için EnvHub ortamları koleksiyonuna bakın: lerobot/so101-tabletop-mujoco (MuJoCo) ve lerobot/so101-tabletop-isaac (Isaac Sim, requirements.txt ve packages.txt üzerinden yüklenir) aynı SO-101 sahnesini, aynı gözlemler, eylemler ve LEROBOT_SIM ile sunar.

Depo, Hugging Face oturumunuzla (HF_TOKEN veya hf auth login) makinenize indirilir; bu sayede özel depolar da çalışır ve görüntü derlemesi hiçbir zaman bir belirteç görmez. --envhub ayrıca env.py içeren yerel bir dizini de alır, böylece bir ortamı itmeden önce sunabilirsiniz: lerobot-env-server --envhub=./my-env --docker=true. --build=true yalnızca değişenleri yeniden derler: packages.txt değiştiğinde apt paketlerini, requirements.txt değiştiğinde gereksinimleri, aksi halde yalnızca depodaki dosyaları. Yeni bir ortamı önce yerel olarak test edin (bkz. Adım 2: Yerel Test).

Çok Görevli Ortamlar

Birden fazla görev içeren (LIBERO gibi) kıyaslamalar için iç içe geçmiş bir sözlük döndürün:

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 çağrıldığında tüm görevleri oluşturur. Bir GPU simülatörü (ör. Isaac Lab) tüm bir batch’i tek bir dünyada adım atıyorsa veya birçok görev içeren bir benchmark kullanılıyorsa, LeRobot’un kendi entegrasyonlarının yaptığı gibi bunun yerine env.py içinde vector_env_fns tanımlayın. Bu, fabrikalar döndürür ve yalnızca çalışan görevlerin fabrikaları çağrılır:

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

Her vektörel env'in num_envs == n_envs olması, otomatik sıfırlama yapmaması (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED), yukarıdaki formatta toplu gözlemler (batched observations) döndürmesi, reset(seed=[...]) içinde env başına bir seed alması ve env başına info["is_success"] raporlaması gerekir. --env.make_env_kwargs bu env'e iletilir ve hem lerobot-eval hem de simülatör sunucusu, make_env yerine bunu kullanır. Tek bir vektörel env zaten tüm batch'i adım attığı için, --eval.use_async_envs=false ile değerlendirme yapın: bir worker süreci yalnızca her gözlem batch'ini süreçler arasında kopyalar, bir sunucu ise simülatörü worker içinde ikinci kez oluşturur.

Güvenlik Düşünceleri

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

Hub'dan ortamlar yüklenirken:

1. Önce kodu inceleyin: Yüklemeye başlamadan önce depoyu ziyaret edin ve env.py dosyasını kontrol edin
2. Commit'lere sabitle: Yeniden üretilebilirlik için belirli commit hash'leri kullanın
3. Bağımlılıkları kontrol edin: requirements.txt dosyasındaki şüpheli paketleri inceleyin
4. Güvenilir kaynakları kullanın: Resmi kuruluşları veya tanınmış araştırmacıları tercih edin
5. Gerektiğinde Sandbox kullanın: Güvenilmeyen kodu izole ortamlarda (konteynerler, sanal makineler) çalıştırın

Güvenli kullanım örneği:

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

Örnek: Hub'dan CartPole

Referans CartPole ortamını kullanan tam bir örnek:

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

EnvHub'in Faydaları

Ortam Yazarları İçin

• Kolay dağıtım: PyPI paketleme gerektirmez
• Sürüm kontrolü: Ortam sürümleme için Git kullanın
• Hızlı yineleme: Güncellemeleri anında yayınlayın
• Belgeler: Hub README'si güzel bir şekilde görüntüleniyor
• Topluluk: LeRobot kullanıcılarıyla doğrudan iletişime geçin

Araştırmacılar İçin

• Hızlı deneyler: Herhangi bir ortamı tek satırda yükleyin
• Tekrarlanabilirlik: Belirli commit'lere sabitle
• Keşif: Hub'daki ortamlara göz atın
• Çakışma yok: Çakışan paketleri kurmanıza gerek yok

Topluluk İçin

• Büyüyen ekosistem: Daha çeşitli simülasyon görevleri
• Standartlaştırma: Ortak make_env API'si
• İşbirliği: Mevcut ortamları çatallayın ve iyileştirin
• Erişilebilirlik: Araştırma paylaşımındaki engelleri azaltma

Sorun Giderme

“Uzak kodun çalıştırılmasının reddedilmesi”

trust_remote_code=True parametresini açıkça geçirmelisiniz:

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

“Modül X bulunamadı”

Hub ortamı, yüklemeniz gereken bağımlılıklara sahiptir:

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

“make_env modülde bulunamadı”

env.py dosyanız bir make_env fonksiyonu açığa çıkarmalıdır:

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

Environment yanlış türü döndürüyor

make_env fonksiyonu şunları döndürmelidir:

• Bir gym.vector.VectorEnv, veya
• Tek bir gym.Env veya
• Bir sözlük {suite_name: {task_id: VectorEnv}}

En İyi Uygulamalar

1. Ortamınızı belgeleyin: README dosyanıza gözlem/aksiyon uzayı açıklamalarını, ödül yapısını ve sonlanma koşullarını ekleyin
2. requirements.txt dosyasını ekleyin: Tüm bağımlılıkları sürümleriyle birlikte listeleyin
3. LEROBOT_SIM tanımlayın: Ortamı tek komutla simülatör sunucusu tarafından sağlanacak şekilde yapılandırın
4. Yeterince test edin: Ortamınızın yerel olarak çalıştığını doğrulayın
5. Anlamsal sürümleme kullanın: Sürümleri sürüm numaralarıyla etiketleyin
6. Örnekler ekleyin: README dosyanıza kullanım örnekleri dahil edin
7. Basit tutun: Mümkün olduğunca bağımlılıkları en aza indirin
8. Çalışmanızı lisanslayın: Kullanım koşullarını netleştirmek için bir LICENSE dosyası ekleyin

Gelecek Yönler

EnvHub ekosistemi heyecan verici olanaklar sunar:

• GPU hızlandırmalı fizik: Isaac Gym veya Brax ortamlarını paylaşın
• Foto gerçekçi render: Gelişmiş grafiklere sahip ortamları dağıtın
• Çoklu ajan senaryoları: Karmaşık etkileşim görevleri
• Gerçek dünya simülatörleri: Fiziksel kurulumların dijital ikizleri
• Prosedürel üretim: Sınırsız görev çeşitliliği
• Alan rastgeleleştirme: Ön yapılandırılmış DR boru hatları

Araştırmacı ve geliştiricilerin katkısı arttıkça, mevcut ortamların çeşitliliği ve kalitesi de artacak ve bu durum tüm robotik öğrenme topluluğuna fayda sağlayacaktır.

Bkz.

• Hugging Face Hub Belgeleme
• Gymnasium Belgeleme
• Örnek Hub Ortamı