LeRobot documentation

シミュレーション

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

シミュレーション

LeRobotのシミュレーターは、LeRobotの規約(カメラ画像とロボット状態を含む辞書形式の観測値、連続アクション、info["is_success"]での成功判定。詳細は環境を参照)に従ったGymnasium環境であり、一度作成すれば、LeRobotがロボットを実行するすべての場所で使用できます。

  • ポリシーを評価するために、バッチ化された環境(--env.*)として使用します。これは、1つのタスクの複数の環境を同時にステップ実行するものです。lerobot-evalおよび学習中の評価で使用されます。
  • シミュレーションロボットとして(--robot.type=sim --robot.env.*): Robotインターフェースの背後に1つの環境があり、実ハードウェアと交換可能です。lerobot-rollout、lerobot-record、lerobot-teleoperate、lerobot-replayで使用されます。

Either runs locally, in your Python environment, or served by lerobot-env-server, usually in its own Docker image, so that the simulator’s dependencies never meet the policy’s. Setting an endpoint selects served execution; both paths give the policy the same observations (HWC uint8 images, flat float32 state), the same episode ends, and the same control conventions.

ローカル提供
バッチ化された環境: lerobot-eval--env.type=<sim>--env.type=<sim> --env.server.endpoint=tcp/...
シミュレーションロボット: lerobot-rollout、-record、-teleoperate、-replay--robot.type=sim --robot.env.type=<sim>--robot.type=sim --robot.env.type=<sim> --robot.env.server.endpoint=tcp/...
インストールシミュレーター、LeRobot(その追加機能)の隣にlerobot[remote]。シミュレーターはサーバーのイメージ内に存在します
へ読み取る
シミュレーション内で評価、記録、または遠隔操作を行うこのページ、およびシミュレータ自体のページ(LIBERO、Meta-World、…)
Hugging Face Hubからシミュレーターを使用または公開するEnvHub
LeRobot が CI で管理するベンチマークを追加しますベンチマークの追加

チェックポイントの評価

ローカルでは、LeRobotの隣にシミュレーターをインストールします(LIBEROを参照):

lerobot-eval \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --policy.device=cuda \
  --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --eval.n_episodes=1 --eval.batch_size=1 \
  --output_dir=outputs/eval_libero

Served: 同じ環境でサーバーを起動し(環境のサービングを参照)、そのエンドポイントを追加します:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
lerobot-eval ... --env.server.endpoint=tcp/127.0.0.1:7448

EnvHub環境も同じ仕組みで動作し、--env.type=envhub --env.hub_path=<user/repo> を使用して、そのコードを読み込んだ上で lerobot-env-server --envhub=<user/repo> --trust_remote_code=true --docker=true によって提供されます。

サーバーのすべてのオプションは--env.server.*の下にあり、ローカル実行には適用されません。クライアントは、サーバー設定で指定されている--env.typeに由来するデプロイメント名を要求します。別のデプロイメントを使用するには--env.server.deploymentを渡します。エンドポイントまたはデプロイメントが誤っている場合、--env.server.handshake_timeout_s(10秒)以内に失敗し、そのエンドポイントが提供しているものを示します。TLSで保護されたサーバーに対しては、リモート推論と同様に、そのZenoh JSON5ファイルを--env.server.zenoh_config_pathで渡します。サーバーは、コマンドが記述する環境を実行する必要があります。つまり、同じtype、task、制御規約、シミュレートされた本体(robot_type)です。そうでない場合、評価は開始を拒否し、差分を列挙します。その他の異なるオプション(解像度、エピソード長など)は警告としてログに記録されます。

Observation の名前は環境から取得されます(observation.images.<camera>、observation.state)。チェックポイントが他のカメラ名で学習された場合は、他のロボットと同様に --rename_map でそれらをマッピングし、複数のカメラが同じ形状を持つ場合でも、各カメラのアイデンティティを保持してください。プレースホルダーカメラ(empty_cameras)はチェックポイントに保存されるポリシー設定であり、必要に応じて --policy.empty_cameras で上書きしてください。

最初のステップの前に、リネーム後のすべてのチェックポイント入力が環境内に存在し、状態とアクションの次元数およびRGBチャネル数が一致している必要があります。画像の高さと幅は異なっていても構いません。リサイズはポリシーの事前処理が担当します。コントローラーの規約(デルタアクションと絶対アクション、回転形式)はチェックされません。環境の規約で学習されたチェックポイントを使用してください。

バッチとサーブスループット

各 step() は、バッチ内の未完了のすべての環境を1回ずつ進めます。終了した環境は、次のリセットまでターミナル観測を保持し、他の環境をステップしても再開されません。--eval.use_async_envs=true(デフォルト)の場合、各環境はローカルまたはサーバー上で独自のワーカープロセスとして実行され、バッチは並列でステップされます。サーバーは、バッチあたり最大 max_envs 個の環境(デフォルトは32)を受け入れます。

--env.server.encoding=jpeg(または、--env.server.jpeg_quality(デフォルトは 90)を指定して --robot.env.server.encoding=jpeg)を使用すると、配信されるカメラフレームを JPEG として送信します。これにより、リモートサーバーでは応答サイズが小さくなり、より大きなバッチを処理できますが、エンコード時間と有圧縮フレームというコストが発生します。ローカルホストでは、生フレームの方が高速です。

