FLUX 3 Eylem

FLUX 3 Action, kamera gözlemlerinden, durumdan ve görev talimatından robot eylemlerini tahmin eder. Donmuş bir Video VAE ve metin kodlayıcı, video latantlarını ve eylem parçalarını tahmin eden bir difüzyon dönüştürücüsüne besleme sağlar; çıkarım sırasında yalnızca eylemler döndürülür. LeRobot, çıkarım ve PEFT'yi destekler: LoRA gövdeyi uyarlar (adapts)ken robotun eylem ve koşullama başlıkları tam olarak eğitilir.

SO-101 flux-3-action-so101 ve Franka Panda robotları flux-3-action-droid (DROID veri setinde ince ayarlanmış) için ince ayarlarla birlikte flux-3-action-base modelini temel eylem modeli olarak sunuyoruz. Buradaki merkezi örnek, flux-3-action-so101 modeline dayalı bir LoRA ile görev uyarlama işlemidir.

Yeni bir robot gövdesini temel modelden eğitmek veya tam ince ayar yapmak için bağımsız flux-action depomuzu kullanın.

Kurulum

Video VAE, NATTEN 0.21.6 veya daha yeni bir sürümünü, tam olarak sizin torch ve CUDA sürümleriniz için derlenmiş bir wheel olarak https://whl.natten.org adresinden gerektirir. NATTEN, torch 2.10'dan 2.13'e kadar olan sürümler için wheel yayınlamaktadır ancak LeRobot'ün varsayılan olarak kurduğu torch 2.15 için henüz yayınlamamıştır; bu nedenle önce desteklenen bir torch sürümünü kurun. Örneğin, LeRobot deposundan, eğitim, politika, PEFT ve EMA bağımlılıklarıyla birlikte CUDA 13.0 destekli torch 2.13 kurabilirsiniz. kurulum kılavuzunda olduğu gibi, TorchCodec CPU indeksinden gelir:

pip install --index-url https://download.pytorch.org/whl/cu130 \
    'torch==2.13.0+cu130' 'torchvision==0.28.0+cu130' 'numpy>=2.0,<2.3'
pip install --index-url https://download.pytorch.org/whl/cpu 'torchcodec==0.13.0+cpu'
pip install -e ".[training,flux3,peft,diffusion]" \
    'torch==2.13.0+cu130' 'torchvision==0.28.0+cu130' 'torchcodec==0.13.0+cpu'
pip install 'natten==0.21.7+torch2130cu130' --find-links https://whl.natten.org

580.65'ten eski bir NVIDIA sürücüsü için bunun yerine CUDA 12.6 derlemesini kullanın: cu126 indeksi, +cu126 torch ve torchvision etiketleri ve natten==0.21.7+torch2130cu126. Farklı bir torch sürümü için, etiketi ona uyan NATTEN tekerleğini kullanın; örneğin CUDA 13.0 ile torch 2.11 için natten==0.21.6+torch2110cu130.

SO-101 görev uyarlama

30 Hz hızında bir LeRobot v3 veri seti kullanın; altı mutlak komut eylem kanalı ve altı ölçülen durum kanalı, eşleşen eklem sırası ve birimlerine sahip olmalıdır. Gripper son kanaldır. Ham değerleri, tutarlı robot kalibrasyonunu ve task içindeki talimatları sağlayın.

Kameralar

Kamera adları, sayısı ve yerleşimi yapılandırılabilir. SO-101 paketi, iki kamerasına ne gösterdiklerine göre isim verir:

Kamera adlarını beklenen anahtarlara eşlemek için --rename_map kullanabilirsiniz, örneğin:

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

Rollout için aynı eşlemeyi kullanın; eşleşen anahtarlar için eşleme gerekmez. Yeniden adlandırma eşlemeleri bölümüne bakın.

Yükle ve eğit

SO-101 politikasını black-forest-labs/flux-3-action-so101 adresinden yükleyin. Kaydedilen yapılandırma, black-forest-labs/flux-3-action-base modelinin sabitlenmiş bir revizyonundan ortak VAE ve metin kodlayıcıyı otomatik olarak yükler. Erişim kısıtlıysa, erişim yetkisine sahip bir hesapla hf auth login komutuyla kimlik doğrulaması yapın. LeRobot kopyasından çalıştırın:

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

Hub önbelleği, devam ve adaptör çıkarımı için indirilen modeli ve paylaşılan kodlayıcıları saklar.

