企业官网建设流程全解析

Hunyuan3D-2 本地部署指南：从文字和图片到 3D 模型的完整实操路径

【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2

Hunyuan3D-2 是腾讯开源的 3D 模型生成工具：输入一段文字描述或一张图片，它直接输出可用的 3D 资产，不需要建模经验。本文带你完成一次完整的本地部署，从装环境、编译 C++ 扩展，到在 Gradio 界面生成第一个模型，最后按硬件调参数，让出图质量和速度都达到你的预期。

先看它能做什么：两阶段生成 3D 模型

先看效果。Hunyuan3D-2 能产出多种风格的 3D 资产：卡通角色、建筑场景、文物复刻、奇幻生物，这条管线都覆盖。

底层机制是两阶段流水线，记住这两个词后面就会反复出现：

• 形状生成：Hunyuan3D-DIT（去噪 Transformer）把文字或图片输入转换成 3D 形状；
• 纹理合成：Hunyuan3D-Paint 给形状贴上精细纹理，让模型看起来真实。

两个阶段全部跑在你的本地显卡上，不依赖外部推理服务。接下来的内容，就是让这条管线在你机器上跑起来。

🧩 把环境配好：装依赖并编译 C++ 扩展

这一节完成本地部署的全部前置工作。做完之后，你的机器上有了完整项目代码、装好的 Python 依赖和编译好的两个 C++ 扩展，后续所有命令可以直接执行。

检查硬件与系统配置

先核对配置是否达标；确认后就可以继续往下做，显卡不达标的话，后面生成会明显变慢甚至爆显存。

克隆仓库并安装 Python 依赖

这一步的目标是把项目代码和全部 Python 依赖弄到本机，完成后你可以在Hunyuan3D-2目录下直接运行后续命令。先把仓库克隆到本地：

git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2

再用项目自带的依赖清单安装全部 Python 库：

pip install -r requirements.txt

提示：pip 报依赖冲突时别硬装，先建虚拟环境再装一遍：

python -m venv venv venv\Scripts\activate pip install -r requirements.txt

编译两个渲染器，完成 C++ 扩展构建

纹理管线依赖两个 C++ 扩展，必须本地各编译一次，否则开启--enable_tex后界面会报错。先编译自定义光栅化器：

cd hy3dgen/texgen/custom_rasterizer python setup.py install cd ../../..

再编译可微分渲染器：

cd hy3dgen/texgen/differentiable_renderer python setup.py install cd ../../..

提示：报 "cl.exe not found" 说明当前命令行不在 VS 构建环境里。以管理员身份打开 "x64 Native Tools Command Prompt for VS 2022"，在里面重跑上面两条编译命令即可。

🎬 生成第一个模型：走一遍 Gradio 界面

本节的目标是打开可视化界面并生成第一个 3D 模型。完成后你会得到一个可下载、可在任意 3D 查看器里打开的 GLB 文件。执行下面的命令启动 Gradio 界面，--enable_tex打开纹理生成：

python gradio_app.py --enable_tex

命令执行完浏览器会自动打开操作页面，界面提供三种输入方式。

文本生成 3D：一句话出一个模型

最简单的入口：在输入框里打一句话，就能出模型。比如输入"一座蓝色屋顶的卡通风格小房子"，对应的 3D 房子就出来了：

图片转 3D：一张图变成 3D 资产

这一模式只需要一张图片，生成完成后得到与之对应的 3D 模型。项目自带一批示例图，都在assets/example_images/目录下，任选一张上传就能试。下面就是用示例图生成的卡通角色，表面细节清晰：

多视角融合：多传几张视图，结构更准

手头有同一物体的多张图时，用这个模式。完成后得到的结构比单图生成更准确：把该物体的前、后、左、右等不同角度视图一起传上去，系统会融合多视角信息来重建结构。assets/example_mv_images/里有多组现成的多视角示例图可用：

选一条适合你的工作流：Blender 插件或 API 集成

接下来两条路按身份二选一：日常用 Blender 建模的，走插件；要把 3D 生成嵌进自己产品的，走 API。

用 Blender 插件集成 Hunyuan3D-2

插件让你直接在 Blender 里生成，结果会自动导入当前场景，方便接着编辑。要求 Blender 3.0 以上版本，安装步骤很短：

1. 打开"编辑 > 偏好设置 > 插件"；
2. 点"安装"，选中项目根目录里的blender_addon.py；
3. 启用插件，在 3D 视图侧边栏就能找到 "Hunyuan3D-2 3D Generator" 面板。

之后在 Blender 里用文字或图片生成，和 Gradio 界面里的操作一致，只是结果直接落在场景里。

启动 API 服务，把 3D 生成嵌进自己的应用

想把 3D 生成能力集成进自己的应用，就走服务路线。启动后，任何脚本和工具都能调用这个本地服务。先启动 API 服务并开启纹理生成：

python api_server.py --host 0.0.0.0 --port 8080 --enable_tex

再用任意 HTTP 客户端发请求即可。下面这条 curl 命令把本地图片编码后上传，生成结果直接存为 GLB 文件：

# 把图片读进来并编码为 base64 img_b64_str=$(base64 -i assets/demo.png) # 发送生成请求，结果写入 output.glb curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{"image": "'"$img_b64_str"'", "texture": true}' \ -o output.glb

⚡ 参数调优：按显卡档位选参数组合

同一套模型在不同硬件上，速度和质量差别很大。这一节做两件事：先按显卡档位选参数组合，再解释两个影响细节和匹配度的高级参数。

按显卡档位选参数组合

先在下面的表格里找到自己的显卡，直接抄对应的参数组合，就能在速度和画质之间取到平衡：

高级参数：细节精度与提示词匹配度

基础组合确定后，还可以微调两个参数：

• --octree_resolution：控制模型细节精度，默认 256。数值越高细节越丰富，但内存占用也越大；
• --guidance_scale：控制结果与输入描述的贴合程度，建议范围 5.0-10.0。数值越高匹配度越高，但结果的多样性会降低。

两个可复现案例：文物数字化与原创角色

两个都能照着跑的例子。按下表给出的设置执行，即可复现对应效果。

案例一：把雕塑图片变成 3D 模型

拿一张雕塑照片，做成可展示的 3D 资产：

• 输入：一张雕塑图（项目自带assets/example_images/075.png可以直接用）；
• 关键设置：Gradio 界面选"图像模式"并上传图片；推理步数 30、分辨率 256、开启纹理生成；
• 输出效果：形态一致的 3D 模型，全程约 5 分钟。

案例二：用文字生成原创卡通角色

不用任何参考图，一句话生成原创角色：

• 输入：文字描述"穿着龙年服饰的卡通企鹅，黄色主体，红色装饰，可爱风格"；
• 关键设置：选"文本模式"，其余参数保持默认；
• 输出效果：一只穿着龙年服饰的卡通企鹅 3D 模型。

🧯 常见坑排障表：三列对照排查

遇到问题先查这张表，对着现象找原因和解决办法：

下一步：继续探索

到这里，Hunyuan3D-2 的本地部署、三种输入模式和参数调优都过了一遍，日常使用够用。想深入的话，从这两处继续：

• 官方文档：docs/source/index.md
• 示例代码：examples/

模型权重会在首次启动时自动下载，保持联网即可。

【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2