Hubからの環境の読み込み

EnvHub 機能により、1行のコードで Hugging Face Hub からシミュレーション環境を直接読み込むことができます。これにより、強力な新しいコラボレーションモデルが実現します。環境が単一の巨大なライブラリ内に閉じ込められるのではなく、誰でもカスタム環境を公開し、コミュニティと共有できるようになるのです。

EnvHubとは何ですか？

EnvHubでは、独自のロボットモデルとシナリオを使用してカスタムのロボティクスシミュレーション環境を作成し、LeRobotフレームワークを通じて誰でも簡単に利用できるようにできます。

EnvHubのパッケージはHugging Face Hubに保存されており、LeRobotを介して1行のコードでシームレスに取得し、AIロボティクスプロジェクトで使用できます。

EnvHubのおかげで、以下が可能になります:

1. 環境を作成して公開し、Hugging Face Hub に Git リポジトリとして保存することで、パッケージングの手間を省いて複雑な物理シミュレーションを配布できます
2. Load environmentsをパッケージとしてインストールせずに動的に読み込む
3. Gitのセマンティクスを使用して、バージョンとトラックの環境変更を管理します
4. Discoverコミュニティが共有する新しいシミュレーションタスク

この設計により、Hub上で興味深い環境を発見してから実験を実行するまで数秒で済みます。また、依存関係の競合や複雑なインストール手順を気にすることなく、独自のロボットや環境を作成することも可能です。

EnvHubパッケージを作成する際は、その中に自由に何でも構築し、お好みのシミュレーションツールを使用できます。これはあなた自身の遊び場です。唯一の要件は、パッケージ内に環境を定義し、LeRobotがそのEnvHubパッケージを読み込んで使用できるようにするenv.pyファイルが含まれていることです。

このenv.pyファイルは、LeRobotが読み込み・実行できるように、小さなAPIを公開する必要があります。特に、LeRobotのメインのエントリポイントであるmake_env(n_envs: int = 1, use_async_envs: bool = False)関数を提供する必要があります。LeRobotは、ローカルでもサーブ時でも、設定なしでこの関数を呼び出します。この関数は、次のいずれかを返す必要があります:

• gym.vector.VectorEnv（最も一般的）
• 単一のgym.Env(自動的にラップされます)
• {suite_name: {task_id: VectorEnv}} をマッピングする dict(マルチタスクベンチマーク用)

デフォルトでは、返されるベクトル環境はラップされていないSyncVectorEnvまたはAsyncVectorEnvである必要があります。LeRobotはenv_fnsを取得し、各環境を独自に構築します。カスタムのベクトルラッパーやサブクラスは、静かに削除されるのではなく、拒否されます。

プロバイダー所有のベクトルラッパーや GPU ネイティブのバッチを使用する場合は、--env.use_native_batch=true を使用します。これにより、前処理の要件を含むローカルでのバッチ評価において、リポジトリのベクトル環境がそのまま維持されます。このオプションは、エンドポイントや SimRobot と併用できません。文字列 API（make_env("user/repo")）も、プロバイダーの環境をそのまま維持します。

env.pyでは、環境（fps、control_mode、コンポーネント名。詳細はEnvHubとシミュレータサーバーを参照）を記述する任意のLEROBOT_SIM辞書も定義できます。これはローカルでの実行時と、サーバーとして提供されている時の両方に適用されます。

クイックスタート

Hubから環境を読み込むには、次のようにします。

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.

リポジトリの構造

Hubから環境を読み込めるようにするには、リポジトリには最低限以下が必要です:

必須ファイル

env.py（またはカスタムの Python ファイル）

• make_env(n_envs: int, use_async_envs: bool) 関数を公開する必要があります
• make_envの追加のキーワード引数は、環境自身のオプションです: --env.make_env_kwargs='{"episode_length": 900}'でそれらを渡します(シミュレーションロボットの場合は--robot.env.make_env_kwargs)。サーバーは--sim.kwargs='{make_env_kwargs: {episode_length: 900}}'でそれを受け取ります。
• この関数は、次のいずれかを返す必要があります:
  • gym.vector.VectorEnv（最も一般的）
  • 単一のgym.Env(自動的にラップされます)
  • {suite_name: {task_id: VectorEnv}} をマッピングする dict(マルチタスクベンチマーク用)

オプションファイル

requirements.txt

• 環境に必要な追加の依存関係をすべてリストアップします
• ユーザーは、環境を読み込む前にこれらを手動でインストールする必要があります

LEROBOT_SIM in env.py

• simulator serverによってサーブされる環境を記述するモジュールレベルの辞書であり、単一のコマンドから開始できるようにします
• すべてのキーは任意です。LEROBOT_SIM がないリポジトリは、デフォルト値で引き続き動作します。
• robot_typeは、lerobotに本体のクラスが存在する場合、実ロボットが記録するタイプ（so_follower、omx_follower）であり、これによりシミュレーションデータセットと実データセットが一致します。

