Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,172 @@
+---
+license: apache-2.0
+tags:
+- vision-language-action
+- mobile-robot
+- kosmos-2b
+- robotics
+- obstacle-avoidance
+datasets:
+- mobile-vla-dataset
+language:
+- en
+- ko
+metrics:
+- mae
+- r2_score
+library_name: transformers
+pipeline_tag: robotics
+---
+
+# 🚀 Mobile VLA: Vision-Language-Action Model for Mobile Robots
+
+## 📋 Model Description
+
+Mobile VLA는 Kosmos-2B를 기반으로 한 Mobile Robot 전용 Vision-Language-Action 모델입니다. 
+장애물 회피 시나리오에서 연속적인 3D 액션 예측을 수행합니다.
+
+### 🎯 핵심 기능
+
+- **Vision-Language-Action**: 이미지와 텍스트 지시사항을 받아 로봇 액션 예측
+- **3D 연속 제어**: `[linear_x, linear_y, angular_z]` 형태의 연속 액션 공간
+- **장애물 회피**: 1-box, 2-box 시나리오에서 좌우 회피 전략 학습
+- **실시간 처리**: 효율적인 vision-only 처리로 빠른 추론
+
+### 🔧 기술 사양
+
+- **백본 모델**: microsoft/kosmos-2-patch14-224
+- **입력**: RGB 이미지 (224x224) + 텍스트 지시사항
+- **출력**: 3D 연속 액션 벡터
+- **학습 방식**: Huber Loss 기반 회귀
+- **데이터**: 72개 실제 로봇 에피소드
+
+## 📊 성능 지표
+
+### 전체 성능
+- **전체 MAE**: 0.285
+- **임계값 정확도 (0.1)**: 37.5%
+
+### 액션별 성능
+| 액션 | MAE | R² Score | 설명 |
+|------|-----|----------|------|
+| linear_x | 0.243 | 0.354 | 전진/후진 (우수) |
+| linear_y | 0.550 | 0.293 | 좌우 이동 (보통) |
+| angular_z | 0.062 | 0.000 | 회전 (낮음) |
+
+### 시나리오별 성능
+| 시나리오 | MAE | 등급 | 설명 |
+|----------|-----|------|------|
+| 1box_right_vertical | 0.217 | B+ | 우수 |
+| 1box_left_horizontal | 0.303 | B | 양호 |
+| 2box_left_vertical | 0.322 | B | 양호 |
+| 1box_left_vertical | 0.337 | B- | 보통 |
+
+## 🚀 사용 방법
+
+### 설치
+```bash
+pip install transformers torch pillow numpy
+```
+
+### 기본 사용법
+```python
+from mobile_vla import MobileVLAModel, MobileVLATrainer
+from PIL import Image
+import torch
+
+# 모델 로드
+model = MobileVLAModel.from_pretrained("minuum/mobile-vla")
+
+# 이미지와 태스크 준비
+image = Image.open("robot_camera.jpg")
+task = "Navigate around obstacles to track the target cup"
+
+# 예측
+with torch.no_grad():
+    actions = model.predict(image, task)
+    
+print(f"Predicted actions: {actions}")
+# 출력: [linear_x, linear_y, angular_z]
+```
+
+### 고급 사용법
+```python
+# 배치 처리
+images = [Image.open(f"frame_{i}.jpg") for i in range(8)]
+actions = model.predict_sequence(images, task)
+
+# 실시간 제어
+for frame in camera_stream:
+    action = model.predict(frame, task)
+    robot.execute(action)
+```
+
+## 🏗️ 모델 아키텍처
+
+```
+[RGB Images] → [Kosmos-2B Vision] → [Action Head] → [3D Actions]
+     ↓              ↓                    ↓             ↓
+   224x224    Image Features         Regression    [x, y, θ]
+```
+
+### 핵심 컴포넌트
+1. **Kosmos-2B Vision Model**: 이미지 특징 추출
+2. **Action Head**: 3D 회귀 헤드 (512 → 3*chunk_size)
+3. **Window/Chunk**: 8프레임 관찰 → 2프레임 예측
+
+## 📈 RoboVLMs와의 비교
+
+| 항목 | RoboVLMs | Mobile VLA |
+|------|----------|------------|
+| **데이터 요구량** | 수백만 데모 | 72 에피소드 |
+| **액션 공간** | 7-DOF Discrete | 3D Continuous |
+| **추론 속도** | 복합적 | 빠름 |
+| **특화 분야** | 범용 Manipulation | Mobile Robot |
+| **평가 방식** | 성공률 | 다차원 회귀 지표 |
+
+## 🎯 주요 개선사항
+
+- **데이터 효율성**: 1000배 적은 데이터로 실용적 성능
+- **실시간 성능**: Vision-only 처리로 빠른 추론
+- **연속 제어**: 정밀한 3D 액션 예측
+- **시나리오 특화**: 장애물 회피 전용 최적화
+
+## 📚 학습 데이터
+
+- **에피소드 수**: 72개
+- **시나리오**: 1box/2box × left/right × vertical/horizontal
+- **액션**: [linear_x, linear_y, angular_z] 연속 값
+- **이미지**: 실제 로봇 카메라 RGB (224x224)
+
+## 🔬 연구 배경
+
+이 모델은 RoboVLMs의 Window/Chunk 메커니즘을 유지하면서 Mobile Robot에 특화된 기능을 추가한 연구입니다:
+
+1. **Window/Chunk 유지**: 8프레임 관찰 → 2프레임 예측 구조
+2. **Kosmos-2B 통합**: Vision-Language 백본 활용
+3. **연속 제어**: Discrete → Continuous 액션 공간 전환
+4. **실제 로봇 데이터**: HDF5 형태의 실제 수집 데이터
+
+## 📄 인용
+
+```bibtex
+@misc{mobile_vla_2024,
+  title={Mobile VLA: Vision-Language-Action Model for Mobile Robot Navigation},
+  author={Mobile VLA Team},
+  year={2024},
+  publisher={HuggingFace},
+  url={https://huggingface.co/minuum/mobile-vla}
+}
+```
+
+## 🤝 기여
+
+이 모델은 RoboVLMs 프레임워크를 기반으로 개발되었으며, Mobile Robot 커뮤니티의 발전을 위해 공개됩니다.
+
+## 📞 연락처
+
+- **Issues**: [GitHub Issues](https://github.com/minuum/vla/issues)
+- **Discussions**: [HuggingFace Discussions](https://huggingface.co/minuum/mobile-vla/discussions)
+
+---
+*Generated on 2025-08-21*