重命名映射與空攝影機

當您使用機器人策略進行訓練、評估或錄製時，您的資料集或環境所提供的觀測值（observations）通常採用一套鍵值（例如 observation.images.front, observation.images.eagle），而您的策略 (policy) 卻預期另一套鍵值（例如 observation.images.image, observation.images.image2）。重命名映射 (rename map) 可以在不更動策略或資料來源的情況下，填補這兩者之間的落差。

範圍：重命名映射僅會重新命名觀測值的鍵（影像與狀態）。動作鍵 (action keys) 不受影響。

為什麼觀測值鍵值不總是相符

策略在預訓練的設定檔中會固定一套輸入特徵名稱。例如：

• 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），而您的評估環境可能又使用另一套名稱。與其修改策略設定檔或重新命名資料集中的欄位，您可以傳入一個重命名映射：這是一個 JSON 字典，負責將來源鍵對應至策略所預期的鍵。重新命名會發生在預處理管線 (preprocessor pipeline) 內部，因此策略始終能看到它所預期的鍵。

使用重命名映射

請在命令列以 JSON 字串的形式傳入映射。慣例始終是：

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

其中 source_key 是資料集或環境提供的名稱，而 policy_key 是策略所預期的名稱。

只有列出的鍵會被重新命名；其餘內容將不受影響地傳遞。條目的順序並不重要。

支援的策略：PI0、PI05、PI0Fast、SmolVLA 和 XVLA。

訓練

假設您在一個資料集上微調 lerobot/xvla-base，其影像分別位於 observation.images.front、observation.images.eagle 和 observation.images.glove。而 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"}'

錄製

lerobot-record 也支援重命名映射，並嵌套在資料集設定中。

lerobot-record \ # When running inference
  --policy.path="<user>/smolVLA_finetuned" \
  ... \
  --dataset.rename_map='{"observation.images.glove2": "observation.images.image"}'

替代方案：直接編輯策略設定檔

如果您總是使用相同的資料集或環境，您可以直接編輯策略的 config.json，使其觀測鍵與您的資料來源相符。這樣就不需要重命名映射了。

取捨：修改策略設定檔會將該策略綁定至單一資料來源。而使用重命名映射則可讓單一策略在多個資料集與環境間通用。

空攝影機：視角數少於策略預期

有些策略是為固定數量的影像輸入所設計的。如果您的資料集攝影機數量較少，您可以在策略設定中設定 empty_cameras，而無需修改模型架構。

運作方式

設定 empty_cameras=N 會在策略設定檔中加入 N 個佔位符影像特徵，名稱如下：

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

在執行時，這些鍵在批次中沒有對應的資料。策略會使用遮罩後的虛擬張量（對於基於 SigLIP 的視覺編碼器會填充 -1，並帶有零注意力遮罩）來填補這些位置，因此在訓練和推論時，這些額外的影像槽位會被有效忽略。

範例

XVLA-base 預設有三個視覺輸入且 empty_cameras=0。而您的資料集只有兩個攝影機：

1. 請設定 --policy.empty_cameras=1。
2. 此設定會新增第三個鍵：observation.images.empty_camera_0。
3. 針對您的兩個真實攝影機，正常使用重命名映射即可。
4. 第三個插槽會被遮罩遮蔽 — 您不需要在資料集中準備假影像。

快速參考