Tencent HunyuanWorld-Voyager: создаем 3D-миры из одного фото. Разбор технологии и гайд по запуску

Tencent выкатил не просто очередную «нейронку для видео». HunyuanWorld-Voyager — это полноценный фреймворк, который по одной картинке строит целый 3D-мир, готовый для «прогулок», и делает это на удивление умнее и качественнее конкурентов. Модель не просто генерирует ролик с движущейся камерой, она одновременно создает и RGB-видео, и точную карту глубины. Это, по сути, готовый набор данных для создания полноценных 3D-сцен без необходимости в сложном пост-процессинге.

В этой статье мы разберем, как это всё работает под капотом, посмотрим на результаты тестов в сравнении с другими моделями и, самое главное, пройдем по шагам процесс установки и запуска этого монстра на собственном железе.

Что такое HunyuanWorld-Voyager?

Если коротко, HunyuanWorld-Voyager — это диффузионная модель, которая решает задачу генерации консистентного (целостного) 3D-пространства на основе одного-единственного изображения. Вы даете ей на вход фотографию, задаете траекторию движения камеры, и на выходе получаете не просто видео «полета», а целый мир, который можно исследовать.

Ключевая фишка — одновременная генерация видео и карты глубины (RGB-D). Большинство аналогичных решений генерируют только RGB-видео, и для получения 3D-сцены вам приходится применять отдельные алгоритмы. Voyager же выдает идеально синхронизированные данные, которые можно напрямую «скармливать» технологиям вроде 3D Gaussian Splatting для получения детализированных трехмерных моделей.

Основные возможности:

• Генерация видео с управляемой камерой: Вы можете задать путь, по которому камера будет двигаться в сгенерированном мире.
• Реконструкция видео в 3D: Благодаря наличию карты глубины, созданные ролики легко превращаются в облака точек или 3D-меши.
• Генерация 3D из изображения (Image-to-3D): Конечная цель — получение исследуемой 3D-сцены из статичной картинки.

Основные возможности:

• Генерация видео с управляемой камерой: Вы можете задать путь, по которому камера будет двигаться в сгенерированном мире.
• Реконструкция видео в 3D: Благодаря наличию карты глубины, созданные ролики легко превращаются в облака точек или 3D-меши.
• Генерация 3D из изображения (Image-to-3D): Конечная цель — получение исследуемой 3D-сцены из статичной картинки.

Как это работает? Архитектура под капотом

В основе Voyager лежат два ключевых компонента, которые и отличают его от конкурентов.

Два кита Voyager: Диффузия и Исследование

1. World-Consistent Video Diffusion (Миро-консистентная видеодиффузия): Это ядро модели. Оно представляет собой единую архитектуру, которая учится генерировать сразу два потока данных — цветное видео (RGB) и видео с картой глубины (Depth). Важно, что модель при генерации нового кадра учитывает уже существующие данные о мире, чтобы сохранить целостность сцены. Например, если на первом кадре была ваза, то при облете камеры она останется на том же месте и сохранит свою форму.

2. Long-Range World Exploration (Исследование мира): Чтобы создавать длинные видео «прогулок» по сцене, нужна эффективная память. Для этого разработчики внедрили механизм «мирового кэша» (World Cache). Он работает на основе облака точек, отсекая ненужные детали (point culling) и используя авторегрессионный подход для постепенного расширения сцены. Проще говоря, модель достраивает мир по мере движения камеры, постоянно сверяясь с тем, что уже было создано, чтобы избежать артефактов и разрывов.

Данные решают все: свой движок для обучения

Создать огромный датасет для обучения такой модели — задача нетривиальная. Нужны миллионы видео с точными данными о движении камеры и глубине каждого кадра. Размечать такое вручную — безумие.

Команда Tencent пошла другим путем: они создали масштабируемый движок для построения данных. Это автоматизированный пайплайн, который берет на вход любое видео и самостоятельно:

• Оценивает позы камеры для каждого кадра.
• Рассчитывает метрическую глубину.

Это позволило им без ручной работы собрать гигантский датасет из более чем 100 000 видеофрагментов, смешав реальные съемки и рендеры из Unreal Engine. Такой подход дает огромное преимущество в качестве и разнообразии обучающих данных.

Сравнение с конкурентами: цифры и факты

На бумаге все выглядит красиво, но как Voyager показывает себя в деле? Разработчики сравнили его с несколькими актуальными open-source моделями.

Качество генерации видео

