TRL documentation

Funções de Recompensa

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.18.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Funções de Recompensa

Este módulo contém algumas funções de recompensa úteis, destinadas principalmente ao uso com o GRPOTrainer e o RLOOTrainer.

accuracy_reward

trl.rewards.accuracy_reward

< >

( completions: list[list[dict[str, str]]]solution: list[str]log_extra: collections.abc.Callable[[str, list], None] | None = None**kwargs )

Parâmetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a serem avaliadas. Cada completion deve ser uma lista de uma mensagem, ou seja, um dicionário contendo a chave "content" com o valor sendo o texto da completion.
  • solution (list[str]) — Lista das soluções em texto bruto para as perguntas/problemas/prompts.
  • log_extra (callable, opcional) — Função chamável para registrar colunas extras na tabela de conclusões, fornecida automaticamente pelo trainer. O valor padrão é None para permitir a chamada direta da função fora de um trainer (por exemplo, para testes).
  • **kwargs — Argumentos de palavra-chave adicionais. Esta função não os utiliza, mas eles são obrigatórios na assinatura da função para garantir compatibilidade com treinadores como GRPOTrainer.

Função de recompensa que verifica se a conclusão corresponde à resposta correta.

  • Se tanto o valor de referência quanto a previsão forem analisáveis → use a verificação matemática.
  • Se o gold não for analisável → retorne None para pular o exemplo.

Exemplo:

>>> from trl.rewards import accuracy_reward

>>> solutions = [r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completions = [
...     [{"role": "assistant", "content": r"My answer is \boxed{\frac{1}{3}}"}],
...     [{"role": "assistant", "content": r"My answer is \boxed{\frac{1}{2}}"}],
... ]
>>> accuracy_reward(completions, solutions)
[1.0, 0.0]

reasoning_accuracy_reward

trl.rewards.reasoning_accuracy_reward

< >

( completions: list[list[dict[str, str]]]solution: list[str]reasoning_delimiters: list[str] | None = Nonelog_extra: collections.abc.Callable[[str, list], None] | None = None**kwargs )

Parâmetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a serem avaliadas. Cada completion deve ser uma lista de uma mensagem, ou seja, um dicionário contendo a chave "content" com o valor sendo o texto da completion.
  • solution (list[str]) — Lista das soluções em texto bruto para as perguntas/problemas/prompts.
  • reasoning_delimiters (list[str]], opcional) — Lista de strings indicando onde o conteúdo de raciocínio termina. A resposta final é assumida como estando após a última ocorrência de qualquer um desses delimitadores. Se None, o padrão é ["</think>"].
  • log_extra (callable, opcional) — Função chamável para registrar colunas extras na tabela de conclusões, fornecida automaticamente pelo trainer. O valor padrão é None para permitir a chamada direta da função fora de um trainer (por exemplo, para testes).
  • **kwargs — Argumentos de palavra-chave adicionais. Esta função não os utiliza, mas eles são obrigatórios na assinatura da função para garantir compatibilidade com treinadores como GRPOTrainer.

Função de recompensa que remove o conteúdo de raciocínio e verifica se a resposta final corresponde ao valor verdadeiro.

  • Se tanto o valor de referência quanto a previsão forem analisáveis → use a verificação matemática.
  • Se o gold não for analisável → retorne None para pular o exemplo.

Exemplo:

>>> from trl.rewards import reasoning_accuracy_reward

>>> reasoning_delimiters = ["</think>"]
>>> solutions = [r"\frac{1}{3}", r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completions = [
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content </think> The final answer is \boxed{\frac{1}{3}}",
...         }
...     ],
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content </think> The final answer is \boxed{\frac{1}{2}}",
...         }
...     ],
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content with partial answers \boxed{\frac{1}{3}} but no final answer",
...         }
...     ],
... ]
>>> reasoning_accuracy_reward(completions, solutions, reasoning_delimiters=reasoning_delimiters)
[1.0, 0.0, 0.0]

get_cosine_scaled_reward

trl.rewards.get_cosine_scaled_reward

< >

