
خلاصه: در این مطلب، اسکریپتها و کانتینرهایی را برای تنظیم دقیق TRELLIS.2 در اختیارتان میگذاریم؛ TRELLIS.2 یکی از مدلهای محبوب تولید سهبعدی است و با این ابزارها میتوانید آن را روی داراییهای سهبعدی خودتان تنظیم دقیق کنید. این کار هم بهصورت محلی و هم روی Hugging Face Jobs اجرا میشود. اگر به تنظیم دقیق علاقه دارید، میتوانید اسکریپتهای ما را با چند آرگومان ساده اجرا کنید (به شرط آنکه مجموعهدادهتان را در Hugging Face Hub بارگذاری کرده باشید) یا خودتان با این مخزن کد آنها را دستکاری کنید. اگر میخواهید بیشتر بدانید، در ادامه توضیح میدهیم که اسکریپت چطور کار میکند. بزن بریم!
مقدمه
تولید سهبعدی کاربردهای زیادی در رباتیک، شبیهسازی، رسانه و سرگرمی دارد. در این حوزهها، واداشتن اشیای تولیدشده به رعایت قواعد سختگیرانه و یکسانسازی نمایش مدل و داده کار دشواری است. قالبهای فایل زیادی مثل GLB و PLY وجود دارد. نمایشهای متنوعی هم هست، مثل میدانهای تابشی عصبی (NeRF) و اسپلَتینگ گاوسی سهبعدی (3DGS). هر کدام مزایا و معایب خودشان را دارند.
TRELLIS یک نمایش درونی مشترک به نام نمایش نهفتهٔ یکپارچه معرفی کرد. رمزگشاهای آن این نمایش را به مدل سهبعدی در قالب خروجی موردنیاز تبدیل میکنند. بنابراین لازم نیست برای هر قالب نمایش، از مدل جداگانه استفاده کنید.
همان تیم بعداً TRELLIS.2 را منتشر کرد که نمایش ساختار سهبعدی را در مدل بهبود میدهد. اما هیچکدام از این دو مدل راه سادهای برای انطباق با یک کار مشخص ارائه نمیدهند.
چه چیزی را میخواهیم بهبود دهیم
یک مدل همهمنظوره مثل TRELLIS.2 میتواند در جزئیاتی که برای یک کاربرد خاص مهماند خطا کند. برای نمونه، کاربری ممکن است به هندسهٔ دقیق مدلهای مبلمان نیاز داشته باشد. بدون تنظیم دقیق برای آن کار، مدل از پیش آموزشدیده میتواند هندسهای با دقت ناکافی تولید کند. در آزمایش ما از زیرمجموعهای از GSO استفاده میکنیم که ۱۸۸ شیء کفش دارد. در آزمونهای اولیه، مدل از پیش آموزشدیده معمولاً کفشهایی تولید میکرد که ظاهر درستی داشتند، اما کفیشان نادرست بود. بررسی میکنیم آیا LoRA میتواند دقت کفیها را بیشتر کند.

هدف ما این است که با استفاده از مجموعهداده Google Scanned Objects (GSO)، عملکرد TRELLIS.2 را روی یک دستهٔ مشخص از اشیا بهبود دهیم. توضیح میدهیم کدام مؤلفههای خط لوله را تنظیم دقیق میکنیم و کدام را در طول آموزش بدون تغییر میگذاریم. این خط لوله ساختار، هندسهٔ دقیق و مواد را از هم جدا میکند. بنابراین فقط مؤلفههایی را تنظیم دقیق میکنیم که برای کار ما اهمیت دارند.

