图片转3D模型完整教程：Hunyuan3D-2 本地部署与首次生成上手
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
手里有一张角色插画，想把它变成能直接丢进游戏场景的带纹理 3D 模型？Hunyuan3D-2 做的就是这件事：输入一张图片（或一段文字描述），它输出一个可编辑的 glb 模型。本文带你在一台带 NVIDIA 显卡的电脑上完成 Hunyuan3D-2 本地部署，从克隆仓库到跑通第一次图片转 3D，全程给出可复制的命令。
环境门槛：本地部署 Hunyuan3D-2 前的硬件与系统要求
先核对你的机器是否达标，避免装到一半才发现跑不动：
| 项目 | 最低要求 | 推荐配置 | 不满足时的替代方案 |
|---|---|---|---|
| GPU 显存 | 6 GB（仅生成形状） | 16 GB（形状 + 纹理全流程） | 显存不足时改用 Hunyuan3D-2mini 模型并关闭纹理生成 |
| 操作系统 | macOS / Windows / Linux | 三端均官方支持 | 无替代，跨平台运行 |
| Python | 3.10.x | 3.10.9，配合虚拟环境 | 装依赖前先用python -m venv venv建环境 |
| 磁盘空间 | 10 GB 可用 | 20 GB（存放多组模型权重） | 只保留 mini 系列权重可省一半空间 |
⚠️ 注意：显存数据来自仓库官方说明——"6 GB VRAM for shape generation and 16 GB for shape and texture generation in total"。8 GB 显存的卡建议全程带--low_vram_mode参数。
从克隆仓库到编译完成的部署主线
部署共四步：拉代码 → 装依赖 → 编译两个 C++ 扩展。前两步装 Python 依赖，后两步只在你需要纹理生成（给模型"上色"）时才必须执行。
第一步，克隆仓库并进入目录。执行后终端不会输出内容，目录切换成功即可：
git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2第二步，安装 PyTorch 与 Python 依赖。PyTorch 需按你的 CUDA 版本从 PyTorch 官网单独安装（仓库未锁定版本），其余依赖一条命令装完，随后把项目本身以可编辑模式装入环境。预期看到一行行Successfully installed ...：
pip install -r requirements.txt pip install -e .第三步，编译自定义光栅化器（custom rasterizer，负责把 3D 网格渲染成 2D 图供纹理模型参考）。编译成功后终端无报错、扩展装进当前 Python 环境，然后退回项目根目录：
cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../..第四步，编译可微分渲染器（differentiable renderer，纹理生成时对渲染结果求梯度用）。命令结构与上一步一致：
cd hy3dgen/texgen/differentiable_renderer python3 setup.py install cd ../../..💡 小贴士：这两步依赖 C++ 编译工具链（requirements 里已包含 ninja 和 pybind11）。Windows 上需要 Visual Studio 2022 的 C++ 桌面开发组件；Linux 上确保有 g++。只用形状生成、不上色的话，这两步可以跳过。
三种使用入口：网页界面、Blender 集成与 API 调用
新手：Gradio 网页界面
最省事的入口。启动后浏览器自动打开 Gradio 页面，左侧选输入模式，右侧调参数并生成：
python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 \ --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode界面默认带纹理生成；只想看速度可加--disable_tex，想再快就换 turbo 子文件夹--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm。首次启动会从 Hugging Face 自动下载模型权重（模型名tencent/Hunyuan3D-2），需要联网，耐心等待进度条走完。
进阶：Blender 插件
先启动一次 API 服务（插件通过它通信）：
python api_server.py --host 0.0.0.0 --port 8080然后在 Blender 中：编辑 → 偏好设置 → 插件 → 安装，选择项目根目录下的blender_addon.py，启用后就能在 Blender 侧边栏面板里直接发起生成，结果自动导入当前场景。
开发者：API 服务调用
不想维护长连接或想批量跑任务时，直接用 HTTP 接口。服务启动命令同上（注意api_server.py的默认端口是 8081，README 示例中用--port 8080显式指定）。请求体把图片转成 base64 放进 JSON：
img_b64_str=$(base64 -i assets/demo.png)再发送 POST 请求，返回的响应体就是 glb 文件本身：
curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{"image": "'"$img_b64_str"'"}' \ -o test2.glbJSON 里还可传"texture": true开启纹理、"octree_resolution"、"num_inference_steps"、"guidance_scale"调整生成效果。如果你要写脚本而非调 HTTP，代码 API 只有几行：
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(image='assets/demo.png')[0]mesh是 trimesh 对象，可直接mesh.export('out.glb')。
效果与原理：文字和图片转 3D 模型实测
文字模式：一段描述生成卡通角色
启动 Gradio 时加--enable_t23d开启文本入口，输入assets/example_prompts.txt里的提示词（如 "a lovely rabbit eating carrots"）即可得到带纹理的卡通角色：
图片模式：一张照片转可渲染模型
上传图片后点生成，等待进度条结束即可导出 glb。用仓库自带的示例图assets/example_images/075.png生成的人物雕塑：
多视角模式同样支持：把物体的前、左、后三张视图（仓库assets/example_mv_images/下有 14 组示例）一起上传，几何还原更准。
两阶段架构：先形状后纹理
Hunyuan3D-2 是两阶段流水线：形状模型 Hunyuan3D-DiT（基于 flow matching 的扩散 Transformer）把条件图片对齐成网格几何；纹理模型 Hunyuan3D-Paint 再为网格合成高分辨率贴图。形状与纹理解耦，所以它既能给自动生成的网格上色，也能为你手工做的网格生成纹理。
参数调优：按硬件选择参数组合
下表组合均取自仓库真实参数（耗时为本地参考值，随机器波动）：
| 硬件 | 推荐参数组合 | 预估耗时 | 质量 |
|---|---|---|---|
| 16 GB 显存以上 | tencent/Hunyuan3D-2+--subfolder hunyuan3d-dit-v2-0+ Octree Resolution 256 | 5-10 分钟 | 高 |
| 8-12 GB 显存 | 同上 +--low_vram_mode | 5-10 分钟 | 高（略慢） |
| 6 GB 显存 | --model_path tencent/Hunyuan3D-2mini+--low_vram_mode | 3-6 分钟 | 中 |
| 追求速度 | --subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm | 大幅缩短 | 中 |
三个关键参数（Gradio 界面均有对应滑条）：
- Octree Resolution：网格细节精度，默认 256，范围 16-512，调高更精细但更吃显存。
- Steps（推理步数）：默认 50，越多越稳但越慢。
- Guidance Scale（引导强度）：默认 7.5，调高让结果更贴近输入图，调低更有随机性。
问题排错：显存不足、编译失败等高频故障直答
Q：生成时报 "CUDA out of memory"？按优先级依次尝试：加--low_vram_mode启动 → 换成--model_path tencent/Hunyuan3D-2mini→ 去掉纹理（Gradio 加--disable_tex，API 请求不传"texture"）。
Q：编译两个 C++ 扩展时报cl.exe not found？Windows 上以管理员身份运行 "x64 Native Tools Command Prompt for VS 2022"，在其中重新执行python3 setup.py install；确认 VS 2022 装了 C++ 桌面开发组件。Linux 上则是缺 g++，装上再试。
Q：生成太慢，想快速出图？启动参数换成--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm，这是官方蒸馏出的 Turbo 权重 + FlashVDM 加速。
Q：纹理发糊、几何细节不够？界面里把 Steps 调到 50 以上、Guidance Scale 提高到 7.5-10、Octree Resolution 保持 256 起步；API 中对应"guidance_scale"与"octree_resolution"字段（默认分别为 5.0 和 128，偏低）。
Q：API 请求返回 404 或 JSON 错误？确认服务真的在跑的端口上——api_server.py默认端口 8081，而示例请求发到 8080，两边要一致；另外"image"字段必须是 base64 字符串，缺图或格式错误会返回error_code: 1。
延伸阅读：官方文档、示例代码与模型来源
- 入门文档：docs/source/started/（代码、Gradio、API、Blender、ComfyUI 各有一篇）
- 官方文档首页：docs/source/index.md
- 进阶示例（多视角转 3D、给手工网格上色等）：examples/
- 端到端最小脚本（形状 + 纹理完整流程）：minimal_demo.py
- 文本模式示例提示词：assets/example_prompts.txt
- 模型权重来源与规格：docs/source/modelzoo.md
- 技术报告 PDF：assets/report/Tencent_Hunyuan3D_2_0.pdf
结语
到这里，你的机器上已经有一套能出活的本地图片转 3D 工具。下一步建议：随便找一张边缘干净的单物体图（手办、玩偶、道具都合适），丢进 Gradio 的图片模式，用默认参数跑一次并导出 glb。拿到模型后拖进 Blender 或任何 3D 查看器里转一圈，再决定是否需要调 Octree Resolution 或换 Turbo 子文件夹提速——多跑两次，参数的手感就来了。
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
