이 글에서 가장 먼저 확인할 것은 무엇인가요?

Hunyuan-GameCraft는 참조 이미지·텍스트 설명·순서가 있는 이동 입력을 받아 게임 카메라가 움직이는 영상을 만들어요. 공식 Linux CUDA 예제는 704×1216 설정에서 최소 GPU 메모리를 24GB로 안내하지만 매우 느리고, 80GB GPU를 권장해요. 기본 50-step 체크포인트로 예제 마을 이미지를 MP4로 만드는 순서를 따라가요.

필요한 메모리는 어느 정도인가요?

작성자가 공개한 단일 GPU 경로는 Linux, NVIDIA CUDA, GPU 메모리 24GB 이상을 대상으로 해요. 해상도는 704×1216이며 CPU 오프로딩과 FP8을 함께 사용해요. 작성자는 최소 24GB 구성을 매우 느리다고 설명하고, 더 나은 생성 품질을 위해 80GB GPU를 권장해요. 아래 명령은 그 공식 저메모리 예제를 기준으로 해요.

이미지·영상 생성

최종 업데이트 2026-10-30

24GB GPU에서 Hunyuan-GameCraft로 조작 영상을 생성하기

마을 이미지와 키보드 방향 입력을 받아 조작 장면을 MP4로 이어 붙여요.

Hunyuan-GameCraft는 참조 이미지·텍스트 설명·순서가 있는 이동 입력을 받아 게임 카메라가 움직이는 영상을 만들어요. 공식 Linux CUDA¹ 예제는 704×1216 설정에서 최소 GPU² 메모리를 24GB로 안내하지만 매우 느리고, 80GB GPU를 권장해요. 기본 50-step 체크포인트³로 예제 마을 이미지를 MP4로 만드는 순서를 따라가요.

실행 조건과 핵심 내용

입력은 참조 이미지, 장면 설명, 순서가 있는 키보드 카메라 동작이에요.
공식 24GB 단일 GPU 예제는 CPU 오프로딩과 FP8을 사용하고 704×1216에서 매우 느려요.
기본 체크포인트는 50회 추론 단계를 사용하고 8-step 증류 모델은 별도 가중치와 설정을 써요.

이미지와 이동 입력으로 게임 장면을 이어요

Hunyuan-GameCraft는 게임 엔진의 물리나 조작 가능한 게임을 실행하는 대신, 참조 이미지·프롬프트⁴·키보드와 마우스에서 만든 카메라 동작을 받아 다음 장면을 영상으로 생성해요. 이 예제에서는 저장소에 포함된 asset/village.png를 첫 장면으로 쓰고 w, a, d, s 입력을 순서대로 넣어 마을을 이동하는 클립을 만들어요. 한 동작 입력에 해당하는 프레임⁵ 구간을 순차 생성해 MP4로 저장합니다. Hunyuan-GameCraft 공식 저장소

작성자가 공개한 단일 GPU 경로는 Linux, NVIDIA CUDA, GPU 메모리 24GB 이상을 대상으로 해요. 해상도는 704×1216이며 CPU⁶ 오프로딩⁷과 FP8⁸을 함께 사용해요. 작성자는 최소 24GB 구성을 매우 느리다고 설명하고, 더 나은 생성 품질을 위해 80GB GPU를 권장해요. 아래 명령은 그 공식 저메모리 예제를 기준으로 해요.

저장소가 명시한 GPU 메모리 범위
설정	작성자 안내
단일 GPU, 704×1216	최소 24GB, 매우 느림
더 나은 생성 품질	80GB GPU 권장

산길 영상의 거친 화면과 선명한 화면이 모니터에서 좌우로 비교돼요. — 참조 장면의 구도를 지키며 생성된 영상의 각 프레임이 이어져요.

Linux에 CUDA 12.4와 Python 환경을 맞춰요

저장소는 수동 설치 기준으로 CUDA 12.4, Python 3.10, PyTorch⁹ 2.5.1을 안내해요. NVIDIA 드라이버와 CUDA 12.4 런타임¹⁰이 서로 호환되는 Linux 환경에서 아래 명령을 실행합니다. FlashAttention¹¹ 2는 저장소가 안내하는 추가 가속 패키지예요. 공식 설치 안내

