ベンチマークの追加

ベンチマークは、LeRobotが単一の場所であるlerobot.sim内で操作するシミュレーターであり、すべての使用法で同じ挙動を示すように設計されています: lerobot-eval (バッチ化された環境、--env.type=<benchmark>)、ロールアウトとレコーディング (シミュレーションロボット、--robot.type=sim --robot.env.type=<benchmark>)、ローカルでの実行、または独自のDockerイメージからlerobot-env-serverによって提供される場合です。使用法については、シミュレーション: ローカルまたは提供を参照してください。

追加するもの

どちらのパスも同じ環境の動作を公開します:

native simulator → LocalVectorEnv, locally or on an env server → canonical NumPy observations
  → batched env or sim robot → one-time image/tensor preparation → saved policy preprocessing
  → policy → saved action postprocessing → native simulator

そのシミュレーターのcanonical_observation()アダプターに画像の向き、クォータニオンの変換、状態の順序を、そのconventions()に制御の慣例をそれぞれ配置し、評価とロールアウトが一致するようにします。sim/integrations/utils.pyは、統合間で共有されるマッピングのみに使用してください。共有環境コードは、シミュレーターの名称で分岐してはいけません。新しいベンチマークには環境プロセッサーは不要です。観測は、すでに正規化された状態でポリシー自身のプロセッサーに到達します。

評価の実行方法

lerobot-eval は、すべてのベンチマークを同じ方法で評価します：

1. make_env() は、ネストされた {suite: {task_id: vector env}} 辞書を構築します。
2. eval_policy_all() は、各タスクについてn_episodes回のロールアウトを実行します。タスクは1つずつ（または--env.max_parallel_tasks個同時に）処理されます。
3. 結果はエピソードごと、タスクごと、スイートごと、および全体で集計されます: pc_success（成功率）、avg_sum_reward、およびavg_max_reward。各成功率には、その件数（n_episodes 中の n_success）と、パーセント単位の95% Wilson 信頼区間（pc_success_ci95）が付随します。この区間はエピソード間のサンプリングノイズのみをカバーしており、同じレシピの異なる学習ラン間のばらつきについては何も示していません。

成功は、環境が各 step() で報告する info["is_success"] から得られます。環境は独自の数値も報告できます。それらは info["metrics"] に格納され、各名前を環境ごとの 1 つの float にマッピングするマップです。これらは、エピソードが終了したステップで取得され、各エピソードのエントリである per_episode[i]["metrics"] 配下で利用できます。

環境が備えている必要があるもの

環境の構造

env_fns() は、各タスクの環境ファクトリを構築せずに返します:

def env_fns(
    task: str,
    n_envs: int,
    gym_kwargs: dict | None = None,
) -> dict[str, dict[int, list[Callable[[], gym.Env]]]]:
    """{suite: {task_id: [make_single_env] * n_envs}} for MyBenchmark."""

単一タスクのベンチマークは{"<task>": {0: [...]}}を返し、複数タスクのベンチマーク（LIBEROなど）は{"libero_spatial": {0: [...], 1: [...], ...}, ...}を返します。LocalVectorEnvは初回使用時に各make_single_envファクトリをローカルまたはサーバー上で呼び出し、--eval.use_async_envs=trueを指定した場合は、環境ごとに別のプロセスで呼び出します。

gym.Env

class MyBenchmarkEnv(gym.Env):
    metadata = {"render_modes": ["rgb_array"], "render_fps": <fps>}

    def __init__(self, task_suite, task_id, ...):
        super().__init__()
        self.task = <task_name_string>
        self.task_description = <natural_language_instruction>
        self._max_episode_steps = <max_steps>
        self.observation_space = spaces.Dict({...})
        self.action_space = spaces.Box(low=..., high=..., shape=(...,), dtype=np.float32)

step() は info["is_success"] に成功を報告し、それ以外の測定値は info["metrics"] に格納されます。アクションは 1 次元の連続 Box です。

Observations は、統合の canonical_observation() アダプターが理解する dict です。再利用可能なデフォルトのアダプターは、以下をマッピングします:

その他の配列はobservation.<key>として渡されます。gym.Env内でシミュレーターの出力をこれらのキーにリネームするか、その統合のアダプターでネイティブな表現を処理してください。

GPUベースのシミュレーター（EGLレンダリング付きのMuJoCoなど）: シミュレーターが__init__中にGPU/EGLコンテキストを割り当てている場合、その割り当てを、最初のreset()/step()呼び出し時に実行される_ensure_env()ヘルパーに遅延してください。これにより、ワーカープロセス内で構築された環境が、古いGPUハンドルを継承することを防げます。パターンについてはLiberoEnv._ensure_env()を参照してください。

規約（統合内のconventions()）

conventions(kwargs) から、シミュレータの制御レート、コントローラ、および順序付けられたコンポーネント名を返します。この関数はシミュレータのオプションを引数に取ります（RoboTwin のように、アクションモードに依存する場合があります）。この関数は、設定で指定されていない項目を補完し、ロボット、データセット、チェックポイントにおける状態とアクションのコンポーネントに名前を付けます。semantics のデフォルト値は <type>-<control>-v1 です。robot_type は、シミュレーションロボットによって記録されるシミュレートされた本体の名前です。lerobot にクラスが存在する場合は、実ロボットが記録するタイプ（so_follower）、それ以外の場合は短い名前（panda、sawyer）を指定します。指定しない場合、データセットには sim_robot が記録されます。

設定（src/lerobot/envs/configs.py）

--env.type=<name>（および--robot.env.type=<name>）でユーザーがベンチマークを選択できるように、設定を登録します。そのsim_settings()は、サーバー YAML のsimセクションとしてシミュレーターを記述します。LocalVectorEnvが残りの処理を行います。

@EnvConfig.register_subclass("<benchmark_name>")
@dataclass
class MyBenchmarkEnvConfig(EnvConfig):
    task: str = "<default_task>"
    fps: int = <fps>
    obs_type: str = "pixels_agent_pos"

    @property
    def gym_kwargs(self) -> dict:
        return {"obs_type": self.obs_type}

    def sim_settings(self) -> dict:
        return {"type": "<benchmark_name>", "task": self.task, "kwargs": {"gym_kwargs": self.gym_kwargs}}

デフォルト値とサーバーのYAML設定を一致させます。提供される評価は、コマンドが記述する環境と異なる環境で実行されるサーバーを拒否します。機能は環境が作成される際の記述から取得されるため、設定ファイルでは何も宣言しません。

チェックポイントの承認

--rename_map は、他のロボットと同様に、環境のカメラキーをチェックポイントの学習済みキーにエイリアスします。CI では、benchmarks/benchmarks.yaml のエントリの rename_map から取得されます。リネーム後、チェックポイントの入力が存在し、状態/アクションの次元が一致している必要があります。リネームではチェックポイントのメタデータを修復できません。RGB チャネル数とレイアウトは、受け入れ時にチェックされます。取得時の高さ/幅は、学習メタデータと異なる場合があります。リサイズはポリシーの前処理に属します。

検証とCI

1. 統合の観察アダプターをシミュレーターの生出力と比較して確認し、特にカメラの向きと状態の順序、および環境ラッパーが適用したアクションを確認してください。
2. ローカルとサーブされたシード付きリセット/ステップシーケンスを比較します（scripts/ci/check_sim_parity.py）。決定論的シミュレーターのマニフェストエントリにparity: trueを設定すると、CIで実行されます。ターミナルのフリーズ、成功、エピソード長、レンダリング、リソースのクリーンアップを確認してください。
3. サーバーコードおよびネイティブモジュールに対して、torch無効化されたインポートガードを実行します。RoboTwinやRoboMMEのように、独自のtorchランタイムを必要とするシミュレーターを文書化します。
4. ローカルでlerobot-eval --env.type=<name> --env.task=<task> --eval.n_episodes=1 --policy.path=<checkpoint>を実行し、--env.server.endpointを指定してサーバーに対して実行します。タスクの説明とレンダリングされたカメラビューを確認してください。
5. GPUランナーで生成されたベンチマークジョブを実行します。共有の評価/学習統合を変更する際は、LIBEROの学習スモークテストを維持してください。