Pinned SO-101-finetuned checkpoint, scene / wrist kamera anahtarlarını, sekiz gözlem zaman adımını, bağımsız olarak kodlanmış iki görsel anlık görüntüyü ve geçmiş eylem/durum koşullandırmasını kullanır. 42 eylem tahmin eder, ilk 32’sini 30 Hz’de çalıştırır ve ardından yeniden planlama yapar. Kaydedilen işlemciler, taban modelin eşleşen normalizasyon istatistiklerini taşır. Bu checkpoint ayarları, görev uyarlama sırasında korunur. Paylaşılan examples/flux3/lora.json yalnızca eğitim/çalışma zamanı ayarlarını ve eğitim bütçesini sağlar; aynı dosya, her Hub paketinde lora.json olarak paketlenir. Kamera yerleşimi, koşullandırma, eylem temsili ve kayıp ayarları checkpoint’ten gelir. Bu komutlar, kaydedilen 32 çalışma uzunluğunu, 3/3 rehberlik değerini ve eager çalıştırmayı korur. Rehberlik 4/1 ve derleme için --policy.guidance_scale=4 --policy.guidance_scale_action=1 --policy.compile_model=true ekleyin.

Koşullama deneyleri: LeRobot, n_obs_steps, history_snapshots ve condition_on_past_actions parametrelerini sunar. Bunların değiştirilmesi, uyumlu model/işleyici ayarları ve ince ayar gerektirir; olağan görev uyarlama için kontrol noktasının kaydedilmiş değerlerini koruyun.

Ön ayar, sönümleme 0.999 olan rank/alpha 32 LoRA ve EMA'yı etkinleştirir; hiçbir şey otomatik olarak yüklenmez. Yeni adaptörleri üst düzey peft ayarları üzerinden etkinleştirin, kayıtlı bir adaptörü tanımlayan --policy.use_peft=true parametresini kullanmayın.

Deneylerimizde EMA, DROID üzerinde önemli faydalar sağlarken, SO-101 sonuçları şu ana kadar karışık. Faydası, veriye ve eğitim kurulumuna bağlıdır. Hangisinin dağıtılacağına karar vermeden önce, EMA'nın etkin tutulmasını ve hem ham hem de EMA checkpoint'lerinin aynı rollout protokolü altında değerlendirilmesini öneririz. Periyodik çevrimdışı doğrulama kaybı, ham ağırlıkları kullanır; iki varyantı otomatik olarak karşılaştırmaz.

Hızlı iterasyon için tek GPU bütçesiyle başlayın. Daha büyük bir eğitim bütçesi için, bu geçersiz kılma ayarlarıyla aynı yapılandırmayı kullanın:

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

Etkili batch, GPU sayısı × GPU başına batch × birikimdir. LeRobot, steps, save_freq ve eval_steps değerlerini mikro adım cinsinden sayar; optimizator güncellemeleri için birikim değerine bölün. Hazır ayar, her 500 mikro adımda (125 güncellemede) kaydeder ve değerlendirme yapar. Birikim değerini değiştirirken bu üç ayarın da birikime bölünebilir olmasını sağlayın. Zamanlayıcı dondurma, ısınma, azalma ve soğuma süreleri de mikro adım cinsindendir. Bu faz uzunluklarını ayarlarken, istenen optimizator güncelleme sayısını birikim çarpanıyla çarpın. Her iki bütçe de aynı LoRA, optimizator ve EMA ayarlarını kullanır ve yüklenen tabanın koşullandırma, eylem boyutları ve normalizasyonunu korur. Kontrol noktaları hem ham hem de EMA adaptörlerini içerir. Bütçeyi ve kontrol noktasını, ayrılmış değerlendirme ve roll-out’lar kullanarak seçin; daha büyük bir batch daha iyi sonuçları garanti etmez.

Hazır ayar, her görev için son %20'lik bölümü değerlendirme için ayırır. Batch boyutunu ve birikimi donanımınıza göre ayarlayın; çoklu GPU eğitimi ve PEFT eğitimi konularına bakın.

DROID görev uyarlama

Deneysel: examples/flux3/lora.json, SO-101 PEFT optimizatörünü, LoRA'yı, dropout'u, EMA'yı ve eğitim bütçesi ayarlarını yeniden kullanır. Yapılandırma yükleme işlemi kontrol edilmiştir, ancak uçtan uca DROID PEFT eğitimi ve görev performansı henüz doğrulanmamıştır.

DROID politikasını doğrudan depo kimliğiyle yükleyin; ortak kodlayıcıları otomatik olarak çözümlenir:

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