저장소 루트에서 환경을 만들고 활성화한 뒤 PyTorch, 고정 의존성, FlashAttention을 설치해요. 다음 단계부터는 계속 Hunyuan-GameCraft-1.0 디렉터리에서 실행해요.

Linux 환경과 저장소 의존성 설치

git clone https://github.com/Tencent-Hunyuan/Hunyuan-GameCraft-1.0.git
cd Hunyuan-GameCraft-1.0
conda create -n HYGameCraft python==3.10 -y
conda activate HYGameCraft
conda install pytorch==2.5.1 torchvision==0.20.0 torchaudio==2.5.1 pytorch-cuda=12.4 -c pytorch -c nvidia -y
python -m pip install -r requirements.txt
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

모델 파일과 마을 입력 이미지를 준비해요

가중치 내려받기 전에 저장 공간을 확인해요. 공개 다운로드는 Hugging Face 저장소의 모델 파일과 표준 모델 구성요소를 weights/에 가져옵니다. 저장소가 요구한 체크포인트 경로가 만들어졌는지 확인한 뒤, 입력은 별도 파일을 만들지 않고 예제 asset/village.png를 사용합니다. 가중치 파일 구조와 다운로드 안내

명령은 저장소의 weights로 이동해 전체 모델 저장소를 내려받고, 두 체크포인트가 생성됐는지 확인해요. 첫 실행에서 누락 파일 오류가 나면 파일 이름과 위치가 안내된 구조에 맞는지 점검해요.

GameCraft 가중치 다운로드와 경로 확인

python -m pip install 'huggingface_hub>=0.34,<1.0'
cd weights
hf download tencent/Hunyuan-GameCraft-1.0 --local-dir ./
cd ..
test -f weights/gamecraft_models/mp_rank_00_model_states.pt
test -f weights/stdmodels/vae_3d/hyvae/pytorch_model.pt
test -f asset/village.png

모니터에 해안 풍경을 좌우로 비교한 화면이 보이고, 옆에는 필름 릴과 연결되지 않은 외장 SSD가 놓여 있어요. — 한 번의 생성은 정지 이미지에서 움직이는 프레임 묶음으로 이어져요.

기본 50-step 체크포인트로 클립을 생성해요

아래 명령은 저장소 공식 단일 GPU 저메모리 경로에 맞춰요. 24GB 예제는 CPU 오프로딩을 켜고 FP8을 사용하며, 첫 이미지에서 시작해 w, a, d, s 동작을 순서대로 적용합니다. 각 동작 속도는 저장소 예제 값인 0.2이고, 이 기본 체크포인트는 50 inference¹² steps를 사용해요. 공식 저메모리 추론 예제

24GB GPU 공식 CPU 오프로딩 예제로 village.mp4 생성

export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
export MODEL_BASE=weights/stdmodels
export DISABLE_SP=1
export CPU_OFFLOAD=1
torchrun --nnodes=1 --nproc_per_node=1 --master_port 29605 hymm_sp/sample_batch.py \
  --image-path asset/village.png \
  --prompt "A charming medieval village with cobblestone streets, thatched-roof houses, and vibrant flower gardens under a bright blue sky." \
  --add-neg-prompt "overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion, blurring, text, subtitles, static, picture, black border." \
  --ckpt weights/gamecraft_models/mp_rank_00_model_states.pt \
  --video-size 704 1216 \
  --cfg-scale 2.0 \
  --image-start \
  --action-list w a d s \
  --action-speed-list 0.2 0.2 0.2 0.2 \
  --seed 250160 \
  --sample-n-frames 33 \
  --infer-steps 50 \
  --flow-shift-eval-video 5.0 \
  --cpu-offload \
  --use-fp8 \
  --save-path ./results_poor/

첫 GPU 작업에서 메모리 부족이 나면 results_poor/에 이미 파일이 있는지 확인한 뒤 프레임 설정을 줄여 다시 짧게 확인할 수 있어요. GPU 메모리 24GB에서 작성자가 안내한 설정은 매우 느리므로, 먼저 80GB 권장 조건에 가까운 장비인지와 CPU_OFFLOAD·--cpu-offload가 모두 켜졌는지 확인하세요. 이 모델은 프레임 영상을 오프라인으로 생성해요.

