Hunyuan3D-2 本地部署指南：图片转 3D 模型的完整实战手册

Hunyuan3D-2 本地部署指南图片转 3D 模型的完整实战手册【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2Hunyuan3D-2 是腾讯开源的高分辨率 3D 资产生成系统支持本地部署可完成图片 → 带纹理 3D 模型的生成流程。系统由形状模型 Hunyuan3D-DiT负责几何生成与纹理模型 Hunyuan3D-Paint负责纹理合成两个部分组成输出可直接导入 Blender 的 .glb / .obj 文件。适合希望把 3D 生成能力跑在自己机器上的开发者以及需要为项目批量产出 3D 资产、又不想依赖云端服务的创作者。读完本文你可以完成环境搭建、用一张图片生成一个带纹理的 3D 模型并掌握常用参数的调整方法。一、效果预览输入一张 2D 图片也支持文本、多视角图片系统先生成无纹理的裸网格几何再为网格合成高分辨率纹理图最终输出可从任意角度查看的 .glb 纹理模型。官方效果展示覆盖了角色、动物、日常物品等多种对象几何结构与输入图片高度对齐。 多视角模式下系统接收同一物体的 front / back / left 三张视图示例见assets/example_mv_images/利用多方向信息补全单张图无法覆盖的背面几何结构精度更高。二、环境自查部署前先核对以下配置官方支持 Windows、Linux、macOS 三个平台Windows 下需要 C 编译环境Python推荐 3.10PyTorch 需按 官方说明 对应 CUDA 版本先行安装GPU 显存仅做形状生成约需 6 GB形状 纹理全流程约需 16 GB内存 / 磁盘16 GB 内存、20 GB 可用磁盘空间编译工具链Windows 需 Visual Studio 2022 并勾选C 桌面开发组件Linux / macOS 需标准 C 工具链依赖requirements.txt中的 ninja 与 pybind11最常见的两个环境坑⚠️ 直接从 PyPI 安装 PyTorch 导致版本与本地 CUDA 不匹配 —— 按 PyTorch 官方页面给出的矩阵、选择对应 CUDA 版本安装。⚠️ 编译 C 扩展时报cl.exe not found—— 关闭普通终端改用VS 2022 x64 Native Tools Command Prompt执行编译命令并确认 VS Installer 中已安装 C 桌面开发 workload。三、部署步骤三步完成本地部署第一步获取代码git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2第二步安装 Python 依赖进入项目根目录后安装依赖清单并注册本地包pip install -r requirements.txt pip install -e .第三步编译两个 C 扩展纹理管线依赖custom_rasterizer与differentiable_renderer两个本地编译的扩展在对应目录依次执行安装cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer python3 setup.py install 若只打算做形状生成、不做纹理第三步可跳过Gradio 界面会降级为仅几何输出。四、主使用流程Gradio 界面图片转带纹理 3D 模型最具代表性的场景是单张图片 → 纹理 .glb。启动 Gradio 服务命令较长可分两行执行python gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode输入浏览器打开http://localhost:8080选择图片输入模式上传一张主体清晰、背景简单的图片例如仓库自带示例assets/example_images/example_002.png参数默认参数即可运行低显存保留--low_vram_mode追求速度可将--subfolder换成hunyuan3d-dit-v2-0-turbo并加--enable_flashvdm。输出点击生成后形状推理数分钟纹理合成随后完成完成后可在页面 3D 查看器中旋转检查下载得到的 .glb 文件保留了海豚的体态与蓝色皮肤纹理。其余入口按需选用API 服务运行python api_server.py --host 0.0.0.0 --port 8080 --enable_tex将图片编码为 base64 后 POST 到/generate端点响应直接是 .glb 文件请求体还支持octree_resolution、guidance_scale等参数Blender 插件先启动 API 服务再在 Blender 3.0 中安装blender_addon.py生成的模型可直接进场景代码集成提供 diffusers 风格 APIHunyuan3DDiTFlowMatchingPipeline与Hunyuan3DPaintPipeline两个 pipeline 可直接在 Python 中串联调用多视角生成、Turbo 加速等更完整的写法见 examples/ 目录与官方文档代码篇五、调参与答疑参数速查表参数作用推荐范围--model_path形状模型仓库tencent/Hunyuan3D-2标准/ tencent/Hunyuan3D-2mini轻量显存不足时--subfolder形状模型版本hunyuan3d-dit-v2-0完整/ hunyuan3d-dit-v2-0-turbo蒸馏加速--low_vram_mode模型在 CPU / GPU 间自动换入换出显存 16 GB 及以下建议开启--enable_flashvdm启用 FlashVDM 加速推理与 turbo 模型搭配开启octree_resolution表面提取的八叉树分辨率128默认256越高细节越多guidance_scale对输入条件图片/文本的遵循强度5.0默认10.0高频问题⚠️症状启动时打印Failed to load texture generator界面只能出几何、不出纹理。解法两个 C 扩展未编译成功回到三、部署步骤第三步重新执行若仍报错检查是否缺少 ninja / pybind11 或 C 工具链。⚠️症状纹理生成阶段显存溢出OOM。解法确认已加--low_vram_mode显存低于 16 GB 时先用tencent/Hunyuan3D-2mini只生成几何约 6 GB 显存纹理部分改用 API 服务在空闲时段处理。⚠️症状生成结果几何粗糙、或纹理与输入图片偏差明显。解法将octree_resolution从 128 提高到 256guidance_scale从 5.0 上调至 8.0 左右代价是生成时间变长可先低分辨率快速预览、确认后再出成品。Hunyuan3D-2 把图片输入 → 纹理 .glb 导出的完整链路放在了本地形状与纹理两个模型解耦也允许你对手工制作的网格单独补纹理。部署的主要成本在于一次性编译两个 C 扩展之后所有生成都在本机完成。下一步建议先用轻量组合验证链路 ——python gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini-turbo --low_vram_mode跑通一次完整生成后再换回tencent/Hunyuan3D-2完整模型产出最终资产。【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考