NVlabs/ProtoMotions 딥다이브
— 가상의 인간·로봇에게 "움직이는 법"을 물리 시뮬레이션으로 가르치는 GPU 학습 프레임워크

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README는 이렇게 소개한다: "A GPU-accelerated simulation and learning framework for training physically simulated digital humans and humanoid robots." 모듈성(Modularity), 확장성(Extensibility), 확장 가능성(Scalability) 세 가지를 핵심 가치로 내세우며, 애니메이션·로보틱스·강화학습이라는 서로 다른 커뮤니티를 잇는 다리 역할을 표방한다. NVIDIA Research의 SIL(Simulation, Imitation, Learning) 팀이 만들었고, 이전 버전들(ProtoMotions, ASE, MaskedMimic 등 여러 논문 코드베이스)의 후속작인 3세대(v3.1)다.

2왜 주목받는가

NVIDIA Research의 다목적 통합 플랫폼 포지셔닝 · sim2real 실증 · 경쟁 프로젝트 대비 장점.

ProtoMotions3가 TrendShift 상위권에 오른 이유는 크게 세 가지로 요약된다. 첫째, 휴머노이드 로봇(Unitree G1·H1_2 등) 상용화가 급물살을 타면서 "물리 시뮬레이션으로 로봇 제어를 학습시키는" 접근 자체의 수요가 폭증했다. 둘째, README가 보여주는 데모 목록이 이례적으로 광범위하다 — 대규모 모션 학습, 멀티 GPU 확장, 원커맨드 리타겟팅, 임의 로봇 학습, sim2sim, sim2real, 고품질 렌더링, 텍스트-투-모션, 절차적 씬 생성, 생성형 정책까지 한 저장소 안에서 전부 다룬다. 셋째, NVIDIA Research 브랜드와 Apache-2.0 완전 오픈소스 라이선스가 결합되어 학계·산업계 양쪽에서 채택 장벽이 낮다.

경쟁/유사 프로젝트 대비 무엇이 다른가

3기술 스택 전체 지도

시뮬레이터 백엔드 5종 · 강화학습 프레임워크(PyTorch Lightning Fabric) · 리타겟팅/변환 파이프라인.

setup.py는 아주 단순하다 — 패키지 이름 protomotions, 버전 3.1, find_namespace_packages로 하위 패키지를 전부 포함한다. 진짜 복잡함은 의존성 쪽에 있다 — 시뮬레이터별로 requirements_isaacgym.txt·requirements_isaaclab.txt·requirements_newton.txt·requirements_mujoco.txt·requirements_genesis.txt 5개의 별도 requirements 파일이 존재한다. 이는 "하나의 코드베이스, 여러 개의 설치 프로파일"이라는 설계 철학을 그대로 드러낸다.

백엔드별 시뮬레이터 스택

학습/에이전트 스택

4아키텍처 심화 분석

멀티 시뮬레이터 추상화 · MdpComponent 모듈 조립 · obs/reward/control 분리 · 학습 루프 전체 흐름.

ProtoMotions3의 아키텍처를 이해하는 가장 빠른 길은 "이 저장소가 어떤 문제를 풀려고 이렇게 설계됐는가"를 먼저 보는 것이다. 목표는 ① 물리 엔진이 바뀌어도 학습 코드는 그대로, ② 새로운 과제(steering·mimic·masked_mimic 등)를 만들 때 거대한 환경 클래스를 통째로 새로 짜지 않아도 되게, ③ 학습된 정책을 ONNX로 내보낼 때 "이 관측값이 어디서 왔는지"를 자동으로 추적할 수 있게 하는 것이다. 이 세 목표가 각각 Simulator 추상 클래스, MdpComponent 컴포넌트 시스템, FieldPath 컨텍스트 경로라는 세 가지 설계로 구현되어 있다.

① Simulator 추상 클래스 — "20개 이상의 계약"으로 시뮬레이터를 갈아 끼운다

protomotions/simulator/base_simulator/simulator.py(1,679줄)는 Simulator(RecordingMixin, ABC)라는 추상 클래스를 정의한다. _physics_step·_apply_simulator_pd_targets·_apply_simulator_torques·_get_simulator_bodies_state·_get_sim_body_ordering 등 @abstractmethod로 표시된 메서드가 20개 이상이며, 각 물리 엔진 구현체(isaacgym/simulator.py·newton/simulator.py 등)는 이 메서드들만 자신의 API에 맞게 구현하면 된다. 그 위의 공개 API(reset()·step()·get_bodies_state())는 전부 부모 클래스에 한 번만 구현되어 있어, 학습 루프·리타겟팅·평가 코드는 어떤 시뮬레이터를 쓰든 완전히 동일하다.

② MdpComponent — "관측/보상/종료 함수 + 데이터 출처"를 하나로 묶는다

