Tencent Hunyuan3D

一、前言

        腾讯于2024年11月5日正式开源了最新的MoE模型“混元Large”以及混元3D生成大模型“Hunyuan3D-1.0”，支持企业及开发者在精调、部署等不同场景下的使用需求。

GitHub - Tencent/Hunyuan3D-1

二、技术与原理

        Hunyuan3D-1.0 是一款支持文本生成3D（Text-to-3D）和图像生成3D（Image-to-3D）的统一框架，旨在提升3D生成的速度和质量。该模型采用两阶段方法：

1. 多视角扩散模型：在约4秒内高效生成多视角RGB图像，捕捉3D资产的丰富细节。

2. 前馈重建模型：在约7秒内根据生成的多视角图像快速重建3D资产，处理多视角生成中的噪声和不一致性，恢复3D结构。

        该框架集成了腾讯自研的文本生成图像模型“Hunyuan-DiT”，支持文本和图像条件的3D生成。标准版本的参数量是轻量版和其他现有模型的3倍，平衡了生成速度和质量，显著减少了生成时间，同时保持了生成资产的质量和多样性。

三、主要特性

• 双模式支持：同时支持文本和图像输入，满足不同的3D生成需求。

• 高效生成：在NVIDIA A100 GPU上，轻量版模型约10秒生成3D网格，标准版约25秒。

• 开源计划：提供推理、检查点、烘焙相关、训练、ComfyUI、蒸馏版本和TensorRT版本的开源支持，方便开发者使用和二次开发。

四、使用方法

1. 环境配置：建议使用Python 3.9和CUDA 11.7以上版本。可通过提供的env_install.sh脚本进行环境安装。

2. 模型下载：从Hugging Face下载预训练模型，包括轻量版、标准版和稀疏视角重建模型。

3. 推理：提供了文本生成3D和图像生成3D的推理脚本，可根据需求进行配置。

4. Gradio界面：提供了基于Gradio的Web界面，方便用户进行交互式操作。

五、当前瓶颈

        尽管Hunyuan3D-1.0在生成速度和质量上取得了显著进展，但仍存在以下挑战：

• 生成质量的提升：在复杂场景或细节丰富的对象上，生成的3D模型可能存在细节缺失或不准确的情况，需要进一步优化模型以提升生成质量。

• 多样性与泛化能力：模型在处理多样化输入时的泛化能力有待增强，特别是在处理未见过的输入或复杂场景时，可能无法生成高质量的3D模型。

• 计算资源需求：尽管生成速度有所提升，但在高分辨率或复杂场景下，仍需要大量计算资源，限制了模型的实际应用范围。

六、教程汉化

1. 开始安装

首先，克隆仓库并进入项目目录：

git clone https://github.com/tencent/Hunyuan3D-1 cd Hunyuan3D-1

2. 环境配置（适用于Linux）

项目提供了 env_install.sh 脚本来配置环境，建议使用 Python 3.9 和 CUDA 11.7 以上版本。

安装步骤：

conda create -n hunyuan3d-1 python=3.9 conda activate hunyuan3d-1 bash env_install.sh

安装 xformers 或 flash_attn 来加速计算

pip install xformers --index-url https://download.pytorch.org/whl/cu121
pip install flash_attn

先前已经创建好？

如果先前已经创建好环境，直接激活进入即可

conda activate hunyuan3d-1-py311

先前已经创建好但是忘记了？

conda env list

这个命令将列出系统中所有的 Python 版本和 Conda 虚拟环境

检查环境是否切换成功，pip是否对应虚拟环境

which pip

3. 下载预训练模型

预训练模型可以从 Hugging Face 获取：https://huggingface.co/spaces/tencent/Hunyuan3D-1

提供以下三种模型：

• Hunyuan3D-1/lite：轻量版模型，用于多视角生成。
• Hunyuan3D-1/std：标准版模型，用于多视角生成。
• Hunyuan3D-1/svrm：稀疏视角重建模型。

下载模型的步骤：

1.首先安装 Hugging Face CLI 工具：

python3 -m pip install "huggingface_hub[cli]"

2.下载模型文件：

mkdir weights huggingface-cli download tencent/Hunyuan3D-1 --local-dir ./weights mkdir weights/hunyuanDiT huggingface-cli download Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled --local-dir ./weights/hunyuanDiT

4. 推理生成

文本生成3D

支持中英文输入，可以使用以下命令进行文本生成3D：

python3 main.py \ --text_prompt "a lovely rabbit" \ --save_folder ./outputs/test/ \ --max_faces_num 90000 \ --do_texture_mapping \ --do_render

图像生成3D

使用以下命令进行图像生成3D，将 /path/to/your/image 替换为图像路径：

