使用 LoRA 对 TRELLIS.2 进行 3D 生成微调:实用指南

TL;DR: Hugging Face 发布了一份实用的微调指南、脚本和 Docker 容器,用于通过 LoRA 将 3D 生成模型 TRELLIS.2 适配到自定义 3D 资产。在 Google Scanned Objects 的 188 个鞋类对象子集上,仅微调两个控制几何结构的 DiT,在保持纹理阶段冻结的情况下,显著改善了留出集(held-out)的几何效果。

Hugging Face 发布了什么

Hugging Face 发布了一份指南及配套工具,用于使用 LoRA 微调 TRELLIS.2。该发布包含微调脚本和两个 Docker 容器:一个用于将 3D 网格预处理为 TRELLIS.2 潜在空间(latents),另一个用于训练 LoRA 适配器。这些容器可以在本地使用 Docker 运行,也可以在 Hugging Face Jobs 上运行。

该指南通过 Google Scanned Objects 数据集中的鞋类对象进行了端到端的实验演示。它涵盖了哪些流水线组件需要微调、哪些需要冻结、训练循环的工作原理,以及适配后的模型在留出对象上的表现。

配套仓库为 suvadityamuk/trellis2-finetuning,训练好的适配器发布在 suvadityamuk/trellis-2-finetune-gso。

为什么要微调 3D 生成模型?

通用 3D 生成模型可以产生看似合理的物体,但在特定应用所需的细节上往往表现不佳。该指南以鞋类为例:预训练的 TRELLIS.2 模型通常能生成外观正确的鞋子,但鞋底往往不准确。

该实验使用了 GSO 中 188 个鞋类对象(该数据集总共包含 1,030 个对象)。其中 9 个对象被留出用于评估,其余 179 个用于训练。目标是测试 LoRA 适配器是否能使未见过的鞋类对象的鞋底更加准确。

选择冻结什么与选择微调什么同样重要。

TRELLIS.2 的工作原理

TRELLIS.2 通过五个主要阶段生成 3D 对象:去除图像背景、编码图像、预测粗略结构、生成详细几何结构以及生成材质。随后,流水线将结果导出为带纹理的网格。

图像编码

BiRefNet 从输入图像中去除背景。随后,DINOv3-L 将图像编码为特征标记(feature tokens)。生成模型使用这些标记来引导 3D 对象。

稀疏结构生成

稀疏结构流 DiT 预测物体的粗略形状。它是一个扩散 Transformer,产生一个大小为 16³ × 8 的小潜在空间。VAE 解码器随后将此潜在空间转换为 64 × 64 × 64 的占用网格(occupancy grid)。网格中的每个体素(voxel)指示该位置是否属于物体的一部分。

该指南向此模型添加了 LoRA 适配器,因为其输出引导了几何阶段。

O-Voxel 和结构化潜在空间

O-Voxel 是 TRELLIS.2 使用的 3D 格式。它是一个稀疏体素网格,仅保留物体表面的体素。每个体素存储局部几何信息(如网格顶点)和材质属性。CPU 可以在几秒钟内将网格转换为 O-Voxel,GPU 可以在几秒钟内将 O-Voxel 转换回网格。

结构化稀疏潜在空间来自 TRELLIS。它们将 3D 数据保存在稀疏张量中,这使得计算更快。该模型仅使用网格中约 10% 的体素,因此不会在空体素上消耗计算资源。形状流 DiT 和纹理流 DiT 是稀疏 Transformer,而稀疏结构流 DiT 是密集 Transformer。

几何生成

形状流 DiT 使用占用网格和 DINOv3 特征标记来产生潜在空间。另一个 VAE 解码器将此潜在空间转换为分辨率为 512 × 512 × 512 的 O-Voxel 几何结构。

该指南向此 DiT 添加了 LoRA 适配器,因为它控制物体的形状。

材质生成和网格创建

