TRL documentation

Асинхронный GRPO Trainer

You are viewing v1.18.1 version. A newer version v1.18.2 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Асинхронный GRPO Trainer

model badge

Обзор

AsyncGRPOTrainer реализует тот же алгоритм GRPO, но разделяет генерацию rollout и обучение. Фоновый процесс непрерывно получает завершения от сервера vLLM, пока цикл обучения их потребляет, благодаря чему генерация и обновление градиентов выполняются параллельно, а не поочерёдно.

Этот тренажёр был предложен Amine Dirhoussi и Quentin Gallouédec.

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

В этом примере показано, как обучать модель с использованием метода Asynchronous GRPO. Мы обучаем модель Qwen3.5 2B на промптах из набора данных DeepMath-103K. Данные из набора можно посмотреть здесь:

Ниже приведён скрипт для обучения модели. Тренеру требуются vLLM и kernels, а accuracy_reward — math-verify, которые можно установить с помощью pip install trl[vllm,kernels,math_verify].

# train_async_grpo.py
from datasets import load_dataset
from trl import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

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 = AsyncGRPOTrainer(
        model="Qwen/Qwen3.5-2B",
        reward_funcs=accuracy_reward,
        train_dataset=dataset,
    )
    trainer.train()

Генерация выполняется на сервере vLLM, на других GPU, чем у тренера. Запустите его на GPU 0:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3.5-2B \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096

Затем выполните скрипт на GPU 1 с помощью следующей команды:

CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py

Совместимость и ограничения

Некоторые комбинации аргументов намеренно ограничены в текущей реализации AsyncGRPOTrainer:

  • Генерация всегда выполняется на отдельном сервере vLLM, запускаемом с помощью vllm serve. Режим совместного размещения (colocate) отсутствует.
  • Промпты из набора данных должны быть в диалоговом формате. При использовании environment_factory в наборе данных может отсутствовать столбец prompt, а reset() предоставляет его.
  • Функции вознаграждения должны быть вызываемыми объектами Python. Модели вознаграждения, переданные в виде идентификатора модели или объекта PreTrainedModel, не поддерживаются, см. Использование пользовательской функции вознаграждения.
  • Для работы тренера требуется transformers>=5.2.0.
  • Sharded training использует FSDP2. DeepSpeed не поддерживается, равно как и параллелизм контекста и последовательности (cp_size > 1 или sp_size > 1 в parallelism_config).
  • use_liger_kernel=True не поддерживается.
  • PEFT-адаптеры, нацеленные на lm_head, не поддерживаются.
  • Модели с attention sinks не поддерживаются. Единственные поддерживаемые слои, не относящиеся к attention, — это слои gated DeltaNet в гибридных моделях (Qwen3.5, Qwen3.6, Qwen3-Next, …), для которых требуется transformers>=5.15.0.
  • Изображения не поддерживаются, см. Обучение моделей зрения и языка.

При обучении ядро внимания загружается с Hub через библиотеку kernels: kernels-community/aiter-flash-attn для GPU AMD (ROCm), kernels-community/flash-attn4 для GPU NVIDIA Blackwell и kernels-community/flash-attn3 для остальных GPU NVIDIA. Модели, ограничивающие значения логитов внимания (attn_logit_softcapping), например Gemma 2, не поддерживаются на GPU AMD и на GPU NVIDIA Blackwell.

Более подробный обзор метода Asynchronous GRPO

В GRPOTrainer генерация и обучение выполняются последовательно: сгенерировать батч, вычислить потерю, обновить веса, повторить. Даже в colocate mode один этап должен завершиться, прежде чем начнётся другой. В AsyncGRPOTrainer рабочий процесс rollout генерирует и оценивает завершения в фоновом процессе, пока цикл обучения вычисляет потерю и обновляет модель. Чтобы понять, как это работает, процесс можно разбить на три основных шага: генерация завершений, вычисление преимущества и вычисление потери. Модель-референс отсутствует, поэтому нет слагаемого KL-расстояния (по умолчанию в GRPO beta=0.0).

Генерация завершений

Рабочий процесс rollout поддерживает в работе до max_concurrent_rollouts запросов к серверу vLLM. Для каждого промпта он генерирует группу из G G дополнений (num_generations) и, когда вся группа готова, оценивает её и вычисляет преимущества. Полученные обучающие примеры попадают в очередь, из которой их забирает цикл обучения. Генерация ждёт только тогда, когда она опережает обучение на max_staleness шагов (см. Параллелизм), ), а шаг обучения ждёт только тогда, когда очередь пуста.

Каждые weight_sync_steps шагов обучения тренер отправляет обновлённые веса на сервер vLLM по NCCL, чтобы следующие завершения генерации формировались на основе последней политики. В связи с этим завершение может быть получено от политики, на несколько шагов более старой, чем та, что сейчас обучается: образец, отстающий более чем на max_staleness обновлений весов в момент, когда тренер его извлекает, отбрасывается.

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

  • a группа — это один промпт и его G G роллауты. Преимущество вычисляется внутри неё.
  • rollout — это один полный диалог, сгенерированный для промпта, включая все вызовы инструментов. Он состоит из одного или нескольких turns, каждый из которых соответствует одному запросу vLLM.
  • sample — это то, на чём вычисляется loss: токены rollout с их advantage. Мульти-турный rollout может порождать более одного sample (см. Multi-turn rollouts).
  • Строка — это то, что один процесс передаёт в одном микробатче: несколько образцов, упакованных вместе (см. Упаковка деревьев). Микробатч содержит по одной строке на процесс, а gradient_accumulation_steps микробатчей образуют один шаг — шаг оптимизатора.

Существует три вида количества токенов: сгенерированные токены — это те, которые произвела модель, переданные токены — это все токены образца (включая промпт и результаты инструментов), а обучающие токены — это те, по которым вычисляется функция потерь.

Вычисление преимущества

Для каждого из G G дополнений в группе награда представляет собой сумму наград от каждой функции вознаграждения. Преимущество нормализуется внутри группы, как в GRPO: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

Опция scale_rewards отсутствует: преимущество всегда масштабируется стандартным отклонением группы. Завершение, для которого все функции вознаграждения вернули None, исключается из среднего и стандартного отклонения группы и получает нулевое преимущество.

Группа, в которой все вознаграждения равны, отбрасывается: при стандартном преимуществе оно равно нулю во всех точках, поэтому обучение на такой группе потребовало бы прямого и обратного прохода, не изменив ничего. Доля таких групп логируется как frac_zero_std_groups. Шаг заполняется из оставшихся групп, поэтому большое количество отброшенных групп означает больше генераций на один шаг. Отброшенная группа всё равно учитывается в эпохе, которая остаётся одним проходом по промптам.

Вычисление функции потерь

Лог-вероятности сервера vLLM никогда не совпадают с лог-вероятностями тренера точно: разные ядра, другая точность и политика, отстающая на несколько шагов (см. Работа с рассогласованием между обучением и инференсом). Тренер использует лог-вероятности сэмплера как старую политику, поэтому одно отношение важности покрывает и рассогласование, и устаревание: ri,t(θ)=πθ(oi,t∣q,oi,<t)πsampler(oi,t∣q,oi,<t). r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\text{sampler}}(o_{i,t} \mid q, o_{i,< t})}.

Токены, у которых отношение выходит за пределы [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max], исключаются из функции потерь. Подробнее см. Masked Importance Sampling.

По умолчанию (score_centering=True), тренажёр использует Score Centering. Веса важности сами по себе не устраняют рассогласование: оценка ∇θlog⁡πθ \nabla_\theta \log \pi_\theta выбранного токена в среднем не равна нулю при выборке из μ \mu , поэтому каждое обновление также тянет политику к сэмплеру. Score centering вычитает это математическое ожидание на каждой позиции: ∇θL=−Eo∼μ[A^(f(rt)∇θlog⁡πθ(ot)−Ev∼μ[f(rv)∇θlog⁡πθ(v)])],rv=πθ(v)μ(v), \nabla_\theta \mathcal{L} = - \mathbb{E}_{o \sim \mu} \left[ \hat{A} \left( f(r_t) \nabla_\theta \log \pi_\theta(o_t) - \mathbb{E}_{v \sim \mu} \left[ f(r_v) \nabla_\theta \log \pi_\theta(v) \right] \right) \right], \quad r_v = \frac{\pi_\theta(v)}{\mu(v)},

где f(r)=r f(r) = r внутри [Cmin⁡,Cmax⁡] [C_{\min}, C_{\max}] и 0 0 снаружи. Внутреннее математическое ожидание берётся по num_sampler_logprobs самым вероятным токенам на каждой позиции, которые worker rollout запрашивает у сервера.

При score_centering=False, тренажёр использует обрезанную суррогатную целевую функцию GRPO вместо этого, с тем же маскированным отношением: L(θ)=−1∑i∣oi∣∑i∑t=1∣oi∣1[Cmin⁡≤ri,t(θ)≤Cmax⁡]min⁡(ri,t(θ)A^i,t, clip(ri,t(θ),1−ϵlow,1+ϵhigh)A^i,t), \mathcal{L}(\theta) = - \frac{1}{\sum_{i} |o_i|} \sum_{i} \sum_{t=1}^{|o_i|} \mathbb{1}\left[ C_{\min} \le r_{i,t}(\theta) \le C_{\max} \right] \min \left( r_{i,t}(\theta) \hat{A}_{i,t}, \, \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_{\text{low}}, 1 + \epsilon_{\text{high}} \right) \hat{A}_{i,t} \right),

где ϵlow \epsilon_{\text{low}} это epsilon а ϵhigh \epsilon_{\text{high}} это epsilon_high.

В обоих случаях функция потерь нормализуется на количество обученных токенов в микропачке, подсчитанное по всем процессам, и усредняется по gradient_accumulation_steps микропачкам одного шага.

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

