解決できる課題 事業紹介トップ 経営データ分析基盤 AI導入・業務改善 AI 業務アプリ 基幹システムのWeb化・段階移行 複雑な SaaS を専用 UI に Shopify Plus 移行・拡張 生成AI 活用(Multi AI) SEO / AIO / 広告運用 顧問・アドバイザリ インフラ構築 PHP脆弱性対策・更新 WordPressからEmDashへの移行 自社メディア投資・開発
AI導入 AI導入・業務改善 ChatGPTの社内導入 OpenAI Codex導入 AI運用・定着 Claude / MCP 総合 Claude Cowork Claude Code 導入支援 Claude Code 使いこなし支援 Claude Design MCP 開発・サーバー構築
EC構築・移行 Shopify Plus トップ EC-CUBEからShopifyへの移行 大手カートからの移行 Shopify 通常プラン EC サイト構築
実績
業界ニュース 業界ニュース トップ AI ニュース └ Claude └ ChatGPT・Codex └ Gemini └ その他 Shopify ニュース SaaS ニュース お知らせ(自社発信)
会社情報 相談する
2026.11.14

TRELLIS.2のLoRAファインチューニング完全ガイド(Hugging Face)

記事のサマリー(TL;DR)

  • Hugging Faceは、3Dモデル「TRELLIS.2」を自前の3DアセットでファインチューニングするためのスクリプトとDockerコンテナを公開しました。ローカル環境でもHugging Face Jobs上でも実行できます。
  • Google Scanned Objects(GSO)データセットから188点の靴(footwear)オブジェクトを使い、LoRA(低ランク適応)アダプターをTRELLIS.2のSparse-Structure Flow DiTとShape Flow DiTの2つのコンポーネントに追加して学習しました。テクスチャ(材質)を生成するtexture flow DiTは凍結(フリーズ)し、ファインチューニングの対象から外しています。
  • 9件のホールドアウト(学習未使用)オブジェクトで評価した結果、平均F-score@0.02はベースモデルの0.276からLoRA適用後0.803に、Chamfer distanceは0.174から0.033に、normal consistencyは0.530から0.804に変化したと報告されています。

利用条件・事前準備

ファインチューニングを実行する前に、以下が必要とされています。

  • Hugging FaceのHF_TOKEN(取得ページから入手可能)
  • DINOv3へのアクセス権を持つHugging Faceアカウント(DINOv3はgated modelのため)
  • 自前データセットを使う場合は、事前にメッシュデータをHugging Face Hubにアップロードしておくこと

詳細

背景:3D生成における課題

3D生成はロボティクス、シミュレーション、メディア、エンターテインメントなど多くの分野で利用されていますが、生成物を厳密なルールに従わせることや、モデル・データ表現を標準化することは難しいとされています。GLBやPLYといった複数のファイル形式、NeRF(ニューラル放射界)や3D Gaussian Splatting(3DGS)といった複数の表現方式が存在し、それぞれに利点と欠点があります。

TRELLISは、これらを統一的に扱うための共通の内部表現「unified latent representation」を導入しました。デコーダーがこの表現を必要な出力形式の3Dモデルに変換するため、表現形式ごとに異なるモデルを用意する必要がなくなります。同じチームが後継のTRELLIS.2をリリースし、3D構造の表現を改善しましたが、どちらのモデルも特定タスクへの適応を容易にする手段は備えていませんでした。

改善したい点

TRELLIS.2のような汎用モデルは、特定用途で重要となる細部を誤ることがあります。例えば家具モデルで正確なジオメトリが必要な場合、ファインチューニングなしの事前学習済みモデルでは精度が不十分なジオメトリが生成されることがあるとしています。

今回の実験では、GSOのサブセットである188点の靴オブジェクトを使用しました。初期テストでは、事前学習済みモデルは見た目が正しい靴を生成するものの、ソール(靴底)の形状が不正確になる傾向があったとのことです。この課題に対し、LoRAによってソールの精度を改善できるかを検証しています。

