重命名映射和空相机

当你使用机器人策略进行训练、评估或记录时，你的数据集或环境在一组键下提供观测（例如 observation.images.front、observation.images.eagle），而你的策略期望另一组键（例如 observation.images.image、observation.images.image2）。重命名映射在不更改策略或数据源的情况下弥合了这一差距。

范围： 重命名映射仅重命名观测键（图像和状态）。动作键不受影响。

为什么观测键并不总是匹配

策略有一组固定的输入特征名称，这些名称嵌入在其预训练配置中。例如：

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 字典，将源键映射到策略期望的键。重命名发生在预处理器管道内部，因此策略始终看到其期望的键。

使用重命名映射

在命令行上将映射作为 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"}'

替代方案：直接编辑策略配置

如果你总是使用相同的数据集或环境，可以编辑策略的 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。你的数据集只有两个相机：

设置 --policy.empty_cameras=1。
配置添加第三个键：observation.images.empty_camera_0。
像往常一样为你的两个真实相机使用重命名映射。
第三个槽被掩码掉——你的数据集中不需要假图像。

快速参考

目标	操作
数据集键 ≠ 策略键	`--rename_map='{"dataset_key": "policy_key", ...}'`
环境键 ≠ 策略键（评估）	`--rename_map='{"env_key": "policy_key", ...}'`
使用不同键进行推出（推理）	`--rename_map='{"source_key": "policy_key", ...}'`.
相机少于策略期望的数量	`--policy.empty_cameras=N`（PI0、PI05、PI0Fast、SmolVLA、XVLA 支持）
避免传递重命名映射	编辑策略的 `config.json`，使其键与你的数据源匹配