Статьи

Hunyuan-GameCraft: запускаем процедурный игровой мир от Tencent. Пошаговый гайд

2025-08-15 19:03 Опенсорс ML / DL Разработка игр

Привет! Не так давно мы щупали Matrix-Game 2.0, интерактивную модель мира, которая на лету дорисовывала окружение по командам. И вот, на сцену выходит новый, куда более серьезный игрок — Hunyuan-GameCraft от гиганта Tencent.

Это фреймворк для генерации высокодинамичных, интерактивных игровых видео. Проще говоря, это следующий шаг к той самой "Матрице": вы жмете на клавиатуру, а ИИ в реальном времени строит для вас игровой мир. Проект опенсорсный, код написан на Python.

Давайте разберемся, как это работает, чем отличается от аналогов, и, самое главное, как развернуть этот генератор миров у себя на машине.

Что это и чем отличается от Matrix-Game?

Если Matrix-Game был скорее технодемкой, то Hunyuan-GameCraft — это уже продуманный фреймворк. Разработчики из Tencent (авторы PUBG Mobile, если что) подошли к вопросу основательно.

Вот ключевые отличия и фичи, которые делают этот проект особенным:

  1. Гибридное кэширование истории (Hybrid History Condition): Модель не просто смотрит на последний кадр, а эффективно сохраняет информацию о сцене. Это позволяет ей генерировать длинные, последовательные видео, где мир не "забывается" после резкого поворота камеры.
  2. Единое пространство управления: Ввод с клавиатуры (W, A, S, D) и мыши унифицирован в общее пространство представления камеры. Это позволяет модели плавно интерполировать движения, делая управление более естественным и предсказуемым.
  3. Дистилляция модели для эффективности: Кроме основной, "тяжелой" модели, разработчики подготовили и дистиллированную (ускоренную) версию. Она требует меньше шагов для генерации (8 вместо 50!), что делает ее пригодной для развертывания в реальном времени.
  4. Огромный игровой датасет: Модель обучали на миллионе записей геймплея из более чем 100 AAA-игр. Это обеспечивает невероятное разнообразие стилей и хорошую "насмотренность" в плане физики и динамики игровых миров.

This browser does not support the video element.

В сухом остатке: Hunyuan-GameCraft — это более основательная и потенциально более стабильная попытка создать интерактивный ИИ-мир, чем Matrix-Game.

Требования к железу и подготовка окружения

Как и всегда, запустить такое на слабом железе не получится. Требования серьезные:

  • GPU: NVIDIA с объемом памяти не менее 24 ГБ. В идеале — RTX 3090/4090 или что-то из линейки A100/H100.
  • ОС: Linux. На Windows запуск потребует дополнительных усилий, мы их рассматривать не будем.
  • RAM: Минимум 64 ГБ оперативной памяти.

[!INFO] В репозитории есть скрипты для запуска на одной GPU с выгрузкой части данных в CPU (CPU Offload), что делает проект доступным для владельцев "народных" 24 ГБ карт.

Перед началом создадим чистое conda окружение, чтобы не было конфликтов зависимостей. Рекомендуемая версия Python — 3.10.

conda create -n hy-gamecraft python=3.10 -y
conda activate hy-gamecraft

Теперь мы готовы к установке.

Пошаговый запуск: от git clone до интерактивной сессии

Процесс установки и запуска хорошо документирован, но давайте пройдемся по нему вместе, разбирая каждый шаг.

Шаг 1: Клонирование репозитория и установка зависимостей

Сначала клонируем официальный репозиторий проекта с GitHub.

git clone https://github.com/Tencent-Hunyuan/Hunyuan-GameCraft-1.0.git
cd Hunyuan-GameCraft-1.0

Теперь установим все Python-библиотеки из файла requirements.txt.

pip install -r requirements.txt

[!WARNING] Проект сильно зависит от flash-attention для ускорения. Убедитесь, что у вас установлен nvcc (CUDA Toolkit) и gcc, так как pip скорее всего будет компилировать пакет из исходников. Если возникнут ошибки — следуйте официальной инструкции по установке flash-attention.

После этого установим сам пакет hymm_sp в режиме разработки.

python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

Шаг 2: Загрузка весов модели

