🦾 pusher-v5-ppo - Physical AI Pusher-v5 PPO Model

이 저장소는 MuJoCo 7-DoF 로봇 팔 (Pusher-v5) 환경에서 물체를 목표 지점으로 밀어 넣는 작업을 수행하도록 Stable-Baselines3 PPO 알고리즘으로 학습된 피지컬 AI 강화학습 모델입니다.

---

🤖 환경 개요 (Environment Overview)

• 환경 명칭: Gymnasium Pusher-v5 / 7-자유도 로봇 팔 물리 시뮬레이션
• 관측 공간 (Observation Space): 23차원 연속형 벡터 (7 관절 각도, 7 관절 각속도, 엔드이펙터 3D 좌표, 물체 3D 좌표, 목표 3D 좌표)
• 행동 공간 (Action Space): 7차원 연속형 토크 제어 [-2.0, 2.0]
• 보상 구조:
  1. r_near: 엔드이펙터 팁과 물체 사이의 거리에 대한 보상
  2. r_dist: 물체와 최종 목표 지점 사이의 거리에 대한 보상
  3. r_ctrl: 불필요한 과도 토크 에너지를 억제하는 제어 페널티
  4. r_goal: 물체가 목표 지점에 안착했을 때의 추가 보너스

⚙️ 학습 하이퍼파라미터 (Hyperparameters)

파라미터	값
알고리즘	PPO (Proximal Policy Optimization)
신경망 정책 (Policy)	MlpPolicy (Actor-Critic)
학습률 (Learning Rate)	3e-4
n_steps / Batch Size	512 / 64
Discount Factor (Gamma)	0.99
GAE Lambda	0.95
Clip Range	0.2
총 학습 스텝 수	10,000 Steps

---

🚀 사용법 (How to Load and Test)

1. 필수 라이브러리 설치

pip install stable-baselines3 gymnasium huggingface_hub

2. Hugging Face에서 모델 다운로드 및 추론 실행 (Python)

from huggingface_hub import hf_hub_download
from stable_baselines3 import PPO
import gymnasium as gym

# 1. Hugging Face Hub에서 모델 .zip 다운로드
model_file = hf_hub_download(
    repo_id="lookarooka/pusher-v5-ppo",
    filename="ppo_pusher_best.zip"
)

# 2. Stable-Baselines3 PPO 모델 로드
model = PPO.load(model_file)
print("✅ 모델 로드 성공:", model_file)

# 3. 환경 생성 및 추론 시연
try:
    env = gym.make("Pusher-v5", render_mode="human")
except Exception:
    # MuJoCo 독립 환경 지원
    from pusher_env import make_pusher_env
    env = make_pusher_env("Pusher-v5")

obs, info = env.reset()
for _ in range(300):
    action, _states = model.predict(obs, deterministic=True)
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

---

📁 모델 파일 구성

• ppo_pusher_best.zip: 학습 완료된 Stable-Baselines3 PPO 신경망 가중치 (.zip)
• model_metadata.json: 학습 설정 및 환경 세부 메타데이터
• README.md: 모델 카드 및 사용 가이드

---

Created with Physical AI Brain Studio