python3 main.py \ --image_prompt "/path/to/your/image" \ --save_folder ./outputs/test/ \ --max_faces_num 90000 \ --do_texture_mapping \ --do_render

5. 常用参数配置

参数	默认值	描述
--text_prompt	None	文本提示，用于3D生成
--image_prompt	None	图像路径，用于3D生成
--t2i_seed	0	文本生成图像的随机种子
--t2i_steps	25	文本生成图像的采样步数
--gen_seed	0	3D生成的随机种子
--gen_steps	50	3D生成的采样步数
--max_faces_num	90000	3D网格的最大面数限制
--save_memory	False	文生图将自动移至CPU
--do_texture_mapping	False	将顶点阴影更改为纹理阴影
--do_render	False	是否渲染GIF

6. 预设脚本

项目还提供了以下快捷脚本来帮助用户快速执行不同配置的任务：

bash scripts/text_to_3d_demo.sh # 文本生成3D的示例脚本 bash scripts/text_to_3d_fast_demo.sh # 快速文本生成3D的示例脚本 bash scripts/image_to_3d_demo.sh # 图像生成3D的示例脚本 bash scripts/image_to_3d_fast_demo.sh # 快速图像生成3D的示例脚本

注意：运行这些示例脚本通常需要约40GB的显存。

7. 使用 Gradio 进行交互操作

项目提供了基于 Gradio 的 Web 界面，方便用户进行交互式操作。

• 标准版（更好的生成效果）：

python3 app.py

• 轻量版（更快的生成速度）：

python3 app.py --use_lite

运行后，可通过 http://0.0.0.0:8080 访问Web界面。请将 0.0.0.0 替换为您的服务器IP地址。

8. 摄像机参数

输出视图固定为一组摄像机姿势，默认视角设置如下：

• 方位角 （相对于输入视角）
• Azimuth  (relative to input view)：0度，60度，120度，180度，240度，300度。

七、Gradio界面使用教程

 Text to 3D

1. Text to 3D功能介绍

• Text to 3D：将输入的文字描述转换为3D模型。

2. 输入选项

• Input text：输入描述3D模型的文字。例如，“一只黑白相间的熊猫在白色背景上居中坐着，呈现出卡通风格和可爱氛围”。这会生成一个符合描述的3D模型。

3. 参数设置

• T2I seed：用于文字转图像的随机种子。数值的变化会导致生成的图像略有不同。默认值为 0，但如果结果不理想，可以尝试更改此值。
• T2I step：生成文字到图像时的步数。步数越多，生成的图像质量可能越高，但生成时间也会更长。默认值是 25。
• Gen seed：用于图像到3D模型的随机种子。默认值为 0，但如果结果不满意，可以更改此值。
• Gen step：生成3D模型时的步数，数值越高生成的细节可能越多，默认是 50。
• Max number of faces：控制生成3D模型的面数。默认值是 90000，较高的面数会带来更精细的模型，但处理速度可能会变慢。

4. 导出选项

• Texture mapping：勾选后，生成的3D模型会包含纹理贴图，更加逼真。
• Render gif：勾选后，会导出一个 .gif 动态图片，展示3D模型的多角度视图。

5. 输出格式

• Multi views：多角度视图预览。
• Obj：生成 .obj 格式的3D模型文件。
• Glb：生成 .glb 格式的3D模型文件，适合Web应用。
• GIF：导出 .gif 动态图片，展示模型的360度视图。
• rembg image：移除背景图像。

Image to 3D

1. Image to 3D功能介绍

• Image to 3D：将输入的图像转换为3D模型。您可以上传一张图像（例如某个物体的图片），系统将尝试生成相应的3D模型。

2. 输入选项

• Input image：在这里上传要转换为3D模型的图像。

3. 参数设置

• Gen seed：用于生成3D模型的随机种子。数值的变化会影响生成的模型略有不同。如果对结果不满意，可以更改这个值（默认是 0）。
• Gen step：生成3D模型时的步数，数值越高，生成的模型可能更精细，默认是 50。
• Max number of faces：控制生成3D模型的面数。默认值是 90000，较高的面数可以带来更细致的模型，但处理速度可能变慢。

4. 导出选项

• Texture mapping：勾选后，生成的3D模型会包含纹理贴图，使模型更真实。
• Render gif：勾选后，会导出一个 .gif 文件，以动态方式展示生成的3D模型。

5. 输出格式

• rembg image：移除图像的背景。
• Multi views：展示生成的3D模型的多角度视图。
• Obj：导出为 .obj 格式的3D模型文件。
• Glb：导出为 .glb 格式的3D模型文件，更适合Web应用。
• GIF：导出 .gif 动态文件，展示模型的多角度视图。