企业官网建设流程全解析

Hunyuan3D-2 安装教程：从克隆到输出带纹理 3D 模型，10 分钟跑通

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

第一次跑 Hunyuan3D-2——这个用单张图片生成带纹理 3D 模型的开源系统——最容易卡住的，是编译光栅化器时弹出fatal error: 'cuda_runtime.h' file not found，或者from_pretrained下权重时长时间没动静。最短路径其实只有三条命令：克隆、装依赖、跑 demo。有 NVIDIA 显卡的话，约 10 分钟能拿到一个 GLB 文件。

跑通：Hunyuan3D-2 最短安装步骤

系统要求

• Linux（Ubuntu 20.04+），Windows 走 WSL2
• NVIDIA GPU + CUDA 11.8/12.1；几何生成约需 6GB 显存，几何+纹理全流程约 24.5GB
• Python 3.10
• 50GB 可用磁盘，其中约 8GB 以上为模型下载

最短安装路径

git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2 pip install torch # 先装 CUDA 版 PyTorch，光栅化器编译依赖 CUDA 头文件 pip install -r requirements.txt # 一次装齐 diffusers、trimesh、gradio 等其余依赖

两个自定义渲染模块需要本地编译，纹理生成离不开它们：

cd hy3dgen/texgen/custom_rasterizer && python3 setup.py install && cd ../../.. # 自定义光栅化器，没有现成 wheel，必须本机编译 cd hy3dgen/texgen/differentiable_renderer && python3 setup.py install && cd ../../.. # 可微渲染器，同样需要本机编译

跑第一次生成：

python3 minimal_demo.py # 首次自动下载约 8GB 权重，最后输出 demo.glb

跑对了的标志：当前目录出现demo.glb，用 Blender 或任意网页 3D 查看器能直接打开。

Hunyuan3D-2 编译报错解决

编译失败几乎都是"torch 不是 CUDA 版"。先确认：

python3 -c "import torch; print(torch.__version__, torch.version.cuda)"

第二行输出None就重装 CUDA 版 torch，再按上面顺序重跑两个setup.py。显存只有 8GB，先用 mini 版跑通流程：

python3 examples/shape_gen_mini.py

⚠️ 仓库是只读的，两个 setup.py 不要改。编译失败时优先检查 torch 版本，缺构建工具则补装 ninja 与 pybind11（pip install ninja pybind11）。

跑顺：Hunyuan3D-2 高频报错与调优

先拿一张官方示例图把几何生成跑起来：

调优建议：

• 模型缓存挪到大盘：export HF_HOME=/data/hf_cache
• 8GB 显存走全流程：--model_path tencent/Hunyuan3D-2mini --low_vram_mode
• 用 Turbo 蒸馏模型提速：--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm

💡 24.5GB 是"几何+纹理"两步合计；只跑几何生成 6GB 显存就够，纹理步骤可单独换机跑。

跑深：按使用场景接入 Hunyuan3D-2

单次出图

适合验证效果、出一两个模型。挑一张单主体图片（仓库 assets/example_images 下就有现成例子）：

python3 examples/shape_gen.py # 只生成几何，输出 demo.glb python3 minimal_demo.py # 几何+纹理全流程

跑对了的标志：目录里出现demo.glb，拖进 Blender 或网页查看器能看到完整纹理。

Gradio 界面操作

适合不想写代码、边调参数边看效果：

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

浏览器打开http://localhost:8080。跑对了的标志：页面显示 Hunyuan-3D-2.0，左侧选一张示例图点生成，右侧 3D 窗口能旋转预览网格。

多视角图输入

适合手里有正、背、侧多角度照片，想要更准的几何：

python3 examples/shape_gen_multiview.py

输入需要四视角图片目录，仓库在 assets/example_mv_images 下备了成套示例。

跑对了的标志：绕到模型背面看，轮廓与输入照片一致，不像单图输入那样脑补变形。

对外提供服务

适合接进自己的 Web 应用或给团队共用：

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

调用方只发 HTTP 请求：

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

跑对了的标志：out.glb直接生成，调用端不需要装任何模型依赖。

延伸资源

• 代码 API 说明：docs/source/started/code.md
• 10+ 使用示例（多视角、FlashVDM 加速）：examples/
• 模型列表（mini/mv/Turbo 各版本与显存需求）：docs/source/modelzoo.md
• API 服务说明：docs/source/started/api.md
• Blender 插件：blender_addon.py，需先启动 API 服务

下一步建议：先用 Turbo 蒸馏版把出图速度拉满，再把 api_server.py 接进你现有的工作流。项目迭代快，新功能和模型版本看 README_zh_cn.md 顶部的"最新消息"部分。

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