Hunyuan3D-Omni

Hunyuan3D-Omni 是一个用于可控生成 3D 资产的统一框架，继承了 Hunyuan3D 2.1 的结构。与之不同的是，Hunyuan3D-Omni 构建了一个统一的控制编码器，以引入额外的控制信号，包括点云、体素、骨骼和边界框。

多模态条件控制

• 边界框控制：生成受 3D 边界框约束的 3D 模型。
• 姿态控制：创建具有特定骨骼姿态的 3D 人体模型。
• 点云控制：根据输入点云生成 3D 模型。
• 体素控制：从体素表示创建 3D 模型。

🎁 模型库

生成过程需要 10 GB 显存。

模型	描述	日期	大小	HuggingFace
Hunyuan3D-Omni	具有多模态控制的图像到形状模型	2025-09-25	3.3B	下载

安装

需求

我们使用 Python 3.10 测试我们的模型。

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

使用

推理

多模态推理

python3 inference.py --control_type <control_type> [--use_ema] [--flashvdm]

control_type 参数有四个可选值：

point：使用点云控制类型进行推理。
voxel：使用体素控制类型进行推理。
bbox：使用边界框控制类型进行推理。
pose：使用姿态控制类型进行推理。

--use_ema 标志启用指数移动平均（EMA）模型，以获得更稳定的推理结果。

--flashvdm 标志启用 FlashVDM 优化，以提高推理速度。

请根据您的需求选择合适的 control_type。例如，如果您想使用 point 控制类型，可以运行：

python3 inference.py --control_type point 
python3 inference.py --control_type point --use_ema
python3 inference.py --control_type point --flashvdm

致谢

我们感谢以下项目的贡献者：TripoSG、CLAY、Trellis、DINOv2、Stable Diffusion、FLUX、diffusers、HuggingFace、CraftsMan3D、Michelangelo、Hunyuan-DiT、HunyuanVideo、HunyuanWorld-1.0、HunyuanWorld-Voyager以及 PoseMaster，感谢他们开放的研究与探索。

引用

如果您在研究中使用此代码，请引用：

@misc{hunyuan3d2025hunyuan3domni,
      title={Hunyuan3D-Omni: 一个用于可控生成 3D 资产的统一框架}, 
      author={腾讯 Hunyuan3D 团队},
      year={2025},
      eprint={2509.21245},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2509.21245}, 
}

@misc{hunyuan3d2025hunyuan3d,
    title={Hunyuan3D 2.1：从图像到高保真 3D 资产，并配备可用于生产的 PBR 材质},
    author={腾讯 Hunyuan3D 团队},
    year={2025},
    eprint={2506.15442},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

@misc{hunyuan3d22025tencent,
    title={Hunyuan3D 2.0：扩展扩散模型以生成高分辨率纹理 3D 资产},
    author={腾讯 Hunyuan3D 团队},
    year={2025},
    eprint={2501.12202},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

@misc{yang2024hunyuan3d,
    title={Hunyuan3D 1.0：一个用于文本到 3D 和图像到 3D 生成的统一框架},
    author={腾讯 Hunyuan3D 团队},
    year={2024},
    eprint={2411.02293},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

星标历史

Hunyuan3D-Omni 快速上手指南

Hunyuan3D-Omni 是腾讯混元团队推出的统一 3D 资产可控生成框架。它在 Hunyuan3D 2.1 的基础上，引入了统一的控制编码器，支持通过点云、体素、骨架姿态和边界框等多种模态信号精确控制 3D 模型的生成。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 Windows
• Python 版本: 3.10 (已测试验证)
• 显卡要求: 显存至少 10 GB (用于生成过程)
• CUDA 版本: 推荐 CUDA 12.4 (对应 PyTorch 2.5.1)

安装步骤

1. 安装 PyTorch

根据官方推荐，首先安装与 CUDA 12.4 匹配的 PyTorch 核心组件：

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

提示：国内用户若下载缓慢，可尝试使用清华大学或阿里云镜像源替换 --index-url 后的地址。

2. 安装项目依赖

克隆项目代码后，进入目录并安装其余依赖包：

pip install -r requirements.txt

3. 下载模型

从 Hugging Face 下载预训练模型文件，并将其放置在项目指定的模型目录中（通常为 weights 或配置文件指定的路径）：

• 模型地址: Hunyuan3D-Omni on Hugging Face
• 模型大小: 3.3B

基本使用

安装完成后，即可通过命令行进行多模态推理。工具支持四种控制类型：点云 (point)、体素 (voxel)、边界框 (bbox) 和 姿态 (pose)。

基础推理命令

以下是最简单的运行示例，以点云控制为例：

python3 inference.py --control_type point

进阶选项

为了获得更稳定的生成结果或更快的推理速度，可以添加以下参数：

• --use_ema: 启用指数移动平均模型，提升生成稳定性。
• --flashvdm: 启用 FlashVDM 优化，显著加快推理速度。

组合使用示例：

# 使用点云控制 + EMA 稳定模式
python3 inference.py --control_type point --use_ema

# 使用点云控制 + 加速模式
python3 inference.py --control_type point --flashvdm

# 同时启用 EMA 和加速
python3 inference.py --control_type point --use_ema --flashvdm

切换控制类型

只需更改 --control_type 参数即可切换不同的控制模态：

# 边界框控制
python3 inference.py --control_type bbox

# 姿态控制 (适用于人物模型)
python3 inference.py --control_type pose

# 体素控制
python3 inference.py --control_type voxel

请根据您的输入数据格式（如点云文件、骨骼数据等）选择对应的控制类型，并确保输入数据已按照项目要求的格式准备好。