Для оценки качества видео использовался датасет RealEstate10K. Сравнивались четыре модели: SEVA, ViewCrafter, See3D и FlexWorld. Метрики стандартные для оценки изображений: PSNR, SSIM (структурное сходство) и LPIPS (перцептивное сходство, т.е. насколько результат похож на оригинал для человеческого глаза).

[!INFO] Что означают эти цифры?

• PSNR (Peak Signal-to-Noise Ratio): Чем выше, тем меньше попиксельных искажений.
• SSIM (Structural Similarity Index): Чем выше (ближе к 1), тем лучше сохранена структура изображения.
• LPIPS (Learned Perceptual Image Patch Similarity): Чем ниже, тем более реалистичным изображение кажется человеку.

Как видим, Voyager лидирует по всем трем метрикам, что говорит о более высоком качестве и реализме генерируемых видео. Особенно заметно преимущество при больших движениях камеры, где другие модели часто «плывут» и создают артефакты.

Качество 3D-реконструкции

Здесь сравнивалось качество 3D-сцен, восстановленных с помощью 3D Gaussian Splatting (3DGS) из сгенерированных видео. Поскольку конкуренты не создают карту глубины, для них ее приходилось восстанавливать с помощью отдельного инструмента (VGGT).

Результаты говорят сами за себя. Даже когда Voyager использует тот же сторонний инструмент для реконструкции (VGGT), он обходит конкурентов за счет более геометрически корректного видео. А когда используется его собственная, нативно сгенерированная карта глубины (строка "Voyager -"), качество реконструкции становится еще выше.

Комплексная оценка на WorldScore Benchmark

WorldScore — это бенчмарк для оценки моделей, генерирующих целые "миры". Он оценивает все: от контроля камеры до фотореалистичности и 3D-консистентности.

Здесь Voyager получает наивысший средний балл (WorldScore Average) и высший балл за субъективное качество (Subjective Quality). Это подтверждает, что сгенерированные миры не только технически корректны, но и выглядят наиболее убедительно для зрителя.

Запускаем HunyuanWorld-Voyager у себя

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

Шаг 0: Требования к железу — это серьезно

[!WARNING] Вам понадобится настоящий монстр, а не игровая видеокарта.

• Минимальные требования: GPU с 60 ГБ видеопамяти для генерации видео в разрешении 540p.
• Рекомендованные требования: GPU с 80 ГБ видеопамяти для лучшего качества.

Модель тестировалась на NVIDIA A100/H100 (80GB). Если у вас нет доступа к такому оборудованию, запустить модель локально, скорее всего, не получится.

Протестированная ОС — Linux.

Шаг 1: Подготовка окружения

Сначала клонируем репозиторий проекта.

git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-Voyager
cd HunyuanWorld-Voyager

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

# 1. Создаем новое conda-окружение с Python 3.11.9
conda create -n voyager python==3.11.9

# 2. Активируем его
conda activate voyager

# 3. Устанавливаем PyTorch нужной версии с поддержкой CUDA 12.4
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

# 4. Устанавливаем остальные зависимости из файла
python -m pip install -r requirements.txt
python -m pip install transformers==4.39.3

# 5. Устанавливаем flash-attention v2 для ускорения (требует CUDA >= 11.8)
python -m pip install flash-attn

# 6. Устанавливаем xDiT для параллельного запуска на нескольких GPU
python -m pip install xfuser==0.4.2

[!TIP] Решаем проблему с 'core dump' На некоторых конфигурациях GPU может возникать ошибка float point exception (core dump). Разработчики предлагают решение: убедитесь, что у вас установлены CUDA 12.4, CUBLAS >= 12.4.5.8 и CUDNN >= 9.0.0, а затем выполните:

pip install nvidia-cublas-cu12==12.4.5.8
export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/

Это может спасти вам несколько часов отладки.

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

Для скачивания весов модели используется huggingface-cli. Если у вас его нет, установите: python -m pip install "huggingface_hub[cli]"

Теперь, находясь в корневой папке проекта HunyuanWorld-Voyager, выполняем команду:

huggingface-cli download tencent/HunyuanWorld-Voyager --local-dir ./ckpts

Веса модели будут загружены в папку ckpts. Будьте готовы, что это займет приличное время — модели весят десятки гигабайт.

Шаг 3: Генерация видео (Inference)

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

Вариант А: Запуск на одном GPU

Это базовый сценарий. Команда для запуска генерации выглядит так:

