この記事で最初に確認すべきことは何ですか？

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を推奨しています。以下は公式の低メモリ例に沿ったコマンドです。

画像・動画生成

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を指定しています。CUDA 12.4ランタイム¹⁰に対応するNVIDIAドライバーを備えた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へ移動してモデルリポジトリを取得し、2つの公開チェックポイントを確認します。初回実行でファイル不足エラーが出たら、ファイル名と保存場所が記載された構成に合っているか見直してください。

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が置かれています。 — 1回の生成で静止画から動くフレームの列へ広がります。

基本の50-stepチェックポイントで動画を生成します

このコマンドはリポジトリの単一GPU・低メモリ経路に沿っています。24GB例ではCPUオフロードとFP8を有効にし、参照画像からw、a、d、sを順に適用します。各操作の速度値はリポジトリ例と同じ0.2です。基本チェックポイントは50推論ステップで実行します。公式の低メモリ推論例

公式の24GB 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/に出力ファイルがあるか確認し、フレーム設定を短くして小さく再試行できます。作者は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モデルの実行ではモデル計算を担います。
本文に戻る
チェックポイント — 学習済みモデルの重みなどを保存したファイルです。同じモデル系列でも、版や用途によって異なるチェックポイントを使うことがあります。
本文に戻る
プロンプト — モデルに送る入力文です。生成モデルでは作りたい結果を説明する文になり、出力の構成や内容を大きく左右します。
本文に戻る
フレーム — 動画を構成する1枚の画像です。
本文に戻る
CPU — OSや一般的なプログラム命令を実行する中央処理装置です。AIでは前処理やデータ転送などの汎用処理も担います。
本文に戻る
オフロード — 容量が足りないとき、モデルデータの一部をGPUメモリからシステムRAMやストレージへ移して処理する方法です。データ転送が追加されます。
本文に戻る
FP8 — 一つの値を8ビットで表す浮動小数点形式です。
本文に戻る
PyTorch — AIモデルを作成・実行するソフトウェアフレームワークです。モデルと合わせて、対応するPyTorchの版やハードウェアも確認します。
本文に戻る
ランタイム — プログラムの実行時に必要な機能を提供するソフトウェア環境です。ローカルAIではモデル実行エンジンを指すこともあります。
本文に戻る
FlashAttention — Attentionを小さなタイルに分けて計算し、中間値を高速なオンチップメモリに保つことで、GPUメモリとの往復とAttention行列全体の保存を減らすアルゴリズムです。
本文に戻る

よくある質問

この記事で最初に確認すべきことは何ですか？: 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を推奨しています。以下は公式の低メモリ例に沿ったコマンドです。