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-2

想把客户发来的一张海豚图放进游戏场景，传统建模要排一整周的期。Hunyuan3D-2 是腾讯开源的 3D 资产生成系统：一张图片、甚至一段文字描述，都能变成带纹理的高分辨率 3D 模型，且全部计算跑在你自己的电脑上。读完本文，你能在本地搭好运行环境、完成第一次图生 3D，并把它接入 Blender 或自己的应用。

01 先形状后纹理：一条管线里的两个模型

Hunyuan3D-2 把 3D 生成拆成两段：第一段由 Hunyuan3D-DiT 负责，它从输入条件里推断几何结构，输出一张"裸网格"；第二段交给 Hunyuan3D-Paint，借助几何与扩散先验，给这张网格铺上高分辨率贴图。拆开的好处是每一步只解决一件事，而且 Paint 的纹理合成不挑来源——手工雕刻的网格同样能上色。技术细节可以看 技术报告 PDF，各变体模型的规模与定位整理在 模型清单 里。

显存方面，纯形状生成约需 6GB，形状加纹理全流程约需 16GB。也就是说中端卡跑几何没问题，真正把显存吃满的是纹理环节。

02 本地环境三步走：克隆、依赖、两个 C++ 扩展

动手前先对一遍环境要求：Windows 10/11 64 位（Linux、macOS 也可用）、Python 3.10.x（3.10.9 较稳）、NVIDIA 显卡且显存 ≥6GB、16GB 内存。Windows 用户额外要装 Visual Studio 2022 的"使用 C++ 的桌面开发"workload——项目里有两个纹理相关的 C++ 扩展必须现场编译，缺编译器时安装报错。

1️⃣克隆代码并安装依赖（国内网络慢可给 pip 加镜像源）：

git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2 pip install -r requirements.txt pip install -e .

2️⃣编译两个纹理扩展：custom_rasterizer（自定义光栅化器）和 differentiable_renderer（可微分渲染器），各自目录里都有 setup.py，按顺序执行即可：

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

💡 编译时报cl.exe not found，说明当前终端里没有编译器环境。关掉终端，从开始菜单启动 VS2022 自带的 "x64 Native Tools Command Prompt"，再重跑上面的命令。

03 Gradio 界面的三种用法：文字、单图、多视角

对新手最友好的入口是 Gradio 网页界面。第一次跑建议从 0.6B 的轻量模型开始，一条命令启动：

python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode

启动后浏览器自动弹出页面，共三种输入方式：

• 文字描述：输入"一个黄色的香蕉，带有自然纹理"这类句子，模型从文本直接推断形状
• 单张图片：上传一张照片即可。assets/example_images/ 里备了几十张现成的测试图，比如这根香蕉：

• 多视角图片：上传物体前、后、左几张不同角度的照片，重建的几何更准。assets/example_mv_images/ 下有 14 组三视角样例，其中一组的正面图：

想换主力 1.1B 模型，把--model_path改成tencent/Hunyuan3D-2、--subfolder改成hunyuan3d-dit-v2-0；追求速度就用 Turbo 蒸馏版（--subfolder hunyuan3d-dit-v2-0-turbo并追加--enable_flashvdm）。更多组合写法可以参考 examples 目录。

拿项目自带的小海豚走一遍完整流程：

上传这张图后等 6-8 分钟，输出是一个可任意角度旋转查看的 3D 模型，海豚的体态和蓝色皮肤纹理都被保留下来。

04 接入现有工作流：Blender 插件与 API 服务两条路

已经在 Blender（3.0+）里干活的话，直接装插件：菜单"编辑 > 偏好设置 > 插件"，点"安装"并选择项目根目录的 blender_addon.py，启用后 3D 视图侧边栏会出现 "Hunyuan3D-2 3D Generator" 面板，支持文字、图像输入与纹理生成，产出直接落进当前场景。注意插件本身不跑模型，它靠调用 API 服务，所以得先把服务端拉起来。

要把 3D 生成嵌进自研应用，走 API 服务：

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

起来之后发 POST 请求，图片 base64 进、.glb 文件出：

img_b64_str=$(base64 -i assets/example_images/example_002.png) curl -X POST "http://localhost:8080/generate" -H "Content-Type: application/json" \ -d '{"image": "'"$img_b64_str"'"}' -o output.glb

接口的更多字段说明见 API 文档。

05 显存不够怎么配：三档方案加参数参考

按显卡档位挑一套启动参数：

• 高性能档（RTX 4070 及以上）：--fp16开半精度，显存大约省一半；--flashvdm开 FlashVDM 加速，速度快约三成；--resolution 384出最终质量
• 平衡档（RTX 3060/3070）：--resolution 256 --steps 30，标准质量，速度质量都居中
• 入门档（GTX 1660/RTX 2060）：--model_path tencent/Hunyuan3D-2mini --resolution 128，用轻量模型换"跑得起来"

💡 一个省算力的习惯：先用 128 低分辨率快速预览，形态满意了再上 256 以上重出成品，避免反复烧显存。

从克隆代码到第一次图生 3D，再到接进 Blender 和自研服务，这条链路到这里已经通了。现在就动手：用第 03 节的 mini 模型命令启动 Gradio 界面，丢进assets/example_images/里那张香蕉图，5 分钟后你就能拿到自己生成的第一个带纹理 3D 模型。

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