跳至主要內容

工具與應用

TRELLIS.2 3D 生成模型 LoRA 微調完整指南:修正特定物件幾何細節的容器化實戰

Hugging Face 發布 TRELLIS.2 3D 生成模型 LoRA 微調指南,示範以 188 件鞋類 3D 掃描資料集微調 Sparse Structure 與 Shape Flow DiT,讓 F-score 從 0.276 提升至 0.803。

TRELLIS.2 3D 生成模型 LoRA 微調完整指南:修正特定物件幾何細節的容器化實戰

在機器人技術、物理模擬、媒體製作與遊戲娛樂等領域中,3D 生成技術的應用潛力龐大,但要讓生成的 3D 物件嚴格遵守特定規則或符合標準化的資料表示卻相當困難。面對 GLB、PLY 等多元檔案格式,以及神經輻射場(NeRF)、3D 高斯潑濺(3DGS)等各具優缺點的 3D 表示法,TRELLIS 率先提出了「統一潛在表示(Unified Latent Representation)」,透過解碼器將內部潛在特徵轉換為目標 3D 格式;隨後同一團隊推出的 TRELLIS.2 更進一步強化了 3D 結構的表達能力。

然而,通用型 3D 生成模型在面對特定應用場景時,仍容易在關鍵細節上失準。為了解決這個問題,Hugging Face 團隊於 2026 年 11 月 12 日發布了〈The Definitive Fine-Tuning Guide for 3D Generation Models〉,詳細示範如何透過 LoRA(Low-Rank Adaptation) 與容器化工作流,在本地端或 Hugging Face Jobs 上針對特定物件類別微調 TRELLIS.2。

實驗目標:修正通用模型的「鞋底」幾何誤差

在原始測試中,未經微調的預訓練 TRELLIS.2-4B 模型雖然能生成外觀合理的鞋子,但鞋底(sole)的幾何形狀往往不夠精確。

為了驗證 LoRA 是否能有效改善特定品類的幾何準確度,研究團隊從 Google Scanned Objects (GSO) 資料集的 1,030 個物件中,精選出 188 件鞋類物件作為實驗資料集(其中 179 個用於訓練,9 個作為保留評估的 holdout 測試集)。

TRELLIS.2 架構拆解:五大階段與 O-Voxel 表示法

在決定微調哪些模組之前,必須先理解 TRELLIS.2 生成 3D 物件的五個主要階段:

  1. 影像去背與編碼:先使用 BiRefNet 移除輸入影像背景,再透過具權限控管(gated)的 DINOv3-L 將影像編碼為特徵 tokens,作為後續 3D 生成的條件引導。

  2. 稀疏結構生成(Sparse Structure Flow DiT):這是一個密集型擴散變換器(dense DiT),負責預測物件的粗略形狀,產出 $16^3 \times 8$ 的小型潛在特徵,再由 VAE 解碼器轉為 $64 \times 64 \times 64$ 的佔用網格(occupancy grid)。

  3. O-Voxel 與結構化稀疏潛在表示:O-Voxel 是 TRELLIS.2 的專屬 3D 格式,僅保留物件表面的體素(約佔網格總體素的 10%),大幅節省空體素的運算浪費。由於資料精簡,CPU 可在數秒內將網格轉為 O-Voxel,GPU 也能在數秒內將其還原為網格。

  4. 幾何生成(Shape Flow DiT):稀疏型變換器(sparse transformer),結合佔用網格與 DINOv3 特徵 tokens 生成潛在特徵,經 VAE 解碼為 $512 \times 512 \times 512$ 解析度的 O-Voxel 精細幾何。

  5. 材質生成與網格匯出(Texture Flow DiT):依據形狀潛在特徵與 DINOv3 特徵,生成每個體素的基礎色(base color)、金屬度(metallic)、粗糙度(roughness)與透明度(alpha),最後與幾何結合並匯出為附帶貼圖的 GLB 網格。

微調策略:選擇「凍結什麼」與「微調什麼」同等重要

針對僅有 188 個樣本的小型資料集,全參數微調(full fine-tuning)不僅算力成本高昂,更極易覆蓋模型原有的先驗知識(learned priors)。因此團隊採用 Hugging Face 的 PEFT 函式庫進行 LoRA 微調,總計僅訓練約 930 萬個可微調參數(其餘原始權重全數凍結):

管線組件訓練策略LoRA 設定與原因
Sparse Structure Flow DiT微調於 Attention 與 MLP 層加入 Rank 8 LoRA,修正粗略結構以引導後續幾何生成。
Shape Flow DiT微調於 Attention 層加入 Rank 16 LoRA,直接控制 $512^3$ 高解析度幾何細節(如鞋底輪廓)。
Texture Flow DiT凍結資料集僅包含烘焙光影效果的漫反射貼圖(diffuse color maps),缺乏獨立材質貼圖;強行微調會導致模型將光影誤學為表面材質,甚至引發災難性遺忘(catastrophic forgetting)。
TRELLIS.2 分層 LoRA 微調策略針對特定幾何誤差微調結構與形狀 DiT,同時凍結材質階段避免災難性遺忘
Sparse Structure DiT於 Attention 與 MLP 層加入 Rank 8 LoRA 修正粗略結構
Shape Flow DiT於 Attention 層加入 Rank 16 LoRA 控制幾何細節
Texture Flow DiT(凍結)保持凍結,避免模型將烘焙光影誤學為表面材質