실제 소스(protomotions/envs/mdp_component.py)를 열어 보면, MdpComponent 클래스는 세 부분으로 나뉜다: compute_func(순수 텐서 함수 — 부작용 없이 입력을 받아 출력을 계산), dynamic_vars(compute_func의 파라미터 이름을 FieldPath 객체에 매핑 — "이 값은 매 스텝 바뀐다"는 뜻), static_params(가중치·상수처럼 실행 중 안 바뀌는 값). 이 구조가 왜 중요한가는 get_bindings_dict() 메서드를 보면 드러난다 — dynamic_vars의 FieldPath들이 그대로 ONNX 입력 이름 문자열로 변환된다. 즉 "이 관측값이 컨텍스트의 어느 경로에서 왔는지"를 설정 단계에서부터 명시적으로 선언해 두면, 나중에 배포 파이프라인이 자동으로 "로봇이 실제로 어떤 센서 데이터를 넣어줘야 하는지"를 추출할 수 있다.

# mdp_component.py 실제 docstring 예제 (경로 표기 + 정적 파라미터 분리)
observation_components = {
    "max_coords_obs": MdpComponent(
        compute_func=compute_humanoid_max_coords_observations,
        dynamic_vars={
            "body_pos": EnvContext.current.rigid_body_pos,  # FieldPath
            "body_rot": EnvContext.current.rigid_body_rot,
        },
        static_params={"local_obs": True},  # ONNX 그래프에 상수로 굽힘
    ),
}

context_views.py의 EnvContext는 클래스 레벨로 접근하면(EnvContext.current.dof_pos) 설정용 FieldPath 객체를 반환하고, 인스턴스 레벨로 접근하면(ctx.current.dof_pos) 실제 텐서 값을 반환하는 이중 접근(dual access) 디스크립터 패턴을 쓴다. 이 트릭 덕분에 실험 config 파일 안에서 IDE 자동완성을 받으면서도, 런타임에는 진짜 텐서가 흘러 들어온다.

③ 관측/보상/제어의 3단 분리 — steering 과제로 보는 실전 조립

README가 자랑하는 "몬리식 env 클래스 없이 모듈로 과제를 조립한다"는 주장은 실제로 steering(방향 조종) 과제의 4개 파일에서 그대로 확인된다.

실제 steering_control.py(약 220줄)를 열어 보면, SteeringControl 클래스는 reset()(새 목표 방향·속도 샘플링, 10%는 완전 랜덤 방향, 나머지는 이전 방향에서 점진적 변화), step()(목표 갱신 시점 확인), populate_context()(계산된 상태를 EnvContext.steering에 채워 넣기)라는 세 메서드만으로 과제 상태 관리를 전부 해결한다. 이 클래스는 관측·보상 계산 로직을 전혀 모른다 — 오직 "지금 목표가 무엇인지"만 컨텍스트에 올려 두고, 그걸 누가 어떻게 쓰는지는 mlp.py가 MdpComponent로 배선한다. 이게 바로 "몬리식 env 클래스가 필요 없다"는 주장의 실체다.

④ 학습 루프 — Lightning Fabric 기반 PPO/AMP 순환

train_agent.py(1,020줄)의 main()은 체크포인트 유무로 resume/warm_start/fresh 세 모드를 판별한 뒤, build_all_components()로 terrain·scene_lib·motion_lib·simulator를 만들고, BaseEnv와 BaseAgent(PPO/AMP/ASE 등)를 초기화해 agent.fit()을 호출한다. 흥미로운 점은 설정 저장 방식이다 — dataclass 기반 config 객체는 JSON/YAML로 안전하게 직렬화하기 어려운 타입(Union, 중첩 dataclass, torch.Tensor)을 담고 있어서, resolved_configs.pt(pickle, 완전 재현 보장)와 resolved_configs.yaml(사람이 읽기용, best-effort)을 동시에 저장한다. "학습 중 CLI로 오버라이드한 값은 영구적으로 저장되어 재시작 시에도 그대로 적용된다"는 점도 코드 주석에 명시적으로 경고되어 있다 — 실무에서 재현성 버그를 막기 위한 설계다.

5디렉토리 구조 해부

protomotions/·examples/·pyroki/·deployment/·usd_convert/ 실제 내용 기반.

6학습 포인트 (기술별)

이 저장소에서 실제로 무엇을 배울 수 있는가 + 각 주제 실습 아이디어.

7하드웨어 / 시스템 요구사항

GPU/CUDA 요구사항 · 시뮬레이터별 규모 · 현실적인 개인 대안.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — GPU 없이 코드를 읽는 것부터, GPU 보유자를 위한 전체 학습 파이프라인까지.

과제 1 · 아키텍처 다이어그램 손으로 그려보기 난이도 ★☆☆☆☆

GPU도, 설치도 필요 없는 첫 실습이다. examples/experiments/steering/mlp.py 파일 하나만 읽고, "이 실험이 실행될 때 어떤 순서로 어떤 파일이 호출되는지"를 손으로 화살표 도식을 그려 본다. terrain_config()·env_config()·agent_config() 세 함수가 무엇을 반환하고 train_agent.py의 어느 부분이 그것을 소비하는지 추적하는 것이 목표다.

