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 物件的五個主要階段:
影像去背與編碼:先使用 BiRefNet 移除輸入影像背景,再透過具權限控管(gated)的 DINOv3-L 將影像編碼為特徵 tokens,作為後續 3D 生成的條件引導。
稀疏結構生成(Sparse Structure Flow DiT):這是一個密集型擴散變換器(dense DiT),負責預測物件的粗略形狀,產出 $16^3 \times 8$ 的小型潛在特徵,再由 VAE 解碼器轉為 $64 \times 64 \times 64$ 的佔用網格(occupancy grid)。
O-Voxel 與結構化稀疏潛在表示:O-Voxel 是 TRELLIS.2 的專屬 3D 格式,僅保留物件表面的體素(約佔網格總體素的 10%),大幅節省空體素的運算浪費。由於資料精簡,CPU 可在數秒內將網格轉為 O-Voxel,GPU 也能在數秒內將其還原為網格。
幾何生成(Shape Flow DiT):稀疏型變換器(sparse transformer),結合佔用網格與 DINOv3 特徵 tokens 生成潛在特徵,經 VAE 解碼為 $512 \times 512 \times 512$ 解析度的 O-Voxel 精細幾何。
材質生成與網格匯出(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)。 |
實戰工作流: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維持數值穩定性,前向傳播則啟用bfloat16autocasting 節省顯存。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.276 | 0.803 |
| Chamfer Distance | 雙向表面點雲最近距離(越低越好) | 0.174 | 0.033 |
| Normal Consistency | 表面法向量方向一致度(越高越好) | 0.530 | 0.804 |
資料顯示,同時套用兩個幾何 LoRA 後,所有 9 個測試物件的 F-score 均優於基礎模型,且鞋底的幾何結構明顯更貼近真實 3D 掃描結果。
未來方向
這套「依據問題與資料特性精準挑選微調目標」的策略(微調結構與形狀階段、凍結材質階段),未來可望延伸應用於其他 3D 生成模型(如 Pixal3D、UniLat3D),或進一步探索針對 Gaussian-splat 與世界生成模型(如 HunyuanWorld 2.0、NVIDIA Lyra 2.0)的專屬微調方法。
相關連結
官方原文部落格:The Definitive Fine-Tuning Guide for 3D Generation Models (Hugging Face Blog)
微調後 LoRA 模型權重:suvadityamuk/trellis-2-finetune-gso
預處理完成之鞋類潛在資料集:suvadityamuk/gso-footwear-trellis2-latents
原始 3D 掃描資料集:hugging-3d/google-scanned-objects
TRELLIS.2 技術論文:Native and Compact Structured Latents for 3D Generation (arXiv:2512.14692)