企业官网建设流程全解析

Hunyuan3D-2实操教程：从单张图片到带纹理3D模型，4步产出第一个模型

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

建模组需要把一张产品渲染图变成能导入Blender调整纹理的3D模型。本文在CUDA显卡上跑通Hunyuan3D-2图像生成3D全流程：装好环境、编译渲染模块、跑通首个.glb文件，完成即算达标。

先跑起来

下面是最短的3步安装路径，跑通后直接执行示例脚本、拿到demo.glb即算通过。

第1步：拉取代码。

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

第2步：安装依赖。先按官方指引安装CUDA版PyTorch，再装其余依赖：

pip install -r requirements.txt pip install -e .

第3步：编译两个渲染模块。仅纹理流水线需要，只做几何生成可跳过：

cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer python3 setup.py install cd ../../..

首次运行会自动下载模型权重，第一次启动耗时较长属正常现象。

它是怎么工作的

Hunyuan3D-2是一个两阶段的图像生成3D系统：先产出无纹理的几何网格，再给这个网格贴出高分辨率贴图。网格（mesh）就是用三角形拼出的物体表面，是Blender等3D软件的通用表示，两阶段各自的输出都能单独拿去用。

第一阶段Hunyuan3D-DiT（1.1B参数）基于流匹配扩散模型，从一张或多张图片推断物体的三维形状，默认推理50步；第二阶段Hunyuan3D-Paint（1.3B参数）把参考图上的颜色和材质投影到网格上，它不依赖生成几何，直接给手工建模的模型上色也行。官方基准里CMMD几何细节指标3.193、纹理FID 282.429，均优于对比的开源与闭源模型，数值见README.md的Performance小节。

这种主体清晰、背景干净的单图是最标准的输入。显存方面：几何阶段约6GB，两阶段全跑共16GB。

核心用法

这一节按三个典型场景给出最小可运行示例：单图片、多视角图片、文字提示与低显存界面。

用单张图片生成带纹理的3D模型

两阶段管线用几行代码串起来，输出是trimesh对象，调用export即可存成glb/obj等格式。

• 输入图建议用透明背景的RGBA格式；RGB图先抠背景，写法见examples/shape_gen.py。
• 几何与纹理各用一个Pipeline类，从同一个模型库加载。
• num_inference_steps=50、octree_resolution=380控制速度与精度，参数组合参考examples/shape_gen.py。

from PIL import Image from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline from hy3dgen.texgen import Hunyuan3DPaintPipeline image = Image.open('assets/demo.png').convert('RGBA') mesh = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')(image=image)[0] mesh = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2')(mesh, image=image) mesh.export('output.glb')

用多视角图片生成几何更稳的模型

给到front/left/back三个视角，几何与纹理对输入的还原都更严格，适合手里已有多角度渲染图的场景。

• 示例图在assets/example_mv_images/，每个文件夹含front/left/back三张。
• 多视角几何用1.1B的Hunyuan3D-2mv系列，纹理可换turbo版，参考examples/fast_texture_gen_multiview.py。
• image参数传三张图组成的列表，顺序front、left、back。

from PIL import Image import trimesh from hy3dgen.texgen import Hunyuan3DPaintPipeline pipeline = Hunyuan3DPaintPipeline.from_pretrained( 'tencent/Hunyuan3D-2', subfolder='hunyuan3d-paint-v2-0-turbo') mesh = trimesh.load('assets/1.glb') images = [Image.open(p) for p in [ 'assets/example_mv_images/1/front.png', 'assets/example_mv_images/1/left.png', 'assets/example_mv_images/1/back.png']] mesh = pipeline(mesh, image=images) mesh.export('demo_textured.glb')

用文字提示或低显存模式启动本地界面

没有现成图片、只有一句描述时，可以带文字生3D开关启动Gradio界面；显存小或想跑通流程再调参，就用mini模型加低显存模式。

• 启动命令加--enable_t23d才出现文本输入框，内部先把文字转成图片再进3D管线。
• 显存低于16GB就加--low_vram_mode；0.6B的2mini系列内存占用更低。
• 想快速预览可换Turbo子文件夹并加--enable_flashvdm，推理从50步降到5步，命令对照见docs/source/started/gradio.md。

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

启动后浏览器访问http://localhost:8080。要发HTTP请求生成，则改用python api_server.py --host 0.0.0.0 --port 8080，请求示例见docs/source/started/api.md。

容易踩的坑

以下几条是前几次运行的高频错误，每条一行，现象直接给修复动作。

• ⚠️ 纹理阶段显存溢出：几何约占6GB，纹理再叠加，合计16GB起步 → 加--low_vram_mode，或换0.6B的Hunyuan3D-2mini。
• setup.py install提示找不到nvcc：未装CUDA工具包或不在PATH → 安装CUDA 11.x工具包，把其bin目录加入PATH后重新编译。
• 模型下载长时间卡住：默认走HuggingFace源，网络慢 → 运行前执行export HF_ENDPOINT=https://hf-mirror.com。
• 界面里看不到文本输入框：启动时漏了--enable_t23d→ 给gradio_app.py命令补上该参数并重启。
• 生成形状残留背景色或缺角：输入图不是透明底 → 用hy3dgen/rembg.py里的BackgroundRemover先抠背景再喂入。

接下来可以做什么

跑通第一个模型后，沿这三个方向深入，路径均在仓库内：

• 接入Blender：先启动API服务，再安装blender_addon.py插件，生成的模型直接落进Blender场景，步骤见docs/source/started/blender.md。
• 加速推理：读examples/fast_shape_gen_with_flashvdm.py，Turbo模型加FlashVDM可把几何推理降到5步。
• 理解模型细节：各模型参数量与日期查docs/source/modelzoo.md，技术报告在assets/report/Tencent_Hunyuan3D_2_0.pdf。

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