FLUX 3 Action

FLUX 3 Action memprediksi aksi robot dari pengamatan kamera, state, dan instruksi tugas. Video VAE dan text encoder yang dibekukan (frozen) memberi masukan ke diffusion transformer yang memprediksi video latents dan action chunks; hanya aksi yang dikembalikan saat inference. LeRobot mendukung inference dan PEFT: LoRA menyesuaikan trunk, sementara kepala aksi dan kondisioning robot dilatih secara penuh.

Kami menyediakan flux-3-action-base sebagai model aksi dasar, bersama dengan finetuning untuk robot SO-101 flux-3-action-so101 dan Franka Panda flux-3-action-droid (dihaluskan pada dataset DROID). Contoh utama di sini adalah adaptasi tugas melalui LoRA yang didasarkan pada model flux-3-action-so101.

Untuk melatih embodi robot baru dari model dasar atau melakukan finetuning penuh, gunakan repositori flux-action kami yang berdiri sendiri.

Instalasi

Dari checkout LeRobot, instal dependensi untuk pelatihan, kebijakan, PEFT, dan EMA:

pip install -e ".[training,flux3,peft,diffusion]"

Video VAE juga memerlukan wheel NATTEN yang kompatibel dengan torch/CUDA dari https://whl.natten.org. Untuk torch 2.11 dengan CUDA 12.8:

uv pip install natten==0.21.6+torch2110cu128 --find-links https://whl.natten.org

Gunakan natten==0.21.6+torch2100cu128 untuk torch 2.10, atau bangun untuk lingkungan Anda.

Adaptasi tugas SO-101

Gunakan dataset LeRobot v3 pada 30 Hz, dengan enam kanal aksi yang diperintahkan secara absolut dan enam kanal keadaan yang diukur dalam urutan dan satuan sendi yang sesuai. Gripper berada di urutan terakhir. Sediakan nilai mentah, kalibrasi robot yang konsisten, dan instruksi dalam task.

Kamera

Nama, jumlah, dan tata letak kamera dapat dikonfigurasi. Paket SO-101 memberi nama dua kameranya berdasarkan apa yang ditampilkan:

Anda dapat menggunakan --rename_map untuk memetakan nama kamera ke kunci yang diharapkan, misalnya:

--rename_map='{"observation.images.top":"observation.images.scene","observation.images.gripper_cam":"observation.images.wrist"}'

Gunakan pemetaan yang sama untuk rollout; kunci yang cocok tidak memerlukan peta. Lihat peta penamaan ulang.

Muat dan latih

Muat kebijakan SO-101 dari black-forest-labs/flux-3-action-so101. Konfigurasi yang disimpan secara otomatis memuat VAE bersama dan pengkode teks dari revisi yang dikunci dari black-forest-labs/flux-3-action-base. Jika akses dibatasi, autentikasi dengan hf auth login menggunakan akun yang memiliki akses. Jalankan dari checkout LeRobot:

lerobot-train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-so101 --policy.device=cuda \
  --dataset.repo_id=YOUR_ORG/YOUR_SO101_DATASET \
  --output_dir=outputs/so101_lora

Cache Hub menyimpan model yang diunduh dan encoder bersama untuk inferensi resume dan adapter.

Checkpoint SO-101-finetuned yang di-pin menggunakan kunci kamera scene / wrist, delapan langkah waktu observasi, dua snapshot visual yang dikodekan secara independen, serta kondisioning aksi/keadaan masa lalu. Checkpoint ini memprediksi 42 aksi, mengeksekusi 32 pertama pada 30 Hz, lalu merencanakan ulang. Prosesor yang disimpan membawa statistik normalisasi yang sesuai dengan basis. Pengaturan checkpoint ini dipertahankan selama adaptasi tugas. examples/flux3/lora.json bersama hanya menyediakan pengaturan pelatihan/runtime dan anggaran pelatihan; file yang sama dibundel sebagai lora.json di setiap paket Hub. Tata letak kamera, kondisioning, representasi aksi, dan pengaturan loss berasal dari checkpoint. Perintah ini mempertahankan panjang eksekusi tersimpan sebesar 32, guidance 3/3, dan eksekusi eager. Untuk guidance 4/1 dan kompilasi, tambahkan --policy.guidance_scale=4 --policy.guidance_scale_action=1 --policy.compile_model=true.

