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) veya make_env(n_envs: int = 1, use_async_envs: bool = False, cfg: EnvConfig | None = None) fonksiyonunu sağlamalısınız. 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

Ortamı yapılandırmak için (ör. ortam sayısı, görev, kamera adı, başlangıç durumları, kontrol modu, bölüm uzunluğu vb.) make_env fonksiyonuna bir EnvConfig nesnesi de iletebilirsiniz.

Son olarak, ortamınızın LeRobot ile çalışabilmesi için gym.vector.VectorEnv arayüzünü, reset ve step gibi yöntemler dahil olmak üzere uygulaması gerekir.

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

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

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:

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

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:

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

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. Yeterince test edin: Ortamınızın yerel olarak çalıştığını doğrulayın
4. Anlamsal sürümleme kullanın: Sürümleri sürüm numaralarıyla etiketleyin
5. Örnekler ekleyin: README dosyanıza kullanım örnekleri dahil edin
6. Basit tutun: Mümkün olduğunca bağımlılıkları en aza indirin
7. Ç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ı