# VLA-JEPA

这是 **VLA-JEPA** 的 LeRobot 移植版本，该视觉-语言-动作模型结合了 Qwen3-VL 语言骨干、自监督视频世界模型（V-JEPA2）以及流匹配 DiT 动作头。

---

## 架构概览

VLA-JEPA 包含三个主要组件：

| 组件               | 模块                            | 角色                                                    |
| ----------------------- | --------------------------------- | ------------------------------------------------------- |
| **Qwen3-VL 主干网络**   | `Qwen3VLInterface`                | 将图像和语言指令融合为上下文标记 |
| **DiT-B 动作头**   | `VLAJEPAActionHead`               | 针对动作块的流匹配扩散           |
| **V-JEPA2 世界模型** | `ActionConditionedVideoPredictor` | 自监督视频预测损失（仅用于训练）   |

### 数据流

**训练：**

1. 由 `num_video_frames` 帧组成的视频片段会被 V-JEPA2 编码为逐帧的 patch token。
2. Qwen3-VL 骨干网络处理多视角图像和任务指令，并生成一个上下文标记序列，其中包含特殊动作标记（用于世界模型的条件输入）和具身标记。
3. 动作头将这些上下文标记作为交叉注意力的键/值，并通过流匹配预测去噪后的动作块。
4. 世界模型预测器使用从 Qwen 中提取的动作 token 来预测未来的 V-JEPA2 帧嵌入；在这些预测上计算的回归损失会被加到动作损失中。

**推理：**仅使用 Qwen 和动作头。推理时不需要世界模型。

### Action head 详情

通过 `action_model_type` 可用的预设：

| 预设  | 注意力头 | Head dim |
| ------- | ----- | -------- |
| `DiT-B` | 12    | 64       |
| `DiT-L` | 32    | 48       |

该预设仅设置注意力几何结构，且每个条目都可以通过 `action_num_heads` / `action_attention_head_dim` 进行覆盖。由此可推导出两个宽度：

- DiT 的 **内部**宽度为 `heads x head_dim`（对于 `DiT-B` 为 768），该值由推导得出而非直接配置；
- DiT 的 **输出**宽度，以及动作解码器和状态编码器 MLP 的宽度，均为 `action_hidden_size`（默认值为 1024）。

因此，`DiT-B` 运行一个宽度为 768 的 Transformer，并将其投影到 1024。这两者是相互独立的。

### 世界模型详情

视频预测器是一个 ViT 风格的 Transformer（`ActionConditionedVideoPredictor`），它接受：

- **帧标记**：投影到 `predictor_embed_dim` 的 V-JEPA2 块嵌入
- **动作标记**：投影到 `predictor_embed_dim` 的 Qwen 动作标记嵌入

它采用块因果注意力机制，使每个时间步都能关注所有之前的时间步。预测器的输入 `embed_dim` 等于 `num_views × video_encoder_hidden_size`（例如，预训练检查点中为 2 个视角 × 1024 = 2048）。

---

## 预训练检查点

