# EO-1

EO-1 é uma **política Vision-Language-Action para controle de robôs**. A implementação do LeRobot integra o EO-1 com o treinamento, a avaliação e a interface de processador padrão do LeRobot.

## Visão geral do modelo

O EO-1 utiliza um backbone Qwen2.5-VL para compreensão de visão-linguagem e adiciona uma cabeça de ação de fluxo contínuo (flow-matching) para controle de robôs. A política formata cada amostra de controle de robô como uma conversa multimodal: as imagens da câmera são passadas para o Qwen2.5-VL, o estado do robô é representado com tokens de estado do EO-1 e o trecho de ação futuro é representado com tokens de ação do EO-1.

<img
  src="https://huggingface.co/datasets/HaomingSong/lerobot-documentation-images/resolve/main/lerobot/eo_pipeline.png"
  alt="An overview of EO-1"
  width="85%"
/>

Durante o treinamento, o EO-1 aprende a desruidar trechos contínuos de ações nas posições de tokens de ação. Durante a inferência, ele amostra um trecho de ações, retorna ações contínuas e executa `n_action_steps` do trecho antes de amostrar novamente.

### O que a Integração do LeRobot Abrange

- Configuração padrão `policy.type=eo1` por meio do LeRobot
- Pré-processamento de imagem e texto do Qwen2.5-VL por meio de processadores de política
- Previsão de ações por fluxo contínuo
- Salvamento/carregamento de checkpoints por meio das APIs de política do LeRobot
- Treinamento com `lerobot-train` e avaliação com `lerobot-eval`

O projeto mais amplo do EO-1 também inclui pré-treinamento intercalado de visão-texto-ação e fluxos de trabalho de raciocínio multimodal. Esta página foca no caminho de política de controle de robô do LeRobot.

## Requisitos de instalação

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

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

3. Se você deseja treinar ou avaliar no LIBERO, instale também as dependências do LIBERO:

   ```bash
   pip install -e ".[eo1,libero]"
   ```

O EO-1 pode usar o backend padrão de atenção de produto escalar do PyTorch por meio de `policy.attn_implementation=sdpa`. Se o seu ambiente tiver uma instalação compatível do `flash_attn`, você pode solicitar `policy.attn_implementation=flash_attention_2`.

## Requisitos de Dados

O EO-1 espera um dataset LeRobot com:

- Pelo menos uma observação visual, por exemplo `observation.images.image`
- `observation.state`
- `action`
- Uma instrução de tarefa de linguagem por meio do campo `task` do conjunto de dados

Se o seu conjunto de dados usa nomes de observação diferentes, use `rename_map` para alinhá-los com os nomes esperados pela sua configuração de treinamento ou avaliação.

## Uso

Para usar o EO-1 em uma configuração do LeRobot, especifique o tipo de política como:

```python
policy.type=eo1
```

Use o checkpoint de release convertido para começar a partir do pré-treinamento intercalado de visão-texto-ação do EO-1:

```bash
--policy.path=lerobot/eo1-base
```

