README.md

---
license: apache-2.0
tags:
  - robotics
  - deployment
  - inference
  - cyclo-intelligence
  - ffw-sg2
  - lerobot
  - gr00t
pretty_name: cyclo_intelligence 배포 가이드 (FFW_SG2)
---

# cyclo_intelligence 배포 — 처음부터 끝까지

학습한 정책(LeRobot ACT/VQ-BeT/Diffusion 또는 GR00T N1.7)을 ROBOTIS **cyclo_intelligence** 웹 UI로
로봇에 올려 실행하는 전 과정. **실전에서 실제로 겪은 함정까지** 반영했다.

> 학습 파이프라인은 → LeRobot [`humanoid-imitation-learning`](https://huggingface.co/JSHNSL/humanoid-imitation-learning) · GR00T [`gr00t-ffw-sg2-finetune`](https://huggingface.co/JSHNSL/gr00t-ffw-sg2-finetune)

---

## 큰 그림

cyclo_intelligence는 여러 컨테이너로 구성된다:

| 컨테이너 | 역할 |
|----------|------|
| `cyclo_intelligence` | 오케스트레이터 + 웹 UI (nginx) |
| `lerobot_server` | **LeRobot 정책** 추론 엔진 (`robotis/lerobot-zenoh`) |
| `groot_server` | **GR00T 정책** 추론 엔진 (`robotis/groot-zenoh`) |
| `ai_worker` | 로봇 제어 (실물/mock) |

정책 종류에 따라 **다른 엔진**이 뜬다 — LeRobot은 `lerobot_server`, GR00T는 `groot_server`.

---

## 1. 설치

[공식 install 스크립트](https://github.com/ROBOTIS-GIT/cyclo_intelligence):
```bash
curl -fsSL https://raw.githubusercontent.com/ROBOTIS-GIT/cyclo_intelligence/main/install.sh | bash
```
- 호스트명이 `ffw` 로 시작하는 **로봇 PC**: `/mnt/ssd/cyclo_intelligence` 에 설치 + `~/cyclo_intelligence` bind-mount
- 그 외: `~/cyclo_intelligence`

컨테이너 확인:
```bash
cd ~/cyclo_intelligence
docker ps        # cyclo_intelligence, lerobot_server 가 Up (healthy)
```

---

## 2. 모델을 어디에 두나 — **가장 중요한 것**

정책은 **`/workspace/model/<backend>/<이름>/`** 에 둔다. 호스트 경로로는:

```
~/cyclo_intelligence/docker/workspace/model/lerobot/<이름>/    ← LeRobot 정책
~/cyclo_intelligence/docker/workspace/model/groot/<이름>/      ← GR00T 정책
```

> ⚠️ **`~/.cache/huggingface/...` 가 아니다.** UI가 읽는 드롭박스는 `/workspace/model/{lerobot,groot}/` 다.
> ⚠️ **학습 컨테이너의 `/workspace` 와 헷갈리지 말 것.** `docker run ... gr00t`(학습용)의 `/workspace` 와
> cyclo_intelligence의 `/workspace` 는 **다른 컨테이너**다. cyclo 쪽에 둬야 웹에 보인다
> → 호스트의 `~/cyclo_intelligence/docker/workspace/model/` 에 두는 게 제일 확실.

### 추론에 필요한 파일만 (checkpoint 등은 뺀다)

**GR00T** — 7개면 된다:
```
config.json
model-00001-of-00003.safetensors
model-00002-of-00003.safetensors
model-00003-of-00003.safetensors
model.safetensors.index.json
experiment_cfg/          ← modality (19-dim/카메라1개) 정보
processor_config.json    (또는 processor/ 폴더)
```
**LeRobot (0.5.2)** — 정규화 파일이 핵심:
```
config.json
model.safetensors
policy_preprocessor.json
policy_preprocessor_step_*_normalizer_processor.safetensors     ← 입력 정규화 (필수!)
policy_postprocessor.json
policy_postprocessor_step_*_unnormalizer_processor.safetensors  ← 출력 역정규화 (필수!)
train_config.json
```
> ❌ **빼는 것**: `checkpoint-*/`(각 수GB 중복), `optimizer.pt`, `scheduler.pt`, `rng_state.pth`,
> `trainer_state.json`, `training_args.bin`, `wandb_config.json` — 전부 학습 재개용이라 추론엔 불필요.
>
> ⚠️ **LeRobot은 반드시 0.5.2로 학습한 것.** 옛 0.3.3 모델(preprocessor/postprocessor 파일 없음)은
> 로드돼도 정규화가 안 돼 로봇이 이상하게 움직인다 → 0.5.2로 재학습해야 한다.

---

## 3. HF에서 모델 받아 배치

**cyclo_intelligence 캐시가 호스트에 마운트**돼 있으므로 호스트에서 직접 받는 게 깔끔하다.

### GR00T 예시 (HF repo에 checkpoint-* 로 저장된 경우)

최종 스텝만 골라서 받는다:
```bash
# 어떤 체크포인트가 있나
python3 -c "from huggingface_hub import HfApi; import re; print(sorted({int(m.group(1)) for f in HfApi().list_repo_files('JSHNSL/groot_ffw_ltable') if (m:=re.match(r'checkpoint-(\d+)/',f))}))"
```
```bash
# 최종(예: 20000)만 받기
hf download JSHNSL/groot_ffw_ltable --include "checkpoint-20000/*" --local-dir /tmp/g
```
```bash
# 필요한 것만 배치 (한 줄 — 여러 줄로 나누면 공백이 깨진다)
DST=~/cyclo_intelligence/docker/workspace/model/groot/groot_ffw_ltable_20k
mkdir -p "$DST"
cp -a /tmp/g/checkpoint-20000/config.json /tmp/g/checkpoint-20000/model-00001-of-00003.safetensors /tmp/g/checkpoint-20000/model-00002-of-00003.safetensors /tmp/g/checkpoint-20000/model-00003-of-00003.safetensors /tmp/g/checkpoint-20000/model.safetensors.index.json /tmp/g/checkpoint-20000/experiment_cfg /tmp/g/checkpoint-20000/processor_config.json "$DST"/
```
```bash
# ⭐ 모델 3개가 GB 단위로 들어갔는지 반드시 확인
ls -la "$DST"
```

### LeRobot 예시 (repo 최상위에 파일이 있는 경우)

```bash
DST=~/cyclo_intelligence/docker/workspace/model/lerobot/diffusion_ffw
hf download JSHNSL/diffusion_ffw_ltable --local-dir "$DST"
```

> 컨테이너가 root로 만든 폴더는 root 소유가 된다. 호스트에서 만지려면 `sudo`, 또는
> `sudo chown -R $USER:$USER ~/cyclo_intelligence/docker/workspace/model`.

---

## 4. 웹 UI에서 실행

브라우저로 cyclo_intelligence 접속 → **Inference**:
1. 모델 타입 — **ACT / VQ-BeT / Diffusion** (LeRobot) 또는 **N1.7** (GR00T)
2. User — 폴더 구조상 owner (예: `JSHNSL`) 또는 직접 배치한 이름
3. Policy — 방금 배치한 폴더 이름
4. **Load** → 로딩되면 **Inference**로 넘어감

성공 로그 (엔진 컨테이너):
```bash
docker logs -f groot_server 2>&1 | grep -v "Service call timed out"   # GR00T
docker logs -f lerobot_server                                          # LeRobot
```
GR00T가 뜨면:
```
Loading GR00T policy from: /workspace/model/groot/groot_ffw_ltable_20k
Policy info: {'video': ['cam_left_head'], 'state': ['arm_left','arm_right','head','lift'], ...}
Action chunk: T=16, D=19        ← 추론이 실제로 돌고 있음
```

---

## 5. 자주 걸리는 것 (실전)

| 증상 | 원인 / 해결 |
|------|------------|
| **웹 UI Loading 무한** (GR00T) | `groot_server` 자동 기동 실패 → `docker start groot_server` 후 UI에서 다시 Load |
| **웹에 모델이 안 보임** | `/workspace/model/<backend>/` 가 아닌 곳에 뒀거나, **학습 컨테이너**의 `/workspace` 에 넣음 → cyclo 쪽 `~/cyclo_intelligence/docker/workspace/model/` 에 배치 |
| **Diffusion/VQ-BeT 로드는 되는데 로봇 안 움직임** | 큐 기반 정책 엔진 버그 → [`cyclo-intelligence-patches`](https://huggingface.co/JSHNSL/cyclo-intelligence-patches) 한 줄 적용 (`prediction.py` 패치 + `diffusers` 설치) |
| **`No module named 'diffusers'`** (Diffusion) | `docker exec lerobot_server sh -c 'VIRTUAL_ENV=/lerobot/.venv uv pip install diffusers'` (이 컨테이너엔 pip 없음, uv 사용) |
| **VQ-BeT 드롭다운에 없음** | UI에 항목 추가 + root로 재빌드 → patches repo 참고 |
| **ACT는 되는데 접근만 하고 grasp 약함** | 정책 성능/시각 조건 문제 (단일 cam_head). 배포 버그 아님 |
| **옛 ACT(0.3.3) 로드했는데 이상** | preprocessor/postprocessor 파일 없음 → **0.5.2로 재학습** |
| **`Timeout waiting for sensors: camera:cam_right_head`** | 로봇 config가 카메라 4개 기대. 정책이 1개만 쓰면 **경고일 뿐 추론은 진행됨** |
| **카메라 회색 / 로봇 mock** | **실물 로봇·카메라가 없는 PC**라서. 실제 동작은 로봇이 연결된 PC에서만 |
| 모델 파일 root 소유 | `sudo chown -R $USER:$USER ~/cyclo_intelligence/docker/workspace/model` |

---

## 6. 정책별 요약

| 정책 | 엔진 | 배치 위치 | 특이사항 |
|------|------|-----------|----------|
| **ACT** | lerobot_server | `model/lerobot/` | 바로 됨 (0.5.2) |
| **Diffusion** | lerobot_server | `model/lerobot/` | 엔진 패치 + `diffusers` 필요 |
| **VQ-BeT** | lerobot_server | `model/lerobot/` | 엔진 패치 + UI 항목 추가 필요 |
| **GR00T N1.7** | groot_server | `model/groot/` | `groot_server` 수동 기동 필요할 수 있음 |

> Diffusion·VQ-BeT 관련 패치는 [`JSHNSL/cyclo-intelligence-patches`](https://huggingface.co/JSHNSL/cyclo-intelligence-patches) 에 한 줄 적용 스크립트로 있다.

---

## ⚠️ 실물 로봇이 없는 PC에서는

로드·추론(Action chunk 생성)까지는 되지만, **실제 로봇 움직임은 안 보인다** — 카메라는 회색(mock),
관절도 mock. 이 PC에서 확인 가능한 것은:
- ✅ 모델이 **로드되는가**
- ✅ modality를 **정확히 인식하는가** (`Policy info`)
- ✅ **추론이 도는가** (`Action chunk`)

**실제 grasp/이동**은 ZED+RealSense가 달린 **실물 FFW_SG2 로봇 PC**에서만 의미가 있다.