README.md

• 環境をドキュメント化：実装しているタスク、観測空間/アクション空間、報酬などを記載します。
• 使用例と特別なセットアップ手順を含める

.gitignore

• リポジトリから不要なファイルを除外する

リポジトリの構成例

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

環境リポジトリの作成

ステップ1: 環境を定義する

make_env 関数を含む env.py ファイルを作成します:

# 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

ステップ2: ローカルでテスト

アップロードする前に、ローカルで環境をテストしてください:

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

ステップ3: Hubにアップロード

リポジトリを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

代わりに、huggingface_hub Python APIを使用します。

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からの環境の読み込み

基本的な使用方法

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)

高度なトピック: 特定のバージョンへのピン留め

再現性とセキュリティを確保するために、特定のGitリビジョンに固定します:

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

カスタムファイルパス

環境定義が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)

非同期環境

複数の環境でより良いパフォーマンスを得るには:

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

URL形式リファレンス

ハブのURL形式は、複数のパターンをサポートしています:

EnvHubとシミュレータサーバー

デフォルトでは、EnvHubの環境は評価プロセス内で実行されます: make_envはリポジトリのenv.pyをダウンロードし、その依存関係はLeRobotの隣にインストールされます。環境の依存関係をポリシーの依存関係から分離するために、代わりにsimulator serverで提供します。1つのコマンドで、リポジトリとそのrequirements.txtを含むイメージをビルドし、サーバーを起動します:

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

requirements.txt（pip のルールに従ってインストールされるため、--extra-index-url 行が機能します）に加えて、このイメージは、Hugging Face Spaces と同様に、1 行 1 パッケージで記述された任意の packages.txt に列挙された apt パッケージをインストールします。このイメージはプレーンな Ubuntu です。GPU ドライバーはホストから提供され、CUDA ライブラリはそれらを必要とする Python のホイール（torch、Isaac Sim）から提供されます。

--envhub を渡すことは、trust_remote_code=True と同様に、リポジトリのコードを実行することを明示的に同意することを意味します。コミットを固定し、他の環境と同様にそのエンドポイントを追加して評価してください。

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を指定しない場合、同じコマンドは環境をローカルで実行します（--trust_remote_code=trueを指定）。シミュレーションロボットは、--robot.env.*の下で同じオプションを受け取ります。

サーバーはリポジトリのLEROBOT_SIMから制御レート、アクション規約、コンポーネント名を読み取り、宣言されていない項目にはデフォルト値を使用します。コマンドラインで値を上書きできます。コマンドラインの指定はリポジトリの設定を優先します。例: --sim.fps=15。

サーブするには、環境がこれらの規約に従う必要があります:

• make_env は、環境ごとのファクトリ（上記の例にある SyncVectorEnv/AsyncVectorEnv など）から構築されたベクトル環境、または単一の gym.Env を返します。サーバーはこれらのファクトリから独自の環境を構築し、セッションが終了したときにそれらを閉じます。
• env.pyはサーバープロセスごとに1回だけ実行されるため、プロセス全体の状態を保持できます。例えば、1回しか起動できないシミュレーターアプリケーション（Isaac SimのSimulationApp）などが該当します。
• Observations は、LeRobot がローカルで読み取る辞書です: pixels（HWC uint8 画像 1 つ、またはカメラの辞書）、agent_pos および environment_state、これらは NumPy 配列として扱われます。
• アクションは1次元の連続Boxです。
• エピソードはterminated/truncatedまたは_max_episode_steps(デフォルト 500)によって終了し、info["is_success"]が成功を報告します。タスクのテキストは、環境のtask_description(またはtask)属性から取得されます。
• LEROBOT_SIM は任意ですが、デフォルト値（30 fps、位置制御）があなたの環境と一致しない場合は、必ず宣言してください。

例として、EnvHubの環境コレクションを参照してください。lerobot/so101-tabletop-mujoco (MuJoCo) と lerobot/so101-tabletop-isaac (Isaac Sim、requirements.txt および packages.txt 経由でインストール) は、同じSO-101のシーンで、同じ観測、アクション、およびLEROBOT_SIMを提供します。

リポジトリは、Hugging Face のログイン情報（HF_TOKEN または hf auth login）を使用してあなたのマシンにダウンロードされるため、プライベートリポジトリも利用可能であり、イメージのビルド時にトークンが参照されることはありません。 --envhub には、プッシュする前に環境を提供するための env.py を含むローカルディレクトリを指定できます: lerobot-env-server --envhub=./my-env --docker=true。 --build=true を指定すると、変更された部分のみが再ビルドされます: packages.txt が変更された場合は apt パッケージ、requirements.txt が変更された場合は requirements、それ以外の場合はリポジトリのファイルのみです。新しい環境は、まずローカルでテストしてください（ステップ 2: ローカルでテスト を参照）。

