# Çoklu GPU Eğitimi

LeRobot, [Hugging Face Accelerate](https://huggingface.co/docs/accelerate) üzerinden birden fazla GPU üzerinde eğitim alır. Üç veri paralel yerleşimi desteklenir:

| Düzen   | Ne işe yarar                                                  | Yapılandırma                                                  |
| -------- | ------------------------------------------------------------- | ------------------------------------------------------- |
| **DDP**  | Tüm GPU'larda tam modeli kopyalar                        | herhangi bir çoklu GPU başlatmasında varsayılan olarak                         |
| **FSDP** | Parametreleri, gradyanları ve optimizör durumunu GPU'lar arasında parçalara ayırır | `--parallelism.dp_shard=N`                              |
| **HSDP** | GPU grupları içinde parçalar, gruplar arasında kopyalar        | `--parallelism.dp_replicate=R --parallelism.dp_shard=S` |

## Kurulum

`accelerate`, `training` ek paketiyle birlikte gelir:

```bash
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:

```bash
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):

```bash
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.

> [!WARNING]
> 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ı artık yansıtmaz. Bu yüzden `lerobot-train`, [accelerate ortam değişkenleri](https://huggingface.co/docs/accelerate/usage_guides/fsdp) 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:

```bash
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:

```bash
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](./torch_accelerators#mixed-precision) 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:

```bash
--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`'den 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'ünü (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:

```bash
# 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_training) (`--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:

```bash
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](#checkpoints)).
- `--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:

```text
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:

| `--checkpoint_format`     | Ağırlıklar artefaktı                             | Kullanım zamanı                                                              |
| ------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| `safetensors` _(varsayılan)_ | yalnızca tek bir `model.safetensors`              | her kontrol noktasının `from_pretrained` ile anında yüklenebilir olmasını istiyorsanız |
| `dcp`                     | sadece `pytorch_model_fsdp_0/` shard dizini | tüm ağırlıkları toplamak, kaydetme ve devam etme işlemlerini çok yavaşlatır           |
| `safetensors_dcp`         | her ikisi                                         | hızlı devam _ve_ anında yüklenebilir kontrol noktaları istiyorsanız           |

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:

```bash
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).

> [!NOTE]
> 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](https://huggingface.co/docs/accelerate/usage_guides/fsdp)'na bakın. Büyük ölçekli eğitim hakkında daha derine inmek için [Ultrascale Playbook](https://huggingface.co/spaces/nanotron/ultrascale-playbook)'a göz atın.

