在线AI教程 / AI工具
[Hugging Face] The Definitive Fine-Tuning Guide for 3D Generation Models
返回文章 3D 生成模型权威微调指南 发布于 2026 年 11 月 12 日 GitHub 上更新 10 苏瓦蒂亚·慕克吉 苏瓦迪亚穆克 梅尔韦 梅尔韦 佩德罗昆卡 普库恩克 !
返回文章
3D 生成模型权威微调指南
发布于 2026 年 11 月 12 日
GitHub 上更新
10
![]()
![]()
![]()
![]()
![]()
![]()
![]()
苏瓦蒂亚·慕克吉
苏瓦迪亚穆克
![]()
梅尔韦
梅尔韦
![]()
佩德罗昆卡
普库恩克
!英雄GIF
总而言之;在本博客中,我们提供了微调脚本和容器来微调 TRELLIS.2,这是 3D 资产上流行的 3D 模型,它可以在本地运行,也可以在 Hugging Face Jobs 上运行。如果您对微调感兴趣,您可以使用带有少量参数的脚本(假设您将数据集更新为 Hugging Face Hub),或者使用此存储库自行修改它们。如果您想了解更多信息,我们将介绍该脚本的工作原理。我们走吧!
## 介绍
3D 生成在机器人、模拟、媒体和娱乐领域有多种用途。在这些领域中,很难使生成的对象遵守严格的规则并标准化模型和数据表示。文件格式有很多种,例如 GLB 和 PLY)。还有许多表示,例如神经辐射场(NeRFs)和3D高斯泼溅(3DGS)。每一种都有不同的优点和缺点。
TRELLIS引入了一种通用的内部表示,称为统一潜在表示。其解码器将此表示形式转换为所需输出格式的 3D 模型。因此,您不必为每种表示格式使用不同的模型。
该团队随后发布了 TRELLIS.2,它改进了模型对 3D 结构的表示。但这两种模型都没有提供一种简单的方法来使其适应特定任务。
我们想要改进的地方
通用模型(例如 TRELLIS.2)可能会在对特定应用程序很重要的细节上出错。例如,用户可能需要家具模型的精确几何形状。如果不对该任务进行微调,预训练模型可能会生成不够准确的几何形状。我们使用包含 188 个鞋类对象的 GSO 子集进行实验。在我们最初的测试中,预训练模型通常会生产出看起来正确的鞋子,但鞋底却不正确。我们测试LoRA是否可以使鞋底更加准确。

我们的目标是使用 Google 扫描对象 (GSO) 数据集来提高 TRELLIS.2 在特定对象类别上的性能。我们将解释哪些管道组件需要微调,哪些组件在训练期间保持不变。管道将结构、详细几何形状和材料分开。因此,我们将仅微调对我们的任务重要的组件。

