# المُحسِّنات والمُجدوِلات

يحدّث المُحسِّن أوزان النموذج أثناء التدريب. يغلّف المجدول المُحسِّن ويضبط معدل التعلم في كل خطوة تدريب. ينشئ [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) كلاهما عند استدعائه [create_optimizer_and_scheduler()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer_and_scheduler).

```md
                                    ┌────────────┐         ┌──────────────┐
                                    │ Optimizer  │         │  Scheduler   │
                                    │ (adamw_torch_fused)◄─│  (linear)    │
                                    │            │         │              │
                                    │ param_groups         |              |
                                    │  └ lr       ◄────────┤              |
                                    │  └ weight_decay      │              │
                                    └──────┬─────┘         └──────────────┘
                                           │                      
  ┌──── EACH TRAINING STEP ───────────────────────────────────────────┐
  │                                        │                          │
  │   model(batch)                         │                          │
  │       │                                │                          │
  │       ▼                                │                          │
  │     loss ──► loss.backward() ──► param.grad                       │
  │                                        │                          │
  │                          ┌─────────────┘                          │
  │                          ▼                                        │
  │              optimizer.step()                                     │
  │                          │                                        │
  │                          ▼                                        │
  │                   param.data updated                              │
  │                          │                                        │
  │                          ▼                                        │
  │              lr_scheduler.step()  ──► recalculates lr             │
  │                          │            writes to optimizer         │
  │                          ▼            .param_groups['lr']         │
  │              model.zero_grad()                                    │
  │                                                                   │
  └───────────────────────────────────────────────────────────────────┘
```

اضبط سلوك المُحسِّن والمجدول، مثل `lr_scheduler_type()` و`optim()`، في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments). تُعدّ القيم الافتراضية (مُحسِّن `adamw_torch` ومجدول التسخين `linear`) نقطة انطلاق جيدة لمعظم عمليات الضبط الدقيق.

```py
from transformers import TrainingArguments

args = TrainingArguments(
    ...,
    # Optimizer
    optim="adamw_torch",          # or "adamw_torch_fused", "adafactor", "sgd", etc.
    learning_rate=2e-5,
    weight_decay=0.01,
    adam_beta1=0.9,
    adam_beta2=0.999,
    adam_epsilon=1e-8,
    # Scheduler
    lr_scheduler_type="cosine",   # "linear", "cosine", "constant_with_warmup", etc.
    warmup_steps=500,
    lr_scheduler_kwargs={"num_cycles": 3},  # scheduler-specific extras
)
```

## المجدولون المعتمدون على المقاييس

تتكيف بعض مجدولات التعلم مع ديناميكيات التدريب بدلاً من اتباع جدول ثابت.

