Microduck RL – 소형 이족 로봇을 위한 시뮬레이션-실제 훈련

개요 – 800g, 25cm 키의 이족 보행 로봇(Microduck)에게 걷기, 서기, 구르기, 스케이트, 차기 등을 가르치는 MuJoCo-Warp 환경 및 훈련 스크립트 모음입니다. 정책은 PPO로 학습되고 ONNX로 내보내진 후, 동반 마이크로덕 런타임에 의해 실제 로봇에서 실행됩니다.

중요한 이유

완전한 시뮬레이션-실제 파이프라인 – BAM 액추에이터 모델(전압 제어 Dynamixel XL330)을 현실적인 마찰, 백래시, 도메인 무작위화와 함께 사용합니다. 이러한 충실도는 이렇게 작은 서보 구동 로봇의 시뮬레이션-실제 격차의 가장 큰 원인입니다.
핫스왑 가능한 정책 – 모든 정책은 61차원 관측 벡터를 공유하므로, 데몬을 재시작하지 않고도 걷기, 회복, 트릭 등을 전환할 수 있습니다.
오픈소스 재현성 – MJCF 로봇 파일(Onshape에서 생성)부터 훈련 명령, 내보내기 스크립트, 게시 워크플로우까지 모든 것이 제공됩니다.

작동 방식(높은 수준의 흐름)

환경 정의 – src/mjlab_microduck/tasks/*_env_cfg.py가 각 작업(예: Mjlab-Velocity-Flat-MicroDuck)을 설명합니다. 지형, 보상 함수, 무작위화 플래그를 설정합니다.
훈련 – uv run train <task> --env.scene.num-envs 4096를 실행합니다. PPO는 MuJoCo Warp를 통해 GPU에서 실행됩니다. 일반적인 보행은 1~2시간 안에 완료됩니다.
검사 – uv run play …는 MuJoCo 뷰어에서 체크포인트를 시각화합니다. 비디오를 녹화할 수도 있습니다.
내보내기 – scripts/export.py는 체크포인트를 관측 정규화기를 이미 포함하는 ONNX 그래프로 변환합니다.
게시 – uv run publish …는 ONNX 파일과 매니페스트를 Hugging Face Hub에 업로드하여 모든 Microduck 로봇에 설치 가능하게 합니다.
배포 – 로봇에서 robotctl policy add … 및 robotctl policy load walk …로 정책을 로드합니다. 데몬은 런타임에 이를 전환합니다.

주요 구성 요소

구성 요소	역할
BAM 액추에이터 모델	전압 제어, 역기전력, 쿨롱 및 스트리벡 마찰, 선택적 ±1° 기어 유격(백래시)을 시뮬레이션합니다.
MJCF 로봇 파일	Onshape에서 내보냄. 여러 변형(`robot_walk.xml`, `robot_groundcontact.xml`, `robot_groundcontact_rollers.xml`, 백래시 버전 포함).
작업 레지스트리 (`src/mjlab_microduck/tasks/__init__.py`)	자동 생성된 백래시 쌍을 포함한 모든 환경을 등록합니다.
훈련 CLI (`train_cli.py`)	mjlab 훈련 프레임워크의 얇은 래퍼. 업스트림 mjlab CLI와 동일합니다.
내보내기/추론 스크립트	`scripts/export.py`는 ONNX를 생성합니다. `scripts/infer_policy.py`는 CPU MuJoCo에서 정책을 실행하여 빠른 테스트를 수행합니다.
게시 도구	ONNX + `manifest.json` + README를 패키징하고 Hugging Face에 푸시하여 검증(형상, NaN, 정규화기)을 처리합니다.
테스트	보상 부호 규칙, 관절 인덱스 일관성, NaN 가드를 확인하는 작은 pytest 스위트.

시작하기(빠른 단계)

# 클론 및 이동
git clone https://github.com/pollen-robotics/microduck_rl && cd microduck_rl

# 보행 훈련(GPU 필요)
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096

# 시청
uv run play Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <entity/project/run_id>

# ONNX로 내보내기
uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <...>

# 선택 사항: Hugging Face에 게시
uv run publish --onnx output.onnx --repo <user>/microduck-walk --kind perpetual --slot walk

GPU가 없나요? 훈련을 Hugging Face Jobs로 오프로드하려면 --hf-jobs를 추가하세요.

일반적인 사용 사례

연구 – 실제 이족 로봇에서 도메인 무작위화, 액추에이터 모델링 또는 새로운 보상 설계를 실험합니다.
교육/데모 – 몇 줄의 코드로 작은 로봇이 트릭(구르기, 롤러 스케이트)을 수행하는 것을 보여줍니다.
커뮤니티 공유 – 맞춤형 보행이나 트릭을 Hugging Face Hub에 게시합니다. Microduck이 있는 사람은 누구나 즉시 설치할 수 있습니다.

라이선스 및 저작자 표시

코드: Apache 2.0.
3D 메시: CC-BY-NC-SA 4.0(LICENSE-MODELS.md 참조).

Microduck RL은 현실적인 액추에이터 물리, 도메인 무작위화, 간소화된 게시 워크플로우를 갖춘 실제 로봇을 위한 현대적인 시뮬레이션-실제 강화 학습의 구체적인 종단 간 예입니다.

pollen-robotics/microduck_rl