Hunyuan3D-2 部署零基础上手：本地还是云端？一张决策表选对部署路径-编程实验室

Hunyuan3D-2 部署零基础上手：本地还是云端？一张决策表选对部署路径

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

Hunyuan3D-2 能把一张图变成高分辨率的 3D 资产，先生成几何、再合成纹理。这篇文章带你把 Hunyuan3D-2 部署走完全程：先帮你在本地与云端之间做选择，再按分支一步步落地，最后给排错清单，不用来回翻文档。

先对号入座：我该用本地还是云端？

Hunyuan3D-2 是两阶段流程：Hunyuan3D-DiT 出几何，Hunyuan3D-Paint 合成纹理，两阶段都很吃 GPU 显存，这也是部署选型难的原因。

用下面四条逻辑对号入座：

每周只用几次、对成本敏感 → 云端部署，按需开 GPU 实例，用完即关，按小时计费。
每天开发、调试、调参超过 4 小时 → 本地部署，一次性买显卡，电费摊薄后远比按小时付费划算。
团队要共用一个图生 3D 入口 → 云端部署 + 容器化，把能力暴露成 API。
手里没有 NVIDIA 显卡 → 直接云端部署，本地这条路走不通。

还有一条隐性标准：本地部署要亲手编译两个 CUDA 依赖，没折腾过 C++ 扩展的人容易卡住；云端可以把这些全藏进镜像里。

路径 A：本地落地，从硬件到第一个 glb

硬件清单：8GB 显存到底够不够

够，但只够跑精简版。完整流程（几何 + 2K 纹理）建议 16GB 起步，推荐配置：

GPU：最低 8GB 显存（只能跑 mini），推荐 RTX 3090/4090 的 24GB
内存：32GB
磁盘：100GB 空闲（模型权重 + 缓存）
系统：Ubuntu 20.04/22.04，或 Windows + WSL2

装依赖：三步走，两步是 CUDA 编译

先按官网指引装对应 CUDA 版本的 PyTorch，版本号必须和系统 CUDA 对齐，否则后面编译全失败。然后一条命令装主依赖：

pip install -r requirements.txt

这一行会装好 diffusers、trimesh、gradio 等主依赖。真正的坑在纹理环节的两个自编译组件。先编译自定义光栅化器：

cd hy3dgen/texgen/custom_rasterizer python3 setup.py install

再编译可微分渲染器，它是 CUDA C++ 内核，不编译纹理管线完全跑不起来：

cd ../../differentiable_renderer python3 setup.py install

⚠️ 遇到 CUDA 版本不匹配报错，唯一解法就是让系统 CUDA 和 PyTorch 的编译版本保持一致，CUDA 11.8 是最稳的选择。

上面要编译的两个组件都在架构图右侧的纹理合成环节里，本地部署的麻烦基本都出在这里。

拉权重与验证：首次运行自动下载

克隆项目代码：

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

模型权重不用单独下载，首次加载 pipeline 时会自动从 tencent/Hunyuan3D-2 拉取，总共几个 GB，耐心等第一次。

然后用最小化演示脚本验收，它走完整条链路：读入示例图 → 抠背景 → 生成几何 → 合成纹理 → 导出 demo.glb：

python minimal_demo.py

✅ 脚本跑完没报错、当前目录出现 glb 文件，本地部署就算完成，拿 Blender 打开检查即可。更完整的参数写法可以看 examples/shape_gen.py，minimal_demo.py 里还包含文生 3D 的用法。

输入图有讲究：主体清晰、背景干净出效果最好，背景杂乱就依赖自动抠图，容易翻车。

路径 B：云端落地，容器化是主线

云端最省钱的 GPU 实例怎么挑

别看实例型号，只看两个数字：显存 24GB 以上（A10 级别，跑完整管线）；16GB（V100/T4）也能跑，但纹理分辨率别拉太高。成本参考：A10 级别每小时 10 元人民币上下，V100 每小时 3 美元出头。日均使用不到 4 小时的话，云端比本地更省。

Docker 部署：镜像分三块写

基础镜像选带 CUDA 工具链的 devel 版，版本和本地编译保持一致：

FROM nvidia/cuda:11.8.0-cudnn8-devel-ubuntu22.04 WORKDIR /app COPY . /app

依赖编译放进构建阶段，两个最易出错的 setup.py 在镜像里一次搞定，以后开机不再碰编译：

RUN pip install -r requirements.txt && \ cd hy3dgen/texgen/custom_rasterizer && python setup.py install && \ cd ../../differentiable_renderer && python setup.py install

启动指令直接指向 Gradio 界面，绑定 0.0.0.0 保证容器外可访问：

CMD ["python", "gradio_app.py", "--server-name", "0.0.0.0"]

构建并启动容器：

docker build -t hunyuan3d-2 . docker run --gpus all -p 7860:7860 hunyuan3d-2

⚠️--gpus all漏掉的话容器看不到 GPU，进程要么直接报错要么退回 CPU，速度慢几百倍。

支线：把图生 3D 暴露成 API 给团队用

想多人共用这台云端机器，就把启动入口换成 API 服务器：

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

客户端核心就三行：

import requests, base64 r = requests.post("http://<服务器IP>:8080/generate", json={"image": base64.b64encode(open("in.png","rb").read()).decode()}) open("out.glb","wb").write(r.content) # 需要纹理时在 json 里加 texture 参数

记得在云厂商安全组里放行 8080 端口，不然 0.0.0.0 绑了也白绑。

跑起来之后：界面与 Blender 集成一次讲完

Gradio 界面是新手最友好的入口：

python gradio_app.py

浏览器打开 http://localhost:7860，图像输入和文本生成都支持，步数、分辨率等参数可以实时调。如果你平时主力是 Blender，可以完全绕开网页：先起 API 服务器，再在 Blender 里 Edit > Preferences > Add-ons > Install，选 blender_addon.py，填好 API 地址，直接在视口里调起图生 3D，不用浏览器和 DCC 之间来回切换。

报错急救包：六个高频故障

症状	原因	一行解
setup.py 编译失败，找不到 nvcc	缺 CUDA 工具链	`sudo apt install nvidia-cuda-toolkit`后重装 PyTorch
编译报 CUDA 版本不匹配	系统 CUDA 与 PyTorch 版本错位	换 CUDA 11.8 编译版的 PyTorch，两端对齐
权重下载卡死	Hugging Face 连接不稳定	`export HF_ENDPOINT=https://hf-mirror.com`后重试
CUDA out of memory	完整模型超出显存	换精简版：`python examples/shape_gen_mini.py`
几何正常但纹理发黑	可微分渲染器没编译	回头重跑上面两个 setup.py
云端 API 访问不通	绑定地址或安全组没放通	启动加`--host 0.0.0.0`并在安全组开端口

收尾：一句话选型

日均使用超过 4 小时选本地，偶尔用或团队共享选云端，没有 GPU 就只剩云端。

部署跑通后，三个值得接着做的方向：

提速：用 FlashVDM 加速采样，看 examples/fast_shape_gen_with_flashvdm.py，几何生成能从分钟级压到秒级。
多视角输入：手上有同一主体前、侧、背多张图时，用 examples 目录下的多视角样例，形状一致性明显更好。
工作流整合：把 Hunyuan3D-2 接进 ComfyUI 的 3D 生成工作流，和现有出图管线串起来用。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考