Matrix-Game 2.0: будущее геймдева на Python? Пошаговый запуск

Привет! Сегодня у нас на столе нечто особенное. Забудьте про очередные нейронки, которые по текстовому промпту рисуют котиков или пишут за вас код-лапшу.

Проект Matrix-Game 2.0 — это интерактивная "модель мира". Говоря по-человечески, это нейросеть, которая не просто генерирует видео, а строит виртуальный мир и позволяет с ним взаимодействовать в реальном времени. Вы жмете на клавиатуру, двигаете мышью — и мир откликается, дорисовывая себя на лету со скоростью 25 FPS. Исходный код лежит на GitHub, так что мы можем не только посмотреть, но и потрогать.

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

Что это такое и почему это не просто очередная "нейронка для видео"?

Ключевое отличие Matrix-Game 2.0 от моделей вроде Sora или Pika — интерактивность и работа в реальном времени. Стандартные модели генерации видео работают по принципу "промпт -> долгое ожидание -> готовый ролик". Это односторонний процесс.

Matrix-Game же использует авторегрессионную диффузию. Это значит, что модель предсказывает следующий кадр, основываясь на предыдущих кадрах и текущих действиях пользователя (нажатиях клавиш, движениях мыши). Это фундаментальный сдвиг парадигмы: от генератора контента к симулятору мира.

Вот основные компоненты, которые делают это возможным:

• Массивный датасет: Разработчики собрали ~1200 часов интерактивных видео из Unreal Engine и GTA V. Модели есть на чем учиться физике и поведению.
• Модуль внедрения действий (Action Injection): Специальный компонент, который позволяет модели "понимать" ввод с клавиатуры и мыши на уровне каждого кадра.
• Быстрая генерация: Благодаря дистилляции модели и каузальной архитектуре (предсказание будущего на основе прошлого), удалось добиться генерации в реальном времени (25 FPS), что критически важно для игр.

Проще говоря, это шаг к созданию полноценных симуляций, где ИИ не просто следует скриптам, а динамически моделирует окружение.

Железо и подготовка

Сразу оговорюсь: запустить такое чудо на офисном ноутбуке не выйдет. Требования серьезные, но вполне ожидаемые для современных ML-задач.

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

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

conda create -n matrix-game-2.0 python=3.10 -y
conda activate matrix-game-2.0

Теперь можно переходить к установке.

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

Процесс довольно прямолинейный, если следовать инструкции.

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

Сначала клонируем репозиторий проекта и переходим в созданную папку.

git clone https://github.com/SkyworkAI/Matrix-Game.git
cd Matrix-Game-2

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

pip install -r requirements.txt

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

python setup.py develop

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

Шаг 2: Загрузка моделей

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

Затем выполните команду для скачивания моделей в папку Matrix-Game-2.0 внутри вашего проекта:

huggingface-cli download Skywork/Matrix-Game-2.0 --local-dir Matrix-Game-2.0

Эта команда загрузит все доступные веса: универсальные, для GTA и для TempleRun.

Шаг 3: Первый запуск (на автопилоте)

Для начала давайте запустим генерацию с предопределенными случайными действиями, чтобы убедиться, что все работает. Для этого используется скрипт inference.py.

Команда выглядит так:

python inference.py \
    --config_path configs/inference_yaml/inference_universal.yaml \
    --checkpoint_path Matrix-Game-2.0/universal/model.safetensors \
    --img_path demo_images/universal/0000.png \
    --output_folder outputs \
    --num_output_frames 150 \
    --seed 42 \
    --pretrained_model_path Matrix-Game-2.0

Давайте разберем аргументы:

• --config_path: Путь к конфигу. Для начала используем универсальный (inference_universal.yaml). Есть также для GTA (inference_gta_drive.yaml) и TempleRun.
• --checkpoint_path: Путь к весам модели, которые мы скачали на предыдущем шаге.
• --img_path: Стартовое изображение, с которого начнется генерация.
• --output_folder: Папка, куда сохранятся итоговые видео.
• --num_output_frames: Количество генерируемых латентных кадров.
• --pretrained_model_path: Путь к папке с дополнительными компонентами, в частности VAE (Wan2.1_VAE.pth).

После выполнения этой команды в папке outputs должны появиться два видеофайла: demo.mp4 и demo_icon.mp4 (с наложенным интерфейсом).

Шаг 4: Интерактивный режим (стриминг)