Eksperimen kondisioning: LeRobot mengekspos n_obs_steps, history_snapshots dan condition_on_past_actions. Mengubahnya memerlukan pengaturan model/processor yang kompatibel dan fine-tuning; pertahankan nilai yang disimpan pada checkpoint untuk adaptasi tugas biasa.

Preset ini mengaktifkan LoRA rank/alpha 32 dan EMA dengan decay 0.999; tidak ada yang diunggah secara otomatis. Aktifkan adaptor baru melalui pengaturan peft tingkat atas, bukan --policy.use_peft=true, yang mengidentifikasi adaptor yang disimpan.

Dalam eksperimen kami, EMA memberikan manfaat yang signifikan pada DROID, sementara hasil untuk SO-101 sejauh ini masih bervariasi. Manfaatnya bergantung pada data dan konfigurasi pelatihan. Kami merekomendasikan untuk tetap mengaktifkan EMA dan mengevaluasi checkpoint mentah serta checkpoint EMA di bawah protokol rollout yang sama sebelum memilih yang akan di-deploy. Validasi loss offline berkala menggunakan bobot mentah; validasi ini tidak membandingkan kedua varian secara otomatis.

Mulai dengan anggaran GPU tunggal untuk iterasi cepat. Untuk anggaran pelatihan yang lebih besar, gunakan konfigurasi yang sama dengan override berikut:

accelerate launch --num_processes=4 --multi_gpu -m lerobot.scripts.lerobot_train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-so101 --policy.device=cuda \
  --dataset.repo_id=YOUR_ORG/YOUR_SO101_DATASET \
  --batch_size=8 --steps=14000 \
  --output_dir=outputs/so101_lora_large

Batch efektif adalah GPU × batch per GPU × akumulasi. LeRobot menghitung steps, save_freq, dan eval_steps dalam microsteps; bagi dengan akumulasi untuk mendapatkan jumlah update optimizer. Preset menyimpan dan mengevaluasi setiap 500 microsteps (125 update). Pastikan ketiga pengaturan tersebut habis dibagi akumulasi saat mengubahnya. Panjang fase freeze, warmup, decay, dan cooldown scheduler juga menggunakan microsteps. Kalikan jumlah update optimizer yang diinginkan dengan faktor akumulasi saat mengatur panjang fase-fase ini. Kedua anggaran menggunakan pengaturan LoRA, optimizer, dan EMA yang sama, serta mempertahankan conditioning, dimensi aksi, dan normalisasi dari base yang dimuat. Checkpoint mencakup adapter mentah dan EMA. Pilih anggaran dan checkpoint menggunakan evaluasi held-out dan rollouts; batch yang lebih besar tidak menjamin hasil yang lebih baik.

Preset ini menyisihkan 20% episode terakhir per tugas untuk evaluasi. Sesuaikan ukuran batch dan akumulasi untuk perangkat keras Anda; lihat pelatihan multi-GPU dan pelatihan PEFT.

Adaptasi tugas DROID

Eksperimental: examples/flux3/lora.json menggunakan kembali pengaturan optimizer PEFT SO-101, LoRA, dropout, EMA, dan anggaran pelatihan. Pemuatan konfigurasi telah diperiksa, tetapi pelatihan PEFT DROID end-to-end dan kinerja tugas belum divalidasi.

Muat kebijakan DROID langsung melalui ID repo; encoder bersamaannya akan diselesaikan secara otomatis:

lerobot-train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-droid \
  --dataset.repo_id=YOUR_ORG/YOUR_DROID_TASK_DATASET \
  --output_dir=outputs/droid_lora

Ini menggunakan batch efektif 8 dan 2.500 pembaruan optimizer, dengan EMA diaktifkan dan checkpoint raw/EMA disimpan setiap 125 pembaruan. Unggahan otomatis ke Hub dinonaktifkan. Untuk anggaran yang lebih besar, jalankan dengan empat GPU seperti pada contoh SO-101 dan tambahkan --batch_size=8 --steps=14000.

