TRL documentation

Treinador GRPO Assíncrono

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Treinador GRPO Assíncrono

model badge

Visão geral

AsyncGRPOTrainer implementa o mesmo algoritmo GRPO, mas desacopla a geração de rollout do treinamento. Um worker em segundo plano transmite continuamente as conclusões de um servidor vLLM enquanto o loop de treinamento as consome, de modo que a geração e as atualizações de gradiente se sobrepõem em vez de alternar.

Este trainer foi contribuído por Amine Dirhoussi e Quentin Gallouédec.

Início rápido

Este exemplo demonstra como treinar um modelo usando o método GRPO Assíncrono. Treinamos um modelo Qwen3.5 2B com os prompts do conjunto de dados DeepMath-103K. Você pode visualizar os dados do conjunto de dados aqui:

Abaixo está o script para treinar o modelo. O trainer precisa de vLLM e kernels, e accuracy_reward precisa de math-verify, que você pode instalar com 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()

A geração é executada em um servidor vLLM, em GPUs diferentes das do treinador. Inicie-o na 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

Em seguida, execute o script na GPU 1 usando o seguinte comando:

CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py

Compatibilidade e restrições

Algumas combinações de argumentos são intencionalmente restritas na implementação atual do AsyncGRPOTrainer:

  • A geração é sempre executada em um servidor vLLM separado, iniciado com vllm serve. Não há modo de colocalização.
  • Prompts from the dataset must be in conversational format. With an environment_factory, the dataset may have no prompt column, and reset() provides it.
  • Funções de recompensa devem ser chamáveis em Python. Modelos de recompensa fornecidos como um id de modelo ou um PreTrainedModel não são suportados, consulte Usando uma função de recompensa personalizada.
  • O trainer precisa de transformers>=5.2.0.
  • O treinamento em shards usa FSDP2. O DeepSpeed não é suportado, e nem o paralelismo de contexto e de sequência (cp_size > 1 ou sp_size > 1 em parallelism_config).
  • use_liger_kernel=True não é suportado.
  • Adaptadores PEFT que visam lm_head não são suportados.
  • Modelos com attention sinks não são suportados. As únicas camadas não de atenção suportadas são as camadas gated DeltaNet de modelos híbridos (Qwen3.5, Qwen3.6, Qwen3-Next, …), que exigem transformers>=5.15.0.
  • Imagens não são suportadas, consulte Training Vision Language Models.

O treinamento carrega o kernel de atenção do Hub por meio da biblioteca kernels: kernels-community/aiter-flash-attn em GPUs AMD (ROCm), kernels-community/flash-attn4 em GPUs NVIDIA Blackwell e kernels-community/flash-attn3 em outras GPUs NVIDIA. Modelos que limitam seus logits de atenção (attn_logit_softcapping), como o Gemma 2, não são suportados em GPUs AMD nem em GPUs NVIDIA Blackwell.

Olhando mais a fundo para o método GRPO Assíncrono

No GRPOTrainer, a geração e o treinamento são sequenciais: gera-se um lote, calcula-se a perda, atualizam-se os pesos e repete-se. Mesmo no modo colocate, uma fase deve terminar antes que a outra comece. No AsyncGRPOTrainer, um worker de rollout gera e pontua as conclusões em um processo em segundo plano enquanto o loop de treinamento calcula a perda e atualiza o modelo. Para entender como funciona, pode ser dividido em três etapas principais: gerar conclusões, calcular a vantagem e calcular a perda. Não há um modelo de referência, portanto não há um termo de divergência de KL (o padrão do GRPO, beta=0.0).

Gerando complementos

O worker de rollout mantém no máximo max_concurrent_rollouts solicitações em andamento para o servidor vLLM. Para cada prompt, ele gera um grupo de G G completos (num_generations) e, quando o grupo inteiro é concluído, avalia-o e calcula suas vantagens. As amostras de treinamento resultantes são colocadas em uma fila, da qual o loop de treinamento as retira. A geração só espera quando está max_staleness etapas à frente do treinamento (veja Concorrência), e uma etapa de treinamento só espera quando a fila está vazia.

A cada weight_sync_steps passos de treinamento, o trainer envia seus pesos atualizados para o servidor vLLM via NCCL, para que as próximas completions venham da política mais recente. Uma completion pode, portanto, vir de uma política alguns passos mais antiga do que a que está sendo treinada: uma amostra que esteja mais de max_staleness atualizações de pesos atrás quando o trainer a busca é descartada.

As métricas e o restante desta página usam os seguintes termos para as etapas pelas quais uma conclusão passa:

  • a grupo é um prompt e seus G G rollouts. A vantagem é calculada dentro dele.
  • um rollout é uma conversa completa gerada para um prompt, incluindo todas as chamadas de ferramenta. Ele é composto por um ou mais turns, cada um correspondendo a uma requisição do vLLM.
  • um sample é o que a perda é calculada sobre: os tokens de um rollout, com sua vantagem. Um rollout de múltiplas rodadas pode produzir mais de um sample (veja Multi-turn rollouts).
  • uma linha é o que um processo encaminha em um micro-lote: várias amostras empacotadas juntas (veja Tree packing). Um micro-lote contém uma linha por processo, e gradient_accumulation_steps micro-lotes formam um passo, o passo do otimizador.

As contagens de tokens se dividem em três tipos: os tokens gerados são aqueles produzidos pelo modelo, os tokens encaminhados são todos os tokens de uma amostra (incluindo o prompt e os resultados de ferramentas) e os tokens treinados são aqueles sobre os quais a perda é calculada.

Calculando a vantagem

Para cada um dos G G completamentos de um grupo, a recompensa é a soma das recompensas de cada função de recompensa. A vantagem é normalizada dentro do grupo, como no GRPO: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

Não há a opção scale_rewards: a vantagem é sempre escalada pelo desvio padrão do grupo. Uma conclusão para a qual todas as funções de recompensa retornaram None é excluída da média e do desvio padrão do grupo e recebe uma vantagem de zero.

Um grupo cujas recompensas são todas iguais é descartado: com a vantagem padrão, ela é zero em todos os pontos, portanto, treinar com ele custaria uma passagem de frente e uma de retrocesso sem mover nada. A fração de grupos assim é registrada como frac_zero_std_groups. O passo é preenchido a partir dos grupos que são mantidos, então muitos grupos descartados significam mais geração por passo. Um grupo descartado ainda conta para a época, que permanece como uma passagem pelos prompts.

Calculando a perda

As log-probabilidades do servidor vLLM nunca correspondem exatamente às do treinador: kernels diferentes, uma precisão diferente e uma política alguns passos atrás (veja Lidando com a Divergência entre Treinamento e Inferência). O treinador usa as log-probabilidades do amostrador como a política antiga, de modo que uma única razão de importância cobre tanto a divergência quanto a obsolescência: 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})}.

Tokens cuja proporção fica fora de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] são descartados da perda. Para mais informações, consulte Masked Importance Sampling.

Por padrão (score_centering=True), o trainer usa Score Centering. Os pesos de importância sozinhos não removem o descompasso: a score ∇θlog⁡πθ \nabla_\theta \log \pi_\theta de um token amostrado não tem média zero sob o sampler μ \mu , portanto, cada atualização também puxa a política em direção ao sampler. O Score Centering subtrai essa expectativa em cada posição: ∇θ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)},

onde f(r)=r f(r) = r dentro de [Cmin⁡,Cmax⁡] [C_{\min}, C_{\max}] e 0 0 fora. A expectativa interna é calculada sobre os num_sampler_logprobs tokens mais prováveis em cada posição, solicitados pelo worker de rollout ao servidor.

Com score_centering=False, o trainer usa o objetivo substituto com recorte do GRPO, com a mesma razão mascarada: 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),

onde ϵlow \epsilon_{\text{low}} é epsilon e ϵhigh \epsilon_{\text{high}} é epsilon_high.

Em ambos os casos, a perda é normalizada pelo número de tokens treinados no micro-lote, contado em todos os processos, e média sobre os gradient_accumulation_steps micro-lotes de uma etapa.

Métricas registradas