benchmarks/benchmarks.yaml は scripts/ci/benchmark_matrix.py によってマトリックスを生成します。.github/workflows/benchmark_run.yml が各エントリを実行します。CI ジョブをコピーするのではなく、マニフェストにエントリを追加してください。CI はパイプラインをエンドツーエンドで確認するため、エピソード数を上限設定しています。その metrics.json は、チェックポイントのリビジョン、シミュレータのイメージタグ、コミット、上限値を記録し、これらの実行を smoke とマークします。これらの成功率はポリシーのスコアではありません。シミュレータのイメージには個別のピン留めとコンテンツタグがあります。BuildKit のキャッシュは、永続的なランナーでのみ保持されます。

ベンチマークの変更

統合のcanonical_observation()、conventions()および環境ラッパーは、ポリシーが何を見るか、そしてそのアクションがどのように適用されるかを決定します。画像の向き、状態の順序、制御レートが誤っていてもクラッシュはしません。ポリシーはわずかに誤った入力を参照し、その成功率が低下します。これらのいずれかを変更する場合、以下が伴います：

• 回帰テストは、記録済みまたは合成された観測データに対して、旧バージョンと新バージョンの出力を比較します。tests/sim/integrations/test_libero.py 内の test_libero_numpy_adapter_parity がそのモデルです。このテストは、torch を使用しない LIBERO アダプターが、以前の LIBERO プロセッサと完全に同じ出力を生成することを示しています。
• プルリクエストにおけるスコアへの想定される影響：なし、またはどのスコアがどのように変化するか、その理由。

依存関係 (pyproject.toml)

ローカル利用用の新しいオプション依存関係グループを追加します:

mybenchmark = ["my-benchmark-pkg==1.2.3", "lerobot[scipy-dep]"]

ピン留めルール:

• 常に固定してください。再現性を確保するために、ベンチマーク用のパッケージは正確なバージョンに固定してください（例: metaworld==3.0.0）。
• 必要に応じて（例: ; sys_platform == 'linux'）、プラットフォームマーカーを追加します。
• 既知の脆弱なトランジティブ依存関係は、ピン留めしてください（例: Meta-World イメージでは、MuJoCo 3.17 がモーションキャプチャのウェルドを壊すため、mujoco==3.15.0がピン留めされています）。
• ベンチマークのドキュメントページにドキュメントの制約を記載してください。依存関係がLeRobotのものと競合する場合、サポートされるパスが提供されます。

ベンチマークのドキュメントページの作成

docs/source/_toctree.ymlの“Benchmarks”セクションにページを追加します。各ベンチマークページには、以下を含める必要があります：

• タイトルと説明 — ベンチマークが何をテストし、なぜそれが重要であるかについての1〜2段落。
• リンク — 論文、GitHubリポジトリ、プロジェクトのウェブサイト（利用可能な場合）。
• 出典とライセンス — ソースリポジトリ、固定されたコードおよびアセットのリビジョン、それぞれのライセンス。ライセンスの使用を禁止しているベンチマークを追加しないでください。
• 概要の画像またはGIF。
• 利用可能なタスク — タスクスイートの数と簡単な説明をまとめた表。
• インストール — pip install -e ".[<benchmark>]"、またはサーバーコマンド。
• 評価 — 再現可能な結果を得るために、n_episodes を指定した推奨の lerobot-eval コマンド。
• ポリシーの入力と出力 — 形状付きの観測キー、アクション空間の説明。
• 学習 — lerobot-train コマンドの例。
• 参照結果 — 実行可能な事前学習済みチェックポイントの少なくとも1つについて、そのリビジョンと、lerobot-eval コマンドを用いて再現できる公開済みの成功率です。この値の近傍に到達しない統合は、完成したとはみなされません。

完全な例については、docs/source/libero.mdxおよびdocs/source/metaworld.mdxを参照してください。