Bu, etkin batch 8 ve 2.500 optimizasyon güncellemesi kullanır; EMA etkinleştirilmiştir ve ham/EMA checkpoint'leri her 125 güncellemede bir kaydedilir. Otomatik Hub yüklemeleri devre dışıdır. Daha büyük bütçe için, SO-101 örneğinde olduğu gibi dört GPU ile başlatın ve --batch_size=8 --steps=14000 ekleyin.

Preset, DROID checkpoint’ın kamera yerleşimini, koşullandırma, eylem temsilini, kontrol hızını ve işleyicilerini yükler; yalnızca listelenen eğitim/çalışma zamanı ayarlarını geçersiz kılar. Veri setiniz checkpoint’in sözleşmesiyle eşleşmelidir: mevcut paket üç kamera, sekiz durum/eylem kanalı ve 15 Hz’de mutlak eklem konumu komutları kullanır. Gerekirse kamera adlarını --rename_map ile eşleyin. Her iki robot da aynı eğitim örneğini kullanır; yükleme veya çıkarım için robota özgü bir tarif gerekmez.

Varsayılanlar ve normalizasyon

Yeni yapılandırmalar bu PEFT varsayılanlarını kullanır. --policy.path yüklenirken kontrol noktasının kaydedilmiş ayarları kullanılır; açık yapılandırma/CLI geçersiz kılma işlemleri önceliklidir. DROID kontrol noktaları kendi yapılandırmalarını korur.

Yeni yapılandırmalar n_obs_steps=1, history_snapshots=1 ve condition_on_past_actions=false değerlerini kullanır. Bir kontrol noktası yüklenirken açık değerleri korunur: sabitlenmiş SO-101 paketi sekiz geçmiş zaman adımı, iki görsel anlık görüntü ve geçmiş eylem/durum koşullandırması kullanır. conditioning="history" bağımsız anlık görüntü kodlamasını seçer; tek başına zaman adımı sayısını belirlemez. Eğitim ayrıca hedefler olarak gelecek kareleri ve komutları, eylem farklarını hesaplamak için de bir önceki komutu okur.

Kamera adları/sırası, durum/aksiyon boyutları ve mutlak aksiyon kanalları robota özgü olarak kalır. SO-101 kontrol noktası son kanalı mutlak olarak tutar (delta_absolute_dims=[-1]) ve [1, 1, 1, 1, 1, 2] kanal ağırlıklarını kullanır. Sınıf varsayılanları mutlak kanal istisnaları kullanmaz ve eşit ağırlıklar uygular.

Tabanın kaydedilmiş işlemcileri normalizasyon istatistiklerini barındırır. Ham durumları/aksiyonları besleyin ve eğitim, devam ve çıkarım için aynı istatistikleri koruyun. SO-101 paketinin çeyreklik değerleri (quantiles), eklem sıralamasını, birimlerini ve kalibrasyonunu varsayar; bunlar evrensel SO-101 kalibrasyon değerleri değildir. Farklı istatistikler kullanmak için, eğitimden önce eşleşen işlemcilere sahip ayrı bir taban hazırlayın. Mutlak-aksiyon veri seti istatistikleri, komut-delta istatistiklerinin yerini tutamaz.

Eğitim, adaptörleri ve eğitilmiş başları, tam tabana bir referansla kaydeder. Yeniden yüklerken o tabanı ve dondurulmuş kodlayıcı dosyalarını erişilebilir tutun; adaptörler otomatik olarak ona birleştirilmez.

Devam et

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

Ham pretrained_model kontrol noktasından devam edin; bu işlem, optimizör ve EMA durumunu geri yükler. Çıkarım için, EMA etkinleştirildiyse pretrained_model_ema kardeşini seçebilirsiniz. Her adaptörün orijinal tabanını ve işlemcilerini koruyun; yeni indirilen bir taban, daha eski bir adaptör tarafından kullanılanın yerini tutmaz.

Çıkarım

LeRobot çalıştırıcısının --policy.path parametresini, eğitilmiş adaptör kontrol noktasına yönlendirin; bu, referans verilen taban modeli ve kaydedilmiş işlemcileri yükler. tam bir taban ile doğrudan çağrılarda, işlemcileri taban modelle birlikte yükleyin:

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)

