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 仓库的日文 READMEREADME_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 中的FlowMatchEulerDiscreteSchedulerhy3dgen/shapegen/schedulers.py#L56与ConsistencyFlowMatchEulerDiscreteSchedulerhy3dgen/shapegen/schedulers.py#L330承担后者对应一致性蒸馏Turbo 类模型。形状后处理工具面数缩减、浮点剔除、退化面剔除、网格简化统一导出自 hy3dgen/shapegen/init.py#L16FaceReducer、FloaterRemover、DegenerateFaceRemover、MeshSimplifier。阶段二纹理合成hy3dgen/texgen/pipelines.pyHunyuan3DPaintPipeline.__call__hy3dgen/texgen/pipelines.py#L189-L240的实际流程为输入图像经recenter_image居中支持透明通道裁切并补白边送入Light_Shadow_Removerdelight 模型去除光照阴影得到“无光照”提示图对手工/生成网格执行 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_exp4融合为 2048×2048 纹理图render_size与texture_size默认均为 2048见 hy3dgen/texgen/pipelines.py#L40-L47再对不可靠区域做 UV 修复inpaint最终set_texturesave_mesh返回带纹理的网格。三、官方评测数据README 中给出的量化对比来自文档原文指标为 CMMD↓、FID_CLIP↓、FID↓、CLIP-score↑模型CMMD(⬇)FID_CLIP(⬇)FID(⬇)CLIP-score(⬆)顶级开源模型13.59154.639289.2870.787顶级闭源模型13.60055.866305.9220.779顶级闭源模型23.36849.744294.6280.806顶级闭源模型33.21851.574295.6910.799Hunyuan3D 2.03.19349.165282.4290.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、accelerateaccelerate同时是enable_model_cpu_offload低显存机制的运行前提源码要求 accelerate ≥ 0.17.0见 hy3dgen/shapegen/pipelines.py#L353-L356网格处理trimesh输出对象类型、pymeshlab、pygltflib、xatlasUV 展开两个setup.py install编译的正是纹理流水线的 CUDA 扩展hy3dgen/texgen/custom_rasterizer自定义光栅化 kernelhy3dgen/texgen/custom_rasterizer/lib/custom_rasterizer_kernel/rasterizer_gpu.cu与 hy3dgen/texgen/differentiable_renderer可微渲染这也是为什么仅做形状生成时并非必须编译它们而纹理生成必须安装Demo 层gradio、fastapi、uvicorn、rembg、onnxruntime。模型权重不随仓库分发。加载时smart_load_modelhy3dgen/shapegen/utils.py#L89-L126的查找顺序是先查本地缓存目录环境变量HY3DGEN_MODELS默认~/.cache/hy3dgen下按模型名/子目录组织找不到才通过huggingface_hub.snapshot_download仅拉取指定subfolder/*的文件——因此显式指定subfolder可以直接控制下载哪一套权重。五、API 用法diffusers 风格接口与全部参数5.1 形状生成 Hunyuan3D-DiTfrom hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(tencent/Hunyuan3D-2) mesh pipeline(imageassets/demo.png)[0]from_pretrained的完整签名hy3dgen/shapegen/pipelines.py#L200-L232devicecuda、dtypetorch.float16、use_safetensorsTrue、variantfp16、subfolderhunyuan3d-dit-v2-0。也就是说上面的示例默认加载的就是Hunyuan3D-DiT-v2-0子目录下的config.yaml与model.fp16.safetensors。pipeline(...)调用参数及源码默认值hy3dgen/shapegen/pipelines.py#L683-L700参数默认值作用image—条件图路径字符串、PIL 图像或列表支持批量num_inference_steps50扩散采样步数sigmas 在 [0,1] 上均匀取该数量的点timesteps/sigmasNone自定义时间步/噪声尺度序列二选一见retrieve_timestepsguidance_scale5.0flow matching 版 classifier-free guidance 强度对带guidance_embed的蒸馏模型改为嵌入 guidance源码 L734-L737box_v1.01表面重建包围盒半径octree_resolution384marching cubes 八叉树分辨率直接影响网格细节上限mc_level0.0等值面 level 值num_chunks8000表面重建分块大小mc_algoNone表面提取算法如mc源码提示已建议改用pipeline.vae.surface_extractor SurfaceExtractors[mc_algo]()output_typetrimesh输出trimesh对象或latentenable_pbarTrue是否显示采样进度条输出为trimesh 对象源码中export_to_trimesh会将面片法线方向翻转后构造trimesh.Trimesh见 hy3dgen/shapegen/pipelines.py#L94-L109可直接mesh.export(out.glb)保存为 glb/obj 等格式。旧版 DDPM 风格的Hunyuan3DDiTPipeline也一并导出其 guidance 支持dual_guidanceCLIP 引导 DINO 引导双分支见 hy3dgen/shapegen/pipelines.py#L551-L646Flow Matching 版是其__call__的简化重写。5.2 纹理合成 Hunyuan3D-Paintfrom hy3dgen.texgen import Hunyuan3DPaintPipeline from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline # 先生成网格 pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(tencent/Hunyuan3D-2) mesh pipeline(imageassets/demo.png)[0] pipeline Hunyuan3DPaintPipeline.from_pretrained(tencent/Hunyuan3D-2) mesh pipeline(mesh, imageassets/demo.png)Hunyuan3DPaintPipeline.from_pretrained(model_path, subfolderhunyuan3d-paint-v2-0-turbo)会并行加载两套权重固定的hunyuan3d-delight-v2-0去光照模型与subfolder指定的多视角扩散模型hy3dgen/texgen/pipelines.py#L54-L87subfolder取值决定pipe_name为hunyuanpaint或hunyuanpaint-turbohy3dgen/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.pyFlashVDM/Turbo 快速推理等可作为参数组合的参照实现。六、Gradio 应用与命令行参数本地托管 Gradio 界面python3 gradio_app.pygradio_app.py#L648-L660 定义了全部启动参数默认值与常见调优组合如下参数默认值说明--model_pathtencent/Hunyuan3D-2mini形状模型仓库--subfolderhunyuan3d-dit-v2-mini-turbo具体形状模型子目录如hunyuan3d-dit-v2-0加载 1.1B 主模型--texgen_model_pathtencent/Hunyuan3D-2纹理模型仓库--port/--host8080/0.0.0.0服务端口与地址--devicecuda运行设备--mc_algomc表面提取算法传入enable_flashvdm时联动 VAE 的 mc 算法--enable_t23d关开启文本到 3D内部先文本生图--disable_tex关仅形状生成、跳过纹理--enable_flashvdm关启用 FlashVDM 加速源码中会按模型名映射替换为 turbo 版 VAE 子目录hy3dgen/shapegen/pipelines.py#L258-L298--compile关对 VAE/模型/conditioner 执行torch.compilehy3dgen/shapegen/pipelines.py#L253-L256--low_vram_mode关低显存模式内部调用enable_model_cpu_offload依赖 accelerate 的cpu_offload_with_hookoffload 顺序为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-02025-01-21图像到形状模型subfolderhunyuan3d-dit-v2-0Hunyuan3D-Paint-v2-02025-01-21纹理生成模型delight 多视角扩散见上节subfolder机制仓库hy3dgen代码后续还支持hunyuan3d-paint-v2-0-turbo等蒸馏子目录源码pipe_dict已包含映射但本文以日文 README 所列 v2-0 模型为基准。开源状态推理代码 ✅、模型检查点 ✅、技术报告 ✅ComfyUI、TensorRT 版本在原文档中仍为待办项。八、引用若使用本仓库请按官方 BibTeX 引用技术报告assets/report/Tencent_Hunyuan3D_2_0.pdf2025 年发布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_pretrainedpipeline(...)的 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），仅供参考