# RoboCerebra

  아래 명령어는 시뮬레이터를 로컬에서 실행합니다. 정책의 의존성과 분리하기 위해 대신 `lerobot-env-server --config_path=docker/sim/configs/robocerebra.yaml --sim.task= --docker=true`로 서빙하세요. 여기서 ` is the command's `--env.task`, and run the command with `--env.type=robocerebra --env.server.endpoint=tcp/127.0.0.1:7448. 서버는 시작할 때 지정된 작업을 실행합니다(자세한 내용은 [Simulation: local or served](./simulation) 참조).

[RoboCerebra](https://robocerebra.github.io/)는 VLA에서 **고급 추론, 계획, 기억**을 평가하는 장기 조작 벤치마크입니다. 에피소드는 언어 기반의 중간 지시와 함께 여러 하위 목표를 연결하며, LIBERO의 시뮬레이터 스택(MuJoCo + robosuite, Franka Panda 7-DOF) 위에 구축되어 있습니다.

- 논문: [RoboCerebra: A Large-scale Benchmark for Long-horizon Robotic Manipulation Evaluation](https://arxiv.org/abs/2506.06677)
- 프로젝트 웹사이트: [robocerebra.github.io](https://robocerebra.github.io/)
- Dataset: [`lerobot/robocerebra_unified`](https://huggingface.co/datasets/lerobot/robocerebra_unified) — LeRobot v3.0, 20 fps 기준 6,660 에피소드 / 571,116 프레임, 언어 기반 1,728개의 하위 작업.
- 사전 학습된 정책: [`lerobot/smolvla_robocerebra`](https://huggingface.co/lerobot/smolvla_robocerebra)

## 사용 가능한 작업

RoboCerebra는 LIBERO의 시뮬레이터를 재사용하므로, 평가는 LIBERO의 `libero_10` 장기 목표(long-horizon) 스위트에 대해 수행됩니다:

| Suite     | CLI 이름    | 작업 | 설명                                                   |
| --------- | ----------- | ----- | ------------------------------------------------------------- |
| LIBERO-10 | `libero_10` | 10    | 3~6개의 하위 목표를 연결하는 장기 지평의 주방/거실 작업 |

데이터셋의 각 RoboCerebra 에피소드는 자연어 지시문이 포함된 여러 하위 작업으로 세분화되며, 통합 데이터셋은 이를 독립적인 감독 신호로 노출합니다.

## 설치

RoboCerebra는 LIBERO에 기반하므로 `libero` extra만 있으면 됩니다:

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

RoboCerebra는 Linux(MuJoCo / robosuite)가 필요합니다. 학습 또는 평가 전에 렌더링 백엔드를 설정하세요:

```bash
export MUJOCO_GL=egl  # for headless servers (HPC, cloud)
```

## 평가

RoboCerebra eval은 RoboCerebra의 카메라 명명 규칙(`image` + `wrist_image`)과 3개 뷰로 학습된 정책이 예상하는 입력 레이아웃을 받도록 추가된 빈 카메라 슬롯을 사용하여 LIBERO의 `libero_10` 스위트에 대해 실행됩니다:

```bash
lerobot-eval \
  --policy.path=lerobot/smolvla_robocerebra \
  --env.type=libero \
  --env.task=libero_10 \
  --env.fps=20 \
  --env.obs_type=pixels_agent_pos \
  --env.observation_height=256 \
  --env.observation_width=256 \
  '--env.camera_name_mapping={"agentview_image": "image", "robot0_eye_in_hand_image": "wrist_image"}' \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --eval.use_async_envs=false \
  --policy.device=cuda \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.wrist_image": "observation.images.camera2"}' \
  --policy.empty_cameras=1
```

### 권장 평가 에피소드

`libero_10` 스위트에서 재현 가능한 벤치마킹을 위해 **태스크당 10에피소드**(총 100개)를 사용합니다. 이는 RoboCerebra 논문에서 사용된 프로토콜과 일치합니다.

## 정책 입력 및 출력

**관찰 사항:**

- `observation.state` — 8차원 고유감각 상태 (7개 관절 위치 + 그리퍼)
- `observation.images.image` — 3인칭 시점, 256×256 HWC uint8
- `observation.images.wrist_image` — 손목에 장착된 카메라의 뷰, 256×256 HWC uint8

**작업:**

- `Box(-1, 1, shape=(7,))`에서의 연속 제어 — 엔드 이펙터 델타(6D) + 그리퍼(1D)

## 학습

[`lerobot/robocerebra_unified`](https://huggingface.co/datasets/lerobot/robocerebra_unified)의 통합 데이터셋은 두 개의 RGB 스트림과 언어 기반 서브태스크 어노테이션을 제공합니다:

| 기능                          | Shape         | 설명          |
| -------------------------------- | ------------- | -------------------- |
| `observation.images.image`       | (256, 256, 3) | 삼인칭 시점    |
| `observation.images.wrist_image` | (256, 256, 3) | 손목 장착형 카메라 |
| `observation.state`              | (8,)          | 관절 위치 + 그립퍼  |
| `action`                         | (7,)          | EEF 델타 + 그리퍼  |

이를 기반으로 SmolVLA 베이스를 Fine-tune합니다:

```bash
lerobot-train \
  --policy.path=lerobot/smolvla_base \
  --policy.repo_id=${HF_USER}/smolvla_robocerebra \
  --policy.empty_cameras=1 \
  --dataset.repo_id=lerobot/robocerebra_unified \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.wrist_image": "observation.images.camera2"}' \
  --env.type=libero \
  --env.task=libero_10 \
  '--env.camera_name_mapping={"agentview_image": "image", "robot0_eye_in_hand_image": "wrist_image"}' \
  --output_dir=outputs/smolvla_robocerebra
```

`smolvla_base`는 `camera1`~`camera3` 이름의 카메라를 기대하므로, 카메라 플래그는 [평가](#evaluation) 명령과 동일합니다. `--rename_map`은 데이터셋의 카메라를 해당 이름으로 매핑하고, `--env.camera_name_mapping`은 학습 중 평가 시 LIBERO 카메라에 데이터셋의 이름을 부여합니다.

## 발표된 결과 재현

발행된 체크포인트 [`lerobot/smolvla_robocerebra`](https://huggingface.co/lerobot/smolvla_robocerebra)는 `lerobot/robocerebra_unified`로 학습되었으며, [평가](#evaluation) 섹션의 명령어로 평가되었습니다. CI는 벤치마크에 영향을 미치는 모든 PR에서 `--eval.n_episodes=1`을 사용하여 동일한 명령어를 스모크 테스트로 실행합니다.