腾讯混元3D 2.1部署和使用指南

腾讯Hunyuan3D-2.1 是腾讯混元团队推出的一个可扩展的 3D 资产生成系统，通过开源框架和基于物理的渲染 （PBR） 纹理合成，首次发布完整的模型权重和训练代码，使社区开发人员能够直接微调和扩展模型，以适应各种下游应用。升级后的 PBR 管道取代了以前基于 RGB 的纹理模型，利用基于物理的材料模拟来生成具有照片般逼真光线交互的纹理（例如，金属反射、次表面散射）。

形状生成流程

系统的形状生成模块包含以下关键组件：

• Hunyuan3D-DiT VAE-Decoder

• DiT Blocks

• OND Lir

• Transformer结构

生成流程如下：

1、输入图像经过处理得到Noisy Latent

2、结合Timestep t和PE MN Latent生成Shape

3、通过Query points Q得到3D Shape

纹理合成框架

纹理合成采用双分支结构：

• 冻结的参考分支

• 可训练的生成分支

生成过程中会结合几何条件（法线、CCM），生成Albedo、Metallic及Roughness等纹理参数。

性能表现

团队将Hunyuan3D 2.1与其他开源及闭源的3D生成方法进行了评估，数值结果显示，Hunyuan3D 2.1在生成纹理3D资产的质量和条件跟随能力上超越了所有基线模型。

形状生成性能对比

纹理生成性能对比

Hunyuan3D-2.1模型库

Hunyuan3D-2.1提供了两个核心模型：

资源占用情况：

• 形状生成：10GB VRAM

• 纹理生成：21GB VRAM

• 形状和纹理同时生成：29GB VRAM

Hunyuan3D 2.1安装指南

Hunyuan3D 2.1支持Macos、Windows、Linux系统。

安装依赖

模型在A100 GPU上测试，需要Python 3.10和PyTorch 2.5.1+cu124：

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

cd hy3dpaint/custom_rasterizer
pip install -e .

cd ../..

cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

代码使用

系统设计了类似diffusers的API，以下是生成3D模型的示例代码：

import sys

sys.path.insert(0, './hy3dshape')
sys.path.insert(0, './hy3dpaint')
from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

# 先生成网格
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2.1')
mesh_untextured = shape_pipeline(image='assets/demo.png')[0]

# 生成纹理
paint_pipeline = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=6, resolution=512))
mesh_textured = paint_pipeline(mesh_path, image_path='assets/demo.png')

Gradio应用

可以在本地部署Gradio应用：

python3 gradio_app.py \
  --model_path tencent/Hunyuan3D-2.1 \
  --subfolder hunyuan3d-dit-v2-1 \
  --texgen_model_path tencent/Hunyuan3D-2.1 \
  --low_vram_mode