Preset memuat tata letak kamera, kondisioning, representasi aksi, laju kontrol, dan prosesor dari checkpoint DROID, hanya menimpa pengaturan pelatihan/runtime yang tercantum. Dataset Anda harus sesuai dengan kontrak checkpoint: paket saat ini menggunakan tiga kamera, delapan kanal state/aksi, dan perintah posisi sendi absolut pada 15 Hz. Petakan nama kamera dengan --rename_map jika diperlukan. Kedua robot menggunakan contoh pelatihan yang sama; tidak diperlukan resep khusus robot untuk pemuatan atau inferensi.

Nilai bawaan dan normalisasi

Konfigurasi baru menggunakan nilai default PEFT ini. Memuat --policy.path menggunakan pengaturan yang disimpan di checkpoint; penggantian eksplisit melalui config/CLI memiliki prioritas lebih tinggi. Checkpoint DROID mempertahankan konfigurasinya sendiri.

Konfigurasi baru menggunakan n_obs_steps=1, history_snapshots=1, dan condition_on_past_actions=false. Memuat checkpoint mempertahankan nilai eksplisitnya: paket SO-101 yang dipin menggunakan delapan langkah waktu riwayat, dua snapshot visual, dan kondisioning aksi/keadaan masa lalu. conditioning="history" memilih pengkodean snapshot independen; hal ini sendiri tidak menentukan jumlah langkah waktu. Pelatihan juga membaca frame dan perintah masa depan sebagai target, ditambah perintah sebelumnya untuk menghitung delta aksi.

Nama dan urutan kamera, dimensi state/action, serta kanal aksi absolut tetap bersifat spesifik robot. Checkpoint SO-101 mempertahankan kanal terakhir sebagai absolut (delta_absolute_dims=[-1]) dan menggunakan bobot kanal [1, 1, 1, 1, 1, 2]. Nilai default kelas tidak menggunakan pengecualian kanal absolut dan menggunakan bobot yang sama.

Prosesor yang disimpan oleh base memiliki statistik normalisasi. Masukkan state/action mentah dan pertahankan statistik yang sama untuk pelatihan, resume, dan inferensi. Kuantil dari paket SO-101 mengasumsikan urutan sendi, unit, dan kalibrasi paket tersebut; nilai-nilai ini bukan nilai kalibrasi SO-101 yang universal. Untuk menggunakan statistik yang berbeda, siapkan base terpisah dengan prosesor yang sesuai sebelum pelatihan. Statistik dataset aksi absolut tidak dapat menggantikan statistik delta perintah.

Training menyimpan adapter dan kepala yang dilatih dengan referensi ke basis lengkap. Simpan basis tersebut dan file encoder beku-nya agar tetap dapat diakses saat memuat ulang; adapter tidak digabungkan secara otomatis ke dalamnya.

Lanjutkan

lerobot-train \
  --config_path=outputs/so101_lora/checkpoints/last/pretrained_model/train_config.json \
  --resume=true

Lanjutkan dari checkpoint pretrained_model mentah, yang memulihkan status optimizer dan EMA. Untuk inferensi, Anda dapat memilih saudara pretrained_model_ema miliknya ketika EMA diaktifkan. Pertahankan basis dan prosesor asli untuk setiap adapter; basis yang baru diunduh bukanlah pengganti untuk yang digunakan oleh adapter yang lebih lama.

Inferensi

Arahkan --policy.path dari runner LeRobot ke checkpoint adapter yang telah dilatih; checkpoint ini akan memuat base yang dirujuk dan prosesor yang disimpan. Untuk pemanggilan langsung dengan base lengkap, muat prosesor bersamanya:

from lerobot.policies.factory import make_pre_post_processors
from lerobot.policies.flux3 import Flux3Policy

checkpoint = "black-forest-labs/flux-3-action-so101"
policy = Flux3Policy.from_pretrained(checkpoint).eval()
preprocessor, postprocessor = make_pre_post_processors(policy.config, pretrained_path=checkpoint)