# 코드를 실행하지 않고 읽기만 해도 되는 실습 — 저장소 클론만
git clone https://github.com/NVlabs/ProtoMotions.git
cd ProtoMotions
cat examples/experiments/steering/mlp.py
# env_config() 함수가 반환하는 EnvConfig의 필드들을 나열해 보기
grep -n "def \|_control\|_obs\|_reward" examples/experiments/steering/mlp.py

과제 2 · MdpComponent 미니 버전 직접 구현 난이도 ★★☆☆☆

protomotions/envs/mdp_component.py를 참고하되 그대로 베끼지 않고, "함수 + 파라미터 매핑"을 저장하는 나만의 MiniComponent 클래스를 파이썬으로 새로 작성한다. compute() 메서드가 딕셔너리에서 실제 값을 찾아와 함수에 넣어 호출하도록 구현하고, 원본의 to_dict() 직렬화 메서드까지 흉내 내 본다.

// 직접 구현해 볼 시그니처 (GPU/torch 불필요, 순수 파이썬으로 연습 가능)
class MiniComponent:
    def __init__(self, compute_func, dynamic_vars: dict, static_params: dict = None):
        self.compute_func = compute_func
        self.dynamic_vars = dynamic_vars     # {param_name: context_key}
        self.static_params = static_params or {}

    def compute(self, ctx: dict):
        # TODO: dynamic_vars의 각 경로를 ctx에서 찾아 실제 값으로 치환한 뒤
        # compute_func(**resolved, **static_params) 호출
        ...

# 테스트 예시
def add(a, b, scale=1.0):
    return (a + b) * scale

comp = MiniComponent(add, {"a": "x", "b": "y"}, {"scale": 2.0})
assert comp.compute({"x": 3, "y": 4}) == 14

과제 3 · MuJoCo CPU 백엔드로 사전학습 체크포인트 재생 난이도 ★★★☆☆

GPU가 없어도 시도할 수 있는 첫 "진짜 실행" 실습이다. requirements_mujoco.txt 안내를 그대로 따라 CPU 전용 conda 환경을 만들고, 공식 문서(Quick Start)가 제공하는 사전학습 체크포인트를 내려받아 재생해 본다. 물리 시뮬레이션이 실제로 로봇의 관절을 움직이는 것을 화면으로 확인하는 것이 이 실습의 핵심이다.

# MuJoCo CPU 백엔드 설치 (requirements_mujoco.txt 안내 그대로)
conda create -n protomotions_mujoco python=3.10
conda activate protomotions_mujoco
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install -e .
pip install -r requirements_mujoco.txt

# 사전학습 체크포인트로 추론 (num_envs=1 필수)
python protomotions/inference_agent.py \
    --checkpoint results/pretrained/last.ckpt \
    --simulator mujoco \
    --num-envs 1

과제 4 · steering 과제의 보상 가중치 바꿔 학습 결과 비교 난이도 ★★★★☆

GPU 1장(중급 이상)이 있다면, examples/experiments/steering/mlp.py의 compute_heading_velocity_rew 호출부에서 방향 일치 가중치(0.7)와 자세 일치 가중치(0.3)를 각각 0.5/0.5, 0.9/0.1로 바꿔가며 세 번 학습시켜 본다. num_envs는 작게(예: 512) 설정해 학습 시간을 단축하고, TensorBoard로 세 실험의 보상 곡선을 겹쳐 비교한다.

# 예시 학습 명령 (GPU 1장, 축소된 num_envs)
python protomotions/train_agent.py \
    --robot-name g1 \
    --simulator isaacgym \
    --experiment-path examples/experiments/steering/mlp.py \
    --experiment-name steering_test_v1 \
    --motion-file data/motions/amass_train.pt \
    --num-envs 512 \
    --batch-size 4096

과제 5 · (GPU 다중 보유자용) 신규 로봇 추가 & sim2sim 파이프라인 완주 난이도 ★★★★★

README의 "Add Your Own Robot" 가이드(MJCF 자산 추가 → robot_configs 설정 채우기 → factory.py에 등록)를 그대로 따라, 간단한 로봇(예: 2족 보행 장난감 수준의 MJCF)을 하나 등록해 본다. 이후 --simulator isaacgym으로 학습한 정책을 --simulator newton·--simulator mujoco로 각각 sim2sim 테스트하며, 3개 물리 엔진에서 행동이 얼마나 일관되는지 직접 관찰하는 것이 최종 목표다.

9관련 기술 심화 학습 로드맵

강화학습 기초 → 물리 시뮬레이션 → 휴머노이드 제어 → sim2real — 8주 계획.

10핵심 키워드 사전

이 문서와 저장소에 나온 주요 용어 정리.

11참고 링크

공식 저장소 · 공식 문서 · 관련 프로젝트 · 데이터셋.