RTX 5090에서 Matrix-Game 4.0 로컬 브라우저 데모 실행하기

게임 엔진이 입력과 물리를 계산하고 비디오 모델이 화면을 렌더링해요.

Matrix-Game-4 저장소에서 Python 3.12와 CUDA¹ 13.2용 PyTorch² 환경을 만들고 rtx5090 프리셋을 선택해요. manifest revision 2c53100457da7abcf0e966f75637c644d3423a63에서 Ancient Egypt 모델과 게임 자산을 받아 네이티브 게임을 빌드한 뒤 MediaMTX와 모델 서버를 실행하면 http://127.0.0.1:8025/에서 로컬 데모를 열 수 있어요.

실행 조건과 핵심 내용

추론 서버는 Linux, Python 3.12, NVIDIA GPU에서 실행해요.
5090 프리셋은 --preset rtx5090이며 별도 양자화 체크포인트를 요구하지 않아요.
--fps 40은 게임 캡처 목표 주기이며 모델 처리량이나 지연 시간 측정값이 아니에요.
정상 접속 주소는 서버 PC의 http://127.0.0.1:8025/예요.

엔진은 게임을 계산하고 모델은 화면을 그려요

Matrix-Game 4.0은 실행 가능한 저폴리 게임에서 키보드 입력과 물리를 게임 엔진으로 처리하고, causal video model로 깨끗한 RGB 화면을 스트리밍하는 프로젝트예요. HUD와 소리는 렌더러 밖에서 프레임³에 맞춰 붙입니다. 이 설치 경로는 RTX 5090 한 대에서 Ancient Egypt 장면을 로컬 브라우저로 조작하는 구성입니다. 공식 v4 README

모니터에 산길 영상 두 장면이 나란히 보이고 책상에 컴퓨터와 필름 릴이 놓여 있어요 — 실행 환경에는 게임 클라이언트와 추론 서버가 함께 필요해요.

Linux와 RTX 5090 실행 환경을 준비해요

추론은 Linux, NVIDIA GPU⁴, Python 3.12을 요구해요. 브라우저 데모를 띄울 같은 호스트에 네이티브 게임과 GStreamer도 준비해야 하고 CMake, C++20, SDL2, FFmpeg 같은 시스템 의존성은 공식 설치 안내를 따라 설치해요. 모델 추론⁵만 따로 시험할 때와 브라우저 데모를 준비할 때 필요한 구성은 같지 않습니다.

RTX 5090 경로는 rtx5090 또는 선택 사항인 rtx5090-sage 프리셋을 명시해요. 기본 rtx5090은 PyTorch SDPA를 사용하고 SageAttention 설치를 요구하지 않습니다. 다른 GPU가 자동으로 맞는 프리셋을 고르는 구조도 아니에요. 현재 README에 공개된 최적화 추론 지원은 5090이며 5080과 5070은 후속 릴리스 예정으로 적혀 있어요. RTX 5090 설치 안내

가상환경에 PyTorch와 Matrix-Game을 설치해요

터미널에서 저장소를 받고 v4 폴더로 이동해요. 아래 명령은 Python 3.12 가상환경⁶을 만든 다음 CUDA 13.2용 PyTorch 2.12.0과 Matrix-Game 추론·서버·다운로드 의존성을 설치합니다. 명령은 저장소의 Matrix-Game-4 디렉터리에서 실행해야 해요.

RTX 5090용 Python 환경 만들기

git clone https://github.com/SkyworkAI/Matrix-Game.git
cd Matrix-Game/Matrix-Game-4
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch==2.12.0 torchvision==0.27.0 --index-url https://download.pytorch.org/whl/cu132
python -m pip install -e '.[inference,server,download,test]'

고정 revision에서 Ancient Egypt 파일을 받아요

게임 데이터와 모델은 별도로 내려받아요. 두 manifest를 같은 공식 Hub revision 2c53100457da7abcf0e966f75637c644d3423a63에 맞추면 코드가 기대하는 자산 목록과 체크포인트⁷를 섞지 않게 돼요. 기본 예시는 resources/에 Ancient Egypt 장면을 저장합니다. 내려받은 파일은 Git 저장소 밖의 별도 경로로 옮기지 말고 이 디렉터리에 둘 수 있어요.

장면 자산과 체크포인트 받기

matrix-game download --manifest releases/game-assets.json \
  --repo-id Skywork/Matrix-Game-4.0 --repo-type model \
  --revision 2c53100457da7abcf0e966f75637c644d3423a63 \
  --scene ancient-egypt --resources resources

matrix-game download --manifest releases/models.json \
  --repo-id Skywork/Matrix-Game-4.0 --repo-type model \
  --revision 2c53100457da7abcf0e966f75637c644d3423a63 \
  --scene ancient-egypt --resources resources

필름 스트립에 자전거를 탄 사람이 이동하는 여러 장면이 이어져 있어요 — 조작 입력이 게임 상태를 바꾸고 모델은 그 상태의 화면을 렌더링해요.

게임을 빌드하고 두 서비스를 시작해요