返信にはバッチ内のすべての環境のフレームが含まれ、両端でmax_payload_bytes(デフォルトは 32 MiB)に収まる必要があります。収まらない場合、サーバーはバッチを開く際に拒否します。大規模なバッチや高解像度のカメラを使用する場合は、サーバー側(YAML のzenohセクションでlisten_endpointsの隣にあるmax_payload_bytes)とクライアント側(--env.server.max_payload_bytesまたは--robot.env.server.max_payload_bytes)で値を引き上げてください。

シミュレーションロボットを実行する

バッチ化された環境やシミュレーションロボットとして使用する場合と同じ環境:

lerobot-eval    --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' ...
lerobot-rollout --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 ...

例えば:

lerobot-rollout \
  --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 \
  --task="pick up the black bowl between the plate and the ramekin and place it on the plate" \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --device=cuda --fps=20 --inference.type=sync \
  --display_data=true --display_mode=rerun \
  --return_to_initial_position=false --play_sounds=false
  • --robot.env.* は、評価における --env.* と同じオプションを受け取ります。--robot.task_id はロボットが実行する1つのタスクを選択しますが、評価ではスイートのすべてのタスク、または --env.task_ids に指定されたタスクが実行されます。EnvHub の環境は --robot.env.type=envhub --robot.env.hub_path=<user/repo> で指定し、ローカルで実行するには --robot.env.trust_remote_code=true を使用します。
  • --robot.env.server.endpoint=tcp/... は、バッチ化された環境に対して --env.server.endpoint が行うのと同様に、環境を env サーバー上で駆動します。ロボットは、そのサーバーがその環境を実行していることを確認します。
  • 各 send_action() は環境をちょうど1ステップだけ進めます。観測の読み取り、ポリシーの推論、および待機はシミュレーションを進めません。既存の制御ループがリアルタイムのペース配分を管理します。
  • --fps は、環境の制御レートに等しくなければなりません。補間を行う場合は、--interpolation_multiplier で割った値に等しくなければなりません。これは、すべてのコマンドが環境を1回進めるためです。録画を行う場合、--dataset.fps は --fps に等しくなければなりません。そうでない場合、ロールアウトは開始を拒否します。

シムロボットはロボットです: --robot.type=sim --robot.env.* を実際のフォロワーの --robot.* に置き換えるだけで、それ以外はそのままです。テレオペレーターは、実際のフォロワーを操作するようにシムロボットを操作します(lerobot/so101-tabletop-mujoco のような SO-101 のツインには --teleop.type=so101_leader を使用)。環境がフォロワーのアクション名と単位を宣言している場合、不一致は最初のアクションで報告されます。

Robot camera features は、実ハードウェアの録画と同じ observation.images.<camera> という名前を使用します。名前が指定されていない単一のカメラは observation.images.image となります。バッチ評価では、単一カメラの場合の observation.image のように、環境自身のキーが保持されます。その名前のチェックポイントをシミュレーションロボットでデプロイする場合は、--rename_map='{"observation.images.image": "observation.image"}' を使用してください。

ポリシーが遅延している場合、シミュレーションロボットを保持しても物理シミュレーションは進行しません。シミュレータの障害は、ロールアウトのシャットダウンに伝播します。

シミュレーションで記録

lerobot-record は、環境が宣言した robot_type(LIBERO の場合は panda、SO-101 のツインの場合は so_follower)を、データセットの本体として保存します。宣言されていない場合は sim_robot が保存されます。

記録されたエピソードは環境のそれに従います。lerobot-recordおよびエピソード単位のロールアウト戦略は、各エピソードの開始時にシミュレーション環境を再起動し、環境のエピソードが終了したとき(成功、終了、またはステップ数の上限に達したとき)またはその期間が満了したとき、いずれか先に起きた時点で終了します。したがって、各記録されたエピソードは、その初期状態からの1つのシミュレーションエピソードになります。手動でのリセットは不要なため、エピソード間のリセットフェーズは--dataset.reset_time_s=0でスキップし、エピソード単位のロールアウト戦略を使用する場合は--strategy.reset_to_initial_position=falseも渡してください。

エピソードが終了すると、ロボットは停止します。アクションは無視され、最終状態が保持されます。また、latest には最終報酬、終了フラグ、成功フラグが保持されます。その後、テレオペレーションとベースのロールアウト戦略が新しいエピソードを開始します(戦略はポリシーもリセットします)。そして、リプレイは停止します。ポリシーで記録するには、エピソード単位のロールアウト戦略を使用してください。実物のロボットには影響がありません。それらのエピソードは時間ベースであり、シーンは手動でリセットされます。成功率を評価するには、lerobot-eval とバッチ化された環境を使用してください。

リモート推論

--robot.*オプションをそのまま維持し、ローカルポリシーおよび推論オプションを以下に置き換えてください。

--inference.type=remote \
--inference.endpoint=tcp/127.0.0.1:7447 \
--inference.deployment=libero \
--inference.semantics=libero-delta-v1

