README_KR.md

🦾 Pusher-v5 PPO // 인공지능 로보틱스 관제 허브 & 실시간 제어 콕핏

Gymnasium MuJoCo 7자유도 로봇 팔 연속 제어 텔레메트리 & PPO 심층 강화학습 통합 플랫폼
🌐 English Documentation | 🇰🇷 한국어 매뉴얼

본 리포지토리는 Gymnasium의 물리 시뮬레이션 환경인 Pusher-v5에서 7자유도(7-DOF) 로봇 팔이 원통형 물체를 목표 지점까지 정확하게 밀어 넣도록 학습시키는 Stable-Baselines3 PPO 강화학습 시스템 및 **실시간 30 FPS 웹 관제 콕핏(FastAPI + WebSocket)**을 제공합니다.

---

🌟 핵심 성능 및 모델 스펙

항목	상세 규격 및 벤치마크 결과
학습 환경	Gymnasium MuJoCo Pusher-v5 (7자유도 로봇 매니퓰레이터)
관측 공간 (Observation)	23차원 연속 벡터 (관절 각도 7, 관절 각속도 7, 팁 위치 3, 물체 위치 3, 골 위치 3)
행동 공간 (Action)	7차원 연속 모터 토크 제어값 (Box[-2.0, 2.0], float32)
학습 알고리즘	Proximal Policy Optimization (PPO, MlpPolicy)
백엔드 프레임워크	Stable-Baselines3 / PyTorch / FastAPI / Starlette WebSockets
초기 기초 점수 (Step 0)	-57.51 pts (무작위 관절 탐색, 팔-물체 거리 0.215m)
최종 수렴 점수 (Step 300k+)	-32.42 ± 4.30 pts *(최고 에피소드: -26.15 pts)*
팔-물체 접촉 정밀도	0.028 m (2.8cm) (원통 물체 완벽 포착 및 밀착)
목표 지점 근접 정밀도	0.054 m (목표 골대 안착 및 푸싱 완료)

---

🏛️ 시스템 아키텍처 및 데이터 흐름

flowchart TD
    subgraph Live_Web_Cockpit ["1-화면 제로 스크롤 로보틱스 관제 콕핏"]
        W1["HTML5 / CSS3 / Vanilla JS 클라이언트"] <-->|"WebSocket /ws/simulation @ 30 FPS"| S1["FastAPI 고성능 서버"]
        S1 -->|"Base64 JPEG 물리 스트림"| W1
        S1 -->|"7-DOF 바이폴라 모터 토크 (-2.0 ~ +2.0 Nm)"| W1
        S1 -->|"3D 데카르트 좌표: 팁, 물체, 골대"| W1
        W1 -->|"제어 명령: Start, Pause, Step, Reset, Policy"| S1
    end

    subgraph Analytics_Deck ["4-탭 분석 및 리플레이 덱"]
        T1["1탭: 실시간 텔레메트리 차트 (Raw 보상 & 20-Ep 이동평균선)"]
        T2["2탭: 마일스톤 리플레이 갤러리 (16:9 와이드 비디오 카드)"]
        T3["3탭: 실시간 PPO 터미널 로그 (학습 진행률 & FPS 콘솔)"]
        T4["4탭: 환경 스펙 & 보상 함수 수학 공식"]
    end

    subgraph Deep_RL_Pipeline ["PPO 강화학습 파이프라인"]
        TR1["train.py / 백그라운드 학습 스레드"] --> TR2["Pusher-v5 물리 엔진"]
        TR2 --> TR3["VisualProgressCallback"]
        TR3 --> TR4["Step 0부터 300k까지의 비디오(MP4) 및 GIF"]
        TR3 --> TR5["4분할 학습 분석 그래프 & metrics.json"]
        TR4 & TR5 --> TR6["원클릭 압축 패키지: ppo_pusher_bundle.zip"]
    end

---

🎮 관제 센터 주요 기능

1. 초저지연 30 FPS 실시간 물리 캔버스:

   • 웹소켓을 통한 고속 렌더링 스트림 및 실시간 FPS 카운터.
   • 7개 관절 모터 토크를 중앙 0.0 기준으로 양수(청록색, Cyan)와 음수(장미색, Rose)로 실시간 시각화하는 7-DOF 바이폴라 토크 게이지.
   • 로봇 손가락 끝(Tip), 물체(Object), 골대(Goal)의 3D 공간 좌표 X, Y, Z 미터 단위 정밀 추적.
   • 키보드 단축키 지원 (Space 시작/일시정지, R 리셋, S 1스텝 전진, H HUD 온오프).

2. 강화학습 예산 프리셋 셀렉터:

   • 500 Ep (50k Steps • ~12s) - 빠른 테스트
   • 2,000 Ep (200k Steps • ~45s) - 기본 푸싱 학습
   • 5,000 Ep (500k Steps • ~1.8m) ★ 추천 완성형 정책
   • 10,000 Ep (1M Steps • ~3.5m) - 초정밀 수렴
   • ⚙️ 사용자 정의(Custom) 스텝 설정

3. 16:9 와이드 멀티 비디오 카드 갤러리:

   • 스텝 0부터 최종 스텝까지 AI의 성장 과정을 넷플릭스 썸네일처럼 한눈에 가로로 비교하는 비디오 카드 릴.
   • 카드별 독립 MP4 비디오 및 GIF 애니메이션 즉시 다운로드 기능.