انتخاب اینکه چه چیزی را ثابت نگه داریم به اندازهٔ انتخاب اینکه چه چیزی را تنظیم دقیق کنیم مهم است.
از چه ابزارهایی استفاده میکنیم؟
LoRA
LoRA، کوتاهشدهٔ «سازگاری کمرتبه»، مدل را با آموزش ماتریسهای آداپتر کوچک تنظیم دقیق میکند و در این حین وزنهای اصلی ثابت میمانند. این روش تعداد پارامترهای آموزشپذیر و حافظهٔ لازم برای گرادیان و وضعیت بهینهساز آنها را کاهش میدهد. برای افزودن و آموزش این آداپترها از کتابخانهٔ PEFT شرکت Hugging Face استفاده میکنیم. برای اطلاعات بیشتر، راهنمای LoRA ما را بخوانید.
Hugging Face Jobs
Hugging Face Jobs بارهای کاری کانتینری را روی سختافزار ابری اجرا میکند. ما از آن هم برای پیشپردازش و هم برای آموزش استفاده میکنیم. اگر میخواهید از GPU خودتان استفاده کنید، دستورهای محلی Docker را در ادامه ببینید. پیش از شروع مطمئن شوید که این موارد را دارید:
یک HF_TOKEN که میتوانید از اینجا بگیرید
حساب Hugging Face شما باید به DINOv3 دسترسی داشته باشد، چون DINOv3 یک مدل gated است
اگر از مجموعهدادهٔ خودتان استفاده میکنید، پیش از شروع مشهای آن را در Hub بارگذاری کنید.
TRELLIS.2 چطور کار میکند
پیش از آموزش، ببینیم TRELLIS.2 چطور یک شیء سهبعدی تولید میکند و آداپترهای LoRA را کجا اضافه میکنیم.
TRELLIS.2 پنج مرحلهٔ اصلی دارد: حذف پسزمینهٔ تصویر، رمزگذاری تصویر، پیشبینی ساختار درشت، تولید هندسهٔ دقیق و تولید مواد. سپس خط لوله نتیجه را بهصورت یک مش بافتدار خروجی میدهد.

رمزگذاری تصویر ورودی
ابتدا BiRefNet پسزمینه را از تصویر ورودی حذف میکند. سپس DINOv3-L تصویر را به توکنهای ویژگی رمزگذاری میکند. مدلهای تولید از این توکنها برای هدایت شیء سهبعدی استفاده میکنند.

تولید ساختار تنک (Sparse Structure Flow)

DiT جریان ساختار تنک، شکل درشت شیء را پیشبینی میکند. این مدل یک ترانسفورمر انتشار (DiT) است که یک نمایش نهفتهٔ کوچک به ابعاد 16³ × 8 میسازد. سپس رمزگشای یک خودرمزگذار متغیر (VAE) این نمایش نهفته را به شبکهٔ اشغال 64 × 64 × 64 تبدیل میکند. هر وکسل در این شبکه نشان میدهد که آن نقطه بخشی از شیء است یا نه. وکسل همان پیکسل سهبعدی است. به این مدل آداپترهای LoRA اضافه میکنیم، چون خروجی آن مرحلهٔ هندسه را هدایت میکند.
O-Voxel و نمایشهای نهفتهٔ ساختاریافته
O-Voxel قالب سهبعدی TRELLIS.2 است. یک شبکهٔ وکسل تنک است که فقط وکسلهای روی سطح شیء را نگه میدارد. هر وکسل هندسهٔ محلی، مثل یک رأس مش، و ویژگیهای مواد را حفظ میکند. چون این قالب کوچک است، CPU در چند ثانیه یک مش را به O-Voxel تبدیل میکند. GPU هم در چند ثانیه O-Voxel را به مش برمیگرداند.

نمایشهای نهفتهٔ تنک ساختاریافته از TRELLIS میآیند. دادههای سهبعدی را در تنسورهای تنک نگه میدارند که محاسبه را سریعتر میکند. مدل فقط حدود ۱۰٪ از وکسلهای شبکه را استفاده میکند، بنابراین محاسبات را صرف وکسلهای خالی نمیکند. به همین دلیل DiT جریان شکل و DiT جریان بافت، ترانسفورمرهای تنک هستند. DiT جریان ساختار تنک اما یک ترانسفورمر متراکم است.
تولید هندسه (Shape Flow)
DiT جریان شکل از شبکهٔ اشغال و توکنهای ویژگی DINOv3 برای ساختن یک نمایش نهفته استفاده میکند. سپس رمزگشای VAE دیگری این نمایش نهفته را به هندسهٔ O-Voxel با تفکیک 512 × 512 × 512 تبدیل میکند.
به DiT این مرحله آداپترهای LoRA اضافه میکنیم، چون شکل شیء را کنترل میکند.

