# Оптимизаторы и планировщики

Оптимизатор обновляет веса модели в процессе обучения. Планировщик оборачивает оптимизатор и корректирует скорость обучения на каждом шаге обучения. [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer) создаёт оба объекта, когда вызывает [create_optimizer_and_scheduler()](/docs/transformers/main/ru/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/ru/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/ru/main_classes/optimizer_schedules#transformers.GreedyLR) сбрасывается в исходное состояние и начинает новый цикл.

Для [GreedyLR](/docs/transformers/main/ru/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/ru/main_classes/optimizer_schedules#transformers.GreedyLR) для полного списка настраиваемых параметров.

## Интеграции с оптимизаторами

Transformers интегрирует сторонние оптимизаторы для специализированных сценариев обучения.

| Оптимизатор | Установка | `optim="value"` | Описание |
|---|---|---|---|
| APOLLO | `apollo-torch` | `apollo_adamw` | Эффективная по памяти полная параметризация с помощью случайных проекций; достаточно ранга 1 |
| GrokAdamW | `grokadamw` | `grokadamw` | Целенаправленно откладывает обобщение (grokking) |
| LOMO / AdaLomo | `lomo-optim` | `lomo` / `adalomo` | Объединяет шаги градиента и обновления для дообучения всех параметров с низким потреблением памяти |
| Без расписания | `schedulefree` | `schedule_free_adamw`, `schedule_free_radam`, `schedule_free_sgd` | Убирает аннелинг LR; используйте в паре с `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
```

[Approximated Gradient Scaling for Memory Efficient LLM Optimization (APOLLO)](https://huggingface.co/papers/2412.05270) — это оптимизатор с низким потреблением памяти для обучения всех параметров на этапах предобучения и дообучения. Он обеспечивает производительность, сопоставимую с AdamW, при затратах на память, близких к SGD, за счёт использования дешёвых случайных проекций вместо SVD. Для максимального сокращения потребления памяти используйте APOLLO-Mini — вариант с рангом 1.

Используйте параметр `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 |
|---|---|---|---|
| rank | ранг вспомогательного подпространства для масштабирования градиентов | 256 | 1 |
| scale_type | как применяются коэффициенты масштабирования | `channel` (масштабирование по каналам) | `tensor` (масштабирование на уровне тензора) |
| scale | корректирует обновления градиентов для стабилизации обучения | 1.0 | 128 |
| update_proj_gap | шагов до обновления матриц проекций | 200 | 200 |
| proj | тип проекции | `random` | `random` |

Включите APOLLO-Mini с конфигурацией rank-1.

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

[Low-Memory Optimization (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
```

[Оптимизатор Schedule Free (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) снижает потребление памяти при обучении LLM. В отличие от методов низко-ранговой адаптации, таких как [LoRA](https://hf.co/papers/2106.09685), GaLore сохраняет обучение *всех параметров*.

Укажите в [trl.SFTConfig](https://huggingface.co/docs/trl/main/en/sft_trainer#trl.SFTConfig) параметр `optim` со значением оптимизатора 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` к имени оптимизатора для послойной оптимизации (`"galore_adamw_layerwise"`). Низкоранговое разложение применяется только к линейным слоям, на которые нацелен 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",
)
```

Режим Layerwise является экспериментальным. Он работает только на [одном GPU](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/ru/main_classes/trainer#transformers.Trainer).

[Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer) откладывает создание оптимизатора до выполнения [create_optimizer()](/docs/transformers/main/ru/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/ru/main_classes/trainer#transformers.Trainer) пропускает вызовы [create_optimizer()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.create_optimizer) и [create_scheduler()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.create_scheduler), если предоставлены готовые экземпляры. Если вы не передаёте планировщик, [Trainer](/docs/transformers/main/ru/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/ru/main_classes/trainer#transformers.Trainer.create_optimizer) и [create_scheduler()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.create_scheduler), поэтому вам необходимо самостоятельно указать группы параметров.

### Переопределение методов оптимизатора и планировщика

Создайте подклассы [create_optimizer()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.create_optimizer) и [create_scheduler()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.create_scheduler) для полного контроля. Оба метода выполняются *в процессе* [train()](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer.train).

Переопределите [create_scheduler()](/docs/transformers/main/ru/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/ru/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/ru/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
```

