Çoklu GPU Eğitimi

LeRobot, Hugging Face Accelerate üzerinden birden fazla GPU üzerinde eğitim alır. Üç veri paralel yerleşimi desteklenir:

Kurulum

accelerate, training ek paketiyle birlikte gelir:

pip install 'lerobot[training]'

Başlatılıyor

Dağıtık eğitim, hem torchrun hem de accelerate launch üzerinden başlatılabilir. Accelerate, düz bir başlatıcı olarak kullanılır: eğitim yapılandırmasını yönetmez ve tüm dağıtık eğitim ayarları LeRobot’un kendi yapılandırma sisteminde tutulur.

torchrun ile:

torchrun --nproc-per-node=2 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=act \
  --policy.repo_id=${HF_USER}/my_trained_policy \
  --output_dir=outputs/train/act_multi_gpu \
  --job_name=act_multi_gpu \
  --trackio.enable=true

accelerate launch ile (sadece bir başlatıcı olarak):

accelerate launch --num_processes=2 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=act \
  --policy.repo_id=${HF_USER}/my_trained_policy \
  --output_dir=outputs/train/act_multi_gpu \
  --job_name=act_multi_gpu \
  --trackio.enable=true

--parallelism.* bayrakları olmadan, çoklu işlem başlatması düz DDP çalıştırır. Çoklu düğüm çalıştırmaları standart torchrun --nnodes/--node-rank/--rdzv-endpoint bayraklarını (veya accelerate launch --num_machines/--machine_rank/--main_process_ip) kullanır.

Accelerate’in YAML yapılandırma dosyaları (accelerate launch --config_file some.yaml, accelerate config) desteklenmez. Bu dosyalar, motoru ortam değişkenleri aracılığıyla yapılandırarak LeRobot’un yapılandırma sistemini atlar; bu nedenle train_config.json, bir çalıştırmanın fiilen kullandığı ayarları yansıtmaz. Bu yüzden lerobot-train, accelerate ortam değişkenleri ayarlandığında başlatılmayı reddeder. Ayarları bunun yerine --parallelism.* / --accelerator.* bayraklarında belirtin veya geçersiz kılma işlemini kabul edip yine de ilerlemek için LEROBOT_ALLOW_ACCELERATE_ENV=1 değerini ayarlayın.

Toplu işlem anlamları, öğrenme oranı ve adımlar

Her bir dp_replicate × dp_shard veri paralel işçisi, her adımda kendi --batch_size mikro-toplusunu yüklediğinden, bir eğitim adımı batch_size × dp_world_size örnek tüketir ve bunların × gradient_accumulation_steps kadarı her optimizator güncellemesine girer:

effective_batch_size = batch_size × dp_world_size × gradient_accumulation_steps

Eğitim bandı, başlangıçta bu faktörizasyonu yazdırır. --steps, optimizör güncellemelerini değil, döngü adımlarını (işçi başına mikro-toplamları) sayar.

Gradient accumulation birincil sınıf bir bayraktır:

torchrun --nproc-per-node=2 $(which lerobot-train) \
  --batch_size=8 --accelerator.gradient_accumulation.steps=4 ...

LeRobot, etkin batch boyutu arttığında öğrenme oranını veya adım sayısını otomatik olarak ölçeklemez. Ölçeklendirmeyi genişletip eşdeğer bir eğitim istiyorsanız, lütfen manuel olarak ayarlayın; örneğin 2 GPU ile: --optimizer.lr değerini ikiye katlayın (doğrusal ölçekleme) veya --steps değerini yarıya indirin.

Parçalı eğitim (FSDP)

Bir model DDP ile eğitilecek kadar büyük değilse, onu FSDP2 ile parçalayın:

torchrun --nproc-per-node=4 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=<your_policy> \
  --parallelism.dp_shard=4 \
  --accelerator.mixed_precision=bf16 \
  --output_dir=outputs/train/my_policy_fsdp

--parallelism.dp_shard=-1, başlatıcının başlattığı işlem sayısına göre bölümlere ayırır.

--accelerator.mixed_precision hem bf16 hem de fp16 destekler. Ayrıntılar karma hassasiyet bölümünde

Birimleri sarmala

FSDP, modeli birimlere (genellikle tekrarlanan transformer bloğu) böler ve ileri/geri yayılım sırasında birimi tek tek toplar. Politikalar, sarmalayıcı birimlerini politika sınıfındaki _fsdp_wrap_modules üzerinden bildirir. Örneğin, ACT ["ACTEncoderLayer", "ACTDecoderLayer"] ve FastWAM ["MoTLayer"] bildirir. _fsdp_wrap_modules bildirimi olmayan bir politika için aşağıdaki bayraklardan birini iletin. Modül sınıf adını açıkça belirleyebilir veya bunun yerine boyut tabanlı bir politika kullanabilirsiniz:

--accelerator.fsdp.wrap_modules='["MyTransformerBlock"]'   # explicit class names
--accelerator.fsdp.min_num_params=1000000                  # or: wrap every submodule above 1M params

FSDP, bağlı ağırlıkları (örneğin girdi gömlemesine bağlı dil başlığı) sarmalama birimleri arasında bölüştüremez. torch 2.12 ve üzeri sürümler ilk eğitim adımında durur ve parametrenin adını belirtirken, daha eski sürümler bunları sessizce ayırır. Tekrarlanan blok sınıfını sarmalamak, bunları genellikle kök birimde birlikte tutar.

Bir politika _fsdp_wrap_modules bildirmiyorsa ve --accelerator.fsdp.wrap_modules veya --accelerator.fsdp.min_num_params geçirilmiyorsa, çalışma sessizce yalnızca kök modülü sarmak yerine (bu, tüm bölme bellek tasarruflarından vazgeçmek anlamına gelir) başlangıçta başarısız olur.

Diğer bölme ayarları:

• --accelerator.fsdp.reshard_after_forward: forward sonrası her birim parametrelerinin bellekte kalıp kalmayacağı.
• --accelerator.fsdp.cpu_offload: parametreleri, gradyanları ve optimizör durumlarını CPU'da tutar.
• --accelerator.fsdp.ignored_modules: parçalanmamış olarak tutulacak modül yollarının regex'i.
• --accelerator.fsdp.mixed_precision_policy.{param_dtype,reduce_dtype,output_dtype,cast_forward_inputs}: PyTorch’un MixedPrecisionPolicy alanları, her FSDP birimine uygulanır. Herhangi bir alan ayarlandığında, politika yalnızca bu alanlardan oluşturulur ve --accelerator.mixed_precision’ten türetilen politikanın yerini alır; bu nedenle param_dtype’i de ayarlayın. torch 2.15’ten önce, ayarlanmamış bir reduce_dtype param_dtype’i izler. torch 2.15’ten itibaren, parametrelerin kendi dtype’ini (karışık hassasiyette float32) izler. float16, loss scaler’ı oluşturan --accelerator.mixed_precision=fp16 gerektirir.

HSDP

Hibrit Parçalı Veri Paralelliği: parametreler, gradyanlar ve optimizör durumları dp_shard sıraları arasında parçalanır ve bu parçalama dp_replicate kez kopyalanır. Parametre all-gather ve gradyan reduce-scatter işlemleri bir parça grubunun içinde kalır; yalnızca kopyaları senkronize eden all-reduce işlemi gruplar arasında geçer. Bu iki boyutun çarpımı dünya boyutuna eşit olmalıdır:

# 16 GPUs = 2 nodes × 8: shard within each node, replicate across nodes
torchrun --nnodes=2 --nproc-per-node=8 ... $(which lerobot-train) \
  --parallelism.dp_replicate=2 --parallelism.dp_shard=8 ...

PEFT

PEFT ince ayarı (--peft.*) FSDP2 ve HSDP altında çalışır. Donmuş temel model, adaptörlerle birlikte parçalanır (shard edilir), böylece her rank yalnızca temel ağırlıkların kendi parçasını tutar:

torchrun --nproc-per-node=4 $(which lerobot-train) \
  --policy.path=${HF_USER}/my_base_policy \
  --peft.method_type=LORA --peft.r=16 \
  --parallelism.dp_shard=4 \
  --accelerator.mixed_precision=bf16 \
  --output_dir=outputs/train/my_policy_fsdp_lora

• Wrap birimleri, politikanın _fsdp_wrap_modules beyanından (veya --accelerator.fsdp.wrap_modules parametresinden) gelir.
• Taban model bf16 veya fp16 olarak saklanıyorsa karma hassasiyet (mixed precision) kullanın. PEFT, adaptörlerini fp32'de tutarken --peft.full_training_modules kopyaları taban modelin dtype'ını korur ve FSDP2, birlikte parçaladığı eğitilebilir parametreler için tek bir dtype gerektirir. Karma hassasiyet açıkken accelerate, her eğitilebilir parametreyi fp32'ye yükseltir.
• Checkpoint'lar, tam ağırlıklar yerine adaptörü saklar; bu durum her --checkpoint_format için geçerlidir (bkz. Checkpoint'lar).
• --accelerator.fsdp.ignored_modules, PEFT modelinin base_model.model. ile başlayan modül adlarıyla eşleştirilir. Bunlarla eşleşmek için deseni .* ile başlatın.

Kontrol Noktaları

Her kontrol noktası bir pretrained_model/ dizini ve bir training_state/ dizini içerir:

