stable-worldmodel: 재현 가능한 World Model 연구 및 평가 플랫폼

재현 가능한 world model 연구 및 평가를 위한 플랫폼.

설치 (Installation) ·
빠른 시작 (Quick Start) ·
환경 (Environments) ·
솔버 및 베이스라인 (Solvers & Baselines) ·
문서화 (Documentation) ·
논문 (Paper) ·
인용 (Citation)

stable-worldmodel은 대규모의 표준화된 환경(standardized environments) 전반에 걸쳐 world model 연구의 세 가지 단계 — 데이터 수집 (collecting data), 훈련 (training), 그리고 모델 예측 제어 (model-predictive control)를 이용한 평가 (evaluating with model-predictive control) — 에 대한 단일하고 통합된 인터페이스(single, unified interface)를 제공합니다. 이 라이브러리는 일반적인 베이스라인 및 플래닝 솔버(planning solvers)의 레퍼런스 구현체(reference implementations)와 함께 제공되므로, 연구 코드는 중요한 기여 부분인 모델과 목적(model and the objective)에 집중할 수 있습니다.

PyPI에서:

pip install stable-worldmodel # base만
pip install 'stable-worldmodel[all]' # + 훈련, 환경, 데이터 형식

LeRobot 데이터셋 지원은 별도의 선택적 추가 기능(opt-in extra)입니다 (Python 3.12 이상 필요): pip install 'stable-worldmodel[lerobot]'

.

소스에서 (개발 버전):

git clone https://github.com/galilai-group/stable-worldmodel
cd stable-worldmodel
uv venv --python=3.10 && source .venv/bin/activate
...

데이터셋과 체크포인트는 $STABLEWM_HOME 아래에 저장됩니다 (기본값은 ~/.stable_worldmodel/). 변수를 재정의하여 선호하는 저장 위치를 지정할 수 있습니다.

이 라이브러리는 활발하게 개발 중입니다. API는 마이너 버전 간에 변경될 수 있습니다.

import stable_worldmodel as swm
from stable_worldmodel.policy import WorldModelPolicy, PlanConfig
from stable_worldmodel.solver import CEMSolver
...

레퍼런스 구현체는 scripts/train/에 제공됩니다.

: lewm.py는 LeWM을 구현하며, prejepa.py는 DINO-WM을 재현합니다.

H200 GPU에서 Push-T LanceDB 데이터셋으로 훈련된 LeWM의 GPU 활용률.

기록(Recording), 로드(loading), 변환(conversion)은 모두 작은 **형식 레지스트리 (format registry)**를 통해 이루어집니다. 트레이드오프에 맞는 백엔드를 선택하거나, 자체적으로 등록할 수 있습니다.

형식 (Format)	디스크 레이아웃 (On-disk layout)	최적 용도 (Best for)
lance	LanceDB 테이블 (에피소드 연속적 플랫 로우)	기본값 — 추가(append)에 용이, 빠른 인덱스 읽기
hdf5	단일 .h5 파일 (컬럼당 하나의 데이터셋)	휴대 가능한 단일 파일 아티팩트
folder	.npz 컬럼 + 스텝당 하나의 JPEG	검사, 부분 키 스트리밍 (partial-key streaming)
video	.npz 컬럼 + 에피소드당 하나의 MP4 (decord)	긴 에피소드, 압축된 이미지 저장
lerobot	lerobot://<repo_id> (읽기 전용 어댑터)	LeRobot Hub 데이터셋에서 직접 학습/평가

world.collect("data/pusht.lance", episodes=100) # 기본값: lance
world.collect("data/pusht_video", episodes=100, format="video") # mp4 에피소드
ds = swm.data.load_dataset("data/pusht.lance", num_steps=16) # 자동 감지
...

모든 라이터 (writer)는 mode 키워드 인자 (kwarg) ('append' (기본값), 'overwrite', 'error')를 허용합니다. world.collect를 다시 실행하면 실패하는 대신 기존 데이터셋을 확장합니다.

처리량 및 저장소 벤치마크 (Throughput & storage benchmarks)

아래 수치는 scripts/benchmark/compare_h5_lance.py를 통해 생성되었으며, 해당 스크립트로 재현할 수 있습니다. 벤치마크는 LeWorldModel 논문의 PushT 데이터셋을 사용합니다.

형식 (Format)	소스 (Source)	캐시 (Cache)	초당 샘플 수 (samples/s)	스텝당 밀리초 (ms/step)
HDF5	로컬 (local)	캐시 없음 (no-cache)	1416.1	45.2
...
형식 (Format)	로컬 크기 (Local size)
---	---
HDF5	43.12 GB
...

환경은 DeepMind Control Suite, Gymnasium classic control, OGBench, Craftax, Arcade Learning Environment (100개 이상의 Atari 게임), 그리고 고전적인 월드 모델 벤치마크 (Two-Room, PushT)에서 가져옵니다. 대부분의 환경은 변화 요인 (factors of variation) — 독립적으로 제어 가능한 시각적 및 물리적 파라미터 (조명, 질감, 역학, 형태학) — 세트를 포함하고 있어, 추가 설정 없이도 분포 변화 (distribution shifts)에 대한 제로샷 일반화 (zero-shot generalization)를 쉽게 평가할 수 있습니다. 새로운 환경을 추가하려면 Gymnasium 인터페이스를 준수하기만 하면 됩니다.

전체 환경 목록 (Full environment list)

Environment ID	# FoV
swm/PushT-v1	16
...
Solver	Type
---	---
Cross-Entropy Method (CEM)	Sampling
...
Baseline	Type
---	---
DINO-WM	JEPA
...

설치 후에는 코드를 작성하지 않고도 데이터셋, 환경 및 체크포인트 (checkpoints)를 검사하거나 변환할 수 있는 swm 명령어를 사용할 수 있습니다:

swm datasets # 캐시된 데이터셋 목록 표시
swm inspect pusht_expert_train # 특정 데이터셋 검사
swm envs # 등록된 모든 환경 목록 표시
...

API 레퍼런스, 튜토리얼 및 가이드를 포함한 전체 문서는 galilai-group.github.io/stable-worldmodel에서 확인할 수 있습니다.

@misc{maes_lld2026swm,
title = {stable-worldmodel: A Platform for Reproducible World Modeling Research and Evaluation},
author = {Lucas Maes and Quentin Le Lidec and Luiz Facury and Nassim Massaudi and
...

이슈 (issue)를 생성해 주세요 — 기꺼이 도와드리겠습니다.