Все предобученные модели лежат на Hugging Face. Самый простой способ их скачать — через huggingface-cli. Если утилиты нет, установите ее: pip install "huggingface_hub[cli]".

Теперь выполним команду для скачивания всех необходимых весов. Они будут загружены в папку weights внутри проекта.

huggingface-cli download tencent/Hunyuan-GameCraft-1.0 --local-dir ./weights

Эта команда скачает всё, что нужно:

  • Основные веса модели mp_rank_00_model_states.pt.
  • Веса ускоренной (дистиллированной) модели mp_rank_00_model_states_distill.pt.
  • Необходимые компоненты, такие как VAE и текстовые энкодеры (CLIP и LLaVA).

После завершения загрузки у вас должна получиться вот такая структура папок:

Hunyuan-GameCraft-1.0/
└── weights/
    ├── gamecraft_models/
    │   ├── mp_rank_00_model_states.pt
    │   └── mp_rank_00_model_states_distill.pt
    └── stdmodels/
        ├── vae_3d/
        ├── llava-llama-3-8b-v1_1-transformers/
        └── openai_clip-vit-large-patch14/

Теперь все готово к первому запуску.

Шаг 3: Тестовый запуск на одной GPU (с CPU Offload)

Давайте сначала запустим генерацию на одной видеокарте с минимальными требованиями к VRAM (24 ГБ). Для этого будем использовать скрипт run_sample_batch_4090.sh.

Откройте файл scripts/run_sample_batch_4090.sh и убедитесь, что пути к моделям указаны верно. По умолчанию они должны быть правильными, если вы следовали шагу 2.

#!/bin/bash
JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=${JOBS_DIR}:$PYTHONPATH
export MODEL_BASE="/path/to/models" # <-- УКАЖИТЕ ПРАВИЛЬНЫЙ ПУТЬ!
checkpoint_path="/path/to/ckpts" # <-- И ЗДЕСЬ!

# ... остальной код

[!TIP] Важно! Переменная MODEL_BASE должна указывать на папку, где лежат stdmodels (т.е. .../Hunyuan-GameCraft-1.0/weights/stdmodels). А checkpoint_path — полный путь к файлу .../Hunyuan-GameCraft-1.0/weights/gamecraft_models/mp_rank_00_model_states.pt. Отредактируйте скрипт перед запуском!

После того как пути исправлены, запускаем скрипт:

bash scripts/run_sample_batch_4090.sh

Что здесь происходит?

  • export DISABLE_SP=1 и export CPU_OFFLOAD=1: Эти переменные отключают Sequence Parallelism (распараллеливание на несколько GPU) и включают выгрузку неиспользуемых частей модели из VRAM в оперативную память. Это замедляет генерацию, но позволяет запуститься на одной карте.
  • torchrun --nnodes=1 --nproc_per_node=1 ...: Запуск скрипта hymm_sp/sample_batch.py на одном GPU.
  • --image-path "asset/village.png": Стартовая картинка.
  • --prompt "...": Текстовое описание сцены.
  • --action-list w s d a: Список "нажатий клавиш", которые будут симулированы. Модель сгенерирует 4 сегмента видео, соответствующие движению вперед, назад, вправо и влево.
  • --action-speed-list 0.2 0.2 0.2 0.2: "Сила" или "скорость" каждого действия.
  • --cpu-offload и --use-fp8: Флаги, дополнительно снижающие потребление VRAM за счет выгрузки в RAM и использования 8-битной точности вычислений.

После успешного выполнения в папке results/ появится видеофайл village.mp4. Он будет состоять из исходного кадра и четырех сгенерированных фрагментов, склеенных вместе.

Шаг 4: Запуск на нескольких GPU (максимальная производительность)

Если у вас есть доступ к серверу с несколькими GPU (например, 8x A100), вы можете запустить генерацию в параллельном режиме. Для этого используется скрипт run_sample_batch_sp.sh.

Процесс аналогичен: проверьте и исправьте пути в скрипте, а затем запустите его.

bash scripts/run_sample_batch_sp.sh

Ключевое отличие в команде запуска: torchrun --nnodes=1 --nproc_per_node=8 .... Это говорит PyTorch задействовать 8 GPU на одной машине. В этом режиме CPU_OFFLOAD отключен, и генерация происходит значительно быстрее.

