# Асинхронная дистилляция

> [!IMPORTANT]
> Этот тренажёр требует `vllm`, `transformers>=5.2.0` и `kernels` (при обучении FlashAttention загружается из Hub через него). Для распределённого обучения поддерживается только FSDP2 (DeepSpeed ZeRO не поддерживается).
>
> В настоящее время `vllm` и `transformers` имеют конфликтующие ограничения зависимостей. Чтобы обойти это, сначала установите vLLM, затем принудительно установите transformers, после чего добавьте `kernels` через extra TRL, который фиксирует версию, принимаемую transformers:
>
> ```bash
> pip install vllm
> pip install 'transformers>=5.2.0' --no-deps
> pip install 'trl[kernels]'
> ```

## Обзор

[experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.1/ru/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) — это асинхронный аналог [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer), построенный по образцу [AsyncGRPOTrainer](/docs/trl/v1.18.1/ru/async_grpo_trainer#trl.AsyncGRPOTrainer): фоновый рабочий процесс генерации создаёт собственные on-policy завершения студента и оценивает их с помощью учителя, в то время как обучение продолжается параллельно, а не чередуется между генерацией и обновлением градиентов. В отличие от синхронного тренера, учитель никогда не загружается локально — достаточно только URL-адреса сервера vLLM, поэтому учитель может работать на полностью отдельном от студента и тренера оборудовании или даже быть моделью значительно большего размера, чем могла бы поместиться рядом со студентом.

`compute_loss` минимизирует обобщённую дивергенцию Йенсена–Шеннона между распределениями токенов по позициям для ученика и учителя (`beta=0.0` — прямая KL-дивергенция, `beta=1.0` — обратная KL-дивергенция, промежуточные значения интерполируют между ними), тот же целевой функционал, что используют [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer) и `ServerDistillationTrainer`. Обучение всегда выполняется on-policy: ученик генерирует каждую завершённую последовательность, на которой обучается.

### Мультиучительная on-policy дистилляция (MOPD)

MOPD не входит в состав статьи [2306.13649](https://huggingface.co/papers/2306.13649), на основе которой построена основная цель данного тренера (она описывает синхронный сценарий с одним учителем); это отдельный метод, описанный в [MOPD: Multi-Teacher On-Policy Distillation for Capability Integration in LLM Post-Training]( https://huggingface.co/papers/2606.30406). Там MOPD является третьим из трех этапов — сначала общее SFT, затем независимая RL-обучение одного эксперта на каждый домен, после чего MOPD объединяет этих замороженных экспертов в одного студента. `AsyncDistillationTrainer` реализует только этот третий, объединяющий этап: эксперты-учителя по доменам должны уже существовать (например, обучены отдельно с помощью [GRPOTrainer](/docs/trl/v1.18.1/ru/grpo_trainer#trl.GRPOTrainer)/[RLOOTrainer](/docs/trl/v1.18.1/ru/rloo_trainer#trl.RLOOTrainer)) и обслуживаться по HTTP, прежде чем вы укажете на них `teacher_server_urls`. В самой статье для этапа 3 используется обратный KL (`beta=1.0`), а не значение по умолчанию этого тренера `beta=0.0` (прямой KL).

`teacher_server_urls` принимает более одного элемента. При наличии одного элемента все образцы оцениваются этим единственным учителем (простая дистилляция on-policy). При нескольких элементах столбец `teacher_id` каждого обучающего образца определяет, какой учитель будет его оценивать, — например, запросы по математике направляются учителю-специалисту по математике, а запросы по коду — учителю-специалисту по коду, каждый из которых обслуживается независимо. Каждый образец направляется только на своего соответствующего учителя, усреднение или ансамблирование между учителями не применяются. Если у образца отсутствует или не сопоставлен `teacher_id`, возникает исключение, а не происходит молчаливого переключения на неверного учителя. См. `examples/async_distillation_mopd/async_distillation_mopd.py` для рабочего примера, объединяющего экспертов по математике, коду и следованию инструкциям, выпущенных вместе с [Open-MOPD](https://huggingface.co/papers/2608.19098), в их общий SFT-чекпоинт, а также `examples/async_distillation_mopd/launcher.py` для запуска на 4 GPU одной командой [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs).

> [!WARNING]
> Каждый учитель должен использовать тот же токенизатор, что и ученик. Завершения передаются учителям в виде сырых идентификаторов токенов, а идентификаторы кандидатов, которые учитель возвращает, напрямую индексируют собственный словарь ученика в `compute_loss`. Учителя из той же семейства моделей, что и ученик (как в примере MOPD, где ученик SmolLM3 формируется из экспертов SmolLM3, обученных из одной и той же контрольной точки), удовлетворяют этому условию; учитель с другим словарём обучает ученика на неверных токенах, что остаётся незамеченным, если только его словарь не больше словаря ученика.

**Создание контрольных точек и возобновление**: параметр `ignore_data_skip` по умолчанию установлен в `True`; цикл пропуска и повторного воспроизведения базового Trainer не применяется к живой очереди rollout. Вместо этого индекс первого промпта, по которому ещё не проводилась тренировка, сохраняется в `rollout_state.json` вместе с каждой контрольной точкой и восстанавливается при возобновлении, благодаря чему worker быстро перемотывает к этому промпту без повторного воспроизведения образцов. Это позиция *обученных* данных, а не генератора: worker опережает тренировку на глубину очереди rollout, и эти буферизованные образцы теряются при завершении запуска, поэтому возобновление с позиции генератора привело бы к пропуску промптов, которые были сгенерированы, но не использовались для обучения. Потоковые наборы данных (`IterableDataset`) нельзя перемотать; их worker при возобновлении начинает с промпта 0. При использовании FSDP с `bf16=True` (по умолчанию) или `fp16=True` файл `model.safetensors` записывается в этом типе данных, даже если основные веса имеют тип fp32, поэтому опубликованная контрольная точка имеет размер модели, используемой для обслуживания, а не вдвое больше; основные веса fp32 и состояние оптимизатора по-прежнему записываются в файлы для возобновления (`pytorch_model_fsdp.bin`, `optimizer.bin`), которые и читаются при возобновлении, поэтому процесс возобновления не затрагивается. Без FSDP контрольная точка также является файлом для возобновления, поэтому она сохраняет основной тип данных.

## Чем отличается от [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer)

В [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer) учитель — это локально загруженная модель: генерация, прямой проход учителя и обновление градиентов выполняются последовательно в одном процессе. [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.1/ru/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) разделяет эти задачи так же, как [AsyncGRPOTrainer](/docs/trl/v1.18.1/ru/async_grpo_trainer#trl.AsyncGRPOTrainer) разделяет rollout и обновление в GRPO:

- **Рабочий процесса rollout** (фоновый процесс) — генерирует завершения с vLLM-сервера ученика, отправляет полную последовательность обратно на `/v1/completions` разрешённого учителя с параметром `prompt_logprobs` для teacher-forced оценки (учитель не генерирует новые токены) и помещает готовые к обучению образцы в очередь.
- **Цикл обучения** (основной процесс) — извлекает примеры из очереди, вычисляет обобщённую потерю JSD и обновляет веса ученика.

Поскольку оценка учителя выполняется по HTTP, а не через локальный прямой проход, передаётся только разреженный верхний k-срез его распределения (`teacher_top_k`), а не полное пространство словаря — см. документацию к параметрам `beta` и `teacher_top_k` в [experimental.async_distillation.AsyncDistillationConfig](/docs/trl/v1.18.1/ru/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig), где точно указано, для каких кандидатов протокол гарантирует получение logprob от учителя в каждом режиме `beta`.

Каждые `weight_sync_steps` шагов обучения обновлённые веса студента передаются на его сервер vLLM через NCCL. Как и в случае с [AsyncGRPOTrainer](/docs/trl/v1.18.1/ru/async_grpo_trainer#trl.AsyncGRPOTrainer), генерация опережает обучение, поэтому образцы могут отражать слегка устаревшую политику; `max_staleness` определяет, на сколько обновлений весов образец может отставать, прежде чем быть отброшенным.

## Быстрый старт

```python
# train_async_distillation.py
from datasets import load_dataset
from trl.experimental.async_distillation import AsyncDistillationTrainer

if __name__ == "__main__":  # the rollout worker is a spawned process that re-imports this script
    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

    trainer = AsyncDistillationTrainer(
        model="Qwen/Qwen2.5-0.5B-Instruct",
        train_dataset=dataset,
    )
    trainer.train()
```

Сервер учителя, vLLM-сервер ученика и тренер должны работать на **отдельных GPU**. Оба представляют собой обычные экземпляры `vllm serve`, но требуют разных флагов: учитель используется только для оценки (`--logprobs-mode processed_logprobs`, чтобы `teacher_temperature` влияло на возвращаемые logprobs, и `--max-logprobs -1`, чтобы `teacher_top_k` могло превышать стандартное ограничение vLLM в 20), тогда как ученик используется только для генерации и требует включения передачи весов через NCCL, чтобы тренер мог передавать в него обновлённые веса. При оценке отправляется вся последовательность ученика, и учитель запрашивается для одного дополнительного токена, поэтому значение `--max-model-len` учителя (или его значение по умолчанию) должно быть больше, чем у ученика:

```bash
# Terminal 1: teacher server on GPU 0 (static, never updated)
CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-1.5B-Instruct \
    --port 8001 \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1
```

```bash
# Terminal 2: student's vLLM server on GPU 1 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
    --port 8000 \
    --weight-transfer-config '{"backend":"nccl"}'
```

```bash
# Terminal 3: training on GPU 2
CUDA_VISIBLE_DEVICES=2 python train_async_distillation.py
```

## LoRA

Передайте `peft_config`, чтобы обучить адаптер LoRA на студенте, а не на полной модели:

```python
from peft import LoraConfig

trainer = AsyncDistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)
```

Каждый синхронизационный цикл требует передачи обновлённой модели-ученика на её сервер. По умолчанию тренер объединяет адаптер с базовой моделью и отправляет полные объединённые веса, что составляет около 15 ГБ для модели 7B при каждой синхронизации. Запустите vLLM-сервер ученика с флагом `--enable-lora`, и он будет отправлять только адаптер, что составляет около 160 МБ при `r=32`:

```bash
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
    --port 8000 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6
```

`VLLM_ALLOW_RUNTIME_LORA_UPDATING=1` открывает эндпоинт, на который тренер отправляет каждый новый адаптер. Добавьте `VLLM_WORKER_MULTIPROC_METHOD=spawn`, если вы используете тензорное параллельное обслуживание, и в любом случае сохраняйте `--weight-transfer-config`: тренер выбирает режим синхронизации только при запуске, к этому моменту сервер уже запущен, а синхронизация с объединением весов является вариантом по умолчанию. Сервер учителя не затрагивается: он никогда не обновляется.

`--max-lora-rank` должен быть одним из `1, 8, 16, 32, 64, 128, 256, 320, 512`. Он задает максимальный ранг, который сервер может обслуживать, а не ранг, который будет использоваться по умолчанию, поэтому адаптер с `r=4` корректно работает при значении `8`. `--max-loras` должен быть не менее `max_staleness + 2`: тренер регистрирует `max_staleness + 1` версий адаптеров, чтобы роллаут, начатый при более старой политике, мог завершиться при ней, а не переключаться на новую в процессе генерации, а при каждой синхронизации загружается следующая версия до разгрузки самой старой. Тренер проверяет оба значения при запуске и сообщает, с какими параметрами нужно перезапустить сервер.

vLLM загружает адаптеры с диска, а не по сети, поэтому тренер записывает каждую версию в `<output_dir>/.vllm_lora/` и передаёт серверу путь. Если сервер работает на другой машине, этот каталог должен находиться на файловой системе, доступной обоим узлам.

> [!WARNING]
> `<output_dir>/.vllm_lora/` — это кэш для обслуживания, а не место, где хранится обученный адаптер. В нём содержатся только самые последние версии, причём каждая из них удаляется вскоре после того, как выходит из окна устаревания. Именно чекпоинты сохраняют обученный вами адаптер, поэтому не отключайте их: при `save_strategy="no"` многочасовой запуск завершится, не оставив после себя ничего. `output_dir` также должен быть доступен для чтения сервером и должен пережить завершение задачи, поэтому локальный временный каталог узла не подойдёт, даже если он позволил бы избежать синхронизации с медленной общей файловой системой.

> [!TIP]
> Синхронизация адаптеров не всегда быстрее. При обслуживании LoRA-адаптера vLLM генерирует токены примерно в 1,33–1,39 раза медленнее, чем при обслуживании объединённых весов, а именно генерация обычно определяет общее время выполнения. Взамен вы получаете значительно более короткий перерыв при каждой синхронизации и использование около 1% пропускной способности канала синхронизации. Если узким местом является пропускная способность генерации, объединённая синхронизация часто остаётся лучшим выбором.

## Записываемые метрики

Rollout проходит через несколько этапов, прежде чем превратиться в градиент. Сначала рассмотрим эти этапы: от промпта до финального состава батча:

```
Dataset row = PROMPT (message list + optional `teacher_id`)
 └─ ROLLOUT            (1 prompt -> 1 student completion -> 1 teacher scoring call)
     ├─ generate       (student's vLLM /v1/completions, sampled)
     └─ score          (the routed teacher's /v1/completions with `prompt_logprobs`, teacher-forced)
         └─ SAMPLE     (prompt + completion + the teacher's sparse per-position distribution)

════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════

         └─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
             └─ ROW            (Planner assigns it to one of `dp` rows, Σ Lᵢ²-balanced)
                 └─ MICRO-BATCH (`dp` rows, one per rank)
                     └─ PACKED ROW (1 concat sequence, `position_ids` reset per sample)
                         └─ FORWARD (`compute_loss`, bs=1, inter-rank padding stripped)
             └─ OPTIMIZER STEP (from `grad_accum` micro-batches)
```

Чтение сверху вниз:

- **rollout** — это один промпт, сгенерированный и оценённый один раз. Группы не существует: в дистилляции нет базовой линии преимущества для вычисления между поколениями, поэтому промпт не повторяется, и один rollout даёт ровно один обучающий пример.
- примером **sample** является это дополнение вместе с топ-`teacher_top_k` кандидатами учителя для каждой позиции дополнения. Именно это передаётся через границу процесса.
- за пределами границы тренер распределяет образцы по **строкам** (по одной на каждый ранг DP), упаковывает каждую строку в одну конкатенированную последовательность и накапливает `grad_accum` микробатчи в один шаг оптимизатора.

Таким образом, мы разделяем наши метрики в зависимости от того, какой этап (или _сущность_) они описывают:

| namespace      | сущность, которую он считает                                                            |
| -------------- | --------------------------------------------------------------------------- |
| `rollout/`     | один цикл генерации и оценки: сколько времени он занял и насколько далеко продвинулся         |
| `completions/` | что студент (vLLM) сгенерировал для одного запроса                            |
| `sample/`      | представляет _один_ пример обучения, такой, каким он поступает в очередь                |
| `batch/`       | один микро-батч или один шаг оптимизатора (сформированный из одного или нескольких образцов)  |
| `perf/`        | измеренные секунды и FLOPs                                                  |

Всё, что измеряет сама функция потерь, логируется без префикса (`jsd`, `entropy`, `teacher_entropy`), а при MOPD — с детализацией по `teacher/<teacher_id>/*` — см. [расхождение](#the-divergence) ниже.

Давайте также определим некоторые термины, чтобы метрики токенов были однозначными:

- токены **generated** — это то, что сгенерировал ученик (`completions/*`).
- К **forwarded** токенам относятся все токены, которые обрабатывает проход _forward_: промпт и сгенерированные токены.
- Токены **trained** — это подмножество, по которому вычисляется loss, где `completion_mask == 1`. trained ≠ generated: позиция completion, для которой teacher не оценил ни одного кандидата, маскируется в расчёте расхождения, но всё равно передаётся дальше.

Метрики записываются в журнал один раз за **окно логирования**: всё, что было зафиксировано с момента предыдущей записи, то есть за последние `logging_steps` шагов оптимизатора. В пределах окна:

- Среднее значение, измеряемое на каждый rollout, образец или вызов, например `rollout/duration_s` и `rollout/score_s`, усредняется по всем rollout'ам, образцам или вызовам в окне. Скорость, например `rollout/generated_tokens_per_s`, вычисляется как общее количество токенов, делённое на общее количество секунд.
- В противном случае имя, последняя часть которого содержит слово `count`, суммируется: `sample/dropped_stale_count` — это количество выбросов с момента последнего логирования, а не с начала обучения.
- Имя, последняя часть которого содержит слово `max` или `min`, например `sample/staleness_max` или `completions/max_length`, сохраняет максимальное или минимальное значение.
- Любая другая метрика представляет собой среднее значение, записанное в окне.

Единицы:

- `_s`: секунды.
- `tokens_per_s`: токены в секунду.
- `_frac`: доля от 0 до 1.
- `_per_step`: величина за один шаг оптимизатора, усреднённая по шагам в окне.

Метрики, которые [GRPOTrainer](/docs/trl/v1.18.1/ru/grpo_trainer#trl.GRPOTrainer) также записывает в журнал, сохраняют свои имена из GRPO (`completions/mean_length`, `completions/clipped_ratio`).

### Как формируются номера пакетов

**Строка** — это то, что **один** DP-ранк прогоняет через сеть в одном микро-батче: несколько сэмплов, склеенных в одну последовательность, при этом `position_ids` сбрасываются на каждой границе сэмпла. Планировщик определяет, какие сэмплы попадут в какую строку (балансируя Σ Lᵢ², чтобы ни один ранк не отставал), а коллабор данных выполняет склейку.

Во всех наших метриках **«шаг» всегда означает полный шаг оптимизатора**, а не микро-батч. `gradient_accumulation_steps` микро-батчей образуют один шаг, и каждая метрика с суффиксом `_per_step` относится к шагу оптимизатора, что соответствует `global_step`, `logging_steps` и остальной терминологии `Trainer`. Если метрика относится к микро-батчу, это прямо указано (`batch/microbatches_per_step`), либо это величина на строку (`batch/row_*`, `batch/samples_per_row`).

Следовательно, на каждом шаге используется фиксированное количество **row-slots**:

```
row-slots per step = gradient_accumulation_steps x world_size
```

что позволяет метрикам батча формировать лестницу, по которой можно сверять их между собой:

```
sample                                     sample/forwarded_tokens_mean
  └─ packed into a ROW                     batch/samples_per_row, batch/row_tokens_mean
      └─ one row per DP rank               = one micro-batch
          └─ gradient_accumulation_steps micro-batches = one STEP
                                           batch/samples_per_step, batch/forwarded_tokens_per_step
```

Таким образом, `batch/samples_per_step ≈ row-slots x batch/samples_per_row`, и аналогично для токенов. Обе стороны совпадают только с точностью до вариации между микробатчами внутри шага — метрики на шаг являются суммами, а метрики на строку — средними значениями — поэтому ожидайте расхождение в доли процента, а не точное совпадение.

`batch/row_fill_frac` — это метрика, за которой стоит следить, когда образцы длинные: образец на 10k токенов плохо укладывается в бюджет 32k (три помещаются, четыре — никогда, поэтому упаковщик часто получает два, и строка заполняется примерно на 77%), тогда как образцы на 1k токенов укладываются в него почти идеально. Это квантование, а не ошибка, и `token_budget` — это рычаг управления, с учётом того, что внимание имеет сложность O(L²) на последовательность, поэтому более полная строка из длинных последовательностей не увеличивает потребление памяти линейно.

### Очередь развёртывания

Рабочий процесс отправляет оценённые образцы в очередь, а тренер извлекает их из неё. Четыре метрики описывают эту единственную очередь и отвечают на разные вопросы:

| метрика                      | вопрос                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `rollout/queue_size`        | сколько образцов сейчас ожидают                                                                  |
| `sample/time_in_queue_s`    | как долго **один образец** находился там до того, как на нём началась тренировка, — вторая половина его «неполитичности» |
| `perf/rollout_wait_s`       | как долго обучение оставалось заблокированным, потому что очередь была **пустой**                                            |
| `rollout/backpressure_s`    | сколько времени генерация (worker) ждала, так как опережала обучение на `max_staleness` шагов           |

Последние две метрики (`perf/rollout_wait_s` и `rollout/backpressure_s`) являются зеркальными отражениями. Их совместное чтение вместе с размером очереди позволяет определить, какая сторона является узким местом:

- Очередь почти пуста, `perf/rollout_wait_s` высокий → **generation-bound**. Тренеру не хватает данных; проверьте `rollout/generated_tokens_per_s`, `rollout/concurrency` и `rollout/score_s`.
- очередь, содержащая примерно `max_staleness` шагов токенов, `rollout/backpressure_s` высокий → **ограничение со стороны тренера**. Генерация задерживается, а `sample/staleness_mean` находится вблизи своего предела.
- оба значения высокие → само ограничение `max_staleness` слишком строгое: запущенные rollout'ы заполняют его до того, как их образцы попадут в очередь, поэтому тренер ждёт, пока генерация будет приостановлена. Увеличьте `max_staleness`.
- оба близки к нулю → сбалансировано!

### Завершения

**Completion** — это то, что сервер vLLM студента сгенерировал для одного запроса.

| метрика                                             | значение                                                                                             |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `completions/mean_length`                          | сгенерированные токены за один прогон                                                                        |
| `completions/min_length`, `completions/max_length` | самое короткое и самое длинное завершение в окне                                                       |
| `completions/clipped_ratio`                        | доля завершений, которые не закончились на EOS, то есть были обрезаны по `max_completion_length`        |
| `completions/mean_terminated_length`, `completions/min_terminated_length`, `completions/max_terminated_length` | одинаковой длины, по завершённым последовательностям, которые закончились на EOS |

### Развёртывания

**Rollout** — это один промпт, пропущенный через весь процесс: сгенерированный студентом, а затем пропущенный через учителя с принудительным обучением (teacher-forcing). Поскольку вызов учителя находится на критическом пути каждого rollout (в отличие от GRPO, где оценка выполняется в отдельном цикле по завершённым группам), медленный учитель напрямую отражается на `rollout/duration_s`.

| метрика                     | значение                                                                                                                                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rollout/duration_s`       | время реального выполнения одного rollout, от диспетчеризации до оцененного образца: генерация **и** вызов учителя                                                                                                                                              |
| `rollout/score_s`          | из этого, время, которое занял вызов `/v1/completions` со стороны учителя                                                                                                                                                                                  |
| `teacher/<id>/score_s`     | Только MOPD: то же самое, но для каждого учителя отдельно. Один медленный эксперт ограничивает только те rollout-процессы, которые направляются к нему, что усреднённое значение в смешанном режиме скрывает                                                                                                                     |
| `rollout/generated_tokens_per_s`  | пропускная способность генерации за последний интервал (оконная), поэтому задержка отображается                                                                                                                                                                 |
| `rollout/concurrency`      | rollouts в процессе выполнения, то есть генерируемые или оцениваемые                                                                                                                                                                                          |
| `rollout/vllm_retry_count` | повторные запросы к vLLM, направляемые либо на сервер студента, либо на сервер учителя. В противном случае деградировавший сервер выглядит как необъяснимая медлительность. Этот раздел находится здесь, а не в `completions/`, поскольку он учитывает запросы к серверу, а не сгенерированный текст     |
| `rollout/backpressure_s`   | насколько долго генерация ждала, так как была на `max_staleness` шагов впереди. См. [очередь rollout](#the-rollout-queue)                                                                                                                           |
| `rollout/queue_size`       | образцы с оценкой, ожидающие в очереди развёртывания, измеренные в точке, где тренер извлекает их. См. [очередь развёртывания](#the-rollout-queue)                                                                                                              |

### Образцы, поступающие из очереди

Каждая выборка представляет собой один `RolloutSample`: промпт, ответ студента и разреженная оценка учителя для него. Воркер помещает их в `rollout_buffer`; всё, что описано ниже, измеряется на стороне тренера, когда он извлекает их для обучения.

| метрика                                                        | значение                                                                                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sample/forwarded_tokens_mean`, `sample/forwarded_tokens_max` | токены в одном **образце**: промпт + сгенерированный текст. Упаковка — это задача на уровне строк, см. `batch/row_*`                                                      |
| `sample/trained_tokens_mean`                                  | из них, по каким именно вычисляется функция потерь                                                                                                           |
| `sample/time_in_queue_s`                                      | сколько времени этот пример находился в этой очереди перед обучением. Не то же самое, что `perf/rollout_wait_s` — см. [очередь rollout](#the-rollout-queue) |
| `sample/staleness_mean`, `sample/staleness_max`               | насколько устарела версия политики относительно данных. `jsd` показывает _эффект_ отклонения от текущей политики на потерю; это указывает на причину                            |
| `sample/dropped_stale_count`                                  | отброшено образцов из-за превышения `max_staleness`                                                                                                     |

### Пакеты

Один микро-батч — это `world_size` строк (помните, что упаковка сворачивает всё в одну последовательность), по одному на каждый ранг DP, так что ранг _i_ выполняет прямой проход по строке _i_. `gradient_accumulation_steps` таких микро-батчей образуют один шаг оптимизатора. Таким образом, один шаг охватывает в общей сложности `gradient_accumulation_steps × world_size` строк. Каждая метрика с суффиксом `_per_step` ниже представляет собой сумму по всему шагу и по всем рангам; метрики `batch/row_*` являются _средними_ по строкам.

| метрика                                                                   | значение                                                                                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `batch/forwarded_tokens_per_step`, `batch/trained_tokens_per_step`       | токенов за один шаг оптимизатора, переданных и обученных соответственно                                                                      |
| `batch/samples_per_step`                                                 | обучающих примеров на шаг оптимизатора                                                                                                  |
| `batch/microbatches_per_step`                                            | подсчитаны, а не прочитаны из конфигурации                                                                                                     |
| `batch/masked_token_frac`                                                | токены, переданные вперёд, для которых `completion_mask == 0` — доля forward-прохода, не дающая градиента                                       |
| `batch/samples_per_row`, `batch/row_tokens_mean`, `batch/row_tokens_max` | насколько плотно планировщик заполнил строку каждого ранга                                                                                       |
| `batch/row_fill_frac`                                                    | row tokens против `token_budget`. Низкое значение означает, что бюджет не используется                                                             |
| `batch/row_imbalance`                                                    | `max Σ Lᵢ² / mean Σ Lᵢ²` по строкам. Сложность Attention составляет O(L²), поэтому это позволяет предсказать, какой ранг задерживает all-reduce градиентов. Значение 1.0 означает идеальное распределение |
| `batch/pad_frac`                                                         | межранговая отсечка. Затрачивает только байты для широковещательной передачи; удаляется перед прямой                                                     |
| `batch/dropped_oversize_count`                                           | образцы отброшены из-за превышения `token_budget`                                                                                          |

### Расхождение

То, что измеряет сама целевая функция, усреднённое по обученным токенам окна. Именно эти значения следует отслеживать для оценки процесса обучения, в отличие от показателей пропускной способности.

| метрика                          | значение                                                                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jsd`                           | обобщённая JSD, которую минимизирует функция потерь, при заданном `beta`. Снижение значения означает, что распределение ученика сходится к распределению учителя                             |
| `entropy`                       | собственная предсказательная энтропия студента. Схлопывание здесь при снижении `jsd` означает, что студент сужает распределение, а не учится                                             |
| `teacher_entropy`               | энтропия учителя по кандидатам, которые он сообщил. Значение ограничено снизу истинным значением, так как по каналу передаются только `teacher_top_k` кандидатов                             |
| `teacher/<id>/jsd`              | Только MOPD: `jsd` ограничивается токенами, оцененными учителем. Учителя в разных доменах могут расходиться с очень разной скоростью, что смешанный `jsd` усредняет  |
| `teacher/<id>/entropy`          | Только MOPD: тот же самый разбор `teacher_entropy`                                                                                                                  |
| `teacher/<id>/token_frac`       | Только MOPD: доля оценённых токенов, которые взял учитель. Косой роутинг в остальном невидим: учитель, которому не хватает строк, всё равно отчитывается о здоровом `teacher/<id>/jsd`   |
| `aux_loss` | потери балансировки нагрузки роутера MoE на микро-батч, усреднённые по рангам, записываемые в журнал, когда модель возвращает логиты роутера и `router_aux_loss_coef` не равно 0. В отличие от строк выше, это не усреднение на токен |

Не существует энтропии `entropy` для каждого отдельного учителя: энтропия ученика является свойством его собственной политики, а не того, какой учитель оценил образец, поэтому смешанная метрика уже покрывает этот случай.

### Производительность

Throughput измеряет количество токенов, которые тренер обрабатывает в секунду. **Model FLOPs Utilization (MFU)** оценивает процент теоретической вычислительной мощности устройств обучения, используемой для прямого и обратного проходов модели. Мощность, учитываемая при этой оценке, зависит от аппаратного обеспечения и точности обучения.

Throughput и MFU сообщаются на двух временных основаниях:

- **`fwd_bwd_`** измеряет производительность на этапах прямого и обратного проходов.
- **`wall_clock_`** измеряет производительность за полный шаг оптимизатора, включая обновления оптимизатора, синхронизацию весов и время, затраченное на ожидание роллаутов.

Эта разница позволяет отделить вычислительную производительность от затрат на ожидание и координацию. Оба показателя MFU описывают только **устройства обучения**: они не включают вычислительные мощности или аппаратные возможности внешних серверов rollout или teacher. Wall-clock MFU отражает время, которое тринер тратит на ожидание этих сервисов, а не их собственную загрузку.

MFU отображается только в том случае, если известна пиковая вычислительная мощность локального устройства обучения для выбранной точности, а оценка FLOPs поддерживает архитектуру модели (например, Llama, Qwen2, Qwen3, Qwen3-MoE или Qwen3-VL). В противном случае MFU не выводится; обучение продолжается, а метрики пропускной способности и времени остаются доступными.

| метрика                                                            | значение                                                                                                                                               |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `perf/step_s`                                                     | wall time между шагами оптимизатора: включает вычисления, оптимизатор, синхронизацию весов и ожидание в очереди                                                           |
| `perf/fwd_bwd_s`                                                  | forward + backward, суммированные по микробатчам шага. Это знаменатель каждого метрики `fwd_bwd_` ниже                                    |
| `perf/fwd_s`                                                      | forward-часть. `fwd_s / fwd_bwd_s` около 1/3 — это обычное соотношение; более высокое значение означает, что backward-проход дёшев или за recompute платят на forward-проходе |
| `perf/optimizer_s`                                                | `optimizer.step()`                                                                                                                                    |
| `perf/rollout_wait_s`                                             | как долго тренер находился в заблокированном состоянии из-за пустой очереди. См. [очередь rollout](#the-rollout-queue)                                             |
| `perf/weight_sync_s`                                              | полная синхронизация, плюс `_pause_s` (ожидание vLLM), `_barrier_s` (рассинхронизация рангов) и `_transfer_s` (передача байтов)                                               |
| `perf/fwd_bwd_forwarded_tokens_per_s`, `perf/wall_clock_forwarded_tokens_per_s` | токенов, переданных вперёд, в секунду на каждой основе                                                                                                             |
| `perf/wall_clock_trained_tokens_per_s`                                   | так же, но учитывающие только те токены, которые увидела функция потерь                                                                                                            |
| `perf/fwd_bwd_mfu`, `perf/wall_clock_mfu`                         | использование FLOPs модели на каждой основе                                                                                                                 |

## Философия проектирования

Этот тренажер намеренно поддерживается в минимальном виде и не предназначен для превращения в универсальное решение. Если вам требуется функция, которая не поддерживается, мы рекомендуем клонировать репозиторий и адаптировать тренажер под ваши нужды напрямую. Новые функции будут рассматриваться только при наличии значительного спроса со стороны сообщества.

## AsyncDistillationConfig[[trl.experimental.async_distillation.AsyncDistillationConfig]]

#### trl.experimental.async_distillation.AsyncDistillationConfig[[trl.experimental.async_distillation.AsyncDistillationConfig]]

```python
trl.experimental.async_distillation.AsyncDistillationConfig(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 1e-06, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool | None = None, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 1, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = True, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, dtype: str = 'float32', trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, max_completion_length: int = 2048, temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, repetition_penalty: float = 1.0, chat_template_kwargs: dict | str | None = None, vllm_server_base_url: str = 'http://localhost:8000', vllm_server_timeout: float = 1800.0, teacher_server_urls: dict[str, str] | str | None = None, beta: float = 0.0, teacher_temperature: float = 1.0, teacher_top_k: int = 8, add_tail_bucket: bool = True, token_budget: int | None = None, max_concurrent_rollouts: int = 512, max_staleness: int = 4, weight_sync_steps: int = 1, rollout_worker_timeout: float = 300.0, log_completions: bool = False, log_completions_steps: int = 100, num_completions_to_print: int | None = None)
```

[Источник](https://github.com/huggingface/trl/blob/v1.18.1/trl/experimental/async_distillation/async_distillation_config.py#L22)

**Параметры, управляющие моделью:**

model_init_kwargs (`dict[str, Any]` или `str`, *необязательный*) : Именованные аргументы для [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained), используемые при создании экземпляра модели-ученика из пути. Значение `revision` также используется при загрузке класса обработки.

dtype (`str`, *необязательный*, по умолчанию `"float32"`) : Тип данных для загрузки модели-ученика, один из `"auto"`, `"bfloat16"`, `"float16"` или `"float32"`. По умолчанию используется `"float32"`, поскольку рассогласование между обучением и инференсом, относительно которого оцениваются асинхронные тренажёры ([Defeating the Training-Inference Mismatch via FP16](https://huggingface.co/papers/2510.26788)), чувствительно к собственной точности тренажёра. Для полного устранения этого рассогласования также необходимо запускать vLLM-сервер ученика с тем же dtype (`vllm serve --dtype`). Значение `dtype` в `model_init_kwargs` имеет приоритет. Серверы-учителя не затрагиваются: они никогда не обновляются. Этот параметр задаёт только dtype, в котором загружаются веса. При использовании FSDP с смешанной точностью (по умолчанию `bf16=True`) accelerate повышает точность каждого обучаемого параметра до fp32 перед шардированием, поэтому мастер-веса и состояние оптимизатора остаются в fp32 независимо от значения `dtype`, тогда как прямой и обратный проходы выполняются в bf16 или fp16. Чекпоинты записываются в этом dtype смешанной точности, а не в fp32. Без FSDP повышение точности не происходит: `dtype="bfloat16"` при `bf16=True` сохраняет веса и состояния оптимизатора в bf16, что соответствует обучению в чистом bf16.

trust_remote_code (`bool`, *optional*, defaults to `False`) : Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) and [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

router_aux_loss_coef (`float`, *необязательный*) : Коэффициент вспомогательной функции потерь для балансировки нагрузки в моделях Mixture-of-Experts (MoE), добавляемой к функции потерь обучения с этим весом. Если значение не задано, используется значение, объявленное в конфигурации модели. Установите `0.0`, чтобы отключить. Вызывает ошибку при использовании с моделью, не являющейся MoE.

**Параметры, управляющие генерацией:**

max_completion_length (`int`, *необязательный*, по умолчанию `2048`) : Максимальное количество токенов, генерируемых на одно завершение.

temperature (`float`, *необязательный*, по умолчанию `1.0`) : Температура для выборки on-policy завершений студента.

top_p (`float`, *необязательный*, по умолчанию `1.0`) : Параметр top-p (nucleus) sampling для on-policy генерации.

top_k (`int`, *optional*, по умолчанию `0`) : Параметр top-k выборки для генерации on-policy. Значение `0` отключает top-k фильтрацию.

min_p (`float`, *optional*) : Минимальная вероятность токена, которая масштабируется вероятностью наиболее вероятного токена. Значение должно находиться в диапазоне от `0.0` до `1.0`. Типичные значения лежат в диапазоне `0.01-0.2`.

repetition_penalty (`float`, *optional*, по умолчанию `1.0`) : Число с плавающей точкой, которое штрафует новые токены в зависимости от того, встречаются ли они в промпте и в уже сгенерированном тексте. Значения > `1.0` побуждают модель использовать новые токены, а значения < `1.0` — повторять токены.

chat_template_kwargs (`dict[str, Any]`, *необязательный*) : Дополнительные именованные аргументы, передаваемые в функцию `apply_chat_template` при генерации ответов.

**Параметры, управляющие серверами vLLM:**

vllm_server_base_url (`str`, *необязательный*, по умолчанию `"http --//localhost:8000"`): базовый URL vLLM-сервера студента, используемый как для генерации, так и для потоковой передачи обновлений весов.

vllm_server_timeout (`float`, *optional*, по умолчанию `1800.0`) : Таймаут в секундах для вызовов серверов vLLM: ожидание готовности сервера студента при запуске, каждый запрос на генерацию или оценку, а также каждый вызов синхронизации весов. Ожидание сервера и вызовы синхронизации весов вызывают исключение при истечении таймаута; запрос на генерацию или оценку, для которого истёк таймаут, повторяется.

teacher_server_urls (`dict[str, str]`, *необязательный*, по умолчанию `{"default" : "http://localhost:8001"}`): сервер(ы) vLLM для учителя, каждый из которых запускается с помощью `vllm serve <teacher-model> --logprobs-mode processed_logprobs --max-logprobs -1`. Каждый учитель статичен: этот тренер никогда не транслирует обновления весов ни одному из них, поэтому учителю не нужны ни `VLLM_SERVER_DEV_MODE`, ни backend для передачи весов, только эти два флага, которые делают его оценку точной (см. `teacher_temperature` и `teacher_top_k`). Каждый учитель должен использовать тот же токенизатор, что и студент: завершения отправляются в виде сырых идентификаторов токенов, а идентификаторы, которые учитель возвращает, используются напрямую для индексации собственного словаря студента в `compute_loss`. Учитель с другим словарем обучается по неверным токенам, причем незаметно, если его словарь не больше словаря студента. Оценка представляет собой запрос с принудительным использованием учителя (teacher-forced) по собственным токенам завершения студента (`max_tokens=1`, `prompt_logprobs=teacher_top_k`, `temperature=teacher_temperature`), тот же запрос, который `get_sequence_logprobs()` отправляет для синхронных тренеров с серверным учителем. Из-за этого одноразового токена учителю требуется `--max-model-len` больше, чем у студента, иначе самые длинные завершения не смогут быть оценены. Одна запись оценивает каждый образец (обычная одно-учительская on-policy дистилляция, значение по умолчанию). Несколько записей включают MOPD (много-учительская on-policy дистилляция, см. [MOPD](https://huggingface.co/papers/2606.30406)): столбец `teacher_id` каждой строки обучения определяет, какая запись ее оценивает, например `{"math": "http://localhost:8002", "code": "http://localhost:8003"}` со значением `teacher_id` `"math"` или `"code"` для каждой строки.

**Параметры, управляющие потерей дистилляции:**

beta (`float`, *optional*, по умолчанию `0.0`) : Коэффициент интерполяции для обобщённого расхождения Дженсена–Шеннона. Значение `0.0` соответствует прямому KL (mean-seeking), `1.0` — обратному KL (mode-seeking), а промежуточные значения обеспечивают интерполяцию согласно той же формулировке обобщённого JSD, которую внутренне вычисляет [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer). Множество, на котором вычисляется расхождение, зависит от режима и повторяет логику `ServerDistillationTrainer`: при `beta=0.0` используется полное множество из `teacher_top_k` токенов, переданных учителем (плюс хвостовая корзина), поскольку веса прямого KL как раз и обеспечиваются этим множеством. При `beta != 0.0` множество сужается до двух кандидатов — топ-1 токена учителя и фактического токена завершения — поскольку именно для этих двух токенов протокол гарантирует наличие лог-вероятности от учителя без передачи более широкого (или полного) словаря; любое более широкое множество было бы лишь вероятностным приближением покрытия вероятных токенов студента, а не гарантией.

teacher_temperature (`float`, *необязательный*, по умолчанию `1.0`) : Температура softmax для расхождения, применяемая к *обеим* сторонам: передается учителю, чтобы vLLM вычислял свои logprobs при этой температуре на стороне сервера (точно, а не путем масштабирования на стороне клиента), и применяется к собственным logits ученика в `compute_loss`, повторяя единственную `temperature` в `ServerDistillationTrainer`. Не связана с `temperature`, которая управляет только тем, как ученик генерирует свои завершения. Сервер учителя должен запускаться с `--logprobs-mode processed_logprobs`, чтобы это значение вообще влияло на возвращаемые им logprobs; без этого флаг учитель молча возвращает необработанные logprobs, и настройка затрагивает только сторону ученика.

teacher_top_k (`int`, *optional*, по умолчанию `8`) : Количество токенов-кандидатов на каждую позицию, запрашиваемых у teacher через `prompt_logprobs`. Для приближения распределения teacher используются только эти кандидаты (плюс реализованный токен, который vLLM всегда сообщает, даже если он не входит в top-k, плюс хвостовой бакет, учитывающий оставшуюся вероятность, см. `add_tail_bucket`); полная лексика никогда не передаётся по HTTP. Сторона student в расчёте дивергенции является точной (вычисляется локально, без приближения), поскольку student — это обучаемая модель, и её полные логиты уже доступны в `compute_loss`. Значение `8` — это лёгкий дефолт для smoke-тестов; в production-настройках on-policy-distillation в смежных RL-фреймворках используется разреженная поддержка teacher примерно в том же диапазоне (в miles по умолчанию `16`, в EasyOPD — `64`), поэтому при реальном обучении разумно увеличить это значение до `16`–`64`. Любое значение выше `20` требует, чтобы сервер teacher был запущен с флагом `--max-logprobs -1`, который снимает дефолтный лимит vLLM на количество logprob на токен.

add_tail_bucket (`bool`, *необязательный*, по умолчанию `True`) : Нужно ли добавлять хвостовое значение, представляющее оставшуюся вероятность за пределами `teacher_top_k`, чтобы избежать тривиально малой дивергенции, когда `teacher_top_k` мало.

token_budget (`int`, *optional*) : Максимальное количество реальных токенов, упакованных в одну строку (один проход вперед для одного ранга DP). `TokenBudgetBatcher` формирует микробатчи, сбалансированные по Σ Lᵢ², строки которых укладываются в этот бюджет, ограничивая пиковое потребление памяти независимо от количества образцов (число образцов на строку становится динамическим). Если `None` (по умолчанию), значение устанавливается равным `max_model_len` сервера vLLM для student (запрашивается при начале обучения) — это верхний предел длины промпта + завершения, поэтому ни один образец rollout не может превысить бюджет. Образец длиннее `token_budget` не помещается ни в одну строку и отбрасывается с предупреждением, учитывается как `batch/dropped_oversize_count`.

**Параметры, управляющие асинхронным конвейером развёртывания:**

max_concurrent_rollouts (`int`, *optional*, по умолчанию `512`) : Максимальное количество rollout-ов, одновременно находящихся в работе на vLLM-серверах студента и учителя, в процессе генерации или оценки.

max_staleness (`int`, *optional*, по умолчанию `4`) : Максимальное количество шагов обновления весов, на которые образец rollout может отставать от текущей версии модели, прежде чем будет отброшен. Генерация ограничена этим значением: rollout запускается только в том случае, если количество токенов в очереди и в процессе обработки укладывается в объём, который trainer потребляет за `max(max_staleness, 1)` шагов.

weight_sync_steps (`int`, *необязательный*, по умолчанию `1`) : Количество шагов обучения между синхронизациями весов с vLLM-сервером студента.

rollout_worker_timeout (`float`, *optional*, по умолчанию `300.0`) : Количество секунд с последнего сигнала о жизни (heartbeat) от rollout-воркера, после которых тренер считает его зависшим и прерывает выполнение.

**Параметры, управляющие ведением журнала:**

log_completions (`bool`, *необязательный*, по умолчанию `False`) : Флаг, определяющий, следует ли логировать выборку пар (prompt, completion) каждые `log_completions_steps` оцененных образцов.

log_completions_steps (`int`, *optional*, по умолчанию `100`) : Количество оценённых образцов между записями завершений в журнал. Используется только если `log_completions` равно `True`. Считается в образцах, оценённых рабочим процессом rollout, а не в шагах оптимизатора: рабочий процесс выполняется в отдельном процессе от тренера и не имеет доступа к `self.state.global_step`.

num_completions_to_print (`int`, *optional*) : Количество завершений, которые выводить с помощью `rich`. Если `None`, в журнал записываются все завершения.

Класс конфигурации для [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.1/ru/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer).

Этот класс содержит только параметры, специфичные для асинхронной on-policy дистилляции. Полный список аргументов обучения см. в документации [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments). Обратите внимание, что значения по умолчанию в этом классе могут отличаться от значений в [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments). Его структура повторяет [AsyncGRPOConfig](/docs/trl/v1.18.1/ru/async_grpo_trainer#trl.AsyncGRPOConfig) (асинхронный конвейер, сервер vLLM, поля для логирования совпадают), при этом поля clipping/group из GRPO заменены полями потерь teacher-distillation, описанными ниже.

> [!NOTE]
> Эти параметры имеют значения по умолчанию, отличные от [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: По умолчанию `1`, а не `500`. - `gradient_checkpointing`: По умолчанию `True`, а не `False`. - `bf16`: По умолчанию `True`, если не задан `fp16`, а не `False`. - `learning_rate`: По умолчанию `1e-6`, а не `5e-5`. - `ignore_data_skip`: По умолчанию `True`, а не `False`; цикл пропуска и повторного воспроизведения базового Trainer не применяется к асинхронной очереди rollout.

## AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

#### trl.experimental.async_distillation.AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

```python
trl.experimental.async_distillation.AsyncDistillationTrainer(model: str | PreTrainedModel, args: trl.experimental.async_distillation.async_distillation_config.AsyncDistillationConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None), peft_config: PeftConfig | None = None)
```

[Источник](https://github.com/huggingface/trl/blob/v1.18.1/trl/experimental/async_distillation/async_distillation_trainer.py#L1059)

**Параметры:**

model (`str` или [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) : Модель-студент, подлежащая обучению. Может быть:  - строкой, являющейся *model id* предобученной модели, размещенной в репозитории моделей на huggingface.co, или путем к *каталогу*, содержащему веса модели, сохраненные с помощью [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained). Загружается с помощью [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained). - объектом [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). Его реализация внимания переключается на бэкенд FlashAttention тренера для обучения без padding.  Имя модели из конфигурации используется для идентификации модели-студента на ее сервере vLLM.

args ([experimental.async_distillation.AsyncDistillationConfig](/docs/trl/v1.18.1/ru/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig), *необязательный*) : Конфигурация для этого тренера. Если `None`, используется конфигурация по умолчанию.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) или [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)) : Набор данных для обучения. Должен включать столбец `"prompt"` (формат [conversational](dataset_formats#conversational)). Любые дополнительные столбцы игнорируются.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), *optional*) : Класс обработки, используемый для обработки данных. Если `None`, он загружается по имени модели с помощью [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained). Если у него нет токена отбивки, используется `tokenizer.eos_token`.

callbacks (список [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *необязательный*) : Список колбэков для настройки цикла обучения, добавляемых к стандартным колбэкам (см. [здесь](https://huggingface.co/docs/transformers/main_classes/callback)).

optimizers (`tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]`, *необязательный*, по умолчанию `(None, None)`) : Кортеж, содержащий оптимизатор и планировщик, которые следует использовать. По умолчанию используются `AdamW` и линейное расписание, управляемое параметром `args`.

peft_config (`PeftConfig`, *необязательный*) : конфигурация PEFT, используемая для обёртки модели. Если `None`, модель не оборачивается. Если сервер vLLM ученика был запущен с `--enable-lora`, адаптер LoRA синхронизируется с ним как адаптер, а не как объединённые веса; см. раздел LoRA в документации AsyncDistillation.

Асинхронный аналог [DistillationTrainer](/docs/trl/v1.18.1/ru/distillation_trainer#trl.DistillationTrainer), спроектированный по образцу [AsyncGRPOTrainer](/docs/trl/v1.18.1/ru/async_grpo_trainer#trl.AsyncGRPOTrainer): фоновый worker генерации rollout'ов формирует on-policy завершения студента и оценивает их по отношению к серверу учителя, пока обучение продолжается параллельно, отделяя процесс генерации от цикла обновления градиентов. Если в GRPO обрезанная функция потерь policy-gradient использует групповое относительное преимущество, то `compute_loss` данного тренера читает разреженное распределение учителя по позициям и минимизирует обобщенную JSD относительно него (см. `AsyncDistillationConfig.beta`), всегда в on-policy режиме: студент генерирует каждое завершение, на котором обучается.

В отличие от синхронного `DistillationTrainer`, этот тренер поддерживает только оценку по учителю, работающему через HTTP (внешний сервер vLLM). Локальный (внутрипроцессный, на GPU) прямой проход учителя не может выполняться в дочернем процессе, запущенном воркером rollout с отключенным CUDA, так же, как функции вознаграждения в GRPO, и вместо этого должен выполняться в основном процессе обучения; этот путь пока не реализован.

Пример:

```python
>>> from trl.experimental.async_distillation import AsyncDistillationTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

>>> trainer = AsyncDistillationTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     train_dataset=dataset,
... )
>>> trainer.train()
```