目標は、GSOデータセットを用いて特定の物体カテゴリーに対するTRELLIS.2の性能を改善することです。パイプラインは構造、詳細なジオメトリ、マテリアルを分離して扱うため、タスクに重要なコンポーネントのみをファインチューニングし、それ以外は変更しない方針を取っています。何を凍結するかは、何をファインチューニングするかと同じくらい重要だとしています。

使用する技術:LoRAとHugging Face Jobs

LoRA(Low-Rank Adaptation)は、元の重みを凍結したまま小さなアダプター行列を学習することでモデルをファインチューニングする手法です。学習可能なパラメータ数と、その勾配・オプティマイザ状態に必要なメモリを削減できます。今回はHugging FaceのPEFTライブラリを使ってこれらのアダプターを追加・学習しています。

Hugging Face Jobsは、クラウドハードウェア上でコンテナ化されたワークロードを実行する仕組みで、前処理と学習の両方に使用されています。自前のGPUを使う場合は、ローカルのDockerコマンドを利用します。

TRELLIS.2の仕組み

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

入力画像のエンコード:まずBiRefNetが入力画像の背景を除去します。次にDINOv3-Lが画像を特徴トークンにエンコードし、生成モデルがこのトークンを使って3Dオブジェクトを導きます。

Sparse Structure Generation(Sparse Structure Flow):sparse-structure flow DiT(拡散トランスフォーマー)がオブジェクトの粗い形状を予測し、サイズ16³×8の小さな潜在表現を生成します。これをVAE(変分オートエンコーダー)デコーダーが64×64×64のoccupancyグリッドに変換します。各ボクセル(3次元のピクセル)がその位置がオブジェクトの一部かどうかを示します。この段階の出力がジオメトリ生成を導くため、ここにLoRAアダプターを追加しています。

O-VoxelとStructured Latents:O-VoxelはTRELLIS.2の3D形式で、オブジェクト表面のボクセルのみを保持するスパース(疎)なボクセルグリッドです。各ボクセルはメッシュ頂点などの局所的なジオメトリとマテリアル属性を保持します。形式が小さいため、CPUでメッシュをO-Voxelに変換するのに数秒、GPUでO-Voxelをメッシュに戻すのに数秒かかるとしています。Structured sparse latentsはTRELLIS由来で、3Dデータをスパーステンソルとして保持することで計算を高速化します。グリッド内のボクセルのうち約10%しか使用しないため、空のボクセルに計算資源を費やさずに済むとされています。このため、shape flow DiTとtexture flow DiTはスパーストランスフォーマーであり、sparse-structure flow DiTは密なトランスフォーマーです。

ジオメトリ生成(Shape Flow):shape flow DiTは、occupancyグリッドとDINOv3の特徴トークンを使って潜在表現を生成します。別のVAEデコーダーがこれを512×512×512の解像度のO-Voxelジオメトリに変換します。このDiTはオブジェクトの形状を制御するため、ここにもLoRAアダプターを追加しています。

マテリアル生成とメッシュ作成:最終段階では、texture flow DiTが形状の潜在表現とDINOv3の特徴を入力として、ジオメトリ表面のマテリアルとテクスチャを定義します。VAEデコーダーが各ボクセルのベースカラー、メタリック、ラフネス、アルファ値に変換します。この段階にはLoRAアダプターを追加していません。理由は、使用データセットには拡散色(diffuse color)マップはあるものの、この段階の学習に必要な個別のマテリアルマップがないこと、また今回の課題が靴の「形状」であり、ベースモデルが既に良好な色とテクスチャを生成できているためです。最後に、パイプラインがジオメトリとマテリアル属性を結合してテクスチャ付きメッシュを作成し、GLBファイルとして出力します。

ファインチューニング対象の選定

