# MapとEmpty Camerasの名前を変更

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

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

## 観察キーが常に一致しない理由

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

- [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero) は `observation.images.base_0_rgb` と `observation.images.left_wrist_0_rgb` を期待します。
- [xvla-base](https://huggingface.co/lerobot/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](https://huggingface.co/lerobot/xvla-base) をファインチューニングしたとします。XVLA は `observation.images.image`、`observation.images.image2`、`observation.images.image3` を期待します:

```bash
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](https://huggingface.co/lerobot/pi0fast-libero)）に対して、LIBERO環境が `observation.images.image` と `observation.images.image2` を返す場合:

```bash
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番目のスロットはマスクされています。データセットにダミーの画像は不要です。

## クイックリファレンス

| 目標                                    | 対処方法                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Datasetキー ≠ policyキー              | `--rename_map='{"dataset_key": "policy_key", ...}'`                         |
| Envキー ≠ ポリシーキー（評価）           | `--rename_map='{"env_key": "policy_key", ...}'`                             |
| 異なるキーでのロールアウト（推論） | `--rename_map='{"source_key": "policy_key", ...}'`.                         |
| ポリシーが想定するカメラ数より少ない       | `--policy.empty_cameras=N`（PI0、PI05、PI0Fast、SmolVLA、XVLAでサポート） |
| リネームマップの渡し方を避ける              | ポリシーの`config.json`を編集し、キーがデータソースと一致するようにしてください          |