纹理流 DiT 使用形状潜在空间和 DINOv3 特征作为输入。它定义了几何表面的材质和纹理。VAE 解码器随后将潜在空间转换为每个体素的基础颜色、金属度、粗糙度和 alpha 值。

该指南没有在此阶段添加 LoRA 适配器。鞋类数据集具有漫反射颜色贴图,但缺乏训练纹理流 DiT 所需的独立材质贴图。基础模型已经能产生良好的颜色和纹理,而正在解决的问题是鞋子的形状。

最后,流水线将几何和材质属性组合成带纹理的网格,并将其导出为 GLB 文件。

微调什么,冻结什么

该指南仅向稀疏结构流 DiT 和形状流 DiT 添加了 LoRA 适配器。这两个 DiT 控制物体的形状和几何结构。纹理流 DiT 被冻结以保留其现有能力。

在现有的漫反射颜色贴图上训练纹理流 DiT 会有问题,因为这些贴图包含烘焙的光照效果。数据集不提供独立的材质贴图。如果纹理模型在漫反射贴图上进行训练,它可能会学会将光照表示为表面属性。它还可能忘记之前学到的东西,即所谓的灾难性遗忘。

LoRA 比全量微调更受青睐,因为鞋类子集很小:仅来自 GSO 的 188 个对象。全量微调成本高得多,并且可能会覆盖模型学到的先验知识。该指南的配置在两个目标 DiT 中总共训练了约 930 万个适配器参数。

LoRA 配置在稀疏结构流 DiT 的注意力层和前馈 MLP 层中使用了秩为 8 的适配器。它在形状流 DiT 的注意力层中使用了秩为 16 的适配器。秩决定了适配器矩阵的大小;更高的秩允许适配器学习更多内容。

训练流水线内部

预处理为潜在空间

预处理容器使用 Blender 渲染每个对象的 16 个视图。这些视图在 LoRA 训练期间充当条件图像。Blender 通过 xvfb-run 工具在无显示器的情况下运行。容器还通过 TRELLIS.2 预处理流水线处理每个对象。

该流水线使用 TRELLIS.2 的冻结编码器将输入网格转换为训练潜在空间。它保存这些潜在空间,以便后续运行无需再次编码网格。在训练期间,每个样本会随机选择一个视图作为条件图像。

对于 188 个鞋类对象,完整的预处理运行在 a100-large Hugging Face Jobs 实例上大约耗时 1 小时。预处理命令支持诸如 --holdout 0.05、--views 16 和 --workers 8 等选项。留出设置保留了 188 个对象中的 9 个用于评估。

准备 LoRA 适配器

该指南使用 Hugging Face 的 PEFT 库将 LoRA 适配器插入到选定的层中。TRELLIS.2 具有自定义的前向传播,因此标准的 PeftModel() 包装器无法工作。相反,代码调用 inject_adapter_in_model(),它在保留模型自定义接口的同时直接向模型添加适配器。

可训练的适配器权重保持在 32 位浮点数以保证数值稳定性。前向传播使用 bfloat16 自动混合精度(autocasting),这允许 PyTorch 在某些操作中使用较低精度并减少内存使用。自动混合精度不会改变冻结的主干权重存储方式。

训练目标和循环

训练目标是修正流匹配(rectified flow matching),这是 TRELLIS.2 在预训练期间使用的相同目标。该指南指出,此目标也用于 Stable Diffusion 3 和 Flux 2 等图像生成模型。

训练循环仅更新稀疏结构和形状 DiT 中的 LoRA 参数。所有原始模型权重保持冻结。优化器是 AdamW,beta 设置为 (0.9, 0.95)。

对于每个样本,循环采样一个时间步 t。稀疏结构流 DiT 使用 logit-normal 时间步调度,而形状流 DiT 使用均匀调度,这基于 TRELLIS.2 的配置。循环生成与数据形状匹配的随机噪声,根据 t 将干净数据与噪声混合,预测 t × 1000 处的速度以匹配预训练条件,并计算损失作为预测速度与目标速度之间的均方误差。

