MapとEmpty Camerasの名前を変更

ロボットポリシーで学習、評価、または記録を行う場合、データセットまたは環境は特定のキーセット（例: observation.images.front、observation.images.eagle）で観測値を提供しますが、ポリシーは別のキーセット（例: observation.images.image、observation.images.image2）を期待します。リネームマップは、ポリシーやデータソースを変更することなく、このギャップを埋めます。

スコープ: 名前変更マップはobservationキー（画像と状態）のみを名前変更します。アクションキーには影響しません。

なぜ観測キーが常に一致しないのか

Policiesには、事前学習済み設定に組み込まれた固定の入力特徴量名のセットがあります。例えば:

• pi0fast-libero は observation.images.base_0_rgb と observation.images.left_wrist_0_rgb を期待します。
• xvla-base は observation.images.image、observation.images.image2、および observation.images.image3 を期待します。

データセットではまったく異なる名前（例: observation.images.front、observation.images.eagle、observation.images.glove）が使用されている場合があり、評価環境ではさらに別のセットが使用されている可能性があります。ポリシーの構成を編集したり、データセットの列名を変更したりする代わりに、rename map（ソースキーをポリシーが期待するキーにマッピングする JSON 辞書）を渡します。リネームはプリプロセッサのパイプライン内で実行されるため、ポリシーは常に期待されるキーを確認できます。

リネームマップの使用

マッピングをJSON文字列としてコマンドラインに渡します。慣例は常に以下の通りです:

--rename_map='{"source_key": "policy_key", ...}'

ここで、source_keyはデータセットまたは環境が提供するものであり、policy_keyはポリシーが期待するものです。

リストに列挙されたキーのみがリネームされ、それ以外は変更なしでそのまま渡されます。エントリの順序は重要ではありません。

サポートされているポリシー: PI0、PI05、PI0Fast、SmolVLA、XVLA。

トレーニング

observation.images.front、observation.images.eagle、observation.images.glove 以下の画像を含むデータセットで lerobot/xvla-base をファインチューニングしたとします。XVLA は observation.images.image、observation.images.image2、observation.images.image3 を期待します:

lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/xvla_training \
  --job_name=xvla_training \
  --policy.path="lerobot/xvla-base" \
  --policy.repo_id="HF_USER/xvla-your-robot" \
  --policy.dtype=bfloat16 \
  --policy.action_mode=auto \
  --steps=20000 \
  --policy.device=cuda \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true \
  --rename_map='{"observation.images.front": "observation.images.image", "observation.images.eagle": "observation.images.image2", "observation.images.glove": "observation.images.image3"}'

評価

observation.images.base_0_rgb と observation.images.left_wrist_0_rgb を期待するポリシー（例: pi0fast-libero）に対して、LIBERO環境が observation.images.image と observation.images.image2 を返す場合:

lerobot-eval \
  --policy.path=lerobot/pi0fast-libero \
  --env.type=libero \
  ... \
  --rename_map='{"observation.images.image": "observation.images.base_0_rgb", "observation.images.image2": "observation.images.left_wrist_0_rgb"}'

代替案: ポリシー設定を直接編集する

常に同じデータセットまたは環境を使用する場合は、ポリシーのconfig.jsonを編集して、観測キーがデータソースと一致するように設定できます。そうすれば、リネームマップは不要になります。

トレードオフ: ポリシー設定を変更すると、それが1つのデータソースに固定されてしまいます。リネームマップを使用することで、1つのポリシーを多数のデータセットや環境で使い回すことができます。

空のカメラ: ポリシーが期待するビュー数より少ない

一部のポリシーは、固定数の画像入力用に構築されています。データセットのカメラ数が少ない場合は、モデルのアーキテクチャを変更する代わりに、ポリシー設定でempty_camerasを設定できます。

仕組み

empty_cameras=N を設定すると、ポリシー設定に N 個のプレースホルダー画像機能が追加され、以下のように命名されます:

observation.images.empty_camera_0
observation.images.empty_camera_1
...

実行時、これらのキーにはバッチ内に対応するデータがありません。ポリシーは、マスク付きのダミーテンソル（SigLIPベースのビジョンエンコーダーの場合は-1でパディングし、ゼロのアテンションマスクを使用）でこれらを埋めるため、追加の画像スロットは学習および推論中に実質的に無視されます。

例

XVLA-baseには3つの視覚入力があり、デフォルトではempty_cameras=0です。あなたのデータセットには2つのカメラしかありません:

1. --policy.empty_cameras=1を設定します。
2. configには3番目のキーobservation.images.empty_camera_0が追加されます。
3. 2つの実際のカメラについては、通常どおりリネームマップを使用してください。
4. 3番目のスロットはマスクされています。データセットにダミーの画像は不要です。

クイックリファレンス