TRL documentation
Funções de Recompensa
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
< source >( 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 éNonepara 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
Nonepara 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
< source >( 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. SeNone, 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 éNonepara 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
Nonepara 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
< source >( 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ão0.5) — Recompensa de uma conclusão correta no comprimento máximo. - max_value_correct (
float, opcional, padrão1.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:
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
< source >( 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.
get_repetition_penalty_reward
trl.rewards.get_repetition_penalty_reward
< source >( ngram_size: int = 3max_penalty: float = -1.0 ) → Callable
Parâmetros
- ngram_size (
int, opcional, padrão3) — 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:
onde é 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.
get_soft_overlong_punishment
trl.rewards.get_soft_overlong_punishment
< source >( max_completion_len: intsoft_punish_cache: int )
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)
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]