# WALL-OSS

WALL-OSS 是一个用于具身智能的开源基础模型，由 [XSquare Robot](https://x2robot.com/en/research/68bc2cde8497d7f238dde690) 团队于 2025 年提出。LeRobot 的实现改编自其开源的 [WallX](https://github.com/X-Square-Robot/wall-x) 仓库。

X Square Robot 的 WALL-OSS 现已集成到 Hugging Face 的 LeRobot 生态系统中。这是 LeRobot 团队与 X Square Robot 团队之间一项令人兴奋的协作项目。现在，您可以直接通过 LeRobot 对 WALL-OSS 进行后训练、评估和部署。借此，我们旨在让开源机器人社区能够更轻松地定制和部署 WALL-OSS 基础模型。阅读并探索 WALL-OSS 的 [论文](https://arxiv.org/pdf/2509.11766) 和 [代码](https://github.com/X-Square-Robot/wall-x)。

## 模型概览

WALL-OSS 团队正在构建具身基础模型，以捕获并压缩世界上最有价值的数据：连续、高保真的物理交互流。通过在模型的决策与身体的实际体验之间建立直接的反馈回路，使得真正可泛化的智能得以涌现——这种智能不仅理解世界如何运作，还知道如何在其中有效行动。

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/walloss-lerobot-paper.png"
  alt="An overview of WALL-OSS"
  width="85%"
/>

从技术层面来看，WALL-OSS 引入了一种紧密耦合的多模态架构（紧密耦合的 MoE 结构），该架构融合了离散和连续的动作建模策略。通过两阶段训练流程（Inspiration → Integration），模型逐步统一了语义推理和高频动作生成。其核心创新包括：

- **具身感知增强的多模态预训练**：在统一的视觉-语言-动作数据上进行大规模训练，以增强空间、因果和操作理解能力。
- **统一跨层级思维链（Uni-CoT）**：一个可微分的统一框架，整合了高层指令推理、子任务分解和细粒度动作合成，形成从“理解”到“执行”的连续链条。
- **混合专家（MoE）动作头**：根据任务阶段动态激活专家，并在离散或连续空间中建模动作，以维持稳定的 VLM 先验。
- **两阶段训练范式**：
  - **灵感阶段**：注入离散动作先验，以增强空间理解并实现语义与动作的对齐。
  - **集成阶段**：使用 flow matching 实现高频连续控制。

## 安装要求

1. 按照我们的[安装指南](./installation)安装 LeRobot。
2. 运行以下命令安装 WallX 依赖项：

   ```bash
   pip install -e ".[wallx]"
   ```

## 用法

要在 LeRobot 中使用 WallX，请将策略类型指定为：

```python
policy.type=wall_x
```

### 文本生成与交互式控制

WALL-OSS 通过 [Bring your own policy](./bring_your_own_policies#text-capable-policies) 中的策略契约暴露原生文本生成功能。在运行 WALL-OSS 的常规输入流水线之前，运行时提供 `query_kind`，调用方提供 `query_text`：

```python
request = {
    **observation,
    "query_kind": "vqa",
    "query_text": "Which object is closest to the right gripper?",
}
processed_batch = preprocessor(request)
answer = policy.generate_text(processed_batch)
```

`vqa` 将问题保留为用户负载。`next_subtask` 在 `${subtask}` 之前应用检查点配方。WALL-X 直接覆盖其 Qwen 视觉语言专家的公开 `generate_text(processed_batch)` API，并通过 `supports_text_generation()` 报告该能力。

交互式语言运行时可以生成一个子任务，然后基于该子任务来条件化 WALL-OSS 的动作预测：

```bash
lerobot-rollout \
  --strategy.type=base \
  --policy.path=your-org/your-wall-oss-checkpoint \
  --robot.type=your_robot_type \
  --robot.port=/dev/your_robot_port \
  --task="clear the table" \
  --interactive=true
```

在 `/start` 之后，使用 `/vqa <question>` 进行基于图像的 VQA，或使用 `/autosteer <goal>` 进行基于配方的下一子任务生成。`/subtask <text>` 会跳过生成过程，直接将指令发送到动作推理。

## 训练

要训练 WallX，您可以使用标准的 LeRobot 训练脚本并配置相应的参数：

```bash
lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=wall_x \
    --output_dir=./outputs/wallx_training \
    --job_name=wallx_training \
    --policy.repo_id=your_repo_id \
    --policy.pretrained_name_or_path=x-square-robot/wall-oss-flow \
    --policy.prediction_mode=diffusion \
    --policy.attn_implementation=eager \
    --steps=3000 \
    --policy.device=cuda \
    --batch_size=32
```

### 使用语言注释进行训练

WALL-X 使用其内置的配方从 LeRobot 的可选语言列进行训练。仅在需要替换该配方时，才设置 `recipe_path`：

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_language_annotated_dataset \
  --policy.type=wall_x \
  --policy.pretrained_name_or_path=x-square-robot/wall-oss-flow \
  --policy.text_loss_weight=0.01 \
  --policy.flow_loss_weight=1.0 \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

定向的助手轮次接收下一词元交叉熵，而 `low_level` 配方流接收连续流动作监督。一行可能接收其中一种目标或两者兼有。用户提示、图像、本体感觉、动作查询词元以及填充均不计入文本损失。将 `policy.recipe=null` 设置为 null 以使用 WALL-OSS 的原始仅动作训练路径。

有关注释模式和可用配方，请参阅 [语言列和配方](./language_and_recipes)。

### 训练参数

| 参数                           | 描述                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dataset.repo_id`                | 您的训练数据集的 Hugging Face Hub 仓库 ID（例如，`lerobot/aloha_sim_insertion_human`）                                                      |
| `--policy.type`                    | 指定使用 WallX 策略架构                                                                                                                 |
| `--output_dir`                     | 用于保存训练检查点和日志的本地目录                                                                                             |
| `--job_name`                       | 此训练运行的名称标识符（用于日志记录/跟踪）                                                                                            |
| `--policy.repo_id`                 | 用于推送训练后模型的 Hugging Face Hub 仓库 ID                                                                                          |
| `--policy.pretrained_name_or_path` | 用于初始化的预训练 WallX 权重路径（官方 WALL-OSS 检查点）                                                                        |
| `--policy.prediction_mode`         | 动作预测策略：`diffusion` 或 `fast` - `diffusion` 使用迭代去噪来生成动作，`fast` 则使用下一个 token 预测 |
| `--policy.attn_implementation`     | 注意力实现后端 - `eager` 使用标准 PyTorch 注意力（其他选项包括 `flash_attention_2` 或 `sdpa`）                               |
| `--steps`                          | 要运行的训练总步数                                                                                                                         |
| `--policy.device`                  | 用于训练的设备（`cuda` 表示 GPU，`cpu` 表示 CPU）                                                                                                            |
| `--batch_size`                     | 每个训练批次的样本数                                                                                                                          |

语言训练使用 `policy.text_loss_weight`（默认值为 `0.01`）、`policy.flow_loss_weight`（默认值为 `1.0`）以及 `policy.tokenizer_max_length`（默认值为 `768`）。`policy.recipe_path` 可选地用于替换内置的 recipe。

## 许可证

该模型遵循 **Apache 2.0 许可证**，与原始的 [WallX 仓库](https://github.com/X-Square-Robot/wall-x) 保持一致。