تولید مواد + ساخت مش
در مرحلهٔ آخر، DiT جریان بافت از نمایش نهفتهٔ شکل و ویژگیهای DINOv3 بهعنوان ورودی استفاده میکند. مواد و بافتهای سطح هندسه را تعیین میکند. سپس رمزگشای VAE نمایش نهفته را به مقادیر رنگ پایه، فلزیبودن، زبری و آلفا برای هر وکسل تبدیل میکند. به این مرحله آداپتر LoRA اضافه نمیکنیم. مجموعهدادهٔ ما نقشههای رنگ پخشی (diffuse) دارد، اما نقشههای مواد جداگانهای را که این مرحله برای آموزش لازم دارد ندارد. از طرفی مشکل ما شکل کفش است. مدل پایه از قبل رنگها و بافتهای خوبی میسازد.
در پایان، خط لوله ویژگیهای هندسه و مواد را در یک مش بافتدار ترکیب میکند و آن را بهصورت فایل GLB خروجی میدهد.

برنامهریزی
کدام مؤلفهها را تنظیم دقیق کنیم
آداپترهای LoRA را فقط به DiT جریان ساختار تنک و DiT جریان شکل اضافه میکنیم. این DiTها شکل و هندسهٔ شیء را کنترل میکنند. DiT جریان بافت را ثابت نگه میداریم تا تواناییهای فعلیاش حفظ شود.
مجموعهدادهٔ ما نقشههای رنگ پخشی دارد که جلوههای نورپردازی پختهشده در آنها گنجانده شده است. برای آموزش DiT جریان بافت به نقشههای مواد جداگانه نیاز داریم. نقشههای رنگ در مجموعهدادهٔ ما رنگ سطح را با نورپردازی مخلوط میکنند. بنابراین هدف درستی برای این آموزش نیستند.
اگر DiT جریان بافت را با این نقشهها آموزش دهیم، ممکن است یاد بگیرد نورپردازی را بهعنوان ویژگی سطح نمایش دهد. همچنین ممکن است آموختههای قبلیاش را از دست بدهد؛ مشکلی که به آن فراموشی فاجعهبار میگویند.
چرا از LoRA استفاده کنیم
زیرمجموعهٔ ما ۱۸۸ کفش از ۱۰۳۰ شیء GSO را شامل میشود. برای مجموعهدادهای به این کوچکی، LoRA انتخاب بهتری از تنظیم دقیق کامل است. تنظیم دقیق کامل بسیار پرهزینهتر است. همچنین میتواند آنچه مدل از قبل خوب انجام میدهد (پیشفرضهای آموختهشدهاش) را از بین ببرد. پیکربندی ما در مجموع حدود ۹.۳ میلیون پارامتر آداپتر را برای هر دو DiT هدفگذاریشده آموزش میدهد. در لایههای توجه و پیشخور (MLP) DiT جریان ساختار تنک از آداپترهای رتبهٔ ۸ استفاده میکنیم. در لایههای توجه DiT جریان شکل از آداپترهای رتبهٔ ۱۶ استفاده میکنیم. رتبه اندازهٔ ماتریسهای آداپتر را تعیین میکند. رتبهٔ بالاتر به آداپتر اجازه میدهد بیشتر یاد بگیرد.
چه چیزی را اجرا میکنید
راهاندازی یک مدل سهبعدی میتواند به وابستگیها و مراحل نصب زیادی نیاز داشته باشد. ما دو ایمیج Docker در اختیارتان میگذاریم (که میتوانید روی Jobs یا روی دستگاه خودتان اجرا کنید) که نرمافزارهای لازم را دارند. یکی برای پیشپردازش و دیگری برای تنظیم دقیق است.
برای آموزش آداپترهای LoRA و بارگذاری آنها در Hub:
به کانتینرها دسترسی به دادههایتان بدهید.
پارامترهای کارتان را تنظیم کنید.
کانتینر پیشپردازش را اجرا کنید.
کانتینر تنظیم دقیق را اجرا کنید.
سپس اسکریپت تنظیم دقیق، تنظیماتش و تأثیر هر تنظیم بر آموزش را توضیح میدهیم.
نمای کلی آزمایش
سه بخش آزمایش را مرور میکنیم:
آمادهسازی داده. مشهای GLB یا OBJ را به نمایشهای نهفتهای تبدیل کنید که TRELLIS.2 برای آموزش استفاده میکند و تصاویر ورودی را رندر کنید.
آموزش آداپترها. برای هر DiT یک کار جداگانه با مجموعهدادهٔ آمادهشده و یک پیکربندی LoRA اجرا کنید.
توضیح کد. بررسی کنید که کانتینرها چطور داده را بارگذاری میکنند، آداپترها را اضافه میکنند و مدلها را آموزش میدهند.
مجموعهدادهٔ پیشپردازششده را ذخیره میکنیم تا همهٔ اجراهای آموزش بتوانند از آن دوباره استفاده کنند.
راهنمای گامبهگام
اجرا روی Hugging Face Jobs
پیشپردازش
کانتینر پیشپردازش با استفاده از Blender از هر شیء ۱۶ نما رندر میکند. آموزش LoRA از این نماها بهعنوان تصاویر شرطیساز استفاده خواهد کرد. Blender بدون نمایشگر و از طریق ابزار xvfb-run اجرا میشود. کانتینر همچنین هر شیء را از خط لولهٔ پیشپردازش عبور میدهد. برای نمونهای از خروجی میانی، مجموعهدادهٔ کفش را اینجا ببینید. برای ۱۸۸ شیء ما، اجرای کامل روی یک کار a100-large حدود ۱ ساعت طول کشید. نسخهٔ فشردهای از خط لولهٔ پیشپردازش هم در این مخزن همراه موجود است.
export HF_TOKEN=hf_xxx
# Replace your-username with your Hugging Face username
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برای Hugging Face Jobs، این آرگومانها را میفرستیم:
پرچم | معنی
-d | جدا شدن (Detach): شناسه و نشانی کار را چاپ میکند و برمیگردد. برای پیگیری کار، دستور hf jobs logs -f <id> را اجرا کنید
--flavor a100-large | سختافزار. ما از a100-large (۸۰ گیگابایت) استفاده میکنیم. برای دیدن همهٔ گزینهها، دستور hf jobs hardware را اجرا کنید
--timeout 6h | کار پس از این مدت متوقف میشود. هر دو دستور از سر گرفته میشوند. پیشپردازش اشیای تمامشده را رد میکند. آموزش از جدیدترین چکپوینت در --push-to ادامه مییابد
--secrets HF_TOKEN | توکن شما (از HF_TOKEN یا hf auth login) را بهصورت متغیر محیطی رمزگذاریشده به کار میفرستد. توکن در ایمیج نوشته نمیشود
cr.hf.co/...:latest | ایمیجی که اجرا میشود. تمام متن بعد از آن، دستوری است که در کانتینر اجرا میشود
این کانتینر چند آرگومان دیگر هم میپذیرد (چه روی Hugging Face Jobs اجرا شود چه با Docker) که مستنداتشان را اینجا میتوانید ببینید. مراحل خط لولهٔ پیشپردازش در بخش مربوطه در ادامه توضیح داده شده است.
تنظیم دقیق با LoRA
کانتینر آموزش، مجموعهدادهٔ آمادهشده و یک پیکربندی از پیش تعیینشده یا فایل پیکربندی را بارگذاری میکند. معیارهای آموزش را با Trackio ثبت میکند. برای پایش اجرا از داشبورد Trackio استفاده کنید.
ما از «ss» و «shape» برای نشان دادن دو حالت آموزش LoRA استفاده میکنیم. حالت «ss» فقط DiT جریان ساختار تنک را تنظیم دقیق میکند، در حالی که حالت «shape» DiT جریان شکل را تنظیم دقیق میکند. در پشت صحنه، این دو حالت صرفاً به فایلهای config.json متفاوتی برای هر مرحله ارجاع میدهند. جزئیات بیشتر دربارهٔ این فرایند در بخش مربوطه در ادامه آمده است.
export HF_TOKEN=hf_xxx # Replace your-username with your Hugging Face username
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 بارگذاری میکند. کانتینر پارامترهایی میپذیرد که برای اختصار در همینجا مستند شدهاند. یک اسکریپت فشرده هم در همان مخزن موجود است.
اگر میخواهید با مجموعهدادهٔ از پیش پردازششدهٔ ما بازی کنید و تنظیم دقیق انجام دهید، میتوانید از مجموعه دستورهای زیر استفاده کنید.
export HF_TOKEN=hf_xxx
# Replace your-username with your Hugging Face username
# For the 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
# For the 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اجرا بهصورت محلی با Docker
دستورها و پرچمها همان دستورهای Hugging Face Jobs هستند. فقط گزینههای Docker متفاوت است.
# For preprocessing into latents
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# For 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
# For 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اگر میخواهید از مجموعهدادهٔ از پیش پردازششدهٔ ما بهصورت محلی روی دستگاه دلخواهتان استفاده کنید، از دستورهای زیر استفاده کنید:
export HF_TOKEN=hf_xxx # Replace your-username with your Hugging Face username
# For Sparse-structure Flow DiT
docker run --gpus all --rm --shm-size 16g -e HF_TOKEN \
-v hf-cache:/root/.cache/huggingface \
-v "$PWD/work":/workspace/work \
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 \
--trackio-space your-username/trellis2-trackio \
--set max_steps=3000 i_save=500
# For Shape Flow DiT
docker run --gpus all --rm --shm-size 16g -e HF_TOKEN \
-v hf-cache:/root/.cache/huggingface \
-v "$PWD/work":/workspace/work \
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 \
--trackio-space your-username/trellis2-trackio \
--set max_steps=3000 i_save=500آداپترهای LoRA آموزشدیدهٔ ما در این مخزن هستند: suvadityamuk/trellis-2-finetune-gso
درون خط لولهٔ آموزش
پیشپردازش به نمایشهای نهفته