Самое интересное — это интерактивный режим. Для него используется скрипт inference_streaming.py. Он не принимает заранее заданных действий, а будет запрашивать их у вас в консоли в реальном времени.

python inference_streaming.py \
    --config_path configs/inference_yaml/inference_universal.yaml \
    --checkpoint_path Matrix-Game-2.0/universal/model.safetensors \
    --output_folder outputs \
    --seed 42 \
    --pretrained_model_path Matrix-Game-2.0

Скрипт сначала попросит указать путь к стартовому изображению, а затем будет в цикле запрашивать действия с клавиатуры и генерировать следующие фрагменты видео, пока вы его не остановите.

[!TIP] В репозитории есть небольшая проблема с рендерингом при движении камеры вверх (могут появляться черные экраны). Разработчики обещают исправить. Если столкнулись с этим, просто измените направление движения.

Под капотом: Краткий анализ кода inference.py

Чтобы понять, как это работает, давайте заглянем в inference.py. Я не буду разбирать каждую строчку, но выделю ключевые моменты.

Инициализация (__init__)

Класс InteractiveGameInference инициализирует все необходимое:

1. Конфигурация: OmegaConf.load(self.args.config_path) загружает YAML-конфиг, который определяет параметры пайплайна (шаги шумоподавления, режим и т.д.).
2. Основная модель (generator): Создается WanDiffusionWrapper — это обертка над CausalWanModel, главной диффузионной моделью.
3. VAE (Variational Autoencoder): Загружается VAE (VAEDecoderWrapper и get_wanx_vae_wrapper). Его задача — переводить изображения из пиксельного пространства в латентное (скрытое) и обратно. Диффузионная модель работает именно с латентами, потому что это гораздо эффективнее, чем с полноразмерными изображениями.
4. Пайплайн (pipeline): CausalInferencePipeline объединяет generator и vae_decoder в единый механизм для генерации.
5. Загрузка весов: load_file(self.args.checkpoint_path) загружает скачанные веса модели.

Генерация видео (generate_videos)

Этот метод — сердце процесса. Вот что происходит по шагам:

1. Подготовка первого кадра:

   • load_image(self.args.img_path): Загружается стартовое изображение.
   • Оно обрабатывается (изменение размера, нормализация) и кодируется в латентное представление с помощью VAE: self.vae.encode(...). Это будет наш первый латентный кадр, от которого "оттолкнется" генерация.

2. Создание "холста" для будущих латентов:

   • Создается тензор cond_concat, который содержит первый закодированный кадр и маску, указывающую модели, что только этот кадр является известным, а все остальные нужно сгенерировать.

3. Подготовка условий (actions):

   • В зависимости от режима (universal, gta_drive и т.д.) из utils.conditions загружается последовательность случайных действий: Bench_actions_universal(num_frames).
   • Эти действия (координаты мыши и состояние клавиш) формируют conditional_dict — словарь с условиями для генерации.

4. Запуск пайплайна:

   • Вызывается self.pipeline.inference(...). Внутри этой функции происходит магия:
     • Цикл шумоподавления (denoising loop): Модель итеративно "очищает" случайный шум, приближая его к осмысленному видео, основываясь на предыдущих кадрах (контексте) и действиях пользователя (conditional_dict).
     • Каузальность и KV-кэш: Ключевая особенность — использование KV-кэша. После генерации каждого блока кадров, модель не вычисляет заново всю историю, а переиспользует уже вычисленные состояния (ключи и значения в механизме внимания), что кардинально ускоряет процесс.

5. Декодирование и сохранение:

   • Полученные латенты декодируются обратно в пиксели с помощью vae_decoder.
   • process_video(...) сохраняет итоговые кадры в видеофайл, опционально накладывая на него иконку мыши и нажатые клавиши для наглядности.

Почему это важно?

Matrix-Game 2.0 — это больше, чем просто крутая технодемка. Это демонстрация жизнеспособности концепции "моделей мира" (World Models). Идея в том, что для создания по-настоящему интеллектуальных агентов (например, для беспилотных автомобилей или роботов) им нужна внутренняя модель того, как устроен мир и как он реагирует на действия.

Эта технология открывает двери для:

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

Конечно, технология еще сырая. Генерация не всегда стабильна, есть артефакты, а требования к железу высоки. Но это — реальный, работающий прототип. И тот факт, что он написан на Python и доступен в open-source, позволяет любому энтузиасту прикоснуться к таким технологиям.

Так что, если у вас есть подходящее железо, не поленитесь — соберите и запустите.