콘텐츠로 이동
StarVLA

빠른 시작

배경 지식

섹션 제목: “배경 지식”

이러한 개념이 처음이라면 다음의 간략한 설명을 참고하세요:

  • VLM (Vision-Language Model): Qwen-VL이나 GPT-4V처럼 이미지와 텍스트를 모두 이해하는 AI 모델입니다.
  • VLA (Vision-Language-Action Model): VLM에 액션 출력을 추가한 모델로, 모델이 “보고” “말하는” 것뿐만 아니라 “행동”까지 할 수 있습니다. 이미지와 자연어 명령을 입력받아 로봇 동작(예: 관절 각도 — 로봇 팔의 각 관절에 대한 목표 각도 값)을 출력합니다. VLM 기반 외에도, WM(World Model) — 미래 상태를 예측하는 비디오 생성 모델 — 을 기반으로 VLA를 구축할 수도 있습니다.
  • StarVLA가 하는 일: StarVLA를 “VLA 개발을 위한 PyTorch”라고 생각하세요 — VLM을 VLA로 변환하기 위한 전체 인프라를 제공합니다: 데이터 로딩, 학습 루프, 평가, 배포 파이프라인이 모두 재사용 가능하므로 모델 자체에 집중할 수 있습니다. VLM에서 시작하든 WM에서 시작하든 동일한 도구로 학습과 평가를 수행합니다.

요구 사항

섹션 제목: “요구 사항”
항목최소권장
GPUNVIDIA GPU 1개 (VRAM 16GB 이상)8xA800 이상 (A100 / H200 등)
CUDA12.0+12.4
Python3.103.10
디스크약 20GB (코드 + 기본 모델)100GB 이상 (데이터셋 포함)
OSLinux (Ubuntu 20.04+)Ubuntu 22.04

1단계: 설치

섹션 제목: “1단계: 설치”

  1. 저장소 클론

    Terminal window
    git clone https://github.com/starVLA/starVLA
    cd starVLA

  2. conda 환경 생성

    Terminal window
    conda create -n starVLA python=3.10 -y
    conda activate starVLA

  3. 의존성 설치

    Terminal window
    # 기본 의존성 설치
    pip install -r requirements.txt
    

    # FlashAttention2 설치 (빠른 Transformer 추론에 필요)
    # 참고: flash-attn은 소스에서 컴파일합니다; 최초 설치 시 10-20분이 소요될 수 있습니다 — 이는 정상입니다
    pip install flash-attn --no-build-isolation
    

    # starVLA를 개발 모드로 설치 (-e = editable 모드:
    # 코드 변경이 재설치 없이 즉시 반영됩니다)
    pip install -e .

문제 해결: flash-attn 설치

섹션 제목: “문제 해결: flash-attn 설치”

flash-attn은 CUDA 및 PyTorch 버전에 민감합니다. 설치에 실패하면 버전 호환성을 확인하세요:

Terminal window
# CUDA 버전 확인
nvcc -V


# 설치된 패키지 버전 확인
pip list | grep -E 'torch|transformers|flash-attn'

검증된 조합:

  • flash-attn==2.7.4.post1 + CUDA 12.0 / 12.4 + PyTorch 2.6.0

nvcc 버전과 PyTorch CUDA 버전이 일치하지 않는 경우(예: nvcc 11.8이지만 PyTorch cu121), 이를 맞춰야 합니다. 가장 간단한 방법은 nvcc 버전에 맞는 PyTorch를 재설치하는 것입니다:

Terminal window
# 예시: nvcc 12.4의 경우
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

2단계: 설치 확인

섹션 제목: “2단계: 설치 확인”

모든 것이 정상적으로 작동하는지 확인하는 두 단계:

  1. 기본 모델 다운로드

    StarVLA는 Qwen-VL 모델 패밀리를 기반으로 합니다. 먼저 기본 모델을 다운로드해야 합니다.

    Terminal window
    # Hugging Face CLI 설치 (아직 설치하지 않은 경우)
    pip install huggingface_hub[cli]
    

    # Qwen3-VL-4B 다운로드 (약 8GB)
    huggingface-cli download Qwen/Qwen3-VL-4B-Instruct --local-dir ./playground/Pretrained_models/Qwen3-VL-4B-Instruct

  2. 프레임워크 스모크 테스트 실행

    가짜 데이터로 순전파를 수행하여 모델이 올바르게 로드되고 예측하는지 확인합니다:

    Terminal window
    python starVLA/model/framework/QwenGR00T.py

    다음과 같은 결과가 표시되어야 합니다:

    • 전체 모델 구조 출력
    • model.predict_action(fake_data)가 액션 배열을 반환 (shape: [batch, action_horizon, action_dim])
    • 오류 없음

    CUDA 메모리 부족이 발생하면 더 작은 모델(예: Qwen2.5-VL-3B)을 사용해 보세요.

디렉토리 구조

섹션 제목: “디렉토리 구조”

설치 후 작업하게 될 프로젝트 레이아웃입니다:

starVLA/                          # 프로젝트 루트 (git 저장소)
├── starVLA/                      # 코어 패키지 (Python 관례: 외부 디렉토리는 프로젝트, 내부 동명 디렉토리가 실제 패키지 코드)
│   ├── model/framework/          # 모델 정의 (QwenOFT.py, QwenGR00T.py 등)
│   ├── dataloader/               # 데이터 로딩 파이프라인
│   ├── training/                 # 학습 스크립트
│   └── config/                   # DeepSpeed 및 학습 설정 템플릿
├── deployment/                   # 배포 (정책 서버)
├── examples/                     # 벤치마크별 평가 및 학습 예제
│   ├── LIBERO/
│   ├── SimplerEnv/
│   ├── Robocasa_tabletop/
│   ├── Robotwin/
│   └── Behavior/
├── playground/                   # 모델과 데이터를 위한 관례적 디렉토리
│   ├── Pretrained_models/        # 기본 모델 (예: Qwen3-VL-4B-Instruct)
│   └── Datasets/                 # 학습 데이터셋
└── results/                      # 학습 출력 (체크포인트, 로그)
    └── Checkpoints/

다음 단계

섹션 제목: “다음 단계”

설치 확인이 완료되면 목적에 맞는 경로를 선택하세요:

목표추천 문서
StarVLA의 설계 이해레고 블록 설계
기존 체크포인트로 평가 실행모델 저장소에서 체크포인트 확인 후 벤치마크 가이드 참조 (LIBERO, SimplerEnv)
자체 데이터로 학습자체 LeRobot 데이터셋 사용하기
VLM 데이터와 공동 학습VLM 데이터와 공동 학습
자주 묻는 질문FAQ