Hunyuan3D-2 完全技术指南：双阶段图生 3D 生成系统的架构、API 与实战部署-酒店常州论坛

Hunyuan3D-2 完全技术指南：双阶段图生 3D 生成系统的架构、API 与实战部署

【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2

本文以 Hunyuan3D-2 仓库的日文 README（README_ja_jp.md）为主体骨架，完整覆盖该系统的双阶段生成架构、官方评测数据、模型清单与全部使用方式，并结合hy3dgen源码逐一剖析Hunyuan3DDiTFlowMatchingPipeline与Hunyuan3DPaintPipeline的加载机制、调用参数与默认值。读完后，你将能够独立完成 Hunyuan3D 2.0 的环境安装，用 diffusers 风格的 API 跑通“单图到带纹理 3D 资产”的完整链路，并为 Gradio 应用与低显存场景配置合适的启动参数。

一、系统定位：形状与纹理解耦的大规模 3D 合成系统

Hunyuan3D 2.0 是面向高分辨率带纹理 3D 资产生成的大规模 3D 合成系统，由两个基础组件构成：

Hunyuan3D-DiT（形状生成模型）：构建在可扩展的 flow-based diffusion transformer 之上，目标是生成与给定条件图像充分一致的几何体，为下游应用提供基础；
Hunyuan3D-Paint（纹理合成模型）：利用强大的几何先验与扩散先验，为生成或手工制作的网格产出高分辨率、色彩鲜明的纹理贴图。

此外，官方还构建了 Hunyuan3D-Studio 这一多用途制作平台，帮助专业与非专业用户高效地操作甚至动画化网格资产。项目口号为“让每个人在 3D 资产创建与操作中的想象力成为现实”。

这一设计思路的关键在于形状与纹理生成的难度解耦：先生成“裸网格（bare mesh）”，再为该网格合成纹理贴图，既降低了单阶段端到端生成的难度，也允许对任意手工网格直接进行纹理化。

二、两阶段生成流水线与源码映射

架构图（上图，来自 assets/images/arch.jpg）展示了从条件图出发、经 Hunyuan3D-DiT 得到几何、再经 Hunyuan3D-Paint 得到带纹理资产的完整链路。这一流程在源码中有清晰的对应关系：

阶段一：形状生成（hy3dgen/shapegen/pipelines.py）

入口为Hunyuan3DDiTFlowMatchingPipeline，其__call__实现（hy3dgen/shapegen/pipelines.py#L680-L770）依次完成：图像预处理（prepare_image）→ 条件编码（encode_cond，对 classifier-free guidance 拼接触发/非条件分支）→ 以sigmas = np.linspace(0, 1, num_inference_steps)构造的 flow matching 时间步序列上做扩散采样 → 调用self._export将 latent 经 VAE 解码、由 marching cubes 表面重建导出trimesh对象。
时间步调度由 hy3dgen/shapegen/schedulers.py 中的FlowMatchEulerDiscreteScheduler（hy3dgen/shapegen/schedulers.py#L56）与ConsistencyFlowMatchEulerDiscreteScheduler（hy3dgen/shapegen/schedulers.py#L330）承担，后者对应一致性蒸馏（Turbo 类）模型。
形状后处理工具（面数缩减、浮点剔除、退化面剔除、网格简化）统一导出自 hy3dgen/shapegen/init.py#L16：FaceReducer、FloaterRemover、DegenerateFaceRemover、MeshSimplifier。

阶段二：纹理合成（hy3dgen/texgen/pipelines.py）

Hunyuan3DPaintPipeline.__call__（hy3dgen/texgen/pipelines.py#L189-L240）的实际流程为：

输入图像经recenter_image居中（支持透明通道裁切并补白边）；
送入Light_Shadow_Remover（delight 模型）去除光照阴影，得到“无光照”提示图；
对手工/生成网格执行 UV 展开（mesh_uv_wrap）并加载进可微渲染器MeshRender；
从 6 个候选相机位（方位角 [0, 90, 180, 270, 0, 180]、俯仰角 [0, 0, 0, 0, 90, -90]，权重 [1, 0.1, 0.5, 0.1, 0.05, 0.05]）渲染法线图与位置图，连同提示图交给多视角扩散网络（Multiview_Diffusion_Net）生成多视角纹理视图；
bake_from_multiview将多视角视图反向投影并加权（bake_exp=4）融合为 2048×2048 纹理图（render_size与texture_size默认均为 2048，见 hy3dgen/texgen/pipelines.py#L40-L47），再对不可靠区域做 UV 修复（inpaint），最终set_texture+save_mesh返回带纹理的网格。

三、官方评测数据

README 中给出的量化对比（来自文档原文，指标为 CMMD↓、FID_CLIP↓、FID↓、CLIP-score↑）：