LoRAアダプターはsparse-structure flow DiTとshape flow DiTにのみ追加し、オブジェクトの形状とジオメトリを制御するこれらのDiTを対象としています。texture flow DiTは現在の性能を維持するため凍結しています。使用データセットの拡散色マップには照明効果が焼き込まれており、texture flow DiTの学習には別個のマテリアルマップが必要です。色マップは表面の色と照明が混在しているため、学習の正しいターゲットにはならないとしています。これらのマップでtexture flow DiTを学習させると、照明を表面の属性として学習してしまったり、既に学習した内容を忘れてしまう「catastrophic forgetting(破滅的忘却)」が起きる可能性があるとしています。

LoRAを使う理由

今回使用したサブセットは、GSOの1,030オブジェクトのうち188点の靴です。このように小規模なデータセットには、フルファインチューニングよりLoRAの方が適しているとしています。フルファインチューニングはコストがはるかに高く、モデルが既に持つ学習済みの事前知識(prior)を上書きしてしまう可能性もあります。

今回の設定では、対象とする2つのDiT全体で約930万個のアダプターパラメータを学習しています。sparse-structure flow DiTのアテンション層とフィードフォワード(MLP)層にはランク8のアダプターを、shape flow DiTのアテンション層にはランク16のアダプターを使用しています。ランクはアダプター行列のサイズを決める値で、ランクが高いほどアダプターがより多くを学習できるとされています。

実行する内容

3Dモデルのセットアップには多くの依存関係とインストール手順が必要になり得ます。そのため、必要なソフトウェアを含む2つのDockerイメージ(前処理用と、ファインチューニング用)が提供されています。これらはHugging Face Jobsでも自前のマシンでも実行できます。

LoRAアダプターを学習してHubにアップロードする手順は次の通りです。

  1. コンテナにデータへのアクセス権を与える
  2. タスクに応じたパラメータを設定する
  3. 前処理用コンテナを実行する
  4. ファインチューニング用コンテナを実行する

実験の概要

実験は3つのパートに分かれます。

  1. データ準備:GLBまたはOBJ形式のメッシュを、TRELLIS.2が学習に使う潜在表現に変換し、入力画像をレンダリングする。
  2. アダプターの学習:準備済みデータセットとLoRA設定を用いて、各DiTにつき1つのジョブを実行する。
  3. コードの説明:コンテナがデータを読み込み、アダプターを追加し、モデルを学習する仕組みを確認する。

前処理済みデータセットは保存され、以降のすべての学習実行で再利用できるようにしています。

Hugging Face Jobsでの実行:前処理

前処理用コンテナはBlenderを使って各オブジェクトの16視点をレンダリングします。これらの視点はLoRA学習時の条件画像として使用されます。Blenderはxvfb-runユーティリティを通してディスプレイなしで実行されます。コンテナはまた、各オブジェクトを前処理パイプラインにかけます。188オブジェクトの全処理には、a100-largeジョブで約1時間かかったと報告されています。

export HF_TOKEN=hf_xxx
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

主な引数は以下の通りです。

  • -d:デタッチ実行。ジョブIDとURLを表示して処理を返す。進行状況はhf jobs logs -f <id>で確認。
  • --flavor a100-large:使用するハードウェア(80GB)。利用可能なオプションはhf jobs hardwareで確認できる。
  • --timeout 6h:指定時間でジョブが停止するが、再実行すれば再開できる。前処理は完了済みオブジェクトをスキップし、学習は--push-to先の最新チェックポイントから再開する。
  • --secrets HF_TOKEN:トークンを暗号化された環境変数としてジョブに渡す。イメージ自体には書き込まれない。
  • cr.hf.co/...:latest:実行するイメージ。その後に続くテキストがコンテナ内で実行されるコマンド。

このコンテナは、Hugging Face Jobsで実行する場合でもDockerで実行する場合でも、追加の引数を受け付けます。詳細は別途ドキュメント化されています。

LoRAファインチューニングの実行

学習用コンテナは、準備済みデータセットと設定プリセットまたは設定ファイルを読み込み、学習指標をTrackioで記録します。進行状況はTrackioダッシュボードで確認できます。

