重命名地图和空相机

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

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

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

策略的预训练配置中内置了一组固定的输入特征名称。例如：

• 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。

训练

假设您在包含 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，使其观测键与你的数据源相匹配。这样就不需要重命名映射了。

权衡：修改策略配置会将其绑定到单一数据源。而使用重命名映射表，可以让同一策略在多个数据集和环境中复用。

空摄像头：视图数量少于策略预期

某些策略是为固定数量的图像输入而设计的。如果您的数据集中的相机数量较少，可以在策略配置中设置 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. 第三个槽位被屏蔽了——您的数据集中无需使用伪造图像。

快速参考