( max_len: intmin_value_wrong: float = -1.0max_value_wrong: float = -0.5min_value_correct: float = 0.5max_value_correct: float = 1.0 ) → Callable

Parâmetros

  • max_len (int) — Comprimento máximo da conclusão (em tokens) usado para normalizar o agendamento cosseno, $L_{\max}$.
  • min_value_wrong (float, opcional, padrão -1.0) — Recompensa de uma conclusão incorreta no comprimento mais curto.
  • max_value_wrong (float, opcional, padrão -0.5) — Recompensa de uma conclusão incorreta no comprimento máximo.
  • min_value_correct (float, opcional, padrão 0.5) — Recompensa de uma conclusão correta no comprimento máximo.
  • max_value_correct (float, opcional, padrão 1.0) — Recompensa de uma conclusão correta no comprimento mais curto.

Retorna

Callable

Uma função de recompensa que recebe as conclusões, suas soluções e os ids de tokens, e retorna uma lista de recompensas (None para exemplos com uma solução de referência não analisável).

Função de recompensa que escala uma recompensa de correção pelo comprimento da conclusão seguindo um agendamento cosseno, para favorecer o raciocínio conciso. Referência: Apêndice C.1 do artigo “Demystifying Long Chain-of-Thought Reasoning” (https://huggingface.co/papers/2502.03373).

A correção é determinada pela verificação matemática (como em accuracy_reward()), e o comprimento é o número de tokens de conclusão. A recompensa interpola ao longo de um agendamento cosseno entre um limite de conclusão curta e um limite de conclusão longa: Rcosine(y)=vmin⁡+12(vmax⁡−vmin⁡)(1+cos⁡(∣y∣Lmax⁡π)) R_{\text{cosine}}(y) = v_{\min} + \frac{1}{2}(v_{\max} - v_{\min})\left(1 + \cos\left(\frac{|y|}{L_{\max}}\pi\right)\right)

Para uma conclusão correta, $(v{\min}, v{\max}) = (\texttt{min_value_correct}, \texttt{max_value_correct})$, de modo que uma conclusão mais curta é recompensada mais. Para uma conclusão errada, os limites são invertidos para $(v{\min}, v{\max}) = (\texttt{max_value_wrong}, \texttt{min_value_wrong})$, de modo que uma conclusão mais curta é penalizada mais (uma conclusão errada mais longa é penalizada menos, preservando a exploração). Quando a solução de referência não é interpretável, o exemplo é ignorado (recompensa None), como em accuracy_reward().

Exemplo:

>>> from trl.rewards import get_cosine_scaled_reward

>>> cosine_scaled_reward = get_cosine_scaled_reward(max_len=100)
>>> completions = [[{"content": r"\boxed{\frac{1}{3}}"}], [{"content": r"\boxed{\frac{1}{2}}"}]]
>>> solution = [r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completion_ids = [[1] * 50, [1] * 50]  # both completions are 50 tokens, half of max_len
>>> cosine_scaled_reward(completions, solution, completion_ids)
[0.75, -0.75]

think_format_reward

trl.rewards.think_format_reward

< >

( completions: list[list[dict[str, str]]]**kwargs ) → list[float]

Parâmetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a serem avaliadas. Cada completion deve ser uma lista de uma mensagem, ou seja, um dicionário contendo a chave "content" com o valor sendo o texto da completion.
  • **kwargs — Argumentos de palavra-chave adicionais. Esta função não os utiliza, mas eles são obrigatórios na assinatura da função para garantir compatibilidade com treinadores como GRPOTrainer.

Retorna

list[float]

Uma lista de recompensas, em que cada recompensa é 1.0 se a conclusão corresponder ao formato esperado, caso contrário, 0.0.

Função de recompensa que verifica se o processo de raciocínio está contido nas tags "<think>" e "</think>". A função retorna uma recompensa de 1.0 se o formato estiver correto, caso contrário, 0.0.

Exemplo:

>>> from trl.rewards import think_format_reward

>>> completions = [
...     [{"content": "<think>\nThis is my reasoning.\n</think>\nThis is my answer."}],
...     [{"content": "<think>\nThis is my reasoning.\nThis is my answer."}],
... ]
>>> think_format_reward(completions)
[1.0, 0.0]

get_repetition_penalty_reward

trl.rewards.get_repetition_penalty_reward

< >

( ngram_size: int = 3max_penalty: float = -1.0 ) → Callable

Parâmetros

  • ngram_size (int, opcional, padrão 3) — Tamanho dos n-gramas de tokens a serem considerados.
  • max_penalty (float, opcional, padrão -1.0) — Penalidade negativa máxima, aplicada a uma conclusão totalmente repetitiva. Deve ser não positiva.

Retorna

Callable

Uma função de recompensa que recebe uma lista de ids de tokens de conclusão e retorna uma lista de penalidades (cada uma em [max_penalty, 0.0]).

Função de recompensa que penaliza n-gramas repetidos em uma conclusão, usada para desencorajar texto degenerado e repetitivo (um modo de falha comum e uma estratégia de burla de recompensa quando recompensas de moldagem de comprimento ou formato são usadas). Referência: Apêndice C.2 do artigo “Demystifying Long Chain-of-Thought Reasoning” (https://huggingface.co/papers/2502.03373).

A penalidade é proporcional à fração de n-gramas repetidos na conclusão: Rrepetition(y)=(1−# unique n-grams# total n-grams)×p R_{\text{repetition}}(y) = \left(1 - \frac{\#\,\text{unique } n\text{-grams}}{\#\,\text{total } n\text{-grams}}\right) \times p

onde pp é max_penalty. Uma conclusão sem n-gramas repetidos recebe uma recompensa de 0.0, enquanto uma totalmente repetitiva se aproxima de max_penalty. Os n-gramas são calculados sobre os ids dos tokens da conclusão (o artigo aplica a penalidade a tokens repetidos), portanto a recompensa é definida pelo tokenizer e agnóstica em relação ao idioma. Conclusões com menos de ngram_size tokens recebem uma recompensa de 0.0.

Exemplo:

>>> from trl.rewards import get_repetition_penalty_reward

>>> repetition_penalty = get_repetition_penalty_reward(ngram_size=2, max_penalty=-1.0)
>>> completion_ids = [[1, 2, 3, 4], [5, 5, 5, 5, 5]]
>>> repetition_penalty(completion_ids)
[0.0, -0.75]

get_soft_overlong_punishment

trl.rewards.get_soft_overlong_punishment

< >

( max_completion_len: intsoft_punish_cache: int )

Parâmetros

  • max_completion_len (int) — Comprimento máximo da conclusão, ( L_{\max} ).
  • soft_punish_cache (int) — Comprimento mínimo da conclusão, ( L_{\text{cache}‌} ). Se definido como 0, nenhum comprimento mínimo é aplicado.

Função de recompensa que penaliza conclusões excessivamente longas. É usada para penalizar conclusões excessivamente longas, mas não para recompensar conclusões mais curtas. Referência: Eq. (13) do paper DAPO (https://huggingface.co/papers/2503.14476) Rlength(y)={0,∣y∣≤Lmax⁡−Lcache(Lmax⁡−Lcache)−∣y∣Lcache,Lmax⁡−Lcache<∣y∣≤Lmax⁡−1,Lmax⁡<∣y∣ R_{\text{length}}(y) = \begin{cases} 0, & |y| \le L_{\max} - L_{\text{cache}} \\ \dfrac{(L_{\max} - L_{\text{cache}}) - |y|}{L_{\text{cache}}}, & L_{\max} - L_{\text{cache}} < |y| \le L_{\max} \\ -1, & L_{\max} < |y| \end{cases}

Exemplo:

>>> from trl.rewards import get_soft_overlong_punishment

>>> soft_overlong_punishment = get_soft_overlong_punishment(max_completion_len=100, soft_punish_cache=20)
>>> completion_ids = [[1] * 90]  # simulating a completion with 90 tokens. 90 is between 80 and 100.
>>> soft_overlong_punishment(completion_ids)
>>> [-0.5]
Update on GitHub