Шаг 5: Запуск ускоренной (дистиллированной) модели

Для сценариев, требующих максимальной скорости, можно использовать дистиллированную модель. Она генерирует видео всего за 8 шагов шумоподавления вместо 50. Качество может быть немного ниже, но скорость — в разы выше.

Для этого используется скрипт run_sample_batch_distill.sh. Не забудьте поправить пути к MODEL_BASE и checkpoint_path (теперь он должен указывать на ..._distill.pt).

bash scripts/run_sample_batch_distill.sh

Обратите внимание на ключевые изменения в параметрах:

  • --checkpoint_path: Указывает на файл mp_rank_00_model_states_distill.pt.
  • --cfg-scale 1.0: Сниженная сила влияния промпта, что типично для дистиллированных моделей.
  • --infer-steps 8: Всего 8 шагов генерации.

Под капотом: краткий анализ архитектуры

Давайте очень кратко, без погружения в математику, разберем, как устроена модель HYVideoDiffusionTransformer из файла hymm_sp/modules/models.py.

  1. Входные данные: Модель принимает на вход:

    • x: Зашумленные латенты видео (то, что нужно "очистить").
    • t: Текущий шаг времени в процессе шумоподавления.
    • text_states и text_states_2: Текстовые эмбеддинги от двух энкодеров (LLaVA-Llama и CLIP).
    • cam_latents: Эмбеддинги, описывающие движение камеры (полученные из action_id и action_speed).
    • freqs_cos, freqs_sin: Ротационные позиционные эмбеддинги (RoPE), которые помогают модели понимать положение "пикселей" в пространстве и времени.

  2. Эмбеддинги: Все входные данные (кроме латентов) преобразуются в единое векторное пространство с помощью специальных модулей: img_in (для изображений), txt_in (для текста), time_in (для времени), camera_net (для движений камеры).

  3. Двухпоточная архитектура (DoubleStreamBlock): Первые 19 слоев трансформера — двухпоточные. Это значит, что обработка визуальной информации (латентов изображений) и текстовой информации идет параллельно, в двух отдельных "потоках". Они обмениваются информацией друг с другом через механизм cross-attention. Это позволяет модели глубоко связать смысл текста с визуальным рядом.

  4. Однопоточная архитектура (SingleStreamBlock): После 19-го слоя визуальные и текстовые токены объединяются в одну последовательность и обрабатываются вместе в следующих 38 слоях. Это позволяет модели находить более сложные, мультимодальные зависимости.

  5. Модуляция (ModulateDiT): По всей сети разбросаны слои модуляции. Они "впрыскивают" информацию о времени (t) и текстовом контексте (text_states_2) прямо в слои трансформера, адаптируя их поведение на каждом шаге генерации. Это похоже на то, как работают AdaLN слои в Stable Diffusion 3.

  6. Финальный слой: В конце обработанные латенты проходят через FinalLayer, который преобразует их в формат, готовый для декодирования VAE обратно в пиксели.

[!INFO] Почему это важно? Такая гибридная архитектура (сначала два потока, потом один) — это тренд в современных мультимодальных моделях. Она позволяет эффективно обрабатывать разные типы данных, не теряя их специфики, а затем объединять их для создания целостного результата.

Заключение: Куда все это движется?

Hunyuan-GameCraft, как и Matrix-Game, — это не просто генераторы видео. Это первые шаги к созданию процедурных, интерактивных миров на лету. Технология все еще находится на ранней стадии, но уже сейчас она демонстрирует огромный потенциал для:

  • Игр нового поколения: Миры, которые не нарисованы заранее, а генерируются и изменяются в ответ на действия игрока.
  • Реалистичных симуляторов: Обучение автопилотов и роботов в динамически создаваемых, фотореалистичных средах.
  • Быстрого прототипирования в геймдеве: Возможность "наиграть" прототип уровня вместо долгой ручной сборки в редакторе.

Да, требования к железу пока заоблачные для массового пользователя, а в генерации встречаются артефакты. Но это лишь вопрос времени. Тот факт, что такие проекты появляются в опенсорсе, позволяет сообществу экспериментировать и ускорять прогресс. Если у вас есть подходящая видеокарта — обязательно попробуйте запустить.