LeRobot 组织内直接提供了三个检查点：[`lerobot/VLA-JEPA`](https://huggingface.co/collections/lerobot/vla-jepa)，由 [ginwind/VLA-JEPA](https://huggingface.co/ginwind/VLA-JEPA) 转换而来：

| 检查点                    | 数据集           | 相机                 | 世界模型 | 动作维度 |
| ----------------------------- | ----------------- | ----------------------- | ----------- | ---------- |
| `lerobot/VLA-JEPA-LIBERO`     | LIBERO-10         | 2（agentview + wrist）   | 已启用     | 7          |
| `lerobot/VLA-JEPA-Pretrain`   | DROID 1.0.1       | 2（外部左侧视图） | 已启用     | 7          |
| `lerobot/VLA-JEPA-SimplerEnv` | OXE 桥接 / RT-1 | 1（视图重复 ×2）  | 已启用     | 7          |

所有检查点均使用 `Qwen/Qwen3-VL-2B-Instruct` 作为语言骨干。

---

## 配置

`VLAJEPAConfig` 中的关键参数：

| 参数                    | 默认       | 描述                                                                                                                                                                                                                                                |
| ---------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chunk_size`                 | 7             | 每次推理调用预测的动作数量                                                                                                                                                                                                             |
| `n_action_steps`             | 7             | 在重新规划之前，从预测块中执行的步骤                                                                                                                                                                                                 |
| `num_video_frames`           | 8             | 输入世界模型的                                                                                                                                                                                                                   |
| `enable_world_model`         | `True`        | 是否加载并训练 V-JEPA2 预测器                                                                                                                                                                                                            |
| `world_model_loss_weight`    | 0.1           | JEPA 预测损失相对于动作损失的权重                                                                                                                                                                                             |
| `causal_world_model_context` | `False`       | 以因果方式编码世界模型上下文（每个上下文位置仅执行一次前缀 V-JEPA2 前向传播），以防止双向注意力将未来帧泄漏到预测器输入中。这会额外产生 `t_enc_ctx` 次编码器调用                                            |
| `num_inference_timesteps`    | 4             | 用于动作去噪的欧拉积分步骤                                                                                                                                                                                                               |
| `freeze_qwen`                | `False`       | 冻结 Qwen3-VL 主干网络，仅训练动作头                                                                                                                                                                                                |
| `reinit_modules`             | `None`        | 在加载时允许随机重新初始化的关键前缀（用于跨本体迁移，请参阅 [在不同本体上进行微调](#fine-tuning-on-a-different-embodiment)）                                                                            |
| `resize_images_to`           | `None`        | `(height, width)` 是送入 Qwen3-VL 视觉塔之前，每个相机帧被调整到的尺寸。`None` 表示保留原始分辨率，此时 Qwen3-VL 的 patch 数量会随之增加，因此 720x1280 的相机可能会耗尽 GPU 显存。已发布的检查点使用的是 `[224, 224]` |
| `gripper_dim`                | 6             | 动作向量中夹爪维度的索引。当 `gripper_joint_names` 与数据集动作名称匹配时，此参数将被忽略                                                                                                                                      |
| `gripper_joint_names`        | `["gripper"]` | 用于标识夹爪的动作维度名称；匹配到的索引优先于 `gripper_dim`                                                                                                                                                                  |
| `gripper_threshold`          | 0.5           | `pre_snap_gripper_action` 和 `binarize_gripper_action` 使用的阈值。请注意，`binarize` 在反归一化_之后_运行，因此该值是与夹爪的物理值进行比较的                                                                          |
| `pre_snap_gripper_action`    | `False`       | 在反归一化之前，将夹爪维度截断到 {0, 1}。这是 LIBERO 特有的，详见下文                                                                                                                                                                          |
| `binarize_gripper_action`    | `False`       | 在反归一化之后，将夹爪维度二值化为 {-1, 1}。这是 LIBERO 特有的，详见下文                                                                                                                                                                      |
| `clip_normalized_actions`    | `True`        | 在反归一化之前，将归一化后的动作裁剪到 [-1, 1] 范围内。仅当 `ACTION` 使用 `MIN_MAX` 时生效；在 `MEAN_STD` 下会被忽略（并给出警告），因为在该模式下裁剪会在 1 个标准差处截断。                                                                          |
| `world_model_num_views`      | `None`        | 相机视角，即世界模型预测器所针对的视角。已固化到检查点的形状中。`None` 会回退到 `jepa_tubelet_size`，这也是已发布的检查点所编码的内容                                                                                |

`pre_snap_gripper_action` 和 `binarize_gripper_action` 是 starVLA LIBERO 评估循环的移植版本，仅适用于 LIBERO 的动作约定。`pre_snap` 会将 {0, 1} 写入 _normalized_ 空间，反归一化器将这些值映射到中点和最大值，随后 `binarize` 将该 **physical** 值与 `gripper_threshold`（0.5）进行比较。对于以度、毫米或 [0, 100] 为单位的夹爪，这两个值都会落在阈值之上，导致指令夹爪变为常数。因此，它们的默认值为 `False`；仅在 LIBERO 风格的设置中启用它们，如果启用，请在夹爪自身的单位下设置 `gripper_threshold`。当数据集统计信息显示该范围无法工作时，处理器工厂会发出警告。

---

## 训练

训练步数可能会根据数据集大小和计算预算而有所不同。原始论文先在 ssv2 + droid 上联合预训练 50k 步，然后针对 LIBERO 额外训练 30k 步，但从提供的预训练检查点进行微调时，较少的步数仍可能获得良好的性能。

### 从头开始完整训练

```bash
lerobot-train \
  --policy.type=vla_jepa \
  --policy.repo_id=your_org/your_repo \
  --dataset.repo_id=your_org/your_dataset
```

### 从预训练检查点微调

```bash
lerobot-train \
  --policy.path=lerobot/VLA-JEPA-Pretrain \
  --policy.repo_id=your_org/your_repo \
  --dataset.repo_id=your_org/your_dataset
```

如果希望冻结 Qwen 主干网络并仅训练动作头，请设置 `policy.freeze_qwen=True`：

```bash
lerobot-train \
  --policy.path=lerobot/VLA-JEPA-Pretrain \
  --policy.repo_id=your_org/your_repo \
  --policy.freeze_qwen=true \
  --dataset.repo_id=your_org/your_dataset
```

### 在另一种具身形态上进行微调

当目标机器人的动作或状态维度与预训练检查点不同时，动作头的输入/输出投影层将出现形状不匹配，无法直接加载。`reinit_modules` 允许您列出允许形状不匹配的键前缀——这些层将被随机重新初始化，而其他所有权重则从检查点中复用。在所列前缀之外的任何形状不匹配都会引发错误。

依赖于 `action_dim` 和 `state_dim` 的层是：

| 层                                     | 键前缀                          |
| ----------------------------------------- | ----------------------------------- |
| 动作编码器（action_dim → inner_dim）   | `model.action_model.action_encoder` |
| 动作解码器（hidden_size → action_dim） | `model.action_model.action_decoder` |
| 状态编码器（state_dim → inner_dim）     | `model.action_model.state_encoder`  |

```bash
lerobot-train \
  --policy.path=lerobot/VLA-JEPA-Pretrain \
  --policy.repo_id=your_org/your_repo \
  --policy.freeze_qwen=true \
  --policy.reinit_modules='["model.action_model.action_encoder", "model.action_model.action_decoder", "model.action_model.state_encoder"]' \
  --dataset.repo_id=your_org/your_dataset
```

如果您的机器人没有本体感觉状态，请从列表中省略 `model.action_model.state_encoder`。

### 复现 LIBERO 的结果

**在 LIBERO 上训练：**从 Pretrain 检查点开始训练，在 LIBERO 数据集上训练 30k 步。原始论文提到在 8 个 GPU 上训练，批大小为 32，即全局批大小为 256。

```bash
lerobot-train \
  --policy.path=lerobot/VLA-JEPA-Pretrain \
  --policy.repo_id=your_org/your_repo \
  --dataset.repo_id=HuggingFaceVLA/libero \
  --steps=30000
```

**评估预训练的 LIBERO-10 检查点：**

```bash
lerobot-eval \
  --policy.path=lerobot/VLA-JEPA-LIBERO \
  --env.type=libero \
  --env.task=libero_spatial,libero_object,libero_goal,libero_10 \
  --eval.n_episodes=10 \
  --eval.batch_size=5
```

仅评估部分任务：

```bash
lerobot-eval \
  --policy.path=lerobot/VLA-JEPA-LIBERO \
  --env.type=libero \
  --env.task=libero_10 \
  --env.task_ids='[0,1,2]' \
  --eval.n_episodes=10 \
  --eval.batch_size=5
```

**预期结果：**

| 套件          | 剧集 | 成功 | 成功率 |
| -------------- | -------- | --------- | ------------ |
| libero_spatial | 100      | 93        | **95.0%**    |
| libero_object  | 100      | 100       | **100.0%**   |
| libero_goal    | 100      | 98        | **98.0%**    |
| libero_10      | 100      | 96        | **93.0%**    |
| **总体**    | **400**  | **387**   | **96.5%**    |

---

## 在相机数量不同的数据集上进行微调

预训练的世界模型预测器使用 `embed_dim = world_model_num_views × 1024` 进行训练，即两个相机视角。

此视图数量过去是从 `jepa_tubelet_size` 读取的，该参数同时也用于命名 JEPA 编码器的 _时间_ 管体大小。现在该字段由 `world_model_num_views` 表示；将其保留为 `None` 时会回退到 `jepa_tubelet_size`，从而确保已发布的检查点能够保持不变地继续加载。

**默认行为 — 查看填充/裁剪（无需操作）**

从 `VLA-JEPA-Pretrain` 进行微调时，模型会自动调整输入世界模型的视图数量，以匹配 `world_model_num_views`：

- **单视角数据集（例如 BridgeV2）：**将单视角潜在表示复制以生成双视角世界模型输入，从而在不产生任何权重失配的情况下保留 JEPA 自监督信号。
- **>2 视角数据集（例如包含 3 个视角的 DROID）：**所有视角都会传入 Qwen 主干网络（以提供更丰富的上下文），但仅前 `world_model_num_views` 个视角（一个腕部视角 + 一个第三人称视角，遵循已配置的视角顺序）会被用于世界模型。

**选项 1 — 禁用世界模型**

设置 `enable_world_model=False` 以完全跳过 JEPA 损失。此时仅加载并训练 Qwen 骨干网络和操作头。这对于获得良好的操作性能已经足够。

```bash
lerobot-train \
  --policy.path=lerobot/VLA-JEPA-Pretrain \
  --policy.enable_world_model=false \
  --policy.repo_id=your_org/your_repo \
  --dataset.repo_id=your_org/single_camera_dataset
```

**选项 2 — 重新初始化预测器输入投影**

如果要将 `world_model_num_views` 更改为 2 以外的值，请使用 `strict=False` 加载检查点，并根据新的 `embed_dim` 重新初始化 `model.video_predictor.predictor_embed`。其他所有预测器块权重（注意力、MLP、归一化、输出投影）均与相机数量无关，可以直接复用预训练检查点中的权重。

---

## 引用

```bibtex
@misc{sun2026vlajepaenhancingvisionlanguageactionmodel,
  title         = {VLA-JEPA: Enhancing Vision-Language-Action Model with Latent World Model},
  author        = {Jingwen Sun and Wenyao Zhang and Zekun Qi and Shaojie Ren and Zezhi Liu and Hanxin Zhu and Guangzhong Sun and Xin Jin and Zhibo Chen},
  year          = {2026},
  eprint        = {2602.10098},
  archivePrefix = {arXiv},
  primaryClass  = {cs.RO},
  url           = {https://arxiv.org/abs/2602.10098},
}
```

---

## 许可证

权重遵循原始 [ginwind/VLA-JEPA](https://huggingface.co/ginwind/VLA-JEPA) 仓库的许可条款（**Apache 2.0 License**）。LeRobot 集成代码遵循 **Apache 2.0 License**。