از رمزگذارهای ثابت TRELLIS.2 برای تبدیل مشهای ورودی به نمایشهای نهفتهٔ آموزش استفاده میکنیم. این نمایشهای نهفته را ذخیره میکنیم تا اجراهای بعدی مجبور نباشند مشها را دوباره رمزگذاری کنند.
همچنین از هر شیء ۱۶ نما در Blender رندر میکنیم. در طول آموزش، برای هر نمونه یک نمای تصادفی را بهعنوان تصویر شرطیساز انتخاب میکنیم. ۹ شیء از ۱۸۸ شیء را برای ارزیابی نگه میداریم و روی ۱۷۹ شیء دیگر آموزش میدهیم. این اشیای نگهداشتهشده نشان میدهند که آیا آداپترها روی اشیایی که مدل در طول آموزش ندیده است کار میکنند یا نه.

برخی از نماهایی که Blender برای یک شیء رندر کرد
قطعهکد اول داده را آماده میکند. FLOW مشخص میکند کدام DiT جریان آموزش ببیند (ss یا shape) و STEPS تعداد گامهای بهینهساز را تعیین میکند. اندازهٔ دستهٔ ۴ با ۴ گام انباشت گرادیان، اندازهٔ دستهٔ مؤثر ۱۶ را میدهد. سپس قطعهکد فایل پیکربندی LoRA را برای DiT جریان انتخابشده بارگذاری میکند، مجموعهداده را در قالب TRELLIS.2 میسازد، اشیای نگهداشتهشده را حذف میکند و بارگذار داده را برای تنظیم دقیق میسازد.
cfg = json.load(
open(
{
"ss": "/workspace/TRELLIS.2/configs/lora/ss_flow_lora_gso.json",
"shape": "/workspace/TRELLIS.2/configs/lora/slat_flow_img2shape_lora_gso.json",
}[FLOW]
)
)
key, latents = {
"ss": ("ss_latent", "ss_latents/ss_enc_conv3d_16l8_fp16_64"),
"shape": ("shape_latent", "shape_latents/shape_enc_next_dc_f16c32_fp16_512"),
}[FLOW]
roots = json.dumps(
{
"gso": {
key: f"{DATA}/{latents}",
"render_cond": f"{DATA}/renders_cond",
"meta": DATA,
}
}
)
ds = getattr(datasets, cfg["dataset"])(roots, **cfg["dataset_args"])
holdout = set(open(f"{DATA}/holdout.txt").read().split())
ds.instances = [(root, sha) for root, sha in ds.instances if sha not in holdout]
batches = cycle(
DataLoader(
ds,
batch_size=BATCH,
shuffle=True,
drop_last=True,
num_workers=4,
collate_fn=getattr(ds, "collate_fn", None),
)
)آمادهسازی آداپترهای LoRA