训练设置使用批大小为 4,梯度累积步数为 4,有效批大小为 16。梯度检查点(gradient checkpointing)通过在反向传播期间重新计算某些中间值来节省 GPU 内存。对于无分类器引导(classifier-free guidance)的 dropout,循环将一部分随机样本的条件设置为零。在梯度累积后,它会裁剪梯度并执行优化器步骤。它每 10 步记录一次损失,每 500 步保存一个适配器检查点。

运行作业

该指南提供了两个容器镜像:cr.hf.co/suvadityamuk/trellis2-finetuning-prep:latest 用于预处理,cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest 用于训练。相同的命令和标志在 Hugging Face Jobs 和本地 Docker 上均可工作;只有 Docker 选项有所不同。

运行前,用户需要一个具有 DINOv3 访问权限的 Hugging Face token,因为 DINOv3 是一个受限模型。如果使用自定义数据集,必须先将网格上传到 Hugging Face Hub。

稀疏结构流 DiT 的代表性训练命令如下:

export HF_TOKEN=hf_xxx

hf jobs run -d --flavor a100-large --timeout 12h --secrets HF_TOKEN \
  cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \
  trellis2-train --config ss \
    --latents your-username/my-meshes-trellis2 \
    --push-to your-username/my-trellis2-lora \
    --run-name ss_lora \
    --push-path ss_lora \
    --trackio-space your-username/trellis2-trackio

训练容器支持两种模式:ss 用于稀疏结构流 DiT,shape 用于形状流 DiT。每种模式引用不同的配置文件。容器使用 Trackio 记录训练指标,如果设置了 --push-to,它会将适配器检查点上传到 Hugging Face Hub。

两个 Hugging Face Jobs 命令都支持恢复运行。预处理会跳过已完成的对象,训练会从 --push-to 仓库中的最新检查点继续。

结果

该指南训练了两个适配器:一个用于稀疏结构 DiT,另一个用于形状 DiT。每次运行在 Hugging Face Jobs 上使用一个 A100 80 GB GPU。稀疏结构运行耗时 7.2 小时,形状运行耗时 3.6 小时。

稀疏结构流 DiT 的训练损失在开始时下降很快,随后变慢。形状流 DiT 的损失保持在大致相同的水平。该指南提醒说,这些曲线显示了训练目标的变化情况,但它们不能直接衡量生成几何结构的质量。流匹配损失随采样对象、噪声和时间步长而变化,因此必须在留出对象上比较输出。

在 9 个留出对象上,微调后的模型产生的鞋底更接近参考扫描件。该指南报告了以下平均指标:

指标 基础模型 使用鞋类适配器 方向
F-score @ 0.02 0.276 0.803 越高越好
Chamfer 距离 0.174 0.033 越低越好
法线一致性 0.530 0.804 越高越好

F-score @ 0.02 在扫描件边界框对角线的 2% 匹配阈值下结合了精确率和召回率。Chamfer 距离衡量从一个表面上的点到另一个表面上最近点的双向距离。法线一致性衡量表面方向的一致程度。

使用这两个适配器,F-score 在所有 9 个留出对象上都更好。

实践经验与未来方向

该指南的主要经验是训练目标必须与问题和可用数据相一致。对于鞋类实验,结构和形状阶段进行了微调,而纹理阶段被冻结,因为数据集缺乏纹理训练所需的材质贴图。

主要经验是选择一个与问题和现有数据相一致的训练目标。

该指南建议测试相同的选择是否有助于其他 3D 生成模型,例如 Pixal3D 和 UniLat3D。它还确定了高斯溅射(Gaussian-splat)和世界生成模型,例如 HunyuanWorld 2.0 和 NVIDIA Lyra 2.0,作为可能的后续步骤。这些模型使用不同的表示和训练流水线,因此可能需要不同的微调方法。

Sources