Hugging Face's logo

JSHNSL
/
cyclo-intelligence-deploy

Robotics
LeRobot
deployment
inference
cyclo-intelligence
ffw-sg2
gr00t
Model card Files
xet
 Community
How to use from the
Use from the
LeRobot library

cyclo_intelligence 배포 — 처음부터 끝까지

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

학습 파이프라인은 → LeRobot humanoid-imitation-learning · GR00T 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 스크립트:

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

컨테이너 확인:

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-* 로 저장된 경우)

최종 스텝만 골라서 받는다:

# 어떤 체크포인트가 있나
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))}))"

# 최종(예: 20000)만 받기
hf download JSHNSL/groot_ffw_ltable --include "checkpoint-20000/*" --local-dir /tmp/g

# 필요한 것만 배치 (한 줄 — 여러 줄로 나누면 공백이 깨진다)
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"/

# ⭐ 모델 3개가 GB 단위로 들어갔는지 반드시 확인
ls -la "$DST"

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

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로 넘어감

성공 로그 (엔진 컨테이너):

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 한 줄 적용 (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 에 한 줄 적용 스크립트로 있다.

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

로드·추론(Action chunk 생성)까지는 되지만, 실제 로봇 움직임은 안 보인다 — 카메라는 회색(mock), 관절도 mock. 이 PC에서 확인 가능한 것은:

  • ✅ 모델이 로드되는가
  • ✅ modality를 정확히 인식하는가 (Policy info)
  • ✅ 추론이 도는가 (Action chunk)

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

Downloads last month

-

Downloads are not tracked for this model. How to track
Video Preview
Robotics
loading