از کتابخانهٔ PEFT برای درج آداپترهای LoRA در لایههای انتخابشده استفاده میکنیم. TRELLIS.2 یک گذر رو به جلو (forward pass) سفارشی دارد، بنابراین پوشش استاندارد PeftModel() کار نمیکند. در عوض، inject_adapter_in_model() را فراخوانی میکنیم. این تابع آداپترها را مستقیماً به مدل اضافه میکند و رابط سفارشی آن را حفظ میکند.
وزنهای آموزشپذیر آداپتر را برای پایداری عددی در ممیز شناور ۳۲ بیتی (fp32) نگه میداریم و برای گذر رو به جلو از ریختهگری خودکار bfloat16 (bf16) استفاده میکنیم. ریختهگری خودکار به PyTorch اجازه میدهد برای برخی عملیات از دقت پایینتر استفاده کند که مصرف حافظه را کاهش میدهد. ریختهگری خودکار نحوهٔ ذخیرهٔ وزنهای ثابت ستون فقرات را تغییر نمیدهد.
model = models.from_pretrained(cfg["ckpt"])
for block in model.blocks:
block.use_checkpoint = True
inject_adapter_in_model(
LoraConfig(
r=cfg["rank"], lora_alpha=cfg["alpha"], target_modules=cfg["lora_targets"]
),
model,
)
params = []
for name, p in model.named_parameters():
p.requires_grad_("lora_" in name)
if p.requires_grad:
p.data = p.data.float() # fp32 master weights for LoRA
params.append(p)
model.cuda().train()آموزش