Durante o treinamento, registramos as seguintes métricas:

  • num_tokens: O número total de tokens encaminhados até o momento, incluindo prompts e completions. Com tree packing, um prefixo compartilhado por várias amostras é contado uma única vez.
  • completions/mean_length: O comprimento médio das conclusões geradas. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/min_length: O comprimento mínimo das conclusões geradas. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/max_length: O comprimento máximo das conclusões geradas. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/mean_terminated_length: O comprimento médio das conclusões geradas que terminam com EOS. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/min_terminated_length: O comprimento mínimo das conclusões geradas que terminam com EOS. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/max_terminated_length: O comprimento máximo das completions geradas que terminam com EOS. Ao usar ferramentas, apenas os tokens que não são de ferramentas são contados.
  • completions/clipped_ratio: A proporção de conclusões truncadas (clipped), cuja última rodada não termina com um token EOS.
  • completions/duplicate_frac: A fração de rollouts que repetem um rollout anterior do seu grupo token por token. Veja Saturação e duplicados.
  • tools/call_frequency: O número médio de chamadas de ferramentas por conclusão, em todos os rollouts, incluindo os grupos que são descartados em seguida. Registrado apenas quando o trainer possui ferramentas.
  • tools/failure_frequency: A fração de chamadas de ferramenta que falharam (a ferramenta não foi encontrada ou lançou uma exceção), em relação a todas as chamadas de ferramenta, incluindo os grupos que são descartados em seguida. É NaN em uma janela de log sem nenhuma chamada de ferramenta, onde o GRPO registra 0.0. Registrado apenas quando o trainer possui ferramentas.
  • rewards/{reward_func_name}/mean: A recompensa média de uma função de recompensa específica, considerando todas as conclusões pontuadas, incluindo os grupos que são descartados em seguida. Quando um ambiente possui a recompensa por meio de get_reward, {reward_func_name} é o nome da classe do ambiente.
  • rewards/{reward_func_name}/group_std: O desvio padrão da recompensa de uma função de recompensa específica, calculado dentro de cada grupo e médio sobre as amostras treinadas.
  • reward: A recompensa média geral após somar as recompensas entre as funções, em todas as conclusões pontuadas, incluindo os grupos que são descartados em seguida. É a recompensa da política, portanto é a que deve ser acompanhada: reward_trained exclui os grupos cujas recompensas são todas iguais.
  • reward_group_std: O desvio padrão dos recompensas somadas entre as funções, calculado dentro de cada grupo e médio sobre as amostras treinadas. É por ele que a vantagem é dividida, ao contrário do reward_std do GRPO, que é calculado sobre o lote inteiro.
  • reward_trained: A recompensa média das amostras em que o treinador treinou. Ele exclui os grupos cujas recompensas são todas iguais e as amostras descartadas por exceder max_staleness.
  • reward_zero_std_groups: A recompensa média dos grupos cujas recompensas são todas iguais, que são descartados: a recompensa em que eles estão presos. Consulte Saturação e duplicados para ler isso junto com frac_zero_std_groups e reward.
  • frac_zero_std_groups: A fração de grupos com desvio padrão de recompensa igual a zero (todas as respostas estão corretas ou incorretas) ou com menos de duas conclusões pontuáveis. Esses grupos são descartados.
  • sampling/sampling_logp_difference/mean: A diferença absoluta média entre as probabilidades logarítmicas retornadas pelo amostrador (vLLM) e as recalculadas pelo modelo de treinamento, nos tokens treinados.
  • sampling/sampling_logp_difference/max: A maior diferença absoluta desse tipo.
  • sampling/importance_sampling_ratio/min: A menor razão de amostragem por importância ri,t(θ) r_{i,t}(\theta) entre o modelo e o amostrador, nos tokens treinados, antes que os tokens fora de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] sejam descartados.
  • sampling/importance_sampling_ratio/mean: A média da razão de importance sampling.
  • sampling/importance_sampling_ratio/max: A maior razão de amostragem de importância.
  • sampling/masked_mean: A fração de tokens treinados descartados da perda porque a razão de amostragem de importância deles fica fora de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max].
  • sampling/sampler_mass: A massa de probabilidade média coberta pelos num_sampler_logprobs tokens mais prováveis do sampler. Registrado apenas quando score_centering=True.
  • entropy: Entropia média das previsões de tokens entre os tokens treinados.
  • aux_loss: A perda auxiliar de balanceamento de carga de um modelo Mixture-of-Experts, antes de ser escalada por router_aux_loss_coef e adicionada à perda. Registrada apenas quando o modelo é um modelo MoE e router_aux_loss_coef é diferente de zero.
  • clip_ratio/region_mean: A proporção de probabilidades de tokens em que o objetivo do GRPO é limitado para permanecer dentro da região de confiança: clip(ri,t(θ),1−ϵlow,1+ϵhigh) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) . Com score_centering=True a perda não é limitada, portanto as clip_ratio/* métricas contam os tokens fora da região de confiança.
  • clip_ratio/low_mean: A proporção média das probabilidades de tokens que foram cortadas no limite inferior da região de confiança: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: A menor fração por conclusão de tokens recortados no limite inferior da região de confiança: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: A razão média das probabilidades de tokens que foram cortadas no limite superior da região de confiança: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: A maior fração por conclusão de tokens recortados no limite superior da região de confiança: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.

As outras métricas descrevem o pipeline assíncrono.

As métricas são registradas uma vez por janela de registro: tudo que foi registrado desde o último log, o que abrange os últimos logging_steps passos do otimizador. Ao longo da janela:

  • Uma média medida por rollout, amostra ou chamada, como reward, rollout/turns_mean e tools/latency_s, é calculada como a média de todos os rollouts, amostras ou chamadas na janela. Uma taxa, como rollout/generated_tokens_per_s, é o total de tokens dividido pelo total de segundos.
  • Caso contrário, um nome cuja última parte contém a palavra count é somado: sample/dropped_stale_count é o número de amostras descartadas desde o último log, não desde o início do treinamento.
  • Um nome cuja última parte contém a palavra max ou min, como sample/staleness_max ou completions/max_length, mantém o maior ou menor valor.
  • Qualquer outra métrica é a média dos valores registrados na janela.

Unidades:

  • _s: segundos.
  • tokens_per_s: tokens por segundo.
  • _frac: fração entre 0 e 1.
  • _per_step: quantidade em um passo do otimizador, média dos passos na janela.

Métricas de rollout

  • rollout/duration_s: O tempo real de um rollout, desde o despacho até o momento em que o loop de rollout o coleta.
  • rollout/generated_tokens_per_s: A taxa de geração, em tokens gerados por segundo, desde o relatório anterior.
  • rollout/concurrency: O número de rollouts em andamento para o servidor vLLM.
  • rollout/concurrency_cap: O limite atual de rollouts em andamento, que segue a carga do servidor. Consulte Concorrência.
  • rollout/turns_mean, rollout/turns_max: O número médio e máximo de turnos por rollout.
  • rollout/samples_per_rollout: O número de amostras de treinamento por rollout. Acima de 1.0, alguns rollouts foram ramificados; abaixo de 1.0, alguns não produziram nenhum token treinado. Veja Multi-turn rollouts.
  • rollout/fork_frac: A fração de transições de turno cujo prompt não começa com os tokens retidos, indicando que o turno iniciou uma nova amostra.
  • rollout/drift_tokens_mean, rollout/drift_tokens_max: O número de tokens retidos que um fork re-renderizou, em média, ao longo das transições de turno (aquele que não faz fork conta como 0). A nova amostra compartilha os tokens antes da divergência, portanto, é isso que cada fork adiciona ao forward.
  • rollout/score_queue_size: O número de grupos concluídos aguardando para serem pontuados.
  • rollout/queue_size: O número de amostras pontuadas aguardando na fila de rollout, medido no ponto em que o trainer as retira. Consulte A fila de rollout.
  • rollout/score_s: O tempo para pontuar um grupo.
  • rollout/score_wait_s: O tempo que um grupo concluído aguardou antes de ser pontuado.
  • rollout/score_block_s: O tempo em que a geração foi bloqueada porque a fila de pontuação estava cheia.
  • rollout/backpressure_s: O tempo que a geração esperou para iniciar um rollout porque estava max_staleness passos à frente do treinamento, em média sobre as esperas na janela de registro. Veja Concorrência.
  • rollout/vllm_retry_count: O número de solicitações vLLM repetidas. Um servidor degradado, caso contrário, parece apenas lentidão inexplicada.
  • rollout/vllm_kv_cache_usage_frac: O uso do cache KV do vLLM (máximo entre os motores), médio sobre as consultas na janela de registro.
  • rollout/vllm_running_requests: O número de solicitações que os motores do servidor estão decodificando (o num_requests_running do vLLM, somado entre os motores). A diferença em relação a rollout/concurrency corresponde ao que está no processo do servidor de API, montando as respostas.
  • rollout/vllm_queued_requests: O número de solicitações que o servidor aceitou, mas ainda não agendou (o num_requests_waiting do vLLM, somado entre os motores).
  • rollout/vllm_preemption_count: O número de solicitações que o servidor preemiu (o num_preemptions_total do vLLM, somado entre os motores). Uma sincronização de pesos redefine os caches do servidor, o que preempe toda solicitação em execução, portanto, isso não é um sinal de pressão.

Métricas da ferramenta

  • tools/latency_s, tools/{tool_name}/latency_s: O tempo gasto na execução de uma chamada de ferramenta, no total e por ferramenta.
  • tools/{tool_name}/call_count, tools/{tool_name}/failure_count: O número de chamadas e chamadas com falha por ferramenta.
  • tools/unknown_name_count: O número de chamadas a uma ferramenta que não existe. Diferentemente de uma ferramenta que foi executada e gerou uma exceção, este é um erro de política.
  • tools/parallel_calls_mean: O número médio de chamadas de ferramentas em uma mensagem de assistente que chama ferramentas.
  • tools/loop_exhausted_frac: A fração de rollouts interrompidos em max_tool_calling_iterations enquanto ainda estavam chamando ferramentas, sobre todos os rollouts, incluindo rollouts sem chamadas e os grupos que são descartados em seguida. Registrado apenas quando o trainer possui ferramentas.

HarnessAsyncGRPOTrainer registra a maioria desses com os mesmos nomes. Consulte Training on harnesses para as diferenças.

Métricas do ambiente

  • env/reset_s: O tempo gasto no reset() do ambiente antes do início de um rollout. Registrado apenas quando environment_factory é fornecido.
  • env/reward_s: O tempo gasto no get_reward() do ambiente após o término de um rollout. Registrado apenas quando o ambiente define get_reward.

Métricas de exemplo

  • sample/forwarded_tokens_mean, sample/forwarded_tokens_max: A média e o número máximo de tokens encaminhados por amostra.
  • sample/trained_tokens_mean: O número médio de tokens treinados por amostra.
  • sample/time_in_queue_s: O tempo que uma amostra ficou na fila de rollout antes de ser usada no treinamento.
  • sample/staleness_mean, sample/staleness_max: O número de atualizações de pesos entre a política que gerou uma amostra e a política que está treinando com ela. As métricas sampling/importance_sampling_ratio/* e sampling/sampling_logp_difference/* combinam essa obsolescência com a divergência entre treinamento e inferência: uma razão diferente de 1.0 ou uma diferença de log-probabilidade diferente de 0.0 com obsolescência zero indica a divergência, por exemplo, uma diferença de dtype com o servidor.
  • sample/dropped_stale_count: O número de amostras descartadas por exceder max_staleness.

Métricas de lote

  • batch/forwarded_tokens_per_step, batch/trained_tokens_per_step: O número de tokens encaminhados e treinados por etapa, em todos os processos.
  • batch/samples_per_step, batch/groups_per_step: O número de amostras e de grupos distintos por etapa. Eles diferem pelo número de amostras por grupo.
  • batch/microbatches_per_step: O número de micro-lotes por etapa.
  • batch/masked_token_frac: A fração de tokens encaminhados que não são treinados.
  • batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max: O número de amostras por linha, e a média e o máximo de tokens encaminhados por linha.
  • batch/row_fill_frac: A fração de token_budget que as linhas utilizam.
  • batch/row_imbalance: A razão entre o custo de atenção da linha mais cara e o custo médio. O processo com a linha mais cara faz os outros pararem no all-reduce de gradiente; 1.0 representa equilíbrio perfeito.
  • batch/packing_ratio: O número de tokens antes do empacotamento por token encaminhado: o fator pelo qual o empacotamento reduz o encaminhamento, 1.0 quando nada é compartilhado.
  • batch/pad_frac: A fração de padding adicionada para tornar as linhas do mesmo comprimento. Isso apenas custa transferência e é removido antes do forward.
  • batch/dropped_oversize_count: O número de amostras descartadas por exceder o token_budget.

Métricas de desempenho

  • perf/step_s: O tempo real de uma etapa, incluindo o otimizador, a sincronização dos pesos e o tempo de espera por amostras.
  • perf/fwd_bwd_s, perf/fwd_s: O tempo gasto nas passadas de forward e backward de um passo, e apenas nas passadas de forward.
  • perf/optimizer_s: O tempo gasto na etapa do otimizador.
  • perf/rollout_wait_s: O tempo em que o treinamento ficou aguardando porque a fila de rollout estava vazia. Veja A fila de rollout.
  • perf/weight_sync_s: O tempo de uma sincronização de pesos, dividido em perf/weight_sync_pause_s (aguardando o vLLM pausar), perf/weight_sync_barrier_s (aguardando os outros processos) e perf/weight_sync_transfer_s (enviando os pesos).
  • perf/fwd_bwd_forwarded_tokens_per_s, perf/wall_clock_forwarded_tokens_per_s: O número de tokens encaminhados por segundo, ao longo das passadas de forward e backward ou ao longo de toda a etapa.
  • perf/wall_clock_trained_tokens_per_s: O número de tokens treinados por segundo, ao longo de toda a etapa.
  • perf/fwd_bwd_mfu, perf/wall_clock_mfu: A utilização de FLOPs do modelo nos dispositivos de treinamento, ao longo das passadas de forward e backward ou ao longo de toda a etapa. Eles excluem o servidor vLLM. Registrados apenas quando o pico de computação do dispositivo de treinamento na precisão de treinamento é conhecido e quando a estimativa de FLOPs suporta a arquitetura do modelo (como Llama, Qwen2, Qwen3, Qwen3-MoE ou Qwen3-VL).

Personalização

Configurando o servidor vLLM

O trainer gera com um servidor vLLM, ao qual ele se conecta em vllm_server_base_url (padrão: 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 e --weight-transfer-config expõem os endpoints pelos quais o trainer envia seus pesos.
  • --logprobs-mode processed_logprobs faz o servidor retornar as log-probabilidades da distribuição da qual ele amostrou, após a aplicação de temperature e top-k/top-p, que é o que a razão de importância compara.
  • --api-server-count 8 mantém as principais log-probabilidades, o que torna as solicitações de centralização de pontuação baratas de atender (veja o aviso abaixo).
  • --max-model-len é o comprimento máximo total da sequência (prompt e conclusão) que você espera. Um valor menor reduz o uso de memória de GPU no servidor, liberando mais memória para o cache KV e aumentando o throughput. Um bom ponto de partida é o comprimento do prompt mais max_completion_length da sua configuração. Com ferramentas, cada turno adiciona até max_completion_length tokens mais os resultados das ferramentas, então defina-o para a conversa mais longa que você espera. Se o prompt de um turno mais max_completion_length for maior que --max-model-len, o servidor rejeita a solicitação e a execução para com o erro do servidor. Com top_k ou top_p, o servidor, em vez disso, para aquele turno quando atinge --max-model-len e rejeita apenas um prompt que já tenha esse comprimento. Ele também é o token_budget padrão.

Certifique-se de que o servidor está usando GPUs diferentes das do trainer; caso contrário, você pode encontrar erros do NCCL. Você pode especificar as GPUs a serem usadas com a variável de ambiente CUDA_VISIBLE_DEVICES.

A serialização das principais log-probabilidades é um trabalho de CPU no servidor de API do vLLM, e, com o valor padrão de num_sampler_logprobs=8 para um único servidor de API, o throughput de geração é reduzido pela metade. Inicie o servidor com --api-server-count 8 no vLLM 0.32 ou posterior: medido em uma H100 com modelos de 1,5B a 7B, as principais 8 log-probabilidades passam a custar menos de 3% do throughput de geração. No vLLM 0.31, a mesma flag ainda deixa uma perda de 20 a 40%, corrigida no upstream por vllm-project/vllm#58181.

Concorrência

Três limites determinam quantos rollouts são executados simultaneamente. Os dois primeiros se adaptam automaticamente; o terceiro é definido por você.

Obsolescência. max_staleness define quantos passos de treinamento a geração pode ficar à frente do treinador. O worker rastreia isso em tokens, pois o número de amostras em um passo muda conforme as conclusões ficam mais longas ou mais curtas. Após cada passo, o treinador conta os tokens que utilizou e permite que o worker mantenha na fila ou em andamento até max(max_staleness, 1) vezes essa quantidade de tokens. Antes do primeiro passo, ele assume que cada linha está completa. O worker inicia um novo grupo de rollouts apenas enquanto estiver abaixo desse limite. No início, ele ainda não sabe quantos tokens um rollout produz, então inicia um grupo de cada vez até que o primeiro grupo termine. Uma amostra que ainda assim ficar com mais de max_staleness passos de obsolescência é descartada.

Carregamento do vLLM. Enviar muitas solicitações ao vLLM de uma vez só o torna mais lento: o cache de KV fica cheio e o vLLM precisa pausar e refazer algumas solicitações. Por isso, o worker também mantém um limite dinâmico de quantos rollouts rodam simultaneamente, registrado como rollout/concurrency_cap, e verifica o /metrics do servidor a cada 5 segundos para ajustá-lo. O limite começa no número de solicitações que cabem no cache de KV em comprimento total (KV cache tokens / max_model_len), para que o servidor não fique sobrecarregado no início. Enquanto o uso do cache de KV ficar abaixo de 60% e não houver solicitações aguardando, o limite aumenta em 25%, no máximo uma vez por cada lote de rollouts finalizados equivalente ao limite atual. Quando o uso ultrapassa 80%, o limite diminui em 30%: as solicitações em andamento continuam, e as novas ficam aguardando. Se o servidor não tiver um endpoint /metrics, o limite é max_concurrent_rollouts.

Recursos. max_concurrent_rollouts (padrão 512) é o limite superior de rollouts executados simultaneamente. É o único limite que você define, pois o trainer não consegue ver o que seus ambientes e ferramentas conseguem processar. Cada rollout em execução usa um ambiente, pode executar chamadas de ferramentas síncronas em uma thread pool desse tamanho e mantém uma conexão aberta com o servidor vLLM. Defina-o para o que esses componentes conseguem processar, por exemplo, o número de sessões que seu servidor de ambiente aceita:

from trl import AsyncGRPOConfig

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

Se for muito baixo, a geração fica mais lenta. Um rollout mantém seu slot enquanto executa ferramentas ou aguarda entre as turnos, não apenas enquanto o vLLM gera, portanto, rollouts que chamam muitas ferramentas precisam de mais slots para manter o vLLM ocupado. Se for muito maior que o padrão, o servidor vLLM pode começar a descartar conexões.

As métricas registradas mostram qual limite está impedindo a geração:

  • rollout/backpressure_s acima de zero: o limite de obsolescência. A geração está à frente do treinamento, o que é esperado quando a inferência é mais rápida que o treinamento.
  • rollout/concurrency em rollout/concurrency_cap, abaixo de max_concurrent_rollouts: a carga do servidor vLLM.
  • rollout/concurrency em max_concurrent_rollouts, com baixo rollout/vllm_kv_cache_usage_frac e alto perf/rollout_wait_s: o limite. Aumente max_concurrent_rollouts se seus ambientes e ferramentas permitirem.

A fila de rollout

O worker envia amostras pontuadas para uma fila e o trainer as retira dela. Quatro métricas descrevem essa fila:

  • rollout/queue_size: quantas amostras estão aguardando.
  • sample/time_in_queue_s: quanto tempo uma única amostra ficou aguardando antes de ser usada no treinamento, a parte de tempo de sua obsolescência.
  • perf/rollout_wait_s: quanto tempo o treinamento ficou aguardando porque a fila estava vazia.
  • rollout/backpressure_s: quanto tempo a geração esperou porque estava max_staleness passos à frente do treinamento.

Os dois últimos são imagens espelhadas. Lidos em conjunto com o tamanho da fila, eles indicam qual lado é o gargalo:

  • fila quase vazia, perf/rollout_wait_s alto: limitado pela geração. O treinador está com falta de dados; verifique rollout/generated_tokens_per_s, rollout/concurrency e rollout/score_queue_size.
  • fila contendo cerca de max_staleness passos de tokens, rollout/backpressure_s alto: limitado pelo trainer. A geração é retardada e sample/staleness_mean fica próximo do seu limite.
  • ambos altos: o próprio limite de max_staleness é muito restrito. Os rollouts em andamento o preenchem antes que suas amostras alcancem a fila, fazendo com que o trainer espere enquanto a geração é retida. Aumente max_staleness.
  • ambos próximos de zero: equilibrado.

Saturação e duplicados

A política aprende a partir das diferenças entre os rollouts de um grupo: cada vantagem é calculada em relação à recompensa média do grupo. Quando todos os rollouts de um grupo recebem a mesma recompensa, todos obtêm uma vantagem zero, de modo que o grupo é descartado (veja Métricas registradas) e não ensina nada à política. À medida que uma execução satura, cada vez mais grupos terminam assim, seja porque todos os rollouts resolvem o prompt ou porque nenhum o faz. Quatro métricas distinguem esses casos, e cada uma responde à sua própria pergunta, para que você possa lê-las diretamente de seus gráficos:

métricapergunta
frac_zero_std_groupsque proporção dos grupos não carrega nenhum sinal
reward_zero_std_groupsonde esses grupos estão parados: sua recompensa média. Com recompensas 0/1, é a proporção deles em que todos os rollouts passaram, então 0,9 significa que quase todos foram resolvidos, e 0,1 que quase todos falham em todos os rollouts
rewardo quão bem a política se comporta em todos os grupos pontuados, incluindo os descartados
completions/duplicate_fracse a amostragem ainda gera desdobramentos diferentes para o mesmo prompt

Leia os três primeiros juntos, em relação à faixa da sua recompensa:

frac_zero_std_groupsreward_zero_std_groupsrewarddiagnósticoo que fazer
baixoqualquer (ruidoso em poucos grupos)qualquersaudável: a maioria dos grupos produz um gradientenada
subindopróximo ao topo da faixasubindosaturando no topo: os prompts ficaram fáceis demais para a política, o que é como uma execução bem-sucedida geralmente terminainterrompa a execução ou passe para prompts mais difíceis
altopróximo do limite inferior da faixabaixo e planopreso no fundo: os prompts são difíceis demais, ou a função de recompensa nunca dá créditoVerifique primeiro completions/clipped_ratio, pois uma conclusão cortada antes da resposta recebe nota 0, e depois leia algumas conclusões para verificar se a função de recompensa as interpreta corretamente
subindocaircairregression: grupos que antes passavam agora falham juntosverifique completions/duplicate_frac e entropy para detectar um colapso
altono meioqualqueruma mistura: com recompensas 0/1, alguns prompts são fáceis demais e outros difíceis demais. Com recompensas de crédito parcial, os grupos também podem ficar presos na mesma pontuação parcialler os rollouts

completions/duplicate_frac é a proporção de rollouts que repetem um rollout anterior do seu grupo, token por token, em todas as suas turnos. Rollouts idênticos recebem recompensas idênticas, portanto, duplicatas também aumentam frac_zero_std_groups.

completions/duplicate_fracdiagnóstico
próximo de 0, com uma pequena linha de base em tarefas cujas conclusões são curtas o suficiente para serem repetidas por acasohealthy: os rollouts de um grupo são amostrados de forma independente
salta para (num_generations - 1) / num_generationsa amostragem não é mais aleatória: cada grupo retorna como cópias de um único rollout. Por exemplo, uma temperatura de 0, ou motores vLLM paralelos de dados decodificando o mesmo texto porque compartilham uma semente de amostragem (o worker envia uma semente única com cada solicitação para evitar isso)
sobe lentamente, com a entropy caindocolapso: a política está convergindo para uma única resposta por prompt

Essas métricas são registradas quando o worker pontua um grupo, e não quando seus samples são treinados, portanto, elas avançam ligeiramente em relação ao treinamento e incluem grupos cujos samples são posteriormente descartados por exceder max_staleness. Um grupo em que nenhum rollout pôde ser pontuado, porque todas as funções de recompensa retornaram None, é descartado e contabilizado em frac_zero_std_groups, mas, como não possui recompensa, reward_zero_std_groups não o inclui.

Empacotamento de árvores

As amostras de um micro-lote são empacotadas em uma linha por processo, sem padding. Uma linha é uma prefix trie, não uma concatenação: um token compartilhado por várias amostras é encaminhado uma única vez, e a atenção ainda mostra a cada amostra exatamente o seu próprio histórico. Os rollouts de um grupo repetem todos o seu prompt, e cada turno de um rollout multi-turno repete a conversa até aquele ponto, de modo que o forward diminui pela razão de empacotamento (batch/packing_ratio). Trata-se apenas de uma mudança de layout: cada token treinado mantém seu próprio alvo, vantagem e antiga log-verossimilhança, e sua log-verossimilhança corresponde ao encaminhamento da amostra isoladamente.

Em dois rollouts de um prompt, onde p é o prompt e a, b as duas conclusões:

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

Algumas consequências:

  • Qualquer prefixo comum é compartilhado: os rollouts de um prompt e, entre prompts, um prompt de sistema ou um esquema de ferramenta comum. Uma amostra vai para a linha que já contém seu grupo, onde seu prompt já está. Quando essa linha está cheia, a amostra vai para outra linha se um processo ainda tiver uma vazia, ou se isso não aumentar a linha mais carregada, que define o tempo do micro-lote; caso contrário, o micro-lote é fechado.
  • Nada compartilhado é empacotamento simples: cada amostra se torna seu próprio segmento, o que é um empacotamento sem preenchimento comum.
  • Somente K/V é duplicado: um prefixo compartilhado é coletado uma vez por segmento descendente, o que é aproximadamente o que o treinamento descompactado manteria, e é pequeno com atenção de consulta agrupada.
  • Híbridos Gated DeltaNet são suportados (Qwen3.5, Qwen3.6, Qwen3-Next, …): a convolução deles lê os próprios antecessores de cada token, e a regra delta em blocos inicia cada segmento a partir do estado final do seu pai.

token_budget limita os tokens de uma linha, contando um token compartilhado apenas uma vez. Por padrão, é o max_model_len do servidor, portanto nenhuma amostra pode excedê-lo. Sem nada compartilhado, o tree packing roda com uma velocidade aproximada à do packing simples sem padding, e a aceleração cresce aproximadamente com a razão de packing (cerca de 2,8 a 3x com uma razão de 3,4 no Qwen3-0.6B e 1.7B, em H100). A razão é o prefixo compartilhado vezes as amostras por linha, então batch/samples_per_row é o principal indicador: próximo de 1, nada pode ser compartilhado, e o parâmetro de ajuste é token_budget. batch/row_fill_frac é importante quando as amostras são longas: uma amostra de 10k tokens preenche mal um orçamento de 32k (três cabem, quatro nunca cabem, então o planejador frequentemente obtém duas e a linha fica cerca de 77% cheia), enquanto amostras de 1k token preenchem-no quase perfeitamente.

Avalie o tree packing pelo throughput, batch/trained_tokens_per_step / perf/fwd_bwd_s. Um micro-batch empacotado contém mais amostras, portanto perf/fwd_bwd_s aumenta e perf/fwd_bwd_mfu, que divide pelos tokens encaminhados, diminui: nenhum dos dois é uma regressão. Mais amostras por linha também significam mais rollouts extraídos por passo, de modo que uma execução limitada pela geração se torna ainda mais limitada.

As métricas de lote são compostas da seguinte forma: um passo contém gradient_accumulation_steps × num_processes linhas, portanto batch/samples_per_step é aproximadamente esse número de vezes batch/samples_per_row, e o mesmo vale para tokens. Os dois lados concordam apenas até a variação entre os micro-lotes de um passo, pois as métricas por passo são somas e as por linha são médias.

Qualquer coisa que torne as linhas mais longas ou mais escassas remove o compartilhamento. Uma conversa de múltiplas rodadas que nunca se ramifica é uma única amostra longa, e rollout/samples_per_rollout indica quantas amostras uma conversa gera.

Amostragem top-k e top-p

Top-k e top-p renormalizam a distribuição de amostragem sobre um conjunto de candidatos restrito, em vez de sobre o vocabulário inteiro. As log-probabilidades do servidor refletem isso (--logprobs-mode processed_logprobs), portanto o trainer precisa normalizar sobre o mesmo conjunto; caso contrário, todas as razões de importância ficam enviesadas: a probabilidade de um token sob o vocabulário inteiro é menor do que sob o conjunto de candidatos do qual ele foi extraído (DeepSeek-V3.2, seção 3.1). Com top_p < 1 ou top_k > 0, o worker solicita ao servidor o conjunto de candidatos de cada token amostrado e o trainer renormaliza suas log-probabilidades sobre esse conjunto. Isso requer duas flags adicionais no servidor, e top_k precisa ser definido, pois o vLLM limita o tamanho do conjunto de candidatos com ele:

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 faz o vLLM registrar o conjunto de candidatos (vLLM 0.28 ou posterior, em seu V2 model runner: VLLM_USE_V2_MODEL_RUNNER=1 se o servidor recusar a flag), e --enable-scale-out expõe o endpoint token-in-token-out que o retorna. O worker verifica ambos no servidor quando inicia. Um vLLM mais antigo não consegue retornar o conjunto, então o trainer continua normalizando sobre o vocabulário inteiro e emite um aviso sobre a razão enviesada.

Treine adaptadores com PEFT

Suportamos integração estreita com a biblioteca 🤗 PEFT, permitindo que você treine adaptadores e os compartilhe no Hub, em vez de treinar o modelo inteiro.

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()

Cada sincronização de pesos precisa enviar a política atualizada para o servidor. Por padrão, o trainer mescla o adaptador no modelo base e envia os pesos completos mesclados, o que é cerca de 15 GB para um modelo de 7B em cada sincronização. Inicie o servidor vLLM com --enable-lora e ele enviará apenas o adaptador, cerca de 160 MB em 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 expõe o endpoint para o qual o trainer envia cada novo adapter. Mantenha --weight-transfer-config mesmo com --enable-lora: o trainer só escolhe um modo de sincronização quando inicia, momento em que o servidor já está ativo, e a sincronização mesclada é o fallback.

--max-lora-rank deve ser um dos valores 1, 8, 16, 32, 64, 128, 256, 320, 512. Ele define o rank máximo que o servidor pode atender, e não o rank que ele efetivamente servirá, portanto um adaptador r=4 funciona perfeitamente sob 8. --max-loras deve ser pelo menos max_staleness + 2: o trainer mantém max_staleness + 1 versões de adaptador registradas para que um rollout iniciado sob uma política mais antiga possa ser concluído sob ela, em vez de trocar de política no meio da geração, e cada sincronização carrega a próxima versão antes de descarregar a mais antiga. O trainer verifica ambos os valores ao iniciar e informa com quais valores reiniciar o servidor.

O vLLM carrega adaptadores do disco em vez da rede, portanto o trainer grava cada versão em <output_dir>/.vllm_lora/ e fornece o caminho ao servidor. Se o servidor estiver em uma máquina diferente, esse diretório precisa estar em um sistema de arquivos visível para ambos.

<output_dir>/.vllm_lora/ é um cache de serviço, não o local onde o seu adaptador treinado é armazenado. Ele apenas mantém as versões mais recentes, e cada uma é excluída pouco depois de sair da janela de obsolescência. Os checkpoints são o que preservam o adaptador que você treinou, portanto, não os desative: com save_strategy="no", uma execução de várias horas termina e não deixa nada para trás. O output_dir também precisa ser legível pelo servidor e precisa sobreviver ao término do job, portanto, um armazenamento temporário local do nó não funcionará, mesmo que isso mantivesse as sincronizações fora de um sistema de arquivos compartilhado lento.

A sincronização de adaptadores nem sempre é mais rápida. O vLLM gera tokens cerca de 1,33 a 1,39 vezes mais devagar ao servir um adaptador LoRA do que ao servir pesos mesclados, e a geração geralmente é o que domina o tempo real de execução em RL. Em contrapartida, você obtém uma pausa muito mais curta em cada sincronização e cerca de 1% da largura de banda de sincronização. Se o throughput de geração for o seu gargalo, a sincronização mesclada ainda costuma ser a melhor escolha.

Usando uma função de recompensa personalizada

O AsyncGRPOTrainer suporta o uso de funções de recompensa personalizadas. Para garantir compatibilidade, sua função de recompensa deve atender aos seguintes requisitos:

As funções de recompensa podem ser chamadas síncronas em Python ou corrotinas assíncronas async def. Quando você fornece várias funções de recompensa, elas são executadas de forma concorrente: as assíncronas são aguardadas juntas e as síncronas são executadas em threads, de modo que suas latências se sobrepõem.

  1. Argumentos de entrada:

    • A função deve aceitar os seguintes argumentos como palavras-chave:

      • prompts (contém os prompts),
      • completions (contém as completions geradas),
      • completion_ids (contém as conclusões tokenizadas),
      • Todos os nomes de colunas (exceto prompt) que o conjunto de dados pode ter. Por exemplo, se o conjunto de dados contiver uma coluna chamada ground_truth, a função será chamada com ground_truth como argumento de palavra-chave.

      A maneira mais fácil de atender a esse requisito é usar **kwargs na assinatura da função.

    • O conjunto de dados está em formato conversacional, portanto prompts e completions são listas de dicionários de mensagens.

  2. Valor de retorno: A função deve retornar uma lista de floats. Cada float representa a recompensa correspondente a uma única conclusão.

As funções de recompensa são executadas no worker de rollout, um processo separado, portanto, tudo o que é passado a ele é serializado (pickled). Cada função de recompensa, ferramenta e environment_factory (e qualquer coisa que eles encapsulem) deve ser serializável: use uma função em nível de módulo, functools.partial ou uma instância de classe chamável. Lambdas e closures geram um TypeError em trainer.train(). Esta é uma diferença em relação ao GRPOTrainer, onde as funções de recompensa são chamadas no processo e os closures funcionam.

O processo de rollout também é executado com CUDA_VISIBLE_DEVICES="", portanto não pode usar a GPU. Um modelo de recompensa baseado em GPU (por exemplo, um avaliador AutoModelForSequenceClassification) é carregado sem erro, mas faz fallback silenciosamente para a CPU. Mantenha as funções de recompensa leves (verificadores como accuracy_reward, verificações de formato ou comprimento). Se você precisar de um modelo de recompensa em GPU, sirva-o por trás de seu próprio mecanismo de inferência (vLLM, TGI, …) em GPUs separadas e faça com que uma função de recompensa picklable o chame via HTTP.

Exemplo 1: Recompensar conclusões mais longas

Abaixo está um exemplo de uma função de recompensa que recompensa conclusões mais longas:

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]

Você pode testá-lo da seguinte forma:

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

Exemplo 2: Recompensar conclusões com um formato específico

Abaixo está um exemplo de uma função de recompensa que verifica se a conclusão possui um formato específico. Este exemplo é inspirado na função format reward usada no artigo DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Ele foi projetado para um formato conversacional, em que os prompts e as conclusões consistem em mensagens estruturadas.

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]

Você pode testar esta função da seguinte forma:

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

Exemplo 3: Recompensar conclusões com base em uma referência

Abaixo está um exemplo de uma função de recompensa que verifica se a conclusão está correta. Este exemplo é inspirado na função de recompensa de precisão usada no artigo DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. O conjunto de dados contém uma coluna chamada 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)]

Você pode testar esta função da seguinte forma:

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

Exemplo 4: Funções de recompensa multitarefa

Abaixo está um exemplo de uso de múltiplas funções de recompensa no AsyncGRPOTrainer. Neste exemplo, definimos duas funções de recompensa específicas para tarefas: math_reward_func e coding_reward_func. A math_reward_func recompensa problemas de matemática com base na sua correção, enquanto a coding_reward_func recompensa problemas de programação com base em se a solução funciona.

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()

Neste exemplo, o math_reward_func e o coding_reward_func são projetados para funcionar com um conjunto de dados misto que contém problemas de matemática e de programação. A coluna task no conjunto de dados é usada para determinar qual função de recompensa aplicar a cada problema. Se não houver uma função de recompensa relevante para uma amostra no conjunto de dados, a função de recompensa retornará None, e o AsyncGRPOTrainer continuará com as funções e tarefas válidas. Isso permite que o AsyncGRPOTrainer lide com múltiplas funções de recompensa com diferentes aplicabilidades.

Observe que o AsyncGRPOTrainer ignorará as recompensas None retornadas pelas funções de recompensa e considerará apenas as recompensas retornadas pelas funções relevantes. Isso garante que o modelo seja treinado nas tarefas relevantes e ignore as tarefas para as quais não há uma função de recompensa relevante.

Exemplo 5: Funções de recompensa assíncronas

Funções de recompensa personalizadas também podem ser definidas como corrotinas async def. Isso é útil se a sua recompensa depender de I/O lento (por exemplo, chamar um serviço remoto). Quando você passa várias funções de recompensa assíncronas, o AsyncGRPOTrainer as executa de forma concorrente, de modo que a latência delas se sobrepõe.

Abaixo está um exemplo mínimo de uma função de recompensa assíncrona que simula uma operação limitada por E/S:

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]

Passando a função de recompensa para o treinador

Para usar sua função de recompensa personalizada, passe-a para o AsyncGRPOTrainer da seguinte forma:

from trl import AsyncGRPOTrainer

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

Você pode passar várias funções de recompensa como uma lista; essa lista pode incluir tanto funções síncronas quanto assíncronas:

from trl import AsyncGRPOTrainer

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

e a recompensa será calculada como a soma das recompensas de cada função.

Personalizando o loop de rollout

A geração, as recompensas, as vantagens e o filtragem são executados no processo de rollout, em AsyncRolloutLoop. Para alterar um deles, crie uma subclasse do loop, sobrescreva o método correspondente àquele passo e defina a subclasse como loop_cls em uma subclasse do trainer. O construtor do trainer não muda.

MétodoChamadoPadrão
filter_prompt(row_index, row, epoch)uma vez por prompt, antes da geraçãoaceita todos os prompts
generate_one(prompt, tools, group_id)uma vez por rollouto loop de ferramentas de múltiplas rodadas
generate_one_turn(prompt_ids)uma vez por solicitação de amostragemuma solicitação vLLM com as configurações de amostragem da config
compute_advantages(group)uma vez por grupo, depois que as recompensas são somadas em group.rewardsrecompensa padronizada dentro do grupo
setup(), close()quando os loops começam e paramnada

Por exemplo, um currículo que para de amostrar prompts que a política já resolve, com seu limiar em uma subclasse de configuração:

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

As recompensas são somadas sobre reward_funcs, ambientes que definem get_reward e o reward que um generate_one personalizado define em seu Rollout: para pontuar com um juiz, passe uma função de recompensa assíncrona, ou pontue dentro de generate_one. compute_advantages é executado para cada grupo, incluindo aquele que é descartado em seguida porque todas as suas recompensas pontuadas são iguais; o descarte considera as recompensas, não as vantagens. O loop é construído em um processo iniciado, então defina a subclasse no nível do módulo e mantenha o código de treinamento sob if __name__ == "__main__":. Crie os clientes em setup, que é executado no loop de eventos do loop, em vez de sobrescrever __init__. Um prompt que filter_prompt rejeita é ignorado para aquela época e conta para ela, assim como um grupo descartado. Se ele rejeitar todos os prompts de uma época, o loop levanta uma exceção.

Retomando de um checkpoint

O Trainer base retoma o treinamento pulando e reproduzindo os lotes nos quais já treinou, o que não se aplica a uma fila de rollout ao vivo, portanto ignore_data_skip é sempre True. Em vez disso, o índice do primeiro prompt ainda não treinado é salvo em rollout_state.json junto com cada checkpoint e restaurado na retomada, de modo que o worker avança rapidamente até esse prompt sem reproduzir amostras. Trata-se da posição trained, e não da posição do gerador: o worker opera à frente do treinamento pela profundidade da fila de rollout, e essas amostras em buffer são perdidas quando a execução termina, de modo que retomar a partir da posição do gerador pularia prompts que foram gerados, mas nunca treinados. Conjuntos de dados em streaming (IterableDataset) não podem ser reposicionados, portanto seu worker reinicia a partir do primeiro prompt na retomada.

Treinamento de Agentes

O GRPO assíncrono suporta treinamento de agentes: o modelo chama ferramentas durante a geração e aprende com o resultado.

  • Uma ferramenta é uma função Python simples (síncrona ou assíncrona) exposta ao modelo. Use tools para chamadas sem estado (uma calculadora, uma busca na web).
  • Um environment é a forma mais geral: um objeto com estado, criado do zero para cada rollout, cujos métodos públicos são expostos como ferramentas, além de um hook de ciclo de vida reset e um get_reward opcional que permite que ele possua a recompensa. Use environment_factory quando precisar de estado por rollout, de um hook de reset ou de recompensa gerenciada pelo environment.

Elas se compõem — você pode passar tools independentes junto com um environment_factory.

Ferramentas

O argumento tools espera uma lista de funções Python (síncronas ou assíncronas) que definem as ferramentas disponíveis para o agente:

from trl import AsyncGRPOTrainer

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

Cada ferramenta deve ser uma função Python padrão com argumentos e tipos de retorno com type hints, além de uma docstring no estilo Google descrevendo seu propósito, argumentos e valor de retorno. Para mais detalhes, consulte o Guia de passagem de ferramentas.

O modelo chama uma ferramenta pelo seu nome, portanto cada ferramenta é registrada sob seu __name__ e deve ser uma função de nível de módulo, o que também a mantém picklable para o worker de rollout. Ferramentas síncronas são executadas em uma thread pool dimensionada para max_concurrent_rollouts, de modo que uma ferramenta lenta nunca bloqueia os outros rollouts em andamento. Dentro de um turno do assistente, as chamadas de ferramenta são executadas na ordem em que o modelo as emitiu. Portanto, até max_concurrent_rollouts ferramentas síncronas podem ser executadas simultaneamente, de modo que uma ferramenta que lê ou escreve estado compartilhado deve ser thread-safe.

O loop de chamada de ferramentas exige que o modelo de chat seja preservador de prefixo (a adição de uma mensagem de ferramenta não deve alterar a forma como as mensagens anteriores são renderizadas). Para famílias de modelos conhecidas (por exemplo, Qwen3, DeepSeek-V3), o TRL substitui automaticamente o modelo de treinamento por um modelo corrigido quando as ferramentas estão habilitadas. Consulte Modelos de Chat para a lista completa.

Use max_tool_calling_iterations no AsyncGRPOConfig para limitar o número de turnos de chamada de ferramentas. Por padrão, não há limite, e a geração é interrompida quando o modelo produz um turno de resposta sem chamadas de ferramentas.

Exemplo:

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],
    ...,
)

Ambientes

Você também pode fornecer ferramentas por meio de environment_factory. Neste modo, o AsyncGRPOTrainer cria uma instância de ambiente por rollout e expõe os métodos públicos do ambiente como ferramentas.

Ao usar um environment_factory, o ambiente possui os dados: não há um train_dataset externo. Em cada rollout, reset() produz a tarefa — amostragem própria de um corpus mantido pelo ambiente, ou geração de um estado proceduralmente — e retorna o prompt. max_steps define o comprimento do treinamento. O seguinte é um exemplo mínimo de um ambiente que amostra um alvo e expõe um método increment (exposto como uma ferramenta).

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()

Uma classe de ambiente possui dois métodos reservados: reset e get_reward. Diferentemente de qualquer outro método público, esses não são expostos ao modelo como ferramentas.

  • reset (obrigatório) é chamado quando o rollout começa. Ele pode retornar None ou uma string. Quando retorna uma string, essa string é o prompt do usuário.
  • get_reward (opcional, síncrona ou assíncrona) não recebe argumentos e retorna um float: o ambiente pontua o episódio que acabou de executar com base no seu próprio estado interno (o jogo terminou em uma vitória? a palavra foi adivinhada?). É chamada uma vez por rollout concluído e atua como fonte de recompensa.

Ambos são executados na pool de threads de ferramentas do worker, portanto, um ambiente lento atrasa apenas o seu próprio rollout, mas não os outros em andamento. Suas durações são registradas como env/reset_s e env/reward_s.

Como o ambiente realiza a autoamostragem a cada reset(), os G membros de um grupo GRPO podem não compartilhar o mesmo estado inicial, tornando a linha de base do grupo ligeiramente mais ruidosa. Para estados idênticos dentro de um grupo, faça com que reset() derive o estado deterministicamente a partir de uma chave compartilhada.

Fornecendo um conjunto de dados externo (opcional)

Em vez de deixar que o ambiente faça a amostragem por conta própria, você pode fornecer um train_dataset externo. Por exemplo, quando suas tarefas já estão em um dataset, ou para rotear entre múltiplos ambientes. Por rollout, o trainer amostra uma linha, usa sua coluna "prompt" como o prompt e passa as colunas da linha para reset() como argumentos de palavra-chave (para que o ambiente leia a tarefa do dataset).

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()

Recompensas

Recompensas controladas pelo ambiente e recompensas controladas pelo treinador não são exclusivas. Passe reward_funcs para recompensas que são naturais de calcular a partir da conclusão (por exemplo, uma verificação de formato no texto) e deixe o ambiente retornar sua recompensa dependente do estado por meio de get_reward. Todas as fontes são somadas com peso 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`
)

Vários ambientes

Para treinar em uma mistura de tarefas em uma única execução (por exemplo, uma tarefa de codificação e um jogo), passe um dicionário que mapeia nomes de ambientes para fábricas, em vez de um único chamável. Cada rollout seleciona seu ambiente por meio de um campo environment no conjunto de dados, e somente as ferramentas daquele ambiente são expostas. Isso evita vazar ferramentas irrelevantes (a ferramenta move do jogo para um exemplo de codificação, e vice-versa). Cada ambiente ainda possui seus próprios dados e retorna o prompt de reset(), de modo que o conjunto de dados precisa apenas da coluna environment para rotear entre eles.

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()

As instâncias de ambiente são reutilizadas entre etapas (reiniciadas entre episódios), de modo que um __init__ caro é pago uma vez, em vez de a cada etapa. O campo environment é consumido pelo treinador e não é encaminhado para reset.

Rollouts de múltiplas rodadas

A cada turno, a conversa inteira é renderizada por meio do chat template e a geração é feita a partir dela. Um chat template nem sempre renderiza uma conversa em crescimento da mesma forma (alguns, por exemplo, descartam o raciocínio de turnos anteriores), de modo que os tokens de prompt de um turno podem diferir dos tokens mantidos até o momento. Ao final do rollout, o worker reconcilia os turnos em amostras de treinamento: um turno cujo prompt começa com os tokens mantidos é anexado à mesma amostra, e qualquer outro turno inicia uma nova. Cada token gerado é treinado em exatamente uma amostra, de modo que um fork custa tokens de forward, mas não gera sinal de treinamento.

Cada amostra de um rollout recebe a vantagem do rollout. rollout/fork_frac e rollout/drift_tokens_* mostram como as rodadas foram reconciliadas.

Integrações de Ambiente

Para treinar agentes que executam dentro de seu próprio harness, como agentes de codificação em sandboxes do Harbor, consulte Training on harnesses no guia do OpenEnv.

Treinando Modelos de Visão e Linguagem

Modelos de visão-linguagem (Qwen3.5, Qwen3.6, Qwen3-VL, …) podem ser treinados em conjuntos de dados de apenas texto. Passe o id do modelo como de costume; nada mais muda.

A torre de visão está congelada. Um conjunto de dados apenas de texto nunca gera tokens de imagem, portanto a torre nunca é exercitada pela passagem direta. Tudo fora do modelo de texto (torre de visão, projetor multimodal) tem requires_grad=False: não recebe gradientes nem estado do otimizador, e a sincronização de pesos o ignora, de modo que o servidor mantém os valores carregados do checkpoint. A torre ainda é carregada, então consome memória de GPU para seus pesos.

Imagens ainda não são suportadas. Prompts que contêm imagens não são enviados ao servidor vLLM nem à passagem de treinamento. O treinamento multimodal também precisa do caminho de empacotamento sem padding para construir posições 3D M-RoPE a partir da grade da imagem, o que não está implementado aqui.

AsyncGRPOTrainer

classe 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 )

Parâmetros

  • model (str ou PreTrainedModel) — Modelo a ser treinado. Pode ser:
    • Uma string, sendo o model id de um modelo pré-treinado hospedado em um repositório de modelos no huggingface.co, ou um caminho para um diretório contendo pesos de modelo salvos usando save_pretrained, por exemplo, './my_model_directory/'. O modelo é carregado com a arquitetura declarada em seu config: AutoModelForImageTextToText para um checkpoint de visão-linguagem (cujo vision tower é carregado, mas congelado, veja Training Vision Language Models), AutoModelForCausalLM caso contrário.
    • Um objeto PreTrainedModel. Sua implementação de atenção é alterada para o backend de atenção em árvore do trainer para treinamento empacotado.

    O nome do modelo na configuração é usado para identificar o modelo no servidor vLLM usado para a geração.

  • reward_funcs (RewardFunc | list[RewardFunc], opcional) — Funções de recompensa a serem usadas para calcular as recompensas. Para calcular as recompensas, chamamos todas as funções de recompensa com os prompts e as conclusões e somamos as recompensas. Pode ser omitido quando a recompensa é fornecida pelo ambiente através de environment_factory (veja abaixo). Pode ser:
    • Uma única função de recompensa: a função recebe os prompts e as conclusões geradas, além de quaisquer colunas adicionais no conjunto de dados. Ela deve retornar uma lista de recompensas. As funções de recompensa podem ser síncronas ou assíncronas e também podem retornar None quando a recompensa não se aplica a essas amostras. Isso é útil para treinamento multitarefa, em que diferentes funções de recompensa se aplicam a diferentes tipos de amostras. Quando uma função de recompensa retorna None para uma amostra, essa função de recompensa é excluída do cálculo da recompensa para aquela amostra. Para mais detalhes, consulte Usando uma função de recompensa personalizada.
    • Uma lista de funções de recompensa, em que cada item é uma função de recompensa conforme descrito acima. As recompensas de todas as funções são somadas.

    Diferentemente do GRPOTrainer, as recompensas são calculadas em um processo filho iniciado, portanto cada função de recompensa (juntamente com tools e environment_factory) deve ser serializável: use uma função em nível de módulo, functools.partial ou uma instância de classe chamável — lambdas e closures falharão na inicialização. As ferramentas são registradas sob seu __name__, portanto devem ser funções em nível de módulo. O processo filho também é executado com CUDA_VISIBLE_DEVICES="", portanto um modelo de recompensa baseado em GPU é executado na CPU (lento), e não na GPU do treinador.

  • args (AsyncGRPOConfig, opcional) — Configuração para este treinador. Se None, uma configuração padrão é usada.
  • train_dataset (Dataset ou IterableDataset, opcional) — Dataset a ser usado para o treinamento. Ele deve incluir uma coluna "prompt". Colunas adicionais no dataset são ignoradas. As amostras devem estar em formato conversacional : cada amostra contém mensagens estruturadas (por exemplo, role e content).

    Pode ser omitido apenas quando um environment_factory é fornecido e o ambiente possui (ou gera proceduralmente) os dados, retornando o prompt de seu método reset(). Nesse caso, max_steps deve ser definido para estabelecer a duração do treinamento.

  • processing_class (PreTrainedTokenizerBase, opcional) — Classe de processamento usada para processar os dados. O lado do padding deve ser definido como “left”. Se None, a classe de processamento é carregada a partir do nome do modelo com from_pretrained. Um token de padding, tokenizer.pad_token, deve ser definido. Se a classe de processamento não tiver definido um token de padding, tokenizer.eos_token será usado como padrão.
  • callbacks (lista de TrainerCallback, opcional) — Lista de callbacks para personalizar o loop de treinamento. Adicionará esses à lista de callbacks padrão detalhada aqui.

    Se você deseja remover um dos callbacks padrão utilizados, use o método remove_callback.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], opcional, padrão (None, None)) — Uma tupla contendo o otimizador e o agendador a serem usados. Por padrão, será uma instância de AdamW no seu modelo e um agendador dado por get_linear_schedule_with_warmup controlado por args.
  • peft_config (PeftConfig, opcional) — Configuração PEFT usada para envolver o modelo. Se None, o modelo não é envolvido. Quando o servidor vLLM foi iniciado com --enable-lora, um adaptador LoRA é sincronizado com ele como um adaptador, em vez de como pesos mesclados; veja a seção LoRA da documentação do AsyncGRPO.
  • tools (lista de Callable, opcional) — Uma lista de funções de ferramenta chamáveis (síncronas ou assíncronas) que o modelo pode invocar durante a geração. Cada ferramenta deve ser uma função Python padrão com argumentos e valores de retorno com type hints apropriados, e um docstring no estilo Google descrevendo seu propósito, argumentos e valor de retorno. Para mais detalhes, veja: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. O modelo usa o nome da função, os type hints e o docstring para determinar como chamá-la. Certifique-se de que o chat template do modelo suporta o uso de ferramentas e de que ele foi fine-tuned para tool calling.
  • environment_factory (EnvironmentFactory ou dict[str, EnvironmentFactory], opcional) — Um chamável que cria e retorna uma instância de ambiente, ou um dicionário que mapeia nomes de ambientes para esses chamáveis. A classe do ambiente deve definir métodos que podem ser invocados como ferramentas durante a geração. Cada método deve atender aos mesmos requisitos das tools descritas acima. O ambiente também deve implementar um método chamável reset que pode ser usado para redefinir o estado entre gerações. O método reset deve retornar None ou uma string: quando retorna uma string, essa string é adicionada à última mensagem do usuário antes da geração. O ambiente também pode definir um método get_reward que não recebe argumentos e retorna um float: quando presente, o ambiente possui a recompensa, e get_reward é chamado uma vez por rollout concluído para pontuá-lo a partir do estado interno do ambiente. Ele atua como uma fonte de recompensa adicional (com peso 1, registrada sob o nome da classe do ambiente) junto com reward_funcs, que então se torna opcional.

    Com um único callable, todos os exemplos usam o mesmo ambiente, com uma instância por rollout para que suas interações permaneçam isoladas. Com um dicionário, cada exemplo deve ter um campo environment que seleciona seu ambiente pelo nome, e apenas as ferramentas desse ambiente são expostas em seu prompt — permitindo que uma única execução misture tarefas (por exemplo, um ambiente de codificação e um jogo). Este recurso é experimental e pode ser alterado ou removido a qualquer momento sem aviso prévio.

Trainer para o método Group Relative Policy Optimization (GRPO). Este algoritmo foi inicialmente proposto no artigo DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. Este trainer é a versão assíncrona do GRPO, na qual a geração é delegada a um servidor vLLM externo que executa de forma assíncrona junto com o treinamento, desacoplando o rollout do loop de atualização de gradiente.

Exemplo:

>>> 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()

Para personalizar quais prompts são amostrados, como um rollout é gerado ou como as vantagens são calculadas, crie uma subclasse de AsyncRolloutLoop e defina-a como loop_cls do trainer. O TRL constrói o loop no

processo de rollout:

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

treino

< >

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

Parâmetros

  • resume_from_checkpoint (str ou bool, opcional) — Se for um str, caminho local para um checkpoint salvo por uma instância anterior de Trainer. Se for um bool e for igual a True, carrega o último checkpoint em args.output_dir salvo por uma instância anterior de Trainer. Se presente, o treinamento será retomado a partir dos estados do modelo/otimizador/agendador carregados aqui.
  • trial (optuna.Trial ou dict[str, Any], opcional) — A execução do trial ou o dicionário de hiperparâmetros para a busca de hiperparâmetros.
  • ignore_keys_for_eval (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar previsões para avaliação durante o treinamento.

Retorna

~trainer_utils.TrainOutput

Objeto contendo a contagem de etapas globais, a perda de treinamento e as métricas.

Ponto de entrada principal do treinamento.

save_model

< >

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

Salvará o modelo, para que você possa recarregá-lo usando from_pretrained().

Salvará apenas a partir do processo principal.

push_to_hub

< >

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

Parâmetros

  • commit_message (str, opcional, padrão "End of training") — Mensagem a ser commitada durante o push.
  • blocking (bool, opcional, padrão True) — Se a função deve retornar apenas quando o git push tiver terminado.
  • token (str, opcional, padrão None) — Token com permissão de escrita para sobrescrever os argumentos originais do Trainer.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo “main”.
  • private (bool, opcional) — Se o repositório deve ser privado quando for criado. O padrão é args.hub_private_repo. Não tem efeito se o repositório já existir.
  • kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais passados para ~Trainer.create_model_card.

Envie self.model e self.processing_class para o hub de modelos do 🤗 no repositório self.args.hub_model_id.

AsyncGRPOConfig

classe 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 = Truegradient_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 )

Parâmetros que controlam o modelo

  • model_init_kwargs (dict[str, Any] ou str, opcional) — Argumentos de palavra-chave para from_pretrained, usados ao instanciar o modelo a partir de um caminho. O valor de revision também é usado ao carregar a classe de processamento.
  • dtype (str, opcional, padrão é "float32") — Tipo de dados para carregar o modelo, um dos "auto", "bfloat16", "float16" ou "float32". O padrão é "float32" porque a incompatibilidade entre treinamento e inferência que este trainer é medido em relação aDefeating the Training-Inference Mismatch via FP16) é sensível à precisão do próprio trainer. Fechar essa lacuna de ponta a ponta também requer servir o servidor vLLM no mesmovllm serve --dtype); uma incompatibilidade é registrada como um aviso no início do treinamento. Um dtype em model_init_kwargs tem precedência.

    Isso apenas define o dtype em que os pesos são carregados. Sob FSDP com precisão mista (bf16=True é o padrão), o accelerate faz o upcast de todos os parâmetros treináveis para fp32 antes do sharding, de modo que os pesos mestres e o estado do otimizador ficam em fp32, independentemente do que dtype indique, enquanto o forward e o backward são executados em bf16 ou fp16. Os checkpoints são então gravados nesse dtype de precisão mista, e não em fp32. Sem FSDP, nada faz upcast: dtype="bfloat16" com bf16=True mantém pesos e estados do otimizador em bf16, o que corresponde a treinamento puro em bf16.

  • trust_remote_code (bool, opcional, padrão False) — Se permite carregar modelos e tokenizers que incluem código Python personalizado do Hub. Encaminhado para from_pretrained e from_pretrained.
  • router_aux_loss_coef (float, opcional) — Coeficiente da perda auxiliar de balanceamento de carga para modelos Mixture-of-Experts (MoE), adicionada à perda de treinamento com esse peso. Quando não definido, o valor declarado na configuração do modelo é utilizado. Defina como 0.0 para desativá-la. Falha quando usado com um modelo não-MoE.

Parâmetros que controlam a geração

  • num_generations (int, opcional, padrão 8) — Número de gerações por prompt a serem amostradas.
  • max_completion_length (int, opcional, padrão 2048) — Número máximo de tokens gerados por solicitação do vLLM, ou seja, por turno em um rollout de múltiplos turnos.
  • temperature (float, opcional, padrão 1.0) — Temperatura para amostragem. Quanto maior a temperatura, mais aleatórias são as conclusões.
  • top_p (float, opcional, padrão 1.0) — Float que controla a probabilidade cumulativa dos tokens principais a serem considerados. Deve estar em (0, 1]. Defina como 1.0 para considerar todos os tokens. Abaixo de 1.0, top_k também deve ser definido, e o servidor vLLM (>= 0.28) iniciado com --return-sampling-mask --enable-scale-out: o trainer renormaliza suas log-probabilidades sobre o conjunto de candidatos do qual cada token foi amostrado, assim como o servidor faz. Um vLLM mais antigo mantém o vocabulário inteiro.
  • top_k (int, opcional, padrão 0) — Número de tokens do vocabulário com maior probabilidade a serem mantidos para o filtro top-k. Se 0, o filtro top-k é desativado e todos os tokens são considerados. Qualquer outro valor requer as flags do servidor descritas em top_p.
  • min_p (float, opcional) — Probabilidade mínima do token, que será escalada pela probabilidade do token mais provável. Deve ser um valor entre 0.0 e 1.0. Valores típicos estão na faixa de 0.01 a 0.2. Acima de 0.0, top_k também deve ser definido, com as flags do servidor descritas em top_p.
  • chat_template_kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais para passar à função apply_chat_template ao gerar completions.
  • max_tool_calling_iterations (int, opcional) — Número máximo de turnos de chamada de ferramentas ao treinar um agente. Se None, não há limite e a geração para quando o modelo gera um turno de resposta sem chamadas de ferramentas.

Parâmetros que controlam o servidor vLLM

  • vllm_server_base_url (str, opcional, padrão "http --//localhost:8000"): URL base do servidor vLLM usado para geração (por exemplo, "http://localhost:8000").
  • vllm_server_timeout (float, opcional, padrão 1800.0) — Tempo limite em segundos para chamadas ao servidor vLLM: aguardando que ele esteja pronto na inicialização, cada solicitação de geração e cada chamada de sincronização de pesos. Aguardar o servidor e as chamadas de sincronização de pesos geram erro quando o tempo limite é excedido; uma solicitação de geração que excede o tempo limite é reprocessada.

Parâmetros que controlam o treinamento

  • epsilon (float, opcional, padrão 0.2) — Valor para o recorte (clipping).
  • epsilon_high (float, opcional) — Valor superior de epsilon para o recorte. Se não for especificado, o valor padrão será o mesmo do limite inferior especificado no argumento epsilon. O paper DAPO recomenda 0.28.
  • score_centering (bool, opcional, padrão True) — Se treinar com centralização de score (paper) em vez do objetivo recortado: o score ponderado pela importância de cada token amostrado menos sua expectativa sob o sampler vLLM, de modo que uma vantagem constante não puxe a política em direção ao sampler. A expectativa é calculada sobre os num_sampler_logprobs tokens mais prováveis em cada posição, cujas log-probabilidades o sampler relata.
  • vllm_importance_sampling_clip_min (float, opcional, padrão 0.5) — Limite inferior C_min da razão de importância entre a política e o amostrador do vLLM. Tokens cuja razão fica fora de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] são descartados da perda (amostragem de importância mascarada).
  • vllm_importance_sampling_clip_max (float, opcional, padrão 5.0) — Limite superior C_max da razão de importância.
  • num_sampler_logprobs (int, opcional, padrão 8) — Número de log-probabilidades superiores solicitadas ao sampler do vLLM para cada token gerado, usado pelo score centering. Valores maiores cobrem mais da massa de probabilidade do sampler, mas custam mais para serializar; o parâmetro --max-logprobs do servidor define o limite.
  • token_budget (int, opcional) — Número máximo de tokens encaminhados em uma única linha (um forward de um rank DP). Um TokenBudgetBatcher forma micro-lotes equilibrados em custo de atenção, cujas linhas permanecem dentro desse orçamento, limitando a memória de pico independentemente da contagem de amostras (o número de amostras por linha se torna dinâmico). O orçamento limita tokens únicos, e não brutos, de modo que tokens compartilhados por várias amostras contam uma vez, e também limita os termos de perda da linha. Se None (padrão), é definido como o max_model_len do servidor vLLM (consultado no início do treinamento) — o limite para o comprimento de prompt + conclusão —, de modo que nenhuma amostra de rollout pode exceder o orçamento. Uma amostra mais longa que token_budget não cabe em nenhuma linha e é descartada com um aviso.

Parâmetros que controlam o pipeline de rollout assíncrono

  • max_concurrent_rollouts (int, opcional, padrão 512) — Número máximo de rollouts executados simultaneamente. Cada um mantém um ambiente, pode executar chamadas de ferramentas síncronas e mantém uma conexão com o servidor vLLM, portanto, defina esse valor de acordo com a capacidade desses recursos. Abaixo desse limite, o número de rollouts em andamento segue o uso do KV-cache do servidor vLLM e o max_staleness.
  • max_staleness (int, opcional, padrão 4) — Número máximo de etapas de atualização de pesos para as quais uma amostra de rollout pode ficar atrasada em relação à versão atual do modelo antes de ser descartada. A geração é limitada a isso: um novo grupo de rollouts inicia apenas enquanto os tokens enfileirados e em processamento couberem no que o treinador consome em max(max_staleness, 1) etapas.
  • weight_sync_steps (int, opcional, padrão 1) — Número de etapas de treinamento entre as sincronizações de pesos para o servidor vLLM.
  • rollout_worker_timeout (float, opcional, padrão 300.0) — Segundos desde o último heartbeat do worker de rollout após os quais o trainer o considera travado e interrompe a execução.

Parâmetros que controlam o registro de logs

  • log_completions (bool, opcional, padrão False) — Se deve registrar uma amostra de pares (prompt, completion) a cada logging_steps etapas.
  • num_completions_to_print (int, opcional) — Número de conclusões a serem exibidas com rich. Se None, todas as conclusões são registradas.

Classe de configuração para o AsyncGRPOTrainer.

Esta classe inclui apenas os parâmetros específicos para o treinamento assíncrono de GRPO. Para a lista completa de argumentos de treinamento, consulte a documentação de TrainingArguments. Observe que os valores padrão nesta classe podem diferir dos presentes em TrainingArguments.

Esses parâmetros possuem valores padrão diferentes de TrainingArguments:

  • logging_steps: O valor padrão é 1 em vez de 500.
  • gradient_checkpointing: O padrão é True em vez de False.
  • bf16: Padrão é True se fp16 não estiver definido, em vez de False.
  • learning_rate: O valor padrão é 1e-6 em vez de 5e-5.
  • lr_scheduler_type: O padrão é constant em vez de linear (veja abaixo).
  • ignore_data_skip: O valor padrão é True em vez de False; o loop de skip-and-replay do Trainer base não se aplica à fila de rollout assíncrono.
  • remove_unused_columns: O valor padrão é False em vez de True, e deve permanecer False: todas as colunas do conjunto de dados são passadas para as funções de recompensa.

Duração do treinamento e taxa de aprendizado sob reconciliação em modo de mensagem: Uma conversa de múltiplas rodadas pode se ramificar em um número variável de linhas de treinamento (uma reescrita da conversa inicia uma nova linha), de modo que o número de amostras, e portanto o número de passos do otimizador, por época não é conhecido antecipadamente. Como consequência:

  • num_train_epochs limita o treinamento por passadas completas sobre o conjunto de dados de prompt, contado como o número de prompts distintos efetivamente treinados. Isso é independente de quantas linhas os forks produzem, portanto, solicitar N épocas sempre treina com N passadas sobre os dados. Quando max_steps é deixado sem definir, esta é a condição de parada e max_steps é apenas um limite de segurança.
  • max_steps, se definido explicitamente (> 0), assume o papel de condição de parada (limitando por passos do otimizador em vez de por épocas) e desativa a parada baseada em épocas.
  • lr_scheduler_type tem como padrão constant porque o horizonte de decaimento é medido em passos do otimizador, o que não pode ser conhecido antecipadamente quando a contagem de passos depende da taxa de fork. Para uma taxa de aprendizado decrescente, defina um agendamento decrescente junto com um max_steps explícito.

AsyncRolloutLoop

classe 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 )

Gera e pontua rollouts para AsyncGRPOTrainer, em um processo de rollout iniciado.

O padrão implementa o GRPO. Para personalizar uma execução, crie uma subclasse, sobrescreva apenas os métodos que mudam e defina a subclasse como o loop_cls do trainer. Cada prompt passa, em ordem, por:

  • filter_prompt(): se deve gerar algo para o prompt.
  • generate_one(): um rollout completo, que chama generate_one_turn() para cada solicitação de amostragem.
  • O grupo de num_generations rollouts é pontuado: suas recompensas são a soma das reward_funcs do trainer, dos ambientes que definem get_reward e de Rollout.reward. Em seguida, compute_advantages() é executado uma vez por grupo.

setup() e close() criam e liberam recursos no event loop do loop, como um cliente HTTP. Um hook pode ler self.config (uma subclasse de AsyncGRPOConfig pode carregar seus próprios campos) e self.tokenizer. Como o loop é construído em um processo gerado, a subclasse deve ser importável (definida em nível de módulo).

filter_prompt

< >

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

Parâmetros

  • row_index (int) — Índice da linha no conjunto de dados de treinamento.
  • row (dict[str, Any]) — A linha do dataset.
  • epoch (int) — Número de passagens completas pelo conjunto de dados antes desta.

Retorna

bool

True para gerar num_generations rollouts para o prompt, False para ignorá-lo.

Se deve gerar para um prompt. Um prompt rejeitado é ignorado para esta epoch e conta como consumido, como um grupo descartado. Admite todos os prompts por padrão. Rejeitar todos os prompts de uma epoch completa gera uma exceção, pois nenhum lote pode chegar ao trainer depois disso.

generate_one

< >

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

Parâmetros

  • prompt (list[dict[str, Any]]) — Prompt messages.
  • tools (list[Callable]) — Ferramentas disponíveis para este rollout: as tools do trainer, além dos métodos públicos do ambiente ao usar environment_factory.
  • group_id (int, opcional, padrão 0) — Identificador do grupo ao qual o rollout pertence.

Retorna

Rollout

O rollout finalizado.

Gere um rollout para um prompt.

Por padrão, um loop de ferramentas de múltiplas rodadas: cada rodada renderiza a conversa inteira com o modelo de chat, amostra uma resposta com generate_one_turn() e executa as chamadas de ferramentas que ela contém, até que o modelo pare de chamar ferramentas ou max_tool_calling_iterations seja atingido. Sobrescreva-o para gerar de forma diferente, por exemplo, com um framework de agente. Retorne todas as solicitações de amostragem em Rollout.turns, já que as sequências de treinamento são construídas a partir delas, e defina Rollout.reward para pontuar o rollout aqui.

generate_one_turn

< >

( prompt_ids: list[int] ) → TurnRecord

Parâmetros

  • prompt_ids (list[int]) — Ids dos tokens do prompt completo.

Retorna

TurnRecord

O prompt e os tokens amostrados com suas log-probabilidades. Com top_k ou top_p, ele também contém o conjunto de candidatos de cada token amostrado, e com num_sampler_logprobs, as principais log-probabilidades do amostrador.

Amostra uma resposta do servidor vLLM, com as configurações de amostragem da config (temperature, top_p, top_k, min_p, repetition_penalty e max_completion_length).

compute_advantages

< >

( group: RolloutGroup ) → np.ndarray

Parâmetros

  • group (RolloutGroup) — Os num_generations rollouts de um prompt, com suas recompensas totais em group.rewards.

Retorna

np.ndarray

Uma vantagem por rollout, na ordem de group.rewards.

Calcule uma vantagem por rollout de um grupo. Por padrão, cada recompensa é padronizada dentro do grupo; um rollout com recompensa NaN recebe vantagem 0 e é excluído da média e do desvio padrão.

Ele é executado para cada grupo. Um grupo cujas recompensas pontuadas são todas iguais é então descartado, independentemente das vantagens que isso retorna.

configuração

< >

( )

Cria os recursos necessários para os outros hooks, como um cliente HTTP. Executa no loop de eventos do loop antes do primeiro prompt. Não faz nada por padrão.

fechar

< >

( )

Libera o que setup() criou. É executado quando os loops param, incluindo em caso de falha. Não faz nada por padrão.

Rollout

classe 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> )

Parâmetros

  • completion (list[dict[str, Any]]) — Messages generated after the prompt, in conversational format. Passed to the reward functions as completions.
  • completion_ids (list[int]) — Ids dos tokens da conclusão gerada. Passados para as funções de recompensa como completion_ids.
  • turns (list[TurnRecord]) — As solicitações de amostragem que geraram o rollout, em ordem. As sequências de treinamento são construídas a partir delas: os tokens amostrados são usados no treinamento, e o restante de cada prompt é o contexto.
  • tool_call_count (int, opcional, padrão 0) — Número de chamadas de ferramenta feitas durante o rollout.
  • tool_failure_count (int, opcional, padrão 0) — Número de chamadas de ferramenta que falharam.
  • reward (float, opcional) — Recompensa calculada durante a geração, por exemplo, por um avaliador externo. Ela é somada às recompensas das funções de recompensa e dos ambientes. Se None, este rollout não recebe recompensa desta fonte.
  • rollout_id (str, opcional) — Identifica o rollout em suas linhas de treinamento, para depuração. O padrão é um novo id hexadecimal aleatório.

Um rollout concluído, conforme retornado por generate_one().

TurnRecord

classe 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 )

Parâmetros

  • prompt_ids (list[int]) — Ids dos tokens do prompt completo enviado para esta rodada, incluindo todas as rodadas anteriores da conversa.
  • output_ids (list[int]) — Ids dos tokens gerados pelo amostrador.
  • output_log_probs (list[float], opcional, padrão []) — Log-probabilidade do sampler de cada token em output_ids. Obrigatório quando qualquer um deles estiver em treinamento.
  • output_mask (list[int], opcional) — Um valor por token em output_ids: 1 para treinar no token, 0 para mantê-lo apenas como contexto. Se None, todos os tokens de saída são treinados.
  • output_sampling_mask (list[list[int]], opcional) — Uma lista por token em output_ids: os ids de tokens dos quais o amostrador poderia extrair sob a truncagem de top_k / top_p. Se None, o vocabulário completo.
  • output_sampler_logprobs (list[dict[int, float]], opcional) — Um dict por token em output_ids: as log-probabilidades do sampler para seus tokens mais prováveis, indexadas pelo id do token. Usado pelo score centering (num_sampler_logprobs).

Uma solicitação de amostragem: o prompt enviado ao amostrador e os tokens que ele gerou.

RolloutGroup

classe 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 )

Parâmetros

  • prompts (list[list[dict[str, Any]]]) — Prompt de cada rollout.
  • reward_kwargs (dict[str, list[Any]]) — As outras colunas da linha do dataset do prompt, passadas às funções de recompensa como argumentos de palavra-chave.
  • completions (list[list[dict[str, Any]]]) — Mensagens de conclusão de cada rollout.
  • completions_ids (list[list[int]]) — IDs dos tokens de conclusão de cada rollout.
  • completions_sequences (list[list[TrainingSequence]]) — Sequências de treinamento construídas a partir de cada rollout. Um rollout cuja história retokenizada mudou entre as rodadas gera mais de uma sequência.
  • tool_call_counts (list[int]) — Número de chamadas de ferramenta em cada rollout.
  • tool_failure_counts (list[int]) — Número de chamadas de ferramenta com falha em cada rollout.
  • model_version (int) — Versão do modelo quando o primeiro rollout do grupo começou.
  • group_id (int) — Identificador do grupo, contado a partir de 0 no processo de rollout.
  • row_index (int) — Índice da linha do prompt no conjunto de dados de treinamento.
  • env_rewards (list[tuple[type, float] or None]) — Para um rollout cujo ambiente define get_reward, a classe do ambiente e sua recompensa; caso contrário, None.
  • rollout_rewards (list[float or None]) — Rollout.reward de cada rollout.
  • queued_at (float, opcional, padrão 0.0) — time.monotonic() quando o grupo foi enfileirado para pontuação.
  • rewards (np.ndarray, opcional) — Recompensa total de cada rollout, somada sobre todas as fontes de recompensa, NaN quando nenhuma fonte a pontuou. Definida antes de compute_advantages() ser chamada.

Os num_generations rollouts de um prompt, pontuados juntos. Cada lista tem uma entrada por rollout.

Update on GitHub