# NeMo Automodel

[NeMo Automodel](https://github.com/NVIDIA-NeMo/Automodel) هو مكتبة تدريب أصلية مبنية على PyTorch DTensor من NVIDIA، مخصصة لضبط النماذج الانتشارية المسبقة التدريب والتدريب المسبق لها على نطاق واسع. وهو أصلي على Hugging Face — يمكنك تدريب أي نموذج بصيغة Diffusers من المستودع دون الحاجة إلى تحويل نقاط الحفظ. تعمل نفس وصفة YAML وسكربت التدريب القابل للتعديل على أي نطاق، من وحدة معالجة رسومية واحدة إلى مئات العقد، مع تدريب موزّع عبر [FSDP2](https://pytorch.org/docs/stable/fsdp.html)، وتحميل بيانات مُصنّفة حسب دقة متعددة، وتدريب في فضاء كامن مُرمّز مسبقًا لتحقيق أقصى استفادة من وحدات معالجة الرسومات. يستخدم [flow matching](https://huggingface.co/papers/2210.02747) للتدريب، وهو مفتوح المصدر بالكامل (Apache 2.0)، مدعوم من NVIDIA، ويُحافظ عليه بنشاط.

يتكامل NeMo Automodel مباشرة مع Diffusers. فهو يُحمّل النماذج المُدرَّبة مسبقًا من Hugging Face Hub باستخدام فئات نماذج Diffusers، وينتج المخرجات عبر [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline).

يتضمن سير العمل النموذجي تثبيت NeMo Automodel (عبر pip أو Docker)، وتجهيز بياناتك عن طريق ترميزها في ملفات `.meta`، وإعداد وصفة YAML، وبدء التدريب باستخدام `torchrun`، وتنفيذ الاستدلال باستخدام نقطة التفتيش الناتجة.

## النماذج المدعومة

| النموذج | معرّف Hugging Face | المهمة | المعاملات | حالة الاستخدام |
|-------|----------------|------|------------|----------|
| 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) | النص إلى فيديو | 1.3B | توليد الفيديو على أجهزة محدودة (يتناسب مع بطاقة A100 واحدة بسعة 40 جيجابايت) |
| FLUX.1-dev | [black-forest-labs/FLUX.1-dev](https://huggingface.co/black-forest-labs/FLUX.1-dev) | النص إلى صورة | 12B | توليد صور عالية الجودة |
| HunyuanVideo 1.5 | [hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v](https://huggingface.co/hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v) | النص إلى فيديو | 13B | توليد فيديو عالي الجودة |

## التثبيت

### متطلبات العتاد

| مكوّن | الحد الأدنى | موصى به |
|-----------|---------|-------------|
| وحدة معالجة الرسوميات | A100 40GB | A100 80GB / H100 |
| وحدات معالجة الرسوميات | 4 | 8+ |
| ذاكرة الوصول العشوائي | 128 GB | 256 جيجابايت+ |
| التخزين | 500 جيجابايت SSD | 2 تيرابايت NVMe |

قم بتثبيت NeMo Automodel باستخدام pip. للاطلاع على جميع طرق التثبيت (بما في ذلك التثبيت من المصدر)، راجع [دليل تثبيت NeMo Automodel](https://docs.nvidia.com/nemo/automodel/latest/guides/installation.html).

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

أو استخدم حاوية Docker الجاهزة التي تتضمن جميع التبعيات.

```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]
> تُفقد نقاط التفتيش عند خروج الحاوية ما لم تُربط مَجلد نقاط التفتيش بالضيف. على سبيل المثال، أضف `-v /host/path/checkpoints:/workspace/checkpoints` إلى أمر `docker run`.

## تجهيز البيانات

يدرّب NeMo Automodel نماذج الانتشار في الفضاء الكامن. يجب معالجة الصور أو مقاطع الفيديو الخام مسبقًا إلى ملفات `.meta` تحتوي على الكمونات الخاصة بـ VAE وتضمينات النص قبل التدريب. وهذا يتجنّب إعادة الترميز في كل خطوة تدريب.

استخدم أداة المعالجة المسبقة المدمجة لتشفير بياناتك. توزّع الأداة العمل تلقائيًا على جميع وحدات معالجة الرسومات المتاحة.

أمر ما قبل معالجة الفيديو هو نفسه لكل من Wan 2.1 و HunyuanVideo، لكن الأعلام تختلف. يستخدم Wan 2.1 `--processor wan` مع `--resolution_preset` و `--caption_format sidecar`، بينما يستخدم HunyuanVideo `--processor hunyuan` مع `--target_frames` لضبط عدد الإطارات و `--caption_format meta_json`.

**وان 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
```

**هونيوان فيديو:**

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

### صيغة الإخراج

ينتج عن المعالجة المسبقة مجلد تخزين مؤقت منظم حسب دلو الدقة. يدعم NeMo Automodel التدريب متعدد الدقة من خلال أخذ العينات المصنّفة في دلاء. تُجمَّع العينات حسب الدقة المكانية بحيث يحتوي كل دفعة على عينات بنفس الحجم، مما يتجنب هدر الحشو.

```
/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]
> راجع دليل [تحضير مجموعة بيانات الانتشار](https://docs.nvidia.com/nemo/automodel/latest/datasets/diffusion-dataset) لمعرفة صيغ التسميات، ومتطلبات البيانات المدخلة، وجميع معاملات ما قبل المعالجة المتاحة.

## إعدادات التدريب

تقوم عملية الضبط الدقيق على مكونين:

1. سكربت الوصفة ([finetune.py](https://github.com/NVIDIA-NeMo/Automodel/blob/main/examples/diffusion/finetune/finetune.py)) هو نقطة دخول بلغة بايثون تحتوي على حلقة التدريب: تحميل النموذج، بناء مُحمِّل البيانات، تنفيذ المرورين الأمامي والخلفي، حساب خسارة مطابقة التدفق، إنشاء نقاط التفتيش، والتسجيل.
2. يحدد ملف الإعدادات بصيغة YAML جميع الإعدادات التي يستخدمها الوصفة: النموذج الذي سيتم ضبطه الدقيق، وموقع البيانات، ومعلمات المُحسِّن الفائقة، واستراتيجية التوازي، وغير ذلك. تقوم بتخصيص التدريب من خلال تحرير هذا الملف بدلاً من تعديل الكود، مما يتيح لك التوسع من وحدة معالجة رسومية واحدة إلى مئات وحدات معالجة الرسومات.

يمكن أيضًا تجاوز أي حقل في ملف YAML من سطر الأوامر:

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

فيما يلي الإعداد المُعلَّم لتدريب نموذج Wan 2.1 T2V 1.3B، مع شرح لكل قسم.

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

### مرجع حقول الإعداد

تُدرج الجدول أدناه الإعدادات الدنيا المطلوبة. راجع [أمثلة NeMo Automodel](https://github.com/NVIDIA-NeMo/Automodel/tree/main/examples/diffusion/finetune) للاطلاع على إعدادات أمثلة كاملة لجميع النماذج.

| القسم | مطلوب؟ | ما يجب تغييره |
|---------|-----------|----------------|
| `model` | نعم | اضبط `pretrained_model_name_or_path` على معرّف النموذج في Hugging Face. اضبط `mode: finetune` أو `mode: pretrain`. |
| `step_scheduler` | نعم | `global_batch_size` هو حجم الدفعة الفعّال عبر جميع وحدات معالجة الرسوميات. يتحكم `ckpt_every_steps` في تكرار إنشاء نقاط التفتيش. يتم حساب تراكم التدرجات تلقائيًا. |
| `data` | نعم | اضبط `cache_dir` على المسار الذي يحتوي على ملفات `.meta` المُعالجة مسبقًا. غيّر `_target_` و`model_type` للنماذج المختلفة. |
| `optim` | نعم | `learning_rate: 5e-6` هو الافتراضي الجيد للضبط الدقيق. اضبطه حسب مجموعة البيانات والنموذج الخاصين بك. |
| `lr_scheduler` | نعم | اختر `cosine` أو `linear` أو `constant` لـ`lr_decay_style`. اضبط `lr_warmup_steps` للتسخين التدريجي. |
| `flow_matching` | نعم | يجب أن يتطابق `adapter_type` مع النموذج (`simple` لـ Wan، و`flux` لـ FLUX، و`hunyuan` لـ HunyuanVideo). راجع إعدادات النموذج المحددة للحصول على `adapter_kwargs`. |
| `fsdp` | نعم | اضبط `dp_size` على عدد وحدات معالجة الرسومات. وفي حالة استخدام عدة عقد، اضبطه على إجمالي عدد وحدات معالجة الرسومات عبر جميع العقد. |
| `checkpoint` | موصى به | اضبط `checkpoint_dir` على مسار دائم، خاصةً في Docker. استخدم `restore_from` للاستئناف من نقطة تفتيش سابقة. |
| `wandb` | اختياري | اضبط الإعدادات لتفعيل تتبع التجارب باستخدام Weights & Biases. اضبط `mode: disabled` لإيقافه. |

## بدء التدريب

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

شغّل ما يلي على كل عقدة، مع ضبط `NODE_RANK` وفقاً لذلك:

```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]
> لتدريب متعدد العقد، اضبط `fsdp.dp_size` في ملف YAML على العدد **الإجمالي** لبطاقات GPU عبر جميع العقد (على سبيل المثال، 16 لعقدتين تحتوي كل منهما على 8 بطاقات GPU).

## التوليد

بعد التدريب، قم بتوليد مقاطع فيديو أو صور من أوامر نصية باستخدام نقطة الفحص المُحسَّنة.

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

مع نقطة تحقق مُعدّلة:

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

مع نقطة تحقق مُعدّلة:

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

مع نقطة تحقق مُعدّلة:

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

يُبنى NeMo Automodel على أساس Diffusers ويستخدمه كهيكل أساسي لتحميل النماذج والاستدلال. يقوم بتحميل النماذج مباشرةً من Hugging Face Hub باستخدام فئات نماذج Diffusers مثل [WanTransformer3DModel](/docs/diffusers/main/ar/api/models/wan_transformer_3d#diffusers.WanTransformer3DModel) و[FluxTransformer2DModel](/docs/diffusers/main/ar/api/models/flux_transformer#diffusers.FluxTransformer2DModel) و[HunyuanVideoTransformer3DModel](/docs/diffusers/main/ar/api/models/hunyuan_video_transformer_3d#diffusers.HunyuanVideoTransformer3DModel)، وينتج المخرجات عبر خطوط أنابيب Diffusers مثل [WanPipeline](/docs/diffusers/main/ar/api/pipelines/wan#diffusers.WanPipeline) و[FluxPipeline](/docs/diffusers/main/ar/api/pipelines/flux#diffusers.FluxPipeline).

توفر هذه التكاملات عدة فوائد لمستخدمي Diffusers:

- **لا حاجة لتحويل نقاط التفتيش**: تعمل الأوزان المُسبقة التدريب من المستودع مباشرةً. وجّه `pretrained_model_name_or_path` إلى أي معرّف نموذج بتنسيق Diffusers وابدأ التدريب فورًا.
- **دعم النماذج من اليوم الأول**: عند إضافة نموذج انتشار جديد إلى Diffusers ورفعته إلى Hub، يمكن ضبطه بدقة باستخدام NeMo Automodel دون الحاجة إلى الانتظار حتى توفر سكربت تدريب مخصص.
- **المخرجات المتوافقة مع خطوط الأنابيب**: تُحفظ نقاط التفتيش المُحسَّنة في صيغة يمكن تحميلها مباشرةً مرة أخرى في خطوط أنابيب Diffusers للاستدلال، أو للمشاركة على Hub، أو للمزيد من التحسين باستخدام أدوات مثل التكميم والتجميع.
- **تدريب قابل للتوسع لنماذج Diffusers**: يضيف NeMo Automodel قدرات التدريب الموزّع (FSDP2، متعدد العقد، تجميع متعدد الدقة) التي تتجاوز ما توفره سكربتات تدريب Diffusers المدمجة، مع الحفاظ على نفس واجهات النماذج والأنابيب.
- **النظام البيئي المشترك**: أي نموذج، أو مُكيّف LoRA، أو مكوّن خط أنابيب من نظام Diffusers البيئي يبقى متوافقًا عبر سير عمل التدريب والاستدلال بالكامل.

## فريق NVIDIA

- Pranav Prashant Thombre، pthombre@nvidia.com
- لينان وانغ، linnanw@nvidia.com
- Alexandros Koumparoulis, akoumparouli@nvidia.com

## الموارد

- [NeMo Automodel GitHub](https://github.com/NVIDIA-NeMo/Automodel)
- [دليل ضبط النماذج التوليدية الانتشارية](https://docs.nvidia.com/nemo/automodel/latest/recipes-e2e-examples/diffusion-fine-tuning)
- [تجهيز مجموعة بيانات الانتشار](https://docs.nvidia.com/nemo/automodel/latest/datasets/diffusion-dataset)
- [تغطية نماذج الانتشار](https://docs.nvidia.com/nemo/automodel/latest/model-coverage/diffusion.html)
- [NeMo Automodel لـ Transformers (ضبط نماذج LLM/VLM)](https://huggingface.co/docs/transformers/en/community_integrations/nemo_automodel_finetuning)