学習モードはssとshapeの2種類があり、ssはSparse-Structure Flow DiTのみを、shapeはShape Flow DiTのみをファインチューニングします。内部的には、それぞれ異なるconfig.jsonファイルを参照しています。

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

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を指定すると、コンテナはアダプターのチェックポイントをHubにアップロードします。

既に処理済みのデータセット(suvadityamuk/gso-footwear-trellis2-latents)を使ってすぐに試すためのコマンドも提供されています。構成はSparse-Structure Flow DiT用とShape Flow DiT用の2通りで、いずれも--set max_steps=3000 i_save=500を指定します。

ローカルDockerでの実行

Hugging Face Jobsと同じコマンド・フラグが使えますが、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
# 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

# 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

既に前処理済みのデータセットをローカルで使う場合も、同様に--set max_steps=3000 i_save=500を付けたコマンドが提供されています。学習済みのLoRAアダプターはリポジトリsuvadityamuk/trellis-2-finetune-gsoで公開されています。

学習パイプラインの内部

潜在表現への前処理:TRELLIS.2の凍結済みエンコーダーを使って入力メッシュを学習用の潜在表現に変換し、保存します。これにより以降の学習実行でメッシュを再エンコードする必要がなくなります。また、Blenderで各オブジェクトの16視点をレンダリングし、学習時には各サンプルについてランダムに1視点を条件画像として選択します。188オブジェクトのうち9点を評価用に残し、残り179点を学習に使用します。これらのホールドアウトオブジェクトにより、学習時に見ていないオブジェクトに対してアダプターが機能するかを確認できます。

データ設定では、FLOW変数が学習対象のflow DiT(ssまたはshape)を選択し、STEPSがオプティマイザのステップ数を設定します。バッチサイズ4と勾配累積ステップ4により、実効バッチサイズは16になります。続いて、選択したflow DiT用のLoRA設定ファイルを読み込み、TRELLIS.2形式のデータセットを作成し、ホールドアウトオブジェクトを除外して、ファインチューニング用のデータローダーを作成します。

LoRAアダプターの準備:peftライブラリを使って、選択した層にLoRAアダプターを挿入します。TRELLIS.2は独自のforward passを持つため、標準のPeftModel()ラッパーは使用できず、代わりにinject_adapter_in_model()を呼び出しています。この関数はモデルに直接アダプターを追加し、独自のインターフェースを維持します。学習可能なアダプターの重みは数値的安定性のため32ビット浮動小数点(fp32)で保持し、forward pass時にはbfloat16(bf16)のオートキャストを使用します。オートキャストは一部の演算で低精度を使うことでメモリ使用量を減らしますが、凍結されたバックボーンの重みの保存形式は変更しません。

学習:目的関数には、Stable Diffusion 3やFlux 2など画像生成モデルでも使われているrectified flow matchingを用いています。TRELLIS.2も事前学習で同じ目的関数を使用しているため、ファインチューニングに適しているとしています。学習ではsparse-structureとshapeの両DiTのLoRAパラメータのみを更新し、元のモデルの重みはすべて凍結したままです。

学習ループ内の主な手順は次の通りです。

  1. 各サンプルについてタイムステップtをサンプリングする(sparse-structure flow DiTにはlogitNormal、shape flow DiTには一様分布を使用。TRELLIS.2の設定に基づく)。
  2. データ形状に合わせたランダムノイズを生成し、ブロードキャスト用にtを整形する。
  3. tに基づいてクリーンデータとノイズを混合する(t=0がノイズ最小、t=1が純粋なノイズ)。
  4. 事前学習の条件に合わせるため、t×1000で速度を予測する。
  5. 予測速度とターゲット速度(x_tの一次微分)の平均二乗誤差として損失を計算する。

