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资产生成系统：用 Hunyuan3D-DiT 扩散模型生成与参考图对齐的网格几何，再由 Hunyuan3D-Paint 贴附纹理，最后导出可直接使用的 GLB 文件。官方给出的显存口径是：仅生成几何需 6 GB 显存，几何加纹理全流程需要 16 GB。本文按部署、参数选择、常见坑的顺序把流程走一遍。
能力总览
系统把3D生成拆成几何与纹理两个相互独立的阶段，好处是两段可以各自加速、各自替换，也可以给手工建模的网格单独上纹理而不重新生成几何。主要能力如下。
| 能力 | 输入 | 输出 | 适用场景 |
|---|---|---|---|
| 单图几何生成 | 一张参考图 | 无纹理网格（trimesh 对象） | 验证造型、比例与剪影 |
| 多视图几何生成 | 前/左/后三张图 | 遮挡被补全的完整网格 | 背面等单视角无法覆盖的结构 |
| 纹理生成 | 网格 + 参考图 | 带纹理 GLB | 游戏资产、商品展示 |
| 步数蒸馏加速（Turbo / FlashVDM） | 同上 | 5 步完成的网格 | 批量出快速原型 |
使用入口有四种：Python API、Gradio Web 界面、HTTP API 服务、Blender 插件，按需取用即可。
两阶段管线如何工作
第一阶段在潜空间采样。DiT（一种基于流匹配的扩散 Transformer）以参考图为条件，从纯噪声逐步采样出3D潜表示，再由 VAE 解码器展开成完整网格。表面提取走八叉树切分加移动立方体的路线，octree_resolution 控制切分粒度：数值越高细节越细，但表面提取变慢、占用的显存也更高。
第二阶段是上色。Hunyuan3D-Paint 基于几何与参考图生成高分辨率纹理，并映射到网格的 UV 布局上，所以手工建模的网格同样可以走这一步。
速度优化上，官方给了两条蒸馏路线：Fast 版用引导蒸馏把 DiT 推理时间减半；Turbo 版结合 FlashVDM 技术把扩散步数从 50 压到 5——它在 VAE 解码器里做自适应键值选择，相当于用少数几次解码覆盖整个体素。代码里对应一行pipeline.enable_flashvdm(topk_mode='merge')，再把推理步数设为 5。
官方技术报告给出的对比中，Hunyuan3D-2 在 CMMD 3.193、FID_CLIP 49.165、FID 282.429、CLIP-score 0.809 四项指标上均优于对比的三个闭源头部方法。
从零克隆到首次运行，三步走完
先按 PyTorch 官网安装对应 CUDA 版本的框架，然后克隆仓库并安装依赖：
git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2 pip install -r requirements.txt pip install -e . # 纹理生成需要编译两个 CUDA 组件 cd hy3dgen/texgen/custom_rasterizer && python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer && python3 setup.py install cd ../../..后两条 setup.py 安装只在使用纹理生成时需要执行。
最小可运行脚本如下，首次运行时from_pretrained会自动下载模型权重并缓存：
from PIL import Image from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( 'tencent/Hunyuan3D-2', device='cuda') image = Image.open('assets/demo.png').convert('RGBA') mesh = pipeline(image=image, num_inference_steps=50)[0] mesh.export('demo.glb')不想写 Python 也可以直接起 Gradio 界面，Turbo 版命令（0.6B 的 mini 模型加 5 步加速）：
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端到端：从一张图到带纹理的 GLB
以 assets/example_images 里的一张图为输入，完整链路是：去背景 → 几何生成 → 纹理生成 → 导出。
from hy3dgen.rembg import BackgroundRemover from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline from hy3dgen.texgen import Hunyuan3DPaintPipeline image = Image.open('assets/example_images/052.png').convert('RGBA') image = BackgroundRemover()(image) shape = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') tex = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = shape(image=image)[0] mesh = tex(mesh, image=image) mesh.export('textured.glb')多视图场景下，加载 Hunyuan3D-2mv 模型，把image参数传成{"front": ..., "left": ..., "back": ...}的字典，输出网格会补全单视角覆盖不到的背面结构。
参数调优与显存取舍
| 参数 | 作用 | 默认值 / 官方示例值 | 权衡 |
|---|---|---|---|
| num_inference_steps | 扩散采样步数 | 50；Turbo 用 5 | 步数越少越快，几何越粗糙；标准质量 30–50 步 |
| octree_resolution | 表面提取时的八叉树粒度 | 384（官方示例用 380） | 越高细节越细，表面提取越慢、显存越高 |
| num_chunks | 表面提取的并行块数 | 8000（官方示例用 20000） | 块数越大越快，但显存占用更高 |
| guidance_scale | 引导强度 | 5.0 | 调高更贴参考图，可能过拟合轮廓；调低更自由 |
| variant='fp16' | 半精度加载权重 | — | 官方示例中用于 mv 模型，降低显存 |
显存预算：仅几何 6 GB，几何加纹理共 16 GB。装不下时按顺序降级：换 Hunyuan3D-2mini（0.6B）→ 加variant='fp16'→ 下调 octree_resolution 与 num_chunks → Gradio 里启用--low_vram_mode。
常见故障点与处理
- 现象：CUDA 显存不足。多为纹理阶段与高分辨率叠加所致。按上一节的降级顺序处理：mini 模型、fp16、调低分辨率参数；批量跑时在纹理阶段前释放几何模型。
- 现象：导入 hy3dgen.texgen 报 ImportError。两个 CUDA 组件没有编译。回到部署一节执行两条 setup.py 安装。
- 现象：生成几何带背景、轮廓与参考图不符。输入图没有去背景。先用 BackgroundRemover 处理，以 RGBA 传入。
- 现象：多视图输出仍有裂缝或缺块。用错了单图模型处理三视图字典。换用 Hunyuan3D-2mv，并保证三张视图同一主体、光照一致。
- 现象：首次运行长时间无响应。权重在首次 from_pretrained 时从模型库下载缓存，属正常现象。
资源入口
- examples/：多视图、FlashVDM 加速、纹理生成等示例脚本
- hy3dgen/shapegen/：几何生成管线、DiT 与 VAE 实现
- hy3dgen/texgen/：纹理管线与可微光栅化器
- docs/source/started/api.md：API 使用文档
- minimal_demo.py：最短端到端脚本
这套系统不适合什么
先说授权：仓库采用腾讯混元非商业许可，商用需要单独评估。其次是输入形态，核心链路以图像为条件，纯文本输入需要先经过文生图环节（仓库内 hy3dgen/text2image.py 提供对应能力）。再者，纹理阶段的两个光栅化组件带 CUDA 内核，在 macOS 上编译不便；完整流程 16 GB 显存的要求对消费级显卡不算低。官方开源计划里，TensorRT 部署版本也尚未完成。需要纯文本直接建模或实时交互流水线的场景，这套系统不是合适选择。
下一步建议
- 跑一遍 minimal_demo.py，确认几何与纹理两条链路都能走通。
- 换 Hunyuan3D-2mini-turbo 加 FlashVDM，对比 5 步与 50 步的几何差异，确定自己业务的最低步数。
- 对背面质量有要求的资产，用 examples/shape_gen_multiview.py 试三视图输入。
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
