Code-as-World란?
Code-as-World는 실행 가능한 코드를 통해 물리적 세계를 표현하기 위한 연구 프로젝트입니다. 핵심 아이디어는 픽셀이 장면에 대한 증거를 제공하지만, 관찰된 결과를 만들어 낸 객체, 상태, 구조, 동역학 또는 메커니즘을 직접 정의하지는 않는다는 것입니다.
이 프로젝트는 반복적인 시뮬레이션과 검증에 기반한 에이전트 프로세스를 사용하여 관찰로부터 실행 가능한 세계 표현을 찾아냅니다. 이러한 표현은 시각적 증거를 재사용 가능한 물리 데이터로 변환하고 정량적 물리 추론을 지원합니다.
이번 릴리스는 두 가지 비전-언어 체크포인트인 Code-as-World-VL-4B와 Code-as-World-VL-9B에 대한 로컬 추론 및 평가를 지원합니다. 또한 vLLM을 통한 OpenAI 호환 서빙과 MuJoCo로 구축한 동영상 기반 물리 추상화 예제도 포함합니다.
주요 기능
- 실행 가능한 세계 표현: 픽셀을 장면의 완전한 온톨로지로 취급하는 대신 물리적 상태, 동역학 및 메커니즘을 모델링합니다.
- 공개된 두 체크포인트: 4B 및 9B Code-as-World-VL 모델 중에서 선택할 수 있습니다.
- QuantiPhy 평가: 검증 동영상에 대한 정량적 물리 추론 평가를 실행하고 평가기 호환 예측 파일을 생성합니다.
- OpenAI 호환 서빙: 표준 vLLM API 서버를 사용하여 두 체크포인트 중 하나를 제공할 수 있습니다.
- 시뮬레이션 예제: 포함된 탄도 축구 사례를 실행하고 렌더링된 동영상과 궤적을 저장합니다.
사전 요구 사항
CUDA가 활성화된 호스트에서 Python 3.10 또는 3.11을 사용하세요. 또한 hf download 명령에서 사용하는 Git과 Hugging Face CLI가 필요합니다. 모델 저장 공간과 GPU 메모리 요구 사항은 4B 체크포인트, 9B 체크포인트 또는 둘 다 사용하는지에 따라 달라집니다.
CUDA 환경에서 저장소의 명령을 실행하세요. README에는 CPU 전용 추론 방법이 제공되지 않습니다.
Code-as-World 설치
1. 저장소 복제
git clone https://github.com/MirroS-Lab/Code-as-World.git
cd Code-as-World2. 가상 환경 생성 및 활성화
python -m venv .venv
source .venv/bin/activate위 활성화 명령은 Unix 계열 셸을 대상으로 합니다. 활성화한 후 프로젝트에서 제공하는 추론 종속 항목을 설치하세요.
pip install -r requirements/inference.txt3. 체크포인트 다운로드
hf download MirroS-Lab/Code-as-World-VL-4B --local-dir weights/4b
hf download MirroS-Lab/Code-as-World-VL-9B --local-dir weights/9b이 명령은 4B 및 9B 모델을 weights/4b와 weights/9b에 저장합니다. 한 모델만 사용할 예정이라면 해당 체크포인트만 다운로드하세요.
QuantiPhy 평가 실행
QuantiPhy는 이 릴리스에서 사용하는 정량 평가 제품군입니다. Code-as-World 평가를 실행하기 전에 QuantiPhy를 복제하고 검증 동영상을 다운로드하세요.
1. 평가 데이터 준비
git clone https://github.com/Paulineli/QuantiPhy.git /path/to/QuantiPhy
hf download PaulineLi/QuantiPhy-validation \
--repo-type dataset \
--local-dir /path/to/QuantiPhy-validation/path/to/QuantiPhy와 /path/to/QuantiPhy-validation을 시스템의 실제 경로로 바꾸세요.
2. 4B 모델 평가
Code-as-World 저장소에서 다음을 실행하세요.
python -m code_as_world.evaluation 4b \
--input-csv /path/to/QuantiPhy/quantiphy_validation.csv \
--video-dir /path/to/QuantiPhy-validation/validation_videos
3. 9B 모델 평가
python -m code_as_world.evaluation 9b \
--input-csv /path/to/QuantiPhy/quantiphy_validation.csv \
--video-dir /path/to/QuantiPhy-validation/validation_videos각 실행은 outputs/quantiphy/에 세 종류의 결과물을 기록합니다. 평가기 호환 예측 CSV, 개별 실행의 지표 요약, 모델의 원시 생성 결과입니다. 개별 점수의 응답을 검토할 때 원시 출력을 보관하면 유용합니다.
4. 공식 평가기 실행
예측 CSV 파일을 생성한 후 pandas를 설치하고 공식 QuantiPhy 평가기를 호출하세요.
pip install pandas
python /path/to/QuantiPhy/evaluator.py \
outputs/quantiphy \
outputs/quantiphy_metrics \
--gt_file /path/to/QuantiPhy/quantiphy_validation.csv이 명령은 outputs/quantiphy에서 찾은 예측 파일을 quantiphy_validation.csv와 비교해 평가하고, 결과 지표를 outputs/quantiphy_metrics에 기록합니다.
vLLM으로 모델 서빙
체크포인트는 OpenAI 호환 vLLM 엔드포인트를 통해 제공할 수 있습니다. 다음 명령은 GPU 0에서 4B 체크포인트를 서빙합니다.
CUDA_VISIBLE_DEVICES=0 vllm serve weights/4b \
--served-model-name code-as-world-4b \
--chat-template code_as_world/templates/qwen3_5_no_think.jinja \
--chat-template-content-format openai \
--default-chat-template-kwargs '{"enable_thinking":false}' \
--max-model-len 4608 \
--gpu-memory-utilization 0.90 \
--media-io-kwargs '{"video":{"num_frames":16,"fps":-1,"video_backend":"openpangu"}}' \
--mm-processor-kwargs '{"do_sample_frames":false}' \
--mm-processor-cache-gb 0 \
--generation-config vllm서버는 모델을 code-as-world-4b라는 이름으로 등록합니다. 프로젝트의 사고 비활성화 채팅 템플릿을 사용하고, 최대 모델 길이를 4608로 설정하며, openpangu 백엔드를 통해 비디오 입력을 16개 프레임으로 구성합니다.
더 큰 체크포인트를 제공하려면 weights/4b를 weights/9b로, code-as-world-4b를 code-as-world-9b로 바꾸세요.
비디오 기반 추상화 예제 실행
저장소에는 MuJoCo를 기반으로 한 탄도 축구 예제가 포함되어 있습니다. 먼저 별도의 시뮬레이션 요구 사항을 설치하세요.
pip install -r requirements/simulation.txt그런 다음 시뮬레이션을 시작합니다.
python -m code_as_world.simulation시뮬레이션은 렌더링된 비디오와 궤적을 outputs/simulations/에 저장합니다.
궤적만 생성
렌더링된 비디오가 필요하지 않다면 렌더링을 비활성화하세요.
python -m code_as_world.simulation --no-render이 모드는 궤적 데이터만 필요하거나 렌더링에 불필요한 오버헤드가 추가되는 경우에 유용합니다.
고급 사용 팁
- 모델을 신중하게 선택하세요: 다운로드한 체크포인트에 맞춰
4b또는9b평가 인수를 일관되게 사용하세요. - 필요한 것만 다운로드하세요: 한 가지 모델 크기만 사용하는 작업 흐름이라면 두 체크포인트를 모두 저장하지 마세요.
- 원시 생성 결과를 보존하세요: 예측이 특정 점수를 받은 이유를 진단할 때는
outputs/quantiphy/의 파일을 검토하세요. - 두 평가 계층을 모두 실행하세요: Code-as-World 명령은 단일 실행 요약을 생성하고, 공식 QuantiPhy 평가기는 생성된 예측 CSV 파일을 함께 평가할 수 있습니다.
- 제공된 채팅 템플릿을 유지하세요: 제공된 실행 방법은
code_as_world/templates/qwen3_5_no_think.jinja를 명시적으로 사용하고 사고 기능을 비활성화합니다. 문서화된 구성을 재현할 때 이 설정을 유지하세요. - GPU 선택에 주의하세요: 실행 예제는
CUDA_VISIBLE_DEVICES=0과 GPU 메모리 사용률0.90을 사용합니다. CUDA 호스트에 맞는 표시 장치를 선택하되, 그 밖의 변경은 공개된 실행 방법과 달라지는 것으로 간주하세요. - 필요할 때 렌더링을 건너뛰세요: 궤적만 필요한 경우 시뮬레이션 명령에
--no-render를 추가하세요.
추가 자료
연구 배경과 방법론은 기술 보고서, 프로젝트 페이지, MirroS 블로그 게시물을 참고하세요.
결론
Code-as-World는 물리적 장면의 실행 가능한 표현을 탐색할 수 있는 실용적인 릴리스를 제공합니다. 추론 환경을 설치하고 체크포인트를 다운로드한 후 QuantiPhy 평가를 재현하거나, vLLM을 통해 모델을 제공하거나, 포함된 MuJoCo 시뮬레이션을 실행할 수 있습니다. 이러한 작업 흐름은 시각적 관찰이 명시적이고 검증 가능한 물리적 추론을 어떻게 지원할 수 있는지 보여 줍니다.