Upload SETUP_CYCLO_GROOT.md with huggingface_hub

SETUP_CYCLO_GROOT.md

@@ -0,0 +1,157 @@
+# 설치 — cyclo_intelligence & Isaac-GR00T
+
+두 저장소를 설치한다. **역할이 다르므로 따로 둔다.**
+
+| 저장소 | 역할 | 위치 |
+|--------|------|------|
+| [`cyclo_intelligence`](https://github.com/ROBOTIS-GIT/cyclo_intelligence) | **배포/추론** — 웹 UI에서 정책을 로봇에 실행 | `~/cyclo_intelligence` |
+| [`Isaac-GR00T-n1.7`](https://github.com/ROBOTIS-GIT/Isaac-GR00T-n1.7) (ROBOTIS 포크) | **GR00T 학습** | `~/Isaac-GR00T` |
+| [`cyclo_lab`](https://github.com/Disniekie01/EKAIWORKER) | Isaac Sim 데이터 생성 + LeRobot 학습 | `~/AIWORKER/cyclo_lab` |
+
+> **왜 GR00T를 따로 클론하나?**
+> cyclo_intelligence는 Isaac-GR00T를 **git 서브모듈**로 이미 포함하고 있다. 하지만 학습을 그 안에서 하면
+> 배포 저장소가 학습 환경(uv, 체크포인트, 캐시)으로 오염된다. **학습은 독립된 클론에서 하고,
+> 결과물만 HF에 올려 배포 때 내려받는다** — LeRobot에서 이미 쓰는 방식과 같다.
+>
+> ⚠️ **단, NVIDIA 원본이 아니라 ROBOTIS 포크를 클론해야 한다.** 추론하는 쪽(cyclo_intelligence 서브모듈)이
+> ROBOTIS 포크이므로, **같은 코드로 학습해야 체크포인트가 로드된다.** 원본으로 학습하면 버전이 갈려
+> 배포에서 못 읽을 수 있다.
+
+---
+
+## 1. cyclo_intelligence (배포/추론)
+
+[공식 README](https://github.com/ROBOTIS-GIT/cyclo_intelligence) 그대로:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ROBOTIS-GIT/cyclo_intelligence/main/install.sh | bash
+```
+
+- 호스트명이 `ffw`로 시작하는 **ROBOTIS 로봇 PC**: `/mnt/ssd/cyclo_intelligence` 에 설치되고 `~/cyclo_intelligence` 로 bind-mount
+- **그 외 PC**: `~/cyclo_intelligence` 에 바로 설치
+
+설치되는 것: Docker 이미지(robotis/cyclo-intelligence, robotis/lerobot-zenoh 등) + 웹 UI + 추론 엔진 + **Isaac-GR00T 서브모듈**
+
+컨테이너 기동/확인:
+```bash
+cd ~/cyclo_intelligence
+docker ps                    # cyclo_intelligence, lerobot_server 가 Up 인지
+```
+
+웹 UI: 브라우저에서 접속 → Inference 페이지에서 정책 선택
+
+관련 문서:
+- [AI Worker Imitation Learning 문서](https://docs.robotis.com/docs/systems/aiworker/imitation_learning/)
+- [AI Worker ROS 2 패키지](https://github.com/ROBOTIS-GIT/ai_worker)
+- [ROBOTIS 사전학습 모델·데이터셋](https://huggingface.co/ROBOTIS)
+
+---
+
+## 2. Isaac-GR00T (GR00T 학습 전용)
+
+### 2-a. 하드웨어 요구사항
+
+| | 요구 |
+|---|---|
+| **파인튜닝** | **40GB+ VRAM 권장** (H100 / L40 권장, A6000도 되지만 느림) |
+| 추론 | 16GB+ VRAM |
+| **dGPU (x86_64)** | **CUDA 12.8 + Python 3.10** |
+
+> GR00T N1.7은 **3B 파라미터**다. 다만 기본 파인튜닝 설정이 **VLM 백본(LLM + 비전 인코더)을 얼리고**
+> projector + diffusion action head만 학습하므로, 전체 학습보다 훨씬 가볍다.
+> 24GB GPU에서도 `--global_batch_size` 를 낮추면 들어갈 여지가 있다 (**실측 필요**).
+
+### 2-b. git-lfs 먼저 (필수)
+
+`demo_data/`의 parquet 파일을 받으려면 **클론 전에** 설치해야 한다:
+```bash
+sudo apt install git-lfs && git lfs install
+```
+
+### 2-c. 클론 (ROBOTIS 포크 + 서브모듈)
+
+```bash
+cd ~
+git clone --recurse-submodules https://github.com/ROBOTIS-GIT/Isaac-GR00T-n1.7.git Isaac-GR00T
+cd Isaac-GR00T
+```
+
+서브모듈 없이 이미 클론했다면:
+```bash
+git submodule update --init --recursive
+```
+
+**cyclo_intelligence가 쓰는 커밋과 맞추기** (체크포인트 호환의 핵심):
+```bash
+# 배포 쪽이 어느 커밋을 쓰는지 확인
+cd ~/cyclo_intelligence
+git submodule status cyclo_brain/policy/groot/Isaac-GR00T
+
+# 학습 쪽을 그 커밋으로 고정
+cd ~/Isaac-GR00T
+git checkout <위에서 나온 커밋 해시>
+```
+
+### 2-d. 환경 설치
+
+**uv** (파이썬 패키지 매니저 — GR00T가 이걸 씀):
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**FFmpeg** (`torchcodec` 비디오 백엔드에 필요):
+```bash
+sudo apt-get update && sudo apt-get install -y ffmpeg
+```
+
+**GR00T 설치** (dGPU x86_64 기준 — **Python 3.10**):
+```bash
+cd ~/Isaac-GR00T
+uv sync --python 3.10
+```
+> flash-attn·TensorRT 같은 GPU 의존성이 **기본 설치에 포함**된다 (미리 빌드된 wheel).
+> x86_64에서는 소스 빌드가 필요 없다.
+
+**확인:**
+```bash
+uv run python -c "import gr00t; print('GR00T installed successfully')"
+uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
+```
+
+### 2-e. 자주 걸리는 것
+
+| 증상 | 해결 |
+|------|------|
+| `CUDA_HOME is unset` (파인튜닝 시) | `bash scripts/deployment/dgpu/install_deps.sh` 를 1회 실행, 또는 `export CUDA_HOME=/usr/local/cuda` |
+| **CUDA 13.x 환경** — Triton `ptx_get_version()` RuntimeError | PyTorch 2.7이 Triton 3.3.1을 고정하는데 CUDA 13+를 인식 못 함 → `uv run bash scripts/patch_triton_cuda13.sh` |
+| `uv run` 할 때마다 `Installing flash-attn...` | **정상**이다. uv가 캐시된 wheel을 재검증하는 것 (2~3초). 소스 빌드가 아니다 |
+| flash-attn `glibc_compat.so` ImportError (구형 OS) | 소스 빌드: `uv pip install flash-attn==2.7.4.post1 --no-binary flash-attn --no-cache` (10~30분) |
+
+---
+
+## 3. 전체 구조
+
+```
+~/AIWORKER/cyclo_lab/     Isaac Sim 데이터 생성 · LeRobot 학습 (ACT/VQ-BeT/Diffusion)
+        │
+        │  HDF5 → LeRobot v3.0 → HuggingFace
+        ▼
+   HuggingFace  ─────────────────────────────┐
+        │  (데이터셋)                          │ (학습된 모델)
+        ▼                                     │
+~/Isaac-GR00T/            GR00T N1.7 파인튜닝 ─┘
+        │
+        │  체크포인트 → HuggingFace
+        ▼
+~/cyclo_intelligence/     웹 UI에서 모델 다운로드 → 로봇에 배포/추론
+```
+
+**핵심**: 학습 저장소들은 서로 독립이고, **HuggingFace가 유일한 연결고리**다.
+cyclo_intelligence는 학습 코드를 몰라도 되고, 모델만 내려받아 실행한다.
+
+---
+
+## 다음 단계
+
+- LeRobot 정책 학습 → [`WORKFLOW.md`](WORKFLOW.md)
+- GR00T N1.7 파인튜닝 → [`GROOT_FINETUNE.md`](GROOT_FINETUNE.md)