LeRobot documentation

重命名地图和空相机

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

重命名地图和空相机

在训练、评估或记录机器人策略时,您的数据集或环境会在一组键(例如 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. 第三个槽位被屏蔽了——您的数据集中无需使用伪造图像。

快速参考

目标该怎么做
数据集键 ≠ 策略键--rename_map='{"dataset_key": "policy_key", ...}'
Env 键 ≠ 策略键(评估)--rename_map='{"env_key": "policy_key", ...}'
使用不同密钥进行 Rollout(推理)--rename_map='{"source_key": "policy_key", ...}'.
相机数量少于策略预期--policy.empty_cameras=N(受 PI0、PI05、PI0Fast、SmolVLA、XVLA 支持)
避免传递重命名映射编辑策略的 config.json,使其键与您的数据源相匹配
Update on GitHub