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生成的速度和质量。该模型采用两阶段方法：

多视角扩散模型：在约4秒内高效生成多视角RGB图像，捕捉3D资产的丰富细节。
前馈重建模型：在约7秒内根据生成的多视角图像快速重建3D资产，处理多视角生成中的噪声和不一致性，恢复3D结构。

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

三、主要特性

双模式支持：同时支持文本和图像输入，满足不同的3D生成需求。
高效生成：在NVIDIA A100 GPU上，轻量版模型约10秒生成3D网格，标准版约25秒。
开源计划：提供推理、检查点、烘焙相关、训练、ComfyUI、蒸馏版本和TensorRT版本的开源支持，方便开发者使用和二次开发。

四、使用方法

环境配置 ：建议使用Python 3.9和CUDA 11.7以上版本。可通过提供的env_install.sh脚本进行环境安装。
模型下载：从Hugging Face下载预训练模型，包括轻量版、标准版和稀疏视角重建模型。
推理：提供了文本生成3D和图像生成3D的推理脚本，可根据需求进行配置。
Gradio界面：提供了基于Gradio的Web界面，方便用户进行交互式操作。

五、当前瓶颈

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

生成质量的提升：在复杂场景或细节丰富的对象上，生成的3D模型可能存在细节缺失或不准确的情况，需要进一步优化模型以提升生成质量。
多样性与泛化能力：模型在处理多样化输入时的泛化能力有待增强，特别是在处理未见过的输入或复杂场景时，可能无法生成高质量的3D模型。
计算资源需求：尽管生成速度有所提升，但在高分辨率或复杂场景下，仍需要大量计算资源，限制了模型的实际应用范围。

六、教程汉化

1. 开始安装

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

bash 复制代码

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

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

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

安装步骤：

bash 复制代码

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

安装 xformers 或 flash_attn 来加速计算

bash 复制代码

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

先前已经创建好？

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

bash 复制代码

conda activate hunyuan3d-1-py311

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

bash 复制代码

conda env list

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

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

bash 复制代码

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 工具：

bash 复制代码

python3 -m pip install "huggingface_hub[cli]"

2.下载模型文件：

复制代码

bash 复制代码

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：

复制代码

bash 复制代码

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 替换为图像路径：

复制代码

bash 复制代码

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 复制代码

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 界面，方便用户进行交互式操作。

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

bash 复制代码

python3 app.py

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

bash 复制代码

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 动态文件，展示模型的多角度视图。