TRELLIS.2 与 Hunyuan3D 本地部署

# TRELLIS.2 与 Hunyuan3D 本地部署

本地部署的目标是把 输入图片 → 模型推理 → 网格与材质 → 可打开的 GLB 跑通，不是重新训练一个三维模型。先使用官方样例验证环境，再换自己的图片，才能分清是环境错误还是素材问题。

# 开始前先看硬件和环境

项目	TRELLIS.2	Hunyuan3D-2
本篇对应实现	微软官方仓库及 4B 权重	腾讯 2.0 仓库的形状、纹理管线
基本路线	图像条件生成 O-Voxel，再转换成网格与材质	先生成形状，再给形状生成纹理
环境重点	官方测试 Linux、NVIDIA，要求至少 24 GB 显存；包含多个编译扩展	PyTorch、形状模型、纹理依赖及自定义光栅化组件
最小验证	官方图片完成推理和 GLB 导出	先导出无纹理形状，再加入纹理生成
许可	主仓库和权重的 MIT 许可不替代第三方组件许可	对应版本的腾讯社区许可，不是统一 Apache 许可

24 GB 是 TRELLIS.2 官方列出的门槛，不是任意分辨率、任意显卡都能成功的保证。Mac 的统一内存也不能直接等同于 CUDA 显存。没有匹配硬件时，先用托管服务或支持自身硬件的 Modly 扩展，不要在当前 Python 环境里反复混装依赖。

# NVIDIA 驱动和显卡状态；查看当前是否有其他进程占用显存。
nvidia-smi

# CUDA Toolkit 编译器；nvidia-smi 显示的 CUDA 字样不代表已安装这个编译器。
nvcc --version

# 在模型的独立 Python 环境内检查 PyTorch 是否真正识别 CUDA。
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

1
2
3
4
5
6
7
8

驱动让操作系统使用 GPU；CUDA Toolkit 提供编译工具；PyTorch 还需要匹配的运行时和扩展。安装成功但导入时报 undefined symbol，经常是组件二进制不匹配，不是图片或提示词错误。

# TRELLIS.2：安装完整依赖

以下来自官方安装说明 (opens new window)，在独立实验目录和有足够空间的 Linux 机器执行。先准备官方要求的 CUDA Toolkit 与 Conda，阅读 setup.sh 后再运行；命令会下载依赖并编译组件。

# --recursive 同时拉取子模块，否则后面可能缺少扩展源码。
git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive
cd TRELLIS.2

# 创建官方 trellis2 环境，安装基础依赖和几何、渲染相关扩展。
. ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm

# 在新终端运行推理前，显式进入这个环境。
conda activate trellis2

# 先验证仓库自带的图片、推理、渲染与 GLB 导出链路。
python example.py

1
2
3
4
5
6
7
8
9
10
11
12

依赖不是随意堆出来的：FlashAttention 加速注意力计算；nvdiffrast 等组件承担渲染相关计算；CuMesh 处理网格；o_voxel 处理 O-Voxel 和导出；FlexGEMM 提供相关 GPU 运算。只有权重文件而缺少这些扩展，仍然无法完成整条链路。

官方安装说明推荐 CUDA Toolkit 12.4。机器存在多个 CUDA 版本时，需要让 CUDA_HOME 指向实际采用的 Toolkit；不要只修改版本字符串。安装成功后记录代码提交号、依赖和权重版本，之后再升级其中某个组件。

# TRELLIS.2：从图片生成并导出 GLB

下面根据官方 example.py (opens new window) 保留推理与导出主线。保存为仓库内的 generate_asset.py，使用仓库自带图片；首次加载可能联网下载权重。

import os

# 必须在相关库初始化前设置。EXR 常用于环境光贴图；这里不渲染视频。
os.environ["OPENCV_IO_ENABLE_OPENEXR"] = "1"
# 尝试缓解部分显存碎片问题，不会增加显卡的物理容量。
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

from PIL import Image
from trellis2.pipelines import Trellis2ImageTo3DPipeline
import o_voxel

# from_pretrained 加载已有模型，不执行训练。
pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")
pipeline.cuda()

# 先用官方素材验证；成功后再换成自己的授权图片。
image = Image.open("assets/example_image/T.png")
mesh = pipeline.run(image)[0]

# 中间结果同时包含网格几何和体素属性，不能仅改后缀当作 GLB。
glb = o_voxel.postprocess.to_glb(
    vertices=mesh.vertices,
    faces=mesh.faces,
    attr_volume=mesh.attrs,
    coords=mesh.coords,
    attr_layout=mesh.layout,
    voxel_size=mesh.voxel_size,
    aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
    # 采用官方示例的导出配置；100 万面和 4K 纹理不是手机网页的通用预算。
    decimation_target=1000000,
    texture_size=4096,
    remesh=True,
    remesh_band=1,
    remesh_project=0,
    verbose=True,
)

# WebP 纹理能减小体积，但最终查看器也需要支持对应 glTF 扩展。
glb.export("sample.glb", extension_webp=True)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