實戰工作流:Hugging Face Jobs 與本地 Docker

為了省去繁瑣的 3D 環境依賴安裝,官方提供了兩個預先打包好的 Docker 映像檔,分別負責資料前處理與 LoRA 訓練(需事先準備具備 DINOv3 存取權限的 HF_TOKEN)。

1. 資料前處理(Preprocessing)

前處理容器會透過 xvfb-run 在無顯示器環境下執行 Blender,為每個 3D 物件渲染 16 個視角作為條件影像,並利用 TRELLIS.2 凍結的編碼器預先將網格轉換為潛在特徵以供重複訓練使用。188 個物件在 a100-large(80 GB)上約需 1 小時完成。

在 Hugging Face Jobs 上執行:

export HF_TOKEN=hf_xxx # 請替換為您的 Hugging Face Token
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

在本地端使用 Docker 執行:

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

2. LoRA 微調訓練(Training)

訓練階段分為 ss(Sparse-Structure Flow DiT)與 shape(Shape Flow DiT)兩種模式,並透過 Trackio 儀表板即時記錄訓練指標。若想直接體驗微調流程,也可跳過前處理,直接使用作者已轉換完成的 suvadityamuk/gso-footwear-trellis2-latents 資料集。

在 Hugging Face Jobs 上執行(使用預處理完畢的鞋類資料集):

export HF_TOKEN=hf_xxx

# 1. 訓練 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

# 2. 訓練 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

訓練管線核心技術解析

深入檢視訓練腳本,有幾個關鍵實作細節值得注意:

  • 資料批次與保留集過濾:訓練時從每個物件的 16 個 Blender 視角中隨機挑選 1 張作為條件影像,並排除 holdout.txt 中的 9 個測試物件。單卡設定 batch size 為 4、梯度累積步數為 4,達到等效 batch size 16。

  • 透過 inject_adapter_in_model() 注入 LoRA:由於 TRELLIS.2 具備自訂的 forward 介面,無法直接使用標準 PeftModel() 包裝器,因此改採 PEFT 的 inject_adapter_in_model() 直接將 LoRA 層注入模型。可訓練權重以 fp32 維持數值穩定性,前向傳播則啟用 bfloat16 autocasting 節省顯存。

  • Rectified Flow Matching 目標函數:沿用與 Stable Diffusion 3、Flux 2 及 TRELLIS.2 預訓練相同的修正流匹配(rectified flow matching)。ss 階段採用 logitNormal 分佈採樣時間步 $t$,shape 階段則採用 uniform 均勻採樣,並搭配隨機將條件歸零的 CFG dropout(p_uncond)與梯度裁剪。

實驗結果與量化評估

在單張 A100 80 GB 上完成訓練,ss 階段耗時 7.2 小時,shape 階段耗時 3.6 小時。由於流匹配損失(flow-matching loss)會隨採樣物件與時間步波動,無法單憑 Loss 曲線判斷幾何品質,團隊進一步在 9 個未見過的 holdout 測試物件上進行了幾何指標評估:

評估指標指標意義與方向基礎模型(Base Model)微調後模型(+ Footwear LoRA)
F-score @ 0.02生成表面與參考掃描的精確率與召回率綜合分數(越高越好)0.2760.803
Chamfer Distance雙向表面點雲最近距離(越低越好)0.1740.033
Normal Consistency表面法向量方向一致度(越高越好)0.5300.804

資料顯示,同時套用兩個幾何 LoRA 後,所有 9 個測試物件的 F-score 均優於基礎模型,且鞋底的幾何結構明顯更貼近真實 3D 掃描結果。

9 件保留測試鞋類幾何評估(F-score @ 0.02)LoRA 微調幾何模組後,鞋類幾何 F-score 從 0.276 躍升至 0.803
F-score @ 0.02(越高越好)
0.276基礎模型(Base Model)
0.803微調後模型(+ Footwear LoRA)約 3 倍
所有 9 個未見過的 holdout 測試物件 F-score 均優於基礎模型。

未來方向

這套「依據問題與資料特性精準挑選微調目標」的策略(微調結構與形狀階段、凍結材質階段),未來可望延伸應用於其他 3D 生成模型(如 Pixal3D、UniLat3D),或進一步探索針對 Gaussian-splat 與世界生成模型(如 HunyuanWorld 2.0、NVIDIA Lyra 2.0)的專屬微調方法。

相關連結

謝謝你,讀到這裡。

保持好奇,明天繼續探索。

© 2026 Communeify. All rights reserved.