005000/  # the training step at that checkpoint
├── pretrained_model/
│   ├── config.json  # policy config
│   ├── train_config.json  # the full training config
│   ├── model.safetensors  # full weights (checkpoint_format ∈ {safetensors, safetensors_dcp}, or any non-sharded run)
│   ├── pytorch_model_fsdp_0/  # DCP weight shards (checkpoint_format ∈ {dcp, safetensors_dcp})
│   ├── policy_preprocessor.json  # preprocessor config (when the run has a preprocessor)
│   ├── policy_preprocessor_step_*.safetensors  # state of the stateful preprocessor steps
│   ├── policy_postprocessor.json  # postprocessor config (when the run has a postprocessor)
│   └── policy_postprocessor_step_*.safetensors  # state of the stateful postprocessor steps
└── training_state/
    ├── optimizer_param_groups.json  # optimizer param groups (non-sharded runs)
    ├── optimizer_state.safetensors  # optimizer state (non-sharded runs)
    ├── optimizer_0/  # DCP optimizer shards (sharded runs)
    ├── rng_state.safetensors  # rng states
    ├── scheduler_state.json  # scheduler state (when the run has a scheduler)
    ├── scaler_state.json  # fp16 loss-scaler state (mixed_precision=fp16 only)
    └── training_step.json  # step + dp_world_size/batch_size/grad_accum/precision + topology

Tek GPU veya DDP eğitimi sırasında, pipeline her state dict'i tek bir dosyaya serialize eder: model için model.safetensors ve optimizer için optimizer_state.safetensors.

Parçalı eğitim sırasında, optimizör durumu training_state/optimizer_0/ altında DCP parçaları olarak kaydedilir ve pretrained_model/ altındaki model yerleşimi --checkpoint_format ile yapılandırılabilir:

PEFT çalıştırması, tam ağırlıklar yerine adaptörünü saklar: adapter_model.safetensors ve adapter_config.json, model.safetensors dosyasının yerini alır ve DCP parçaları yalnızca adaptörü içerir. Temel model, adapter_config.json dosyasında kaydedilen yoldan yüklenir.

Parçalı çalışmalardan toplanan (safetensors) denetim noktaları hakkında bilmeniz gereken iki şey:

• fp32 ağırlıkları saklarlar. Karmaşıklık hassasiyetli eğitim sırasında FSDP, bir fp32 ana kopyasını tutar ve kontrol noktası, eğitimin tutarlı bir şekilde devam etmesini sağlamak için ana kopyayı kaydeder.
• Gather işlemi kolektiftir (tüm sıralar katılır) ancak yalnızca ana süreç yazar.

DCP denetim noktalarını dönüştürme

lerobot-convert-dcp, bir DCP shard dizinini düzenli bir model.safetensors dosyasına birleştirir; bu işlem çevrimdışı ve GPU kullanmadan yapılır:

lerobot-convert-dcp --checkpoint_dir=outputs/train/run/checkpoints/005000
lerobot-convert-dcp --checkpoint_dir=... --delete_dcp=true --push_to_hub=${HF_USER}/my_policy

--push_to_hub, dönüştürülen dizini bir model deposu olarak yayımlar. Bir PEFT çalıştırmasının parçaları adapter_model.safetensors dosyasında birleştirilir. Herhangi bir dcp kontrol noktası gibi, --checkpoint_format=dcp ile kaydedilen bir PEFT kontrol noktası, yalnızca bu dönüştürme işleminden sonra --policy.path ile yüklenir.

Devam Etme

--resume=true --config_path=.../checkpoints/last/pretrained_model/train_config.json ile devam edin. DCP kontrol noktasından devam etmek, model ve optimizör durumunu mevcut topolojiye yeniden bölme (resharding) işlemini destekler; bu da farklı bir dp_replicate/dp_shard bölünmesiyle devam edebileceğiniz anlamına gelir. Veri örnekleyici (data sampler) her zaman doğru epoch ve ofsette devam edebilir, ancak yalnızca dünya boyutu (world size) ve batch boyutu orijinal çalışmayla eşleştiğinde örnekleme düzeyinde tam (sample-exact) olur (aksi halde bir uyarı kaydedilir).

LeRobot 0.6.x ve önceki sürümler tarafından yazılan FSDP checkpoint'leri farklı bir disk düzeni (toplanmış tam optimizör durumu) kullandığı için devam ettirilemez.

Notlar

• Checkpoint kaydetme ve eğitim sonu yayınlama işlemleri kolektiftir (her rank bunlara girer). Toplanan ağırlıklar, yan dosyalar ve Hub yüklemeleri yalnızca ana süreç tarafından yazılır.
• Metrikler, günlüğe kaydedilmeden önce ranklar arasında indirgenir: kayıplar ortalama alınır ve samples/s küme genelindeki verimliliği raporlar.
• Öğrenme hızı zamanlaması, süreç sayısından bağımsız olarak her eğitim adımında bir kez ilerletilir (step_scheduler_with_optimizer=False yerleşiktir).

Altta yatan mekanizma hakkında arka plan bilgisi için Accelerate FSDP kılavuzu'na bakın. Büyük ölçekli eğitim hakkında daha derine inmek için Ultrascale Playbook'a göz atın.