运行 python generate_asset.py 后，用 Blender 或目标查看器打开 sample.glb。成功标准不是控制台没有异常，而是形状完整、材质能显示、文件能在下游打开。导出坐标范围也不代表真实物体尺寸，实际尺度要另外校准。

官方示例的旋转视频还会加载 EXR 环境光贴图。视频渲染失败与模型生成失败应分开定位；不要因为预览编码报错，就把已经成功生成的网格也当成失败。

# 六类常见问题怎样排查

现象	先检查什么	处理重点
CUDA 扩展编译失败	编译日志、Toolkit、PyTorch CUDA 版本、子模块是否完整	在独立环境修复依赖，不反复下载权重
FlashAttention 不支持显卡或算子	GPU 架构和官方支持的注意力后端	按仓库说明选择兼容后端；不能靠随机降版本解决所有问题
权重下载返回 401 / 403 / 404	是否需登录或许可、令牌权限、模型路径	401 多与身份有关，403 多与访问限制有关；404 也可能是隐藏的受限资源，不一概归为网络问题
EXR 无法读取	文件存在、OpenCV 构建是否支持、环境变量是否提前设置	开关不能给不支持 EXR 的构建凭空增加解码器
CUDA out of memory	其他进程、分辨率、阶段峰值、实际显存	先降低官方支持的分辨率配置；碎片参数不是通用扩容方案
GLB 破洞、细节丢失或透明错误	原始结果与重网格后结果、减面和材质设置	对照不同导出配置；默认不透明材质不会自动正确显示 alpha

remesh=True 有助于重新组织导出表面，但可能改变薄结构；decimation_target 更小通常减轻后续渲染负担，但也可能损失轮廓。应保留原始结果，再制作面向 Web 或打印的派生版本。

官方列出的 H100 推理时间在 512³、1024³、1536³ 配置下约为 3、17、60 秒。这些是特定机器与配置的推理数据，不包含所有下载、排队、导出和人工验收时间，更不是训练耗时。自己的成本要记录 GPU 占用时间与合格资产比例。

# Hunyuan3D-2：先形状，再纹理

Hunyuan3D 的形状模型决定杯口、杯把等几何；纹理模型根据图片和几何补外观。形状错了，纹理再精美也不能修复杯把接错的位置。

在独立环境按 Hunyuan3D-2 安装说明 (opens new window) 安装与 CUDA 匹配的 PyTorch 和仓库依赖。纹理步骤还要编译 README 列出的自定义光栅化组件，不能只安装形状管线就认为纹理也可用。

下面保存为仓库内脚本，使用官方 assets/demo.png：

import gc
import torch
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

image_path = "assets/demo.png"

# 阶段一只生成形状。先保存它，纹理失败时无需丢掉已经完成的几何。
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2"
)
mesh = shape_pipeline(image=image_path)[0]
mesh.export("shape.glb")

# 释放不再使用的形状管线，减少同时保留两套模型造成的显存压力。
del shape_pipeline
gc.collect()
torch.cuda.empty_cache()

# 阶段二在已有几何上生成纹理；这一步也需要模型权重和显存。
paint_pipeline = Hunyuan3DPaintPipeline.from_pretrained("tencent/Hunyuan3D-2")
textured_mesh = paint_pipeline(mesh, image=image_path)
textured_mesh.export("textured.glb")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

两个文件的差别应该能直接观察到：shape.glb 用来检查几何，textured.glb 用来检查贴图和最终外观。显存紧张时也可使用官方 Gradio 的低显存模式，具体参数与权重子目录要成套选择，不能把 mini、Turbo、多视图版本混用。

# 从本地实验接到 Blender 或业务系统

Hunyuan3D-2 仓库提供 api_server.py 和 blender_addon.py。关系是 Blender 插件提交任务 → Python API 调用模型 → 返回资产 → Blender 导入；不是插件本身凭空拥有推理能力。

先启动仅本机监听的服务，再按仓库教程安装并启用插件，配置相同地址。端口用未被占用的专用端口，不要照搬示例占用网站端口。远程访问应通过受控网络或带鉴权的业务代理，不直接公开无鉴权推理服务。

业务系统还需要任务记录、并发限制和资源回收，设计可复用生成任务接入。对于长耗时 GPU 任务，限制同时运行数量通常比给每个 HTTP 请求都加载一份模型更重要。

# 面试问答

1. 本地部署图生 3D，最容易踩的坑是什么？参考答案

主要是环境兼容、显存峰值和导出质量。模型不只依赖权重，还依赖 CUDA、PyTorch 和几何处理扩展。我会先在独立环境跑官方样例，再换自己的素材，并把推理、纹理和导出分开检查。最终要在目标浏览器或 Blender 打开结果，不能只看 Python 脚本有没有结束。

2. 有开源模型，为什么还会选托管 API？参考答案

开源不等于零成本。本地要承担 GPU、编译依赖、扩容和维护，调用量不稳定时利用率可能很低。托管 API 更容易先验证业务，但有费用、数据上传和服务限制。我会根据隐私要求、定制程度和每个合格资产的总成本选择，不只比较一次调用的标价。

图生 3D 工具选型与资产验收 Blender 资产处理与真实结构重建

首页

Choose mode