# Hunyuan World 2.0（3D 世界模型）

{% hint style="info" %}
**发布于 2026 年 4 月 15 日** — 腾讯混元发布了 **HY-World 2.0**，首个完全开源的 SOTA 3D 世界模型。本指南涵盖 **WorldMirror 2.0** （已发布的约 12 亿参数重建组件）。姊妹模型 **HY-Pano 2.0** 和 **WorldStereo 2.0** 在官方仓库中被标记为“即将推出”——见下方 [路线图](#roadmap) 。
{% endhint %}

HY-World 2.0 是腾讯的多模态世界模型框架，用于 **重建、生成并模拟完整的 3D 场景**。不同于单物体网格生成器，HY-World 可接收文本、单视图或多视图图像，或视频，并输出可编辑的世界表示——网格、3D 高斯溅射、点云、深度图、表面法线以及恢复出的相机参数——可直接导入 Unity、Unreal 或 Blender。

首批公开权重覆盖 **WorldMirror 2.0** （约 12 亿参数，BF16）——整个栈的重建部分。它可在单张 GPU 上以约 12–24 GB 显存运行，并支持 5 万到 50 万像素的灵活分辨率，还支持 FSDP 多 GPU 分片以处理更大工作负载。开箱即用提供 Python API（`diffusers`风格）、通过 `torchrun`的 CLI，以及 Gradio 演示。ComfyUI 节点 **尚未** 官方提供——目前只有社区移植版。

{% hint style="success" %}
本指南中的所有示例都运行在通过 [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

### 租用的 GPU 服务器上

| 属性    | 值                                                       |
| ----- | ------------------------------------------------------- |
| 组件    | WorldMirror 2.0（已发布）；HY-Pano 2.0 + WorldStereo 2.0 即将推出 |
| 参数量   | 约 12 亿（BF16）                                            |
| 输入模态  | 文本 · 单视图图像 · 多视图图像 · 视频                                 |
| 输出    | 网格 · 3D 高斯溅射 · 点云 · 深度 · 法线 · 相机参数                      |
| VRAM  | 单卡约 12–24 GB；多卡使用 FSDP                                  |
| 分辨率范围 | 5 万 – 50 万像素（灵活分辨率）                                     |
| 许可证   | `tencent-hy-world-2.0-community` （自定义——见下文）             |
| 发布    | 2026-04-15                                              |

{% hint style="warning" %}
**许可证说明：** HY-World 2.0 采用自定义社区许可证发布（`License.txt` 位于仓库根目录）， **尚未** Apache 2.0 或 MIT。商业使用条款与腾讯的 Hunyuan3D 2.1 不同。在基于它构建并发布任何内容之前，请先阅读完整许可证。
{% endhint %}

### 为什么选择 HY-World 2.0？

* **首个开源 SOTA 世界模型** —— 该类别中没有闭源竞争对手
* **输出完整场景，而不只是网格** —— 一次推理同时输出高斯溅射 + 几何 + 相机
* **多模态输入** —— 同一管线可处理文本、图像和视频
* **支持 FSDP** —— 可扩展到 2–8 张 GPU，用于高分辨率或批量推理
* **适配游戏引擎** —— 输出可直接导入 Unity、Unreal 和 Blender

***

## 需求

| 组件      | 最低                     | 推荐                               |
| ------- | ---------------------- | -------------------------------- |
| GPU 显存  | 16 GB（RTX 4080 / 3090） | 24–80 GB（RTX 4090 / A100 / H100） |
| 系统内存    | 32 GB                  | 64–128 GB                        |
| 磁盘      | 80 GB                  | 200 GB                           |
| CUDA    | 12.1                   | 12.4+                            |
| Python  | 3.10                   | 3.10                             |
| PyTorch | 2.4.0                  | 2.4.0+                           |

{% hint style="info" %}
多 GPU 模式需要 **每张 GPU ≥ 1 张输入图像**。如果只有一张参考图像，请使用单卡，并仅在批量或高分辨率任务时让 FSDP 接管。
{% endhint %}

***

## 选项 A——使用 Docker + torchrun 快速开始

一个最小化的 `docker-compose.yml` ，适用于 Clore.ai 容器（腾讯官方镜像尚未发布——此处使用 PyTorch 基础镜像并在容器内安装仓库）：

```yaml
version: "3.8"
services:
  hyworld2:
    image: pytorch/pytorch:2.4.0-cuda12.4-cudnn9-devel
    ports:
      - "7860:7860"
    volumes:
      - ./workspace:/workspace
      - hf_cache:/root/.cache/huggingface
    working_dir: /workspace
    command: >
      bash -c "
        git clone https://github.com/Tencent-Hunyuan/HY-World-2.0 &&
        cd HY-World-2.0 &&
        pip install -r requirements.txt &&
        pip install flash-attn --no-build-isolation &&
        python -m hyworld2.worldrecon.gradio_app
      "
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    shm_size: "16gb"

volumes:
  hf_cache:
```

使用 FSDP 和 BF16 运行多 GPU 重建任务：

```bash
torchrun --nproc_per_node=2 -m hyworld2.worldrecon.pipeline \\
    --input_path /workspace/input_images \\
    --use_fsdp --enable_bf16
```

***

## 选项 B——手动 Python API

```bash
# 克隆并安装
git clone https://github.com/Tencent-Hunyuan/HY-World-2.0
cd HY-World-2.0
conda create -n hyworld2 python=3.10 -y
conda activate hyworld2
pip install torch==2.4.0 torchvision==0.19.0 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
pip install flash-attn --no-build-isolation
```

```python
from hyworld2.worldrecon.pipeline import WorldMirrorPipeline

# 从 HF（tencent/HY-World-2.0）加载约 12 亿 BF16 权重
pipeline = WorldMirrorPipeline.from_pretrained('tencent/HY-World-2.0')

# 从多视图图像文件夹重建 3D 场景
result = pipeline('path/to/images')

# 可选：注入先验相机和深度，以获得更精细的重建
result = pipeline(
    'path/to/images',
    prior_cam_path='path/to/prior_camera.json',
    prior_depth_path='path/to/prior_depth/',
)
```

在 7860 端口启动 Gradio 演示：

```bash
python -m hyworld2.worldrecon.gradio_app
```

对于使用 FSDP 的多 GPU Gradio：

```bash
torchrun --nproc_per_node=2 -m hyworld2.worldrecon.gradio_app \\
    --use_fsdp --enable_bf16
```

***

## Clore.ai GPU 推荐

| 工作负载            | GPU        | VRAM       | 原因                   | Clore.ai 费用  |
| --------------- | ---------- | ---------- | -------------------- | ------------ |
| 单张图像 → 场景，开发/预览 | RTX 4090   | 24 GB      | BF16 能轻松容纳，迭代速度快     | 约 0.5–2 美元/天 |
| 多视图视频重建         | A100 40 GB | 40 GB      | 可处理 20 万+ 像素帧而不会 OOM | 约 3–5 美元/天   |
| 高分辨率批处理（生产）     | A100 80 GB | 80 GB      | 完整 50 万像素灵活分辨率，大批量   | 约 5–8 美元/天   |
| FSDP 多 GPU / 研究 | 2–4× H100  | 160–320 GB | 分片训练级工作负载            | 约 15–40 美元/天 |

{% hint style="success" %}
**在 Clore.ai 上的最佳选择：** 一张 **RTX 4090，约 0.5–2 美元/天** 即可处理日常的 WorldMirror 推理。只有在需要超过 20 万像素重建或长视频输入时，才升级到 A100。
{% endhint %}

***

## 使用场景

* **游戏开发** —— 将概念美术转为粗略的 3D 环境，用于 blockout 和 greybox
* **AR/VR 内容** —— 生成可在 Unity/Unreal 中运行、接近照片级保真的高斯溅射场景
* **影视和动画预演** —— 从实拍照片重建场景，用于虚拟摄影
* **建筑可视化** —— 将参考照片或文本简介转为可编辑的 3D 漫游
* **机器人与仿真** —— 从稀疏的真实世界影像合成 3D 训练环境

***

## 路线图

腾讯在官方仓库中将以下内容列为“即将推出”：

* **HY-Pano 2.0** —— 360° 全景生成（临时方案：HunyuanWorld 1.0）
* **WorldStereo 2.0** —— 世界扩展 / 新视角合成（临时方案：原始 WorldStereo）
* **WorldNav** —— 场景穿越的轨迹规划
* **完整世界生成管线代码** —— 文本/图像 → 完整世界的入口

目前只有 WorldMirror 2.0（重建）组件公开了权重。请关注 [HF 模型页面](https://huggingface.co/tencent/HY-World-2.0) 的更新。

***

## 故障排除

| 问题                        | 解决方案                                                                                                 |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `CUDA 显存不足` 在 16 GB GPU 上 | 将输入分辨率降低到 5 万像素左右，或切换到 RTX 4090（24 GB）。启用 `--enable_bf16`                                            |
| FSDP 启动时卡住                | 确保输入图像数量 **≥** `--nproc_per_node`。FSDP 还需要各 GPU 间的 NCCL + 匹配的 CUDA                                   |
| `flash-attn` 安装失败         | 尝试预编译 wheel `pip install flash-attn --no-build-isolation` 在 CUDA 12.4 上；如果仍然失败，管线也可以在没有它的情况下运行（但会更慢） |
| Clore.ai 上无法访问 Gradio 界面  | 在 Clore 容器配置中转发 7860 端口，或使用 `--share`                                                                |
| 商业用途的许可证问题                | 阅读 `License.txt` 仓库中的 `tencent-hy-world-2.0-community`，它不是标准开源软件                                     |

***

## 下一步

* [Hunyuan3D 2.1](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/hunyuan3d) —— 腾讯的单物体文本/图像转网格生成器（更小、Apache 风格管线、不同用途）
* [TRELLIS 3D](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/trellis-3d) —— 微软的结构化 3D 资产生成器
* [Gaussian Splatting](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/gaussian-splatting) —— 用于渲染 HY-World 生成的 3DGS 输出的管线
* [HuggingFace 模型](https://huggingface.co/tencent/HY-World-2.0)
* [GitHub 仓库](https://github.com/Tencent-Hunyuan/HY-World-2.0)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/hunyuan-world-2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.