# NeMo Automodel

[NeMo Automodel](https://github.com/NVIDIA-NeMo/Automodel), NVIDIA tarafından büyük ölçekte difüzyon modellerinin ince ayar ve ön eğitimi için geliştirilen, PyTorch DTensor yerlisi bir eğitim kütüphanesidir. Hugging Face yerlisidir — Hub'daki herhangi bir Diffusers biçimindeki modeli checkpoint dönüşümü gerektirmeden eğitebilirsiniz. Aynı YAML tarifi ve özelleştirilebilir eğitim betiği, [FSDP2](https://pytorch.org/docs/stable/fsdp.html) dağıtık eğitim, çok çözünürlüklü sepetli veri yükleme ve maksimum GPU kullanımı için önceden kodlanmış latent uzay eğitimi ile 1 GPU'dan yüzlerce düğüme kadar herhangi bir ölçekte çalışır. Eğitim için [flow matching](https://huggingface.co/papers/2210.02747) kullanır ve tamamen açık kaynaklıdır (Apache 2.0), NVIDIA tarafından desteklenir ve aktif olarak sürdürülmektedir.

NeMo Automodel, Diffusers ile doğrudan entegre edilir. Hugging Face Hub'dan önceden eğitilmiş modelleri Diffusers model sınıfları kullanarak yükler ve çıktıları [DiffusionPipeline](/docs/diffusers/main/tr/api/pipelines/overview#diffusers.DiffusionPipeline) ile üretir.

Tipik iş akışı, NeMo Automodel'i kurmak (pip veya Docker), verilerinizi `.meta` dosyalarına kodlayarak hazırlamak, bir YAML tarifi yapılandırmak, eğitimi `torchrun` ile başlatmak ve sonuçta oluşan checkpoint ile çıkarım yapmaktır.

## Desteklenen modeller

| Model | Hugging Face Kimliği | Görev | Parametreler | Kullanım senaryosu |
|-------|----------------|------|------------|----------|
| Wan 2.1 T2V 1.3B | [Wan-AI/Wan2.1-T2V-1.3B-Diffusers](https://huggingface.co/Wan-AI/Wan2.1-T2V-1.3B-Diffusers) | Metinden Videoya | 1.3B | sınırlı donanımda video üretimi (tek bir 40GB A100'e sığar) |
| FLUX.1-dev | [black-forest-labs/FLUX.1-dev](https://huggingface.co/black-forest-labs/FLUX.1-dev) | Metinden Görsele | 12B | yüksek kaliteli görüntü üretimi |
| HunyuanVideo 1.5 | [hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v](https://huggingface.co/hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v) | Metinden Videoya | 13B | yüksek kaliteli video üretimi |

## Kurulum

### Donanım gereksinimleri

| Bileşen | Minimum | Önerilen |
|-----------|---------|-------------|
| GPU | A100 40GB | A100 80GB / H100 |
| GPU'lar | 4 | 8+ |
| RAM | 128 GB | 256 GB+ |
| Depolama | 500 GB SSD | 2 TB NVMe |

NeMo Automodel'i pip ile yükleyin. Tüm kurulum yöntemleri (kaynaktan kurulum dahil) için [NeMo Automodel kurulum kılavuzuna](https://docs.nvidia.com/nemo/automodel/latest/guides/installation.html) bakın.

```bash
pip3 install nemo-automodel
```

Alternatif olarak, tüm bağımlılıkları içeren önceden oluşturulmuş Docker konteynerini kullanın.

```bash
docker pull nvcr.io/nvidia/nemo-automodel:26.02.00
docker run --gpus all -it --rm --shm-size=8g nvcr.io/nvidia/nemo-automodel:26.02.00
```

> [!WARNING]
> Kontrol noktaları, konteyner çıkış yaptığında kaybolur; kontrol noktası dizinini ana makineye bağlamalı olarak (bind-mount) eklememeniz gerekir. Örneğin, `docker run` komutuna `-v /host/path/checkpoints:/workspace/checkpoints` ekleyin.

## Veri hazırlama

NeMo Automodel, difüzyon modellerini latent uzayda eğitir. Eğitimden önce ham görüntüler veya videolar, VAE latentleri ve metin gömlemelerini içeren `.meta` dosyalarına dönüştürülmelidir. Bu, her eğitim adımında yeniden kodlamayı önler.

Yerleşik ön işleme aracını kullanarak verilerinizi kodlayın. Araç, işi otomatik olarak tüm kullanılabilir GPU'lara dağıtır.

Video ön işleme komutu hem Wan 2.1 hem de HunyuanVideo için aynıdır, ancak bayraklar farklıdır. Wan 2.1, `--resolution_preset` ve `--caption_format sidecar` ile birlikte `--processor wan` kullanırken, HunyuanVideo kare sayısını ayarlamak için `--target_frames` ve `--caption_format meta_json` ile birlikte `--processor hunyuan` kullanır.

**Wan 2.1:**

```bash
python -m tools.diffusion.preprocessing_multiprocess video \
    --video_dir /data/videos \
    --output_dir /cache \
    --processor wan \
    --resolution_preset 512p \
    --caption_format sidecar
```

**HunyuanVideo:**

```bash
python -m tools.diffusion.preprocessing_multiprocess video \
    --video_dir /data/videos \
    --output_dir /cache \
    --processor hunyuan \
    --target_frames 121 \
    --caption_format meta_json
```

```bash
python -m tools.diffusion.preprocessing_multiprocess image \
    --image_dir /data/images \
    --output_dir /cache \
    --processor flux \
    --resolution_preset 512p
```

### Çıktı biçimi

Ön işleme, çözünürlük kovasına göre organize edilmiş bir önbellek dizini oluşturur. NeMo Automodel, kovaya göre örneklemeyi kullanarak çoklu çözünürlüklü eğitimi destekler. Örnekler, her bir partinin aynı boyuttaki örnekleri içermesi ve dolgu israfından kaçınılması için uzamsal çözünürlüğe göre gruplandırılır.

```
/cache/
├── 512x512/                      # Resolution bucket
│   ├── <hash1>.meta              # VAE latents + text embeddings
│   ├── <hash2>.meta
│   └── ...
├── 832x480/                      # Another resolution bucket
│   └── ...
├── metadata.json                 # Global config (processor, model, total items)
└── metadata_shard_0000.json      # Per-sample metadata (paths, resolutions, captions)
```

> [!TIP]
> Başlık biçimleri, giriş veri gereksinimleri ve kullanılabilir tüm ön işleme argümanları için [Diffusion Dataset Preparation](https://docs.nvidia.com/nemo/automodel/latest/datasets/diffusion-dataset) kılavuzuna bakın.

## Eğitim yapılandırması

İnce ayar, iki bileşen tarafından yönlendirilir:

1. Bir tarif betiği ([finetune.py](https://github.com/NVIDIA-NeMo/Automodel/blob/main/examples/diffusion/finetune/finetune.py)), eğitim döngüsünü içeren bir Python giriş noktasıdır: modelin yüklenmesi, dataloader'ın oluşturulması, ileri/geri geçişlerin çalıştırılması, flow matching kaybının hesaplanması, checkpoint alınması ve günlük kaydı.
2. YAML yapılandırma dosyası, tarifin kullandığı tüm ayarları belirtir: ince ayarı yapılacak model, verilerin konumu, optimizör hiperparametreleri, paralelleştirme stratejisi ve daha fazlası. Kodu değiştirmek yerine bu dosyayı düzenleyerek eğitimi özelleştirirsiniz; bu sayede 1 GPU'dan yüzlerce GPU'ya ölçekleyebilirsiniz.

Herhangi bir YAML alanı ayrıca CLI'den de geçersiz kılınabilir:

```bash
torchrun --nproc-per-node=8 examples/diffusion/finetune/finetune.py \
  -c examples/diffusion/finetune/wan2_1_t2v_flow.yaml \
  --optim.learning_rate 1e-5 \
  --step_scheduler.num_epochs 50
```

Aşağıda, her bölümü açıklanan, Wan 2.1 T2V 1.3B için ince ayar (fine-tuning) yapılandırması yer almaktadır.

```yaml
seed: 42

# ── Experiment tracking (optional) ──────────────────────────────────────────
# Weights & Biases integration for logging metrics, losses, and learning rates.
# Set mode: "disabled" to turn off.
wandb:
  project: wan-t2v-flow-matching
  mode: online
  name: wan2_1_t2v_fm

# ── Model ───────────────────────────────────────────────────────────────────
# pretrained_model_name_or_path: any Hugging Face model ID or local path.
# mode: "finetune" loads pretrained weights; "pretrain" trains from scratch.
model:
  pretrained_model_name_or_path: Wan-AI/Wan2.1-T2V-1.3B-Diffusers
  mode: finetune

# ── Training schedule ───────────────────────────────────────────────────────
# global_batch_size: effective batch across all GPUs.
# Gradient accumulation is computed automatically: global / (local × num_gpus).
step_scheduler:
  global_batch_size: 8
  local_batch_size: 1
  ckpt_every_steps: 1000     # Save a checkpoint every N steps
  num_epochs: 100
  log_every: 2               # Log metrics every N steps

# ── Data ────────────────────────────────────────────────────────────────────
# _target_: the dataloader factory function.
#   Use build_video_multiresolution_dataloader for video models (Wan, HunyuanVideo).
#   Use build_text_to_image_multiresolution_dataloader for image models (FLUX).
# model_type: "wan" or "hunyuan" (selects the correct latent format).
# base_resolution: target resolution for multiresolution bucketing.
data:
  dataloader:
    _target_: nemo_automodel.components.datasets.diffusion.build_video_multiresolution_dataloader
    cache_dir: PATH_TO_YOUR_DATA
    model_type: wan
    base_resolution: [512, 512]
    dynamic_batch_size: false  # When true, adjusts batch per bucket to maintain constant memory
    shuffle: true
    drop_last: false
    num_workers: 0

# ── Optimizer ───────────────────────────────────────────────────────────────
# learning_rate: 5e-6 is a good starting point for fine-tuning.
# Adjust weight_decay and betas for your dataset.
optim:
  learning_rate: 5e-6
  optimizer:
    weight_decay: 0.01
    betas: [0.9, 0.999]

# ── Learning rate scheduler ─────────────────────────────────────────────────
# Supports cosine, linear, and constant schedules.
lr_scheduler:
  lr_decay_style: cosine
  lr_warmup_steps: 0
  min_lr: 1e-6

# ── Flow matching ───────────────────────────────────────────────────────────
# adapter_type: model-specific adapter — must match the model:
#   "simple" for Wan 2.1, "flux" for FLUX.1-dev, "hunyuan" for HunyuanVideo.
# timestep_sampling: "uniform" for Wan, "logit_normal" for FLUX and HunyuanVideo.
# flow_shift: shifts the flow schedule (model-dependent).
# i2v_prob: probability of image-to-video conditioning during training (video models).
flow_matching:
  adapter_type: "simple"
  adapter_kwargs: {}
  timestep_sampling: "uniform"
  logit_mean: 0.0
  logit_std: 1.0
  flow_shift: 3.0
  num_train_timesteps: 1000
  i2v_prob: 0.3
  use_loss_weighting: true

# ── FSDP2 distributed training ──────────────────────────────────────────────
# dp_size: number of GPUs for data parallelism (typically = total GPUs on node).
# tp_size, cp_size, pp_size: tensor, context, and pipeline parallelism.
#   For most fine-tuning, dp_size is all you need; leave others at 1.
fsdp:
  tp_size: 1
  cp_size: 1
  pp_size: 1
  dp_replicate_size: 1
  dp_size: 8

# ── Checkpointing ──────────────────────────────────────────────────────────
# checkpoint_dir: where to save checkpoints (use a persistent path with Docker).
# restore_from: path to resume training from a previous checkpoint.
checkpoint:
  enabled: true
  checkpoint_dir: PATH_TO_YOUR_CKPT_DIR
  model_save_format: torch_save
  save_consolidated: false
  restore_from: null
```

### Config alanı referansı

Aşağıdaki tablo, asgari gerekli yapılandırmaları listeler. Tüm modeller için tam örnek yapılandırmalar için [NeMo Automodel örneklerine](https://github.com/NVIDIA-NeMo/Automodel/tree/main/examples/diffusion/finetune) bakın.

| Bölüm | Zorunlu mu? | Değiştirilecekler |
|---------|-----------|----------------|
| `model` | Evet | `pretrained_model_name_or_path` değerini Hugging Face model kimliği olarak ayarlayın. `mode: finetune` veya `mode: pretrain` ayarlayın. |
| `step_scheduler` | Evet | `global_batch_size`, tüm GPU'lar arasında geçerli olan etkin batch boyutudur. `ckpt_every_steps`, checkpoint sıklığını kontrol eder. Gradyan biriktirme otomatik olarak hesaplanır. |
| `data` | Evet | Ön işlenmiş `.meta` dosyalarınızı içeren yolu belirtmek için `cache_dir` değerini ayarlayın. Farklı modeller için `_target_` ve `model_type` değerlerini değiştirin. |
| `optim` | Evet | `learning_rate: 5e-6`, ince ayar için iyi bir varsayılandır. Veri setinize ve modelinize göre ayarlayın. |
| `lr_scheduler` | Evet | `lr_decay_style` için `cosine`, `linear` veya `constant` seçin. Kademeli ısınma için `lr_warmup_steps` değerini ayarlayın. |
| `flow_matching` | Evet | `adapter_type`, modelle eşleşmelidir (Wan için `simple`, FLUX için `flux`, HunyuanVideo için `hunyuan`). `adapter_kwargs` için model özel yapılandırmalarına bakın. |
| `fsdp` | Evet | `dp_size` değerini GPU sayısına ayarlayın. Çoklu düğüm için, tüm düğümlerdeki toplam GPU sayısını ayarlayın. |
| `checkpoint` | Önerilen | `checkpoint_dir` değerini kalıcı bir yola ayarlayın, özellikle Docker kullanırken. Önceki bir kontrol noktasından devam etmek için `restore_from` parametresini kullanın. |
| `wandb` | İsteğe bağlı | Weights & Biases deney izlemesini etkinleştirmek için yapılandırın. Kapatmak için `mode: disabled` olarak ayarlayın. |

## Eğitimi başlat

```bash
torchrun --nproc-per-node=8 \
  examples/diffusion/finetune/finetune.py \
  -c examples/diffusion/finetune/wan2_1_t2v_flow.yaml
```

Her düğümde aşağıdakini çalıştırın ve `NODE_RANK` değerini buna göre ayarlayın:

```bash
export MASTER_ADDR=node0.hostname
export MASTER_PORT=29500
export NODE_RANK=0  # 0 on master, 1 on second node, etc.

torchrun \
  --nnodes=2 \
  --nproc-per-node=8 \
  --node_rank=${NODE_RANK} \
  --rdzv_backend=c10d \
  --rdzv_endpoint=${MASTER_ADDR}:${MASTER_PORT} \
  examples/diffusion/finetune/finetune.py \
  -c examples/diffusion/finetune/wan2_1_t2v_flow_multinode.yaml
```

> [!NOTE]
> Çoklu düğüm eğitiminde, YAML'de `fsdp.dp_size` değerini tüm düğümlerdeki **toplam** GPU sayısına ayarlayın (ör. 8 GPU'lu 2 düğüm için 16).

## Üretim

Eğitimden sonra, ince ayarlanmış kontrol noktasını kullanarak metin istemlerinden video veya görüntü oluşturun.

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_wan.yaml
```

İnce ayarlanmış bir kontrol noktasıyla:

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_wan.yaml \
  --model.checkpoint ./checkpoints/step_1000 \
  --inference.prompts '["A dog running on a beach"]'
```

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_flux.yaml
```

İnce ayarlanmış bir kontrol noktasıyla:

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_flux.yaml \
  --model.checkpoint ./checkpoints/step_1000 \
  --inference.prompts '["A dog running on a beach"]'
```

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_hunyuan.yaml
```

İnce ayarlanmış bir kontrol noktasıyla:

```bash
python examples/diffusion/generate/generate.py \
  -c examples/diffusion/generate/configs/generate_hunyuan.yaml \
  --model.checkpoint ./checkpoints/step_1000 \
  --inference.prompts '["A dog running on a beach"]'
```

## Diffusers entegrasyonu

NeMo Automodel, Diffusers üzerine inşa edilmiştir ve model yükleme ile çıkarım için onu omurga olarak kullanır. Modelleri doğrudan Hugging Face Hub'dan [WanTransformer3DModel](/docs/diffusers/main/tr/api/models/wan_transformer_3d#diffusers.WanTransformer3DModel), [FluxTransformer2DModel](/docs/diffusers/main/tr/api/models/flux_transformer#diffusers.FluxTransformer2DModel) ve [HunyuanVideoTransformer3DModel](/docs/diffusers/main/tr/api/models/hunyuan_video_transformer_3d#diffusers.HunyuanVideoTransformer3DModel) gibi Diffusers model sınıfları aracılığıyla yükler ve [WanPipeline](/docs/diffusers/main/tr/api/pipelines/wan#diffusers.WanPipeline) ile [FluxPipeline](/docs/diffusers/main/tr/api/pipelines/flux#diffusers.FluxPipeline) gibi Diffusers pipeline'ları üzerinden çıktıları üretir.

Bu entegrasyon, Diffusers kullanıcıları için çeşitli avantajlar sunar:

- **Kontrol noktası dönüştürme yok**: Hub'daki önceden eğitilmiş ağırlıklar hazır olarak çalışır. `pretrained_model_name_or_path` parametresini herhangi bir Diffusers biçiminde model kimliğine yönlendirin ve eğitimi hemen başlatın.
- **Gün-0 model desteği**: Diffusers'a yeni bir difüzyon modeli eklendiğinde ve Hub'a yüklendiğinde, NeMo Automodel ile özel bir eğitim betiği beklenmeden ince ayar yapılabilir.
- **Pipeline ile uyumlu çıktılar**: İnce ayarlanmış kontrol noktaları, çıkarım için Diffusers pipeline'larına doğrudan geri yüklenebilecek, Hub'da paylaşılacak veya kuantizasyon ve derleme gibi araçlarla daha da optimize edilebilecek bir formatta kaydedilir.
- **Diffusers modelleri için ölçeklenebilir eğitim**: NeMo Automodel, yerleşik Diffusers eğitim betiklerinin sağladıklarının ötesine geçen dağıtık eğitim yetenekleri (FSDP2, çoklu düğüm, çok çözünürlüklü sepetleme) eklerken aynı model ve pipeline arayüzlerini korur.
- **Paylaşılan ekosistem**: Diffusers ekosisteminden herhangi bir model, LoRA adaptörü veya pipeline bileşeni, eğitim ve çıkarım iş akışının tamamında uyumlu kalır.

## NVIDIA Ekibi

- Pranav Prashant Thombre, pthombre@nvidia.com
- Linnan Wang, linnanw@nvidia.com
- Alexandros Koumparoulis, akoumparouli@nvidia.com

## Kaynaklar

- [NeMo Automodel GitHub](https://github.com/NVIDIA-NeMo/Automodel)
- [Diffusion İnce Ayar Kılavuzu](https://docs.nvidia.com/nemo/automodel/latest/recipes-e2e-examples/diffusion-fine-tuning)
- [Diffusion Veri Seti Hazırlığı](https://docs.nvidia.com/nemo/automodel/latest/datasets/diffusion-dataset)
- [Diffusion Model Kapsamı](https://docs.nvidia.com/nemo/automodel/latest/model-coverage/diffusion.html)
- [Transformers için NeMo Automodel (LLM/VLM ince ayarı)](https://huggingface.co/docs/transformers/en/community_integrations/nemo_automodel_finetuning)