选择冻结内容与选择微调内容一样重要。
我们将使用什么?
洛拉
LoRA 是低秩适应的缩写,它通过训练小型适配器矩阵来微调模型,同时保持原始权重冻结。这减少了可训练参数的数量以及其梯度和优化器状态所需的内存。我们使用 Hugging Face 的 PEFT 库来添加和训练这些适配器。有关更多信息,请阅读我们的 LoRA 指南。
Hugging Face工作
Hugging Face Jobs 在云硬件上运行容器化工作负载。我们用它进行预处理和训练。要使用您自己的 GPU,请参阅下面的本地 Docker 命令。在开始之前,请确保您拥有:
您可以[从此处]获取 HF_TOKEN(https://huggingface.co/settings/tokens/new) 您的 Hugging Face 帐户必须具有 访问 DINOv3,因为 DINOv3 是一个门控模型 如果您使用自己的数据集,请在开始之前将其网格上传到中心。
TRELLIS.2 的工作原理
在训练之前,让我们看看 TRELLIS.2 如何生成 3D 对象以及我们将在哪里添加 LoRA 适配器。
TRELLIS.2有五个主要阶段:去除图像背景、编码图像、预测粗略结构、生成详细几何形状和生成材料。然后,管道将结果导出为纹理网格。

对输入图像进行编码
首先,BiRefNet 从输入图像中删除背景。然后 DINOv3-L 将图像编码为特征标记。生成模型使用这些标记来引导 3D 对象。

###稀疏结构生成(稀疏结构流)
稀疏结构流 DiT 预测对象的粗略形状。它是一个扩散变压器 (DiT),可生成大小为 16×8 的小型潜在变量。然后,变分自动编码器 (VAE) 解码器将此潜在变量更改为 64 × 64 × 64 占用网格。网格中的每个体素都会显示该位置是否是对象的一部分。体素是三维的像素。我们向该模型添加 LoRA 适配器,因为它的输出引导几何阶段。 
O-体素和结构化潜伏
O-Voxel 是 TRELLIS.2 的 3D 格式。它是一个稀疏体素网格。它仅保留对象表面上的体素。每个体素都保留局部几何形状,例如网格顶点和材质属性。由于格式很小,CPU 可以在几秒钟内将网格转变为 O-Voxel。 GPU 在几秒钟内将 O-Voxel 变回网格。
结构化稀疏潜在变量来自 TRELLIS。他们将 3D 数据保存在稀疏张量中,这使得计算速度更快。该模型仅使用网格中大约 10% 的体素,因此它不会在空体素上花费计算。因此,形状流DiT和纹理流DiT是稀疏变换器。稀疏结构流 DiT 是一个密集变压器。 
几何生成(形状流)
形状流 DiT 使用占用网格和 DINOv3 特征标记来生成潜在的。然后,另一个 VAE 解码器将其转换为分辨率为 512 × 512 × 512 的 O-体素几何。
我们在此阶段将 LoRA 适配器添加到 DiT,因为它控制对象的形状。

材质生成+网格创建
在最后阶段,纹理流 DiT 使用潜在形状和 DINOv3 特征作为输入。它定义了几何体表面的材质和纹理。然后,VAE 解码器将每个体素的潜在值更改为基色、金属、粗糙度和 alpha 值。我们不会在此阶段添加 LoRA 适配器。我们的数据集具有漫反射颜色图,但缺少此阶段训练所需的单独材质图。另外,我们的问题是鞋子的形状。基础模型已经产生了良好的颜色和纹理。
最后,管道将几何体和材质属性组合成纹理网格并将其导出为 GLB 文件。

规划
哪些组件需要微调
我们仅将 LoRA 适配器添加到稀疏结构流 DiT 和形状流 DiT 中。这些 DiT 控制对象的形状和几何形状。我们冻结纹理流 DiT 以保持其当前功能。
我们的数据集包含漫反射颜色贴图,其中包括烘焙光照效果。为了训练纹理流 DiT,我们需要单独的材质贴图。我们数据集中的颜色图将表面颜色与光照混合。因此,他们不是本次培训的正确目标。
如果我们在这些贴图上训练纹理流 DiT,它可以学习将光照显示为表面属性。它还可能忘记以前学到的东西,这种问题称为灾难性遗忘。
为什么使用 LoRA
我们的子集包含 GSO 中 1,030 个对象中的 188 个鞋子。对于这么小的数据集,LoRA 是比完全微调更好的选择。完全微调的成本要高得多。它还可以覆盖模型已经做得很好的部分(它学到的先验知识)。我们的配置为两个目标 DiT 总共训练了大约 930 万个适配器参数。我们在稀疏结构流 DiT 的注意力和前馈 (MLP) 层中使用 8 级适配器。我们在形状流 DiT 的注意力层中使用 16 级适配器。等级设置适配器矩阵的大小。更高的等级可以让适配器了解更多。
你将运行什么
3D 模型设置可能需要许多依赖项和安装步骤。我们提供两个 Docker 镜像(您可以在 Jobs 或您自己的机器上运行)以及必要的软件。一张图像用于预处理,一张图像用于微调。
要训练您的 LoRA 适配器并将其上传到集线器:
允许容器访问您的数据。 为您的任务设置参数。 运行预处理容器。 运行微调容器。
然后我们解释微调脚本、其设置以及每个设置如何影响训练。
实验概述
我们将逐步完成实验的三个部分:
准备数据。 将 GLB 或 OBJ 网格转换为 TRELLIS.2 用于训练的潜在表示,并渲染输入图像。 训练适配器。 使用准备好的数据集和 LoRA 配置为每个 DiT 运行一项作业。 解释代码。检查容器如何加载数据、添加适配器和训练模型。
我们保存预处理的数据集,以便所有训练运行都可以重复使用它。
演练
Hugging Face工作
预处理
预处理容器使用 Blender 渲染每个对象的 16 个视图。 LoRA 训练将使用这些视图作为条件图像。 Blender 通过 xvfb-run 实用程序在没有显示器的情况下运行。容器还通过预处理管道处理每个对象。请参阅此处的 鞋类数据集 以获取示例中间输出。对于 188 个对象,100 个大型作业的完整运行大约需要 1 小时。 此配套存储库 中还提供了预处理管道的紧凑版本。
export HF_TOKEN=hf_xxx
Replace your-username with your Hugging Face username
hf jobs run -d --flavor a100-large --timeout 6h --secrets HF_TOKEN \ cr.hf.co/suvadityamuk/trellis2-finetuning-prep:latest \ trellis2-prep \ --meshes your-username/my-meshes \ --push-to your-username/my-meshes-trellis2 \ --private --holdout 0.05 \ --views 16 --workers 8
对于Hugging Face工作,我们传递以下参数:
旗帜意义 -d分离:打印作业 ID 和 URL,然后返回。要跟踪作业,请运行 hf jobs messages -f
该容器接受更多参数(无论是在 Hugging Face Jobs 上运行还是使用 Docker 运行),您可以在此处找到文档。预处理管道中采取的步骤稍后记录在本节中。
LoRA 微调
训练容器加载准备好的数据集和配置预设或文件。它使用 Trackio 记录训练指标。使用 Trackio 仪表板监控跑步情况。
我们使用“ss”和“shape”来表示训练 LoRA 的两种模式。 “ss”模式将仅微调稀疏结构流 DiT,而“shape”模式将微调形状流 DiT。在幕后,他们只是引用不同的 config.json 文件以用于每个阶段。有关该过程的更多详细信息,请参阅稍后的本节。
export HF_TOKEN=hf_xxx # Replace your-username with your Hugging Face username
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
hf jobs run -d --flavor a100-large --timeout 12h --secrets HF_TOKEN \ cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \ trellis2-train --config shape \ --latents your-username/my-meshes-trellis2 \ --push-to your-username/my-trellis2-lora \ --run-name shape_lora \ --push-path shape_lora \ --trackio-space your-username/trellis2-trackio \ --set max_steps=3000 i_save=500
如果设置“--push-to”,容器会将适配器检查点上传到集线器。该容器接受的参数也为简洁起见在此处记录。 同一存储库 中还提供了紧凑的脚本。
如果您想使用我们已经处理的数据集并进行微调,请随意使用以下命令集。
export HF_TOKEN=hf_xxx
Replace your-username with your Hugging Face username
For the Sparse-Structure Flow DiT
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 suvadityamuk/gso-footwear-trellis2-latents \ --push-to your-username/trellis2-footwear-lora \ --run-name ss_lora \ --push-path ss_lora \ --trackio-space your-username/trellis2-trackio \ --set max_steps=3000 i_save=500
For the Shape Flow DiT
hf jobs run -d --flavor a100-large --timeout 12h --secrets HF_TOKEN \ cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \ trellis2-train \ --config shape \ --latents suvadityamuk/gso-footwear-trellis2-latents \ --push-to your-username/trellis2-footwear-lora \ --run-name shape_lora \ --push-path shape_lora \ --trackio-space your-username/trellis2-trackio \ --set max_steps=3000 i_save=500
使用 Docker 在本地运行
预处理
命令和标志与Hugging Face作业相同。只是 Docker 选项不同。
For preprocessing into latents
docker run --gpus all --rm --shm-size 16g -e HF_TOKEN=hf_xxx \ -v hf-cache:/root/.cache/huggingface -v "$PWD/work":/workspace/work \ cr.hf.co/suvadityamuk/trellis2-finetuning-prep:latest \ trellis2-prep --meshes your-username/my-meshes --push-to your-username/my-meshes-trellis2
LoRA 微调
For Sparse-structure Flow DiT
docker run --gpus all --rm --shm-size 16g \ -v hf-cache:/root/.cache/huggingface -v "$PWD/work":/workspace/work \ 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 --trackio-space your-username/trellis2-trackio
For Shape Flow DiT
docker run --gpus all --rm --shm-size 16g \ -v hf-cache:/root/.cache/huggingface -v "$PWD/work":/workspace/work \ cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \ trellis2-train --config shape --latents your-username/my-meshes-trellis2 \ --push-to your-username/my-trellis2-lora --trackio-space your-username/trellis2-trackio
如果您想在您选择的计算机上本地使用我们的已预处理的数据集,请使用以下命令:
export HF_TOKEN=hf_xxx # Replace your-username with your Hugging Face username
For Sparse-structure Flow DiT
docker run --gpus all --rm --shm-size 16g -e HF_TOKEN \ -v hf-cache:/root/.cache/huggingface \ -v "$PWD/work":/workspace/work \ cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \ trellis2-train \ --config ss \ --latents suvadityamuk/gso-footwear-trellis2-latents \ --push-to your-username/trellis2-footwear-lora \ --trackio-space your-username/trellis2-trackio \ --set max_steps=3000 i_save=500
For Shape Flow DiT
docker run --gpus all --rm --shm-size 16g -e HF_TOKEN \ -v hf-cache:/root/.cache/huggingface \ -v "$PWD/work":/workspace/work \ cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest \ trellis2-train \ --config shape \ --latents suvadityamuk/gso-footwear-trellis2-latents \ --push-to your-username/trellis2-footwear-lora \ --trackio-space your-username/trellis2-trackio \ --set max_steps=3000 i_save=500
我们训练有素的 LoRA 适配器位于此存储库中:suvadityamuk/trellis-2-finetune-gso
训练管道内部
预处理为潜在变量
我们使用TRELLIS.2的冻结编码器来转换输入网格进入训练潜伏期。我们保存这些潜在变量,因此以后的运行不必再次对网格进行编码。
我们还在 Blender 中渲染每个对象的 16 个视图。在训练过程中,我们为每个样本选择一个随机视图作为条件图像。我们保留 188 个对象中的 9 个用于评估,并在其他 179 个对象上进行训练。这些保留的对象显示适配器是否适用于训练期间模型未看到的对象。

Blender 为一个对象渲染的一些视图
第一个片段设置数据。 “FLOW”选择要训练的流 DiT(“ss”或“shape”),“STEPS”设置优化器步骤数。批处理大小为 4,具有 4 个梯度累积步骤,有效批处理大小为 16。然后,该代码片段加载所选流 DiT 的 LoRA 配置文件,使数据集采用 TRELLIS.2 格式,删除保留的对象,并使数据加载器进行微调。
cfg = json.load( open( { "ss": "/workspace/TRELLIS.2/configs/lora/ss_flow_lora_gso.json", "shape": "/workspace/TRELLIS.2/configs/lora/slat_flow_img2shape_lora_gso.json", }[FLOW] ) )
key, latents = { "ss": ("ss_latent", "ss_latents/ss_enc_conv3d_16l8_fp16_64"), "shape": ("shape_latent", "shape_latents/shape_enc_next_dc_f16c32_fp16_512"), }[FLOW]
roots = json.dumps( { "gso": { key: f"{DATA}/{latents}", "render_cond": f"{DATA}/renders_cond", "meta": DATA, } } )
ds = getattr(datasets, cfg["dataset"])(roots, **cfg["dataset_args"])
holdout = set(open(f"{DATA}/holdout.txt").read().split()) ds.instances = [(root, sha) for root, sha in ds.instances if sha not in holdout]
batches = cycle( DataLoader( ds, batch_size=BATCH, shuffle=True, drop_last=True, num_workers=4, collate_fn=getattr(ds, "collate_fn", None), ) )
准备 LoRA 适配器
我们使用peft 库将 LoRA 适配器插入到选定的层中。 TRELLIS.2 有一个自定义前向传递,因此标准的“PeftModel()”包装器不起作用。相反,我们调用“inject_adapter_in_model()”。此函数将适配器直接添加到模型中并保留其自定义接口。
我们将可训练适配器权重保留为 32 位浮点(“fp32”)以实现数值稳定性,并使用 bfloat16(“bf16”)自动转换进行前向传递。自动转换让 PyTorch 对某些操作使用较低的精度,从而减少内存使用。自动铸造不会改变冻结主干权重的存储方式。
model = models.from_pretrained(cfg["ckpt"]) for block in model.blocks: block.use_checkpoint = True
inject_adapter_in_model( LoraConfig( r=cfg["rank"], lora_alpha=cfg["alpha"], target_modules=cfg["lora_targets"] ), model, )
params = [] for name, p in model.named_parameters(): p.requires_grad_("lora_" in name) if p.requires_grad: p.data = p.data.float() # fp32 master weights for LoRA params.append(p)
model.cuda().train()
培训
需要注意的是,我们的目标函数是古老的整流流匹配(如流行的图像生成模型,如 Stable Diffusion 3、Flux 2 等)。 TRELLIS.2在预训练中使用了相同的目标,因此它是微调的不错选择。有关理论,请阅读有关流匹配的此博客。
我们仅更新稀疏结构和形状 DiT 中的 LoRA 参数。所有原始模型重量保持冻结。
下面的片段显示了一个阶段的核心训练循环。它们比容器代码更简单,并且不包含一些设置步骤。对于完整的工作流程,请使用容器命令。
我们初始化优化器并加载 DINOv3 以从输入图像中提取特征。
opt = torch.optim.AdamW( params, lr=cfg["lr"], weight_decay=cfg["weight_decay"], betas=(0.9, 0.95) )
dino = DinoV3FeatureExtractor( cfg["image_cond_model"], image_size=cfg["image_size"] ).cuda()
然后,我们在训练循环中遵循以下步骤:
为每个样本采样一个时间步 t(对于稀疏结构流 DiT 使用 logitNormal,对于基于 TRELLIS.2 配置的形状流 DiT 使用uniform)。 生成与数据形状匹配的随机噪声并重塑 t 以进行广播。 基于 t 将干净数据与噪声混合(其中 t = 0 是噪声最小的数据,t = 1 是纯噪声)。 预测 t × 1000 的速度以匹配预训练条件。 将损失计算为预测速度和目标速度之间的均方误差(x_t 的一阶导数)。
def flow_loss(x0, cond): s = cfg["t_schedule"]
t = ( torch.rand(x0.shape[0]) if s["name"] == "uniform" else torch.sigmoid( torch.randn(x0.shape[0]) * s["args"]["std"] + s["args"]["mean"] ) ) t = t.cuda()
noise = ( x0.replace(torch.randn_like(x0.feats)) if cfg["sparse"] else torch.randn_like(x0) )
tv = t.view(-1, [1] (len(x0.shape) - 1))
x_t = (1 - tv) x0 + (cfg["sigma_min"] + (1 - cfg["sigma_min"]) tv) * noise
pred, target = model(x_t, t 1000, cond), (1 - cfg["sigma_min"]) noise - x0
return ( F.mse_loss(pred.feats, target.feats) if cfg["sparse"] else F.mse_loss(pred, target) )
训练循环计算损失并更新适配器权重。梯度累积在每个优化器步骤之前添加 4 个小批次的梯度。梯度检查点通过在反向传播期间重新计算一些中间值来节省 GPU 内存。外部循环运行给定数量的优化器步骤,而内部循环则在一组批次上累积梯度。
对于每个批次,DINOv3 对调节图像进行编码。对于无分类器指导 (CFG) dropout,循环将样本的随机部分 (p_uncond) 的条件设置为零。然后,它使用 bf16 自动广播计算流匹配损失。内部循环之后,它会剪辑梯度以防止非常大的更新,并执行优化器步骤。它每 10 步记录一次丢失情况,每 500 步保存一个适配器检查点。
for step in range(1, STEPS + 1): for _ in range(ACCUM): batch = next(batches) x0 = recursive_to_device(batch["x_0"], "cuda")
with torch.no_grad(): cond = dino(batch["cond"]) cond[torch.rand(len(cond), device="cuda") < cfg["p_uncond"]] = 0
with torch.autocast("cuda", dtype=torch.bfloat16): loss = flow_loss(x0, cond) / ACCUM
loss.backward()
torch.nn.utils.clip_grad_norm_(params, cfg["grad_clip"])
opt.step() opt.zero_grad()
结果
我们训练了两种适配器:一种用于稀疏结构 DiT,一种用于形状 DiT。容器镜像中的 LoRA 配置文件包含完整的训练设置:稀疏结构流 DiT 的 ss_flow_lora_gso.json 和slat_flow_img2shape_lora_gso.json用于形状流DiT。每次运行都在 Hugging Face Jobs 上使用一台 A100 80 GB。稀疏结构运行耗时 7.2 小时,形状运行耗时 3.6 小时。
稀疏结构流 DiT 的训练损失一开始下降得很快,然后下降得更慢。形状流 DiT 的损失保持在大致相同的水平。这些曲线显示了训练目标如何变化,但它们并不直接测量生成的几何图形的质量。 
流匹配损失随采样对象、噪声和时间步长的变化而变化。为了查明微调是否改善了几何形状,我们还必须比较保留对象的输出。
下图比较了九个保留对象中五个的输出。它显示输入图像、基础模型生成的输出、旋转调整后的基础输出、鞋类适配器的输出以及参考扫描。在这些示例中,微调模型的鞋底更接近扫描结果。

我们还使用三个指标来评估测试集上的几何形状:
公制这意味着什么 倒角距离从一个表面上的点到另一个表面上最近的点的距离,在两个方向上测量。越低越好。 F 分数 @ 0.02精度(生成的表面有多少靠近参考)和召回(生成的表面覆盖了多少参考表面)的组合。这里,匹配阈值是扫描边界框对角线的 2%。越高越好。 正常稠度表面方向一致的程度。表面法线是垂直于表面的矢量。越高越好。

在图表的九个对象比较中,基本模型的平均 F 得分为 0.276,而带有鞋类适配器的模型的平均 F 得分为 0.803。倒角距离从 0.174 下降到 0.033,正常一致性从 0.530 上升到 0.804。对于这两个适配器,所有九个保留对象的 F 分数都更好。 
有关所有运行的统计信息,请参阅此Trackio space。
未来的方向
唷,我们就这样吧!我们通过将 LoRA 适配器添加到控制几何形状的两个模型组件中,对鞋类生成的 TRELLIS.2 进行了微调。我们准备了一次数据,在单独的作业中训练适配器,并评估保留对象的输出。
主要课程是选择与问题和您拥有的数据相符的训练目标。在这个实验中,我们微调了结构和形状阶段并冻结了纹理阶段。
接下来,我们可以检查相同的选择是否有助于其他 3D 生成模型,例如 Pixal3D 和 UniLat3D。
Gaussian-splat 和世界生成模型,例如 HunyuanWorld 2.0 和 NVIDIA Lyra 2.0,也是下一步的可能。他们的表示和训练管道可能需要不同的方法。
感谢您的关注,我们下期再见! 👋🤗
本文提到的型号1
本文提到的数据集2
本文提到的空格2
本文提到的论文3
本文提到的集合3
我们博客的更多文章
LLM
TGI Multi-LoRA:部署一次,服务 30 个模型
![]()
![]()
![]()
63
2024 年 7 月 18 日
nlp指南社区
多向量嵌入模型的令牌池感知训练
![]()
29
2026 年 11 月 11 日
社区
通过拖入文本输入、粘贴或单击此处来上传图像、音频和视频。
点击或粘贴此处上传图像
· 注册 或 登录 发表评论
10
![]()
![]()
![]()
![]()
![]()
![]()
![]()
![]()
![]()
![]()
本文提到的型号1
本文提到的数据集2
本文提到的空格2
本文提到的论文3
本文提到的集合3