# Run on every control tick, including while actions are queued:
prepared = preprocessor(observation)
normalized_action = policy.select_action(prepared)
absolute_command = postprocessor(normalized_action)

Preprocessor menyangga riwayat observasi/perintah. Postprocessor membatalkan normalisasi, mengintegrasikan delta, dan memperbarui riwayat perintah bersama pada setiap tick. Perintah pertama dijangkarkan ke keadaan terukur; perintah berikutnya diintegrasikan dari perintah sebelumnya. Output kebijakan langsung dinormalisasi dan harus diproses pascaproses. Reset kebijakan dan kedua prosesor pada batas episode atau setelah intervensi; runner sinkron LeRobot melakukan ini. RTC/inferensi asinkron tidak didukung.

Untuk kebijakan single-timestep default, gambar saat ini dan state yang diukur sudah cukup. Untuk prediksi offline dengan delta anchor eksplisit, berikan observation.command_history dengan satu perintah sebelumnya; ini mengikat integrasi output tanpa menambahkan perintah ke conditioning model. Checkpoint yang dikonfigurasi secara eksplisit untuk beberapa timestep observasi memerlukan policy.config.n_obs_steps gambar/state dan riwayat perintah. Lewatkan input melalui preprocessor, panggil predict_action_chunk, lalu lakukan postprocessing. --policy.compile_model=true mengaktifkan kompilasi lazy untuk encoder beku dan DiT inferensi; ini tidak mengompilasi DiT pelatihan.

Untuk VRAM inferensi yang lebih rendah, pindahkan Qwen ke CPU setelah dimuat dan panggilan policy.to(...) terakhir:

policy.frozen.text_encoder.cpu()

Ini memindahkan sekitar 8,3 GiB bobot ke RAM host; instruksi yang tidak di-cache dikodekan lebih lambat, sementara embedding masih ditransfer ke perangkat kebijakan dan di-cache. Hal ini tidak mengurangi memori puncak selama pemuatan, dan policy.to(...) yang kemudian akan memindahkan Qwen kembali bersama kebijakan.

Melatih bentuk lain

Untuk implementasi di mana kami belum menyediakan checkpoint finetuned, mulai dari model dasar di flux-action. Alur kerja tersebut memerlukan definisi kepala aksi dan kondisioning robot, tata letak kamera, representasi dan normalisasi aksi. Dimensi yang sama saja tidak membuat kepala robot lain dapat digunakan kembali.

Untuk inferensi LeRobot berikutnya atau adaptasi tugas, kemas model yang telah dilatih sebagai kebijakan LeRobot lengkap beserta konfigurasinya dan prosesor yang sesuai. File bobot mentah saja bukanlah paket --policy.path yang dapat dimuat. Panduan ini berfokus pada adaptasi kebijakan SO-101 dan DROID yang ada ke tugas-tugas baru.

Semua kebijakan hanya membangun stream konten video dan video_cond, serta stream aksi robot. Bobot gambar/audio yang tidak digunakan difilter sebelum dimuat, menghemat sekitar 28% parameter DiT tanpa mengubah prediksi aksi. Daftar stream yang disimpan tidak mengaktifkan cabang gambar/audio; memuat dan menyimpan basis penuh mencatat tata letak yang dikurangi. Adapter yang menargetkan stream yang dihapus memerlukan basis aslinya dan revisi kode yang lebih lama.

Kebijakan lengkap dimuat secara ketat secara default. Setelah memfilter stream yang diketahui tidak digunakan, bobot yang hilang, tidak terduga, atau berbentuk salah akan memicu error. strict=False secara eksplisit hanya mengizinkan inisialisasi head embodiment yang hilang atau penyesuaian ukuran head yang tidak cocok; bobot trunk tetap wajib dan diperiksa bentuknya.

Validasi

Uji CPU mencakup packing, processor, pembaruan PEFT, dan checkpoint/resume. Pemeriksaan H200 dengan bobot nyata sebelumnya mendahului refactoring processor saat ini. Revisi yang persis ini masih memerlukan validasi GPU dan robot; pemeriksaan yang ada tidak menetapkan kapasitas empat-GPU atau kualitas PEFT pada embodiment baru.