学習ループでは損失を計算してアダプター重みを更新します。勾配累積は、オプティマイザのステップ前に4つの小さいバッチの勾配を合算します。勾配チェックポインティングは、逆伝播時に一部の中間値を再計算することでGPUメモリを節約します。外側のループは指定されたオプティマイザステップ数だけ実行され、内側のループは一定数のバッチにわたって勾配を累積します。各バッチについて、DINOv3が条件画像をエンコードします。classifier-free guidance(CFG)ドロップアウトのため、ランダムな割合(p_uncond)のサンプルで条件をゼロに設定します。その後、bf16オートキャストでflow-matching損失を計算します。内側のループの後、勾配をクリッピングして過大な更新を防ぎ、オプティマイザのステップを実行します。損失は10ステップごとに記録され、アダプターのチェックポイントは500ステップごとに保存されます。

結果

sparse-structure DiT用とshape DiT用の2つのアダプターを学習しました。コンテナイメージ内のLoRA設定ファイル(sparse-structure flow DiT用のss_flow_lora_gso.json、shape flow DiT用のslat_flow_img2shape_lora_gso.json)に完全な学習設定が含まれています。各実行はHugging Face JobsのA100 80GBを1枚使用し、sparse-structureの実行には7.2時間、shapeの実行には3.6時間かかりました。

sparse-structure flow DiTの学習損失は最初に急速に低下し、その後はより緩やかに低下しました。shape flow DiTの損失はほぼ同じ水準で推移しました。これらの曲線は学習目的関数の変化を示すものであり、生成されたジオメトリの品質を直接測るものではないとしています。flow-matching損失はサンプルされたオブジェクト、ノイズ、タイムステップによって変動するため、ファインチューニングがジオメトリを改善するかどうかを確認するには、ホールドアウトオブジェクトでの出力比較も必要だとしています。

9件のホールドアウトオブジェクトのうち5件について、入力画像、ベースモデルの生成出力、回転調整後のベース出力、footwearアダプター適用後の出力、リファレンススキャンを比較した図が示されており、これらの例ではファインチューニング後のモデルのソールがスキャンに近づいているとしています。

ジオメトリの評価には以下の3つの指標を使用しています。

  • Chamfer distance:一方の表面上の点からもう一方の表面上の最も近い点までの距離を双方向で測定したもの。値が低いほど良い。
  • F-score @ 0.02:精度(生成された表面がどれだけリファレンスに近いか)と再現率(生成された表面がリファレンス表面をどれだけカバーしているか)の組み合わせ。マッチングのしきい値はスキャンのバウンディングボックス対角線の2%。値が高いほど良い。
  • Normal consistency:表面の法線方向(表面に垂直なベクトル)がどれだけ一致しているか。値が高いほど良い。

9オブジェクトの比較チャートでは、ベースモデルの平均F-scoreが0.276であるのに対し、footwearアダプターを適用したモデルでは0.803でした。Chamfer distanceは0.174から0.033に低下し、normal consistencyは0.530から0.804に上昇しました。両アダプターを適用した場合、9件のホールドアウトオブジェクトすべてでF-scoreが改善したとしています。全実行の統計はTrackio spaceで確認できるとしています。

今後の方向性

今回の取り組みでは、ジオメトリを制御する2つのモデルコンポーネントにLoRAアダプターを追加することで、靴の生成向けにTRELLIS.2をファインチューニングしました。データを一度準備し、アダプターをそれぞれ別のジョブで学習し、ホールドアウトオブジェクトで出力を評価しています。主な教訓は、課題と手元のデータに合った学習対象を選ぶことだとしています。

今回は構造とshapeの段階をファインチューニングし、テクスチャ段階は凍結しました。今後は、同様の選択がPixal3DやUniLat3Dなど他の3D生成モデルにも役立つかを検討できるとしています。また、HunyuanWorld 2.0やNVIDIA Lyra 2.0といったGaussian-splatやワールド生成モデルも次のステップの候補として挙げられていますが、それらの表現形式や学習パイプラインには異なる手法が必要になる可能性があるとしています。