설치 안내에 나온 네이티브 라이브러리와 브라우저 데모용 미디어 의존성을 준비한 뒤 같은 Matrix-Game-4/ 폴더에서 게임을 빌드해요. MediaMTX와 모델 서버는 별도 터미널에서 실행하므로 한 창에서 서버 출력이 멈추더라도 종료하지 말고 다른 창에서 다음 단계를 진행하세요. 브라우저 데모 요구 사항

게임 빌드

bash scripts/build_game.sh

첫 번째 터미널: MediaMTX 실행

mediamtx configs/mediamtx.yml

두 번째 터미널: RTX 5090 추론 서버 실행

CUDA_VISIBLE_DEVICES=0 bash scripts/serve.sh \
  --scene ancient-egypt --resources resources --preset rtx5090 \
  --prompt-mode fixed --fps 40

브라우저에서 장면을 열고 첫 오류를 나눠 봐요

두 프로세스가 실행 중이면 서버 PC에서 http://127.0.0.1:8025/를 열어요. 화면에서 조작해 장면과 HUD가 나타나는지 확인하면 첫 경로가 연결된 거예요. 터미널의 --fps 40은 게임 프레임을 캡처하려는 목표 주기입니다. 모델이 초당 40프레임을 생성한다거나 버튼을 누른 뒤 화면이 1/40초에 반응한다는 성능 측정값은 아니에요. 브라우저 디코딩, 전송, 버퍼링도 실제 반응에 영향을 줍니다.

페이지가 열리지 않으면 먼저 MediaMTX와 모델 서버 터미널이 살아 있는지 확인해요. 모델 파일 오류가 보이면 저장소 루트에서 matrix-game verify를 두 manifest 각각 실행해 누락 파일을 찾습니다. GPU에서 CUDA 초기화가 실패하면 이 Python 가상환경의 PyTorch가 CUDA 13.2 빌드인지, NVIDIA 드라이버가 그 조합을 지원하는지 먼저 확인하세요. 검증 명령은 모델을 다시 내려받지 않고 설치된 파일 목록과 체크섬을 비교합니다.

브라우저 데모는 인증된 공개 서비스가 아니라 신뢰하는 단일 사용자용이에요. HTTP·RTSP·WebRTC가 기본으로 loopback에 바인딩되므로 포트 포워딩이나 방화벽 변경으로 인터넷에 직접 공개하지 마세요. 원격 접속이 필요하다면 공개 문서의 SSH 포워딩 절차와 보안 안내를 따르세요. 공식 보안 안내

영상 장면을 보여 주는 모니터와 서로 다른 크기의 컴퓨터가 있는 작업실 — 컴퓨터 그림은 실제 Matrix-Game 4.0 실행 화면이 아니에요.

용어 각주

CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다.
본문으로 돌아가기
PyTorch — AI 모델을 만들고 실행하는 소프트웨어 프레임워크입니다. 모델과 함께 호환되는 PyTorch 버전 및 하드웨어 지원도 확인해야 합니다.
본문으로 돌아가기
프레임 — 영상의 한 장면을 이루는 단일 이미지입니다.
본문으로 돌아가기
GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.
본문으로 돌아가기
모델 추론 — 학습된 모델을 사용해 입력에 대한 출력을 계산하는 과정입니다. 이 사이트에서 로컬 추론은 사용자의 기기에서 모델을 실행하는 경우를 뜻합니다.
본문으로 돌아가기
Python 가상환경 — 프로젝트별로 Python 패키지를 분리해 설치하는 공간입니다. 패키지 버전 충돌을 줄이는 데 쓰입니다.
본문으로 돌아가기
체크포인트 — 학습된 모델의 가중치 등을 저장한 파일입니다. 같은 모델 계열도 버전이나 용도에 따라 다른 체크포인트를 쓸 수 있습니다.
본문으로 돌아가기

자주 묻는 질문

이 글에서 가장 먼저 확인할 것은 무엇인가요?: Matrix-Game-4 저장소에서 Python 3.12와 CUDA 13.2용 PyTorch 환경을 만들고 `rtx5090` 프리셋을 선택해요. manifest revision `2c53100457da7abcf0e966f75637c644d3423a63`에서 Ancient Egypt 모델과 게임 자산을 받아 네이티브 게임을 빌드한 뒤 MediaMTX와 모델 서버를 실행하면 `http://127.0.0.1:8025/`에서 로컬 데모를 열 수 있어요.
선택하지 않는 편이 좋은 경우는 언제인가요?: 브라우저 데모는 인증된 공개 서비스가 아니라 신뢰하는 단일 사용자용이에요. HTTP·RTSP·WebRTC가 기본으로 loopback에 바인딩되므로 포트 포워딩이나 방화벽 변경으로 인터넷에 직접 공개하지 마세요. 원격 접속이 필요하다면 공개 문서의 SSH 포워딩 절차와 보안 안내를 따르세요. [공식 보안 안내](https://github.com/SkyworkAI/Matrix-Game/blob/main/Matrix-Game-4/SECURITY.md)