# WALL-OSS

WALL-OSS é um modelo de fundação de código aberto para inteligência incorporada, proposto pela equipe [XSquare Robot](https://x2robot.com/en/research/68bc2cde8497d7f238dde690) em 2025. A implementação do LeRobot é adaptada do repositório de código aberto [WallX](https://github.com/X-Square-Robot/wall-x) deles.

O WALL-OSS da X Square Robot agora está integrado ao ecossistema LeRobot do Hugging Face. Este é um projeto colaborativo empolgante entre as equipes do LeRobot e da X Square Robot. Agora é possível fazer pós-treino, avaliar e implantar o WALL-OSS diretamente pelo LeRobot. Com isso, nosso objetivo é facilitar para a comunidade de robótica de código aberto personalizar e implantar os modelos de fundação do WALL-OSS. Leia e explore o [paper](https://arxiv.org/pdf/2509.11766) e o [código](https://github.com/X-Square-Robot/wall-x) do WALL-OSS.

## Visão geral do modelo

A equipe WALL-OSS está construindo o modelo de fundação encarnado para capturar e comprimir os dados mais valiosos do mundo: o fluxo contínuo e de alta fidelidade da interação física. Ao criar um loop de feedback direto entre as decisões do modelo e a experiência vivida do corpo, torna-se possível a emergência de uma inteligência verdadeiramente generalizável — uma que entende não apenas como o mundo funciona, mas como agir de forma eficaz dentro dele.

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

Tecnicamente, o WALL-OSS introduz uma arquitetura multimodal acoplada de forma estreita (estrutura MoE acoplada de forma estreita) que integra estratégias de modelagem de ações discretas e contínuas. Por meio de um pipeline de treinamento em duas etapas (Inspiration → Integration), o modelo unifica gradualmente o raciocínio semântico e a geração de ações de alta frequência. Suas principais inovações incluem:

- **Pré-treinamento multimodal aprimorado por percepção corporificada**: Treinamento em larga escala em dados unificados de visão, linguagem e ação para fortalecer a compreensão espacial, causal e de manipulação.
- **Cadeia de Pensamento Unificada em Níveis Cruzados (Uni-CoT)**: Um único framework diferenciável que unifica o raciocínio de alto nível sobre instruções, a decomposição de subtarefas e a síntese de ações de granularidade fina, formando uma cadeia contínua do “entendimento” à “execução”.
- **Cabeças de ação Mixture-of-Experts (MoE)**: Ativação dinâmica de especialistas dependendo da fase da tarefa e modelagem de ações em espaço discreto ou contínuo para manter priors estáveis de VLM.
- **Paradigma de treinamento em duas etapas**:
  - **Etapa de inspiração**: Injeção de priors de ações discretas para fortalecer a compreensão espacial e o alinhamento semântico-ação.
  - **Etapa de integração**: Usando flow matching para alcançar controle contínuo de alta frequência.

## Requisitos de instalação

1. Instale o LeRobot seguindo nosso [Guia de Instalação](./installation).
2. Instale as dependências do WallX executando:

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

## Uso

Para usar o WallX no LeRobot, especifique o tipo de política como:

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

### Geração de texto e controle interativo

WALL-OSS expõe a geração de texto nativa por meio do contrato de política de [Traga sua própria política](./bring_your_own_policies#text-capable-policies). O runtime fornece `query_kind` e `query_text` de propriedade do chamador antes de executar o pipeline de entrada normal do WALL-OSS:

```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` preserva a pergunta como o payload do usuário. `next_subtask` aplica a receita de checkpoint antes de `${subtask}`. O WALL-X substitui diretamente a API pública `generate_text(processed_batch)` para seu especialista de visão-linguagem Qwen e relata essa capacidade por meio de `supports_text_generation()`.

O runtime de linguagem interativo pode gerar uma subtarefa e, em seguida, condicionar a previsão de ação do WALL-OSS com base nela:

```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
```

Após `/start`, use `/vqa <question>` para VQA baseado em imagem ou `/autosteer <goal>` para geração do próximo subtask com base em receita. `/subtask <text>` ignora a geração e envia uma instrução diretamente para a inferência de ação.

## Treinamento

Para treinar o WallX, você pode usar o script de treinamento padrão do LeRobot com a configuração apropriada:

```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
```

### Treinar com anotações de linguagem

O WALL-X usa sua receita embutida para treinar a partir das colunas de linguagem opcionais do LeRobot. Defina `recipe_path` apenas para substituir essa receita:

```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
```

As respostas do assistente direcionadas recebem a entropia cruzada do próximo token, enquanto os fluxos do recipe `low_level` recebem supervisão contínua de fluxo-ação. Uma linha pode receber qualquer um dos objetivos ou ambos. Prompts do usuário, imagens, propriocepção, tokens de consulta de ação e padding são excluídos da perda de texto. Defina `policy.recipe=null` para usar o caminho de treinamento original do WALL-OSS, baseado apenas em ações.

Consulte [Colunas de idioma e receitas](./language_and_recipes) para o esquema de anotação e as receitas disponíveis.

### Argumentos de Treinamento

| Argumento                           | Descrição                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dataset.repo_id`                | O ID do repositório no Hugging Face Hub para o seu conjunto de dados de treinamento (por exemplo, `lerobot/aloha_sim_insertion_human`)                                                      |
| `--policy.type`                    | Especifica o uso da arquitetura de política WallX                                                                                                                 |
| `--output_dir`                     | Diretório local onde os checkpoints de treinamento e os logs serão salvos                                                                                             |
| `--job_name`                       | Um identificador de nome para esta execução de treinamento (usado em registro/acompanhamento)                                                                                            |
| `--policy.repo_id`                 | ID do repositório no Hugging Face Hub para onde o modelo treinado será enviado                                                                                          |
| `--policy.pretrained_name_or_path` | Caminho para os pesos pré-treinados do WallX a serem usados para inicialização (o checkpoint oficial do WALL-OSS)                                                                        |
| `--policy.prediction_mode`         | Estratégia de previsão de ação: `diffusion` ou `fast` - `diffusion` usa desruído iterativo para a geração de ações, `fast` usa previsão do próximo token em vez disso |
| `--policy.attn_implementation`     | Backend de implementação de atenção - `eager` usa a atenção padrão do PyTorch (as alternativas incluem `flash_attention_2` ou `sdpa`)                               |
| `--steps`                          | Número total de etapas de treinamento a serem executadas                                                                                                                         |
| `--policy.device`                  | Dispositivo para treinamento (`cuda` para GPU, `cpu` para CPU)                                                                                                            |
| `--batch_size`                     | Número de amostras por lote de treinamento                                                                                                                          |

O treinamento de linguagem usa `policy.text_loss_weight` (padrão `0.01`), `policy.flow_loss_weight` (padrão `1.0`) e `policy.tokenizer_max_length` (padrão `768`). `policy.recipe_path` substitui opcionalmente a receita embutida.

## Licença

Este modelo segue a **Apache 2.0 License**, em conformidade com o repositório original [WallX](https://github.com/X-Square-Robot/wall-x).