`lerobot/eo1-base` é uma conversão nativa do LeRobot de [`IPEC-COMMUNITY/EO-1-3B`](https://huggingface.co/IPEC-COMMUNITY/EO-1-3B). Ele preserva os pesos de visão-linguagem Qwen liberados e a cabeça de ação flow-matching treinada. O tamanho do chunk de ação é 16, correspondendo ao checkpoint upstream. Para inicializar apenas a partir do backbone Qwen original, omita `policy.path` e defina `policy.vlm_base=Qwen/Qwen2.5-VL-3B-Instruct`.

Carregue outro checkpoint EO-1 no formato LeRobot, ajustado finamente, com:

```python
policy.path=your-org/your-eo1-checkpoint
```

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

O EO-1 expõe o backbone do Qwen por meio do contrato de texto de política compartilhado. O Runtime adiciona `query_kind` e `query_text` e, em seguida, executa o processador de entrada padrão do EO-1:

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

`vqa` preserva a pergunta do chamador. `next_subtask` aplica a receita armazenada na configuração de política do EO-1. O EO-1 herda `generate_text(processed_batch)` e sobrescreve `supports_text_generation` e `generate_text`; nenhum VLM separado é carregado.

Com o runtime de linguagem interativo, o EO-1 pode gerar uma subtarefa e reconstruir seu prompt de ação a partir dessa subtarefa atual:

```bash
# Use the robot, port and cameras your checkpoint was trained with
lerobot-rollout \
  --policy.path=your-org/your-eo1-checkpoint \
  --policy.device=cuda \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --task="clear the table" \
  --interactive=true
```

Após `/start`, use `/vqa <question>`, `/autosteer <goal>` ou `/subtask <text>`.

## Treinamento

### Exemplo de Comando de Treinamento

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_dataset \
  --policy.path=lerobot/eo1-base \
  --policy.dtype=bfloat16 \
  --policy.attn_implementation=sdpa \
  --policy.gradient_checkpointing=false \
  --output_dir=./outputs/eo1_training \
  --job_name=eo1_training \
  --steps=300000 \
  --batch_size=16 \
  --policy.device=cuda
```

### Treinar com anotações de linguagem

`EO1Config` inclui uma receita para treinar a partir das colunas de linguagem opcionais do LeRobot. A receita conjunta integrada supervisiona uma resposta de assistente selecionada e seu trecho de ação contínuo na mesma sequência:

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_language_annotated_dataset \
  --policy.type=eo1 \
  --policy.text_loss_weight=0.01 \
  --policy.flow_loss_weight=1.0 \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

As voltas do assistente direcionadas recebem a entropia cruzada do próximo token, enquanto os fluxos da receita `low_level` recebem supervisão de ação de fluxo. Uma linha pode receber qualquer um dos objetivos ou ambos. Prompts do usuário, imagens, tokens de estado, tokens de ação e preenchimento são excluídos da perda de texto. Defina `policy.recipe=null` para desabilitar a renderização da receita e usar o caminho original de treinamento apenas com ações.

Consulte [Colunas de idioma e receitas](./language_and_recipes) para o esquema de anotação e a estrutura da receita. `recipe_path` pode apontar para uma substituição externa explícita em YAML; o LeRobot não fornece arquivos de receita padrão compartilhados. O prompt de sistema padrão faz parte da receita do EO1 e pode ser substituído por um turno de sistema personalizado. Entradas renderizadas sem um turno de sistema, incluindo prompts de VQA, permanecem sem um. O caminho apenas de ação, sem mensagens renderizadas, mantém o prompt de sistema padrão. `EO1PrepareModelMessagesStep` adiciona imagens e tokens de estado/ação às mensagens renderizadas antes do formato Qwen e da tokenização.

### Parâmetros Principais de Treinamento

| Parâmetro                              | Padrão                       | Descrição                                                             |
| -------------------------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `policy.path`                          | `lerobot/eo1-base`            | Pesos do EO-1 convertidos para o formato nativo do LeRobot                |
| `policy.vlm_base`                      | `Qwen/Qwen2.5-VL-3B-Instruct` | Processador/backbone do Qwen usado apenas quando o treinamento é realizado sem `policy.path`   |
| `policy.dtype`                         | `bfloat16`                    | Solicitação de dtype do backbone: um nome de dtype do torch, por exemplo, `bfloat16`, `float32`  |
| `policy.attn_implementation`           | `None`                        | Backend de atenção Qwen opcional, como `sdpa`                         |
| `policy.gradient_checkpointing`        | `false`                       | Reduz o uso de memória durante o treinamento                                    |
| `policy.chunk_size`                    | `16`                          | Número de ações futuras previstas por bloco                            |
| `policy.n_action_steps`                | `16`                          | Número de ações consumidas de um bloco amostrado                         |
| `policy.num_denoise_steps`             | `10`                          | Número de etapas de desruidamento de flow-matching usadas durante a amostragem            |
| `policy.max_state_dim`                 | `32`                          | Dimensão de preenchimento do estado                                                 |
| `policy.max_action_dim`                | `32`                          | Dimensão de preenchimento de ação                                                |
| `policy.force_fp32_autocast`           | `true`                        | Mantém a cabeça de fluxo em fp32, mesmo quando o backbone usa precisão mista |
| `policy.supervise_padding_action_dims` | `true`                        | Controla se as dimensões de ação preenchidas são supervisionadas                |
| `policy.supervise_padding_actions`     | `true`                        | Controla se as linhas de ação futura com preenchimento são supervisionadas               |
| `policy.recipe_path`                   | `None`                        | Permite supervisão de texto e de ações por amostra orientada por receitas            |
| `policy.text_loss_weight`              | `0.01`                        | Peso para a entropia cruzada de tokens assistentes supervisionados                     |
| `policy.flow_loss_weight`              | `1.0`                         | Peso para a perda de fluxo-ação contínua                                  |
| `policy.tokenizer_max_length`          | `1000`                        | Comprimento máximo da sequência conjunta de visão-linguagem-ação                    |

## Avaliação

O EO-1 pode ser avaliado por meio de `lerobot-eval` uma vez que você tenha um checkpoint no formato LeRobot:

```bash
lerobot-eval \
  --policy.path=your-org/your-eo1-checkpoint \
  --env.type=libero \
  --env.task=libero_object \
  --eval.batch_size=1 \
  --eval.n_episodes=20
```

Para conjuntos de dados ou ambientes cujos nomes de câmera diferem da configuração do checkpoint, passe um `rename_map`:

```bash
lerobot-eval \
  --policy.path=your-org/your-eo1-checkpoint \
  --env.type=libero \
  --env.task=libero_object \
  --rename_map='{"observation.images.image2":"observation.images.wrist_image"}'
```

## Notas de configuração

### Processamento de Imagens

O EO-1 usa o processador Qwen2.5-VL. As configurações `policy.image_min_pixels` e `policy.image_max_pixels` controlam os limites de redimensionamento da imagem antes que os tokens visuais sejam passados para o backbone.

### Dimensões de Estado e Ação

A política adiciona padding aos vetores de estado e ação até `policy.max_state_dim` e `policy.max_action_dim` antes da cabeça de fluxo EO-1. As previsões são recortadas de volta para a dimensão original da ação antes de serem retornadas pela política.

### Backend de Atenção

Use `policy.attn_implementation=sdpa` para uma configuração portátil. Use `flash_attention_2` apenas quando `flash_attn` estiver instalado e compatível com o seu ambiente.

## Referências

- [projeto EO-1](https://github.com/EO-Robotics/EO1)
- [artigo EO-1](https://arxiv.org/abs/2508.21112)
- [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct)

## Citação

```bibtex
@article{eo1,
  title={EO-1: Interleaved Vision-Text-Action Pretraining for General Robot Control},
  author={Delin Qu and Haoming Song and Qizhi Chen and Zhaoqing Chen and Xianqiang Gao and Xinyi Ye and Qi Lv and Modi Shi and Guanghui Ren and Cheng Ruan and Maoqing Yao and Haoran Yang and Jiacheng Bao and Bin Zhao and Dong Wang},
  journal={arXiv preprint},
  year={2025},
  url={https://arxiv.org/abs/2508.21112}
}
```

## Licença

Esta integração do LeRobot segue a **Apache 2.0 License** utilizada pelo LeRobot. Consulte as páginas do modelo e do dataset upstream do EO-1 para verificar as licenças dos checkpoints e dos dados do EO-1 liberados.