نکتهٔ مهم این است که تابع هدف ما در اینجا همان تطبیق جریان اصلاحشدهٔ آشنای همیشگی است (همانطور که در مدلهای محبوب تولید تصویر مثل Stable Diffusion 3، Flux 2 و دیگران دیده میشود). TRELLIS.2 هم در پیشآموزش از همین تابع هدف استفاده کرده بود، بنابراین انتخاب خوبی برای تنظیم دقیق است. برای آشنایی با مبانی نظری، این مطلب دربارهٔ تطبیق جریان را بخوانید.
فقط پارامترهای LoRA در DiTهای ساختار تنک و شکل را بهروزرسانی میکنیم. همهٔ وزنهای اصلی مدل ثابت میمانند.
قطعهکدهای زیر حلقهٔ آموزش اصلی یک مرحله را نشان میدهند. آنها از کد کانتینر سادهترند و برخی مراحل راهاندازی را شامل نمیشوند. برای گردش کار کامل، از دستورهای کانتینر استفاده کنید.
بهینهساز را مقداردهی اولیه میکنیم و DINOv3 را برای استخراج ویژگی از تصاویر ورودی بارگذاری میکنیم.
opt = torch.optim.AdamW(
params, lr=cfg["lr"], weight_decay=cfg["weight_decay"], betas=(0.9, 0.95)
)
dino = DinoV3FeatureExtractor(
cfg["image_cond_model"], image_size=cfg["image_size"]
).cuda()سپس در حلقهٔ آموزش این مراحل را دنبال میکنیم:
برای هر نمونه یک گام زمانی t نمونهگیری میکنیم (بر اساس پیکربندی TRELLIS.2، برای DiT جریان ساختار تنک از logitNormal و برای DiT جریان شکل از توزیع یکنواخت استفاده میکنیم).
نویز تصادفی همشکل با داده تولید میکنیم و t را برای پخش (broadcasting) تغییر شکل میدهیم.
دادهٔ تمیز را بر اساس t با نویز مخلوط میکنیم (که در آن t = 0 داده با کمترین نویز و t = 1 نویز خالص است).
سرعت را در t × 1000 پیشبینی میکنیم تا با شرایط پیشآموزش هماهنگ باشد.
خطا را بهصورت میانگین مربعات خطا بین سرعت پیشبینیشده و سرعت هدف (مشتق اول x_t) محاسبه میکنیم.
def flow_loss(x0, cond):
s = cfg["t_schedule"]
t = (
torch.rand(x0.shape[0])
if s["name"] == "uniform"
else torch.sigmoid(
torch.randn(x0.shape[0]) * s["args"]["std"] + s["args"]["mean"]
)
)
t = t.cuda()
noise = (
x0.replace(torch.randn_like(x0.feats))
if cfg["sparse"]
else torch.randn_like(x0)
)
tv = t.view(-1, *[1] * (len(x0.shape) - 1))
x_t = (1 - tv) * x0 + (cfg["sigma_min"] + (1 - cfg["sigma_min"]) * tv) * noise
pred, target = model(x_t, t * 1000, cond), (1 - cfg["sigma_min"]) * noise - x0
return (
F.mse_loss(pred.feats, target.feats)
if cfg["sparse"]
else F.mse_loss(pred, target)
)حلقهٔ آموزش خطا را محاسبه میکند و وزنهای آداپتر را بهروزرسانی میکند. انباشت گرادیان، گرادیانهای ۴ دستهٔ کوچک را پیش از هر گام بهینهساز جمع میکند. چکپوینت گرادیان با بازمحاسبهٔ برخی مقادیر میانی در حین پسانتشار، حافظهٔ GPU را ذخیره میکند. حلقهٔ بیرونی برای تعداد مشخصی گام بهینهساز اجرا میشود، در حالی که حلقهٔ درونی گرادیانها را روی مجموعهای از دستهها انباشت میکند.
برای هر دسته، DINOv3 تصویر شرطیساز را رمزگذاری میکند. برای حذف در راهنمایی بدون طبقهبند (CFG)، حلقه شرطیسازی را برای کسری تصادفی (p_uncond) از نمونهها صفر میکند. سپس خطای تطبیق جریان را با ریختهگری خودکار bf16 محاسبه میکند. پس از حلقهٔ درونی، گرادیانها را برای جلوگیری از بهروزرسانیهای بسیار بزرگ برش میدهد و یک گام بهینهساز انجام میدهد. هر ۱۰ گام خطا را ثبت میکند و هر ۵۰۰ گام یک چکپوینت آداپتر ذخیره میکند.
for step in range(1, STEPS + 1):
for _ in range(ACCUM):
batch = next(batches)
x0 = recursive_to_device(batch["x_0"], "cuda")
with torch.no_grad():
cond = dino(batch["cond"])
cond[torch.rand(len(cond), device="cuda") < cfg["p_uncond"]] = 0
with torch.autocast("cuda", dtype=torch.bfloat16):
loss = flow_loss(x0, cond) / ACCUM
loss.backward()
torch.nn.utils.clip_grad_norm_(params, cfg["grad_clip"])
opt.step()
opt.zero_grad()نتایج
دو آداپتر آموزش دادیم: یکی برای DiT ساختار تنک و یکی برای DiT شکل. فایلهای پیکربندی LoRA در ایمیج کانتینر شامل تنظیمات کامل آموزش هستند: ss_flow_lora_gso.json برای DiT جریان ساختار تنک و slat_flow_img2shape_lora_gso.json برای DiT جریان شکل. هر اجرا از یک A100 80 گیگابایتی روی Hugging Face Jobs استفاده کرد. اجرای ساختار تنک ۷.۲ ساعت و اجرای شکل ۳.۶ ساعت طول کشید.

