Hunyuan3D-2 代码集成指南用 diffusers 风格 API 调用 Shape 生成与纹理合成流水线【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2本文基于仓库文档 code.md 展开讲解 Hunyuan3D-2 的 Python 代码级接入方式如何通过Hunyuan3DDiTFlowMatchingPipeline从单张或多视角图片生成 3D 网格再通过Hunyuan3DPaintPipeline为网格自动合成纹理。读完本文你可以直接在项目脚本中复用官方流水线完成「图片 → 白模 → 带纹理 GLB」的完整生成链路并理解每个关键参数推理步数、八叉树分辨率、CFG 引导强度、模型缓存路径等背后的源码实现。1. API 设计思路diffusers 风格的 PipelineHunyuan3D-2 的核心推理能力封装在hy3dgen包中分为两大模块见 hy3dgen/shapegen/init.py 与 hy3dgen/texgen/init.pyhy3dgen.shapegenshape 生成模块导出Hunyuan3DDiTPipeline、Hunyuan3DDiTFlowMatchingPipeline两个主类同时导出后处理器FaceReducer、FloaterRemover、DegenerateFaceRemover、MeshSimplifier和图像预处理器ImageProcessorV2等hy3dgen.texgen纹理合成模块导出Hunyuan3DPaintPipeline与Hunyuan3DTexGenConfig。两个 Pipeline 都遵循 diffusers 的使用范式from_pretrained(model_path, ...)加载模型 →pipeline(...)调用推理。模型权重默认从 Hugging Face 的tencent/Hunyuan3D-2仓库按需下载并缓存到本地首次运行后即可离线加载。2. Shape 生成Hunyuan3D-DiT 的最小调用文档给出的最小可用示例如下输入一张图片输出一个trimesh对象from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(tencent/Hunyuan3D-2) mesh pipeline(imageassets/demo.png)[0]输出 mesh 是标准的 trimesh 对象文档原文指向其官方文档可以直接保存为 glb/obj 等格式mesh.export(demo.glb)2.1 from_pretrained 的关键参数from_pretrained定义在 hy3dgen/shapegen/pipelines.py签名与默认值如下参数默认值说明model_path-模型仓库名或本地路径如tencent/Hunyuan3D-2devicecuda推理设备dtypetorch.float16权重精度use_safetensorsTrue是否以 safetensors 格式加载权重variantfp16权重变体加载model.fp16.safetensorssubfolderhunyuan3d-dit-v2-0仓库中 shape DiT 模型所在子目录其中subfolder决定了实际加载的模型默认hunyuan3d-dit-v2-0是单视角模型若加载多视角模型Hunyuan3D-2mv应指定subfolderhunyuan3d-dit-v2-mv可参考 examples/shape_gen_multiview.py。2.2 推理调用参数详解Hunyuan3DDiTFlowMatchingPipeline.__call__的完整签名pipelines.py及其默认值参数默认值说明image-支持路径字符串、路径列表、PIL.Image多视角模型支持{front: ..., left: ..., back: ...}字典num_inference_steps50采样步数timesteps/sigmasNone自定义时间步/噪声调度flow matching 下默认用np.linspace(0, 1, num_inference_steps)guidance_scale5.0无分类器引导CFG强度设为负数则关闭generatorNone随机数生成器如torch.manual_seed(12345)用于结果可复现box_v1.01表面提取时包围盒半径归一化空间octree_resolution384自适应八叉树提取的分辨率决定网格精度mc_level0.0marching cubes 的等值面水平num_chunks8000体素网格分块大小显存不足时调小mc_algoNone表面提取算法已废弃改用pipeline.vae.surface_extractor SurfaceExtractors[algo]()可选mc/dmcoutput_typetrimesh可传latent直接返回潜变量enable_pbarTrue是否显示采样进度条官方 examples/shape_gen.py 展示了典型的生产调用对 RGB 图片先用BackgroundRemover去背景再传入 pipelinefrom hy3dgen.rembg import BackgroundRemover from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline from PIL import Image import torch image Image.open(assets/demo.png).convert(RGBA) rembg BackgroundRemover() image rembg(image) # 去除背景 pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( tencent/Hunyuan3D-2, subfolderhunyuan3d-dit-v2-0, variantfp16 ) mesh pipeline( imageimage, num_inference_steps50, octree_resolution380, num_chunks20000, generatortorch.manual_seed(12345), output_typetrimesh, )[0] mesh.export(demo.glb)2.3 采样流程与显存优化从call实现 可以看到 flow matching 采样的核心循环每步把潜变量按 CFG 复制两份、经 DiT 预测噪声后做线性组合noise_pred uncond scale * (cond - uncond)再由 scheduler 更新样本。若模型自身带 guidance embeddingguidance_embedTrue则不走 CFG 而是把guidance_scale作为条件输入。采样结束后_export将潜变量经 VAE 解码为 SDF 体再调用vae.latents2mesh做八叉树表面提取最终export_to_trimesh翻转面片法向顺序并构造trimesh.Trimeshpipelines.py。针对显存受限场景Pipeline 提供了两种机制实现均移植自 diffusers# 整模型级 CPU offloadconditioner - model - vae 顺序换入换出 pipeline.enable_model_cpu_offload()该类属性model_cpu_offload_seq conditioner-model-vae决定了 offload 顺序pipelines.py。此外enable_flashvdm可替换为 turbo 版 VAE 并启用 FlashVDM 解码加速相关完整示例见 examples/fast_shape_gen_with_flashvdm.py。3. 纹理合成Hunyuan3D-Paint文档中的纹理合成示例——先生成 mesh再为同一张图做纹理烘焙from hy3dgen.texgen import Hunyuan3DPaintPipeline from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline # lets generate a mesh first 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支持subfolder参数默认hunyuan3d-paint-v2-0-turbo还有hunyuan3d-paint-v2-0两个变体映射关系见 Hunyuan3DTexGenConfig。若本地缺少权重会依次尝试HY3DGEN_MODELS环境变量指定的缓存目录默认~/.cache/hy3dgen再回退到 Hugging Facesnapshot_downloadpipelines.py。3.1 Paint 流水线的内部流程从 Hunyuan3DPaintPipeline.call的源码实现可以还原出完整的纹理合成链路图像居中与 delight输入图先经recenter_image裁剪居中再交给Light_Shadow_Remover加载hunyuan3d-delight-v2-0子目录权重去除光照阴影得到中性外观的条件图UV 展开与网格加载mesh_uv_wrap对网格做 UV 展开MeshRender可微分渲染器render_size2048、texture_size2048加载网格多视角条件渲染在 6 个候选相机位姿方位角[0, 90, 180, 270, 0, 180]俯仰角[0, 0, 0, 0, 90, -90]对应权重[1, 0.1, 0.5, 0.1, 0.05, 0.05]见 Hunyuan3DTexGenConfig下渲染法线贴图与位置贴图多视角扩散生成Multiview_Diffusion_Net即 hunyuanpaint 的 UNet diffusers 管线以 delight 图 法线/位置图为条件生成各视角的纹理贴图烘焙与补洞bake_from_multiview将各视角纹理反向投影到 UV 空间按视角权重与余弦因子bake_exp4加权融合merge_methodfast未覆盖区域经texture_inpaint修补最终render.save_mesh返回带纹理网格。4. 进阶用法examples 目录文档最后指出更多高级用法见 examples 目录重点是多视角图片生成 3D和为手工网格handcrafted mesh做纹理生成。结合仓库实际文件examples/shape_gen_multiview.py使用tencent/Hunyuan3D-2mvsubfolderhunyuan3d-dit-v2-mv输入{front: ..., left: ..., back: ...}三个视角图片示例图片见assets/example_mv_images/1/生成一致性更好的多视角模型examples/textured_shape_gen_multiview.py多视角 shape 生成 以 front 视角图做纹理合成的端到端组合examples/textured_shape_gen.py单视角白模 纹理合成的最短链路与文档示例对应examples/fast_shape_gen_with_flashvdm.py、examples/fast_shape_gen_multiview.py基于 FlashVDM 的加速采样examples/shape_gen_mini.py、examples/textured_shape_gen_mini.py小显存mini模型版本。多视角 shape 生成的调用方式与单视角一致只是image参数从单图换成视角字典pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( tencent/Hunyuan3D-2mv, subfolderhunyuan3d-dit-v2-mv, variantfp16 ) mesh pipeline( image{front: front, left: left, back: back}, # PIL.Image 列表或字典 num_inference_steps50, octree_resolution380, num_chunks20000, generatortorch.manual_seed(12345), output_typetrimesh, )[0]5. 模型加载与缓存机制两个 Pipeline 的from_pretrained共享一套加载逻辑。shape 侧由smart_load_modelhy3dgen/shapegen/utils.py实现行为如下先拼接HY3DGEN_MODELS默认~/.cache/hy3dgen 仓库名 subfolder查找本地模型本地不存在时用huggingface_hub.snapshot_download仅下载该subfolder子目录allow_patterns[f{subfolder}/*]节省带宽按variant与use_safetensors拼接权重文件名model.fp16.safetensors或model.fp16.ckpt并加载同目录的config.yaml。因此from_single_file会依据config.yaml中的model/vae/conditioner/image_processor/scheduler五个 target 动态实例化组件pipelines.py。如果你只想调试耗时可设置环境变量HY3DGEN_DEBUG1synchronize_timer会在日志中打印「Model Loading / Encode cond / Diffusion Sampling / Export to trimesh」各阶段耗时utils.py。6. 小结Hunyuan3D-2 的 Python 接入面非常收敛能力入口关键参数单视角 shape 生成Hunyuan3DDiTFlowMatchingPipelinenum_inference_steps、octree_resolution、guidance_scale、generator多视角 shape 生成同上 tencent/Hunyuan3D-2mvimage传 front/left/back 字典纹理合成Hunyuan3DPaintPipelinesubfolderturbo / 标准内部固定 6 视角烘焙加速采样pipeline.enable_flashvdm()turbo VAE FlashVDM 解码显存优化pipeline.enable_model_cpu_offload()组件级 CPU offload以上调用链与参数均与仓库源码一一对应shape 侧核心在 hy3dgen/shapegen/pipelines.py纹理侧核心在 hy3dgen/texgen/pipelines.py端到端脚本可直接参考 examples 目录环境搭建请参见 docs/source/installation/index.md 与 README。【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
