Hunyuan3D-2：开源的图像转3D资产生成系统
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
Hunyuan3D-2 是腾讯混元开源的图像转3D资产生成系统，可以免费部署在自己的 GPU 上。第一阶段由单图或多视图图像生成网格，第二阶段合成高分辨率纹理。本文面向会用 Python、有一块 NVIDIA 显卡的开发者，读完你能自己跑通单图生成、Turbo 加速、多视图和纹理四条链路。
Hunyuan3D-2两阶段流水线：从图像到带纹理资产
图像先进入形状模型 Hunyuan3D-DiT，它基于 flow matching 的扩散 Transformer，直接输出不带纹理的网格；网格再交给纹理模型 Hunyuan3D-Paint，结合参考图合成高分辨率纹理贴图，最终得到可直接渲染的 glb 资产。说白了，形状和纹理解耦还带来一个附带好处：Paint 链路可以单独作用在你手工建的网格上，不一定非要自己生成几何。两个模块的代码分别在hy3dgen/shapegen/和hy3dgen/texgen/下，形状侧的核心是 hy3dgen/shapegen/ 里的Hunyuan3DDiTFlowMatchingPipeline，用法接近 diffusers 的from_pretrained风格。
环境搭建：单图生成最小代码
PyTorch 按官网指引单独安装，其余依赖和两个纹理相关的 C++/CUDA 模块按下面顺序装：
git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2 pip install -r requirements.txt pip install -e . cd hy3dgen/texgen/custom_rasterizer && python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer && python3 setup.py install之后单图生成网格的最小示例如下，即examples/shape_gen.py的简化版：
import torch from PIL import Image from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( 'tencent/Hunyuan3D-2', subfolder='hunyuan3d-dit-v2-0', variant='fp16' ) image = Image.open('assets/demo.png').convert('RGBA') mesh = pipeline(image=image, num_inference_steps=50, octree_resolution=380, num_chunks=20000, generator=torch.manual_seed(12345))[0] mesh.export('demo.glb')返回的mesh是 trimesh 对象，可导出 glb/obj。带背景的图先过BackgroundRemover去背（见 hy3dgen/rembg.py）。官方数据：形状生成约 6GB 显存，形状加纹理合计约 16GB，16GB 卡可以单卡跑完整链路。
三个高频图像转3D能力
下面三个能力是实际用得最多的，每节按"适用场景 → 关键代码 → 参数说明"展开。
🚀 Turbo加速：5步推理出网格
适用场景：快速验证草稿与概念方案，想要几十秒内拿到可用网格。
pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( 'tencent/Hunyuan3D-2mini', subfolder='hunyuan3d-dit-v2-mini-turbo', use_safetensors=False, device='cuda' ) pipeline.enable_flashvdm(topk_mode='merge') mesh = pipeline(image=image, num_inference_steps=5, octree_resolution=380, num_chunks=20000)[0]enable_flashvdm：开启 FlashVDM，扩散步数从 50 蒸馏到 5，VAE 解码一并加速。num_inference_steps=5：Turbo 模式的默认步数。- 模型分 mini（0.6B）和完整版
hunyuan3d-dit-v2-0-turbo（1.1B）两档，后者细节更好，前者更省显存。
多视图输入怎么给图
适用场景：单张图拍不到物体背面，需要补全被遮挡的结构。
images = { "front": Image.open("assets/example_mv_images/1/front.png").convert("RGBA"), "left": Image.open("assets/example_mv_images/1/left.png").convert("RGBA"), "back": Image.open("assets/example_mv_images/1/back.png").convert("RGBA"), } pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( 'tencent/Hunyuan3D-2mv', subfolder='hunyuan3d-dit-v2-mv', variant='fp16' ) mesh = pipeline(image=images, num_inference_steps=50, octree_resolution=380)[0]image：pipeline 直接接受 dict，键为front/left/back。- 多视图必须换用专用模型 Hunyuan3D-2mv（1.1B），单图模型不支持这个输入形式。
- 三张图要求同一物体、光照一致，否则对应区域会出现接缝错位。
给网格合成4K PBR纹理
适用场景：最终交付，需要进引擎直接使用的带纹理 glb。
from hy3dgen.texgen import Hunyuan3DPaintPipeline pipeline_texgen = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline_texgen(mesh, image=image) mesh.export('demo_textured.glb')image：参考图，纹理的一致性和对齐都以它为准。- 形状加纹理合计约 16GB 显存，16GB 以下显卡建议先用 Gradio 的低显存模式跑通。
- Paint 另有蒸馏版
hunyuan3d-paint-v2-0-turbo；纹理链路同样支持给手工网格上色。
参数速查与常见现象处理
| 参数 | 作用 | 建议值 |
|---|---|---|
num_inference_steps | 扩散推理步数 | Turbo 用 5，标准质量用 30~50 |
octree_resolution | 网格化（marching cubes）分辨率 | 380，细节不足时提到 420 |
num_chunks | 体素解码分块数 | 20000，显存富余可加大 |
显存档位：形状生成约 6GB，形状加纹理约 16GB（官方口径）；卡不够时在gradio_app.py加--low_vram_mode，它会在生成后清空缓存、降低常驻占用。
三个常见现象：
- 现象：轮廓锯齿、细结构缺失 → 原因：
octree_resolution或步数偏低 → 处理：分辨率提到 420，交付件别用 5 步 Turbo，回到 30~50 步标准模式。 - 现象：多视图对应区域有裂缝、错位 → 原因：输入图背景残留或光照不一致 → 处理：先统一
BackgroundRemover去背，三视图同物同光再送入。 - 现象：CUDA 显存不足 → 原因：形状与纹理模型同时常驻 → 处理：换 0.6B 的 Hunyuan3D-2mini，或走 Gradio 的
--low_vram_mode。
🔌 入口与集成：Gradio、API服务器、Blender
# Gradio 页面（默认 8080 端口） python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm # API 服务器：POST /generate 即可图像转3D python api_server.py --host 0.0.0.0 --port 8080- Gradio 界面：带预览窗口的完整交互页，支持单图与多视图、去背与种子控制。
- API 服务器：把生成能力暴露成 HTTP 接口，方便批量处理。
- Blender 插件：blender_addon.py，需先启动 API 服务器，在 Blender 里直接调服务生成。
接下来可以试什么
examples/fast_shape_gen_multiview.py：多视图加 FlashVDM 的组合，看加速在多视图下的效果。examples/textured_shape_gen_multiview.py：多视图形状加纹理的完整链路，一次拿到带纹理成品。minimal_demo.py：接纹理增强模块，把贴图分辨率再往上提一档。
先跑通单图生成建立手感，再逐步加多视图和纹理，是最省时间的路线。
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