4. 단일 ZIP 파일 자동 패키징:

   • 상단 Download Bundle 버튼을 누르면 학습된 모델 가중치(ppo_pusher.zip), 비디오, 차트, 메트릭이 하나의 압축 파일(ppo_pusher_bundle.zip)로 즉시 다운로드됩니다.

---

🚀 빠른 시작 가이드 (Quickstart)

1. 환경 설치

git clone https://github.com/Hwihwa-Lab/pusher-v5-ppo.git
cd pusher-v5-ppo
pip install -r requirements.txt

2. 실시간 웹 관제 센터 실행

python app.py

브라우저에서 http://localhost:8000 접속.

3. 허깅페이스 원클릭 자동 배포

python deploy_to_hf.py

4. CLI 기반 독립 학습 및 모델 평가

# PPO 에이전트 학습 실행
python train.py --timesteps 300000 --eval_freq 30000

# 학습 완료된 모델 독립 평가 및 비디오 추출
python evaluate.py --model_path ./results/ppo_pusher.zip --episodes 5

---

🐍 5줄 파이썬 빠른 평가 스니펫 (Quick Evaluation)

본 리포지토리의 학습 완료 가중치를 불러와 5줄의 파이썬 코드로 즉시 시뮬레이션을 실행할 수 있습니다:

import gymnasium as gym
from stable_baselines3 import PPO

# 1. Pusher-v5 환경 초기화 및 완성 가중치 로드
env = gym.make("Pusher-v5", render_mode="human")
model = PPO.load("results/ppo_pusher.zip")

# 2. 결정론적 푸싱 제어 롤아웃 실행
obs, _ = env.reset()
done = False
while not done:
    action, _ = model.predict(obs, deterministic=True)
    obs, reward, terminated, truncated, _ = env.step(action)
    done = terminated or truncated

env.close()

---

⌨️ 키보드 단축키 안내 (Keyboard Shortcuts)

단축키	조작 기능	설명
Space	시작 / 일시정지	실시간 30 FPS MuJoCo 물리 시뮬레이션 토글
R	환경 초기화 (Reset)	로봇 팔, 원통 물체, 목표 골대를 새로운 랜덤 위치로 재배치
S	1스텝 전진 (Step Once)	물리 엔진을 1단위 타임스텝(0.05초) 전진
H	HUD 온오프 토글	캔버스 화면 위 텔레메트리 오버레이 표시/숨김

---

🛡️ AI 엔지니어링 거버넌스 및 문서 체계

본 시스템은 강화학습 시뮬레이션의 물리적 무결성을 보존하고 바이브-코딩 드리프트를 방지하기 위해 정밀한 엔지니어링 문서 프로토콜(GitHub 제공)을 준수합니다:

• .cursorrules: AI 코딩 방어 및 규칙 마스터 헌법
• DOCS_AI_CODING_PROTOCOL.md: 코딩 표준 및 전체 문서 맵
• DOCS_SYSTEM_ARCHITECTURE.md: 풀스택 시스템 및 WebSocket 아키텍처 명세서
• DOCS_DATA_SCHEMA.md: 텔레메트리 패킷 프로토콜 및 REST 데이터 스키마
• DOCS_MODEL_EVALUATION_AND_HF_DEPLOY.md: 벤치마크 평가 및 허깅페이스 배포 규격서

📂 리포지토리 파일 구성 (Repository Contents)

• README.md: 영문 글로벌 모델 카드 및 벤치마크 가이드.
• README_KR.md: 한국어 종합 기술 매뉴얼 (한국어 매뉴얼).
• app.py: FastAPI 고성능 백엔드 및 30 FPS WebSocket 물리 스트리밍 서버.
• train.py: Stable-Baselines3 PPO 7자유도 로봇 팔 강화학습 엔진 (VisualProgressCallback 내장).
• evaluate.py: 독립 5회 연속 롤아웃 성능 평가기 및 비디오 녹화기.
• visualizer.py: 독립 Matplotlib 텔레메트리 시각화 및 그래프 생성 모듈.
• web/: 1-화면 제로 스크롤 웹 관제 콕핏 프론트엔드 (app.js, index.html, style.css).
• results/ppo_pusher.zip: 300,000 스텝 완성형 PPO 신경망 가중치 (평균 -32.4 pts).
• ppo_pusher_bundle.zip: 가중치, 12개 체크포인트 비디오, 분석 차트가 포함된 단일 프로덕션 배포 압축본.
• deploy_to_hf.py: 허깅페이스 모델 허브 원클릭 자동 배포 스크립트.
• requirements.txt & packages.txt: 파이썬 패키지 및 OS 의존성 명세서.

---

🔗 오픈소스 공식 링크 (Open Source Hubs)

• 🐙 GitHub 저장소: https://github.com/Hwihwa-Lab/pusher-v5-ppo
• 🤗 Hugging Face 모델 허브: https://huggingface.co/hwihwalab/pusher-v5-ppo

---

📄 라이선스

본 프로젝트는 MIT License를 따릅니다.

---

Trained and deployed with Pusher AI Hub by hwihwalab.