リモート推論セットアップを使用して、ポリシーサーバーを別途起動します。そのスキーマは、--rename_map適用後のロボットの観測値と一致する必要があります。ポリシーサーバーがチェックポイントをロードするため、ロールアウトコマンドから--policy.pathを省略してください。ローカルRTCでは、ポリシーのRTC設定とともに--inference.type=rtcを使用します。

環境をサーブする

LeRobotのソースチェックアウト(イメージはこれからビルドされます)から、リポジトリのルートで実行します:

# An in-tree simulator
lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
# An EnvHub repository, once you have read its code
lerobot-env-server --envhub=<user/repo>@<commit> --trust_remote_code=true --docker=true

--docker=true は docker/sim/compose.server.yaml を使用し、sim.type からイメージを選択します(EnvHub リポジトリからビルドすることもできます)。有効な YAML をマウントし、ホストネットワーク上でコンテナを実行するため、--zenoh.listen_endpoints で指定がない限り、サーバーは localhost:7448 で待ち受けます。別のシミュレーターを選択するには、YAML を差し替えてください。各シミュレーターの制御レート、アクションの規約、コンポーネント名、ロボットタイプは、その統合の conventions()(EnvHub リポジトリの LEROBOT_SIM)から取得されるため、YAML にはタスク名とシミュレーターのオプションのみを指定します。

lerobot-policy-server については、すべての YAML フィールドがネストされたコマンドライン上書きを受け付け、ファイル自体は変更されません。sim.kwargs のような辞書値は、YAML のものにマージされます:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true \
  --sim.task=libero_goal \
  --sim.kwargs='{gym_kwargs: {observation_height: 256, observation_width: 256}}'

有効な設定は$HF_LEROBOT_HOME/sim以下に保存されるため、コンテナを再起動しても検出されます。設定を切り替えるとサーバーが再作成され、アクティブなセッションは終了します。イメージが存在しない場合はビルドされます。シミュレーターやLeRobotのソースを変更した後に再ビルドするには--build=trueを追加し、サーバーを停止するには--stop=trueを追加します。コンテナはEGLレンダリングのためにDockerのGPUアクセスを必要とします。

Vulkan でレンダリングするシミュレーター(Isaac Sim、または RoboMME のように独自の Vulkan ファイルをイメージに同梱している ManiSkill/SAPIEN など)が、Docker 外では動作するのにコンテナ内で vkCreateInstance failed または ERROR_INCOMPATIBLE_DRIVER で失敗する場合、コンテナには NVIDIA ドライバーのライブラリは存在しますが、それらを指すローダーファイル(/usr/share/vulkan/icd.d/nvidia_icd.json、/usr/share/glvnd/egl_vendor.d/10_nvidia.json)が不足しています。gpus: all で使用される NVIDIA Container Toolkit のデフォルトモードではこれらがマウントされない場合がありますが、CDI モードではマウントされます。CDI 経由で GPU を要求してください(docker run では --device nvidia.com/gpu=all、docker/sim/compose.server.yaml では gpus: all の代わりに devices: [nvidia.com/gpu=all] を指定)、またはこれらの 2 つのファイルをイメージに追加してください。

--docker=true を指定しないと、同じコマンドは現在の環境でサーバーを実行します。Python 3.12 以降の隔絶された環境でシミュレーターのネイティブ依存関係をインストールし、--no-deps を付けて LeRobot をインストールし、docker/sim/requirements.txt をインストールします。サーバーは LeRobot の一部であるため、LeRobot と同じ Python が必要です。古い Python のみをサポートするシミュレーターは提供できません。

サーバーが実行される場所

デフォルトでは、接続が暗号化も認証もされないため、サーバーは自機からの接続のみを受け入れます。つまり、サーバーに到達できる者は誰でも環境を操作できてしまうためです。ポリシーを自機で実行しつつ、ワークステーションやGPU付きのクラウドインスタンスなど別のマシンでサーバーを実行するには、自機から到達するネットワークインターフェースのアドレスを--zenoh.listen_endpoints='[tcp/<address>:7448]'として渡し、--env.server.endpoint=tcp/<address>:7448で接続します(シミュレーションロボットの場合は--robot.env.server.endpoint)。この設定は信頼できるネットワーク内に限定するか、リモート推論と同様に、サーバーのYAMLにzenoh.config_fileを、クライアントに--env.server.zenoh_config_pathを追加してTLSとアクセス制御を有効にしてください。低速なリンクでは、JPEGフレームの方が帯域幅を節約できます。

Serverへのリクエストは再試行されません。曖昧なタイムアウトが発生した場合、クライアントは失敗します。その場合は、クライアントを閉じて新しいセッションを開いてください。

シミュレータを追加する

独自の環境を共有するには、EnvHub環境としてHubに公開します。Hubリポジトリ内のenv.pyが統合のすべてであり、このページのすべての機能を利用できます。LeRobotがCIで管理・テストし、ピン留めされたチェックポイントとDockerステージを持つベンチマークは、LeRobot自体に追加されます。ベンチマークの追加を参照してください。

Update on GitHub