企业官网建设流程全解析

如何在10分钟跑通Hunyuan3D-2本地部署：一张图片生成带纹理3D模型的完整指南

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

还在为"把一张图片变成能转着看的3D模型"而折腾一整天吗？找外包建模贵，云端服务既慢又要上传素材。Hunyuan3D-2 就是为解决这个问题而生的：你给它一张图片，它先在本地用 1.1B 的形状生成模型推出几何网格，再用 1.3B 的纹理合成模型贴上图，最终输出一个可直接进 Blender、游戏引擎的 glb 文件。整个过程跑在你自己的显卡上，官方给出的显存门槛很实在——只生成形状约 6GB 显存，形状加纹理全流程约 16GB，一块 RTX 3060 就能完整跑起来。

它的工作方式分两段，这也是后面所有参数的逻辑来源：

第一段 Hunyuan3D-DiT 负责"形"，从图片还原出网格；第二段 Hunyuan3D-Paint 负责"皮"，在网格上合成纹理贴图。两段解耦意味着你可以只跑第一段省显存，也可以给自己手建的模型补纹理。

Hunyuan3D-2 环境要求与依赖安装命令

动手前确认三件事：一张 NVIDIA 显卡（只跑形状 6GB 显存起步，带纹理建议 16GB）、Python 3.10、至少 20GB 磁盘空间——首次运行要下载形状模型和纹理模型的权重，加起来好几个 GB。Windows 用户还需要 Visual Studio 2022 并勾选"使用 C++ 的桌面开发"组件，因为后面要编译两个 C++ 扩展；Linux 有 gcc 即可。注意 PyTorch 要先按官方渠道装好与你 CUDA 版本对应的版本，再执行下面的命令。

# 克隆 Hunyuan3D-2 仓库 git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 # 进入项目根目录 cd Hunyuan3D-2 # 安装 Python 依赖（diffusers、trimesh、gradio 等） pip install -r requirements.txt # 以可编辑方式安装 hy3dgen 核心包 pip install -e .

接着编译纹理阶段依赖的两个 C++ 扩展（光栅化器和可微分渲染器，路径在hy3dgen/texgen/下）。如果你只生成形状、不做纹理，这两步可以跳过：

# 进入自定义光栅化器目录并编译安装 cd hy3dgen/texgen/custom_rasterizer && python setup.py install # 返回项目根目录 cd ../../../ # 进入可微分渲染器目录并编译安装 cd hy3dgen/texgen/differentiable_renderer && python setup.py install # 返回项目根目录 cd ../../../

到这里环境就齐了，代码、依赖、扩展三样都装上了。

一条命令启动 Gradio 界面生成第一个 3D 模型

回到项目根目录，执行：

# 启动 Gradio 界面（默认用 0.6B mini-Turbo 形状模型，速度最快；low_vram_mode 开启显存自动卸载） python3 gradio_app.py --low_vram_mode

首次启动会下载模型权重，等 1~2 分钟后浏览器自动打开界面。界面里上传一张图片，点生成，稍等片刻就能看到网格的 3D 预览，接着可以一键走纹理合成，最后导出 glb、obj、ply、stl 四种格式。

不同显卡和场景，换启动参数即可，核心就是下面几个组合：

多视角模式下，每个视角传一张图即可，仓库里assets/example_mv_images/提供了现成示例，比如这个正面视角：

两个可选开关：--enable_t23d打开文字输入（会额外下载一个文生图模型）；--disable_tex关闭纹理阶段，显存需求降到约 6GB。用 Blender 的话，启动 API 服务后把blender_addon.py当插件装进偏好设置，生成结果直接落到场景里。不想点界面、想写代码调用，examples/ 里是现成脚本，比如shape_gen.py展示了 50 步采样 + 380 八叉树分辨率的完整调用。

动手做一次完整的图片转 3D 示例

下面走一遍 API 路径，把仓库自带的那张海豚图变成带纹理的 glb。它和 Blender 插件底层是同一套接口，也是你以后集成本项目的方式：

# 启动 API 服务，监听 8080 端口并开启纹理阶段 python api_server.py --host 0.0.0.0 --port 8080 --enable_tex # 读取海豚示例图片并编码为 base64（macOS 上把 -w 0 换成 -i） img_b64=$(base64 -w 0 assets/example_images/example_002.png) # 发送生成请求：256 八叉树分辨率、带纹理，结果保存为 output.glb curl -X POST "http://localhost:8080/generate" -H "Content-Type: application/json" -d "{\"image\": \"$img_b64\", \"texture\": true, \"octree_resolution\": 256}" -o output.glb

等几分钟后output.glb就出来了，用任意 glb 查看器打开，从海豚侧面和腹部看纹理是否完整。请求体还支持这些字段：seed固定随机种子、num_inference_steps控制采样步数（默认 5）、guidance_scale控制对输入图的贴合度（默认 5.0）、face_count限制纹理阶段保留的面数（默认 40000）、type指定导出格式。想改成纯文字驱动，把image换成text字段并让服务端开启文生图即可。

Hunyuan3D-2 参数怎么调、常见坑怎么避

调参就围绕三对矛盾：细节、速度、显存。常用的参数和推荐值如下：

调参套路：先用octree_resolution 128+ 少步数快速看轮廓对不对，满意后再用 256 以上出成品，比每次等完整生成快得多。

💡 首次运行下载权重慢的话，给终端设置一个国内的 HuggingFace 镜像环境变量再启动，之后权重会缓存在本地，不用重复下载。

最后集中说三个最常见的坑，都是"一句现象 + 一句解法"：

• 启动时打印 "Failed to load texture generator / Please try to install requirements by following README.md"：两个 C++ 扩展没编译成功，回到安装一节重跑setup.py install，或临时加--disable_tex先用形状功能。
• 生成中途报 "CUDA out of memory"：加--low_vram_mode；还不行就--disable_tex只出形状，或把octree_resolution降到 256 以下。
• Windows 上编译扩展报 "Microsoft Visual C++ 14.0 is required"：在 Visual Studio Installer 里补装 C++ 桌面开发组件，然后从开发者命令提示符里重新编译。

更多参数细节可以翻 docs/ 下的 gradio、api、blender 使用文档。现在就做你的第一个小实验吧：打开 Gradio 界面，把assets/example_images/example_002.png这张海豚图丢进去，跑完形状和纹理后导出 glb，然后对比手里的 2D 原图，看看它还原得怎么样。

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