خطای آموزش DiT جریان ساختار تنک در ابتدا سریع کاهش مییابد و سپس آهستهتر. خطای DiT جریان شکل تقریباً در همان سطح میماند. این نمودارها نشان میدهند که تابع هدف آموزش چطور تغییر میکند، اما کیفیت هندسهٔ تولیدشده را مستقیماً اندازه نمیگیرند.
خطای تطبیق جریان با اشیای نمونهگیریشده، نویز و گامهای زمانی تغییر میکند. برای فهمیدن اینکه آیا تنظیم دقیق هندسه را بهبود میدهد، باید خروجیها را روی اشیای نگهداشتهشده هم مقایسه کنیم.
شکل زیر خروجیها را برای پنج شیء از ۹ شیء نگهداشتهشده مقایسه میکند. تصویر ورودی، خروجی تولیدشدهٔ مدل پایه، خروجی پایه پس از تنظیم چرخش، خروجی با آداپترهای کفش و اسکن مرجع را نشان میدهد. در این نمونهها، کفیهای مدل تنظیمدقیقشده به اسکنها نزدیکترند.

همچنین از سه معیار برای ارزیابی هندسه روی مجموعهٔ آزمون استفاده میکنیم:
معیار | معنی آن
فاصلهٔ Chamfer | فاصلهٔ نقاط یک سطح تا نزدیکترین نقاط سطح دیگر، که در هر دو جهت اندازهگیری میشود. کمتر بهتر است.
F-score @ 0.02 | ترکیب دقت (چه مقدار از سطح تولیدشده به مرجع نزدیک است) و فراخوانی (چه مقدار از سطح مرجع را سطح تولیدشده پوشش میدهد). در اینجا آستانهٔ تطبیق ۲٪ از قطر جعبهٔ محیطی اسکن است. بیشتر بهتر است.
Normal consistency | میزان همراستایی جهتهای سطح. نرمال سطح برداری عمود بر سطح است. بیشتر بهتر است.