python3 sample_image2video.py \
    --model HYVideo-T/2 \
    --input-path "examples/case1" \
    --prompt "An old-fashioned European village with thatched roofs on the houses." \
    --i2v-stability \
    --infer-steps 50 \
    --flow-reverse \
    --flow-shift 7.0 \
    --seed 0 \
    --embedded-cfg-scale 6.0 \
    --use-cpu-offload \
    --save-path ./results

Давайте разберем ключевые параметры:

• --input-path: Путь к папке с "условием" — исходным изображением и картой глубины. В репозитории уже есть готовые примеры (examples/case1, examples/case2 и т.д.).
• --prompt: Текстовое описание того, что должно происходить или что изображено.
• --infer-steps: Количество шагов диффузии. 50 — хороший компромисс между скоростью и качеством.
• --i2v-stability: Флаг для включения режима повышенной стабильности генерации.
• --use-cpu-offload: Позволяет переносить часть моделей (например, VAE и текстовый энкодер) в оперативную память, экономя VRAM.

Результат будет сохранен в папке ./results.

Вариант Б: Параллельный запуск на нескольких GPU (xDiT)

Если у вас есть ферма из нескольких GPU, можно значительно ускорить процесс. Для этого используется torchrun и библиотека xDiT. Например, для запуска на 8 GPU:

ALLOW_RESIZE_FOR_SP=1 torchrun --nproc_per_node=8 \
    sample_image2video.py \
    --model HYVideo-T/2 \
    --input-path "examples/case1" \
    --prompt "An old-fashioned European village with thatched roofs on the houses." \
    --i2v-stability \
    --infer-steps 50 \
    --flow-reverse \
    --flow-shift 7.0 \
    --seed 0 \
    --embedded-cfg-scale 6.0 \
    --save-path ./results \
    --ulysses-degree 8 \
    --ring-degree 1

Общее количество используемых GPU равно произведению --ulysses-degree и --ring-degree. Разработчики приводят таблицу прироста производительности на 8x H20 GPU:

Ускорение почти в 7 раз — впечатляет.

Шаг 4: Пробуем Gradio Demo — самый простой путь

Для тех, кто не хочет возиться с командной строкой, есть удобный веб-интерфейс на Gradio.

Запускается он одной командой:

python3 app.py

После запуска в консоли появится ссылка, которую можно открыть в браузере. Интерфейс интуитивно понятен:

1. Загружаете свое изображение.
2. Выбираете направление движения камеры (forward, backward, left, right).
3. Нажимаете "Generate Condition" — модель создаст и покажет вам видео с траекторией камеры.
4. Пишете текстовый промпт.
5. Нажимаете "Generate Video" и ждете результат.

Шаг 5 (Для продвинутых): Создание собственных "условий" для генерации

Просто запускать готовые примеры скучно. Чтобы использовать свои изображения, нужно сначала создать для них "условие" — то самое видео с траекторией и картой глубины. Для этого используется скрипт create_input.py из папки data_engine.

Сначала установим дополнительные зависимости:

pip install --no-deps git+https://github.com/microsoft/MoGe.git
pip install scipy==1.11.4
pip install git+https://github.com/EasternJournalist/utils3d.git@c5daf6f6c244d251f252102d09e9b7bcef791a38

Теперь можно запустить скрипт:

cd data_engine

python3 create_input.py \
    --image_path "путь/к/вашему/изображению.png" \
    --render_output_dir "путь/куда/сохранить/результат" \
    --type "forward"

Параметр --type определяет траекторию движения камеры. Доступные варианты:

• forward (вперед)
• backward (назад)
• left (влево)
• right (вправо)
• turn_left (поворот налево)
• turn_right (поворот направо)

После выполнения скрипта в папке --render_output_dir будет создана подпапка condition со всем необходимым для запуска основной модели. Дальше вы просто указываете путь к этой папке в параметре --input-path в sample_image2video.py.

Заключение

HunyuanWorld-Voyager — это серьезный шаг вперед в области генерации 3D-сцен из изображений. Он не просто создает красивые видео, а предоставляет готовый инструмент для 3D-реконструкции, обходя конкурентов по качеству и целостности генерируемого мира. Да, требования к железу делают его недоступным для большинства энтузиастов, но это яркая демонстрация того, куда движутся технологии генеративного ИИ. Это уже не игрушки для создания смешных роликов, а мощные фреймворки для создания целых виртуальных миров.