# 重命名地图和空相机

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

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

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

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

- [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`），而您的评估环境可能又使用另一组名称。与其修改策略配置或重命名数据集中的列，不如传入一个 **重命名映射**：一个将源键映射到策略所期望键的 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`**，使其观测键与你的数据源相匹配。这样就不需要重命名映射了。

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

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

某些策略是为固定数量的图像输入而设计的。如果您的数据集中的相机数量较少，可以在策略配置中设置 **`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`，使其键与您的数据源相匹配          |