マルチタスク環境

複数のタスク（LIBERO など）を含むベンチマークでは、ネストされた辞書を返します：

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 は呼び出された際にすべてのタスクを構築します。1つのワールドでバッチ全体をステップ実行するGPUシミュレーター（例: Isaac Lab）や、多数のタスクを持つベンチマークでは、LeRobotの統合がそうしているように、代わりにenv.pyでvector_env_fnsを定義してください。これによりファクトリが返され、実行されるタスクのファクトリのみが呼び出されます:

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

各ベクトル環境はnum_envs == n_envsである必要があります。自動リセットは行わず(metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED)、上記の形式でバッチ化された観測を返します。reset(seed=[...])では環境ごとに1つのシードを受け取り、環境ごとにinfo["is_success"]を報告します。--env.make_env_kwargsはこれに渡され、lerobot-evalとシミュレータサーバーの両方がmake_envの代わりにこれを使用します。1つのベクトル環境がすでにバッチ全体をステップするため、--eval.use_async_envs=falseで評価してください。ワーカープロセスを使用すると、観測バッチ全体をプロセス間でコピーするだけになり、サーバーを使用するとワーカー内でシミュレータが2回構築されてしまいます。

セキュリティに関する考慮事項

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

Hubから環境を読み込む場合:

1. まずコードを確認する: リポジトリにアクセスし、読み込む前にenv.pyを調べます
2. コミットにピン留め: 再現性のために特定のコミットハッシュを使用します
3. 依存関係の確認: requirements.txt内の疑わしいパッケージを確認します
4. 信頼できる情報源を使用する: 公式の組織や著名な研究者を優先する
5. 必要に応じてサンドボックスを使用: 信頼できないコードを隔離された環境（コンテナ、VM）で実行します

安全な使用例:

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

例: HubからのCartPole

参考用の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()

EnvHubの利点

環境作成者向け

• かんたんな配布：PyPIでのパッケージングは不要
• バージョン管理: 環境のバージョン管理には Git を使用します
• 高速な反復: 更新を即座に反映
• ドキュメント: Hub の README が美しくレンダリングされます
• コミュニティ：LeRobotのユーザーに直接リーチする

研究者向け

• クイック実験: 1行で任意の環境を読み込む
• 再現可能性: 特定のコミットに固定する
• Discovery: Hub上の環境を閲覧
• 競合なし: 競合するパッケージのインストールは不要です

コミュニティ向け

• 成長するエコシステム: より多様なシミュレーションタスク
• 標準化: 共通のmake_env API
• コラボレーション: 既存の環境をフォークして改善する
• アクセシビリティ: 研究共有の障壁を低減

トラブルシューティング

“リモートコードの実行を拒否します”

trust_remote_code=True を明示的に渡す必要があります:

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

“モジュール X が見つかりません”

Hub環境には、インストールが必要な依存関係があります:

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

“make_env not found in module”

env.pyには、make_env関数を公開する必要があります。

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

Environmentが誤った型を返す

make_env関数は、以下を返す必要があります:

• gym.vector.VectorEnv、または
• 単一のgym.Env、または
• 辞書 {suite_name: {task_id: VectorEnv}}

ベストプラクティス

1. 環境をドキュメント化する: README に、観測空間/アクション空間の説明、報酬構造、終了条件を含めてください
2. requirements.txt を追加する: バージョンを指定してすべての依存関係を列挙する
3. LEROBOT_SIMを宣言する: 1つのコマンドで、環境をシミュレータサーバーで提供するようにします
4. 徹底的にテストする: プッシュする前に、環境がローカルで正常に動作することを確認します
5. セマンティックバージョニングを使用する: リリースにバージョン番号をタグ付けする
6. 例の追加: READMEに使用例を含める
7. シンプルに保つ: 可能な限り依存関係を最小限に抑える
8. 成果物のライセンス設定: 利用条件を明確にするために LICENSE ファイルを追加します

今後の方向性

EnvHubエコシステムは、魅力的な可能性を秘めています:

• GPU 加速物理: Isaac Gym または Brax の環境を共有
• フォトリアルなレンダリング: 高度なグラフィックスを備えた環境の配布
• マルチエージェントシナリオ: 複雑な相互作用タスク
• 実世界のシミュレーター: 物理的なセットアップのデジタルツイン
• 手続き的生成: 無限のタスクバリエーション
• ドメインランダム化: 事前設定済みのDRパイプライン

研究者や開発者の貢献が増えるにつれて、利用可能な環境の多様性と品質は向上し、ロボティクス学習コミュニティ全体が恩恵を受けることになります。

関連項目

• Hugging Face Hub ドキュメント
• Gymnasium ドキュメント
• Hub環境の例