저장된 마을 영상의 스트림 정보 확인

ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,nb_frames,r_frame_rate -of default=noprint_wrappers=1 results_poor/village.mp4

8-step 증류 버전은 mp_rank_00_model_states_distill.pt, --infer-steps 8, --cfg-scale 1.0, --use-fp8를 조합해요. 아래 명령은 기본 체크포인트와 50-step 설정을 사용합니다. 저장소의 증류 예제

종이배가 시냇가에 놓인 시작 장면과 다리 아래에 도착한 끝 장면이 필름 양쪽에 있어요. — 시작 이미지와 이동 동작이 장면을 어떤 방향으로 이어 갈지 함께 정해요.

용어 각주

CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다.
본문으로 돌아가기
GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.
본문으로 돌아가기
체크포인트 — 학습된 모델의 가중치 등을 저장한 파일입니다. 같은 모델 계열도 버전이나 용도에 따라 다른 체크포인트를 쓸 수 있습니다.
본문으로 돌아가기
프롬프트 — 모델에 보내는 입력문입니다. 생성 모델에서는 만들 결과를 설명하는 문장이 되어 출력의 구성과 내용을 크게 좌우합니다.
본문으로 돌아가기
프레임 — 영상의 한 장면을 이루는 단일 이미지입니다.
본문으로 돌아가기
CPU — 운영체제와 일반 프로그램 명령을 실행하고, AI에서는 전처리·데이터 이동 등 범용 연산을 맡는 중앙 처리 장치입니다.
본문으로 돌아가기
오프로딩 — 메모리가 부족할 때 모델 데이터 일부를 GPU 메모리에서 시스템 RAM이나 저장장치로 옮겨 처리하는 방식입니다. 데이터 이동이 추가됩니다.
본문으로 돌아가기
FP8 — 값 하나를 8비트로 표현하는 부동소수점 수치 형식입니다.
본문으로 돌아가기
PyTorch — AI 모델을 만들고 실행하는 소프트웨어 프레임워크입니다. 모델과 함께 호환되는 PyTorch 버전 및 하드웨어 지원도 확인해야 합니다.
본문으로 돌아가기
런타임 — 프로그램이 실행될 때 필요한 기능을 제공하는 소프트웨어 환경입니다. 로컬 AI에서는 모델을 실행하는 엔진을 가리키기도 합니다.
본문으로 돌아가기
FlashAttention — 어텐션 계산을 작은 타일로 나눠 중간 결과를 빠른 온칩 메모리에 유지하고, GPU 메모리 왕복과 전체 어텐션 행렬 저장을 줄이는 알고리즘입니다.
본문으로 돌아가기
모델 추론 — 학습된 모델을 사용해 입력에 대한 출력을 계산하는 과정입니다. 이 사이트에서 로컬 추론은 사용자의 기기에서 모델을 실행하는 경우를 뜻합니다.
본문으로 돌아가기

자주 묻는 질문

이 글에서 가장 먼저 확인할 것은 무엇인가요?: Hunyuan-GameCraft는 참조 이미지·텍스트 설명·순서가 있는 이동 입력을 받아 게임 카메라가 움직이는 영상을 만들어요. 공식 Linux CUDA 예제는 704×1216 설정에서 최소 GPU 메모리를 24GB로 안내하지만 매우 느리고, 80GB GPU를 권장해요. 기본 50-step 체크포인트로 예제 마을 이미지를 MP4로 만드는 순서를 따라가요.
필요한 메모리는 어느 정도인가요?: 작성자가 공개한 단일 GPU 경로는 Linux, NVIDIA CUDA, GPU 메모리 24GB 이상을 대상으로 해요. 해상도는 704×1216이며 CPU 오프로딩과 FP8을 함께 사용해요. 작성자는 최소 24GB 구성을 매우 느리다고 설명하고, 더 나은 생성 품질을 위해 80GB GPU를 권장해요. 아래 명령은 그 공식 저메모리 예제를 기준으로 해요.