模型	CMMD(⬇)	FID_CLIP(⬇)	FID(⬇)	CLIP-score(⬆)
顶级开源模型1	3.591	54.639	289.287	0.787
顶级闭源模型1	3.600	55.866	305.922	0.779
顶级闭源模型2	3.368	49.744	294.628	0.806
顶级闭源模型3	3.218	51.574	295.691	0.799
Hunyuan3D 2.0	3.193	49.165	282.429	0.809

官方结论：在生成带纹理 3D 资产的几何细节、条件一致性与纹理质量上，Hunyuan3D 2.0 优于全部对比基线（开源与闭源模型）。技术报告 PDF 存于 assets/report/Tencent_Hunyuan3D_2_0.pdf。

四、环境安装（继承原文档并补充依赖说明）

原文档的安装步骤为：先从 PyTorch 官网安装 PyTorch，然后：

pip install -r requirements.txt # for texture cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd hy3dgen/texgen/differentiable_renderer python3 setup.py install

结合 requirements.txt 可以确认各依赖的职责边界：

扩散推理核心：diffusers、transformers、einops、omegaconf、accelerate（accelerate同时是enable_model_cpu_offload低显存机制的运行前提，源码要求 accelerate ≥ 0.17.0，见 hy3dgen/shapegen/pipelines.py#L353-L356）；
网格处理：trimesh（输出对象类型）、pymeshlab、pygltflib、xatlas（UV 展开）；
两个setup.py install编译的正是纹理流水线的 CUDA 扩展：hy3dgen/texgen/custom_rasterizer（自定义光栅化 kernel，hy3dgen/texgen/custom_rasterizer/lib/custom_rasterizer_kernel/rasterizer_gpu.cu）与 hy3dgen/texgen/differentiable_renderer（可微渲染），这也是为什么仅做形状生成时并非必须编译它们，而纹理生成必须安装；
Demo 层：gradio、fastapi、uvicorn、rembg、onnxruntime。

模型权重不随仓库分发。加载时smart_load_model（hy3dgen/shapegen/utils.py#L89-L126）的查找顺序是：先查本地缓存目录（环境变量HY3DGEN_MODELS，默认~/.cache/hy3dgen下按模型名/子目录组织），找不到才通过huggingface_hub.snapshot_download仅拉取指定subfolder/*的文件——因此显式指定subfolder可以直接控制下载哪一套权重。

五、API 用法：diffusers 风格接口与全部参数

5.1 形状生成 Hunyuan3D-DiT

from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(image='assets/demo.png')[0]

from_pretrained的完整签名（hy3dgen/shapegen/pipelines.py#L200-L232）：device='cuda'、dtype=torch.float16、use_safetensors=True、variant='fp16'、subfolder='hunyuan3d-dit-v2-0'。也就是说上面的示例默认加载的就是Hunyuan3D-DiT-v2-0子目录下的config.yaml与model.fp16.safetensors。

pipeline(...)调用参数及源码默认值（hy3dgen/shapegen/pipelines.py#L683-L700）：

参数	默认值	作用
`image`	—	条件图：路径字符串、PIL 图像或列表（支持批量）
`num_inference_steps`	50	扩散采样步数，sigmas 在 [0,1] 上均匀取该数量的点
`timesteps`/`sigmas`	None	自定义时间步/噪声尺度序列（二选一，见`retrieve_timesteps`）
`guidance_scale`	5.0	flow matching 版 classifier-free guidance 强度；对带`guidance_embed`的蒸馏模型改为嵌入 guidance（源码 L734-L737）
`box_v`	1.01	表面重建包围盒半径
`octree_resolution`	384	marching cubes 八叉树分辨率，直接影响网格细节上限
`mc_level`	0.0	等值面 level 值
`num_chunks`	8000	表面重建分块大小
`mc_algo`	None	表面提取算法（如`mc`），源码提示已建议改用`pipeline.vae.surface_extractor = SurfaceExtractors[mc_algo]()`
`output_type`	"trimesh"	输出`trimesh`对象或`latent`
`enable_pbar`	True	是否显示采样进度条

输出为trimesh 对象（源码中export_to_trimesh会将面片法线方向翻转后构造trimesh.Trimesh，见 hy3dgen/shapegen/pipelines.py#L94-L109），可直接mesh.export('out.glb')保存为 glb/obj 等格式。

旧版 DDPM 风格的Hunyuan3DDiTPipeline也一并导出，其 guidance 支持dual_guidance（CLIP 引导 + DINO 引导双分支，见 hy3dgen/shapegen/pipelines.py#L551-L646），Flow Matching 版是其__call__的简化重写。

5.2 纹理合成 Hunyuan3D-Paint

from hy3dgen.texgen import Hunyuan3DPaintPipeline from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline # 先生成网格 pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(image='assets/demo.png')[0] pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(mesh, image='assets/demo.png')