Önişleyici, gözlem/komut geçmişini tamponlar. Sonişileyici, normalizasyonu geri alır, deltaları entegre eder ve her tik'te paylaşılan komut geçmişini günceller. İlk komut, ölçülen duruma sabitlenir; sonraki komutlar, bir önceki komuttan entegre edilir. Doğrudan politika çıktıları normalize edilir ve sonişiye tabi tutulmalıdır. Bölüm sınırlarında veya müdahale sonrasında politika ve her iki işleyiciyi sıfırlayın; LeRobot'un senkron çalıştırıcısı bunu yapar. RTC/asenkron çıkarım desteklenmez.

Varsayılan tek zaman adımı politikası için mevcut görüntüler ve ölçülen durum yeterlidir. Açık bir delta çapası ile çevrimdışı tahmin için, observation.command_history alanına bir önceki komutu sağlayın; bu, modele bir komut eklemeksizin çıktı entegrasyonunu çapalar. Birden fazla gözlem zaman adımı için açıkça yapılandırılmış kontrol noktaları, policy.config.n_obs_steps görüntü/durum ve komut geçmişi gerektirir. Girdileri ön işleyiciden geçirin, predict_action_chunk çağrısını yapın, ardından son işlemeyi uygulayın. --policy.compile_model=true dondurulmuş kodlayıcıların ve çıkarım DiT'inin tembel derlenmesini etkinleştirir; eğitim DiT'ini derlemez.

Daha düşük çıkarım VRAM'i için, Qwen'i yükleme işleminden ve son policy.to(...) çağrısından sonra CPU'ya taşıyın:

policy.frozen.text_encoder.cpu()

Bu işlem, yaklaşık 8,3 GiB ağırlığı ana belleğe (host RAM) taşır; önbelleğe alınmamış talimatlar daha yavaş kodlanır, ancak gömceler (embeddings) yine de politika cihazına aktarılır ve önbelleğe alınır. Bu, yükleme sırasında tepe bellek kullanımını azaltmaz ve sonraki bir policy.to(...) çağrısı, Qwen'i politika ile birlikte geri taşır.

Diğer vücutları eğitme

Henüz ince ayarlanmış bir kontrol noktası sunmadığımız uygulamalarda, flux-action içindeki temel modelden başlayın. Bu iş akışı, robotun eylem ve koşullama başlıklarını, kamera yerleşimini, eylem temsilini ve normalizasyonunu tanımlamayı gerektirir. Sadece eşit boyutlar, başka bir robotun başlıklarının yeniden kullanılabilir olduğu anlamına gelmez.

Sonraki LeRobot çıkarımı veya görev uyarlama işlemleri için, eğitilen modeli yapılandırması ve eşleşen işlemcileriyle birlikte tam bir LeRobot politikası olarak paketleyin. Sadece ham ağırlık dosyası, yüklenebilir bir --policy.path paketi değildir. Bu kılavuz, mevcut SO-101 ve DROID politikalarının yeni görevlere uyarlanmasına odaklanmaktadır.

Tüm politikalar yalnızca video ve video_cond içerik akışlarını ve robotun eylem akışlarını oluşturur. Kullanılmayan görüntü/ses ağırlıkları, yüklenmeden önce filtrelenir ve eylem tahminlerini değiştirmeden DiT parametrelerinin yaklaşık %28'i tasarruf edilir. Kaydedilen akış listeleri, görüntü/ses dallarını etkinleştirmez; tam bir taban yüklenip kaydedildiğinde azaltılmış yerleşim kaydedilir. Kaldırılan akışlara yönelik adaptörler, orijinal tabanlarını ve daha eski bir kod revizyonunu gerektirir.

Tamamlanmış politikalar varsayılan olarak katı (strict) olarak yüklenir. Bilinen kullanılmayan akışlar filtrelendikten sonra, eksik, beklenmedik veya yanlış biçimli ağırlıklar bir hata oluşturur. Açıkça belirtilen strict=False parametresi, yalnızca eksik başlıkları başlatmaya veya eşleşmeyen vücut (embodiment) başlıklarının boyutunu değiştirmeye izin verir; gövde (trunk) ağırlıkları zorunlu kalmaya devam eder ve biçim kontrolü yapılır.

Doğrulama

CPU testleri paketleme, işlemciler, PEFT güncellemeleri ve checkpoint/devam işlemlerini kapsar. Mevcut işlemci yeniden yapılandırmasından önce gerçek ağırlıklı H200 kontrolleri yapılmıştır. Bu tam revizyon hâlâ GPU ve robot doğrulaması gerektirmektedir; mevcut kontroller, yeni bir vücut yapısında dört GPU kapasitesini veya PEFT kalitesini kanıtlamamaktadır.