LoRA를 사용한 3D 생성 모델 TRELLIS.2 파인튜닝: 실전 가이드
TL;DR: Hugging Face는 3D 생성 모델인 TRELLIS.2를 LoRA를 통해 커스텀 3D 에셋에 맞게 조정할 수 있는 실전 가이드, 스크립트, Docker 컨테이너를 공개했습니다. Google Scanned Objects(GSO) 데이터셋의 신발 188개 서브셋을 대상으로 실험한 결과, 텍스처 단계는 고정(frozen)한 채 지오메트리를 제어하는 두 개의 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 모델은 일반적으로 올바르게 보이는 신발을 생성하지만, 밑창(sole) 부분은 부정확한 경우가 많았습니다.
이 실험은 총 1,030개의 객체를 포함하는 GSO 데이터셋에서 188개의 신발 객체를 사용합니다. 188개 중 9개는 평가를 위해 미학습 데이터로 남겨두고, 나머지 179개는 학습에 사용합니다. 목표는 LoRA 어댑터가 학습하지 않은 신발 객체에 대해서도 밑창을 더 정확하게 만들 수 있는지 테스트하는 것입니다.
무엇을 고정할지 선택하는 것은 무엇을 파인튜닝할지 선택하는 것만큼 중요합니다.
TRELLIS.2의 작동 원리
TRELLIS.2는 이미지 배경 제거, 이미지 인코딩, 거친 구조 예측, 상세 지오메트리 생성, 재질 생성이라는 5가지 주요 단계를 통해 3D 객체를 생성합니다. 이후 파이프라인은 결과를 텍스처가 입혀진 메시로 내보냅니다.
이미지 인코딩
BiRefNet이 입력 이미지에서 배경을 제거합니다. 그 후 DINOv3-L이 이미지를 특징 토큰(feature tokens)으로 인코딩합니다. 생성 모델은 이 토큰을 사용하여 3D 객체를 가이드합니다.
희소 구조(Sparse structure) 생성
희소 구조 흐름 DiT(sparse-structure flow DiT)는 객체의 거친 형태를 예측합니다. 이는 16³ × 8 크기의 작은 잠재 공간을 생성하는 확산 트랜스포머(diffusion transformer)입니다. VAE 디코더는 이 잠재 공간을 64 × 64 × 64 점유 그리드(occupancy grid)로 변환합니다. 그리드의 각 복셀(voxel)은 해당 위치가 객체의 일부인지 여부를 나타냅니다.
이 가이드에서는 이 모델의 출력이 지오메트리 단계를 안내하므로 여기에 LoRA 어댑터를 추가합니다.
O-Voxel 및 구조화된 잠재 공간
O-Voxel은 TRELLIS.2에서 사용하는 3D 형식입니다. 이는 객체 표면의 복셀만 유지하는 희소 복셀 그리드입니다. 각 복셀은 메시 정점(vertex)과 같은 로컬 지오메트리와 재질 속성을 저장합니다. CPU는 메시를 O-Voxel로 몇 초 만에 변환할 수 있으며, GPU는 O-Voxel을 다시 메시로 몇 초 만에 변환할 수 있습니다.
구조화된 희소 잠재 공간(Structured sparse latents)은 TRELLIS에서 나옵니다. 이는 3D 데이터를 희소 텐서에 유지하여 계산 속도를 높입니다. 모델은 그리드 내 복셀의 약 10%만 사용하므로 빈 복셀에 연산 자원을 낭비하지 않습니다. 형태 흐름 DiT(shape flow DiT)와 텍스처 흐름 DiT(texture flow DiT)는 희소 트랜스포머인 반면, 희소 구조 흐름 DiT는 밀집 트랜스포머입니다.
지오메트리 생성
형태 흐름 DiT는 점유 그리드와 DINOv3 특징 토큰을 사용하여 잠재 공간을 생성합니다. 또 다른 VAE 디코더는 이 잠재 공간을 512 × 512 × 512 해상도의 O-Voxel 지오메트리로 변환합니다.
이 가이드에서는 이 DiT가 객체의 형태를 제어하므로 여기에 LoRA 어댑터를 추가합니다.
재질 생성 및 메시 생성
텍스처 흐름 DiT는 형태 잠재 공간과 DINOv3 특징을 입력으로 사용합니다. 이는 지오메트리 표면의 재질과 텍스처를 정의합니다. VAE 디코더는 잠재 공간을 각 복셀의 기본 색상, 금속성, 거칠기, 알파 값으로 변환합니다.
이 가이드에서는 이 단계에 LoRA 어댑터를 추가하지 않습니다. 신발 데이터셋에는 확산 색상 맵(diffuse color maps)은 있지만 텍스처 흐름 DiT를 학습시키는 데 필요한 별도의 재질 맵이 부족하기 때문입니다. 기본 모델은 이미 좋은 색상과 텍스처를 생성하며, 해결하려는 문제는 신발의 형태입니다.
마지막으로, 파이프라인은 지오메트리와 재질 속성을 결합하여 텍스처가 입혀진 메시로 만들고 GLB 파일로 내보냅니다.
파인튜닝할 것과 고정할 것
이 가이드는 희소 구조 흐름 DiT와 형태 흐름 DiT에만 LoRA 어댑터를 추가합니다. 이 두 DiT는 객체의 형태와 지오메트리를 제어합니다. 텍스처 흐름 DiT는 기존 기능을 보존하기 위해 고정됩니다.
사용 가능한 확산 색상 맵으로 텍스처 흐름 DiT를 학습시키는 것은 해당 맵에 베이크된 조명 효과가 포함되어 있어 문제가 될 수 있습니다. 데이터셋은 별도의 재질 맵을 제공하지 않습니다. 텍스처 모델을 확산 맵으로 학습시키면 조명을 표면 속성으로 표현하는 법을 배울 수 있습니다. 또한 이전에 학습한 내용을 잊어버리는 '파괴적 망각(catastrophic forgetting)' 문제가 발생할 수 있습니다.
신발 서브셋이 GSO에서 추출한 188개 객체로 작기 때문에 전체 파인튜닝보다 LoRA가 선호됩니다. 전체 파인튜닝은 비용이 훨씬 많이 들고 모델이 학습한 사전 지식을 덮어쓸 수 있습니다. 이 가이드의 구성은 두 대상 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과 같은 옵션을 지원합니다. holdout 설정은 188개 중 9개를 평가용으로 남겨둡니다.
LoRA 어댑터 준비
Hugging Face의 PEFT 라이브러리를 사용하여 선택한 레이어에 LoRA 어댑터를 삽입합니다. TRELLIS.2는 커스텀 포워드 패스를 가지고 있어 표준 PeftModel() 래퍼는 작동하지 않습니다. 대신 코드는 inject_adapter_in_model()을 호출하여 커스텀 인터페이스를 유지하면서 모델에 어댑터를 직접 추가합니다.
학습 가능한 어댑터 가중치는 수치적 안정성을 위해 32비트 부동 소수점으로 유지됩니다. 포워드 패스는 bfloat16 자동 캐스팅을 사용하여 PyTorch가 일부 연산에 낮은 정밀도를 사용하도록 하여 메모리 사용량을 줄입니다. 자동 캐스팅은 고정된 백본 가중치가 저장되는 방식에는 영향을 주지 않습니다.
학습 목표 및 루프
학습 목표는 TRELLIS.2가 사전 학습 중에 사용한 것과 동일한 rectified flow matching입니다. 이 가이드는 이 목표가 Stable Diffusion 3 및 Flux 2와 같은 이미지 생성 모델에서도 사용된다고 언급합니다.
학습 루프는 희소 구조 및 형태 DiT의 LoRA 파라미터만 업데이트합니다. 모든 원본 모델 가중치는 고정된 상태로 유지됩니다. 옵티마이저는 (0.9, 0.95)로 설정된 베타 값을 가진 AdamW입니다.
각 샘플에 대해 루프는 타임스텝 t를 샘플링합니다. 희소 구조 흐름 DiT는 logit-normal 타임스텝 스케줄을 사용하고, 형태 흐름 DiT는 TRELLIS.2 구성에 따라 균일 스케줄을 사용합니다. 루프는 데이터 모양과 일치하는 무작위 노이즈를 생성하고, t를 기반으로 깨끗한 데이터와 노이즈를 혼합하며, 사전 학습 조건과 일치하도록 t × 1000에서 속도를 예측하고, 예측된 속도와 대상 속도 간의 평균 제곱 오차(MSE)로 손실을 계산합니다.
학습 설정은 배치 크기 4와 4단계의 그래디언트 누적을 사용하여 16의 유효 배치 크기를 제공합니다. 그래디언트 체크포인팅은 역전파 중에 일부 중간 값을 다시 계산하여 GPU 메모리를 절약합니다. Classifier-free guidance 드롭아웃을 위해 루프는 샘플의 무작위 비율에 대해 컨디셔닝을 0으로 설정합니다. 그래디언트 누적 후 그래디언트를 클리핑하고 옵티마이저 단계를 수행합니다. 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 토큰이 필요합니다(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
학습 컨테이너는 희소 구조 흐름 DiT를 위한 ss 모드와 형태 흐름 DiT를 위한 shape 모드라는 두 가지 모드를 지원합니다. 각 모드는 서로 다른 구성 파일을 참조합니다. 컨테이너는 Trackio로 학습 지표를 기록하며, --push-to가 설정된 경우 어댑터 체크포인트를 Hugging Face Hub에 업로드합니다.
Hugging Face Jobs 명령은 모두 재개를 지원합니다. 전처리는 이미 완료된 객체를 건너뛰고, 학습은 --push-to 저장소의 최신 체크포인트부터 계속됩니다.
결과
이 가이드는 희소 구조 DiT용과 형태 DiT용으로 두 개의 어댑터를 학습시켰습니다. 각 실행은 Hugging Face Jobs에서 A100 80GB GPU 1개를 사용했습니다. 희소 구조 실행은 7.2시간, 형태 실행은 3.6시간이 소요되었습니다.
희소 구조 흐름 DiT의 학습 손실은 초기에 빠르게 떨어지다가 나중에 더 느리게 떨어집니다. 형태 흐름 DiT의 손실은 거의 같은 수준을 유지합니다. 이 가이드는 이러한 곡선이 학습 목표가 어떻게 변하는지를 보여주지만 생성된 지오메트리의 품질을 직접 측정하지는 않는다고 경고합니다. 흐름 매칭 손실은 샘플링된 객체, 노이즈, 타임스텝에 따라 달라지므로 미학습 객체에 대해서도 출력을 비교해야 합니다.
9개의 미학습 객체에서 파인튜닝된 모델은 참조 스캔에 더 가까운 밑창을 생성했습니다. 가이드는 다음과 같은 평균 지표를 보고합니다:
| 지표 | 기본 모델 | 신발 어댑터 사용 | 방향 |
|---|---|---|---|
| F-score @ 0.02 | 0.276 | 0.803 | 높을수록 좋음 |
| Chamfer distance | 0.174 | 0.033 | 낮을수록 좋음 |
| Normal consistency | 0.530 | 0.804 | 높을수록 좋음 |
F-score @ 0.02는 스캔 바운딩 박스 대각선의 2% 매칭 임계값에서 정밀도와 재현율을 결합합니다. Chamfer distance는 한 표면의 점에서 다른 표면의 가장 가까운 점까지의 거리를 양방향으로 측정합니다. Normal consistency는 표면 방향이 얼마나 일치하는지 측정합니다.
두 어댑터를 모두 사용하면 9개의 모든 미학습 객체에서 F-score가 더 좋습니다.
실전 교훈 및 향후 방향
이 가이드의 주요 교훈은 학습 목표가 문제 및 가용 데이터와 일치해야 한다는 것입니다. 신발 실험의 경우, 텍스처 학습에 필요한 재질 맵이 데이터셋에 부족했기 때문에 텍스처 단계는 고정하고 구조 및 형태 단계를 파인튜닝했습니다.
주요 교훈은 문제 및 보유한 데이터와 일치하는 학습 목표를 선택하는 것입니다.
이 가이드는 동일한 선택이 Pixal3D 및 UniLat3D와 같은 다른 3D 생성 모델에도 도움이 되는지 테스트할 것을 제안합니다. 또한 HunyuanWorld 2.0 및 NVIDIA Lyra 2.0과 같은 가우시안 스플랫(Gaussian-splat) 및 세계 생성 모델을 가능한 다음 단계로 식별합니다. 이러한 모델은 서로 다른 표현과 학습 파이프라인을 사용하므로 다른 파인튜닝 방법이 필요할 수 있습니다.