LoRAを用いた3D生成モデルTRELLIS.2のファインチューニング:実践ガイド

要約: Hugging Faceは、3D生成モデルであるTRELLIS.2をLoRAを用いてカスタム3Dアセットに適応させるための実践的なガイド、スクリプト、およびDockerコンテナを公開しました。Google Scanned Objects(GSO)のフットウェア(靴)サブセット188個を用いた実験では、テクスチャ生成ステージを凍結したまま、ジオメトリを制御する2つのDiTのみをファインチューニングすることで、未知のオブジェクトに対するジオメトリの精度が大幅に向上しました。

Hugging Faceが公開したもの

Hugging Faceは、LoRAを使用してTRELLIS.2をファインチューニングするためのガイドと関連ツールを公開しました。このリリースには、ファインチューニング用スクリプトと2つのDockerコンテナが含まれています。1つは3DメッシュをTRELLIS.2の潜在変数(latents)に前処理するためのもの、もう1つはLoRAアダプターを学習するためのものです。これらのコンテナは、Dockerを使用してローカルで実行することも、Hugging Face Jobs上で実行することも可能です。

このガイドでは、Google Scanned Objectsデータセットのフットウェアを使用したエンドツーエンドの実験手順を解説しています。パイプラインのどのコンポーネントをファインチューニングし、どれを凍結すべきか、学習ループの仕組み、そして適応させたモデルが未知のオブジェクトに対してどのような性能を発揮するかについて説明しています。

関連リポジトリは suvadityamuk/trellis2-finetuning であり、学習済みアダプターは suvadityamuk/trellis-2-finetune-gso で公開されています。

なぜ3D生成モデルをファインチューニングするのか?

汎用的な3D生成モデルはもっともらしいオブジェクトを生成できますが、特定のアプリケーションで重要となる詳細部分で失敗することがあります。このガイドではフットウェアを例に挙げています。事前学習済みのTRELLIS.2モデルは、見た目は正しい靴を生成しますが、靴底の形状が不正確であることがよくありました。

この実験では、合計1,030個のオブジェクトを含むGSOから188個のフットウェアオブジェクトを使用しています。188個のうち9個を評価用に保持し、残りの179個を学習に使用しました。目標は、LoRAアダプターによって、未知のフットウェアオブジェクトに対しても靴底をより正確に生成できるかどうかを検証することです。

何を凍結し、何をファインチューニングするかを選択することは、非常に重要です。

TRELLIS.2の仕組み

TRELLIS.2は、画像の背景削除、画像のエンコード、粗い構造の予測、詳細なジオメトリの生成、マテリアルの生成という5つの主要なステージを経て3Dオブジェクトを生成します。パイプラインは最終的に、テクスチャ付きメッシュとして結果を出力します。

画像エンコーディング

BiRefNetが入力画像から背景を削除します。その後、DINOv3-Lが画像を特徴トークンにエンコードします。生成モデルはこれらのトークンを使用して3Dオブジェクトをガイドします。

疎な構造(Sparse structure)の生成

疎な構造のフローDiTは、オブジェクトの粗い形状を予測します。これは、16³ × 8サイズの小さな潜在変数を生成する拡散トランスフォーマーです。その後、VAEデコーダーがこの潜在変数を64 × 64 × 64の占有グリッド(occupancy grid)に変換します。グリッド内の各ボクセルは、その場所がオブジェクトの一部であるかどうかを示します。

このガイドでは、このモデルの出力がジオメトリステージをガイドするため、このモデルにLoRAアダプターを追加しています。

O-Voxelと構造化潜在変数

O-VoxelはTRELLIS.2で使用される3Dフォーマットです。これは、オブジェクトの表面にあるボクセルのみを保持する疎なボクセルグリッドです。各ボクセルは、メッシュの頂点やマテリアル属性などの局所的なジオメトリを格納します。CPUは数秒でメッシュをO-Voxelに変換でき、GPUは数秒でO-Voxelをメッシュに戻すことができます。

構造化された疎な潜在変数はTRELLISから得られます。これらは3Dデータを疎なテンソルとして保持するため、計算が高速化されます。モデルはグリッド内のボクセルの約10%しか使用しないため、空のボクセルに計算リソースを費やすことはありません。形状フローDiTとテクスチャフローDiTは疎なトランスフォーマーですが、疎な構造フローDiTは密なトランスフォーマーです。

ジオメトリ生成

形状フローDiTは、占有グリッドとDINOv3特徴トークンを使用して潜在変数を生成します。別のVAEデコーダーがこの潜在変数を512 × 512 × 512の解像度のO-Voxelジオメトリに変換します。

このガイドでは、オブジェクトの形状を制御するため、このDiTにLoRAアダプターを追加しています。

マテリアル生成とメッシュ作成

テクスチャフローDiTは、形状の潜在変数とDINOv3特徴を入力として使用します。これはジオメトリ表面のマテリアルとテクスチャを定義します。VAEデコーダーが潜在変数を各ボクセルのベースカラー、メタリック、ラフネス、アルファ値に変換します。

このガイドでは、このステージにはLoRAアダプターを追加していません。フットウェアデータセットには拡散反射カラーマップはありますが、テクスチャフローDiTを学習させるために必要な個別のマテリアルマップが不足しているためです。ベースモデルはすでに良好な色とテクスチャを生成しており、今回対処している問題は靴の形状だからです。