يحدّث [GreedyLR](https://huggingface.co/papers/2512.14527) معدل التعلم من نتائج التقييم. فهو يرفع معدل التعلم بقسمته على `factor` عندما يستمر المؤشر في التحسّن، ويخفض معدل التعلم بضربه في `factor` عندما لا يتحسّن المؤشر. وعندما يتوقف معدل التعلم عند `min_lr` ولا يتحسّن بعد `reset_start` خطوة، يعيد [GreedyLR](/docs/transformers/main/ar/main_classes/optimizer_schedules#transformers.GreedyLR) ضبط نفسه إلى حالته الأولية ويبدأ دورة جديدة.

يتطلب [GreedyLR](/docs/transformers/main/ar/main_classes/optimizer_schedules#transformers.GreedyLR) التقييم أثناء التدريب. اضبط `eval_strategy` على `"steps"` أو `"epoch"`.

```diff
args = TrainingArguments(
+   lr_scheduler_type="greedy",
+   lr_scheduler_kwargs={"patience": 10, "factor": 0.95, "min_lr": 1e-5},
+   eval_strategy="steps",
+   eval_steps=200,
    ...  # remaining args from the TrainingArguments intro config
)
```

> [!TIP]
> يعمل الوضع الافتراضي `mode="min"` مع الخسارة. إذا كنت تتتبع مقياسًا تكون فيه القيمة الأعلى أفضل، مثل الدقة، فمرّر `"mode": "max"` في `lr_scheduler_kwargs`.

راجع فئة [GreedyLR](/docs/transformers/main/ar/main_classes/optimizer_schedules#transformers.GreedyLR) للحصول على القائمة الكاملة للمعلمات القابلة للضبط.

## تكاملات المُحسِّن

تدمج مكتبة Transformers محسّنات الطرف الثالث لسيناريوهات التدريب المتخصصة.

| المُحسِّن | تثبيت | `optim="value"` | الوصف |
|---|---|---|---|
| APOLLO | `apollo-torch` | `apollo_adamw` | كفاءة في استخدام الذاكرة عبر الإسقاطات العشوائية؛ رتبة 1 كافية |
| GrokAdamW | `grokadamw` | `grokadamw` | يستهدف التعميم المتأخر (الغروكينغ) |
| LOMO / AdaLomo | `lomo-optim` | `lomo` / `adalomo` | يجمع بين خطوة تدرّج خطوة التحديث لتدريب كامل المعاملات بذاكرة منخفضة |
| جدولة مجانية | `schedulefree` | `schedule_free_adamw`, `schedule_free_radam`, `schedule_free_sgd` | يلغي تخفيف معدل التعلم؛ يُستخدم مع `lr_scheduler_type="constant"` |
| GaLore | `galore-torch` | `galore_adamw`, `galore_adafactor`, `galore_adamw_8bit` | التعلم الكامل للمعاملات عبر الإسقاط منخفض الرتبة للتدرجات |
| StableAdamW | `torch-optimi` | `stable_adamw` | قصّ تحديث AdamW + AdaFactor؛ لا حاجة إلى قصّ التدرّجات |

```bash
pip install apollo-torch
```

[تقريب تدرّج التدرّج لتحسين نماذج اللغة الكبيرة بكفاءة في الذاكرة (APOLLO)](https://huggingface.co/papers/2412.05270) هو مُحسِّن موفّر للذاكرة للتعلم الكامل للمعاملات أثناء التدريب المسبق والتدريب الدقيق. إنه يطابق أداء AdamW بتكلفة ذاكرة مشابهة لتكلفة SGD من خلال استخدام إسقاطات عشوائية رخيصة بدلاً من SVD. للحصول على توفير أقصى للذاكرة، استخدم APOLLO-Mini، وهو متغير من الدرجة الأولى.

استخدم معامل `optim_target_modules` لتحديد الطبقات التي تريد تدريبها.

```diff
args = TrainingArguments(
+   optim="apollo_adamw",
+   optim_target_modules=[r".*.attn.*", r".*.mlp.*"],
    ...  # remaining args from the TrainingArguments intro config
)
```

مرّر معاملات فائقة إضافية عبر `optim_args`.

> [!TIP]
> اضبط `scale` على `n/r`، حيث `n` هو بُعد الفضاء الأصلي و`r` هو بُعد الفضاء منخفض الرتبة. إن ضبط معدل التعلم مع إبقاء `scale` على قيمته الافتراضية يحقق تأثيرًا مشابهًا.

| معامل | الوصف | APOLLO | APOLLO-Mini |
|---|---|---|---|
| الترتيب | رتبة الفضاء الفرعي المساعد لتقليص التدرج | 256 | 1 |
| scale_type | كيف تُطبَّق عوامل التوسيع | `channel` (تصعيد لكل قناة) | `tensor` (مقياس لكل متجه) |
| scale | يُعدّل تحديثات التدرّج لتثبيت التدريب | 1.0 | 128 |
| update_proj_gap | الخطوات قبل تحديث مصفوفات الإسقاط | 200 | 200 |
| proj | نوع الإسقاط | `random` | `random` |

تفعيل APOLLO-Mini بتكوين من الدرجة الأولى.

```py
args = TrainingArguments(
    optim="apollo_adamw",
    optim_target_modules=[r".*.attn.*", r".*.mlp.*"],
    optim_args="proj=random,rank=1,scale=128.0,scale_type=tensor,update_proj_gap=200",
    ...  # remaining args from the TrainingArguments intro config
)
```

```bash
pip install grokadamw
```

يستهدف [GrokAdamW](https://github.com/cognitivecomputations/grokadamw) ظاهرة *grokking*، حيث تُظهر النماذج تعميماً متأخراً بسبب التدرجات التي تتغير ببطء.

```diff
args = TrainingArguments(
+   optim="grokadamw",
    ...  # remaining args from the TrainingArguments intro config
)
```

```bash
pip install lomo-optim
```

يتضمن [تحسين ذاكرة منخفضة (LOMO)](https://github.com/OpenLMLab/LOMO) مُحسِّنين لتدريب كامل المعلمات بذاكرة منخفضة، وهما [LOMO](https://huggingface.co/papers/2306.09782) و[AdaLomo](https://hf.co/papers/2310.10195). يدمج كلاهما حساب التدرجات وتحديث المعلمات في خطوة واحدة. يضيف AdaLomo معدل تعلم تكيفي لكل معلمة على حدة، على غرار Adam.

> [!TIP]
> يعمل AdaLomo بشكل أفضل دون `grad_norm`، مما يحسّن الأداء ومعدل الإنتاجية.

```diff
args = TrainingArguments(
+   optim="adalomo",
    learning_rate=2e-6,
    ...  # remaining args from the TrainingArguments intro config
)
```

```bash
pip install schedulefree
```

يستبدل [مُحسِّن الجدولة المجانية (SFO)](https://hf.co/papers/2405.15682) العزم بمزيج من المتوسطات والاستيفاء، مما يلغي الحاجة إلى تليين معدل التعلم بالكامل.

يدعم SFO محسّنات RAdam (`schedule_free_radam`) وAdamW (`schedule_free_adamw`) وSGD (`schedule_free_sgd`). ولا يتطلب مجدول RAdam `warmup_steps`.

استخدم SFO مع `lr_scheduler_type="constant"`. تعمل أنواع جدولة أخرى، لكنها تؤثر على السلوك المقصود لـ SFO.

```diff
args = TrainingArguments(
+   optim="schedule_free_radam",
+   lr_scheduler_type="constant",
    learning_rate=2e-6,
    ...  # remaining args from the TrainingArguments intro config
)
```

```bash
pip install torch-optimi
```

ينقل [StableAdamW](https://huggingface.co/papers/2304.13013) آلية تقليم التحديثات من AdaFactor إلى AdamW، مما يلغي الحاجة إلى تقليم التدرجات. وبخلاف ذلك، فهو بديل مباشر لـ AdamW.

> [!TIP]
> إذا كنت تدرب باستخدام أحجام دفعات كبيرة أو ما زلت تلاحظ قفزات في دالة الخسارة، فحاول ضبط `beta_2` بين 0.95 و0.99.

```diff
args = TrainingArguments(
+   optim="stable_adamw",
    learning_rate=2e-6,
    ...  # remaining args from the TrainingArguments intro config
)
```

```bash
pip install galore-torch trl
```

يقلل [Gradient Low-Rank Projection (GaLore)](https://hf.co/papers/2403.03507) من استهلاك الذاكرة عند تدريب نماذج اللغة الكبيرة. وعلى عكس طرق التكيف ذات الرتبة المنخفضة مثل [LoRA](https://hf.co/papers/2106.09685)، يحافظ GaLore على التعلم بـ*جميع المعاملات*.

اضبط `optim` في [trl.SFTConfig](https://huggingface.co/docs/trl/main/en/sft_trainer#trl.SFTConfig) على مُحسِّن GaLore (`"galore_adamw"` أو `"galore_adafactor"` أو `"galore_adamw_8bit"`). حدّد الوحدات المستهدفة عبر `optim_target_modules`، وحدّد المعاملات الخاصة بـ GaLore (`rank`، `update_proj_gap`، `scale`) عبر `optim_args`.

```py
from trl import SFTConfig

args = SFTConfig(
    output_dir="./galore",
    max_steps=100,
    optim="galore_adamw",
    optim_target_modules=[r".*.attn.*", r".*.mlp.*"],
    optim_args="rank=64, update_proj_gap=100, scale=0.10",
)
```

أضف `_layerwise` إلى اسم المُحسِّن (optimizer) لتحسين الطبقات (`"galore_adamw_layerwise"`). تُستخدم التفكيك منخفض الرتبة (low-rank decomposition) فقط للطبقات الخطية المستهدفة بواسطة GaLore. أما جميع الطبقات الأخرى فتُحسَّن بشكل عادي.

```py
from trl import SFTConfig, SFTTrainer

args = SFTConfig(
    output_dir="./galore",
    max_steps=100,
    optim="galore_adamw_layerwise",
    optim_target_modules=[r".*.attn.*", r".*.mlp.*"],
    optim_args="rank=64, update_proj_gap=100, scale=0.10",
)
```

وضع الطبقة تلو الأخرى تجريبي. فهو يعمل على [وحدة معالجة رسومية واحدة](https://github.com/jiaweizzhao/GaLore?tab=readme-ov-file#train-7b-model-with-a-single-gpu-with-24gb-memory) فقط، ولا يدعم DistributedDataParallel (DDP)، وقد لا تعمل قص التدرجات أو DeepSpeed.

## تخصيص المُحسِّن والمجدول

أنشئ مُحسِّناً وجدولة مخصصين لاستخدام مُحسِّن لم يتم دمجه بعد، أو لضبط معدلات التعلم لكل طبقة، أو لتطبيق منطق مخصص.

### مرّر فئة وkwargs

يقبل `~Trainer.optimizer_cls_and_kwargs` فئة مُحسِّن مخصصة، مع تفويض تجميع المعاملات وتحديد الموقع على الجهاز إلى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

يؤجّل [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) إنشاء المُحسِّن حتى يتم تنفيذ [create_optimizer()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer)، بحيث يكون النموذج موجودًا بالفعل على الجهاز الصحيح.

```py
import torch

trainer = Trainer(
    ...
    optimizer_cls_and_kwargs=(
        torch.optim.SGD,
        {"momentum": 0.9, "nesterov": True}
    ),
)
```

### تمرير الكائنات الجاهزة

مرّر مُحسِّنًا ومجدولًا مُعرَّفين مسبقًا إلى `~Trainer.optimizers`. يتخطى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) استدعاء [create_optimizer()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer) و[create_scheduler()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_scheduler) عند توفير كائنات جاهزة مسبقًا. إذا لم تمرر مجدولًا، فإن [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) ينشئ واحدًا تلقائيًا.

> [!WARNING]
> أنشئ المُحسِّن بعد وضع النموذج على الجهاز الصحيح. يتم تحديد المعاملات عند الإنشاء، قبل أن ينقل `Trainer` النموذج. في التدريب الموزّع، قد تُسبّب الأجهزة غير المتطابقة سلوكًا غير صحيح بصمت.

```py
import torch
from transformers import Trainer, get_cosine_schedule_with_warmup

optimizer = torch.optim.AdamW(model.parameters(), lr=2e-5)
scheduler = get_cosine_schedule_with_warmup(
    optimizer, num_warmup_steps=500, num_training_steps=10_000
)

trainer = Trainer(
    ...
    optimizers=(optimizer, scheduler),
)
```

تتجاوز الأمثلة الجاهزة [create_optimizer()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer) و [create_scheduler()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_scheduler)، لذا عليك تحديد مجموعات المعلمات الخاصة بك.

### تجاوز طرق المُحسِّن والمجدول

أنشئ فئة فرعية من [create_optimizer()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer) و [create_scheduler()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_scheduler) للحصول على تحكم كامل. يتم تنفيذ كلا الطريقتين *أثناء* تشغيل [train()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.train).

استبدل [create_scheduler()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_scheduler) لاستخدام جدولة مثل [OneCycleLR](https://docs.pytorch.org/docs/stable/generated/torch.optim.lr_scheduler.OneCycleLR.html) غير المتوفرة في [SchedulerType](/docs/transformers/main/ar/main_classes/optimizer_schedules#transformers.SchedulerType).

بالنسبة لكل طريقة، تأكد من إسناد القيمة إلى `self` وإرجاعها.

```py
import torch
from transformers import Trainer

class MyTrainer(Trainer):

    def create_scheduler(self, num_training_steps, optimizer=None):
        optimizer = optimizer or self.optimizer
        self.lr_scheduler = torch.optim.lr_scheduler.OneCycleLR(
            optimizer,
            max_lr=0.1,
            total_steps=num_training_steps,
        )
        return self.lr_scheduler
```

لا تحتاج إلى تجاوز [create_optimizer()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.create_optimizer) إذا كان المُحسِّن الافتراضي يعمل بشكل صحيح. من الأسهل توسيع طريقة باستخدام `super()` بدلاً من استبدالها بالكامل. على سبيل المثال، أضف مجموعة معلمات إضافية مع إبقاء كل شيء آخر كما هو.

```py
class MyTrainer(Trainer):
    def create_optimizer(self, model=None):
        super().create_optimizer(model)  # builds the default two param groups
        # add extra param group
        self.optimizer.add_param_group({
            "params": self.model.classifier.parameters(),
            "lr": self.args.learning_rate * 10,
        })
        return self.optimizer
```