Во время обучения мы фиксируем следующие метрики:

  • num_tokens: общее количество токенов, переданных на данный момент, включая промпты и завершения. При tree packing префикс, общий для нескольких образцов, учитывается один раз.
  • completions/mean_length: средняя длина сгенерированных завершений. При использовании инструментов учитываются только токены, не относящиеся к инструментам.
  • completions/min_length: минимальная длина генерируемых завершений. При использовании инструментов учитываются только токены, не относящиеся к инструментам.
  • completions/max_length: максимальная длина генерируемых дополнений. При использовании инструментов учитываются только токены, не относящиеся к инструментам.
  • completions/mean_terminated_length: средняя длина сгенерированных завершений, которые заканчиваются токеном EOS. При использовании инструментов учитываются только нетуловые токены.
  • completions/min_terminated_length: минимальная длина сгенерированных завершений, которые заканчиваются токеном EOS. При использовании инструментов учитываются только токены, не относящиеся к инструментам.
  • completions/max_terminated_length: максимальная длина сгенерированных завершений, которые заканчиваются токеном EOS. При использовании инструментов учитываются только токены, не относящиеся к инструментам.
  • completions/clipped_ratio: Доля усечённых (обрезанных) завершений, последний ход которых не заканчивается токеном EOS.
  • completions/duplicate_frac: доля роллов, которые повторяют предыдущий ролл своей группы посимвольно. См. Насыщение и дубликаты.
  • tools/call_frequency: среднее количество вызовов инструментов на завершение по всем развёрткам, включая группы, которые затем отбрасываются. Записывается в журнал только в том случае, если у тренера есть инструменты.
  • tools/failure_frequency: Доля неудачных вызовов инструментов (инструмент не найден или возникло исключение) от общего числа всех вызовов инструментов, включая группы, которые затем отбрасываются. В окне логирования без вызовов инструментов значение равно NaN, при этом GRPO записывает 0.0. Записывается только если у тренера есть инструменты.
  • rewards/{reward_func_name}/mean: среднее значение награды от конкретной функции вознаграждения по всем оценённым ею завершениям, включая группы, которые затем отбрасываются. Если среда управляет наградой через get_reward, то {reward_func_name} — это имя класса среды.
  • rewards/{reward_func_name}/group_std: стандартное отклонение вознаграждения от конкретной функции вознаграждения, вычисленное внутри каждой группы и усреднённое по обученным образцам.
  • reward: Общая средняя награда после суммирования наград по всем функциям для всех оценённых завершений, включая группы, которые затем отбрасываются. Это награда политики, поэтому именно её следует отслеживать: reward_trained исключает группы, в которых все награды равны.
  • reward_group_std: стандартное отклонение суммарных наград по функциям, вычисленное внутри каждой группы и усреднённое по обученным образцам. Именно на него делится преимущество, в отличие от reward_std в GRPO, которое берётся по всей выборке.
  • reward_trained: средняя награда для образцов, на которых обучался тренер. В неё не входят группы, у которых все награды равны, а также образцы, отброшенные из-за превышения max_staleness.
  • reward_zero_std_groups: средняя награда групп, награды в которых все равны и которые отбрасываются: награда, на которой они застряли. См. Насыщение и дубликаты, чтобы прочитать её вместе с frac_zero_std_groups и reward.
  • frac_zero_std_groups: доля групп, у которых стандартное отклонение вознаграждения равно нулю (все ответы верные или неверные), либо в которых меньше двух оцениваемых завершений. Эти группы отбрасываются.
  • sampling/sampling_logp_difference/mean: средняя абсолютная разница между лог-вероятностями, возвращаемыми сэмплером (vLLM), и пересчитанными моделью обучения, по обученным токенам.
  • sampling/sampling_logp_difference/max: наибольшее такое абсолютное значение.
  • sampling/importance_sampling_ratio/min: Минимальное отношение важности выборки ri,t(θ) r_{i,t}(\theta) между моделью и генератором, по обученным токенам, до удаления токенов вне диапазона [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] .
  • sampling/importance_sampling_ratio/mean: Среднее значение такого отношения важности выборки.
  • sampling/importance_sampling_ratio/max: максимальное значение такого отношения важности выборки.
  • sampling/masked_mean: доля обученных токенов, исключённых из функции потерь, поскольку их коэффициент важностного сэмплирования выходит за пределы [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max].
  • sampling/sampler_mass: средняя вероятность, которую покрывают num_sampler_logprobs наиболее вероятных токенов сэмплера. Записывается только при score_centering=True.
  • entropy: Средняя энтропия предсказаний токенов по обученным токенам.
  • aux_loss: вспомогательная функция потерь для балансировки нагрузки в модели Mixture-of-Experts, до её масштабирования коэффициентом router_aux_loss_coef и добавления к общей функции потерь. Записывается в журнал только в том случае, если модель является MoE и router_aux_loss_coef не равен нулю.
  • clip_ratio/region_mean: Соотношение вероятностей токенов, для которых цель GRPO обрезается, чтобы оставаться в области доверия: clip(ri,t(θ),1−ϵlow,1+ϵhigh) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) . При score_centering=True потери не обрезаются, поэтому метрики clip_ratio/* считают токены вне области доверия.
  • clip_ratio/low_mean: Среднее отношение вероятностей токенов, которые были обрезаны по нижней границе области доверия: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: Минимальная доля токенов, обрезанных по нижней границе области доверия, для каждого завершения: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: Среднее отношение вероятностей токенов, обрезанных по верхней границе области доверия: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: Максимальная доля токенов, обрезанных по верхней границе области доверия, для каждого завершения: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.

Остальные метрики описывают асинхронный конвейер.

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

  • Среднее значение, измеряемое на каждый rollout, образец или вызов, например reward, rollout/turns_mean и tools/latency_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: величина за один шаг оптимизатора, усреднённая по шагам в окне.

Метрики развёртывания

  • rollout/duration_s: Фактическое время одного rollout, от момента отправки до сбора результата в цикле rollout.
  • rollout/generated_tokens_per_s: Пропускная способность генерации, выраженная в количестве сгенерированных токенов в секунду, с момента предыдущего отчёта.
  • rollout/concurrency: количество одновременно выполняемых rollout-процессов на сервере vLLM.
  • rollout/concurrency_cap: текущий лимит на количество выполняемых параллельно rollout-ов, который зависит от нагрузки на сервер. См. Параллелизм.
  • rollout/turns_mean, rollout/turns_max: среднее и максимальное количество ходов на один rollout.
  • rollout/samples_per_rollout: количество обучающих выборок на один rollout. Значения выше 1.0 означают, что некоторые rollout были разветвлены; значения ниже 1.0 — что некоторые не дали ни одного обученного токена. См. Многораундовые rollout.
  • rollout/fork_frac: доля переходов между ходами, в которых промпт не начинается с удерживаемых токенов, то есть ход начал новый образец.
  • rollout/drift_tokens_mean, rollout/drift_tokens_max: количество удержанных токенов, которые форк перерисовал, усреднённое по переходам между ходами (переход без форка учитывается как 0). Новая выборка разделяет токены до точки расхождения, поэтому это то, что каждый форк добавляет к прямому проходу.
  • rollout/score_queue_size: количество завершённых групп, ожидающих оценки.
  • rollout/queue_size: количество оценённых образцов, ожидающих в очереди rollout, измеряется в точке, где тренер их извлекает. См. Очередь rollout.
  • rollout/score_s: время оценки группы.
  • rollout/score_wait_s: время, в течение которого завершённая группа ожидала перед оценкой.
  • rollout/score_block_s: время, в течение которого генерация блокировалась из-за переполнения очереди оценки.
  • rollout/backpressure_s: время, в течение которого генерация ждала начала rollout, так как опережала обучение на max_staleness шагов, усреднённое по всем ожиданиям в окне логирования. См. Конкурентность.
  • rollout/vllm_retry_count: количество повторных запросов к vLLM. Без этого деградация сервера выглядит как необъяснимая медленная работа.
  • rollout/vllm_kv_cache_usage_frac: Использование кэша KV в vLLM (максимальное значение по всем движкам), усреднённое по опросам в окне логирования.
  • rollout/vllm_running_requests: количество запросов, которые движки сервера декодируют (сумма num_requests_running vLLM по всем движкам). Разница с rollout/concurrency — это то, что находится в процессе API-сервера и формирует ответы.
  • rollout/vllm_queued_requests: количество запросов, которые сервер принял, но ещё не запланировал (сумма num_requests_waiting по всем движкам vLLM).
  • rollout/vllm_preemption_count: количество запросов, которые сервер прервал (сумма num_preemptions_total по всем движкам vLLM). Синхронизация весов сбрасывает кэши сервера, что приводит к прерыванию всех выполняющихся запросов, поэтому этот показатель не является индикатором нагрузки.

Метрики инструмента

  • tools/latency_s, tools/{tool_name}/latency_s: время, затраченное на выполнение вызова инструмента, по всем инструментам и по каждому инструменту.
  • tools/{tool_name}/call_count, tools/{tool_name}/failure_count: количество вызовов и неудачных вызовов для каждого инструмента.
  • tools/unknown_name_count: количество вызовов инструмента, который не существует. В отличие от инструмента, который был выполнен и вызвал исключение, это ошибка политики.
  • tools/parallel_calls_mean: среднее количество вызовов инструментов в сообщении ассистента, в котором используются инструменты.
  • tools/loop_exhausted_frac: доля роллов, прерванных на max_tool_calling_iterations при активном вызове инструментов, от общего числа роллов, включая роллы без вызовов и группы, которые затем отбрасываются. Записывается в лог только если у тренера есть инструменты.

HarnessAsyncGRPOTrainer записывает большинство из них под теми же именами. См. Обучение на harnesses для различий.

Метрики среды

  • env/reset_s: время, затраченное на reset() среды перед началом rollout. Записывается только при наличии environment_factory.
  • env/reward_s: время, затраченное на выполнение get_reward() среды после завершения rollout. Записывается в лог только в том случае, если среда определяет get_reward.

Примеры метрик

  • sample/forwarded_tokens_mean, sample/forwarded_tokens_max: среднее и максимальное количество пересланных токенов на образец.
  • sample/trained_tokens_mean: среднее количество обученных токенов на образец.
  • sample/time_in_queue_s: время, которое образец провёл в очереди rollout перед обучением.
  • sample/staleness_mean, sample/staleness_max: количество обновлений весов между политикой, сгенерировавшей образец, и политикой, на которой он обучается. Метрики sampling/importance_sampling_ratio/* и sampling/sampling_logp_difference/* объединяют эту устареванность с рассогласованием между обучением и инференсом: если при нулевой устареванности коэффициент отличается от 1.0 или разница лог-вероятностей отличается от 0.0, это указывает на рассогласование, например, на различие в типе данных (dtype) с сервером.
  • sample/dropped_stale_count: количество выбросов, отброшенных из-за превышения max_staleness.

Метрики батча

  • batch/forwarded_tokens_per_step, batch/trained_tokens_per_step: количество токенов, переданных и использованных для обучения на каждом шаге, по всем процессам.
  • batch/samples_per_step, batch/groups_per_step: количество образцов и различных групп на каждом шаге. Они различаются на величину, равную числу образцов в группе.
  • batch/microbatches_per_step: количество микробатчей на шаг.
  • batch/masked_token_frac: Доля переданных токенов, которые не участвуют в обучении.
  • batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max: количество образцов в строке, а также среднее и максимальное число токенов, переданных вперёд, в строке.
  • batch/row_fill_frac: доля token_budget, которую занимают строки.
  • batch/row_imbalance: отношение стоимости внимания самой дорогой строки к средней. Процесс с самой дорогой строкой блокирует остальные на этапе all-reduce градиентов; 1.0 означает идеальную сбалансированность.
  • batch/packing_ratio: количество токенов до упаковки на каждый переданный токен: коэффициент, на который упаковка сокращает прямой проход, 1.0, если ничего не разделяется.
  • batch/pad_frac: Доля добавляемого padding для выравнивания длины строк. Это влияет только на передачу данных, так как padding удаляется перед forward.
  • batch/dropped_oversize_count: количество выбросов, отброшенных из-за превышения token_budget.

Метрики производительности

  • perf/step_s: Фактическое время выполнения шага, включая оптимизатор, синхронизацию весов и время ожидания образцов.
  • perf/fwd_bwd_s, perf/fwd_s: время, затраченное на прямой и обратный проходы шага, и только на прямые проходы.
  • perf/optimizer_s: время, затраченное на шаг оптимизатора.
  • perf/rollout_wait_s: время, в течение которого обучение ожидало, потому что очередь rollout была пуста. См. Очередь rollout.
  • perf/weight_sync_s: время синхронизации весов, разбитое на perf/weight_sync_pause_s (ожидание паузы vLLM), perf/weight_sync_barrier_s (ожидание других процессов) и perf/weight_sync_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 модели на устройствах обучения, рассчитанный по проходам вперёд и назад или за весь шаг. В них не учитывается сервер vLLM. Записываются только в том случае, если известна пиковая производительность устройства обучения на точности обучения и если оценка FLOPs поддерживает архитектуру модели (например, Llama, Qwen2, Qwen3, Qwen3-MoE или Qwen3-VL).

Настройка

Настройка сервера vLLM

Тренер генерирует с помощью сервера vLLM, к которому обращается по адресу vllm_server_base_url (по умолчанию http://localhost:8000):

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096
  • VLLM_SERVER_DEV_MODE=1 и --weight-transfer-config открывают конечные точки, через которые тренер отправляет свои веса.
  • --logprobs-mode processed_logprobs заставляет сервер возвращать лог-вероятности распределения, из которого выполнялась выборка, после применения temperature и top-k/top-p, с которыми сравнивается отношение важности.
  • --api-server-count 8 сохраняет верхние log-probabilities, что позволяет обрабатывать запросы на центрирование оценок с минимальными затратами (см. предупреждение ниже).
  • --max-model-len — это максимальная общая длина последовательности (запроса и завершения), которую вы ожидаете. Меньшее значение снижает потребление памяти GPU на сервере, высвобождая больше памяти для KV-кэша и увеличивая пропускную способность. Хорошей отправной точкой является длина запроса плюс max_completion_length из вашей конфигурации. При использовании инструментов каждый ход добавляет до max_completion_length токенов плюс результаты инструментов, поэтому установите значение, соответствующее самому длинному ожидаемому диалогу. Если длина запроса хода плюс max_completion_length превышает --max-model-len, сервер отклоняет запрос, и выполнение останавливается с ошибкой сервера. При использовании top_k или top_p сервер вместо этого останавливает этот ход, когда достигает --max-model-len, и отклоняет только тот запрос, который уже имеет такую длину. Это также значение по умолчанию для token_budget.

Убедитесь, что сервер использует другие GPU, чем тренажёр, иначе могут возникнуть ошибки NCCL. Вы можете указать используемые GPU с помощью переменной окружения CUDA_VISIBLE_DEVICES.

Сериализация верхних log-probabilities выполняется на CPU в API-сервере vLLM, и при значении по умолчанию для одного API-сервера num_sampler_logprobs=8 пропускная способность генерации снижается вдвое. Запустите сервер с флагом --api-server-count 8 в vLLM 0.32 или более поздней версии: при тестировании на одном H100 с моделями от 1,5 до 7B стоимость верхних 8 log-probabilities составляет менее 3% пропускной способности генерации. В vLLM 0.31 тот же флаг всё ещё приводит к потере 20–40%, что исправлено в vllm-project/vllm#58181.

Параллелизм

Три ограничения определяют, сколько роллаутов выполняется одновременно. Первые два адаптируются автоматически; третье вы задаёте сами.

Устаревание. max_staleness задаёт, на сколько шагов обучения генерация может опережать тренажёр. Рабочий процесс отслеживает это в токенах, поскольку количество образцов в шаге меняется по мере того, как дополнения становятся длиннее или короче. После каждого шага тренажёр подсчитывает использованные им токены и позволяет рабочему процессу удерживать в очереди или в работе не более max(max_staleness, 1) раз этого количества токенов. До первого шага предполагается, что каждая строка заполнена полностью. Рабочий процесс начинает новую группу роллаутов только при условии, что он находится ниже этого лимита. В самом начале он ещё не знает, сколько токенов производит роллаут, поэтому начинает по одной группе за раз, пока не завершится первая группа. Образец, который всё же оказывается старше max_staleness шагов, отбрасывается.

Загрузка vLLM. Если отправлять в vLLM слишком много запросов одновременно, он начинает работать медленнее: кэш KV заполняется, и vLLM вынужден приостанавливать работу и повторять некоторые запросы. Поэтому воркер также поддерживает динамический лимит на количество одновременно выполняемых роллаутов, который логируется как rollout/concurrency_cap, и каждые 5 секунд проверяет /metrics сервера, чтобы корректировать этот лимит. Начальное значение лимита равно количеству запросов, которые помещаются в кэш KV при максимальной длине (KV cache tokens / max_model_len), чтобы сервер не был перегружен на старте. Пока использование кэша KV остаётся ниже 60% и нет ожидающих запросов, лимит увеличивается на 25%, но не чаще, чем один раз за каждые cap завершённых роллаутов. Если использование превышает 80%, лимит снижается на 30%: текущие запросы продолжают выполняться, а новые ждут. Если у сервера нет эндпоинта /metrics, лимитом служит max_concurrent_rollouts.

Ресурсы. max_concurrent_rollouts (по умолчанию 512) — это верхний предел количества одновременно выполняемых rollouts. Это единственный лимит, который вы устанавливаете самостоятельно, поскольку trainer не может определить, что способны выдержать ваши окружения и инструменты. Каждый выполняющийся rollout использует окружение, может выполнять синхронные вызовы инструментов в пуле потоков такого же размера и поддерживает открытое соединение с сервером vLLM. Установите значение, которое они способны выдержать, например, количество сессий, которые принимает ваш сервер окружений:

from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    max_concurrent_rollouts=64,
)

Если значение слишком низкое, генерация замедляется. Роллаут удерживает свой слот, пока выполняет инструменты или ожидает между ходами, а не только во время генерации vLLM, поэтому роллаутам, которые вызывают много инструментов, требуется больше слотов, чтобы vLLM оставался загруженным. Если значение значительно выше значения по умолчанию, сервер vLLM может начать отбрасывать соединения.

Записанные метрики показывают, какой лимит сдерживает генерацию:

  • rollout/backpressure_s больше нуля: предел устаревания. Генерация опережает обучение, что ожидаемо, когда инференс быстрее обучения.
  • rollout/concurrency при rollout/concurrency_cap, ниже max_concurrent_rollouts: нагрузка на сервер vLLM.
  • rollout/concurrency на уровне max_concurrent_rollouts, при низком rollout/vllm_kv_cache_usage_frac и высоком perf/rollout_wait_s: это предел. Увеличьте max_concurrent_rollouts, если ваши окружения и инструменты это позволяют.

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

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

  • rollout/queue_size: сколько образцов ожидают в очереди.
  • sample/time_in_queue_s: время, которое один образец провёл в очереди до начала обучения, временная составляющая его устаревания.
  • perf/rollout_wait_s: время ожидания обучения из-за пустой очереди.
  • rollout/backpressure_s: время ожидания генерации, так как она опережала обучение на max_staleness шагов.

Последние две являются зеркальными отражениями. В сочетании с размером очереди они показывают, какая сторона является узким местом:

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

Насыщенность и дубликаты

Политика обучается на основе различий между результатами (rollouts) в группе: каждое преимущество (advantage) вычисляется относительно среднего вознаграждения группы. Если все результаты в группе получают одинаковое вознаграждение, их преимущества равны нулю, и такая группа отбрасывается (см. Записываемые метрики), не давая политике никакой информации для обучения. По мере насыщения выполнения всё больше групп оказываются в таком состоянии, либо потому что все результаты решают задачу, либо потому что ни один не решает. Четыре метрики позволяют различить эти случаи, и каждая отвечает на свой вопрос, поэтому их можно легко интерпретировать по графикам:

метрикавопрос
frac_zero_std_groupsкакая доля групп не несёт сигнала
reward_zero_std_groupsгде эти группы застряли: их средняя награда. При наградах 0/1 это доля групп, в которых все проходы (rollout) прошли успешно, поэтому 0.9 означает, что почти все они решены, а 0.1 — что почти все они проваливают каждый проход
rewardнасколько хорошо действует политика на каждой оценённой группе, включая отброшенные
completions/duplicate_fracостается ли выборка генерацией различных результатов для одного и того же запроса

Прочитайте первые три вместе, в контексте диапазона вашего вознаграждения:

frac_zero_std_groupsreward_zero_std_groupsrewardдиагностикачто делать
lowany (шумные по нескольким группам)anyhealthy: большинство групп производят градиентnothing
climbingв верхней части диапазонаclimbingнасыщение на верхнем уровне: промпты стали слишком простыми для политики, и именно так обычно заканчивается успешный прогоностановить выполнение или перейти к более сложным запросам
высокийв нижней части диапазонанизкий и плоскийзастраивание на нижнем уровне: промпты слишком сложные, либо функция вознаграждения никогда не выдаёт положительной оценкиСначала проверьте completions/clipped_ratio, так как завершение, обрезанное до ответа, получает оценку 0, а затем прочитайте несколько завершений, чтобы убедиться, что функция вознаграждения корректно их обрабатывает
climbingснижениеснижениеregression: группы, которые раньше проходили, теперь вместе проваливаютсяпроверьте completions/duplicate_frac и entropy на предмет коллапса
высокийв серединеanyсмесь: при наградах 0/1 некоторые промпты слишком простые, а другие — слишком сложные. При частичных наградах группы также могут застревать на одном и том же частичном баллепрочитать развёртки

completions/duplicate_frac — доля роллаутов, которые повторяют предыдущий роллаут своей группы посимвольно на протяжении всех их ходов. Идентичные роллауты получают одинаковые награды, поэтому дубликаты также увеличивают frac_zero_std_groups.

completions/duplicate_fracдиагностика
близко к 0, с небольшим базовым уровнем на задачах, где завершения достаточно короткие, чтобы повториться случайноhealthy: роллауты группы образуются независимо
резко возрастает до (num_generations - 1) / num_generationsвыборка больше не является случайной: каждая группа возвращается как копии одного прогона. Например, температура равна 0, или движки vLLM с параллелизмом данных декодируют один и тот же текст, потому что разделяют сид выборки (воркер отправляет уникальный сид с каждым запросом, чтобы предотвратить это)
медленно возрастает, при этом entropy снижаетсяcollapse: политика сходится к одному ответу на каждый запрос

Эти метрики фиксируются в момент, когда worker оценивает группу, а не когда на её образцах выполняется обучение, поэтому они опережают обучение и включают группы, образцы которых впоследствии отбрасываются из-за превышения max_staleness. Группа, в которой не удалось оценить ни один rollout, потому что каждая функция вознаграждения вернула None, отбрасывается и учитывается в frac_zero_std_groups, но поскольку у неё нет вознаграждения, reward_zero_std_groups её не включает.

Упаковка деревьев

Образцы микробатча упаковываются в одну строку на процесс, без дополнения (padding). Строка представляет собой префиксное дерево (prefix trie), а не конкатенацию: токен, общий для нескольких образцов, обрабатывается один раз, при этом механизм внимания показывает каждому образцу только его собственную историю. Все развёртки (rollouts) в группе повторяют её промпт, а каждый ход многоходовой развёртки повторяет весь разговор до этого момента, поэтому прямой проход сокращается в коэффициент упаковки (batch/packing_ratio). Это лишь изменение компоновки: каждый обучаемый токен сохраняет свою целевую метку, преимущество и старую логарифмическую вероятность, причём его логарифмическая вероятность совпадает с результатом прямого прохода этого образца по отдельности.

На двух роллаутах одного промпта, где p — это промпт, а a и b — два завершения:

1. Rollouts         r0:  p1 p2 p3 a1 a2                10 tokens
                    r1:  p1 p2 p3 b1 b2

2. Trie             S0 [p1 p2] ─┬─ S1 [p3 a1 a2]       p3 is not shared: a position predicts
                                └─ S2 [p3 b1 b2]       one token, and p3 predicts a1 or b1

3. Packed row       index         0  1 |  2  3  4 |  5  6  7
   (depth-first)    input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2    8 tokens: everything but attention
                    position_ids  0  1 |  2  3  4 |  2  3  4    runs on 8 instead of 10
                    segment      S0    | S1       | S2

4. Attention        segment   queries    keys and values: the segment's path in the trie
   (one call)       S0        p1 p2      p1 p2              index 0 1
                    S1        p3 a1 a2   p1 p2 p3 a1 a2     index 0 1 2 3 4
                    S2        p3 b1 b2   p1 p2 p3 b1 b2     index 0 1 5 6 7

5. Loss             r0: a1 a2 predicted at index 2 3   each trained token is predicted at the index
                    r1: b1 b2 predicted at index 5 6   of the token before it in its rollout

Несколько последствий:

  • Общий префикс разделяется: это относится к развёрткам одного промпта, а также к общему системному промпту или схеме инструмента между разными промптами. Образец помещается в строку, где уже находится его группа и его промпт. Когда эта строка заполняется, образец переносится в другую строку, если у процесса ещё есть пустая строка, или если это не увеличит загрузку самой нагруженной строки, которая определяет время микробатча; в противном случае микробатч закрывается.
  • Если ничего не разделяется, это обычная упаковка: каждый пример становится отдельным сегментом, что соответствует стандартной упаковке без отступов.
  • Дублируется только K/V: общий префикс собирается один раз на каждый сегмент потомка, что примерно соответствует объёму данных, который удерживал бы тренировочный процесс без упаковки, и является небольшим при использовании группового внимания (grouped-query attention).
  • Поддерживаются гибриды Gated DeltaNet (Qwen3.5, Qwen3.6, Qwen3-Next, …): их свёртка читает собственных предшественников каждого токена, а их кусочное правило дельты начинает каждый сегмент с конечного состояния его родителя.

token_budget ограничивает количество токенов в строке, при этом общий токен учитывается один раз. По умолчанию это значение равно max_model_len сервера, поэтому ни один образец не может его превысить. Если общих элементов нет, tree packing работает примерно с той же скоростью, что и обычная упаковка без padding, а ускорение растёт примерно пропорционально коэффициенту упаковки (около 2.8–3x при коэффициенте 3.4 на Qwen3-0.6B и 1.7B, на H100). Коэффициент равен длине общего префикса, умноженной на количество образцов в строке, поэтому batch/samples_per_row является основным индикатором: если он близок к 1, общих элементов быть не может, и главным рычагом становится token_budget. batch/row_fill_frac имеет значение, когда образцы длинные: образец на 10k токенов плохо укладывается в бюджет 32k (три помещаются, четыре — никогда, поэтому планировщик часто получает два, и строка заполняется примерно на 77%), тогда как образцы на 1k токенов укладываются в него почти идеально.

Оценивайте tree packing по throughput, batch/trained_tokens_per_step / perf/fwd_bwd_s. Пакетный микро-батч содержит больше образцов, поэтому perf/fwd_bwd_s возрастает, а perf/fwd_bwd_mfu, который делится на количество токенов, переданных в прямом проходе, снижается: ни одно из этих изменений не является регрессией. Больше образцов на строку также означает больше rollouts, извлекаемых на каждом шаге, поэтому run, ограниченный генерацией, становится ещё более ограниченным.

Метрики батча складываются: один шаг содержит gradient_accumulation_steps × num_processes строк, поэтому batch/samples_per_step примерно в такое же количество раз больше, чем batch/samples_per_row, и аналогично для токенов. Обе стороны совпадают только с точностью до вариации между микробатчами одного шага, поскольку метрики на шаг — это суммы, а метрики на строку — средние значения.

Любое изменение, увеличивающее или уменьшающее количество строк, отменяет шаринг. Многоходовой диалог, который никогда не ветвится, представляет собой один длинный образец, а rollout/samples_per_rollout указывает, сколько образцов даёт один диалог.

Выборка top-k и top-p

Top-k и top-p перенормируют распределение выборки по ограниченному набору кандидатов, а не по всему словарю. Лог-вероятности, возвращаемые сервером, отражают это (--logprobs-mode processed_logprobs), поэтому тренеру необходимо нормировать их по тому же набору, иначе каждое отношение важности будет смещено: вероятность токена по всему словарю ниже, чем по набору кандидатов, из которого он был извлечен (DeepSeek-V3.2, раздел 3.1). При top_p < 1 или top_k > 0 воркер запрашивает у сервера набор кандидатов для каждого сэмплированного токена, а тренер перенормирует его лог-вероятности по этому набору. Для этого требуются два дополнительных флага сервера, и top_k должен быть задан, поскольку vLLM ограничивает размер набора кандидатов именно этим параметром:

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --return-sampling-mask \
    --enable-scale-out
from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    top_p=0.95,
    top_k=512,
)

--return-sampling-mask заставляет vLLM фиксировать множество кандидатов (vLLM 0.28 или новее, на его V2 model runner: VLLM_USE_V2_MODEL_RUNNER=1, если сервер отклоняет флаг), а --enable-scale-out открывает endpoint token-in-token-out, который возвращает это множество. Воркер проверяет наличие обоих на сервере при запуске. Старые версии vLLM не могут вернуть множество, поэтому тренер продолжает нормализацию по всему словарю и выводит предупреждение о смещенном соотношении.

Обучение адаптеров с PEFT

Мы поддерживаем тесную интеграцию с библиотекой 🤗 PEFT, что позволяет обучать адаптеры и делиться ими на Hub, а не обучать всю модель целиком.

from datasets import load_dataset
from peft import LoraConfig
from trl import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

if __name__ == "__main__":
    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3.5-2B",
        reward_funcs=accuracy_reward,
        train_dataset=dataset,
        peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
    )
    trainer.train()

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

VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6

VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 открывает эндпоинт, на который тренер отправляет каждый новый адаптер. Оставляйте --weight-transfer-config даже при использовании --enable-lora: тренер выбирает режим синхронизации только при запуске, к этому моменту сервер уже запущен, а синхронизация со слиянием является вариантом по умолчанию.

--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/ и передаёт серверу путь. Если сервер работает на другой машине, этот каталог должен находиться на файловой системе, доступной обоим узлам.

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

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

Использование пользовательской функции вознаграждения

Класс AsyncGRPOTrainer поддерживает использование пользовательских функций вознаграждения. Для обеспечения совместимости ваша функция вознаграждения должна соответствовать следующим требованиям:

Функции вознаграждения могут быть как синхронными вызываемыми объектами Python, так и асинхронными корутинами async def. При указании нескольких функций вознаграждения они выполняются параллельно: асинхронные ожидаются совместно, а синхронные выполняются в отдельных потоках, что позволяет перекрыть их задержки.

  1. Аргументы ввода:

    • Функция должна принимать следующие аргументы по имени:

      • prompts (содержит промпты),
      • completions (содержит сгенерированные завершения),
      • completion_ids (содержит токенизированные завершения),
      • Все имена столбцов (кроме prompt), которые могут присутствовать в наборе данных. Например, если набор данных содержит столбец с именем ground_truth, функция будет вызвана с ground_truth в качестве именованного аргумента.

      Самый простой способ выполнить это требование — использовать **kwargs в сигнатуре функции.

    • Набор данных представлен в диалоговом формате, поэтому prompts и completions являются списками словарей сообщений.

  2. Возвращаемое значение: функция должна возвращать список чисел с плавающей точкой. Каждое число представляет награду, соответствующую одному завершению.

Функции вознаграждения выполняются в процессе rollout worker, то есть в отдельном процессе, поэтому всё, что передаётся в него, сериализуется с помощью pickle. Каждая функция вознаграждения, инструмент и environment_factory (а также всё, что они захватывают в замыкании) должны быть сериализуемы с помощью pickle: используйте функцию на уровне модуля, functools.partial или экземпляр вызываемого класса. Лямбда-функции и замыкания вызывают TypeError при вызове trainer.train(). Это отличие от GRPOTrainer, где функции вознаграждения вызываются в том же процессе, и замыкания работают.

Процесс rollout также выполняется с CUDA_VISIBLE_DEVICES="", поэтому он не может использовать GPU. Модель вознаграждения, работающая на GPU (например, оценщик AutoModelForSequenceClassification), загружается без ошибок, но молча переключается на CPU. Держите функции вознаграждения легкими (верификаторы вроде accuracy_reward, проверки формата или длины). Если вам нужна модель вознаграждения на GPU, обслуживайте её через собственный движок инференса (vLLM, TGI, …) на отдельных GPU и создайте сериализуемую функцию вознаграждения, которая вызывает её по HTTP.

Пример 1: Поощрение более длинных завершений

Ниже приведен пример функции вознаграждения, которая поощряет более длинные завершения:

def reward_func(completion_ids, **kwargs):
    """Reward function that assigns higher scores to longer completions (in terms of token count)."""
    return [float(len(ids)) for ids in completion_ids]

Вы можете протестировать это следующим образом:

>>> prompts = [[{"role": "user", "content": "The sky is"}], [{"role": "user", "content": "The sun is"}]]  # not used in the reward function, but the trainer will pass it
>>> completions = [[{"role": "assistant", "content": " blue."}], [{"role": "assistant", "content": " in the sky."}]]  # not used in the reward function, but the trainer will pass it
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[2.0, 4.0]

Пример 2: Награждайте завершения с определенным форматом

Ниже приведен пример функции вознаграждения, которая проверяет, соответствует ли ответ определенному формату. Этот пример вдохновлен функцией format reward, используемой в статье DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Она предназначена для диалогового формата, в котором промпты и ответы состоят из структурированных сообщений.

import re

def format_reward_func(completions, **kwargs):
    """Reward function that checks if the completion has a specific format."""
    pattern = r"^<think>.*?</think><answer>.*?</answer>$"
    completion_contents = [completion[0]["content"] for completion in completions]
    matches = [re.match(pattern, content) for content in completion_contents]
    return [1.0 if match else 0.0 for match in matches]

Вы можете протестировать эту функцию следующим образом:

>>> prompts = [
...     [{"role": "user", "content": "What is the result of (1 + 2) * 4?"}],
...     [{"role": "user", "content": "What is the result of (3 + 1) * 2?"}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": "<think>The sum of 1 and 2 is 3, which we multiply by 4 to get 12.</think><answer>(1 + 2) * 4 = 12</answer>"}],
...     [{"role": "assistant", "content": "The sum of 3 and 1 is 4, which we multiply by 2 to get 8. So (3 + 1) * 2 = 8."}],
... ]
>>> format_reward_func(prompts=prompts, completions=completions)
[1.0, 0.0]

Пример 3: Награды за завершения на основе эталонного

Ниже приведен пример функции вознаграждения, которая проверяет правильность завершения. Этот пример вдохновлен функцией accuracy reward, используемой в статье DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Набор данных содержит столбец с именем ground_truth.

import re

def reward_func(completions, ground_truth, **kwargs):
    # Regular expression to capture content inside \boxed{}
    matches = [re.search(r"\\boxed\{(.*?)\}", completion[0]["content"]) for completion in completions]
    contents = [match.group(1) if match else "" for match in matches]
    # Reward 1 if the content is the same as the ground truth, 0 otherwise
    return [1.0 if c == gt else 0.0 for c, gt in zip(contents, ground_truth)]

Вы можете протестировать эту функцию следующим образом:

>>> prompts = [
...     [{"role": "user", "content": "Solve the equation $2x + 3 = 7$."}],
...     [{"role": "user", "content": "Solve the equation $3x - 5 = 10$."}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": r"The solution is \boxed{2}."}],
...     [{"role": "assistant", "content": r"The solution is \boxed{6}."}],
... ]
>>> ground_truth = ["2", "5"]
>>> reward_func(prompts=prompts, completions=completions, ground_truth=ground_truth)
[1.0, 0.0]

Пример 4: Многозадачные функции вознаграждения

Ниже приведен пример использования нескольких функций вознаграждения в AsyncGRPOTrainer. В этом примере мы определяем две функции вознаграждения, специфичные для задач: math_reward_func и coding_reward_func. Функция math_reward_func оценивает математические задачи по их правильности, а coding_reward_func — задачи по программированию по тому, работает ли решение.

from datasets import Dataset
from trl import AsyncGRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": [{"role": "user", "content": "What is 2+2?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "Write a function that returns the sum of two numbers."}], "task": "code"},
        {"prompt": [{"role": "user", "content": "What is 3*4?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "Write a function that returns the product of two numbers."}], "task": "code"},
    ]
)

# Math-specific reward function
def math_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "math":
            # Calculate math-specific reward
            correct = check_math_solution(prompt, completion)
            reward = 1.0 if correct else -1.0
            rewards.append(reward)
        else:
            # Return None for non-math tasks
            rewards.append(None)
    return rewards

# Coding-specific reward function
def coding_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "code":
            # Calculate coding-specific reward
            works = test_code_solution(prompt, completion)
            reward = 1.0 if works else -1.0
            rewards.append(reward)
        else:
            # Return None for non-coding tasks
            rewards.append(None)
    return rewards

# Use both task-specific reward functions
if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen2.5-0.5B-Instruct",
        reward_funcs=[math_reward_func, coding_reward_func],
        train_dataset=dataset,
    )

    trainer.train()

В этом примере math_reward_func и coding_reward_func разработаны для работы со смешанным набором данных, содержащим как математические, так и программные задачи. Колонка task в наборе данных используется для определения, какую функцию вознаграждения применить к каждой задаче. Если для образца в наборе данных нет соответствующей функции вознаграждения, функция вернёт None, и AsyncGRPOTrainer продолжит работу с валидными функциями и задачами. Это позволяет AsyncGRPOTrainer обрабатывать несколько функций вознаграждения с разной областью применения.

Обратите внимание, что AsyncGRPOTrainer игнорирует награды None, возвращаемые функциями вознаграждения, и учитывает только награды, возвращаемые соответствующими функциями. Это гарантирует, что модель обучается на релевантных задачах и игнорирует те, для которых нет соответствующей функции вознаграждения.

Пример 5: Асинхронные функции вознаграждения

Пользовательские функции вознаграждения также можно определять как корутины async def. Это полезно, если ваше вознаграждение зависит от медленного ввода-вывода (например, вызова удалённого сервиса). При передаче нескольких асинхронных функций вознаграждения AsyncGRPOTrainer выполняет их параллельно, чтобы их задержки перекрывались.

Ниже приведен минимальный пример асинхронной функции вознаграждения, имитирующей операцию, ограниченную вводом-выводом:

import asyncio

async def async_reward_func(prompts, completions, **kwargs):
    # Simulate an I/O-bound call (e.g., HTTP request, database lookup)
    await asyncio.sleep(0.01)
    # Simple toy reward: 1.0 if the completion is non-empty, else 0.0
    return [1.0 if completion else 0.0 for completion in completions]

Передача функции вознаграждения в тренер

Чтобы использовать собственную функцию вознаграждения, передайте её в AsyncGRPOTrainer следующим образом:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    reward_funcs=reward_func,
    ...,
)

Можно передать несколько функций вознаграждения в виде списка; этот список может включать как синхронные, так и асинхронные функции:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    reward_funcs=[reward_func, async_reward_func1, async_reward_func2],
    ...,
)

а награда будет вычислена как сумма наград от каждой функции.

Настройка цикла развёртывания

Генерация, вознаграждения, преимущества и фильтрация выполняются в процессе rollout, в AsyncRolloutLoop. Чтобы изменить один из этих этапов, создайте подкласс цикла, переопределите метод для нужного этапа и установите этот подкласс как loop_cls в подклассе тренера. Конструктор тренера при этом не меняется.

МетодВызываетсяПо умолчанию
filter_prompt(row_index, row, epoch)один раз на промпт, перед генерациейпринимает любой промпт
generate_one(prompt, tools, group_id)один раз на каждый rolloutмногоходовый цикл использования инструментов
generate_one_turn(prompt_ids)один раз на запрос выборкиодин запрос vLLM с параметрами выборки из конфигурации
compute_advantages(group)один раз для каждой группы, после того как вознаграждения будут сложены в group.rewardsнаграда, стандартизованная в пределах группы
setup(), close()когда циклы начинают и прекращают работуnothing

Например, программа обучения, которая прекращает выборку промптов, которые политика уже решает, с порогом в подклассе конфигурации:

from dataclasses import dataclass

import numpy as np

from trl import AsyncGRPOConfig, AsyncGRPOTrainer
from trl.trainer.async_grpo_trainer import AsyncRolloutLoop


@dataclass
class CurriculumConfig(AsyncGRPOConfig):
    pass_rate_cap: float = 0.9


class CurriculumRolloutLoop(AsyncRolloutLoop):
    def filter_prompt(self, row_index, row, epoch):
        return self.pass_rates.get(row_index, 0.0) < self.config.pass_rate_cap

    async def setup(self):
        self.pass_rates = {}

    def compute_advantages(self, group):
        scored = group.rewards[~np.isnan(group.rewards)]
        if len(scored):
            self.pass_rates[group.row_index] = float(np.mean(scored > 0))
        return super().compute_advantages(group)


class CurriculumTrainer(AsyncGRPOTrainer):
    loop_cls = CurriculumRolloutLoop

Награды суммируются по reward_funcs, окружениям, определяющим get_reward, и значению reward, которое пользовательский generate_one устанавливает в своём Rollout: для оценки с помощью судьи передайте асинхронную функцию награды или выполняйте оценку внутри generate_one. compute_advantages выполняется для каждой группы, включая ту, которая затем отбрасывается, потому что все её оценённые награды равны; отбрасывание основано на наградах, а не на преимуществах. Цикл создаётся в запущенном процессе, поэтому определите подкласс на уровне модуля и поместите код обучения под if __name__ == "__main__":. Создавайте клиенты в setup, который выполняется в event loop цикла, а не переопределяя __init__. Промпт, отклонённый filter_prompt, пропускается в этом эпохе и учитывается в его счётчике, как и отброшенная группа. Если он отклоняет все промпты эпохи, цикл вызывает исключение.

Возобновление из контрольной точки

Базовый Trainer возобновляет работу, пропуская и повторно обрабатывая батчи, на которых уже обучался, что неприменимо к живой очереди rollout, поэтому ignore_data_skip всегда равен True. Вместо этого индекс первого промпта, на котором ещё не было обучения, сохраняется в rollout_state.json вместе с каждой контрольной точкой и восстанавливается при возобновлении, благодаря чему воркер быстро перемотывается к этому промпту без повторной обработки сэмплов. Это позиция trained, а не позиция генератора: воркер опережает обучение на глубину очереди rollout, и эти буферизованные сэмплы теряются при завершении запуска, поэтому возобновление с позиции генератора привело бы к пропуску промптов, которые были сгенерированы, но не использовались для обучения. Потоковые датасеты (IterableDataset) нельзя перемотать, поэтому их воркер при возобновлении начинает с первого промпта.

Обучение агента

Асинхронный GRPO поддерживает обучение агентов: модель вызывает инструменты в процессе генерации и учится на их результатах.

  • Инструмент — это обычная функция Python (синхронная или асинхронная), доступная модели. Используйте tools для вызовов без состояния (калькулятор, веб-поиск).
  • Environment — более общая форма: объектом с состоянием, создаваемым заново для каждого rollout, публичные методы которого доступны как инструменты, плюс хук жизненного цикла reset и необязательный get_reward, позволяющий среде самостоятельно определять награду. Используйте environment_factory, если вам нужно состояние для каждого rollout, хук сброса или награда, управляемая средой.

Они комбинируются — вы можете передать автономные tools вместе с environment_factory.

Инструменты

Аргумент tools принимает список функций Python (синхронных или асинхронных), которые определяют инструменты, доступные агенту:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    tools=[tool1, tool2],
    ...,
)

Каждый инструмент должен быть стандартной функцией Python с аргументами и типом возвращаемого значения, указанными через type hints, а также документирующей строкой в стиле Google, описывающей его назначение, аргументы и возвращаемое значение. Подробнее см. в руководстве по передаче инструментов.

Модель вызывает инструмент по его имени, поэтому каждый инструмент регистрируется под своим __name__ и должен быть функцией на уровне модуля, что также позволяет сериализовать его для rollout-воркера. Синхронные инструменты выполняются в пуле потоков размером max_concurrent_rollouts, поэтому медленный инструмент никогда не блокирует другие выполняющиеся rollout-процессы. В рамках одного хода ассистента вызовы инструментов выполняются в том порядке, в котором модель их сгенерировала. Таким образом, одновременно может выполняться до max_concurrent_rollouts синхронных инструментов, поэтому инструмент, читающий или записывающий общее состояние, должен быть потокобезопасным.

Цикл вызова инструментов требует, чтобы шаблон чата был сохраняющим префикс (добавление сообщения инструмента не должно изменять отображение предыдущих сообщений). Для известных семейств моделей (например, Qwen3, DeepSeek-V3) TRL автоматически подставляет исправленный шаблон обучения, когда инструменты включены. Полный список см. в разделе Chat Templates.

Используйте max_tool_calling_iterations в AsyncGRPOConfig, чтобы ограничить количество ходов с вызовом инструментов. По умолчанию ограничение отсутствует, и генерация останавливается, когда модель выдаёт ответ без вызовов инструментов.

Пример:

from trl import AsyncGRPOTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

async def async_add(a: int, b: int) -> int:
    """
    Asynchronously adds two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The sum of the two integers.
    """
    return a + b

trainer = AsyncGRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

Окружения

Вы также можете предоставить инструменты через environment_factory. В этом режиме AsyncGRPOTrainer создаёт один экземпляр среды на каждый rollout и предоставляет публичные методы среды в качестве инструментов.

При использовании environment_factory среда владеет данными: внешнего train_dataset нет. На каждом rollout reset() формирует задачу — самообразец из корпуса, которым владеет среда, или процедурная генерация состояния — и возвращает промпт. max_steps задаёт длительность обучения. Ниже приведён минимальный пример среды, которая самообразует целевое значение и предоставляет метод increment (представленный как инструмент).

import random

from trl import AsyncGRPOConfig, AsyncGRPOTrainer

class IncrementEnv:
    # Reserved methods
    def reset(self, **kwargs) -> str | None:  # required; called at the start of each rollout
        self.counter = 0
        self.target = random.randint(1, 6)  # self-sample the task
        return f"Increment the counter by {self.target}."  # returned string becomes the prompt

    def get_reward(self) -> float:  # optional: the environment scores itself from its own state
        return float(self.counter == self.target)

    # Public methods (exposed as tools)
    def increment(self, step: int) -> int:
        """
        Increment the internal counter.

        Args:
            step: Value to add to the counter.

        Returns:
            The updated counter value.
        """
        self.counter += step
        return self.counter

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        args=AsyncGRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
        environment_factory=IncrementEnv,
    )
    trainer.train()

Класс окружения имеет два зарезервированных метода: reset и get_reward. В отличие от любых других публичных методов, они не предоставляются модели в качестве инструментов.

  • reset (обязательный) вызывается при начале rollout. Он может возвращать либо None, либо строку. Если возвращается строка, она является пользовательским запросом.
  • get_reward (необязательный, синхронный или асинхронный) не принимает аргументов и возвращает float: среда оценивает только что завершённый эпизод на основе своего внутреннего состояния (завершилась ли игра победой? было ли угадано слово?). Вызывается один раз за каждый завершённый rollout и служит источником вознаграждения.

Оба выполняются в пуле потоков инструментов воркера, поэтому медленное окружение задерживает только собственный rollout, но не другие, находящиеся в процессе выполнения. Их длительность фиксируется в логах как env/reset_s и env/reward_s.

Поскольку среда выполняет самоотборку при каждом вызове reset(), G членов группы GRPO могут не разделять одно и то же начальное состояние, что делает базовую линию группы немного более шумной. Для идентичных состояний внутри группы убедитесь, что reset() детерминированно выводит состояние из общего ключа.

Предоставление внешнего набора данных (необязательно)

Вместо того чтобы позволять среде самостоятельно генерировать примеры, вы можете передать внешний train_dataset. Например, если ваши задачи уже хранятся в датасете, или для маршрутизации между несколькими средами. Для каждого rollout тренер выбирает одну строку, использует её столбец "prompt" в качестве промпта и передаёт столбцы этой строки в reset() в виде именованных аргументов (таким образом, среда считывает задачу из датасета).

from datasets import Dataset
from trl import AsyncGRPOTrainer

# Each row carries the prompt and the task data (here, the counter target to reach).
dataset = Dataset.from_dict(
    {
        "prompt": [[{"role": "user", "content": f"Increment the counter to {i}."}] for i in range(1, 7)],
        "target": list(range(1, 7)),
    }
)

class IncrementEnv:
    def reset(self, target, **kwargs) -> None:  # the row's `target` column arrives as a keyword argument
        self.counter = 0
        self.target = target

    def get_reward(self) -> float:
        return float(self.counter == self.target)

    def increment(self, step: int) -> int:  # exposed as a tool (see the full docstring above)
        self.counter += step
        return self.counter

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        train_dataset=dataset,  # the dataset owns the task; the "target" column reaches reset(target=...)
        environment_factory=IncrementEnv,
    )
    trainer.train()

Награды

Награды, управляемые средой, и награды, управляемые тренером, не являются взаимоисключающими. Передавайте reward_funcs для наград, которые естественно вычислять по завершению (например, проверка формата текста) и позволяйте среде возвращать свою зависящую от состояния награду через get_reward. Все источники суммируются с весом 1.

def format_reward(completions, **kwargs):  # trainer-owned: scores the completion text
    ...

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=AsyncGRPOConfig(max_steps=1000),
    reward_funcs=format_reward,          # trainer-owned: scores the completion
    environment_factory=IncrementEnv,    # env-owned: scores its internal state via `get_reward`
)

Несколько сред

Чтобы обучать модель на смеси задач в одном прогоне (например, на задаче программирования и игре), передайте словарь, сопоставляющий имена сред с фабриками, вместо единой вызываемой функции. Каждый rollout выбирает свою среду через поле environment в наборе данных, и доступны только инструменты этой среды. Это предотвращает утечку нерелевантных инструментов (инструмент move из игры в пример с кодом и наоборот). Каждая среда по-прежнему владеет своими данными и возвращает промпт из reset(), поэтому в наборе данных достаточно столбца environment для маршрутизации между средами.

import random

from datasets import Dataset
from trl import AsyncGRPOConfig, AsyncGRPOTrainer


class CodingEnv:
    def reset(self, **kwargs) -> str:
        n = random.randint(1, 20)
        return f"Compute the {n}th Fibonacci number."

    def run_code(self, code: str) -> str:  # exposed as a tool only for "coding" examples
        """Run the given Python code and return its stdout.

        Args:
            code: The Python source to execute.

        Returns:
            The captured standard output.
        """
        ...

class GameEnv:
    def reset(self, **kwargs) -> str:
        return "Reach the goal tile."

    def move(self, action: str) -> str:  # exposed as a tool only for "game" examples
        """Apply an action to the game and return the new observation.

        Args:
            action: One of "up", "down", "left", "right".

        Returns:
            The observation after the move.
        """
        ...

# The dataset only routes: each row picks the environment for that rollout
if __name__ == "__main__":
    dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        args=AsyncGRPOConfig(chat_template_kwargs={"enable_thinking": False}),
        train_dataset=dataset,
        reward_funcs=reward_func,
        environment_factory={"coding": CodingEnv, "game": GameEnv},
    )
    trainer.train()

Экземпляры среды переиспользуются между шагами (сбрасываются между эпизодами), поэтому дорогостоящий __init__ выполняется один раз, а не на каждом шаге. Поле environment используется тренером и не передаётся в reset.

Многоходовые развёртки

Каждый ход рендерит весь диалог через шаблон чата и генерирует ответ на его основе. Шаблон чата не всегда рендерит растущий диалог одинаково (например, некоторые шаблоны отбрасывают рассуждения из предыдущих ходов), поэтому токены промпта для хода могут отличаться от токенов, накопленных на данный момент. В конце rollout-а воркер согласует ходы в обучающие примеры: ход, промпт которого начинается с накопленных токенов, добавляется к тому же примеру, а любой другой ход начинает новый пример. Каждый сгенерированный токен обучается ровно в одном примере, поэтому ветвление обходится в токенах для прямого прохода, но не даёт обучающего сигнала.

Каждый образец rollout получает преимущество rollout. rollout/fork_frac и rollout/drift_tokens_* показывают, как были согласованы ходы.

Интеграции с окружениями

Чтобы обучать агентов, работающих в собственной среде выполнения, например, агентов для написания кода в песочницах Harbor, см. раздел Обучение в средах выполнения в руководстве OpenEnv.

Обучение моделей «зрение-язык»

Модели «зрение-язык» (Qwen3.5, Qwen3.6, Qwen3-VL, …) можно обучать на наборах данных, содержащих только текст. Передайте идентификатор модели как обычно; ничего другого менять не нужно.

Башня зрения заморожена. Текстовый датасет никогда не порождает токены изображений, поэтому башня не задействуется в прямом проходе. Всё, что находится за пределами текстовой модели (башня зрения, мультимодальный проектор), имеет requires_grad=False: оно не получает градиенты и состояние оптимизатора, а синхронизация весов его пропускает, поэтому сервер сохраняет значения, загруженные из чекпоинта. Башня всё равно загружается, поэтому её веса занимают память GPU.

Изображения пока не поддерживаются. Промпты, содержащие изображения, не передаются на сервер vLLM и не участвуют в прямом проходе обучения. Для мультимодального обучения также необходим путь упаковки без заполнителей для построения 3D-позиций M-RoPE из сетки изображения, который здесь не реализован.

AsyncGRPOTrainer

класс trl.AsyncGRPOTrainer

< >

( model: str | PreTrainedModelreward_funcs: collections.abc.Callable[..., list[float]] | list[collections.abc.Callable[..., list[float]]] | None = Noneargs: trl.trainer.async_grpo_config.AsyncGRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)peft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset]] | None = None )

Параметры

  • model (str или PreTrainedModel) — Модель, подлежащая обучению. Может быть одним из следующих вариантов:
    • Строка, являющаяся model id предобученной модели, размещённой в репозитории моделей на huggingface.co, или путь к каталогу, содержащему веса модели, сохранённые с помощью save_pretrained, например './my_model_directory/'. Модель загружается с архитектурой, объявленной в её конфигурации: AutoModelForImageTextToText для контрольной точки vision-language (в которой vision tower загружается, но замораживается, см. Training Vision Language Models), в противном случае — AutoModelForCausalLM.
    • Объект PreTrainedModel. Его реализация внимания переключается на backend tree attention тренера для пакетного обучения.

    Имя модели из конфигурации используется для идентификации модели на сервере vLLM, применяемом для генерации.

  • reward_funcs (RewardFunc | list[RewardFunc], необязательный) — Функции вознаграждения, используемые для вычисления наград. Для вычисления наград мы вызываем все функции вознаграждения с промптами и завершениями и суммируем награды. Можно опустить, если вознаграждение предоставляется средой через environment_factory (см. ниже). Может быть:
    • Одна функция вознаграждения: функция получает промпты и сгенерированные завершения, а также любые дополнительные столбцы в наборе данных. Она должна возвращать список вознаграждений. Функции вознаграждения могут быть как синхронными, так и асинхронными, а также возвращать None, если вознаграждение неприменимо к этим образцам. Это полезно для обучения в многозадачном режиме, где разные функции вознаграждения применяются к разным типам образцов. Если функция вознаграждения возвращает None для образца, эта функция вознаграждения исключается из расчёта вознаграждения для данного образца. Дополнительные сведения см. в разделе Использование пользовательской функции вознаграждения.
    • Список функций вознаграждения, где каждый элемент представляет собой функцию вознаграждения, описанную выше. Вознаграждения от всех функций суммируются.

    В отличие от GRPOTrainer, вознаграждения вычисляются в дочернем процессе, поэтому каждая функция вознаграждения (вместе с tools и environment_factory) должна быть сериализуемой: используйте функцию на уровне модуля, functools.partial или экземпляр вызываемого класса — лямбда-функции и замыкания приведут к ошибке при запуске. Инструменты регистрируются по их __name__, поэтому они должны быть функциями на уровне модуля. Дочерний процесс также запускается с CUDA_VISIBLE_DEVICES="", поэтому модель вознаграждения, использующая GPU, будет работать на CPU (медленно), а не на GPU тренера.

  • args (AsyncGRPOConfig, необязательный) — Конфигурация для этого тренера. Если None, используется конфигурация по умолчанию.
  • train_dataset (Dataset или IterableDataset, необязательный) — Набор данных для обучения. Он должен содержать столбец "prompt". Любые дополнительные столбцы в наборе данных игнорируются. Образцы должны быть в диалоговом формате: каждый образец содержит структурированные сообщения (например, роль и содержимое).

    Можно опустить только в том случае, если предоставлен environment_factory и среда владеет данными (или генерирует их процедурно), возвращая промпт из метода reset(). В этом случае необходимо задать max_steps, чтобы определить длительность обучения.

  • processing_class (PreTrainedTokenizerBase, необязательный) — Класс обработки, используемый для обработки данных. Сторона дополнения (padding) должна быть установлена в значение “left”. Если None, класс обработки загружается по имени модели с помощью from_pretrained. Токен дополнения, tokenizer.pad_token, должен быть установлен. Если в классе обработки не задан токен дополнения, по умолчанию будет использован tokenizer.eos_token.
  • callbacks (список TrainerCallback, необязательный) — Список callback'ов для настройки цикла обучения. Они будут добавлены к списку callback'ов по умолчанию, описанных здесь.

    Если вы хотите удалить один из используемых по умолчанию колбэков, воспользуйтесь методом remove_callback.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], необязательный, по умолчанию (None, None)) — Кортеж, содержащий оптимизатор и планировщик, которые будут использоваться. По умолчанию будет создан экземпляр AdamW для вашей модели и планировщик, заданный функцией get_linear_schedule_with_warmup и управляемый параметрами args.
  • peft_config (PeftConfig, необязательный) — конфигурация PEFT, используемая для обёртки модели. Если None, модель не оборачивается. Если сервер vLLM был запущен с --enable-lora, адаптер LoRA синхронизируется с ним как адаптер, а не как объединённые веса; см. раздел LoRA в документации AsyncGRPO.
  • tools (список Callable, необязательный) — Список вызываемых функций-инструментов (синхронных или асинхронных), которые модель может вызывать во время генерации. Каждый инструмент должен быть стандартной функцией Python с корректно типизированными аргументами и значениями возвращаемых значений, а также документирующей строкой в стиле Google, описывающей его назначение, аргументы и возвращаемое значение. Дополнительные сведения см. по адресу: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. Модель использует имя функции, типизацию аргументов и документирующую строку, чтобы определить, как её вызвать. Убедитесь, что шаблон чата модели поддерживает использование инструментов и что модель была дообучена для вызова инструментов.
  • environment_factory (EnvironmentFactory или dict[str, EnvironmentFactory], необязательный) — Вызываемый объект, создающий и возвращающий экземпляр среды, или словарь, сопоставляющий имена сред с такими вызываемыми объектами. Класс среды должен определять методы, которые могут вызываться как инструменты в процессе генерации. Каждый метод должен соответствовать тем же требованиям, что и tools описанные выше. Среда также должна реализовывать вызываемый метод reset который можно использовать для сброса состояния между генерациями. Метод reset должен возвращать None или строку: если возвращается строка, она добавляется к последнему сообщению пользователя перед генерацией. Среда также может определять метод get_reward не принимающий аргументов и возвращающий float: при наличии которого среда управляет вознаграждением, а get_reward вызывается один раз за каждый завершённый прогон для оценки на основе внутреннего состояния среды. Он действует как дополнительный источник вознаграждения (с весом 1, логируется под именем класса среды) наряду с reward_funcs, который в этом случае становится необязательным.

    С использованием единого вызываемого объекта каждый пример использует одну и ту же среду, при этом на каждый rollout выделяется отдельный экземпляр, что обеспечивает изоляцию их взаимодействий. При использовании словаря каждый пример должен содержать поле environment, указывающее имя среды, и в его prompt будут доступны только инструменты этой среды — это позволяет в одном запуске смешивать задачи (например, среду для программирования и игру). Эта функция является экспериментальной и может быть изменена или удалена в любой момент без предварительного уведомления.

Trainer для метода Group Relative Policy Optimization (GRPO). Этот алгоритм был впервые предложен в статье DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. Данный trainer представляет собой асинхронную версию GRPO, в которой генерация выносится на внешний сервер vLLM, работающий асинхронно параллельно с обучением, что отделяет rollout от цикла обновления градиентов.

Пример:

>>> from trl import AsyncGRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

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

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

Чтобы настроить выборку промптов, способ генерации rollout или вычисления преимуществ, создайте подкласс AsyncRolloutLoop и задайте его в качестве loop_cls тренера. TRL создаёт цикл в

процесс развёртывания:

>>> class CurriculumTrainer(AsyncGRPOTrainer):
...     loop_cls = CurriculumRolloutLoop

обучение

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

Параметры

  • resume_from_checkpoint (str или bool, необязательный) — Если передано значение типа str, это локальный путь к сохранённой контрольной точке, созданной предыдущим экземпляром Trainer. Если передано значение типа bool и оно равно True, загружается последняя контрольная точка из args.output_dir, сохранённая предыдущим экземпляром Trainer. Если параметр указан, обучение возобновляется из состояний модели/оптимизатора/планировщика, загруженных из этой контрольной точки.
  • trial (optuna.Trial или dict[str, Any], необязательный) — Запуск испытания или словарь гиперпараметров для поиска гиперпараметров.
  • ignore_keys_for_eval (list[str], необязательный) — Список ключей в выводе вашей модели (если он представляет собой словарь), которые следует игнорировать при сборе предсказаний для оценки во время обучения.

Возвращает

~trainer_utils.TrainOutput

Объект, содержащий количество глобальных шагов, потерю обучения и метрики.

Основная точка входа для обучения.

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

Сохранит модель, чтобы вы могли загрузить её снова с помощью from_pretrained().

Сохранение будет выполняться только из основного процесса.

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

Параметры

  • commit_message (str, необязательный, по умолчанию "End of training") — Сообщение для коммита при отправке.
  • blocking (bool, необязательный, по умолчанию True) — Определяет, должна ли функция возвращаться только после завершения git push.
  • token (str, необязательный, по умолчанию None) — Токен с правом записи для перезаписи исходных аргументов Trainer.
  • revision (str, необязательный) — Git-ревизия, от которой выполняется коммит. По умолчанию используется head ветки “main”.
  • private (bool, необязательный) — Определяет, следует ли сделать репозиторий приватным при его создании. По умолчанию используется значение args.hub_private_repo. Не имеет эффекта, если репозиторий уже существует.
  • kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в ~Trainer.create_model_card.

Загрузите self.model и self.processing_class в модельный хаб 🤗 в репозиторий self.args.hub_model_id.

AsyncGRPOConfig

класс trl.AsyncGRPOConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: str = 'constant'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 1logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Truerestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Falselabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonedtype: str = 'float32'trust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonenum_generations: int = 8max_completion_length: int = 2048temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonechat_template_kwargs: dict | str | None = Nonemax_tool_calling_iterations: int | None = Nonevllm_server_base_url: str = 'http://localhost:8000'vllm_server_timeout: float = 1800.0epsilon: float = 0.2epsilon_high: float | None = Nonescore_centering: bool = Truevllm_importance_sampling_clip_min: float = 0.5vllm_importance_sampling_clip_max: float = 5.0num_sampler_logprobs: int = 8token_budget: int | None = Nonemax_concurrent_rollouts: int = 512max_staleness: int = 4weight_sync_steps: int = 1rollout_worker_timeout: float = 300.0log_completions: bool = Falsenum_completions_to_print: int | None = None )

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

  • model_init_kwargs (dict[str, Any] или str, необязательный) — Параметры с ключами для from_pretrained, используемые при создании экземпляра модели из пути. Значение revision также используется при загрузке класса обработки.
  • dtype (str, необязательный, по умолчанию "float32") — Тип данных для загрузки модели, один из "auto", "bfloat16", "float16" или "float32". По умолчанию "float32" равенDefeating the Training-Inference Mismatch via FP16) чувствителен к собственной точности тренера. Чтобы закрыть этот разрыв от начала до конца, также необходимо запускать сервер vLLM с тем же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 and from_pretrained.
  • router_aux_loss_coef (float, необязательный) — Коэффициент вспомогательной функции потерь для балансировки нагрузки в моделях Mixture-of-Experts (MoE), добавляемой к функции потерь обучения с этим весом. Если значение не задано, используется значение, объявленное в конфигурации модели. Установите 0.0, чтобы отключить её. Вызывает ошибку при использовании с моделью, не являющейся MoE.

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

  • num_generations (int, необязательный, по умолчанию 8) — Количество генераций на каждый промпт для выборки.
  • max_completion_length (int, необязательный, по умолчанию 2048) — Максимальное количество токенов, генерируемых на каждый запрос vLLM, то есть на каждый ход в многоходовом развёртывании.
  • temperature (float, необязательный, по умолчанию 1.0) — Температура для выборки. Чем выше температура, тем более случайными будут завершения.
  • top_p (float, необязательный, по умолчанию 1.0) — Число с плавающей запятой, управляющее накопленной вероятностью верхних токенов, которые следует учитывать. Должно находиться в диапазоне (0, 1]. Установите значение 1.0, чтобы учитывать все токены. Если значение меньше 1.0, необходимо также задать top_k, а сервер vLLM (>= 0.28) должен быть запущен с параметрами --return-sampling-mask --enable-scale-out: тренер перенормирует свои лог-вероятности по набору кандидатов, из которого был выбран каждый токен, как это делает сервер. Более старые версии vLLM используют весь словарь.
  • top_k (int, необязательный, по умолчанию 0) — Количество токенов словаря с наивысшей вероятностью, которые сохраняются для фильтрации top-k. Если значение равно 0, фильтрация top-k отключается и учитываются все токены. Для любого другого значения требуются флаги сервера, описанные в разделе top_p.
  • min_p (float, необязательный) — Минимальная вероятность токена, которая масштабируется вероятностью наиболее вероятного токена. Значение должно находиться в диапазоне от 0.0 до 1.0. Типичные значения лежат в диапазоне 0.01–0.2. Если значение больше 0.0, необходимо также задать top_k, используя флаги сервера, описанные в разделе top_p.
  • chat_template_kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы для передачи в функцию apply_chat_template при генерации ответов.
  • max_tool_calling_iterations (int, необязательный) — Максимальное количество итераций вызова инструментов при обучении агента. Если None, ограничение отсутствует, и генерация останавливается, когда модель генерирует ответ без вызовов инструментов.

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

  • vllm_server_base_url (str, необязательный, по умолчанию "http --//localhost:8000"): Базовый URL сервера vLLM, используемого для генерации (например, "http://localhost:8000").
  • vllm_server_timeout (float, необязательный, по умолчанию 1800.0) — Таймаут в секундах для вызовов сервера vLLM: ожидание его готовности при запуске, каждый запрос на генерацию и каждый вызов синхронизации весов. Ожидание сервера и вызовы синхронизации весов вызывают ошибку при истечении таймаута; запрос на генерацию, для которого истек таймаут, повторяется.

Параметры, управляющие обучением

  • epsilon (float, необязательный, по умолчанию 0.2) — Значение эпсилона для обрезания.
  • epsilon_high (float, необязательный) — Верхнее значение epsilon для обрезки. Если не указано, по умолчанию используется то же значение, что и нижняя граница, заданная в аргументе epsilon. Статья DAPO рекомендует 0.28.
  • score_centering (bool, необязательный, по умолчанию True) — Следует ли обучать с центрированием скорей (статья) вместо обрезанной целевой функции: взвешенная по важности скор каждого сэмплированного токена минус её математическое ожидание под сэмплером vLLM, так чтобы постоянное преимущество не тянуло политику к сэмплеру. Ожидание берётся по num_sampler_logprobs наиболее вероятным токенам на каждой позиции, лог-вероятности которых сообщает сэмплер.
  • vllm_importance_sampling_clip_min (float, необязательный, по умолчанию 0.5) — Нижняя граница C_min отношения важности между политикой и сэмплером vLLM. Токены, чьё отношение выходит за пределы [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max], исключаются из функции потерь (маскированное сэмплирование по важности).
  • vllm_importance_sampling_clip_max (float, необязательный, по умолчанию 5.0) — Верхняя граница C_max отношения важности.
  • num_sampler_logprobs (int, необязательный, по умолчанию 8) — Количество верхних лог-вероятностей, запрашиваемых у сэмплера vLLM для каждого сгенерированного токена, используется для центрирования оценок. Чем больше значение, тем больше массы вероятности сэмплера покрывается, но тем выше стоимость сериализации; верхняя граница задается параметром сервера --max-logprobs.
  • token_budget (int, необязательный) — Максимальное количество токенов, передаваемых в одном ряду (один forward на DP-ранке). TokenBudgetBatcher формирует микробатчи, сбалансированные по стоимости внимания, в которых каждый ряд укладывается в этот бюджет, ограничивая пиковое потребление памяти независимо от количества образцов (число образцов в ряду становится динамическим). Бюджет ограничивает уникальные токены, а не сырые, поэтому токены, общие для нескольких образцов, учитываются один раз, и он также ограничивает члены функции потерь ряда. Если None (по умолчанию), значение устанавливается равным max_model_len сервера vLLM (запрашивается при начале обучения) — верхнему пределу длины промпта + завершения — так что ни один образец rollout не может превысить бюджет. Образец длиннее token_budget не помещается ни в один ряд и отбрасывается с предупреждением.

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

  • max_concurrent_rollouts (int, необязательный, по умолчанию 512) — Максимальное количество одновременно выполняемых rollouts. Каждый из них удерживает окружение, может выполнять синхронные вызовы инструментов и поддерживает соединение с сервером vLLM, поэтому установите значение, соответствующее возможностям этих ресурсов. Ниже этого предела количество rollouts в работе определяется использованием KV-кэша сервером vLLM и параметром max_staleness.
  • max_staleness (int, необязательный, по умолчанию 4) — Максимальное количество шагов обновления весов, на которые образец rollout может отставать от текущей версии модели, прежде чем быть отброшенным. Генерация ограничена этим значением: новая группа rollout запускается только тогда, когда количество токенов в очереди и в процессе обработки укладывается в объём, который тренер потребляет за max(max_staleness, 1) шагов.
  • weight_sync_steps (int, необязательный, по умолчанию 1) — Количество шагов обучения между синхронизациями весов с сервером vLLM.
  • rollout_worker_timeout (float, необязательный, по умолчанию 300.0) — Количество секунд с момента последнего сигнала о жизни (heartbeat) от rollout-воркера, после которых тренер считает его зависшим и прерывает работу.

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

  • log_completions (bool, необязательный, по умолчанию False) — Следует ли логировать выборку пар (prompt, completion) каждые logging_steps шагов.
  • num_completions_to_print (int, необязательный) — Количество завершений, которые нужно вывести с помощью rich. Если None, в журнал записываются все завершения.

Класс конфигурации для AsyncGRPOTrainer.

Этот класс содержит только параметры, специфичные для асинхронного обучения GRPO. Полный список аргументов обучения см. в документации TrainingArguments. Обратите внимание, что значения по умолчанию в этом классе могут отличаться от значений в TrainingArguments.

Эти параметры имеют значения по умолчанию, отличные от TrainingArguments:

  • logging_steps: по умолчанию 1, а не 500.
  • gradient_checkpointing: по умолчанию True, а не False.
  • bf16: по умолчанию True, если не задан fp16, а не False.
  • learning_rate: по умолчанию 1e-6, а не 5e-5.
  • lr_scheduler_type: по умолчанию constant, а не linear (см. ниже).
  • ignore_data_skip: по умолчанию True, а не False; цикл пропуска и повторного воспроизведения базового Trainer не применяется к асинхронной очереди rollout.
  • remove_unused_columns: по умолчанию False, а не True, и должен оставаться False: все столбцы набора данных передаются в функции вознаграждения.

Длительность обучения и скорость обучения при согласовании в режиме сообщений: Многоразовый диалог может разветвляться на переменное количество строк для обучения (переписывание диалога запускает новую строку), поэтому количество образцов, а значит, и количество шагов оптимизатора на эпоху, заранее неизвестно. Вследствие этого:

  • num_train_epochs ограничивает обучение полным проходом по набору данных prompt, который измеряется количеством уникальных промптов, на которых фактически проводилось обучение. Это значение не зависит от того, сколько строк генерируют форки, поэтому запрос на N эпох всегда означает N проходов по данным. Если max_steps не задано, то именно это параметр служит условием остановки, а max_steps выступает лишь в роли страховочного предела.
  • max_steps, если задан явно (> 0), становится условием остановки (ограничивая процесс по числу шагов оптимизатора, а не по эпохам) и отключает остановку по эпохам.
  • lr_scheduler_type по умолчанию принимает значение constant, поскольку горизонт затухания измеряется в шагах оптимизатора, а их количество заранее неизвестно, если оно зависит от частоты ветвления. Для затухающей скорости обучения задайте расписание с затуханием и явно укажите max_steps.

AsyncRolloutLoop

класс trl.trainer.async_grpo_trainer.AsyncRolloutLoop

< >

( config: AsyncGRPOConfigmodel_name: strdataset: Datasetreward_funcs: list[collections.abc.Callable[..., list[float]]]processing_class: PreTrainedTokenizerBaseeos_token_ids: list[int]rollout_buffer: Queuemodel_version_value: Synchronizedtoken_allowance: Synchronizedheartbeat_value: Synchronizedfailed_event: Eventexception_info_queue: Queuemetrics_queue: Queuetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], object] | dict[str, collections.abc.Callable[[], object]] | None = Nonescore_queue_maxsize: int = 16lora_name: str | None = Nonedataset_start_index: int = 0 )

Генерирует и оценивает rollout-процессы для AsyncGRPOTrainer в запущенном процессе rollout.

По умолчанию реализован GRPO. Чтобы настроить запуск, создайте подкласс, переопределите только изменяемые методы и установите этот подкласс в качестве loop_cls тренера. Каждый промпт проходит по очереди:

  • filter_prompt(): нужно ли вообще генерировать для данного промпта.
  • generate_one(): один полный прогон, который вызывает generate_one_turn() для каждого запроса на выборку.
  • Группа из num_generations прогонов получает оценку: её вознаграждения представляют собой сумму вознаграждений от reward_funcs тренера, от сред, определяющих get_reward, и от Rollout.reward. Затем compute_advantages() выполняется один раз для каждой группы.

setup() и close() создают и освобождают ресурсы на event loop цикла, например HTTP-клиент. Хук может читать self.config (подкласс AsyncGRPOConfig может содержать собственные поля) и self.tokenizer. Поскольку цикл создаётся в запущенном процессе, подкласс должен быть импортируемым (определённым на уровне модуля).

filter_prompt

< >

( row_index: introw: dict[str, typing.Any]epoch: int ) → bool

Параметры

  • row_index (int) — Индекс строки в обучающем наборе данных.
  • row (dict[str, Any]) — Строка набора данных.
  • epoch (int) — Количество полных проходов по набору данных до текущего.

Возвращает

bool

True — сгенерировать num_generations rollouts для промпта, False — пропустить.

Определяет, следует ли генерировать для промпта. Отклонённый промпт пропускается в текущей эпохе и учитывается как потреблённый, подобно отброшенной группе. По умолчанию принимаются все промпты. Отклонение всех промптов полной эпохи приводит к ошибке, поскольку после этого ни одна партия не сможет достичь тренера.

generate_one

< >

( prompt: list[dict[str, str]]tools: list[collections.abc.Callable]group_id: int = 0 ) → Rollout

Параметры

  • prompt (list[dict[str, Any]]) — Сообщения промпта.
  • tools (list[Callable]) — Инструменты, доступные для этого rollout: tools тренера, а также публичные методы среды при использовании environment_factory.
  • group_id (int, необязательный, по умолчанию 0) — Идентификатор группы, к которой принадлежит rollout.

Возвращает

Развёртка

Готовый rollout.

Сгенерировать один rollout для промпта.

По умолчанию многошаговый цикл вызова инструментов работает так: на каждом шаге весь диалог рендерится с помощью шаблона чата, ответ генерируется с помощью generate_one_turn(), а затем выполняются содержащиеся в нём вызовы инструментов, пока модель не перестанет вызывать инструменты или не будет достигнуто значение max_tool_calling_iterations. Переопределите этот цикл, чтобы генерировать ответы иначе, например, с использованием агентного фреймворка. Возвращайте каждый запрос на выборку в Rollout.turns, поскольку обучающие последовательности строятся на их основе, и задавайте Rollout.reward, чтобы оценить результат здесь.

generate_one_turn

< >

( prompt_ids: list[int] ) → TurnRecord

Параметры

  • prompt_ids (list[int]) — Идентификаторы токенов полного промпта.

Возвращает

TurnRecord

Промпт и сэмплированные токены с их лог-вероятностями. При использовании top_k или top_p также содержит множество кандидатов для каждого сэмплированного токена, а при использовании num_sampler_logprobs — топ-лог-вероятности сэмплера.

Сгенерировать один ответ с сервера vLLM, используя параметры выборки из конфигурации (temperature, top_p, top_k, min_p, repetition_penalty и max_completion_length).

compute_advantages

< >

( group: RolloutGroup ) → np.ndarray

Параметры

  • group (RolloutGroup) — num_generations прогонов одного промпта, с их суммарными наградами в group.rewards.

Возвращает

np.ndarray

Одно преимущество на каждый rollout, в порядке group.rewards.

Вычисляет одно преимущество на каждый rollout в группе. По умолчанию каждая награда стандартизируется внутри группы; rollout с наградой NaN получает преимущество 0 и исключается из среднего и стандартного отклонения.

Она выполняется для каждой группы. Группа, у которой все оценённые вознаграждения равны, затем отбрасывается, независимо от того, какие преимущества это возвращает.

настройка

< >

( )

Создаёт ресурсы, необходимые другим хукам, например HTTP-клиент. Выполняется на event loop цикла перед первым запросом. По умолчанию ничего не делает.

закрыть

< >

( )

Освобождает то, что было создано setup(). Вызывается при остановке циклов, в том числе при сбое. По умолчанию ничего не делает.

Rollout

класс trl.trainer.async_grpo_trainer.Rollout

< >

( completion: list[dict[str, str]]completion_ids: list[int]turns: list[trl.trainer.async_grpo_trainer.TurnRecord]tool_call_count: int = 0tool_failure_count: int = 0reward: float | None = Nonerollout_id: str = <factory> )

Параметры

  • completion (list[dict[str, Any]]) — Messages generated after the prompt, in conversational format. Passed to the reward functions as completions.
  • completion_ids (list[int]) — Идентификаторы токенов сгенерированного завершения. Передаются в функции вознаграждения как completion_ids.
  • turns (list[TurnRecord]) — Запросы выборки, которые сформировали rollout, в порядке их следования. На их основе строятся обучающие последовательности: токены, полученные в результате выборки, используются для обучения, а остальная часть каждого промпта служит контекстом.
  • tool_call_count (int, необязательный, по умолчанию 0) — Количество вызовов инструментов, выполненных во время rollout.
  • tool_failure_count (int, необязательный, по умолчанию 0) — Количество тех вызовов инструментов, которые завершились ошибкой.
  • reward (float, необязательный) — Награда, вычисленная в процессе генерации, например, внешним оценщиком. Она прибавляется к наградам, полученным от функций вознаграждения и сред. Если None, этот прогон не получает награды из этого источника.
  • rollout_id (str, необязательный) — Идентификатор rollout в строках его обучения, используется для отладки. По умолчанию присваивается новый случайный hex-идентификатор.

Один завершённый rollout, возвращаемый generate_one().

TurnRecord

класс trl.trainer.async_grpo_trainer.TurnRecord

< >

( prompt_ids: list[int]output_ids: list[int]output_log_probs: list[float] = <factory>output_mask: list[int] | None = Noneoutput_sampling_mask: list[list[int]] | None = Noneoutput_sampler_logprobs: list[dict[int, float]] | None = None )

Параметры

  • prompt_ids (list[int]) — Идентификаторы токенов полного промпта, отправленного для этого хода, включая все предыдущие ходы диалога.
  • output_ids (list[int]) — Идентификаторы токенов, сгенерированные сэмплером.
  • output_log_probs (list[float], необязательный, по умолчанию []) — Лог-вероятности каждого токена в output_ids по данным сэмплера. Обязателен, если обучается хотя бы один из них.
  • output_mask (list[int], необязательный) — Одно значение на каждый токен в output_ids: 1 — обучать на токене, 0 — использовать только как контекст. Если None, обучение выполняется на всех выходных токенах.
  • output_sampling_mask (list[list[int]], необязательный) — Список для каждого токена в output_ids: идентификаторы токенов, из которых сэмплер мог выбрать при усечении по top_k / top_p. Если None, то полный словарь.
  • output_sampler_logprobs (list[dict[int, float]], необязательный) — Словарь для каждого токена в output_ids: лог-вероятности наиболее вероятных токенов, сгенерированных сэмплером, с ключами по идентификаторам токенов. Используется для центрирования оценок (num_sampler_logprobs).

Один запрос на выборку: промпт, отправленный в модуль выборки, и сгенерированные им токены.

RolloutGroup

класс trl.trainer.async_grpo_trainer.RolloutGroup

< >

( prompts: list[list[dict[str, str]]]reward_kwargs: dict[str, list[typing.Any]]completions: list[list[dict[str, str]]]completions_ids: list[list[int]]completions_sequences: list[list[trl.trainer.async_grpo_trainer.TrainingSequence]]tool_call_counts: list[int]tool_failure_counts: list[int]model_version: intgroup_id: introw_index: intenv_rewards: list[tuple[type, float] | None]rollout_rewards: list[float | None]queued_at: float = 0.0rewards: numpy.ndarray | None = None )

Параметры

  • prompts (list[list[dict[str, Any]]]) — Промпт каждого rollout.
  • reward_kwargs (dict[str, list[Any]]) — Остальные столбцы строки датасета промпта, передаваемые в функции вознаграждения в качестве именованных аргументов.
  • completions (list[list[dict[str, Any]]]) — Сообщения с результатами каждого rollout.
  • completions_ids (list[list[int]]) — Идентификаторы токенов завершения для каждого rollout.
  • completions_sequences (list[list[TrainingSequence]]) — Последовательности обучения, построенные из каждого rollout. Rollout, история которого изменилась после повторной токенизации между ходами, дает более одной последовательности.
  • tool_call_counts (list[int]) — Количество вызовов инструментов в каждом прокате.
  • tool_failure_counts (list[int]) — Количество неудачных вызовов инструментов в каждом прокате.
  • model_version (int) — Версия модели на момент начала первого rollout в группе.
  • group_id (int) — Идентификатор группы, нумерация начинается с 0 в процессе rollout.
  • row_index (int) — Индекс строки промпта в обучающем наборе данных.
  • env_rewards (list[tuple[type, float] or None]) — Для rollout, среда которого определяет get_reward, — класс среды и её награда; в противном случае None.
  • rollout_rewards (list[float or None]) — .reward каждого Rollout.
  • queued_at (float, необязательный, по умолчанию 0.0) — time.monotonic() в момент, когда группа была поставлена в очередь для оценки.
  • rewards (np.ndarray, необязательный) — Суммарное вознаграждение каждого rollout, рассчитанное по всем источникам вознаграждения; NaN, если ни один источник не присвоил ему оценку. Устанавливается до вызова compute_advantages().

Роллауты num_generations одного промпта, оценённые совместно. В каждом списке по одному элементу на роллаут.

Update on GitHub