در مقایسهٔ نهشیئی نمودار، مدل پایه میانگین F-score برابر ۰.۲۷۶ دارد، در مقابل ۰.۸۰۳ برای مدل با آداپترهای کفش. فاصلهٔ Chamfer از ۰.۱۷۴ به ۰.۰۳۳ کاهش مییابد و Normal consistency از ۰.۵۳۰ به ۰.۸۰۴ افزایش مییابد. با هر دو آداپتر، F-score روی هر ۹ شیء نگهداشتهشده بهتر است.
برای آمار همهٔ اجراها، این فضای Trackio را ببینید.
مسیرهای آینده
خب، کارمان تمام شد! ما TRELLIS.2 را برای تولید کفش با افزودن آداپترهای LoRA به دو مؤلفهٔ مدل که هندسه را کنترل میکنند تنظیم دقیق کردیم. داده را یک بار آماده کردیم، آداپترها را در کارهای جداگانه آموزش دادیم و خروجیها را روی اشیای نگهداشتهشده ارزیابی کردیم.
درس اصلی این است که هدف آموزش را هماهنگ با مشکل و دادهای که دارید انتخاب کنید. در این آزمایش، مراحل ساختار و شکل را تنظیم دقیق کردیم و مرحلهٔ بافت را ثابت نگه داشتیم.
در ادامه میتوانیم بررسی کنیم آیا همین انتخابها به مدلهای دیگر تولید سهبعدی مثل Pixal3D و UniLat3D هم کمک میکنند.
مدلهای اسپلَت گاوسی و تولید جهان، مثل HunyuanWorld 2.0 و NVIDIA Lyra 2.0، هم گامهای بعدی ممکن هستند. نمایشها و خط لولههای آموزش آنها میتواند به روشهای متفاوتی نیاز داشته باشد.
ممنون که همراه ما بودید، در مطلب بعدی میبینمتان! 👋🤗