最後に、パイプラインはジオメトリとマテリアル属性を組み合わせてテクスチャ付きメッシュを作成し、GLBファイルとしてエクスポートします。

何をファインチューニングし、何を凍結するか

このガイドでは、疎な構造フローDiTと形状フローDiTにのみLoRAアダプターを追加しています。これら2つのDiTがオブジェクトの形状とジオメトリを制御するためです。テクスチャフローDiTは、既存の能力を維持するために凍結されています。

利用可能な拡散反射カラーマップでテクスチャフローDiTを学習させることは、それらのマップに焼き付けられた照明効果が含まれているため問題があります。データセットには個別のマテリアルマップが提供されていません。もしテクスチャモデルを拡散反射マップで学習させると、照明を表面のプロパティとして表現することを学習してしまう可能性があります。また、以前に学習した内容を忘れてしまう「破滅的忘却」という問題も発生する可能性があります。

フットウェアのサブセットはGSOから抽出された188個と小さいため、完全なファインチューニングよりもLoRAが推奨されます。完全なファインチューニングはコストがはるかに高く、モデルが学習した事前知識を上書きしてしまう可能性があります。このガイドの設定では、ターゲットとなる両方のDiT全体で合計約930万個の学習可能なアダプターパラメーターを学習します。

LoRA設定では、疎な構造フローDiTのアテンション層とフィードフォワードMLP層にランク8のアダプターを使用しています。形状フローDiTのアテンション層にはランク16のアダプターを使用しています。ランクはアダプター行列のサイズを設定します。ランクが高いほど、アダプターはより多くのことを学習できます。

学習パイプラインの内部

潜在変数への前処理

前処理コンテナはBlenderを使用して、各オブジェクトの16方向のビューをレンダリングします。これらのビューは、LoRA学習中の条件付け画像として機能します。Blenderは xvfb-run ユーティリティを介してディスプレイなしで実行されます。コンテナは、各オブジェクトをTRELLIS.2の前処理パイプラインに通します。

パイプラインはTRELLIS.2の凍結されたエンコーダーを使用して、入力メッシュを学習用の潜在変数に変換します。後でメッシュを再エンコードする必要がないように、これらの潜在変数を保存します。学習中、各サンプルに対して条件付け画像としてランダムなビューが1つ選択されます。

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の自動キャストを使用しており、これによりPyTorchは一部の操作で低精度を使用でき、メモリ使用量を削減できます。自動キャストは、凍結されたバックボーンの重みの保存方法を変更するものではありません。

学習目的関数とループ

学習の目的関数は、TRELLIS.2が事前学習中に使用したものと同じ「rectified flow matching」です。このガイドでは、この目的関数がStable Diffusion 3やFlux 2などの画像生成モデルでも使用されていることに言及しています。

学習ループは、疎な構造DiTと形状DiTのLoRAパラメーターのみを更新します。元のモデルの重みはすべて凍結されたままです。オプティマイザーはAdamWで、ベータ値は (0.9, 0.95) に設定されています。

各サンプルに対して、ループはタイムステップ t をサンプリングします。疎な構造フローDiTはロジット正規タイムステップスケジュールを使用し、形状フローDiTはTRELLIS.2の設定に基づいて均一スケジュールを使用します。ループはデータ形状に一致するランダムノイズを生成し、t に基づいてクリーンなデータとノイズを混合し、事前学習条件に一致するように t × 1000 での速度を予測し、予測速度とターゲット速度の間の平均二乗誤差として損失を計算します。

学習設定では、バッチサイズ4と4ステップの勾配蓄積を使用し、実効バッチサイズは16になります。勾配チェックポインティングは、バックプロパゲーション中に一部の中間値を再計算することでGPUメモリを節約します。分類器フリーガイダンスのドロップアウトについては、ループはサンプルのランダムな割合に対して条件付けをゼロに設定します。勾配蓄積後、勾配をクリップし、オプティマイザーのステップを実行します。10ステップごとに損失をログに記録し、500ステップごとにアダプターのチェックポイントを保存します。

ジョブの実行

このガイドでは、前処理用に cr.hf.co/suvadityamuk/trellis2-finetuning-prep:latest、学習用に cr.hf.co/suvadityamuk/trellis2-finetuning-train:latest という2つのコンテナイメージを提供しています。同じコマンドとフラグがHugging Face JobsとローカルのDockerで機能します。異なるのはDockerオプションのみです。

実行前に、DINOv3はゲート付きモデルであるため、ユーザーはDINOv3へのアクセス権を持つHugging Faceトークンが必要です。カスタムデータセットを使用する場合は、最初にメッシュを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 という2つのモードをサポートしています。各モードは異なる設定ファイルを参照します。コンテナはTrackioで学習メトリクスを記録し、--push-to が設定されている場合は、アダプターのチェックポイントをHugging Face Hubにアップロードします。

どちらのHugging Face Jobsコマンドも再開をサポートしています。前処理はすでに完了しているオブジェクトをスキップし、学習は --push-to リポジトリ内の最新のチェックポイントから継続されます。

結果

このガイドでは、疎な構造DiT用と形状DiT用の2つのアダプターを学習しました。各実行にはHugging Face Jobs上のA100 80 GB 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などのガウシアンスプラットや世界生成モデルを、次のステップとして特定しています。これらのモデルは異なる表現と学習パイプラインを使用しているため、異なるファインチューニング手法が必要になる可能性があります。

Sources