Hunyuan3DPaintPipeline.from_pretrained(model_path, subfolder='hunyuan3d-paint-v2-0-turbo')会并行加载两套权重：固定的hunyuan3d-delight-v2-0（去光照模型）与subfolder指定的多视角扩散模型（hy3dgen/texgen/pipelines.py#L54-L87）；subfolder取值决定pipe_name为hunyuanpaint或hunyuanpaint-turbo（hy3dgen/texgen/pipelines.py#L49）。pipeline(mesh, image)返回的是已烘焙纹理的 trimesh 网格，可直接导出 glb。

5.3 高级用法：文本到 3D 与去背景

官方引导读者阅读 minimal_demo.py，其完整流程是：打开示例图 → 若为 RGB（无透明通道）则用hy3dgen.rembg.BackgroundRemover去背景 → 形状生成 → 纹理生成 →mesh.export('demo.glb')（minimal_demo.py#L21-L33）。

仓库 examples/ 目录还提供了更多进阶入口：shape_gen.py、shape_gen_multiview.py（多视角图到 3D）、textured_shape_gen.py、fast_texture_gen_multiview.py（FlashVDM/Turbo 快速推理）等，可作为参数组合的参照实现。

六、Gradio 应用与命令行参数

本地托管 Gradio 界面：

python3 gradio_app.py

gradio_app.py#L648-L660 定义了全部启动参数，默认值与常见调优组合如下：

参数	默认值	说明
`--model_path`	`tencent/Hunyuan3D-2mini`	形状模型仓库
`--subfolder`	`hunyuan3d-dit-v2-mini-turbo`	具体形状模型子目录（如`hunyuan3d-dit-v2-0`加载 1.1B 主模型）
`--texgen_model_path`	`tencent/Hunyuan3D-2`	纹理模型仓库
`--port`/`--host`	`8080`/`0.0.0.0`	服务端口与地址
`--device`	`cuda`	运行设备
`--mc_algo`	`mc`	表面提取算法（传入`enable_flashvdm`时联动 VAE 的 mc 算法）
`--enable_t23d`	关	开启文本到 3D（内部先文本生图）
`--disable_tex`	关	仅形状生成、跳过纹理
`--enable_flashvdm`	关	启用 FlashVDM 加速：源码中会按模型名映射替换为 turbo 版 VAE 子目录（hy3dgen/shapegen/pipelines.py#L258-L298）
`--compile`	关	对 VAE/模型/conditioner 执行`torch.compile`（hy3dgen/shapegen/pipelines.py#L253-L256）
`--low_vram_mode`	关	低显存模式，内部调用`enable_model_cpu_offload`（依赖 accelerate 的`cpu_offload_with_hook`，offload 顺序为`conditioner->model->vae`，见 hy3dgen/shapegen/pipelines.py#L136 与 L334-L402）

例如要跑 1.1B 主模型可执行：

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

不本地部署时，可直接使用官方 Hunyuan3D Studio 网页版。

七、预训练模型清单与开源计划

README 列出的首发模型（发布日期 2025-01-21，均托管于 HuggingFacetencent/Hunyuan3D-2）：

模型	日期	说明
Hunyuan3D-DiT-v2-0	2025-01-21	图像到形状模型（`subfolder='hunyuan3d-dit-v2-0'`）
Hunyuan3D-Paint-v2-0	2025-01-21	纹理生成模型（delight + 多视角扩散，见上节`subfolder`机制）

仓库hy3dgen代码后续还支持hunyuan3d-paint-v2-0-turbo等蒸馏子目录（源码pipe_dict已包含映射），但本文以日文 README 所列 v2-0 模型为基准。开源状态：推理代码 ✅、模型检查点 ✅、技术报告 ✅；ComfyUI、TensorRT 版本在原文档中仍为待办项。

八、引用

若使用本仓库，请按官方 BibTeX 引用技术报告（assets/report/Tencent_Hunyuan3D_2_0.pdf，2025 年发布）：

@misc{hunyuan3d22025tencent, title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation}, author={Tencent Hunyuan3D Team}, year={2025}, eprint={2501.12202}, archivePrefix={arXiv}, primaryClass={cs.CV} }

1.0 版本引用：

@misc{yang2024hunyuan3d, title={Hunyuan3D 1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation}, author={Tencent Hunyuan3D Team}, year={2024}, eprint={2411.02293}, archivePrefix={arXiv}, primaryClass={cs.CV} }

九、小结

架构：两阶段流水线（DiT 形状生成 → Paint 纹理合成）将几何与外观解耦，可复用于手工网格；
落地要点：纹理模块必须额外编译custom_rasterizer与differentiable_renderer两个 CUDA 扩展；
API：两个Pipeline类统一采用from_pretrained+pipeline(...)的 diffusers 风格，形状输出 trimesh、纹理输入 trimesh + 条件图，形成闭环；
调优抓手：subfolder切换模型规格、--low_vram_mode走 accelerate CPU offload、--enable_flashvdm走 turbo VAE、octree_resolution/num_inference_steps控制质量-速度权衡。

【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析