Hunyuan3D-2 Windows 本地部署指南：图片变 3D 模型的一站式教程
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
想把自己的一张图片变成可旋转的 3D 模型，却不想依赖在线服务？想跑起来 Hunyuan3D-2，却被环境依赖和 C++ 扩展编译卡住？这篇 Hunyuan3D-2 本地部署教程带你走完 Windows 上的全部流程。读完本文你将获得：
- 一份可直接照做的 Windows 环境搭建清单（Python、编译器、Python 依赖、C++ 扩展）
- 三种落地方式的可复制命令：Gradio 图形界面、Blender 插件、API 服务
- 一套「快速预览 / 标准质量 / 高细节输出」的参数配置参考
- 编译失败、显存不足等高频问题的排查动作
它是什么：两阶段架构 30 秒速览
这节帮你先建立整体认知，后面所有操作都围绕这套架构展开。Hunyuan3D-2 是腾讯混元系列的高分辨率 3D 资产生成系统，采用「先生成几何、再合成纹理」的两阶段流水线：第一阶段由几何生成模型 Hunyuan3D-DiT 根据条件图产出带细节的裸网格，第二阶段由纹理合成模型 Hunyuan3D-Paint 为生成或手工制作的网格烘焙高分辨率贴图。两个阶段解耦，意味着你可以只跑几何，也可以给已有模型补纹理。核心组件包括：
- Hunyuan3D-DiT：基于流式扩散 Transformer 的几何生成模型，源码见 hy3dgen/shapegen/
- Hunyuan3D-Paint：纹理合成模型，源码见 hy3dgen/texgen/
- 部署入口：gradio_app.py 图形界面、blender_addon.py 插件、api_server.py 后端服务
环境与安装：先装对依赖，后面才不折腾
这节解决的问题是：在 Windows 上跑起来之前，到底要装哪些东西、按什么顺序装。
前置工具清单
- Python 3.10.x，安装时勾选 "Add Python to PATH"
- Visual Studio 2022，安装「使用 C++ 的桌面开发」组件（用于编译 C++ 扩展）
- NVIDIA 显卡 + 对应 CUDA 驱动
- Git
第一步：克隆仓库
git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2第二步：安装 Python 依赖
PyTorch 建议先到官方安装页选择匹配你 CUDA 版本的命令安装，其余依赖一次性装完：
pip install -r requirements.txt pip install -e .requirements.txt 中已包含 diffusers、torch、trimesh、pymeshlab、gradio、onnxruntime、rembg 等核心库。
第三步：编译两个 C++ 扩展（纹理生成必需）
cd hy3dgen/texgen/custom_rasterizer python setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer python setup.py install cd ../../..⚠️ 如果编译时提示找不到
cl.exe或 pybind11，说明当前终端没有加载 MSVC 编译环境：请以管理员身份打开「x64 Native Tools Command Prompt for VS 2022」，重新执行上面的命令；缺 pybind11 则先执行pip install pybind11。
运行与体验：按你的角色选一种方式
这节按人群分层，每种方式都给出启动命令和典型用法，直接照抄即可。
🖱️ 图形界面：新手推荐路径
Gradio 界面提供文本 / 图片 / 多视角三种输入，适合第一次体验。启动标准模型并开启低显存模式：
python gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode启动后浏览器自动打开。关键参数：Octree Resolution（八叉树分辨率）滑块默认 256，越高细节越多、耗时越长；纹理开关勾选后输出带贴图的 GLB 模型。测试图可以直接用仓库自带的 assets/example_images/example_000.png：
多视角模式下可上传前 / 后 / 左 / 右视图，参考素材在 assets/example_mv_images/。
🎬 Blender 插件：专业工作流集成
适合已经在 Blender 里做资产的用户。插件依赖 API 服务，先启动后端：
python api_server.py --host 0.0.0.0 --port 8080然后在 Blender（3.0+）中进入「编辑 > 偏好设置 > 插件」，选择 blender_addon.py 安装并启用，在 3D 视图侧边栏找到 Hunyuan3D-2 面板即可输入提示词或参考图生成，并直接导入当前场景。使用教程见 docs/source/started/blender.md。
🧑💻 API 调用：开发集成
适合把生成能力嵌入自己的应用。服务启动后，向/generate发送 POST 请求即可，参考 docs/source/started/api.md：
img_b64_str=$(base64 -i assets/demo.png) curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{"image": "'"$img_b64_str"'", "texture": true}' \ -o output.glb请求体中常用字段：num_inference_steps（推理步数，默认 5）、guidance_scale（引导尺度，默认 5.0）、seed（种子）、texture（是否生成纹理）。
参数调优：速度、质量、显存的平衡术
这节解决的问题是：不同硬件和场景下，参数到底怎么配。
硬件需求：官方给出的显存参考为——仅几何生成约 6 GB，几何 + 纹理全流程约 16 GB；内存建议 16 GB 起。
| 场景 | 推荐配置 | 预期效果 |
|---|---|---|
| 快速预览 | mini 模型 +--low_vram_mode，Octree 128 | 数分钟出几何，验证提示词是否有效 |
| 标准输出 | 标准模型，Octree 256（界面默认值） | 细节与耗时均衡，日常出图首选 |
| 高细节交付 | 标准模型，Octree 384，增大推理步数 | 细节更丰富，耗时明显增加 |
提速技巧
- 启动时加
--enable_flashvdm配合 Turbo 子文件夹（如--subfolder hunyuan3d-dit-v2-0-turbo），可显著压缩扩散推理时间 - 显存紧张时优先加
--low_vram_mode，或改用tencent/Hunyuan3D-2mini小模型
避坑指南：四个高频问题的标准答案
这节集中回答部署时最容易卡住的几个点。
Q：编译 C++ 扩展时报「cl.exe not found」或链接错误？A：确认当前终端是 VS 2022 的原生工具命令行（管理员身份启动），并且 VS 已装「使用 C++ 的桌面开发」组件；再补装pip install pybind11 ninja后重试。
Q：运行时报 CUDA out of memory？A：先加--low_vram_mode；仍不够就换 mini 模型（--model_path tencent/Hunyuan3D-2mini），并把八叉树分辨率降到 128。
Q：生成的模型没有纹理？A：确认三件事：界面里勾选了纹理生成（或 API 中传了"texture": true）；启动时带了--texgen_model_path；两个 C++ 扩展（custom_rasterizer、differentiable_renderer）都编译成功。
Q：Blender 插件连不上服务？A：先手动访问http://localhost:8080确认 API 服务已在监听（返回非连接失败即可），再核对插件设置里的 API 地址与端口是否一致。
延伸资源：继续深挖的路标
- 入门文档：docs/source/started/index.md，含代码调用、ComfyUI、Gradio 等分册
- API 说明：docs/source/started/api.md
- 提示词库：assets/example_prompts.txt，可直接粘贴进界面测试
- 高级示例脚本（多视角生成、FlashVDM 加速等）：examples/
- 技术报告：assets/report/Tencent_Hunyuan3D_2_0.pdf
- 社区衍生工具：项目 README 中收录了 Windows 整合包、ComfyUI 节点封装等社区扩展，可结合需要查阅
准备好显卡和一杯咖啡，按上面的顺序把环境装好，你的第一个 3D 资产离得很近。
提示：模型权重首次运行时会自动下载，建议在网络稳定时段启动；生成高质量模型时合理设置推理步数与八叉树分辨率，用相同
seed配合不同提示词还能得到风格一致的系列资产。
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
