# RoboVLMs 아키텍처 종합 분석 (환각 없는 코드 기반)

> **작성일**: 2026-01-10  
> **목적**: 교수님 미팅 메모 링크들에 대한 명확한 분석 및 클리어 여부 확인

---

## 분석 대상 링크 목록

| # | 링크 | 유형 | 분석 상태 |
|---|------|------|----------|
| 1 | [base_backbone.py](https://github.com/Robot-VLAs/RoboVLMs/blob/main/robovlms/model/backbone/base_backbone.py) | 코드 | ✅ 완료 |
| 2 | [HuggingFace checkpoints](https://huggingface.co/robovlms/RoboVLMs/tree/main/checkpoints) | 데이터 | ✅ 완료 |
| 3 | [HuggingFace README](https://huggingface.co/robovlms/RoboVLMs/blob/main/README.md) | 문서 | ✅ 완료 |
| 4 | [policy_head/](https://github.com/Robot-VLAs/RoboVLMs/tree/main/robovlms/model/policy_head) | 코드 | ✅ 완료 |
| 5 | [CALVIN config JSON](https://github.com/Robot-VLAs/RoboVLMs/blob/main/configs/calvin_finetune/finetune_kosmos_cont-lstm-post_full-ft_text_vision_wd-0_ws-8_act-10.json) | 설정 | ✅ 완료 |

---

## 링크 #1: base_backbone.py

**파일**: [base_backbone.py](file:///home/billy/25-1kp/vla/RoboVLMs_upstream/robovlms/model/backbone/base_backbone.py)

### 핵심 함수

| 함수명 | 라인 | 역할 |
|--------|------|------|
| `__init__` | 57-191 | 모델 초기화, VLM + Action Head 구성 |
| `_trainable_params_setup` | 511-597 | **Frozen/Trainable 설정 핵심** |
| `_init_backbone` | 248-259 | VLM (Kosmos-2) 로드 |
| `_init_heads` | 467-489 | Action Head 초기화 |
| `forward_continuous` | 727-869 | **Action 예측 핵심 forward** |
| `inference` | 1052-1136 | 추론 시 호출 |

### 핵심 변수 (Line 499-520)

```python
# Frozen/Trainable 설정 핵심 코드
if self.train_setup_configs["freeze_backbone"]:
    model.requires_grad_(False)  # VLM 전체 고정

if self.train_setup_configs.get("train_vision", False):
    self.vision_tower.requires_grad_(True)  # Vision만 학습

if self.train_setup_configs.get("train_text_embedding", False):
    self.word_embedding.requires_grad_(True)  # Text Embedding만 학습

if self.act_head is not None:
    self.act_head.requires_grad_(True)  # Action Head 학습
```

### 분석 결과

✅ **클리어**: `freeze_backbone=True` 시 VLM 고정, Action Head만 학습  
✅ **클리어**: Pretrained VLM 로드 로직 구현 완료 (Line 107-138)

---

## 링크 #2: HuggingFace Checkpoints

**URL**: https://huggingface.co/robovlms/RoboVLMs/tree/main/checkpoints

### 사용 가능한 Checkpoints

| 파일명 | 크기 | 학습 데이터 | Action Dim |
|--------|------|-------------|------------|
| `kosmos_ph_calvin_abcd.pt` | 6.82GB | CALVIN ABCD | 7DoF |
| `kosmos_ph_calvin_abc.pt` | 6.82GB | CALVIN ABC | 7DoF |
| `kosmos_ph_oxe-pretrain.pt` | - | OXE Magic Soup | 7DoF |
| **`kosmos_ph_google-robot-post-train.pt`** | **6.35GB** | **Google Robot** | **7DoF** |

### 다운로드 완료

```bash
# 다운로드 경로
pretrained_ckpts/checkpoints/kosmos_ph_google-robot-post-train.pt  # 6.35GB
```

### 분석 결과

✅ **클리어**: Google Robot checkpoint 다운로드 및 구조 분석 완료  
✅ **클리어**: VLM (1.80B) + Action Head (41M) 분리 확인

---

## 링크 #3: HuggingFace README

**URL**: https://huggingface.co/robovlms/RoboVLMs/blob/main/README.md

### 핵심 Usage 코드

```python
# 공식 사용법 (HuggingFace README)
from robovlms.train.base_trainer import BaseTrainer

configs['model_load_path'] = 'checkpoints/kosmos_ph_calvin_abcd.pt'
model = BaseTrainer.from_checkpoint(configs)

# Inference
action = model.inference_step(input_dict)["action"]
```

### Pretrained 모델 설명

> "RoboKosMos (KosMos + Policy Head) trained on the CALVIN dataset"  
> "The model can be used to predict action based on the vision and language input"

### 분석 결과

✅ **클리어**: Pretrained checkpoint는 **VLM + Action Head 전체**가 학습된 상태  
⚠️ **차이점 발견**: VLM만 가져다 쓰는 것과 전체 checkpoint 사용은 다름

---

## 링크 #4: policy_head/

**URL**: https://github.com/Robot-VLAs/RoboVLMs/tree/main/robovlms/model/policy_head

### 구조

```
policy_head/
├── __init__.py          # LSTMDecoder, FCDecoder, DiscreteDecoder, GPTDecoder 내보냄
├── base_policy.py       # 핵심 Action Head 구현
├── action_tokenizer.py  # Discrete action용 토크나이저
└── trajectory_gpt2.py   # GPT 기반 trajectory prediction
```

### 핵심 클래스: LSTMDecoder

**파일**: base_policy.py

```python
class LSTMDecoder(BasePolicyHead):
    def __init__(
        self,
        in_features,      # VLM hidden_size (2048)
        action_dim,       # 7 (6DoF arm + 1 gripper)
        hidden_size=1024, # LSTM hidden size
        num_layers=4,     # LSTM layers
        fwd_pred_next_n,  # 예측할 action 개수
        window_size,      # history window
        ...
    ):
        self.rnn = lstm_decoder(in_features * latent, hidden_size * latent, num_layers, ...)
        self.actions = MLPTanhHead(self.hidden_size * latent, fwd_pred_next_n * (self.action_dim - 1))  # 6DoF
        self.gripper = MLPSigmoidHead(self.hidden_size * latent, fwd_pred_next_n)  # gripper
```

### 출력 구조 (7DoF)

```python
def forward(self, tok_seq, h_0=None, **kwargs):
    ...
    actions = self.actions(x)   # [bs, seq, fwd_n, 6]  ← arm pose
    gripper = self.gripper(x)   # [bs, seq, fwd_n, 1]  ← gripper
    return actions, gripper
```

### 분석 결과

✅ **클리어**: LSTMDecoder는 7DoF (6 arm + 1 gripper) 출력  
✅ **클리어**: 우리 MobileVLALSTMDecoder는 2DoF (linear_x, linear_y) 출력으로 수정됨

---

## 링크 #5: CALVIN Config JSON

### 핵심 설정 비교

| 설정 | 공식 CALVIN | 우리 Mobile VLA |
|------|------------|-----------------|
| `action_dim` | **7** (6+gripper) | **2** (linear_x, linear_y) |
| `freeze_backbone` | **false** | true |
| `train_vision` | **true** | false |
| `train_text_embedding` | **true** | false |
| `lora_enable` | false | false |
| `hidden_size` | 1024 | 512 |
| `window_size` | 8 | 8 |
| `fwd_pred_next_n` | **10** | 5 |

### 핵심 차이점

**공식 CALVIN config는 `freeze_backbone: false`로 VLM 전체를 학습함**

```json
// 공식 config
"train_setup": {
    "freeze_backbone": false,   // ← VLM 전체 학습!
    "train_vision": true,       // ← Vision encoder 학습
    "train_text_embedding": true // ← Text embedding 학습
}
```

### 분석 결과

⚠️ **중요 발견**: 공식 checkpoint는 **VLM도 함께 학습됨**  
✅ **클리어**: 우리 config와의 차이점 파악 완료

---

## 핵심 차이점 분석

### 1. Pretrained VLM만 가져다 쓰기 vs 전체 Checkpoint 사용

| 방식 | VLM 상태 | Action Head | Instruction Grounding |
|------|---------|-------------|----------------------|
| **VLM만 사용** | HuggingFace 원본 (비학습) | 새로 초기화 | ❌ 없음 |
| **전체 Checkpoint** | Robot 도메인 학습됨 | 7DoF 학습됨 | ✅ 있음 |

### 2. 왜 전체 Checkpoint가 더 나은가?

RoboVLMs pretrained checkpoint는 **VLM도 Robot 도메인에 맞게 fine-tune됨**

공식 config 분석 결과:
```json
"freeze_backbone": false,      // VLM 학습됨
"train_vision": true,          // Vision encoder 학습됨
"train_text_embedding": true   // Text embedding 학습됨
```

따라서:
1. **Vision Encoder**: Robot 카메라 이미지에 최적화됨
2. **Text Encoder**: Robot instruction에 최적화됨
3. **Action Head**: 7DoF arm action 예측에 최적화됨

---

## 권장 전이학습 전략 (수정)

### 기존 전략 (문제 있음)

```
HuggingFace Kosmos-2 (비학습 VLM) + 2DoF Action Head
→ Instruction grounding 기대 불가
```

### 수정된 전략 (권장)

```
RoboVLMs Pretrained VLM (Robot 도메인 학습됨) + 2DoF Action Head
→ VLM이 이미 Robot instruction 이해 능력 있음
→ Instruction grounding 개선 기대
```

### 구현 완료 상태

| 항목 | 상태 |
|------|------|
| Pretrained checkpoint 다운로드 | ✅ 완료 (6.35GB) |
| 키 매핑 구현 | ✅ 완료 (886개 weights 로드) |
| VLM 로드 테스트 | ✅ 성공 (Missing: 0) |
| 2DoF Action Head | ✅ 구현됨 (MobileVLALSTMDecoder) |
| 학습 config | ✅ 생성됨 (mobile_vla_pretrained.json) |

---

## 결론

### 초기 요구사항 클리어 여부

| # | 요구사항 | 클리어 |
|---|----------|--------|
| 1 | base_backbone.py 핵심 함수 파악 | ✅ |
| 2 | Pretrained checkpoints 구조 분석 | ✅ |
| 3 | HuggingFace README 사용법 확인 | ✅ |
| 4 | policy_head LSTMDecoder 구조 분석 | ✅ |
| 5 | 공식 CALVIN config 차이점 분석 | ✅ |

### 다음 단계

1. **Pretrained VLM + 2DoF Action Head로 학습 시작**
2. **LEFT/RIGHT instruction grounding 검증**
3. **공식 config처럼 VLM도 학습할지 결정** (메모리 허용 시)