이미지·영상 생성
최종 업데이트
Oasis 500M 로컬 실행: 이미지와 행동 파일로 게임 영상 만들기
generate.py에 시작 이미지와 행동 기록을 넣으면 다음 프레임을 영상 파일로 저장해요.
Oasis 500M 공개 추론 코드는 시작 이미지나 영상과 action 파일을 읽어 그 조작에 따른 다음 프레임1을 생성해요. Linux NVIDIA CUDA2 환경에 open-oasis를 복제하고 Hugging Face 접근 조건을 직접 수락한 뒤 DiT3·ViT-VAE 가중치 두 개를 내려받아 python generate.py를 실행하면 작업 폴더에 video.mp4가 저장됩니다.
행동 파일이 다음 프레임을 지정해요
Oasis는 시작 화면과 사용자 행동으로 다음 게임 화면을 생성하는 월드 모델이에요. 공개된 500M 추론 코드는 시작 이미지나 영상에서 조건 프레임을 읽고, 별도 action 파일의 조작 시퀀스를 넣어 다음 프레임들을 만들어 video.mp4로 저장해요. 이 경로는 스크립트로 영상을 만드는 오프라인 추론이며, 브라우저 게임처럼 키보드를 누르며 진행하는 UI는 제공하지 않습니다. 공식 open-oasis 저장소
웹사이트의 라이브 데모는 더 큰 버전이라고 모델 카드가 안내해요. 여기서 내려받는 Oasis 500M은 별도 공개 체크포인트4와 추론 코드이므로, 큰 웹 데모와 같은 지연 시간이나 상호작용을 기대하지 말고 파일 출력을 목표로 실행해요. Oasis 500M 모델 카드
NVIDIA GPU가 보이는 Linux Python 환경이 필요해요
공개 generate.py는 시작할 때 torch.cuda.is_available()가 참인지 검사해요. CPU5 전용 PyTorch6나 CUDA를 사용할 수 없는 장치에서는 이 코드가 실행되지 않습니다. 저장소 README의 설치 예시는 CUDA 12.1 인덱스에서 PyTorch·torchvision을 설치하고, einops, diffusers, timm, av를 추가해요. 현재 GPU7와 드라이버 조합이 해당 PyTorch CUDA 패키지를 지원하는지 실행 전에 확인하세요. 저장소는 최소 VRAM8 수치를 공개하지 않아요.
git clone https://github.com/etched-ai/open-oasis.git
cd open-oasis
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
python -m pip install einops diffusers timm av체크포인트 접근 조건을 읽고 가중치 두 개를 받아요
Oasis 파일은 Hugging Face에서 로그인과 접근 조건 수락을 요구해요. 모델 페이지에서 본인에게 적용되는 조건을 읽고, 연락처 정보를 공유해 접근하는 조건에 동의할 때만 본인 계정으로 진행하세요. 이 동의 과정은 각 사용자가 결정해야 하므로 가이드가 대신 처리하지 않습니다. 모델 카드의 다운로드 영역에서 조건 상태를 확인할 수 있어요. Etched/oasis-500m
받을 파일은 DiT 체크포인트 oasis500m.safetensors와 ViT-VAE 체크포인트 vit-l-20.safetensors 두 개예요. hf auth login으로 본인 계정에 로그인한 뒤, --local-dir .을 지정해 현재 open-oasis/ 폴더에 저장하세요. 토큰9은 공유하거나 원고·코드에 적지 마세요. 모델 파일 안내
python -m pip install -U huggingface_hub
hf auth login
hf download Etched/oasis-500m oasis500m.safetensors --local-dir .
hf download Etched/oasis-500m vit-l-20.safetensors --local-dir .샘플 이미지와 조작 기록으로 첫 영상을 만들어요
가중치 두 파일이 저장소 루트에 있으면 open-oasis/에서 python generate.py를 실행해요. 기본값은 sample_data/sample_image_0.png와 sample_data/sample_actions_0.one_hot_actions.pt를 사용하고, 출력 경로는 video.mp4예요. 첫 실행은 모델을 GPU에 올리는 데 시간이 들고 프레임 생성도 진행하므로, 터미널에서 inference10 arguments와 진행 표시가 끝날 때까지 기다립니다. generate.py 기본 경로
작업이 끝나면 open-oasis/video.mp4를 열어 시작 장면 이후의 프레임이 들어 있는지 확인해요. 스크립트 기본 --num-frames 값은 32, 저장 영상의 기본 --fps 값은 20입니다. 여기서 --fps는 영상 파일에 지정하는 재생 프레임률이지 모델 생성 속도를 나타내지 않아요. 공식 기본 사용법
시작 이미지는 바꾸고 행동 파일은 그대로 둘 수 있어요
자신의 PNG·JPG·JPEG를 시작 화면으로 넣으려면 --prompt-path에 이미지 경로를 지정해요. 기본 action 파일은 그대로 두면 예제의 조작 시퀀스를 사용합니다. 행동도 바꾸려면 .actions.pt 또는 .one_hot_actions.pt 파일을 준비해 --actions-path로 경로를 지정하세요. generate.py는 이 파일에서 행동 배열을 읽어 프레임 생성 모델에 전달합니다.
/path/to/opening-frame.png를 실제 이미지 경로로 바꿔 실행해요. 동영상을 시작 입력으로 쓰면 --video-offset으로 읽을 위치를, --n-prompt-frames로 조건 프레임 수를 정합니다. 사용 가능한 옵션은 python generate.py --help에서 확인할 수 있고, --num-frames는 출력 프레임 수를 바꿔요.
python generate.py \
--prompt-path /path/to/opening-frame.png \
--actions-path sample_data/sample_actions_0.one_hot_actions.pt \
--output-path video.mp4CUDA나 파일 오류는 첫 입력과 경로부터 확인해요
실행 직후 AssertionError가 나면 코드의 CUDA 가용성 검사에 걸렸는지 확인해요. 가상환경11을 활성화한 터미널에서 python -c 'import torch; print(torch.cuda.is_available(), torch.version.cuda)'를 실행합니다. 첫 값이 False면 현재 PyTorch가 GPU를 볼 수 없으므로, GPU와 드라이버 조합에 맞는 CUDA 빌드를 설치한 뒤 같은 명령으로 다시 확인하세요. Oasis가 공개한 기본 설치 명령은 CUDA 12.1 wheel 인덱스를 사용합니다.
가중치 파일을 찾지 못했다는 메시지가 나오면 pwd로 현재 폴더가 open-oasis/인지 보고, 그 폴더에 두 .safetensors 파일이 있는지 확인해요. 다른 위치에 보관했다면 --oasis-ckpt와 --vae-ckpt로 실제 파일 경로를 전달할 수 있습니다. 추론 코드의 체크포인트 옵션
동작 파일은 기본 .one_hot_actions.pt를 먼저 사용하고, 출력이 완성되면 시작 프레임과 video.mp4를 함께 열어 확인해요. 다음 실행에서는 이미지 또는 action 파일 중 하나만 바꾸면 결과 차이를 입력별로 비교할 수 있습니다. 저장소는 최소 GPU 메모리를 공개하지 않아요. CUDA 오류나 메모리 부족이 나면 지원되는 --num-frames 옵션으로 출력 프레임 수를 줄여 다시 실행해 보세요.
용어 각주
프레임 — 영상의 한 장면을 이루는 단일 이미지입니다.
본문으로 돌아가기CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다.
본문으로 돌아가기DiT — Diffusion Transformer의 약자입니다. 트랜스포머 구조를 이용해 확산 과정에서 노이즈가 있는 표현을 단계적으로 다듬는 모델 구조입니다.
본문으로 돌아가기체크포인트 — 학습된 모델의 가중치 등을 저장한 파일입니다. 같은 모델 계열도 버전이나 용도에 따라 다른 체크포인트를 쓸 수 있습니다.
본문으로 돌아가기CPU — 운영체제와 일반 프로그램 명령을 실행하고, AI에서는 전처리·데이터 이동 등 범용 연산을 맡는 중앙 처리 장치입니다.
본문으로 돌아가기PyTorch — AI 모델을 만들고 실행하는 소프트웨어 프레임워크입니다. 모델과 함께 호환되는 PyTorch 버전 및 하드웨어 지원도 확인해야 합니다.
본문으로 돌아가기GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.
본문으로 돌아가기VRAM — 그래픽카드의 GPU가 사용하는 메모리입니다. 모델 가중치와 계산 중간값을 저장합니다.
본문으로 돌아가기토큰 — 모델이 입력이나 출력을 나누어 처리하는 단위입니다.
본문으로 돌아가기모델 추론 — 학습된 모델을 사용해 입력에 대한 출력을 계산하는 과정입니다. 이 사이트에서 로컬 추론은 사용자의 기기에서 모델을 실행하는 경우를 뜻합니다.
본문으로 돌아가기Python 가상환경 — 프로젝트별로 Python 패키지를 분리해 설치하는 공간입니다. 패키지 버전 충돌을 줄이는 데 쓰입니다.
본문으로 돌아가기
자주 묻는 질문
- 이 글에서 가장 먼저 확인할 것은 무엇인가요?
- Oasis 500M 공개 추론 코드는 시작 이미지나 영상과 action 파일을 읽어 그 조작에 따른 다음 프레임을 생성해요. Linux NVIDIA CUDA 환경에 `open-oasis`를 복제하고 Hugging Face 접근 조건을 직접 수락한 뒤 DiT·ViT-VAE 가중치 두 개를 내려받아 `python generate.py`를 실행하면 작업 폴더에 `video.mp4`가 저장됩니다.
- 필요한 메모리는 어느 정도인가요?
- 공개 `generate.py`는 시작할 때 `torch.cuda.is_available()`가 참인지 검사해요. CPU 전용 PyTorch나 CUDA를 사용할 수 없는 장치에서는 이 코드가 실행되지 않습니다. 저장소 README의 설치 예시는 CUDA 12.1 인덱스에서 PyTorch·torchvision을 설치하고, `einops`, `diffusers`, `timm`, `av`를 추가해요. 현재 GPU와 드라이버 조합이 해당 PyTorch CUDA 패키지를 지원하는지 실행 전에 확인하세요. 저장소는 최소 VRAM 수치를 공개하지 않아요.
- 조건과 출처는 어디서 확인하나요?
- 웹사이트의 라이브 데모는 더 큰 버전이라고 모델 카드가 안내해요. 여기서 내려받는 Oasis 500M은 별도 공개 체크포인트와 추론 코드이므로, 큰 웹 데모와 같은 지연 시간이나 상호작용을 기대하지 말고 파일 출력을 목표로 실행해요. [Oasis 500M 모델 카드](https://huggingface.co/Etched/oasis-500m)